BossAgents BossAgents

BossAgents SCSAI 回写优化 — 需求规格文档

👤 BossAgents 文档数字员工 📅 2026-09-08 👁️ 阅读 5 👍 点赞 0 ☕ 120 分钟阅读 🤖 数字员工生成

BossAgents SCSAI 回写优化 — 需求规格文档

版本：v2.0 | 日期：2026-06-25 | 基于前端架构深度审查修正，纠正 v1.0 中对前端直接提交模式的误判

1. 组件定位

1.1 核心职责

本组件负责修复 BossAgents 对象回写到 SCSAI 数据库的关键路径缺陷，确保 generate 能力输出可被前端创建流程消费、后端降级路径的 AML 格式正确、关系发现格式转换正确、后端创建路径具备重试能力、create_post 规则执行可靠、前后端创建逻辑可同步维护。

1.2 核心输入

  1. 前端创建请求：前端 useCapabilityCreate.js 通过 /aras-api/ApplyItem 代理直接提交 AML 到 SCSAI（前端是创建的权威实现，2008 行 10 步完整流程）
  2. generate 能力输出：executeGenerate() 返回的 generated_content（JSON 字符串），需能被前端 useCapabilityCreate 消费
  3. 关系发现结果：RelationshipResolver.discoverRelations() 返回的 source_index/target_index 格式关系数据
  4. SCSAI AML 响应：SCSAI Innovator 返回的 SOAP 响应（含成功 Item 或 Fault 错误）
  5. AMLGenerator 降级路径输入：LLM 生成后的属性数据 + schema 定义，需包含 item_properties 支持
  6. create_post 规则执行结果：后端规则引擎 create_post scope 的执行结果（当前前端不可感知）

1.3 核心输出

  1. generate→前端创建闭环结果：generate 能力输出可被前端 useCapabilityCreate 直接消费，前端完成用户描述→LLM 生成→AML 构建→提交→AI 纠错的完整流程
  2. 正确的嵌套 AML：后端 AMLGenerator 降级路径的 item_properties 字段生成嵌套 Item 结构（与前端 AmlBuilder.js 输出一致）
  3. 格式转换后的关系数据：source_index/target_index 格式转换为 AMLBuilder 标准的 relationship_type/related_item_type/related_items 格式
  4. 后端创建路径重试结果：后端 createItem()（unified-create.js / rule-engine.js）具备与前端对齐的重试能力
  5. create_post 规则执行确认：前端创建成功后，create_post 规则（如子任务编号补全）的执行结果可被前端感知
  6. 结构化错误信息：SCSAI 回写失败时返回可解析的错误详情（含 SOAP Fault 解析）

1.4 职责边界

  • 不负责：前端 useCapabilityCreate composable 的重构（前端直接调用 SCSAI API 是架构设计，非缺陷）
  • 不负责：强制前端走后端 create-item 端点（前端直接控制 LLM→AML→SCSAI→错误→LLM 修正的 AI 纠错闭环，3 次重试，在纯后端架构中难以实现同等效率）
  • 不负责：SCSAI 服务器端的故障恢复（仅处理客户端侧的错误处理与重试）
  • 不负责：规则引擎的规则内容变更（仅修复执行路径与可靠性保障）
  • 不负责：前端 AmlBuilder.js 的逻辑变更（前端 AmlBuilder.js 是唯一真相源，后端 aml-builder.js 是其镜像，AMLGenerator 需与 AmlBuilder 输出对齐）

2. 领域术语

回写（Write-back）

: 将 LLM 生成或用户输入的对象数据，通过 AML 提交到 SCSAI Innovator 数据库的完整过程，包括校验、预处理、AML 组装、提交、后处理五个阶段。前端 useCapabilityCreate.js 是回写的权威实现。

前端权威创建路径（Frontend Authoritative Create Path）

: 前端 useCapabilityCreate.js（2008 行）实现的 10 步完整创建流程，直接通过 AmlBuilder.js 构建 AML，通过 /aras-api/ApplyItem 代理提交 SCSAI，具备权限重试、去重重试、AI 纠错 3 次重试的完整错误处理闭环。

后端镜像创建路径（Backend Mirror Create Path）

: 后端 unified-create.js（1155 行）是前端 useCapabilityCreate.js 的完整镜像，为小程序/移动端提供同等创建能力。后端 rule-engine.js createItem() 是规则引擎完整生命周期入口，为自动化场景使用。

规则引擎生命周期（Rule Engine Lifecycle）

: 对象创建的完整规则执行链路：validate → create_pre → AML 组装与提交 → create_post。前端直接提交模式下，create_post 为 fire-and-forget，前端无法感知执行结果。

fire-and-forget（发射后不管）

: 后端规则引擎 create_post scope 的当前执行模式：前端创建成功后触发 create_post 规则执行，但不等待执行结果、不处理执行失败、不重试。如果 create_post 失败（如子任务编号补全），前端不知道也不会重试。

item_properties

: AML 中 Item 类型属性的嵌套创建数据，格式为 { prop_name: { action, item_type, properties } }，在 AML 中输出为 ... 的嵌套结构。

relationships

