SCIOT Object Creation — Field Processing Implementation Documentation

Based on SCIOT-AML-Basic-Settings-Reference.md + Code Implementation + Database Template Configuration

Last Updated: 2026-06-03

Table of Contents

1. Field Classification Framework
2. System Field List
3. Sequence Field Processing
4. Data Type Cleaning Rules
5. Relationship Object Processing
6. Template Configuration for Each Type
7. Front-end Code Field Processing Flow
8. Script Auto-generation Rules
9. Common Issues and Pitfalls

1. Field Classification Framework

Fields for each business object type are divided into three categories:

| Category | Meaning | Data Source | Validation Rules |

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

| llm_fields | Fields that can be generated by LLM | LLM infers from user description | Must pass whitelist filtering + data type cleaning |

| auto_fields | System auto-populated fields | Sequence / Default values / SCSAI server callback | Not involved in LLM generation, but front-end will supplement default values |

| system_fields | System metadata fields | Managed automatically by SCSAI | Completely excluded from front-end logic |

Classification Algorithm (batch-import-templates.js classifyFields)

Priority from high to low:

1. System fields → auto (SYSTEM_FIELDS hardcoded list)
2. **keyed and *_number → auto (auto-numbering, e.g., item_number)
3. keyed but not *_number → llm (user-provided, e.g., name)
4. readonly=1 → auto
5. item/foreign/sequence data types → auto (e.g., wbs_id, default_currency)
6. Special patterns** → auto (_id, percent_, has_change_pending, hc_copied_*)
7. All other fields → llm

Corresponding code locations

• Classification algorithm: scripts/batch-import-templates.js:172-229
• Frontend allowlist: src/views/StaffCapabilities.vue:1603-1613
• Auto fields supplement default values: src/views/StaffCapabilities.vue:1616-1638

2. System Field List

The following fields always belong to auto_fields and are not generated by LLM:

SCSAI meta fields

id, config_id, created_by_id, created_on, modified_by_id, modified_on
permission_id, keyed_name, current_state, state
major_rev, minor_rev, generation, new_version
is_current, is_released, locked_by_id, team_id
managed_by_id, owned_by_id
classification, css, not_lockable
from_project_id, from_template

编号字段（从 is_keyed 自动识别）

item_number           — Part, Document, CAD, ECR, ECN, PR, Manufacturer Part, Product
project_number        — Project
login_name            — User
pop_po_no             — Purchase Order
pop_invoice_no        — Bill Received
sop_order_no          — Sales Order
sop_invoice_no        — Tax Invoice, Commercial Invoice
stk_code              — Stock
...（所有以 _number 结尾的 keyed 字段）

特殊字段

// 前端硬编码系统字段（src/views/StaffCapabilities.vue:1194-1201）
const systemFields = [
  'id','config_id','created_by_id','created_on','modified_by_id','modified_on',
  'permission_id','keyed_name','current_state','state',
  'major_rev','minor_rev','generation','new_version',
  'is_current','is_released','locked_by_id','team_id',
  'classification','css','not_lockable',
  'managed_by_id','owned_by_id','llm_configuration','from_project_id','from_template',
  // 计算字段（只读，不能写入）
  'rollup_percent_compl','rollup_cost','rollup_hours','effort','duration',
  'wbs_number','wbs_short_name'
]

3. 编号字段（Sequence）处理

3.1 SCSAI Sequence 配置

参考 SCIOT-AML-Basic-Settings-Reference.md §3.6：

| Sequence Name | Type | prefix | initial_value | step | pad_to | suffix |

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

| Default Part | Part | - | 100000 | 1 | - | -001 |

| Default Document | Document | - | 100000 | 1 | - | - |

| CAD Document | CAD | CAD- | 0 | 1 | 8 | - |

| ECR | ECR | - | 1 | 1 | - | - |

| ECN | ECN | - | 1 | 1 | - | - |

| PR | Problem Report | - | 1 | 1 | - | - |

| Project Number | Project | - | 1 | 1 | - | - |

3.2 Frontend Sequence Retrieval Logic

Location: src/views/StaffCapabilities.vue:1506-1545

1. 对每个 keyedField:
   a. 从 generation_rules.sequence_field 取配置的 Sequence 名
   b. 无配置时从字段名推断（item_number → "{ItemType} Number"）
   c. GET Sequence → 读取 current_value
   d. current_value + 1 → EDIT Sequence
   e. 3 次重试（GET+EDIT 是独立操作，需乐观锁）
2. 成功 → 用 Sequence 值覆盖 LLM 值
3. 失败但 LLM 提供了值 → 保留 LLM 值
4. 失败且字段必填 → Generate AUTO-{timestamp} 保底值
5. 失败且字段非必填 → 删除该字段

3.3 无 Sequence 配置时的处理

