BossAgents SCSAI Write-back Optimization — Requirements Specification Document

Version: v2.0 | Date: 2026-06-25 | Revised based on in-depth review of frontend architecture, correcting the misjudgment in v1.0 regarding the frontend direct submission mode

1. Component Positioning

1.1 Core Responsibilities

This component is responsible for fixing critical path defects in writing BossAgents objects back to the SCSAI database, ensuring that the generate capability output can be consumed by the frontend creation process, the AML format for backend fallback paths is correct, relationship discovery format conversion is accurate, the backend creation path has retry capability, create_post rule execution is reliable, and frontend/backend creation logic can be maintained synchronously.

1.2 Core Inputs

1. Frontend creation request: Frontend useCapabilityCreate.js submits AML directly to SCSAI via the /SCSAI-api/ApplyItem proxy (frontend is the authoritative implementation of creation, a complete 10-step process at line 2008).
2. Generate capability output: The generated_content (JSON string) returned by executeGenerate(), which must be consumable by frontend useCapabilityCreate.
3. Relationship discovery results: Relationship data in source_index/target_index format returned by RelationshipResolver.discoverRelations()
4. SCSAI AML Response: SCSAI Agent's SOAP response (containing successful Items or Fault errors)
5. AMLGenerator Fallback Path Input: LLM-generated attribute data + schema definition, must include item_properties support
6. create_post Rule Execution Result: Backend rule engine create_post scope execution result (currently not perceivable by frontend)

1.3 Core Outputs

1. generate → Frontend Creation Closed-loop Result: generate capability output can be directly consumed by frontend useCapabilityCreate, enabling the complete workflow from user description → LLM generation → AML construction → submission → AI error correction
2. Correctly Nested AML: Backend AMLGenerator fallback path's item_properties field generates nested Item structure (consistent with frontend AmlBuilder.js output)
3. Relationship Data After Format Conversion: source_index/target_index format converted to AMLBuilder standard relationship_type/related_item_type/related_items format
4. Backend creation path retry result: The backend createItem() (un.gified-create.js / rule-engine.js) possesses retry capability aligned with the frontend.
5. create_post rule execution confirmation: The execution result of the create_post rule (e.g., subtask number completion) can be perceived by the frontend after successful frontend creation.
6. Structured error information: Returns parsable error details (including SOAP Fault parsing) when SCSAI write-back fails.

1.4 Responsibility Boundaries

• Not responsible: Refactoring of the frontend useCapabilityCreate composable (Frontend directly calling the SCSAI API is an architectural design, not a defect).
• Not responsible: Forcing the frontend to use the backend create-item endpoint (The frontend directly controls the AI error correction loop of LLM→AML→SCSAI→error→LLM correction, with 3 retries, which is difficult to achieve with equivalent efficiency in a pure backend architecture).
• Not responsible: SCSAI server-side failure recovery (Only handles client-side error handling and retries).
• Not responsible: Changes to the content of rules in the rule engine (Only fixes execution paths and reliability guarantees).
• Not responsible: Logic changes to the frontend AmlBuilder.js (The frontend AmlBuilder.js is the single source of truth; the backend aml-builder.js is its mirror. The AMLGenerator must align with the output of AmlBuilder).

2. Domain Terminology

Write-back

: The complete process of submitting object data generated by the LLM or entered by the user to the SCSAI Agent database via AML, comprising five stages: validation, preprocessing, AML assembly, submission, and post-processing. The frontend useCapabilityCreate.js is the authoritative implementation of the write-back.

Frontend Authoritative Create Path

: The complete 10-step creation flow implemented by the frontend useCapabilityCreate.js (2008 lines). It directly constructs AML via AmlBuilder.js and submits to SCSAI via the /SCSAI-api/ApplyItem proxy, featuring a complete error-handling loop with three retry mechanisms: permission retry, deduplication retry, and AI error correction.

Backend Mirror Create Path

Backend unified-create.js (1155 lines) is a complete mirror of frontend useCapabilityCreate.js, providing equivalent creation capabilities for mini-programs/mobile terminals. Backend rule-engine.js createItem() is the full lifecycle entry point for the rule engine, used for automation scenarios.

Rule Engine Lifecycle

