需 求 文 档

本体建模 · 开放接口需求清单

提出方
FDE
日期
2026-11-03
面向
平台技术侧(评估 → 实现)
范围
本体建模的原子能力——对象、属性、关系、动作、避坑与经验的增删改查,以及重复提交的幂等保障。权限与组织配置列入二期(第六节),本期不申请写接口。

一、需求(6 条)

编号需求说明
N-01对象 增 / 删 / 改 / 查含对象基本信息、所属套、说明、物理表绑定
N-02属性 增 / 删 / 改 / 查含类型、长度、必填、密级、说明、绑枚举字典;字典本身也要能增改查
N-03关系 增 / 删 / 改 / 查含源对象、目标对象、方向、基数、是否必须、挂钩列
N-04动作 增 / 删 / 改 / 查参数表、角色授权、数字员工授权、审批档、执行规则要能一并写入;查询要能读回完整定义
N-05避坑与经验 增 / 删 / 改 / 查挂在对象 / 属性 / 动作上的踩坑说明,随本体一起下发,供数字员工使用时参考
N-06幂等同一编码重复创建不产生副本;已存在时返回明确结果(已存在,或按参数更新)

二、关于「删」

五类对象的删除都要能真正生效,不能只做新增与修改。

现状是删属性、改列类型、删关系这几样不可用。建模过程中改主意、写错类型是常态,若没有删除能力,错误只能残留在本体里,或新增一列绕开——本体越改越臃肿,而重建对象又会连带影响已有数据与员工订阅,代价更高。

所以 N-01~N-05 的「删」是必需项,不是可选项:

删除对象要能删到什么程度
属性从本体移除(是否连同物理列一起删,由平台决定并给出提示)
关系移除,并清理由此产生的失效关系
动作移除(含其参数与授权)
对象移除(要提示会连带影响的关系与订阅)
避坑与经验移除
验收:建一个测试对象 → 改属性、删属性、删关系、删动作、删一条避坑说明 → 再查一遍,对应项确实消失,没有残留。

三、本期范围之外

以下内容不在本期需求内,列出以便边界清楚:

四、验收(一次跑完即算通过)

联调数据:14 对象 / 105 属性 / 21 关系 / 45 动作
  1. 脚本连续调接口,把这套建出来 → 平台上条数与设计稿完全一致
  2. 同一脚本再跑一遍 → 不产生任何重复(幂等生效)
  3. 改 3 个属性、删 1 个属性、删 1 条关系 → 再查,改动准确、无残留
  4. 全程不产生任何需要人工清理的垃圾数据

五、配合事项

  1. 我们可以提供上述 14 对象的真实方案,作为联调测试数据与期望报文样例。
  2. 接口上线后,我们会作为真实使用方在客户项目中持续使用,并及时反馈缺陷的复现步骤。
  3. 涉及删除这类不可逆操作,我们接受二次确认与权限限制。

六、二期需求:查询权限与组织配置(分期开放)

这些能力最终也要接口化——目标是让数字员工能完整操作本体平台,而不是永远由人在页面上点。但权限类配置的错法很特殊:配错了不会报错。所以它排在建模接口之后,并按「先读、再自检、最后写」的顺序逐级放开。

编号需求内容建议阶段
M-01权限只读导出读出对象级查询权限(含 or/and 模式、归属字段)、角色密级、角色清单、人员与角色的对应关系二期先行
M-02权限变更自检给定「角色或数字员工 + 对象」,返回该身份实际可见的字段与数据范围(或预估行数),用于配置后当场验证二期,与 M-01 同期
M-03权限写入(单条)修改某对象的查询权限、某角色的密级;请求需携带变更前的值,平台回执变更后的值三期
M-04权限变更快照与回滚每次权限变更前自动留存快照;可查询、可一键恢复到变更前三期,M-03 前置
M-05组织配置(角色与人员映射)角色的增查、人员与角色的绑定;建议先开放只读与「申请」,「直接写」放到最后四期
为什么 M-03 必须晚于 M-01 / M-02 / M-04:权限配错有两个方向——少配,数字员工查不到数据(当场可见);多配,客户看到不该看的数据(不报错、无提示,往往等出事才知道)。所以写权限生效的前提是:变更前能查到原值(M-01)、变更后能验证效果(M-02)、出错能一键退回(M-04)。这三条不齐就开放写接口,等于把风险从「配得慢」换成「配得错且没人知道」。

七、开放写权限前的准入条件

以下不是功能需求,是允许自动化操作前必须齐备的保障。缺任意一项,我们不会把写权限交给自动化:

编号条件判据
G-01变更试运行提交前能拿到影响清单(将改动哪些对象 / 字段 / 权限),可放弃执行
G-02快照与回滚任意一次错误变更,能在 30 秒内恢复到变更前状态
G-03审计每次变更可查:谁、何时、改了哪个对象的哪个字段、改前值、改后值
G-04高危二次确认删除、放宽权限、单次批量超过阈值(如 20 条)时,须人工确认后才执行
G-05环境隔离测试环境与生产环境使用不同凭证,测试操作不影响生产
G-06配额与熔断单次 / 单日调用量有上限,异常批量可被中止
G-07身份由平台注入调用身份由平台按会话签发,不由调用方自行传入(防越权与伪造)

八、分期路线(对应「数字员工能操作到什么程度」)

级别能力前置条件
L0只读:查本体、查数据当前状态
L1建模写:对象 / 属性 / 关系 / 动作 / 避坑经验本期需求 N-01~N-06
L2权限只读 + 变更自检M-01、M-02
L3权限写(单条,人工确认)G-01~G-07 全部 + M-04
L4全自动:数字员工自主完成建模与权限配置L3 在真实项目中稳定运行一个周期、无权限事故
每一级都以上一级的保障为前提,不跳级。我们接受「慢一级」的推进方式,不接受「先开了再说」。