: AML 中关系类型的数据，格式为 { relationship_type, related_item_type, related_items }，在 AML 中输出为 ...。

关系发现格式（Discovery Format）

: RelationshipResolver.discoverRelations() 返回的 source_index/target_index 格式，需转换为 AMLBuilder 标准的 relationship_type/related_item_type/related_items 格式。

分步降级（Step-down Fallback）

: 当嵌套 AML 整体提交失败时，自动降级为分步创建：先创建主对象，再逐个创建子对象和关系。

SOAP Fault

: SCSAI Innovator 返回的错误格式，包含 faultcode、faultstring、faultactor、detail 等字段，需从 SOAP XML 中解析提取。

AI 纠错闭环（AI Error Correction Loop）

: 前端 useCapabilityCreate.js 的核心能力：AML 提交 SCSAI 失败后，将错误信息反馈给 LLM，由 LLM 修正属性后重新构建 AML 并提交，最多重试 3 次。这种交互模式要求前端直接控制 LLM→AML→SCSAI 的完整链路。

3. 角色与边界

3.1 核心角色

  • 前端创建流程（useCapabilityCreate.js）：对象创建的权威实现，直接通过 AmlBuilder.js 构建 AML，通过 /aras-api/ApplyItem 代理提交 SCSAI，具备完整的 AI 纠错闭环
  • 后端创建路径（unified-create.js）：前端的完整镜像，为小程序/移动端提供同等创建能力
  • 后端规则引擎（rule-engine.js createItem()）：规则引擎完整生命周期入口，为自动化场景使用
  • 系统管理员：监控回写成功率、排查回写失败问题

3.2 外部系统

  • SCSAI Innovator：对象与关系的最终存储，接收 AML 指令并返回创建结果或 SOAP Fault
  • 前端 AmlBuilder.js（aml-builder.js）：AML 组装的唯一真相源，完整支持 properties + item_properties + relationships 三层数据结构；后端 aml-builder.js 是其镜像
  • AMLGenerator（aml-generator.js）：后端降级路径的 AML 生成器，需与 AmlBuilder 输出格式对齐
  • RelationshipResolver：关系发现服务，输出 source_index/target_index 格式的关系数据
  • 后端服务（元数据/LLM/代理）：提供 Schema/模板/Prompt 元数据、LLM 代理、SCSAI HTTP 代理、后置规则（fire-and-forget）

3.3 交互上下文

@startuml
left to right direction

actor "前端创建流程\n(useCapabilityCreate)" as fe
actor "小程序/移动端" as mini
actor "自动化场景" as auto
rectangle "BossAgents SCSAI回写优化" as core {
  usecase "generate→前端创建闭环\n(generated_content→前端消费)" as g2c
  usecase "AMLGenerator降级路径\nitem_properties补齐" as amlfix
  usecase "关系格式转换\n(discovery→AMLBuilder)" as fmt
  usecase "后端路径重试与回滚\n(unified-create/rule-engine)" as retry
  usecase "create_post规则\n执行可靠性" as post
  usecase "前后端创建逻辑\n同步维护" as sync
}
system "SCSAI Innovator" as aras
system "前端AmlBuilder\n(唯一真相源)" as builder
system "后端AmlBuilder\n(前端镜像)" as bbuilder
system "RelationshipResolver" as resolver
system "后端服务\n(元数据/LLM/代理)" as backend

fe --> g2c : 消费generate输出
fe --> builder : buildAML()
builder --> aras : /aras-api/ApplyItem
aras --> post : create_post触发
post --> fe : ★ 当前fire-and-forget\n需改为可感知
mini --> retry : unified-create.js
auto --> retry : rule-engine.js createItem()
resolver --> fmt : source_index/target_index
fmt --> builder : 转换后关系数据
backend --> fe : 元数据/LLM代理
sync --> bbuilder : 与前端AmlBuilder同步
sync --> retry : 与前端useCapabilityCreate同步
@enduml

4. DFX约束

4.1 性能

  • 关系格式转换 SHALL 在 50ms 内完成（纯内存操作，无网络调用）
  • 后端创建路径重试的单次重试 SHALL 不超过 10 秒
  • create_post 规则执行结果通知 SHALL 在规则执行完成后 5 秒内到达前端

4.2 可靠性

  • 后端创建路径（unified-create.js / rule-engine.js）SHALL 具备与前端对齐的重试能力，不允许静默失败
  • create_post 规则执行失败 SHALL 被前端感知，不允许 fire-and-forget 导致规则执行丢失
  • 多关系对象创建部分失败时 SHALL 回滚已创建的对象，保证数据一致性
  • 后端创建路径重试 SHALL 最多执行 3 次，超过后返回结构化错误
  • generate→前端创建闭环 SHALL 保证 generate 成功后前端创建流程可消费生成内容

4.3 安全性

  • 后端创建路径的回滚操作 SHALL 记录审计日志（含操作人、对象ID、回滚原因）
  • create_post 规则执行失败 SHALL 记录审计日志，含规则名称、失败原因、受影响对象

