Architecture Bottom Line and Delivery Acceptance SLA

This document is the authoritative statement of the architectural red lines and hard delivery acceptance criteria for SCSAI PLM / BossAgents.

Origin: The team reviewed the article "1.5 Years in Agent Development, 20 Commercial Projects, Telling the Unspoken Truth".

Its three truths (① Most people oversimplify Agents, selling 'reliability' not tech; ② Framework ≠ Delivery, Three Safeguards = Mandatory internal doc citation / source links / offline run of 300 bad-case rate before launch

This document codifies our differentiated moat (three architectural bottom lines) into verifiable, auditable, code-demonstrable hard constraints.

Making 'reliability' not a slogan, but a fact reproducible in every line of code and every acceptance check.

0. Mapping to the Three Truths from the Article

1. Three Architectural Non-Negotiables

Non-Negotiable 1: Object-Model-Driven

• The single source of business truth is PLM object classes (ItemType) and AML, not the Agent's "memory" or "context".
• Agents / Digital Employees are only responsible for understanding intent → rule decomposition → generating AML → writing back to object classes via the gateway; all auditable, replayable truth resides in the object model.
• Object classes are extensible: 44 CASC211 classes prefixed with QP_, quality control card columns DIAODU/DINGE/BANZU/CHEJIAN_ZHUREN, creating shop-floor execution classes like JG_PRODUCE_TASK/JG_SD_SBD/JG_WORKING_PROC—this is essentially "extending the object model for Chinese business needs," a standard practice, not overreach.
• Violation criteria: Writing business state into Agent sessions, into pure frontend variables, into temporary tables not aligned with PLM object classes → merge not allowed.

Non-Negotiable 2: SQLite is for Backup / Cache Only, MySQL is the System of Record (SoR)

• SQLite's role: Local disk backup, offline cache, staging for capability outbox, not the System of Record source.
• The definitive compatibility layer server/sqlite-compat.js (2026-07-15, better-sqlite3 + WAL, real disk database, singleton connection, FAILFAST) replaces the old sql.js in-memory-only library (silent data loss, phantom databases).
• Tenant metadata backup server/services/tenant-db-sqlite-backup.js → data/boss_tenants.db, explicitly a backup, not the SoR.
• The System of Record (SoR) is MySQL (migration via migrate-sqlite-to-mysql.cjs; primary instances :5000 / :5001 use the MySQL engine).
• Violation criteria: Storing "real business data" only in SQLite without writing back to MySQL, or declaring SQLite as the authoritative database → Not allowed.

Baseline Three: 7 Capabilities + Import/Export + Copy/Paste = The Foundation of Business Operations

• Business operations are not completed by "generating a piece of code through dialogue," but are realized through standardized capabilities + the standardized data handling trio:

1. 7 core capabilities (see §2);
2. Import/Export (CSV / Excel / JSON / XML / txt, covering Part/Document/BOM/Vendor/Manufacturer/Customer/Project/ECO/WorkOrder);
3. Copy/Paste (AML-level buildCopyAml / buildPasteAml, via /api/SCSAI/copy-paste).

• These three constitute the "foundation of business operations." Any digital worker closed-loop must be built upon this base, not as a separate system.

2. The 7 Core Capabilities (Authoritative Definition, Code Evidence)

The authoritative count is 7 items, not the outdated "five capabilities / six capabilities" from old documents.

| Capability | Meaning | Code Location |

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

| identify | Identify / Locate objects (including the unified create entry) | server/scripts/health-check.js:147's ['identify','validate','repair','optimize','compare','generate','inspect'] |

| validate | Validate object compliance (rule engine guard) | BASE_CAPABILITIES at server/core/capability-offline-guard.js:22 |

| repair | Repair missing / illegal fields | localFix in server/core/offline-rule-fallback.js |

| optimize | Optimize (cost / supplier concentration / specification upgrade suggestions) | localOptimize in server/core/offline-rule-fallback.js |

| compare | Compare (inventory / version / BOM differences) | server/core/capability-offline-guard.js |

| generate | Generate (AML / reports / configurations) | server/routes/agent-loop.js |

| inspect | Inspect (object health / anomaly scanning) | Layer 2 connectivity in server/scripts/health-check.js |

• The unified creation action 'create' is listed alongside the above 7 items as "creation as a capability," totaling 8 BASE_CAPABILITIES.
• The old app/routes/swarm.js:49 listed only 6 items (missing validate/inspect), which is an outdated statement; e2e-business-demo.js:121 already states "7 major capabilities," refer to this article + health-check.js for the correct version.

3. Import/Export + Copy-Paste (code evidence)

4. Quantified Delivery Acceptance SLA (Hard Gate)

Corresponding post: "Script that can run offline on 300 bad cases pre-launch, with repeatable execution and CI-gate capability."

4.1 Metric Definitions

| Metric | Calculation | Gate (Acceptance Threshold) |

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

| Bad Case Rate (badCaseRate) | (Number of Bad Cases / Total Sample Count) × 100% | ≤ 4.7% → Otherwise exit 1, no acceptance allowed |

| Human Handoff Rate (humanHandoffRate) | (Number of Human Handoffs / Total Sample Count) × 100% | For observation only (not a mandatory gate), used to identify capability gaps |

| Average response latency (latencyMs) | Mean processing time per sample | For observation only, offline rule engine typically

• Bad case determination (from server/scripts/acceptance-eval.cjs):

1. Missing fields: lostFields(input, output) detects output missing existing input fields → bad case;
2. Silent pass: expect.fixOrImprove === true but output total === 0 → bad case (absolutely no "looks good" allowed);
3. Other normal outputs + clean/empty object expectation no-op → not a bad case.

• Transfer to manual review: !bad && total === 0 (no bad cases but also no automatic resolution) → transfer to manual, not counted as bad case.

4.2 Execution Method

# 默认 20 条样本（生产扩到 300 条即对应帖文"跑 300 条"）
node server/scripts/acceptance-eval.cjs

# 自定义样本集 / 阈值
ACC_EVAL_SAMPLES=server/scripts/acceptance-samples.json \
ACC_EVAL_THRESHOLD=4.7 \
node server/scripts/acceptance-eval.cjs

• 样本集：server/scripts/acceptance-samples.json（threshold: 4.7，20 条：F01–F10 fix / O11–O15 optimize / B16–B17 both / P18–P20 干净或空对象期望 no-op）。
• 生产落地时把样本集扩到 300 条即与帖文口径一致；闸门逻辑不变。

4.3 实测证据（本次交付验证）

✅ 验收通过：坏例率 0.00% ≤ 4.7%，可约验收。   (exit 0)
⏸ 人工 P20 [fix] fixes=0 improve=0   ← 干净对象正确转人工，非坏例

• 负向验证（临时构造"期望 fix 但 0 产出"样本集）：坏例率 100%、exit 1 → 证明闸门确实能拦住坏例，不是装饰。

5. 兜底纪律（"Agent 可以笨，不能疯"）

规则引擎兜底模块 server/core/offline-rule-fallback.js 顶部纪律，线上与离线验收共用同一份确定性代码：

1. Never falsify AI results: When LLM is unavailable / parsing fails, localFix / localOptimize returns ruleBased: true, frontend explicitly displays "Rule Engine" blue badge, does not impersonate AI.
2. Never silently pass: Any sample with "expecting output" yields 0 output → judged as bad case (see §4.1).
3. Never drop fields: Output must contain all existing input fields (guarded by lostFields).
4. Explainable: Each fix/optimize includes a fixSummary / optimizeSummary text description (e.g., "approx. ¥x.xx (includes n estimates, not purchase price)"), enabling human audit.

Module extraction purpose: Extract inline rules from agent-loop.js to server/core/offline-rule-fallback.js,

Share the same deterministic logic with server/scripts/acceptance-eval.cjs offline gate → byte-level consistency between online fallback and acceptance evaluation, eliminating "one set online, another for acceptance".

6. Code Evidence Mapping Summary (For Audit)

7. Acceptance Checklist (Must pass before PR / Release)

• [ ] Business truth resides in PLM object classes + AML, with no truth source being "only in Agent session / pure frontend variables" (Baseline 1)
• [ ] Real data is written back to MySQL; SQLite is only used for backup / caching (Baseline 2)
• [ ] Business operations are based on the 7 capabilities + import/export + copy-paste foundation, without creating separate systems (Baseline 3)
• [ ] node server/scripts/acceptance-eval.cjs runs successfully, bad case rate ≤ 4.7%, exit 0 (otherwise blocked)
• [ ] LLM failure paths return ruleBased: true, with no forgery, no silent passing, no missing fields (Discipline)
• [ ] Negative sample set can trigger exit 1 (Gate is effective, not a permanent green light)

This document is maintained in sync with server/scripts/acceptance-eval.cjs and server/core/offline-rule-fallback.js; any breach of a baseline is considered an architecture-level regression and must be rolled back or redone.