Quality Digital Employee Refactoring Plan (Based on PPS / SCSAI Real Object Class System)

Status: Design Document (v1, Pending Review). Basis: User-provided 'PPS Process System Complete Object Class System (C# Model + SCSAI ItemType)' dated 2026-08-01 + code verification.

Related: docs/Digital_Employee_Troubleshooting_Checklist.md ("Corrective (Architecture)" section), MEMORY.md "PPS/SCSAI Object Class System" section.

0. Background and Issues

The original Quality Digital Employee (QCC / CAPA / NCR / AUDIT / SPC / STAT / FMEA) master data path had no connection to PLM/SCSAI whatsoever:

• It read from fabricated local quality_* SQLite shadow tables (quality_inspections / quality_ncr / quality_capa / spc_control_limits / spc_data_points …).
• SCSAI was only used as a fallback in the pipeline identify step ("query only if scsaiClient exists"). Default overviews, overdue items, and KPIs all ran against local tables.
• Data Scribe DS-DATA-001 (data-clerk.js) only synchronized Part/Document/Vendor → SCSAI_sync_cache, not any quality-related data → quality_* tables have no SCSAI source.

User's assessment (original quote): "There is absolutely no interaction with the PLM server, no utilization of existing SCSAI capabilities... Although the tables for quality processes lack well-established relationships, they do exist as object classes prefixed with CASC." GL-5.1 also self-admitted: the previous engine's invention of storing quality tags, process_templates, etc., in raw_json for non-existent tables was an error.

Conclusion: The quality_* local table is an erroneous abstraction and must be deprecated. Quality staff should directly query the real ItemType + Relation combination tree from SCSAI and perform writes using the unified creation capability.

1. Architectural Principles (Mandatory)