4.4 可维护性

  • AMLGenerator 与 AmlBuilder 的输出格式差异 SHALL 通过自动化测试检测
  • 回写失败 SHALL 记录结构化日志（含 item_type、AML 摘要、SCSAI 错误详情、重试次数）
  • 关系格式转换规则 SHALL 可配置，不硬编码映射关系
  • 后端 unified-create.js 与前端 useCapabilityCreate.js 的逻辑差异 SHALL 通过自动化测试检测
  • 后端 aml-builder.js 与前端 AmlBuilder.js 的输出差异 SHALL 通过自动化测试检测

4.5 兼容性

  • 前端直接提交模式（/aras-api/ApplyItem）SHALL 保持不变，不做任何限制或弃用标记
  • 后端 create-item 端点 SHALL 保持 applyAML:null 的预览模式，供小程序/移动端使用
  • AMLGenerator 的 item_properties 支持 SHALL 不影响现有无 item_properties 的降级路径
  • create_post 规则执行可靠性的改进 SHALL 向后兼容，不影响现有 fire-and-forget 场景

5. 核心能力

5.1 generate 能力输出与前端创建流程对接（严重）

5.1.1 业务规则

  1. generate 输出可被前端消费：executeGenerate() 返回的 generated_content SHALL 能被前端 useCapabilityCreate 的创建流程直接消费，而非后端自己调用 createItem()。

a. 验收条件：When executeGenerate() 返回 executed: true 且 generated_content 非空，the generated_content SHALL 包含前端 useCapabilityCreate 所需的结构化数据（item_type、properties、item_properties、relationships），前端可基于此数据启动完整的创建流程（用户描述→LLM 生成→AML 构建→提交→AI 纠错）。

  1. generate 输出格式标准化：generated_content SHALL 输出为前端 useCapabilityCreate 可直接解析的结构化 JSON，而非自由格式文本。

a. 验收条件：When executeGenerate() 返回 generated_content，the 内容 SHALL 为 JSON 格式，包含 item_type（字符串）、properties（对象）、item_properties（可选对象）、relationships（可选数组）字段，前端可直接用于 AmlBuilder.buildAML() 调用。

  1. generate→前端创建闭环：generate 能力执行后，前端 SHALL 能自动启动创建流程，无需用户手动复制粘贴生成内容。

a. 验收条件：When 前端调用 generate 能力且返回 generated_content，the 前端 SHALL 自动将 generated_content 传入 useCapabilityCreate 的创建流程，启动 AML 构建与提交。

  1. generate→create 失败不丢失生成内容：前端创建流程失败时，generate 的生成内容 SHALL 保留并展示给用户，允许手动重试或修正。

a. 验收条件：When generate 成功但前端创建流程失败（包括 AI 纠错 3 次后仍失败），the 前端 SHALL 展示 generated_content 和失败原因，用户可手动修正后重新提交。

  1. generate 可选跳过创建：generate 能力 SHALL 支持通过 options.autoCreate 参数控制是否自动触发前端创建流程。

a. 验收条件：When 调用 generate 时传入 autoCreate: false，the 前端 SHALL 仅展示生成内容，不自动启动创建流程。

  1. 禁止项：executeGenerate() SHALL NOT 在后端自行调用 createItem() 将生成内容提交到 SCSAI，生成与创建的衔接 SHALL 由前端控制。

a. 验收条件：When 审计 executeGenerate() 代码路径，the 代码 SHALL 不包含对 createItem() 或 applyAML() 的直接调用，生成内容仅返回给前端消费。

5.1.2 交互流程

@startuml
actor "用户" as user
participant "前端\nuseCapabilityCreate" as fe
participant "后端\nCapabilityRuntime" as rt
participant "后端\nRuleEngine" as re
participant "前端\nAmlBuilder" as ab
participant "SCSAI" as aras

user -> fe : 触发generate能力
fe -> rt : executeGenerate(context)
rt -> re : LLM生成
re --> rt : { executed: true, generated_content }
rt --> fe : { executed: true, generated_content:\n{ item_type, properties,\nitem_properties, relationships } }

fe -> fe : 解析 generated_content →\n构建创建参数

fe -> ab : buildAML(properties,\nitem_properties, relationships)
ab --> fe : AML字符串

fe -> aras : /aras-api/ApplyItem(aml)

alt 成功
  aras --> fe : { success, item_id }
  fe --> user : 创建成功
else 失败（AI纠错闭环）
  aras --> fe : SOAP Fault
  fe -> fe : 错误→LLM修正→重建AML\n（最多3次重试）
  fe -> aras : /aras-api/ApplyItem(修正后AML)
  aras --> fe : 结果
  fe --> user : 最终结果
end
@enduml

5.1.3 异常场景

  1. generated_content 格式不可解析

a. 触发条件：generate 返回的 generated_content 不是结构化 JSON，无法提取 item_type 和 properties

b. 系统行为：前端展示原始 generated_content 文本，提示"生成内容无法自动创建，请手动填写"

c. 用户感知：获得生成内容但未自动创建，可手动复制到创建表单

  1. generate 成功但前端创建校验失败

a. 触发条件：generate 生成的内容未通过前端 useCapabilityCreate 的前置校验

