质量数字员工重构方案（基于 PPS / SCSAI 真实对象类体系）

状态：设计文档（v1，待评审）。依据：用户 2026-08-01 提供的「PPS 工艺系统完整对象类体系（C# 模型 + SCSAI ItemType）」+ 代码核实。

关联：docs/数字员工问题排查清单.md（「纠正（架构）」节）、MEMORY.md「PPS/SCSAI 对象类体系」节。

0. 背景与问题

原质量数字员工（QCC / CAPA / NCR / AUDIT / SPC / STAT / FMEA）的主数据路径完全没连 PLM/SCSAI：

• 读的是臆造的本地 quality_* SQLite 影子表（quality_inspections / quality_ncr / quality_capa / spc_control_limits / spc_data_points …）。
• SCSAI 仅在 pipeline identify 一步做"有 scsaiClient 才查"的兜底，默认总览/逾期/KPI 全走本地表。
• 数据书记员 DS-DATA-001（data-clerk.js）只同步 Part/Document/Vendor → SCSAI_sync_cache，不同步任何质量类 → quality_* 表无任何 SCSAI 来源。

用户判定（原话）："根本没有和 PLM 服务端有任何交互，没有使用 SCSAI 现有能力……质量过程的表虽然没有建立很好的关联关系，但是也存在，是以 CASC 开头的对象类。" GL-5.1 也自指：此前引擎发明 raw_json 存质量标记、process_templates 等不存在的表是错误。

结论：quality_* 本地表是错误抽象，必须废弃。质量员工应直连 SCSAI 查真实 ItemType + Relation 遍历组合树，写走统一创建能力。

1. 架构原则（硬性）