1. Data Source = Real ItemType from SCSAI; local storage of quality master data is eliminated.
2. Any object can be created = Unified creation capability CapabilityRuntime.create (domain-agnostic): If the class does not exist, first _ensureItemType → smartCreateItemType (check for duplicates by name before creating class). If the class exists, resolveExistence checks for duplicate business objects (reuse if found, avoid duplicate creation). There should not and will not be a "quality-domain-exclusive creation employee".
3. Relationships = RelationshipCapability / RelationshipResolver (used for both the PPS Relation table ParUID→SonUID via Type and the QS standard).
4. Zero mock data, real validation: All queries/statistics/write-backs use the real SCSAI; honestly report success:false with missing data details if data is absent, never fabricate 0/green results.
5. Unified scalar extraction: Property values returned by SCSAI are often objects ({_: "value"} / {keyed_name} / {#text}, see troubleshooting list line 29). All workers must use a shared _safeProperty(v) to extract scalars; direct String(v) conversion is prohibited (to avoid [object Object]).

2. Verified Real SCSAI Communication Layer API

Sources: server/utils/SCSAI-client.js, server/core/capability-runtime.js, server/core/relationship-capability.js, server/core/relationship-resolver.js.

2.1 Query

``js

const SCSAI = require('../../utils/SCSAI-client').getSharedClient(30000); // lazy, truthy even if not connected

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 }

// Some properties of each item may be objects → extract using _safeProperty

`

• res.items may be non-array → must guard with Array.isArray(res.items) ? res.items : [] (FMEA root cause of crashes).
• Offline/Disconnected: Returns {success:false, fault:{code:'NETWORK_ERROR'|'TIMEOUT'}} → The worker reports the error honestly and does not fall back to the local table.

2.2 Create (Unified Capability)

`js

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

const rt = new CapabilityRuntime({/* applyAMLFn is injected by sharedClient.sendAML */});

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

// Internally: resolveExistence checks for duplicates → _ensureItemType (creates class if it doesn't exist, checks for duplicate name before creation) → add AML

`

2.3 Edit / Write Back

`js

// capability-runtime.js:1393 / 1419

const aml = +

${rt._escapeXml(value)};

await rt.applyAMLFn(aml);

`

2.4 Relationships (PPS Relation / QS Relationships)

`js

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

// Create relationship (with built-in duplicate check + mirror relationship)

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

// Traverse relationships

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

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

`

RelationshipResolver provides resolveExistence (duplicate check), discoverRelations, buildLinkPlan/executePlan (automatic linking), which can be reused in "create/repair" steps.

3. Digital Worker → Real ItemType Mapping Table

| Digital Worker | Real ItemType (Domain) | Main Read Fields | Write-back Action |

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

| DS-NCR-001 | NCR (QS, one of 21 categories) | item_number/state/created_on/due_date/root_cause/related_process | Overdue list, supplement root_cause (repair) |

| DS-CAPA-001 | Quality Corrective Action (QS, i.e., CAPA) | item_number/state/created_on/due_date/effective_date | Overdue/unclosed list, progress status |

| DS-AUDIT-001 | Audit (QS) | item_number/state/scheduled_date/completed_date | Overdue audit list |

| DS-QCC-001 | CASC211_JG_Q_CONTROL_CARD + CASC211_JG_EXAMINE_ITEM (MES, 43 categories, corresponding to PPS_Report) | Quality control card entry/inspection item/status/overdue stagnation | Quality control card overview, stagnation warning, inspection item association |

| DS-SPC-001 | Characteristic (QP_Module, process characteristic → SPC monitoring target) + CASC211_JG_EXAMINE_ITEM (Cpk candidate) | characteristic upper/lower limits/Cpk, inspection item measurement value | Cpk monitoring, low Cpk warning |

| DS-STAT-001 | Cross-domain Aggregation: NCR + Quality Corrective Action + Audit + Characteristic (Cpk) | Multi-category Daily Window Statistics | KPI Dashboard (Real-time Calculation, No Cached Table Reads) |

| DS-FMEA-001 | DFMEA / PFMEA (QP_Module, including FMEA sub-objects Action/Cause/Control/Effect/Failure Mode) | RPN = SEV × OCC × DET, high_rpn items | High RPN Alert, FMEA Action Tracking |

Correcting previous misinterpretations (already documented in MEMORY.md): CAPA's actual class name = Quality Corrective Action; PFMEA belongs to QP_Module (parallel to DFMEA); CASC211_JG_* classes do exist (detecting 0 rows = class exists but has no data, not class non-existence, possibly in another instance). All internal SCSAI attribute names (e.g., date/status field names for NCR, Cpk field name for Characteristic) must be verified by read-only get on a real record before coding; speculation is prohibited.

4. Per-Employee Design

Each worker retains the existing pipeline/staff framework (runStaffOnce), only replacing the data source: local quality_* queries → SCSAI.sendAML/CapabilityRuntime; all statistical definitions switch to real-time aggregation on actual ItemTypes.

4.1 DS-NCR-001 (NCR, simplest, scplm confirmed data exists NCR-0032 → serves as pilot template)

• Identify: Query NCR via sendAML, filter by state + due_date.
• Statistical scope:
• overdue_7days = due_date (items without root_cause or those in 'Investigating' for over 14 days are listed separately).
• no_root_14days = state='Investigating' && created_on.
• Create: When 0 NCRs are identified and the task requires "data supplementation," use CapabilityRuntime.create('NCR', {...}) (via unified capability, automatic duplicate check).
• Repair: For no_root_14days items, action='edit' to backfill root_cause (requires human-in-the-loop confirmation).
• Compare: Use RelationshipResolver.compareRelations to compare NCRs across multiple versions of the same part.
• Verification assertion: runStaffOnce('DS-NCR-001','',{}) returns actual total/overdue_7days/no_root_14days; when scplm has data, return real values; if no connection, honestly return success:false.

4.2 DS-CAPA-001 (Quality Corrective Action, i.e., CAPA)

• Identification: Query Quality Corrective Action based on state (Open/In Progress/Effective) + due_date.
• Statistics: overdue_count = due_date; close_rate = closed count / total count (reuse STAT).
• Creation/Repair: If no data exists, use CapabilityRuntime.create('Quality Corrective Action', {...}); edit overdue items to advance their status.
• Association: Associate CAPA to root cause NCR / process parameters (related_process) via RelationshipResolver — use RelationshipCapability.createRelation.

4.3 DS-AUDIT-001 (Audit)

• Isomorphic: Query Audit, overdue_count = scheduled_date; creation/repair follows unified capability.

4.4 DS-QCC-001 (CASC211_JG_Q_CONTROL_CARD + EXAMINE_ITEM)

• Identification: Query CASC211_JG_Q_CONTROL_CARD, stale_count = items with long-pending status and created_on (overdue stagnation, corresponding to old quality_inspections stagnation logic).
• Process Context (PPS Assembly Tree): Use RelationshipCapability.queryRelations to trace back from TechFile ─(PPS_TechFile_Report)→ Report(RT=Quality Control Card) to obtain part/process context (see §6).
• Create/Repair: If no data exists, use CapabilityRuntime.create('CASC211_JG_Q_CONTROL_CARD', {...}); attach inspection items as sub-items of CASC211_JG_EXAMINE_ITEM (createRelation).

4.5 DS-SPC-001 (Characteristic + EXAMINE_ITEM Cpk)

• Identify: Query Characteristic (QP_Module, process characteristic → SPC monitoring object), retrieve upper/lower limits and Cpk fields [field names to be confirmed via probe]; low_cpk_count = Cpk.
• Measurement data: Inspection measurement values from CASC211_JG_EXAMINE_ITEM serve as SPC subgroup data (replacing old spc_data_points).
• Create: If Characteristic/Inspection Item is missing, use CapabilityRuntime.create.

4.6 DS-STAT-001 (Cross-domain Real-time Aggregation)

• No longer read the quality_kpi cache table; instead, perform real-time sendAML aggregation for NCR/Quality Corrective Action/Audit/Characteristic:
• 10 KPIs including FPY / SCRAP_RATE / NCR_CLOSE_RATE / CAPA_CLOSE_RATE / CAPA_ONTIME_RATE / AUDIT_*.
• Red light determination continues to use judgeLightStatus (value
• Self-consistency check for alert_count == redKpiCount is retained.
• Each query type is independently try/catch; failure of one type does not affect others (returns partial flag), errors are not silently swallowed.

4.7 DS-FMEA-001 (DFMEA / PFMEA)

• Identification: Query DFMEA/PFMEA + FMEA series child objects (Action/Cause/Control/Effect/Failure Mode).
• High RPN: RPN = SEV × OCC × DET, high_rpn = RPN > 200; guard queryItems return with Array.isArray (root cause of previous crashes).
• Environment dependency: No SCSAI connection → Honestly report success:false + "SCSAI connection not configured", no fallback to local.

5. PPS Combination Tree (Relation.Type) Traversal

Quality personnel need to obtain "process context" (part/process/characteristic), must combine along the real Relation table:

`

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 Code Definition)