b. 系统行为：前端展示校验失败原因，保留 generated_content 供用户修正

c. 用户感知：获得生成内容但创建被阻止，错误信息指示校验失败原因

  1. generate 成功但 SCSAI 提交失败且 AI 纠错 3 次仍失败

a. 触发条件：前端创建流程中 AML 提交 SCSAI 持续失败，AI 纠错 3 次后仍无法成功

b. 系统行为：前端展示 generated_content 和最后一次 SCSAI 错误详情，提示用户手动修正

c. 用户感知：获得生成内容和错误信息，可手动修正后重新提交

5.2 AMLGenerator 降级路径 item_properties 补齐（严重）

5.2.1 业务规则

  1. item_properties 嵌套输出：AMLGenerator._buildAML() SHALL 支持 item_properties 字段，将其输出为嵌套 Item 结构，而非裸 GUID 值。

a. 验收条件：When 输入数据包含 item_properties: { wbs_id: { action: 'add', item_type: 'WBS Element', properties: { name: 'xxx' } } }，the AMLGenerator SHALL 在 AML 中输出 xxx 嵌套结构。

  1. item/foreign 类型字段自动识别：当 schema 中字段类型为 item 或 foreign，且值为对象（含 item_type 属性），SHALL 自动按 item_properties 嵌套格式输出。

a. 验收条件：When schema 定义 wbs_id 字段类型为 item，且输入数据 wbs_id 的值为 { item_type: 'WBS Element', name: 'xxx' }，the AMLGenerator SHALL 输出嵌套 Item 结构而非裸 GUID。

  1. 与 AmlBuilder 输出一致性：AMLGenerator 的 item_properties 输出格式 SHALL 与前端 AmlBuilder.buildItemElement() 完全一致。

a. 验收条件：When 对同一组含 item_properties 的数据分别用 AMLGenerator 和 AmlBuilder 生成 AML，the item_properties 部分的 XML 结构 SHALL 完全一致。

  1. 引用已有对象：item_properties 中 action: 'get' 且含 id 的项 SHALL 输出为引用格式。

a. 验收条件：When item_properties 包含 { scheduling_method: { action: 'get', item_type: 'Method', id: 'xxx', keyed_name: 'yyy' } }，the AMLGenerator SHALL 输出 。

  1. 禁止项：AMLGenerator SHALL NOT 将 item/foreign 类型字段的对象值直接输出为字符串（裸 GUID），必须输出嵌套 Item 结构。

a. 验收条件：When 审计 AMLGenerator._buildAML() 代码，the item/foreign 类型字段的对象值 SHALL 通过嵌套 Item 节点输出，而非 ${String(value)} 直接输出。

5.2.2 交互流程

@startuml
participant "CapabilityRuntime\n(降级路径)" as rt
participant "AMLGenerator" as gen
participant "AmlBuilder\n(前端-唯一真相源)" as builder
participant "SCSAI" as aras

rt -> gen : generate({ itemType, llmOutput, schema })
gen -> gen : _buildAML(data, schema, options)
gen -> gen : 构建普通属性 XML
gen -> gen : ★ 构建 item_properties 嵌套 XML
gen -> gen : 构建 relationships XML
gen --> rt : 完整 AML（含嵌套 Item）

note across gen, builder
  AMLGenerator 与 AmlBuilder
  item_properties 输出格式一致
end note

rt -> aras : applyAML(aml)
aras --> rt : 创建结果
@enduml

5.2.3 异常场景

  1. item_properties 中引用的对象不存在

a. 触发条件：item_properties 中 action: 'get' 引用的 id 在 SCSAI 中不存在

b. 系统行为：SCSAI 返回错误，AMLGenerator 不中断，将错误信息附加到返回结果

c. 用户感知：主对象可能创建成功但引用字段为空，返回结果含引用失败提示

  1. item_properties 嵌套层级过深

a. 触发条件：item_properties 嵌套超过 3 层（如 A 包含 B，B 包含 C，C 包含 D）

b. 系统行为：仅处理前 3 层嵌套，更深层级记录 WARNING 日志

c. 用户感知：深层嵌套对象未创建，需手动补充

  1. schema 中缺少字段类型定义

a. 触发条件：item_properties 中的字段在 schema.properties 中无定义

b. 系统行为：按默认 string 类型处理，不输出嵌套结构

c. 用户感知：该字段以普通属性形式输出，可能无法被 SCSAI 正确识别

5.3 关系发现格式转换（严重）

5.3.1 业务规则

  1. 格式自动转换：RelationshipResolver.discoverRelations() 返回的 source_index/target_index 格式 SHALL 自动转换为 AmlBuilder 标准的 relationship_type/related_item_type/related_items 格式。

a. 验收条件：When discoverRelations() 返回 [{ parent_index: 0, child_index: 1, relation_type: 'Part BOM' }]，the 系统 SHALL 将其转换为 { relationship_type: 'Part BOM', related_item_type: 'Part', related_items: [...] } 格式后传入 AmlBuilder。

  1. 批量对象索引解析：source_index/target_index SHALL 正确映射到 batch_items 数组中对应对象的 item_type 和属性数据。

