Web端对象创建完整流程（小程序端移植参考）

文档日期：2026-06-24

目的：理清 Web 端对象创建流程，明确小程序端移植方案

一、总体架构

用户输入                                      SCSAI
  │                                             │
  ├─[Web端 useCreate.js]─┐                      │
  │  (vue composable)    │                      │
  │  7步流程镜像服务端     │                      │
  │                      │                      │
  ├─[小程序 SCSAI-create]  │                      │
  │  (vue页面)           │                      │
  │                      ▼                      ▼
  │              POST /api/unified/create  ──> SCSAIClient.sendAML()
  │              POST /api/unified/generate-props
  │              POST /api/unified/apply-aml
  │                     ▲                       ▲
  │                     │                       │
  │              ┌──────┴──────┐                │
  │              │ SQLite DB   │                │
  │              │ sciot_import.db              │
  │              │  (模板/规则/提示词)           │
  │              └─────────────┘                │
  └─────────────────────────────────────────────┘

二、数据库表结构（SQLite: sciot_import.db）

2.1 核心表

| 表名 | 用途 | 关键字段 |

|------|------|---------|

| sciot_item_types | 类型定义 | name, label, keyed_name |

| sciot_properties | 属性定义 | item_type_name, name, label, data_type, is_required, list_values, default_value |

| sciot_relationships | 关系定义 | source_item_type, relationship_name, related_item_type |

| sciot_templates | 生成模板 | item_type_name, llm_fields, auto_fields, generation_rules |

| sciot_list_values | 列表值 | list_name, value, label |

| sciot_lifecycle_maps | 生命周期 | item_type_name, name |

| sciot_sequences | 编号序列 | name, value |

| sciot_prompts | 预存提示词 | prompt_type, system_prompt, user_prompt_template |

2.2 模板（sciot_templates）内容示例

每条记录对应一个业务对象类型（如 Part, Document, ECR），包含：

{
  "item_type_name": "Part",
  "llm_fields": ["name", "description", "material", "weight", "unit_cost"],
  "auto_fields": ["item_number"],
  "generation_rules": {
    "default_permission": "标准 PLM 对象",
    "default_properties": { "classification": "Part" },
    "item_properties": {
      "ownership_id": { "target_type": "Identity", "is_mandatory": false }
    },
    "child_objects": [
      {
        "relationship_name": "Part BOM",
        "target_type": "Part",
        "is_mandatory": false,
        "llm_fields": ["name", "quantity", "unit"]
      }
    ]
  }
}

三、完整创建流程（7步）

Step 1: 获取元数据

function fetchTypeTemplateFromDb(itemType) {
  // 1. 查询 sciot_item_types
  const type = db.get('SELECT * FROM sciot_item_types WHERE name = ?', itemType)
  // 2. 查询 sciot_properties（含 list_values）
  const props = db.all('SELECT * FROM sciot_properties WHERE item_type_name = ?', itemType)
  // 3. 查询 sciot_relationships（含关联对象的属性）
  const rels = db.all('SELECT * FROM sciot_relationships WHERE source_item_type = ?', itemType)
  // 4. 查询生命周期、序列
  // 5. 查询 sciot_templates（llm_fields, auto_fields, generation_rules）
  const template = db.get('SELECT * FROM sciot_templates WHERE item_type_name = ?', itemType)
  return { item_type, properties, relationships, lifecycle, sequence, llm_fields, auto_fields, generation_rules }
}

Step 2: 属性过滤与补全（filterAndSanitize）

• 过滤系统管理字段（SYSTEM_MANAGED_FIELDS，如 id, created_on, keyed_name 等）
• 过滤计算字段（rollup_前缀、spi/cpi/rpn 等）
• 过滤 item/foreign 类型字段（后续预创建处理）
• 类型转换（boolean→'1'/'0', integer→整数, date→ISO, float→数字）
• 补充默认值（default_value + generation_rules.default_properties）
• 确保 keyed_field 有值（如 item_number 为空时自动生成 AUTO-xxx）

Step 3: Sequence 编号

• 对 data_type=sequence 或 genRules.sequence_field 的 keyed 字段
• 调用 SCSAI getNextSequence（线程安全）
• 回退方案：直接 get + edit（兼容旧版）

Step 4: 引用字段预创建（precreateItem）

• 对 item/foreign 类型的属性
• 如果有 genRules.item_properties 配置且 is_mandatory
• 先创建引用的子对象（通过 SCSAI ApplyItem）
• 或直接引用已有对象（action='get'）

Step 5: 构建 AML

function buildItemAML(data, propDefsMap) {
  // 输入: { item_type, action, properties, item_properties, default_permission }
  // 输出: AML XML 字符串
  // 示例:
  //   <Item type="Part" action="add">
  //     <name>M8螺栓</name>
  //     <item_number>M8-001</item_number>
  //     <description>304不锈钢材质</description>
  //     <ownership_id><Item type="Identity" id="xxx" action="get"/></ownership_id>
  //   </Item>
}

关键规则：

• action="add" 不带 id → SCSAI 自动生成 GUID
• 关系嵌套在 中 → SCSAI 自动处理 source_id
• 同名关系（relationship_type === related_item_type）→ 属性直接放关系 Item 上
• 异名关系 → 用 包裹关联对象

Step 6: 提交 SCSAI