• configuredSeqField 只在 generation_rules.sequence_name 存在时才匹配 keyed_field
• 如果无 sequence_name，name 等用户提供的 keyed 字段不会被误判为 Sequence 字段
• 字段值直接保留 LLM/用户提供的值（不会被删除）

4. 数据类型清洗规则

位置: src/utils/rule-validator.js:filterAndSanitize

| SCSAI Type | Cleansing Rule | Invalid Value Handling |

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

| string / text / ml_string | Keep original value | - |

| integer | parseInt() | → 0 |

| decimal | parseFloat() | Non-numeric → 0 |

| float | parseFloat() | Non-numeric → 0 |

| boolean | Yes/No/true/false/1/0 | → '1' or '0' |

| date | Keep ISO format | Keep original value |

| list | Keep string (best match with optional value list) | Keep original value |

| color list | same as above | same as above |

| item / foreign | special handling (see item_properties) | moved out of properties |

| sequence | special handling | moved out of properties |

Corresponding Code

// src/utils/rule-validator.js:185-225
function sanitizeProperties(props, propDefs) {
  for (const [key, value] of Object.entries(props)) {
    const def = propDefs.find(p => p.name === key)
    if (!def) continue
    switch (def.data_type) {
      case 'integer':
        sanitized[key] = parseInt(value, 10) || 0
        break
      case 'decimal': case 'float':
        const num = parseFloat(value)
        sanitized[key] = isNaN(num) ? 0 : num
        break
      case 'boolean':
        if (['yes','y','true','1',1,true].includes(value)) sanitized[key] = '1'
        else sanitized[key] = '0'
        break
      default:
        sanitized[key] = value
    }
  }
}

5. 关系对象处理

5.1 关系格式标准化

LLM 可能返回三种格式：

// 格式 A（标准数组）
{"relationships": [{"relationship_type": "Part BOM", "related_items": [...]}]}

// 格式 B（对象键名）
{"relationships": {"Part BOM": {"related_items": [...]}}}

// 格式 C（related_id 包装）
{"relationships": [{"relationship_type": "Part BOM", "related_id": {"id": "..."}}]}

代码统一在 StaffCapabilities.vue:1976-1991 标准化为格式 A。

5.2 Relationship Type Name Resolution

The LLM may use the full relationship display name (e.g., "ECR Affected Item → Affected Item (Affected Items)").

The code extracts the name before "→" and matches it with relTypes.

5.3 related_item_type Override

The LLM often writes related_item_type as the relationship name (e.g., "Part BOM").

The code looks up the correct target type (e.g., "Part") from relTypes and overrides it.

5.4 Sub-object Field Processing

For each sub-object in the relationship:

1. WBS Element → referenced by ID after pre-creation (cannot be created inline)
2. All types → schema based on subTypeTemplates:

• Remove fields that do not exist in the target type
• Generate fallback values for required keyed fields (AUTO-{ts}-{rand})
• Supply default values for hidden fields

6. Template Configuration for Each Type

6.1 Part

6.2 Document

6.3 ECR (Engineering Change Request)

6.4 Project

6.5 Vendor

| Configuration Item | Value |

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

| keyed_field | name |

| llm_fields | name, description, contact_name, main_phone, main_fax, address, city, address_state, zip_code, country, web_site (11 items) |

| auto_fields | state, default_currency (2 items) |

Note: The Vendor's name is both the keyed_field and an llm_field. Because title is not a *_number, the script will not classify it as auto.

6.6 Contact

6.7 Manufacturer Part

6.8 CAD Document

6.9 Product

6.10 Manufacturer

6.11 Customer

6.12 WBS Element (WBS Element)

6.13 Activity2 (Project Activity)

7. Front-end Code Field Processing Flow

Complete process (in execution order):

1. 获取 Schema（/api/aml/unified/schema/:itemType）
   ├─ properties: 所有字段定义（含 data_type, is_keyed, is_required, is_hidden, default_value）
   ├─ llmFields: LLM 可生成字段
   ├─ autoFields: 系统自动填充字段
   ├─ rules: 验证规则
   └─ template: 模板配置（generation_rules, keyed_field）

2. 构建 Prompt → 发送给 LLM
   ├─ 只包含 llmFields 中的字段
   ├─ 包含字段名称、类型、可选值（list 值）
   └─ 包含 relationship_types

3. 解析 LLM 响应
   ├─ 提取 JSON payload
   ├─ 标准化 relationships 格式
   └─ 构建 mainValues + relationships

4. 编号字段处理（keyedFields 循环）
   ├─ 有 Sequence 配置 → 获取 Sequence 值
   ├─ 无 Sequence 但 LLM 有值 → 保留 LLM 值
   ├─ 无 Sequence 且字段必填 → Generate AUTO 保底
   └─ 无 Sequence 且字段非必填 → 跳过

5. 字段过滤 + 数据类型清洗（filterAndSanitize）
   ├─ 只保留 validPropNames 中的字段
   ├─ 清洗 integer/decimal/float/boolean
   └─ 移除 null/undefined/空字符串