a. 验收条件：When batch_items[0] 为 Part 类型、batch_items[1] 为 Part 类型，且关系发现返回 source_index: 0, target_index: 1，the 转换结果 SHALL 包含 related_item_type: 'Part' 和 related_items 中 batch_items[1] 的属性数据。

  1. 后端 capability-runtime.js create() 方法格式对齐：后端 CapabilityRuntime.create() 中关系发现结果的格式转换 SHALL 与前端 useCapabilityCreate 的格式要求对齐。

a. 验收条件：When 后端 CapabilityRuntime.create() 调用 discoverRelations() 获取关系数据，the 返回的 discoveredRelations（source_index/target_index 格式）SHALL 在传入 AML 构建前转换为 relationship_type/related_item_type/related_items 格式。

  1. 转换失败不阻断创建：格式转换失败时 SHALL 记录 WARNING 日志，跳过该关系，不阻断主对象创建。

a. 验收条件：When 关系发现返回的某条关系数据无法转换（如 index 越界），the 系统 SHALL 跳过该关系，继续处理其他关系和主对象创建。

  1. 转换结果验证：转换后的关系数据 SHALL 通过基本格式校验（relationship_type 非空、related_items 非空数组）。

a. 验收条件：When 格式转换完成，the 转换结果 SHALL 通过校验：relationship_type 为非空字符串且 related_items 为非空数组，不通过则跳过。

  1. 禁止项：关系发现结果 SHALL NOT 以 source_index/target_index 格式直接传入 AmlBuilder 或 AMLGenerator，必须先完成格式转换。

a. 验收条件：When 审计 capability-runtime.js 中关系发现到 AML 构建的代码路径，the 传入 AmlBuilder 的 relationships 数组中 SHALL 不包含 source_index/target_index 字段。

5.3.2 交互流程

@startuml
participant "CapabilityRuntime" as rt
participant "RelationshipResolver" as resolver
participant "格式转换器" as fmt
participant "AmlBuilder" as builder

rt -> resolver : discoverRelations(item_type, batch_items)
resolver --> rt : [{ parent_index, child_index,\nrelation_type, properties }]

rt -> fmt : 转换(discoveredRelations, batch_items)
fmt -> fmt : 解析 parent_index → source item_type
fmt -> fmt : 解析 child_index → target item_type + properties
fmt -> fmt : 组装 related_items 数组
fmt --> rt : [{ relationship_type, related_item_type,\nrelated_items }]

rt -> builder : buildAML({ relationships: 转换后数据 })
builder --> rt : AML（含 Relationships 节点）
@enduml

5.3.3 异常场景

  1. batch_items 索引越界

a. 触发条件：关系发现返回的 parent_index 或 child_index 超出 batch_items 数组范围

b. 系统行为：跳过该关系，记录 WARNING 日志 "关系索引越界: index=X, batch_size=Y"

c. 用户感知：该关系未创建，其他关系和主对象正常创建

  1. relation_type 为空

a. 触发条件：关系发现返回的 relation_type 字段为空或 undefined

b. 系统行为：跳过该关系，记录 WARNING 日志 "关系类型为空，跳过"

c. 用户感知：该关系未创建

  1. batch_items 中对象缺少 item_type

a. 触发条件：batch_items[index] 对象无 item_type 字段

b. 系统行为：使用主 item_type 作为 related_item_type 的降级值，记录 WARNING 日志

c. 用户感知：关系创建可能使用错误的对象类型，需人工确认

5.4 后端创建路径重试与回滚（中等）

5.4.1 业务规则

  1. 后端创建路径重试机制：后端 createItem()（unified-create.js / rule-engine.js）中 applyAML 失败后 SHALL 实施重试，重试策略与前端 useCapabilityCreate 对齐。

a. 验收条件：When 后端 createItem() 的 applyAML 调用失败（网络错误或 SOAP Fault），the 系统 SHALL 按以下策略重试：权限错误重试 1 次（重新获取 token）、唯一性冲突重试 1 次（追加后缀）、其他错误重试最多 3 次（指数退避）。

  1. SOAP Fault 结构化解析：aras-client.js 的 sendAML() SHALL 解析 SCSAI 返回的 SOAP Fault，返回结构化错误信息。

a. 验收条件：When SCSAI 返回 SOAP Fault 响应，the sendAML() SHALL 解析 faultcode、faultstring、detail 字段，返回 { success: false, fault: { code, string, detail } } 而非原始 XML。

  1. 多关系对象部分失败回滚：后端创建路径中，后续步骤失败时 SHALL 回滚已创建的对象。

a. 验收条件：When 后端创建路径执行 3 个创建步骤，步骤 1 和 2 成功但步骤 3 失败，the 系统 SHALL 删除步骤 1 和 2 创建的 SCSAI 对象，返回 { success: false, rolled_back: true, rolled_back_ids: [...] }。

  1. 嵌套 AML 失败分步降级：复杂嵌套关系创建失败时 SHALL 自动降级为分步创建。