The complete rule execution chain for object creation: validate → create_pre → AML assembly and submission → create_post. In direct frontend submission mode, create_post operates as fire-and-forget, where the frontend cannot perceive the execution result.

fire-and-forget

The current execution mode for the backend rule engine's create_post scope: triggered upon successful frontend creation, but does not wait for results, handle failures, or retry. If create_post fails (e.g., child task number completion), the frontend is unaware and will not retry.

item_properties

Nested creation data for Item-type properties in AML, formatted as { prop_name: { action, item_type, properties } }, output in AML as a nested structure of ...

relationships

: In AML, data of relationship types formatted as { relationship_type, related_item_type, related_items }, output in AML as ...

Relationship Discovery Format

: The source_index/target_index format returned by RelationshipResolver.discoverRelations() must be converted to the AMLBuilder standard format: relationship_type/related_item_type/related_items.

Step-down Fallback

: When the submission of a nested AML fails entirely, automatically fall back to stepwise creation: first create the main object, then create child objects and relationships one by one.

SOAP Fault

: The error format returned by the SCSAI Agent, containing fields such as faultcode, faultstring, faultactor, detail, which need to be parsed and extracted from the SOAP XML.

AI Error Correction Loop

: Core capability of frontend useCapabilityCreate.js: After AML submission to SCSAI fails, error information is fed back to the LLM. The LLM corrects the attributes, rebuilds the AML, and resubmits, with a maximum of 3 retries. This interaction pattern requires the frontend to directly control the complete LLM→AML→SCSAI chain.

3. Roles and Boundaries

3.1 Core Roles

• Frontend Creation Process (useCapabilityCreate.js): The authoritative implementation for object creation, directly builds AML via AmlBuilder.js, submits to SCSAI via the /SCSAI-api/ApplyItem proxy, and possesses a complete AI error correction loop.
• Backend Creation Path (unified-create.js): A complete mirror of the frontend, providing equivalent creation capabilities for mini-programs/mobile apps.
• Backend Rule Engine (rule-engine.js createItem()): The full lifecycle entry point for the rule engine, used for automation scenarios.
• System Administrator: Monitors write-back success rates and troubleshoots write-back failures.

3.2 External Systems

• SCSAI Agent: The final storage for objects and relationships, receives AML instructions and returns creation results or SOAP Faults.
• Frontend AmlBuilder.js (aml-builder.js): The single source of truth for AML assembly, fully supporting the three-layer data structure of properties + item_properties + relationships; the backend aml-builder.js is its mirror.
• AMLGenerator (aml-generator.js): The AML generator for backend fallback paths, requiring alignment with AmlBuilder's output format.
• RelationshipResolver: A relationship discovery service, outputting relationship data in source_index/target_index format.
• Backend services (metadata/LLM/agent): Providing Schema/Template/Prompt metadata, LLM agent, SCSAI HTTP agent, and post-processing rules (fire-and-forget).

3.3 Interaction Context

@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 Agent" as SCSAI
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 --> SCSAI : /SCSAI-api/ApplyItem
SCSAI --> 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 兼容性

• 前端直接提交模式（/SCSAI-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 Generate→AML 构建→Submit→AI 纠错）。

1. Standardization of generate output format: generated_content SHALL output as structured JSON directly parsable by the frontend useCapabilityCreate, not free-form text.

a. Acceptance criteria: When executeGenerate() returns generated_content, the content SHALL be in JSON format, containing fields item_type (string), properties (object), item_properties (optional object), and relationships (optional array), which can be directly used by the frontend for AmlBuilder.buildAML() calls.

1. generate → frontend creation closed loop: After the generate capability is executed, the frontend SHALL automatically initiate the creation process without requiring users to manually copy and paste the generated content.

a. Acceptance criteria: When the frontend calls the generate capability and generated_content is returned, the frontend SHALL automatically pass generated_content into the creation flow of useCapabilityCreate, initiating AML construction and submission.

1. generate → create failure does not lose generated content: If the frontend creation flow fails, the generated content from generate SHALL be retained and displayed to the user, allowing manual retry or correction.

a. Acceptance criteria: When generate succeeds but the frontend creation flow fails (including after 3 AI correction attempts), the frontend SHALL display generated_content and the failure reason, allowing the user to manually correct and resubmit.