─(PPS_TechFile_Report)→ Report(PPS_Report, RT) ← CASC211_JG_Q_CONTROL_CARD corresponds to this

─(PPS_TechFile_Resource)→ Resource

`

• Traversal implementation: Use RelationshipCapability.queryRelations(itemId, {relType}) to drill down level by level; use relType.name to get the Relation type name from the table above (the actual Relation type name needs to be confirmed via read-only probe and may slightly differ from the code in parentheses).
• Key codes (used to interpret business semantics from TechData/Field):
• CL: CL000013 Product Code / CL000015 Part Code / CL000017 Phase Mark (M·C·S·D) / CL000018 Procedure Type / CL000019 Procedure Characteristic (Critical Part·Important Part·Military Inspection Item·Critical Process) / CL000020 Drawing Type.
• FT: FT000261 Process Attributes (CL000029 Sequence Number · CL000030 Process Name · CL000031 Inspection Mark Critical Process · Military Inspection · Triple Inspection · Z.G · Mandatory Inspection) / FT000260 Manufacturing Resources (CL000025 Type · CL000027 Name) / FT000393 Work Center (CL000651 Code · CL000660 Name).

6. Migration strategy for deprecated quality_* local tables

1. Retain table structure but do not write master data: quality_* tables serve only as optional local cache/audit snapshots (workers can save a snapshot after reading from SCSAI for offline troubleshooting), no longer the primary query path.
2. Write path fully switched to SCSAI: All "create/repair/optimize" actions go through CapabilityRuntime.create / edit / RelationshipCapability, no longer INSERT into local tables.
3. Cleanup: After refactoring is complete and fully validated, remove direct writes to quality_* in _seed_quality_data.cjs (or change it to "local degraded mirror only when SCSAI has no data," not the default path); modify _verify_quality_e2e.cjs to assert against real SCSAI return values instead of local tables.
4. ctx.db root cause fix (commit 3316526b) remains: executionContext.db is still injected for optional local snapshots/state, but is no longer the primary data source.

7. Verification criteria (real validation, zero simulation)

• Connectivity: SCSAI http://114.113.153.234/scplm (database SCPLM, root/gyc123456;) sandbox is reachable, TCP connectivity verified + read-only get validated.
• Field name verification (mandatory before coding): For each target ItemType, run a read-only get single operation, print the actual attribute names (especially date/status fields for NCR, Cpk field for Characteristic, stagnation status field for CASC, and all Relation type names), and record them in the appendix of this plan. No speculation allowed.
• End-to-end (NCR pilot first):
• runStaffOnce('DS-NCR-001','',{}) hits real NCR data in scplm (total/overdue/no_root).
• No data scenario: CapabilityRuntime.create('NCR', {...}) actually creates one record (with TEST- prefix, clean up after run, no dirty data left).
• No SCSAI connection: Honestly return success:false + missing data details, no crashes, no fabrication.
• After full deployment: 7 employees verify one by one; STAT cross-domain aggregation self-consistent alert_count == redKpiCount.

8. Implementation Steps (Phased)

9. Risks and Open Questions

1. Whether CASC data is in scplm: Probe returns 0 rows. Need to confirm if it's "data truly empty" or "requires enterprise_id/different account/another SCSAI instance". If indeed in another instance, QCC/SPC queries need to point to the corresponding serverUrl+database (CAPA confirmed to be in the QS domain of scplm).
2. PFMEA real class name: The specific ItemType name for PFMEA in QP_Module (could be PFMEA or with a prefix), pending confirmation from P0 exploration.
3. Characteristic Cpk field name: The Cpk/upper and lower limit attribute names for Characteristic are to be explored in P0.
4. Relation type name: §5 The content in parentheses is the code; the actual Relation ItemType name is subject to P0 exploration.
5. Creation permission: Whether the root account has permission to create/edit NCR/CAPA/Audit and other quality-related objects in scplm (GL-5.1 previously encountered no default permissions after creating a new ItemType, requiring clearServerCache(); business object creation is generally OK).
6. Write side effects: All pilot creations must carry the TEST- prefix. Clean up after verification to avoid polluting the production PLM.

10. Appendix (P0 exploration output, to be gradually completed)

Format: → Real attribute name list + sample values (desensitized) + available Relation type names.

Placeholder: [To be obtained via P0 read-only get detection].

• NCR: [Pending P0]
• Quality Corrective Action: [Pending P0]
• Audit: [Pending P0]
• CASC211_JG_Q_CONTROL_CARD: [Pending P0]
• CASC211_JG_EXAMINE_ITEM: [Pending P0]
• Characteristic: [Pending P0]
• DFMEA / PFMEA: [Pending P0]