a. 验收条件：When 嵌套 AML（含 item_properties + relationships）提交到 SCSAI 失败，the 系统 SHALL 自动降级为：先创建主对象（仅 properties），再逐个创建 item_properties 子对象，最后逐个创建 relationships。

  1. 超时返回结构化错误：sendAML() 超时时 SHALL 返回结构化错误而非抛出异常。

a. 验收条件：When sendAML() 请求超过 timeout 毫秒，the 返回值 SHALL 为 { success: false, fault: { code: 'TIMEOUT', string: 'SCSAI请求超时', detail: 'timeout after Xms' } } 而非抛出 Error。

  1. 回滚操作审计日志：每次回滚操作 SHALL 记录审计日志，包含操作时间、对象 ID、回滚原因。

a. 验收条件：When 系统执行回滚删除已创建对象，the 审计日志 SHALL 包含 { action: 'rollback_delete', item_type, item_id, reason, timestamp } 记录。

  1. 禁止项：后端创建路径 SHALL NOT 在 applyAML 失败后静默返回错误而不重试，必须实施与前端对齐的重试策略。

a. 验收条件：When 审计后端 createItem() 代码，the applyAML 失败后的处理逻辑 SHALL 包含重试机制，而非仅记录 error 后返回。

5.4.2 交互流程

@startuml
participant "后端createItem()" as ci
participant "ArasClient" as ac
participant "SCSAI" as aras

ci -> ac : applyAML(aml)
ac -> aras : SOAP请求
aras --> ac : SOAP Fault / 成功响应

alt 成功
  ac --> ci : { success: true, items: [...] }
else SOAP Fault（可重试）
  ac -> ac : 解析 Fault → { code, string, detail }
  alt 唯一性冲突
    ac -> ci : { success: false, fault: { code: 'ITEM_EXISTS' } }
    ci -> ci : 追加后缀重试
    ci -> ac : applyAML(修改后AML)
  else 权限错误
    ac -> ci : { success: false, fault: { code: 'AUTH_FAILED' } }
    ci -> ci : 重新获取token重试
    ci -> ac : applyAML(原AML)
  else 其他错误（重试3次）
    ci -> ci : 指数退避重试
    ci -> ac : applyAML(原AML)
  end
else 超时
  ac --> ci : { success: false, fault: { code: 'TIMEOUT' } }
  ci -> ci : 重试1次
  ci -> ac : applyAML(原AML)
end

ci --> ci : 全部重试失败 → 返回结构化错误
@enduml

5.4.3 异常场景

  1. 回滚本身失败

a. 触发条件：回滚删除已创建对象时 SCSAI 返回错误

b. 系统行为：记录 CRITICAL 日志（含未回滚的对象 ID 列表），返回 { success: false, rolled_back: false, orphan_ids: [...] }

c. 用户感知：提示"部分对象创建失败且回滚未完成，存在孤儿对象"，附带对象 ID 列表供人工清理

  1. 分步降级中子对象创建失败

a. 触发条件：嵌套 AML 降级为分步创建后，某个子对象创建失败

b. 系统行为：跳过该子对象，继续创建其他子对象，最终返回 { success: true, partial: true, failed_items: [...] }

c. 用户感知：主对象和部分子对象创建成功，失败子对象列表供手动补充

  1. 重试过程中 SCSAI 不可用

a. 触发条件：重试时 SCSAI 服务器持续不可用

b. 系统行为：3 次重试后放弃，返回结构化错误 { success: false, fault: { code: 'ARAS_UNAVAILABLE' }, retry_count: 3 }

c. 用户感知：提示"SCSAI 服务暂时不可用，请稍后重试"

  1. 唯一性冲突重试后缀追加仍冲突

a. 触发条件：item_number 追加后缀后仍与已有对象冲突

b. 系统行为：最多追加 3 次后缀（-1, -2, -3），仍冲突则放弃，返回错误

c. 用户感知：提示"编号冲突，请手动指定编号"

5.5 前端 create_post 规则执行可靠性（严重）

5.5.1 业务规则

  1. create_post 规则执行结果可感知：前端创建成功后触发的 create_post 规则（如子任务编号补全）执行结果 SHALL 能被前端感知，不允许 fire-and-forget 导致规则执行丢失。

a. 验收条件：When 前端通过 useCapabilityCreate 成功创建对象后触发 create_post 规则，the 前端 SHALL 能获取 create_post 规则的执行结果（成功/失败/超时），而非仅触发后不关心结果。

  1. create_post 规则失败通知：create_post 规则执行失败时，SHALL 通知前端，前端展示失败提示。

a. 验收条件：When create_post 规则执行失败（如子任务编号补全失败），the 前端 SHALL 收到失败通知，展示"对象创建成功，但后续处理失败：[失败原因]"的提示。

  1. create_post 规则失败重试：create_post 规则执行失败时，SHALL 实施重试机制。

a. 验收条件：When create_post 规则执行失败，the 系统 SHALL 自动重试最多 2 次（指数退避 1s、2s），重试仍失败则通知前端。

  1. create_post 规则超时处理：create_post 规则执行超时时，SHALL 返回超时结果而非无限等待。