1. generate Optional Skip Creation: The generate capability SHALL support controlling whether to automatically trigger the front-end creation process via the options.autoCreate parameter.

a. Acceptance Criteria: When calling generate with autoCreate: false, the front-end SHALL only display the generated content and not automatically initiate the creation process.

1. Prohibition: executeGenerate() SHALL NOT call createItem() on the backend to submit generated content to SCSAI; the handoff between generation and creation SHALL be controlled by the front-end.

a. Acceptance Criteria: When auditing the executeGenerate() code path, the code SHALL not contain direct calls to createItem() or applyAML(); generated content shall only be returned for front-end consumption.

5.1.2 Interaction Flow

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

user -> fe : 触发generate能力
fe -> rt : executeGenerate(context)
rt -> re : LLMGenerate
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 -> SCSAI : /SCSAI-api/ApplyItem(aml)

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

5.1.3 异常场景

1. generated_content 格式不可解析

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

b. System Behavior: The front-end displays the original generated_content text and prompts "Generated content cannot be created automatically; please fill in manually."

c. User perception: Receives generated content but it is not automatically created; can manually copy to the creation form.

1. Generation succeeded but front-end creation validation failed.

a. Trigger condition: The content generated by 'generate' fails the pre-validation of the front-end useCapabilityCreate.

b. System behavior: The front-end displays the validation failure reason and retains the generated_content for user correction.

c. User perception: Receives generated content but creation is blocked, with error messages indicating the validation failure reason.

1. Generation succeeded but SCSAI submission failed and AI error correction failed 3 times.

a. Trigger condition: During the front-end creation process, AML submission to SCSAI continuously fails, and AI error correction fails 3 times without success.

b. System behavior: The front-end displays the generated_content and the last SCSAI error details, prompting the user to manually correct.

c. User perception: Receives generated content and error information, can manually correct and resubmit.

5.2 AMLGenerator Fallback Path for item_properties Completion (Severe)

5.2.1 Business Rules

1. Nested output for item_properties: AMLGenerator._buildAML() SHALL support the item_properties field, outputting it as a nested Item structure, not as bare GUID values.

a. Acceptance criteria: When input data contains item_properties: { wbs_id: { action: 'add', item_type: 'WBS Element', properties: { name: 'xxx' } } }, the AMLGenerator SHALL output the xxx nested structure in AML.

1. Automatic identification of item/foreign type fields: When a field type in the schema is item or foreign, and its value is an object (containing the item_type property), it SHALL automatically output in the nested item_properties format.

a. Acceptance criteria: When the schema defines the wbs_id field type as item, and the input data value for wbs_id is { item_type: 'WBS Element', name: 'xxx' }, the AMLGenerator SHALL output a nested Item structure, not a bare GUID.

1. Consistency with AmlBuilder output: The item_properties output format of AMLGenerator SHALL be exactly the same as that of the front-end AmlBuilder.buildItemElement().

a. Acceptance criteria: When generating AML for the same set of data containing item_properties using AMLGenerator and AmlBuilder respectively, the XML structure of the item_properties section SHALL be completely identical.

1. Referencing existing objects: Items in item_properties with action: 'get' and containing an id SHALL be output in reference format.

a. Acceptance criteria: When item_properties contains { scheduling_method: { action: 'get', item_type: 'Method', id: 'xxx', keyed_name: 'yyy' } }, the AMLGenerator SHALL output .

1. Prohibited items: AMLGenerator SHALL NOT directly output object values of item/foreign type fields as strings (bare GUIDs); it must output nested Item structures.

a. Acceptance Condition: When auditing the AMLGenerator._buildAML() code, the object values of item/foreign type fields SHALL be output through nested Item nodes, not directly output as ${String(value)}.

5.2.2 Interaction Flow

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

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 -> SCSAI : applyAML(aml)
SCSAI --> rt : 创建结果
@enduml

5.2.3 异常场景

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

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

b. System Behavior: SCSAI returns an error, AMLGenerator does not interrupt, and appends the error message to the return result.

c. User Perception: The main object may be created successfully but reference fields are empty; the return result contains a reference failure prompt.

1. item_properties nesting level is too deep.

a. Trigger Condition: item_properties nesting exceeds 3 levels (e.g., A contains B, B contains C, C contains D).