6. 补充 auto 字段默认值
   ├─ 有 default_value 且 LLM 未生成 → 补充
   └─ generation_rules.default_properties → 补充

7. 安全网：必填 keyed 字段缺失 → Generate AUTO 保底

8. 处理 item_properties（Item 类型字段）
   └─ 需要预创建的嵌套 Item（如 wbs_id）

9. 关系处理（每个子对象）
   ├─ WBS Element → 预创建 + ID 引用
   ├─ 移除无关字段（基于子类型 schema）
   ├─ 必填 keyed 字段 → AUTO 保底
   └─ hidden 字段 → 补充默认值

10. 规则验证（rules）
    └─ required / pattern / min / max

11. 构建 AML → Submit SCSAI

12. AI 自动纠错重试（最多 3 次）
    └─ 解析错误 → 发给 LLM 修正 → 重试

8. 脚本自动生成规则

scripts/batch-import-templates.js 自动处理 16 个核心业务类型：

Part, Product, Document, ECR, ECN,
Manufacturer Part, Manufacturer, Vendor, Customer, CAD,
Change Controlled Item, Project, Activity2,
WBS Element, Deliverable, Program

生成步骤

1. 从 SCIOT/SCIOT/{module}/Import/ItemType/{name}.xml 提取属性
2. classifyFields() → 按优先级分类 llm / auto
3. buildGenerationRules() → 检测 keyed *_number Generate sequence 配置
4. extractLifecycleStartState() → 从 Life Cycle Map XML 提取初始状态
5. 写入 sciot_templates 表（UPDATE 或 INSERT）

防止覆盖

脚本 UPDATE 时覆盖 llm_fields、auto_fields、generation_rules、keyed_field。

Manual modifications to sciot_import.db will be overwritten if the script is re-run. Solution:

• Implemented: The script's classifyFields and buildGenerationRules have been corrected to automatically generate correct values.
• Backup: sciot_import.db.backup_20260603 contains the complete data after manual adjustments.
• Save via API: The frontend has the /api/aml/sciot/update-template-fields endpoint for persistence.

9. Common Issues and Pitfalls

9.1 The name field was deleted.

Cause: name is a keyed field (is_keyed=1). The old script categorized it as an auto_field. In the code, it entered the Sequence processing branch.

Due to no Sequence configuration, it entered the else branch and was deleted.

Fix Summary:

• Script: Only categorize *_number keyed fields as auto (batch-import-templates.js:191-194).
• Code: configuredSeqField does not match keyed_field when there is no sequence_name (StaffCapabilities.vue:1493).
• Code: Retain LLM values for keyed fields without a Sequence (StaffCapabilities.vue:1583-1585).

9.2 item_number is NULL (sub-item Part).

Cause: The sub Part is created inline (via Part BOM relationship). The code does not generate an item_number for it.

Fix: In the child object processing loop, generate fallback values for all required keyed fields based on subTypeTemplates.

9.3 cost: "High" caused PropertyValueFormatException

Root cause: cost is a decimal type, but the LLM generated the string "High".

Fix: In sanitizeProperties, perform parseFloat + isNaN check for decimal/float types; set non-numeric values to 0.

9.4 ID: undefined

Root cause: parseSCSAIResponse set result.Item as an array, but the code accessed result.Item.id.

Fix: Change result.Item to a single object (items[0]), while preserving the result.items array.

9.5 Inconsistent LLM relationship format

Root cause: The LLM may return an array, an object, or a format wrapped in related_id.

Fix: The relationship normalizer handles all three formats (StaffCapabilities.vue:1976-1991).

9.6 LLM writes the relationship name for related_item_type

Root cause: The LLM does not understand the difference between related_item_type and relationship_type.

Fix: The code looks up the relationship configuration from relTypes and overwrites the LLM's value with the correct target type.

Appendix

A. Database Backup

sciot_import.db → sciot_import.db.backup_20260603 (22.8MB)

B. 相关文件清单

| 文件 | 用途 |

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

| src/views/StaffCapabilities.vue | Main creation process (field processing, relationship handling, Sequence) |

| src/utils/rule-validator.js | Data type cleaning, rule validation |

| src/utils/SCSAI.js | SCSAI API requests, XML parsing |

| src/utils/AmlBuilder.js | AML generation |

| src/utils/PromptBuilder.js | LLM Prompt construction |

| scripts/batch-import-templates.js | Template batch import |

| server/routes/aml.js | Backend API (template query/update) |

| server/routes/unified-aml.js | Unified Schema API |

| server/core/unified-schema.js | Schema Builder |

| server/data/sciot_import.db | SQLite database (templates + attributes + relationships) |

C. Reference Documents

• docs/SCIOT-AML-Basic-Settings-Reference.md — Complete reference for SCSAI basic settings