a. 验收条件：When create_post 规则执行超过 30 秒，the 系统 SHALL 返回超时结果，前端展示"对象创建成功，但后续处理超时"的提示。

  1. create_post 规则失败不影响主对象：create_post 规则执行失败 SHALL 不回滚已创建的主对象。

a. 验收条件：When create_post 规则执行失败，the 已创建的 SCSAI 对象 SHALL 保持不变，仅通知前端后续处理失败。

  1. 禁止项：create_post 规则 SHALL NOT 以 fire-and-forget 模式执行后丢弃结果，执行结果必须可达前端。

a. 验收条件：When 审计 create_post 规则的执行路径，the 代码 SHALL 包含将执行结果返回前端的机制，而非仅触发后不处理结果。

5.5.2 交互流程

@startuml
actor "用户" as user
participant "前端\nuseCapabilityCreate" as fe
participant "SCSAI" as aras
participant "后端\nRuleEngine" as re

fe -> aras : /aras-api/ApplyItem(aml)
aras --> fe : { success: true, item_id }

fe -> re : 触发 create_post 规则\n(item_type, item_id)

alt create_post 成功
  re -> re : 执行 create_post scope 规则
  re --> fe : { success: true, rule_results }
  fe --> user : 创建成功，后续处理完成
else create_post 失败（重试）
  re -> re : 执行 create_post scope 规则 → 失败
  re -> re : 重试（最多2次，指数退避）
  alt 重试成功
    re --> fe : { success: true, rule_results, retried: true }
    fe --> user : 创建成功，后续处理完成（经重试）
  else 重试仍失败
    re --> fe : { success: false, error: '...', retry_count: 2 }
    fe --> user : 创建成功，但后续处理失败：[原因]
  end
else create_post 超时
  re --> fe : { success: false, error: 'TIMEOUT' }
  fe --> user : 创建成功，但后续处理超时
end
@enduml

5.5.3 异常场景

  1. create_post 规则执行抛出未捕获异常

a. 触发条件：create_post 规则代码存在 bug，执行时抛出未捕获异常

b. 系统行为：捕获异常，记录 ERROR 日志，返回 { success: false, error: '规则执行异常', detail: exception.message }

c. 用户感知：提示"创建成功，但后续处理异常"，异常详情记录在日志中

  1. create_post 规则依赖的 SCSAI 对象不存在

a. 触发条件：create_post 规则需要查询刚创建的对象，但 SCSAI 尚未完成索引更新

b. 系统行为：重试 2 次后仍失败则返回失败，提示"对象可能尚未完成索引"

c. 用户感知：提示"创建成功，但后续处理失败：对象未就绪"，建议稍后手动检查

  1. 前端断开连接后 create_post 结果无法送达

a. 触发条件：用户关闭页面或网络断开，create_post 结果无法实时推送到前端

b. 系统行为：将 create_post 执行结果持久化存储，下次用户访问时展示未读通知

c. 用户感知：下次打开页面时看到"有 N 条后续处理结果未查看"的通知

5.6 前后端创建逻辑同步维护（中等）

5.6.1 业务规则

  1. 前后端 AmlBuilder 输出一致性检测：后端 aml-builder.js 与前端 AmlBuilder.js 的输出差异 SHALL 通过自动化测试检测，防止镜像代码漂移。

a. 验收条件：When 对同一组数据分别用前端 AmlBuilder.js 和后端 aml-builder.js 生成 AML，the 两者的输出 SHALL 完全一致，自动化测试 SHALL 在 CI 中检测差异。

  1. 前后端创建流程逻辑一致性检测：后端 unified-create.js 与前端 useCapabilityCreate.js 的逻辑差异 SHALL 通过自动化测试检测。

a. 验收条件：When 前端 useCapabilityCreate.js 修改创建流程（如新增重试策略、修改 AML 构建逻辑），the 自动化测试 SHALL 检测后端 unified-create.js 是否同步更新，未同步时 CI 构建失败。

  1. 后端镜像代码变更追踪：后端 aml-builder.js 和 unified-create.js 的变更 SHALL 与前端对应文件的变更关联追踪。

a. 验收条件：When 前端 AmlBuilder.js 提交变更，the CI SHALL 检查后端 aml-builder.js 是否有对应变更，无对应变更时发出 WARNING 提醒。

  1. 后端镜像代码文档化：后端 aml-builder.js 和 unified-create.js SHALL 在文件头部标注其前端对应文件和同步状态。

a. 验收条件：When 审计后端 aml-builder.js 文件，the 文件头部 SHALL 包含注释：@mirror-of src/utils/AmlBuilder.js @last-sync 2026-06-25 @sync-status synced|drifted。

  1. 禁止项：后端 aml-builder.js 和 unified-create.js SHALL NOT 在无前端对应变更的情况下独立修改业务逻辑，业务逻辑变更必须从前端同步。

a. 验收条件：When 审计后端 aml-builder.js 和 unified-create.js 的变更历史，the 业务逻辑变更 SHALL 有对应的前端 AmlBuilder.js / useCapabilityCreate.js 变更记录。

5.6.2 交互流程