b. System Behavior: Only process the first 3 nesting levels; deeper levels are logged as WARNING.

c. User Perception: Deeply nested objects are not created and need to be manually supplemented.

1. Missing field type definition in schema.

a. Trigger Condition: A field in item_properties has no definition in schema.properties.

b. System behavior: Processed as a default string type, without outputting nested structures.

c. User perception: This field is output as a regular attribute and may not be correctly recognized by SCSAI.

5.3 Relationship Discovery Format Conversion (Severe)

5.3.1 Business Rules

1. Automatic format conversion: The source_index/target_index format returned by RelationshipResolver.discoverRelations() SHALL be automatically converted to the AmlBuilder standard relationship_type/related_item_type/related_items format.

a. Acceptance criteria: When discoverRelations() returns [{ parent_index: 0, child_index: 1, relation_type: 'Part BOM' }], the system SHALL convert it to the format { relationship_type: 'Part BOM', related_item_type: 'Part', related_items: [...] } before passing it to AmlBuilder.

1. Batch object index parsing: source_index/target_index SHALL correctly map to the item_type and attribute data of the corresponding object in the batch_items array.

a. Acceptance criteria: When batch_items[0] is of type Part, batch_items[1] is of type Part, and the relationship discovery returns source_index: 0, target_index: 1, the conversion result SHALL contain related_item_type: 'Part' and the attribute data of batch_items[1] in related_items.

1. Backend capability-runtime.js create() method format alignment: The format conversion of relationship discovery results in the backend CapabilityRuntime.create() SHALL align with the format requirements of the frontend useCapabilityCreate.

a. Acceptance Condition: When the backend CapabilityRuntime.create() calls discoverRelations() to obtain relationship data, the returned discoveredRelations (in source_index/target_index format) SHALL be converted to relationship_type/related_item_type/related_items format before being passed to the AML for construction.

1. Failed conversion does not block creation: If format conversion fails, a WARNING log SHALL be recorded, the relationship skipped, and the main object creation not blocked.

a. Acceptance Condition: When a piece of relationship data returned by relationship discovery cannot be converted (e.g., index out of bounds), the system SHALL skip that relationship and continue processing other relationships and main object creation.

1. Conversion result validation: The converted relationship data SHALL pass basic format validation (relationship_type non-empty, related_items a non-empty array).

a. Acceptance Condition: When format conversion is complete, the conversion result SHALL pass validation: relationship_type must be a non-empty string and related_items a non-empty array; otherwise, skip it.

1. Prohibition: Relationship discovery results SHALL NOT be passed directly to AmlBuilder or AMLGenerator in source_index/target_index format; format conversion must be completed first.

a. Acceptance Criterion: When auditing the code path from relationship discovery to AML construction in capability-runtime.js, the relationships array passed to AmlBuilder SHALL NOT contain source_index/target_index fields.

5.3.2 Interaction Flow

@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. System Behavior: Skip the relationship and log a WARNING: "Relationship index out of bounds: index=X, batch_size=Y".

c. User Perception: The relationship is not created, while other relationships and the main object are created normally.

1. relation_type is empty

a. Trigger Condition: The relation_type field returned by relationship discovery is empty or undefined.

b. System Behavior: Skip the relationship and log a WARNING: "Relationship type is empty, skipping.".

c. User Perception: The relationship is not created.

1. Objects in batch_items are missing item_type

a. Trigger condition: The batch_items[index] object lacks the item_type field

b. System behavior: Use the primary item_type as the fallback value for related_item_type, and log a WARNING

c. User perception: Relationship creation may use an incorrect object type, requiring manual confirmation

5.4 Backend Creation Path Retry and Rollback (Medium)

5.4.1 Business Rules

1. Backend creation path retry mechanism: When applyAML fails in the backend createItem() (unified-create.js / rule-engine.js), SHALL implement retry, aligning the retry strategy with the frontend useCapabilityCreate.

a. Acceptance criteria: When the applyAML call in backend createItem() fails (network error or SOAP Fault), the system SHALL retry according to the following strategy: retry 1 time for permission errors (re-acquire token), retry 1 time for uniqueness conflicts (append suffix), and retry up to 3 times for other errors (exponential backoff).