const mainAml = '<AML>' + buildItemAML(data, propDefsMap) + '</AML>'
const result = await SCSAIClient.sendAML(mainAml)
const createdId = extractItemId(result.items?.[0])

• 失败重试：名称重复时自动加后缀去重
• 权限错误 → World 权限重试

Step 7: 关系递归创建

• 支持 Type A：关系类型 ≠ 关联对象类型（如 Part Document → Document）
• 支持 Type B：关系类型 = 关联对象类型（如 Part BOM → Part）
• 支持多级嵌套 BOM

四、LLM 提示词生成（handleGenerateProps）

4.1 提示词来源

提示词并非每次动态构建，而是从 sciot_prompts 表读取预生成的模板（带 {{name}}、{{label}}、{{prop_count}} 等占位符），并实时填入当前类型的实际数据（字段列表、列表值、关系定义）。

4.2 提示词结构

你是 SCSAI PLM 系统的对象创建专家。
用户想要创建一个 "Part" 对象。

用户需求：创建一个名为M8螺栓的零件

== 主对象可用字段 ==
- name (string)(必填): 名称
- item_number (string)(必填): 物料号
- description (text): 描述
- material (list)(必填) [可选值: 不锈钢, 碳钢, 铝合金, 塑料]: 材料
- weight (decimal): 重量

引用类型字段：
- ownership_id → 引用类型: Identity

可用关系类型：
- Part BOM → 关联对象类型: Part
  关联对象字段: name*(string), quantity*(integer), unit(string)

请根据用户需求，生成创建该对象所需的属性值和关系配置。

返回 JSON 格式：
{
  "properties": { "字段名": "值" },
  "relationships": [
    {
      "relationship_type": "Part BOM",
      "related_item_type": "Part",
      "related_items": [ { "properties": { "name": "值" } } ]
    }
  ]
}

4.3 LLM 响应提取

多重回退解析：

1. 直接 JSON.parse()
2. markdown 代码块提取：/`(?:json)?\s([\s\S]?)`/
3. 大括号提取：/\{[\s\S]*\}/

返回：{ properties: {...}, relationships: [...] }

五、完整的请求链路

方案 A：LLM 生成属性 + 创建（两步，推荐）

请求1: POST /api/unified/generate-props
  body: { itemType: "Part", description: "创建一个M8螺栓，304不锈钢" }
  → 服务端: fetchTypeTemplateFromDb → 构建提示词 → LLM → JSON解析
  → 返回: { properties: {name:"M8螺栓", material:"不锈钢", ...}, relationships: [...] }

请求2: POST /api/unified/create
  body: { itemType: "Part", properties: {...}, relationships: [...] }
  → 服务端: 7步流程(过滤→序列→预创建→构建AML→提交SCSAI→关系创建)
  → 返回: { id: "xxx", itemType: "Part", properties: {...}, steps: [...] }

方案 B：本地 AML 构建 + 轻量提交（替代方案）

请求1: POST /api/unified/generate-props（同上）
请求2: 本地 AmlBuilder.buildAML() → POST /api/unified/apply-aml
  body: { aml: "<AML>...</AML>", itemType: "Part" }
  → 服务端: 仅 SCSAIClient.sendAML(aml) — 跳过 7 步流程
  → 返回: { id: "xxx", itemType: "Part" }

六、小程序端移植方案

6.1 直接复用服务端 API（最小改动，当前状态）

小程序端继续保持：

• POST /api/unified/generate-props 获取 LLM 生成的属性
• POST /api/unified/create 执行完整 7 步创建
• AmlBuilder.js + amlHelper.js 已复制到 src/utils/

6.2 本地化 SCSAI 调用（理想方案）

需要完成的工作：

| 模块 | 状态 | 说明 |

|------|------|------|

| src/utils/AmlBuilder.js | ✅ 已复制 | JSON → AML XML |

| src/utils/amlHelper.js | ✅ 已复制 | 系统字段过滤、校验 |

| src/api/unified-create.js | ✅ 已更新 | 含 createLocal() 方法 |

| 服务端 apply-aml 端点 | ✅ 已添加 | POST /api/unified/apply-aml |

| 本地序列号获取 | ❌ 需增加 | SCSAI getNextSequence 的 HTTP 代理 |

| 本地 item/foreign 预创建 | ❌ 需增加 | 先创建引用对象再提交主对象 |

| 本地关系递归创建 | ❌ 需增加 | 本地 buildRelationshipsAML |

| 规则模板读取 | ❌ 需加 API 代理 | 小程序端需 GET 读取 sciot_templates |

6.3 前端 + 服务端混合方案（推荐过渡）

小程序端: generate-props → LLM 生成属性
小程序端: 本地 AmlBuilder + 本地预处理（序列号API / 预创建API）
小程序端: 本地 buildRelationshipsAML
小程序端: apply-aml → 服务端仅转发到 SCSAI

这个方案让小程序端承担了步骤 1、2、3、5、7 的 JSON 处理逻辑，服务端只做：

1. generate-props — 模板→提示词→LLM（必须服务端，因为 LLM 在服务端）
2. apply-aml — 转发 AML 到 SCSAI
3. 序列号获取 — 代理 SCSAI getNextSequence
4. 预创建引用对象 — 代理 SCSAI ApplyItem（新建引用对象）