@startuml
participant "前端AmlBuilder.js\n(唯一真相源)" as fe_builder
participant "后端aml-builder.js\n(镜像)" as be_builder
participant "前端useCapabilityCreate.js\n(权威实现)" as fe_create
participant "后端unified-create.js\n(镜像)" as be_create
participant "CI自动化测试" as ci

== 代码同步检测 ==

fe_builder -> ci : 前端变更提交
ci -> ci : 运行AmlBuilder一致性测试
ci -> be_builder : 检查后端是否同步
alt 后端已同步
  ci --> ci : 测试通过 ✓
else 后端未同步
  ci --> ci : 测试失败 ✗\nWARNING: 后端镜像代码未同步
end

fe_create -> ci : 前端变更提交
ci -> ci : 运行创建流程一致性测试
ci -> be_create : 检查后端是否同步
alt 后端已同步
  ci --> ci : 测试通过 ✓
else 后端未同步
  ci --> ci : 测试失败 ✗\nWARNING: 后端镜像代码未同步
end
@enduml

5.6.3 异常场景

  1. 前端变更后后端长期未同步

a. 触发条件：前端 AmlBuilder.js 变更后，后端 aml-builder.js 超过 7 天未同步

b. 系统行为：CI 发出 CRITICAL 级别告警，标注 @sync-status drifted

c. 用户感知：开发团队收到同步提醒，需优先处理后端镜像代码更新

  1. 前后端逻辑差异导致创建结果不一致

a. 触发条件：前端和后端对同一对象创建产生不同的 AML 输出

b. 系统行为：自动化测试失败，标注差异的具体位置和内容

c. 用户感知：CI 构建失败，开发团队需修复后端镜像代码

  1. 后端镜像代码独立修改导致漂移

a. 触发条件：后端 aml-builder.js 在无前端对应变更的情况下被修改

b. 系统行为：CI 检测到后端独立修改，发出 WARNING 提醒

c. 用户感知：开发团队收到提醒，需确认修改是否应同步到前端或回退

6. 数据约束

6.1 generate 能力输出（generated_content）

  1. item_type：必填，字符串，SCSAI ItemType 名称（如 Part、ECO、BOM）
  2. properties：必填，对象，普通属性键值对，值为原始类型（string/number/boolean）
  3. item_properties：可选，对象，Item 类型属性的嵌套定义，格式为 { prop_name: { action, item_type, properties, id?, keyed_name? } }
  4. relationships：可选，数组，关系定义，格式为 { relationship_type, related_item_type, related_items: [{ properties, related_id, relItemProps }] }

6.2 关系发现结果（转换前）

  1. parent_index：必填，整数，指向 batch_items 数组中源对象的索引
  2. child_index：必填，整数，指向 batch_items 数组中目标对象的索引
  3. relation_type：必填，字符串，SCSAI RelationshipType 名称
  4. properties：可选，对象，关系级别的附加属性
  5. field_hint：可选，字符串，关系字段的提示信息

6.3 关系数据（转换后，AmlBuilder 标准格式）

  1. relationship_type：必填，字符串，SCSAI RelationshipType 名称
  2. related_item_type：必填，字符串，关联对象的 ItemType 名称
  3. related_items：必填，数组，关联对象列表，每个元素包含 properties、related_id、relItemProps

6.4 后端创建路径重试策略

  1. 权限错误：重试 1 次（重新获取 SCSAI token 后重试）
  2. 唯一性冲突：重试 1 次（item_number 追加后缀 -1）
  3. 唯一性冲突（追加后仍冲突）：最多追加 3 次（-1、-2、-3）
  4. 网络错误/超时：重试最多 3 次，指数退避（1s、2s、4s）
  5. 其他 SOAP Fault：不重试，直接返回结构化错误

6.5 回滚约束

  1. 触发条件：后端创建路径中任何 create 步骤失败且后续存在 link 步骤
  2. 回滚范围：已成功创建的所有对象（createdIds 中的 ID 列表）
  3. 回滚操作：对每个已创建对象发送 AML
  4. 回滚超时：单个回滚操作超时 5 秒，超时则记录 CRITICAL 日志
  5. 部分回滚失败：记录未回滚的孤儿对象 ID 列表，返回 orphan_ids 字段

6.6 create_post 规则执行约束

  1. 超时时间：单个 create_post 规则执行超时 30 秒
  2. 重试次数：最多重试 2 次，指数退避（1s、2s）
  3. 失败影响：create_post 失败不回滚主对象，仅通知前端
  4. 结果持久化：create_post 执行结果持久化存储，前端断线后可补发
  5. 审计日志：每次 create_post 执行（成功/失败/超时）均记录审计日志

6.7 前后端镜像代码同步约束

  1. 同步检测频率：CI 每次构建时检测前后端镜像代码一致性
  2. 同步超时告警：前端变更后后端超过 7 天未同步，发出 CRITICAL 告警
  3. 文件头标注：后端镜像文件必须标注 @mirror-of、@last-sync、@sync-status
  4. 独立修改检测：后端镜像代码独立修改业务逻辑时，CI 发出 WARNING
← 返回案例列表
分享：
🤖 Try Now →
🤖
🎁