1. SOAP Fault structured parsing: sendAML() in SCSAI-client.js SHALL parse the SOAP Fault returned by SCSAI and return structured error information.

a. Acceptance criteria: When SCSAI returns a SOAP Fault response, sendAML() SHALL parse the faultcode, faultstring, and detail fields, returning { success: false, fault: { code, string, detail } } instead of the raw XML.

1. Multi-relationship object partial failure rollback: In the backend creation path, if a subsequent step fails, SHALL roll back already created objects.

a. Acceptance criteria: When the backend creation path executes three creation steps, steps 1 and 2 succeed but step 3 fails, the system SHALL delete the SCSAI objects created in steps 1 and 2, returning { success: false, rolled_back: true, rolled_back_ids: [...] }.

1. Nested AML failure stepwise degradation: When creation of complex nested relationships fails, SHALL automatically degrade to stepwise creation.

a. Acceptance criteria: When nested AML (including item_properties + relationships) submission to SCSAI fails, the system SHALL automatically downgrade to: first create the main object (properties only), then create each item_properties child object one by one, and finally create each relationship one by one.

1. Timeout returns structured error: When sendAML() times out, it SHALL return a structured error instead of throwing an exception.

a. Acceptance criteria: When the sendAML() request exceeds timeout milliseconds, the return value SHALL be { success: false, fault: { code: 'TIMEOUT', string: 'SCSAI request timeout', detail: 'timeout after Xms' } } instead of throwing an Error.

1. Rollback operation audit log: Each rollback operation SHALL record an audit log, including operation time, object ID, and rollback reason.

a. Acceptance criteria: When the system performs a rollback to delete created objects, the audit log SHALL contain a record of { action: 'rollback_delete', item_type, item_id, reason, timestamp }.

1. Prohibition: The backend creation path SHALL NOT silently return an error without retrying after applyAML failure; a retry strategy aligned with the frontend must be implemented.

a. Acceptance Criteria: When auditing the backend createItem() code, the handling logic after applyAML failure SHALL include a retry mechanism, not merely logging the error and returning.

5.4.2 Interaction Flow

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

ci -> ac : applyAML(aml)
ac -> SCSAI : SOAP请求
SCSAI --> 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. System Behavior: Log a CRITICAL message (including the list of object IDs that were not rolled back), return { success: false, rolled_back: false, orphan_ids: [...] }

c. User Perception: Display the message "Partial object creation failed and rollback was incomplete, orphan objects exist," accompanied by the list of object IDs for manual cleanup.

1. Stepwise Degradation with Sub-object Creation Failure

a. Trigger Condition: After nested AML degrades to stepwise creation, a sub-object creation fails.

b. System Behavior: Skip that sub-object, continue creating other sub-objects, and finally return { success: true, partial: true, failed_items: [...] }

c. User perception: Main object and some sub-objects created successfully; failed sub-object list provided for manual completion.

1. SCSAI unavailable during retry.

a. Trigger condition: SCSAI server remains unavailable during retry.

b. System behavior: After 3 retries, abort and return structured error { success: false, fault: { code: 'SCSAI_UNAVAILABLE' }, retry_count: 3 }.

c. User perception: Prompt "SCSAI service temporarily unavailable, please try again later."

1. Uniqueness conflict persists after retry suffix appending.

a. Trigger condition: item_number still conflicts with existing objects after suffix appending.

b. System behavior: Append suffix up to 3 times (-1, -2, -3). If conflict persists, abort and return error.

c. User perception: Prompt "Number conflict, please manually specify a number."

5.5 Reliability of frontend create_post rule execution (Severity: Critical)

5.5.1 Business rules

1. create_post rule execution results must be perceivable: The execution results of create_post rules triggered after successful frontend creation (e.g., subtask number completion) SHALL be perceivable by the frontend. Fire-and-forget leading to rule execution loss is not allowed.

a. Acceptance Criteria: When the frontend successfully creates an object via useCapabilityCreate and triggers the create_post rule, the frontend SHALL be able to obtain the execution result (success/failure/timeout) of the create_post rule, rather than merely triggering it without concern for the outcome.

1. create_post Rule Failure Notification: When the create_post rule execution fails, the frontend SHALL be notified, and the frontend shall display a failure prompt.