1. 数据源 = SCSAI（SCSAI）真实 ItemType，本地不再持有质量主数据。
2. 任意对象都能建 = 统一创建能力 CapabilityRuntime.create（域无关）：类不存在先 _ensureItemType → smartCreateItemType（建类前按 name 查重），类存在则 resolveExistence 业务对象查重（命中复用、不重复建）。不存在也不应有"质量域专属创建员工"。
3. 关系 = RelationshipCapability / RelationshipResolver（PPS 的 Relation 表 ParUID→SonUID via Type、QS 的标准 都用它）。
4. 零模拟数据、真实验证：所有查询/统计/写回走真实 SCSAI；无数据诚实报 success:false 并返回缺数详情，绝不伪造 0/green。
5. 标量提取统一：SCSAI 返回的属性值常为对象（{_: "值"} / {keyed_name} / {#text}，见排查清单 line 29），所有 worker 必须共用一个 _safeProperty(v) 抽取标量，禁止 String(v) 直接转（会出 [object Object]）。

2. 已核实的真实 SCSAI 通信层 API

来源：server/utils/SCSAI-client.js、server/core/capability-runtime.js、server/core/relationship-capability.js、server/core/relationship-resolver.js。

2.1 查询

``js

const SCSAI = require('../../utils/SCSAI-client').getSharedClient(30000); // lazy，truthy 即使未连

const res = await SCSAI.sendAML(

select="item_number,state,created_on,due_date,root_cause"

where="[state]='Open'"

maxRecords="50">created_on desc

);

// res = { success, items: [...], count, fault }

// 每个 item 的某些属性可能是对象 → 用 _safeProperty 抽取

`

• res.items 可能是非数组 → 必须 Array.isArray(res.items) ? res.items : [] 守卫（FMEA 崩溃根因）。
• 离线/未连：返回 {success:false, fault:{code:'NETWORK_ERROR'|'TIMEOUT'}} → worker 诚实报错，不退化到本地表。

2.2 创建（统一能力）

`js

const { CapabilityRuntime } = require('../../core/capability-runtime');

const rt = new CapabilityRuntime({/ applyAMLFn 由 sharedClient.sendAML 注入 /});

const r = await rt.create('NCR', { item_number:'NCR-TEST-001', state:'Open', / ... / });

// 内部：resolveExistence 查重 → _ensureItemType（类不存在建类，建类前 name 查重）→ add AML

`

2.3 编辑 / 回写

`js

// capability-runtime.js:1393 / 1419

const aml = +

${rt._escapeXml(value)};

await rt.applyAMLFn(aml);

`

2.4 关系（PPS Relation / QS Relationships）

`js

const rc = require('../../core/relationship-capability').getRelationshipCapability();

// 写关系（自带查重 + 镜像关系）

await rc.createRelation({ relation_type:'PPS_TechFile_Proc', source_id:techFileId, related_id:procId });

// 遍历关系

const rels = await rc.queryRelations(itemId, { relType:{name:'PPS_TechFile_Proc'} });

// → [{ id, source_id, related_id, related_name, sort_order, state }]

`

RelationshipResolver 提供 resolveExistence（查重）、discoverRelations、buildLinkPlan/executePlan（自动关联），可在"创建/修复"步骤复用。

3. 质量员工 → 真实 ItemType 映射表

| 数字员工 | 真实 ItemType（域） | 主要读字段 | 写回动作 |

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

| DS-NCR-001 | NCR（QS，21 类之一） | item_number/state/created_on/due_date/root_cause/related_process | 逾期清单、补 root_cause（repair） |

| DS-CAPA-001 | Quality Corrective Action（QS，即 CAPA） | item_number/state/created_on/due_date/effective_date | 逾期/未关闭清单、推进状态 |

| DS-AUDIT-001 | Audit（QS） | item_number/state/scheduled_date/completed_date | 逾期审核清单 |

| DS-QCC-001 | CASC211_JG_Q_CONTROL_CARD + CASC211_JG_EXAMINE_ITEM（MES，43 类，对应 PPS_Report） | 质控卡条目/检验项目/状态/超期停滞 | 质控卡总览、停滞预警、检验项目关联 |

| DS-SPC-001 | Characteristic（QP_Module，工序特性→SPC 监控对象）+ CASC211_JG_EXAMINE_ITEM（Cpk 候选） | characteristic 上下限/Cpk、检验项目测量值 | Cpk 监控、低 Cpk 预警 |

| DS-STAT-001 | 跨域聚合：NCR + Quality Corrective Action + Audit + Characteristic(Cpk) | 多类按日窗口统计 | KPI 看板（实时算，不读缓存表） |

| DS-FMEA-001 | DFMEA / PFMEA（QP_Module，含 FMEA 系列子对象 Action/Cause/Control/Effect/Failure Mode） | RPN=SEV×OCC×DET、high_rpn 项 | 高 RPN 预警、FMEA 动作跟踪 |

纠正旧误判（已写入 MEMORY.md）：CAPA 真实类名 = Quality Corrective Action；PFMEA 属 QP_Module（与 DFMEA 并列）；CASC211_JG_* 类真实存在（探测 0 行=类存无数据，非类不存在，未必在另一实例）。所有 SCSAI 内部属性名（如 NCR 的日期/状态字段名、Characteristic 的 Cpk 字段名）需在编码前用只读 get 探测一条真实记录确认，禁止臆测。

4. 逐员工设计

每个 worker 保留现有 pipeline/staff 框架（runStaffOnce），仅替换数据源：本地 quality_* 查询 → SCSAI.sendAML/CapabilityRuntime；统计口径全部改为对真实 ItemType 实时聚合。

4.1 DS-NCR-001（NCR，最简单、scplm 已确认有数据 NCR-0032 → 作为试点模板）

• 识别(identify)：sendAML 查 NCR，按 state + due_date 过滤。
• 统计口径：
• overdue_7days = due_date < now-7d && state='Open'（无 root_cause 或 investigating 超 14d 单列）。
• no_root_14days = state='Investigating' && created_on < now-14d && !root_cause。
• 创建(create)：当识别到 0 条 NCR 且任务要求"补数据"时，CapabilityRuntime.create('NCR', {...})（走统一能力，自动查重）。
• 修复(repair)：对 no_root_14days 项，action='edit' 回填 root_cause（需人在回路确认）。
• 比对(compare)：RelationshipResolver.compareRelations 比对同零件多版本 NCR。
• 验证断言：runStaffOnce('DS-NCR-001','',{}) 返回真实 total/overdue_7days/no_root_14days；scplm 有数据时命真实值；无连接诚实 success:false。

4.2 DS-CAPA-001（Quality Corrective Action，即 CAPA）

• 识别：查 Quality Corrective Action，按 state（Open/In Progress/Effective）+ due_date。
• 统计：overdue_count = due_date < now-30d && state != 'Closed'/'Effective'；close_rate = 已关闭/总数（STAT 复用）。
• 创建/修复：无数据则 CapabilityRuntime.create('Quality Corrective Action', {...})；逾期项 edit 推进状态。
• 关联：CAPA 通过 RelationshipResolver 关联到根因 NCR / 工艺参数（related_process）——用 RelationshipCapability.createRelation。

4.3 DS-AUDIT-001（Audit）

• 同构：查 Audit，overdue_count = scheduled_date < now-30d && state!='Completed'；创建/修复走统一能力。

4.4 DS-QCC-001（CASC211_JG_Q_CONTROL_CARD + EXAMINE_ITEM）

• 识别：查 CASC211_JG_Q_CONTROL_CARD，stale_count = 状态长期 pending 且 created_on < now-45d（超期停滞，对应旧 quality_inspections 停滞逻辑）。
• 工艺上下文（PPS 组合树）：通过 RelationshipCapability.queryRelations 沿 TechFile ─(PPS_TechFile_Report)→ Report(RT=质控卡) 反查所属 TechFile/工艺，得到零件/工序上下文（见 §6）。
• 创建/修复：无数据则 CapabilityRuntime.create('CASC211_JG_Q_CONTROL_CARD', {...})；检验项目挂 CASC211_JG_EXAMINE_ITEM 子项（createRelation）。

4.5 DS-SPC-001（Characteristic + EXAMINE_ITEM Cpk）

• 识别：查 Characteristic（QP_Module，工序特性→SPC 监控对象），取上下限/Cpk 字段 [待 probe 确认字段名]；low_cpk_count = Cpk < 1.0。
• 测量数据：CASC211_JG_EXAMINE_ITEM 的检验测量值作为 SPC 子组数据（替代旧 spc_data_points）。
• 创建：特性/检验项目缺失则 CapabilityRuntime.create。

4.6 DS-STAT-001（跨域实时聚合）

• 不再读 quality_kpi 缓存表，改为对 NCR/Quality Corrective Action/Audit/Characteristic 实时 sendAML 聚合：
• FPY / SCRAP_RATE / NCR_CLOSE_RATE / CAPA_CLOSE_RATE / CAPA_ONTIME_RATE / AUDIT_* 等 10 项 KPI。
• 红灯判定沿用 judgeLightStatus（值 < yellow 阈 → 红）。
• alert_count == redKpiCount 自洽校验保留。
• 每类查询独立 try/catch，单类失败不影响其余（返回 partial 标记），不静默吞错。

4.7 DS-FMEA-001（DFMEA / PFMEA）

• 识别：查 DFMEA/PFMEA + FMEA 系列子对象（Action/Cause/Control/Effect/Failure Mode）。
• 高 RPN：RPN = SEV × OCC × DET，high_rpn = RPN > 200；对 queryItems 返回做 Array.isArray 守卫（旧崩溃根因）。
• 环境依赖：无 SCSAI 连接 → 诚实报 success:false + "未配置 SCSAI 连接"，不退化本地。

5. PPS 组合树（Relation.Type）遍历

质量员工要拿到"工艺上下文"（零件/工序/特性），须沿真实 Relation 表组合：

`

TechFile(PPSSystem_TechFile)

─(PPS_TechFile_Proc)→ Proc(PPS_Proc, TypeID=PT)

─(PPS_Proc_Step)→ Step(PPS_Step, TypeID=ST)

─(PPS_Proc_Field)→ Field(PPS_Field, TypeID=FT)

─(PPS_TechFile_Data)→ TechData(PPS_TechData, ColumnID=CL) → Column(CL 编码定义)

─(PPS_TechFile_Report)→ Report(PPS_Report, RT) ← CASC211_JG_Q_CONTROL_CARD 对应此

─(PPS_TechFile_Resource)→ Resource

`

• 遍历实现：用 RelationshipCapability.queryRelations(itemId, {relType}) 逐级下钻；relType.name 取上表括号内 Relation 类型名（具体 Relation 类型名待只读 probe 确认，可能与括号内编码略有差异）。
• 关键编码（用于从 TechData/Field 解业务语义）：
• CL：CL000013 产品代号 / CL000015 零件代号 / CL000017 阶段标记(M·C·S·D) / CL000018 规程类型 / CL000019 规程特性(关键件·重要件·军检件·关键工序) / CL000020 图纸类型。
• FT：FT000261 工序属性(CL000029 序号·CL000030 工序名·CL000031 检验标记 关键工序·军检·三检·Z.G·强制检验) / FT000260 制造资源(CL000025 类型·CL000027 名称) / FT000393 工作中心(CL000651 代码·CL000660 名称)。

6. 废弃 quality_* 本地表的迁移策略

1. 保留表结构但不写入主数据：quality_* 仅作为可选本地缓存/审计快照（worker 读 SCSAI 后可落一份快照供离线排查），不再是查询主路径。
2. 写路径全切 SCSAI：所有"创建/修复/优化"动作经 CapabilityRuntime.create / edit / RelationshipCapability，不再 INSERT 本地表。
3. 清理：重构完成并真实验证通过后，删除 _seed_quality_data.cjs 对 quality_* 的直写（或改为"先确认 SCSAI 无数据时的本地降级镜像"，非默认路径）；_verify_quality_e2e.cjs 改为断言真实 SCSAI 返回值而非本地表。
4. ctx.db 根因修复（commit 3316526b）保留：仍注入 executionContext.db 供可选本地快照/状态用，但不再作为主数据源。

7. 验证口径（真实验证，零模拟）

• 连通性：SCSAI http://114.113.153.234/scplm（库 SCPLM，root/gyc123456;）沙箱可达，已 TCP 探通 + 只读 get 验证。
• 字段名确认（编码前必做）：对每个目标 ItemType 跑一次只读 get 单条，打印真实属性名（尤其 NCR 的日期/状态字段、Characteristic 的 Cpk 字段、CASC 的停滞状态字段、各 Relation 类型名），写入本方案附录，禁止臆测。
• 端到端（先 NCR 试点）：
• runStaffOnce('DS-NCR-001','',{}) 命中 scplm 真实 NCR 数据（total/overdue/no_root）。
• 无数据场景：CapabilityRuntime.create('NCR', {...}) 真实建 1 条（带 TEST- 前缀，跑后 清理，不留脏数据）。
• 无 SCSAI 连接：诚实 success:false + 缺数详情，不崩溃、不伪造。
• 全量后：7 员工逐个真实验证；STAT 跨域聚合自洽 alert_count == redKpiCount。

8. 实施步骤（分阶段）

9. 风险与待确认项（Open Questions）

1. CASC 数据是否在 scplm：探测返回 0 行。需确认是"数据确空"还是"需 enterprise_id/不同账号/另一 SCSAI 实例"。若确在另一实例，QCC/SPC 查询需指向对应 serverUrl+database（CAPA 已确认在 scplm 的 QS 域）。
2. PFMEA 真实类名：QP_Module 里 PFMEA 的具体 ItemType 名（可能是 PFMEA 或含前缀），待 P0 勘探确认。
3. Characteristic Cpk 字段名：Characteristic 的 Cpk/上下限属性名待 P0 勘探。
4. Relation 类型名：§5 括号内为编码，真实 Relation ItemType 名以 P0 勘探为准。
5. 创建权限：root 账号是否有在 scplm 创建/编辑 NCR/CAPA/Audit 等质量类的权限（GL-5.1 曾遇新建 ItemType 后 no default permission，需 clearServerCache()；业务对象创建一般 OK）。
6. 写入副作用：试点创建一律带 TEST- 前缀，验证后 清理，避免污染生产 PLM。

10. 附录（P0 勘探产出，逐步补全）

格式： → 真实属性名列表 + 样例值（脱敏）+ 可用 Relation 类型名。

占位：[待 P0 只读 get 探测]。

• NCR：[待 P0]
• Quality Corrective Action：[待 P0]
• Audit：[待 P0]
• CASC211_JG_Q_CONTROL_CARD：[待 P0]
• CASC211_JG_EXAMINE_ITEM：[待 P0]
• Characteristic：[待 P0]
• DFMEA / PFMEA：[待 P0]`