a. Acceptance Criteria: When the create_post rule execution fails (e.g., sub-task number completion fails), the frontend SHALL receive a failure notification and display a prompt stating "Object creation succeeded, but subsequent processing failed: [failure reason]".

1. create_post Rule Failure Retry: When the create_post rule execution fails, a retry mechanism SHALL be implemented.

a. Acceptance Criteria: When the create_post rule execution fails, the system SHALL automatically retry up to 2 times (with exponential backoff of 1s, 2s). If retries still fail, the frontend shall be notified.

1. create_post Rule Timeout Handling: When the create_post rule execution times out, SHALL return a timeout result instead of waiting indefinitely.

a. Acceptance Criteria: When the create_post rule execution exceeds 30 seconds, the system SHALL return a timeout result, and the front-end shall display a prompt stating 'Object creation succeeded, but subsequent processing timed out.'

1. create_post Rule Failure Does Not Affect Main Object: Failure in the execution of the create_post rule SHALL NOT roll back the already created main object.

a. Acceptance Criteria: When the create_post rule execution fails, the created SCSAI object SHALL remain unchanged, and only notify the front-end that subsequent processing failed.

1. Prohibition: The create_post rule SHALL NOT be executed in a fire-and-forget mode where results are discarded; the execution results must be accessible to the front-end.

a. Acceptance Criteria: When auditing the execution path of the create_post rule, the code SHALL include a mechanism to return the execution result to the front-end, rather than merely triggering it without handling the result.

5.5.2 Interaction Flow

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

fe -> SCSAI : /SCSAI-api/ApplyItem(aml)
SCSAI --> 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. System Behavior: Catch exceptions, log ERROR, and return { success: false, error: 'Rule execution exception', detail: exception.message }

c. User perception: Prompt "Creation successful, but subsequent processing exception," with exception details logged.

1. The SCSAI object that the create_post rule depends on does not exist.

a. Trigger condition: The create_post rule needs to query the newly created object, but SCSAI has not yet completed index updates.

b. System behavior: After 2 retries, if still failing, returns failure and prompts "Object may not have completed indexing."

c. User perception: Prompt "Creation successful, but subsequent processing failed: object not ready," suggesting manual check later.

1. create_post result cannot be delivered after frontend disconnects.

a. Trigger condition: When the user closes the page or network disconnects, the create_post result cannot be pushed to the frontend in real time.

b. System behavior: Persistently store the create_post execution result, and display unread notifications upon the user's next visit.

c. User perception: See a notification "You have N unread subsequent processing results" upon next page opening.

5.6 Synchronous maintenance of frontend and backend creation logic (Medium)

5.6.1 Business rules

1. Frontend-backend AmlBuilder output consistency check: Differences between backend aml-builder.js and frontend AmlBuilder.js outputs SHALL be detected via automated tests to prevent mirrored code drift.

a. Acceptance Criteria: When generating AML for the same set of data using the front-end AmlBuilder.js and the back-end aml-builder.js respectively, the outputs SHALL be completely identical. Automated tests SHALL detect any differences in CI.

1. Consistency Check for Front-end and Back-end Creation Logic: Any logical discrepancies between the back-end unified-create.js and the front-end useCapabilityCreate.js SHALL be detected by automated tests.

a. Acceptance Criteria: When the front-end useCapabilityCreate.js modifies the creation process (e.g., adding a retry strategy, modifying AML construction logic), the automated tests SHALL detect whether the back-end unified-create.js has been updated accordingly. If not synchronized, the CI build SHALL fail.

1. Back-end Mirror Code Change Tracking: Changes to the back-end aml-builder.js and unified-create.js SHALL be tracked in association with changes to the corresponding front-end files.

a. Acceptance Criteria: When a change is submitted to the front-end AmlBuilder.js, the CI SHALL check whether there is a corresponding change in the back-end aml-builder.js. If no corresponding change exists, a WARNING alert SHALL be issued.

1. Backend mirror code documentation: The backend aml-builder.js and unified-create.js SHALL annotate their corresponding frontend files and synchronization status in the file header.

a. Acceptance criteria: When auditing the backend aml-builder.js file, the file header SHALL contain the comments: @mirror-of src/utils/AmlBuilder.js @last-sync 2026-06-25 @sync-status synced|drifted.

1. Prohibition: The backend aml-builder.js and unified-create.js SHALL NOT be modified independently for business logic without corresponding frontend changes; business logic changes must be synchronized from the frontend.

a. Acceptance criteria: When auditing the change history of backend aml-builder.js and unified-create.js, business logic changes SHALL have corresponding change records in the frontend AmlBuilder.js / useCapabilityCreate.js.

5.6.2 Interaction Flow

@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. System Behavior: CI issues a CRITICAL level alert, tagged @sync-status drifted

c. User Perception: The development team receives a synchronization reminder and must prioritize handling backend mirror code updates

1. Inconsistent creation results due to frontend-backend logic discrepancies

a. Trigger Condition: Frontend and backend produce different AML outputs for the same object creation

b. System Behavior: Automated tests fail, highlighting the specific location and content of the discrepancy

c. User Perception: CI build fails; the development team must fix the backend mirror code

1. Drift caused by independent modifications to backend mirror code

a. Trigger Condition: Backend aml-builder.js is modified without corresponding frontend changes

b. System Behavior: CI detects the independent backend modification and issues a WARNING reminder

c. User Perception: The development team receives a reminder and must confirm whether the changes should be synchronized to the frontend or rolled back

6. Data Constraints

6.1 generate Capability Output (generated_content)

1. item_type: Required, string, SCSAI ItemType name (e.g., Part, ECO, BOM)
2. properties: Required, object, key-value pairs for ordinary properties, values are primitive types (string/number/boolean)
3. item_properties: optional, object, nested definition of Item type properties, format: { prop_name: { action, item_type, properties, id?, keyed_name? } }
4. relationships: optional, array, relationship definitions, format: { relationship_type, related_item_type, related_items: [{ properties, related_id, relItemProps }] }

6.2 Relationship Discovery Results (Before Conversion)

1. parent_index: required, integer, index pointing to the source object in the batch_items array
2. child_index: required, integer, index pointing to the target object in the batch_items array
3. relation_type: required, string, SCSAI RelationshipType name
4. properties: optional, object, additional properties at the relationship level
5. field_hint: optional, string, hint information for the relationship field

6.3 Relationship Data (Transformed, AmlBuilder Standard Format)

1. relationship_type: Required, string, SCSAI RelationshipType name
2. related_item_type: Required, string, associated object's ItemType name
3. related_items: Required, array, associated object list, each element contains properties, related_id, relItemProps

6.4 Backend Creation Path Retry Strategy

1. Permission error: Retry 1 time (retry after re-acquiring SCSAI token)
2. Uniqueness conflict: Retry 1 time (append suffix '-1' to item_number)
3. Uniqueness conflict (still conflicts after appending): Append up to 3 times (-1, -2, -3)
4. Network error/Timeout: Retry up to 3 times, exponential backoff (1s, 2s, 4s)
5. Other SOAP Fault: No retry, return structured error directly

6.5 Rollback Constraints

1. Trigger condition: Any create step fails in the backend creation path and subsequent link steps exist
2. Rollback scope: All successfully created objects (list of IDs in createdIds)
3. Rollback operation: Send AML for each created object
4. Rollback timeout: A single rollback operation times out after 5 seconds; a CRITICAL log is recorded upon timeout.
5. Partial rollback failure: Record the list of orphaned object IDs that were not rolled back, returning the orphan_ids field.

6.6 create_post Rule Execution Constraints

1. Timeout: A single create_post rule execution times out after 30 seconds.
2. Retry count: Maximum of 2 retries with exponential backoff (1s, 2s).
3. Failure impact: create_post failure does not roll back the main object; only the frontend is notified.
4. Result persistence: create_post execution results are persistently stored; they can be re-sent after frontend disconnection.
5. Audit log: An audit log is recorded for every create_post execution (success/failure/timeout).

6.7 Frontend-Backend Mirror Code Synchronization Constraints

1. Synchronization check frequency: CI checks frontend-backend mirror code consistency on every build.
2. Sync timeout alert: If the backend does not sync within 7 days after a frontend change, a CRITICAL alert is issued.
3. File header annotation: Backend mirror files must be annotated with @mirror-of, @last-sync, @sync-status.
4. Independent modification detection: When backend mirror code is modified independently for business logic, CI issues a WARNING.