BossAgents SQLite 数据库总览与一致性规范

修订：2026-08-30（基于 scripts/_db_inventory.cjs 实测，取代 2026-08-05 旧版）

实测方式：node + node:sqlite 只读打开各库 PRAGMA table_info / sqlite_master

⚠️ docs/DATABASE_ARCHITECTURE.md（2026-07-06）已严重过时，以本文为唯一权威。

🔧 表定义真相源已统一：server/db/schema-registry.generated.json（自动实况）+ server/db/schema-classification.json（库职责/PLM 分类/去重归属），由 scripts/gen-schema-registry.cjs 生成、由 ensure-schemas.js 重放建表。本文与 schema-registry.generated.md 均由这两份派生，详见 docs/DATABASE_MANAGEMENT_PLAN.md。

0. 核心结论（先看这段）

1. 本系统数据库是"多库并存 + 表重复 + 建表散落"的混乱状态，不是"一个统一库"。
2. 真正的对象模型真相源在 PLM（114 SCSAI），本地所有 SQLite 都是缓存/派生/本地业务数据。
3. 最致命风险 = 表定义丢失或不一致：建表语句散落在 aml.js / dashboard-sync.js / ai-inspector.js 等模块，会落错库、不补列；且 .gitignore 用 *.db 全局忽略，几乎所有运行库不入库，换电脑重跑即丢表定义。
4. 已发生的同类事故：risk_alerts 缺 related_item 列、inspection_logs 缺表（aml 建到别库、ai-inspector 读不到）。根因都是"没有集中的 schema 真相源"。

1. 运行态库清单（50 个，已排除打包副本/快照/临时库）

按角色分组。括号内为实测 [大小 | 表数]。

1.1 核心统一库（职责重叠，需治理）

| 库 | 位置 | 实测 | 作用 | PLM 对应 |

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

| core_runtime.db | server/data/ | 35MB / 140表 | 最大库，含 SCSAI/Aras 同步缓存、sciot 元数据镜像、巡检、业务表（BOM/订单/质量/文档等） | 混合：PLM 缓存 + 本地业务 |

| rule_engine.db | server/data/ | 30MB / 64表 | 规则引擎(sciot_rules_v2)、数字员工(digital_staff)、巡检(inspection_)、sccapp 镜像、协作(plm_collab_) | 混合：PLM 缓存 + 本地 |

⚠️ 两库都建了 sciot_item_types/sciot_properties/sciot_relationships/inspection_logs/inspection_issues —— 重复建表，来源/数据不一致的根源。

1.2 PLM 镜像 / 主数据缓存

1.3 业务 / 租户 / 用户库（纯本地）

1.4 遥测 / 分析 / 反馈（纯本地）

1.5 质量（纯本地）

1.6 行业知识库（纯本地，按行业分库）

1.7 企业私有

1.8 空壳 / 疑似废弃（建议清理）

| 库 | 实测 | 说明 |

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

| aml_store.db | 0表 | 设计存 AML 对象，从未写入 |

| digital-staff.db | 0表 | 数字员工数据实际在 rule_engine.db.digital_staff |

| aml_asset_library.db | 0表 | 见 1.2，原数据已迁走 |

| server/data/tenants/lru_verify_*.db（20个） | 0表 | 临时 LRU 验证库，应清理 |

打包副本 release8/win-unpacked/resources/databases/ 与 bossagents-miniapp/data/ 是构建产物/小程序端，非源，不在治理范围。

2. 与 PLM 的对应关系（怎么保证一致性）

原则：PLM(114 SCSAI) 是唯一真相源；本地 SQLite 只做缓存 / 派生 / 本地业务。

| 数据类型 | 真相源 | 本地缓存位置 | 一致性机制 |

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

| 对象类/属性/关系/生命周期（元模型） | PLM ItemType | sciot-metadata.db（主） + core_runtime/rule_engine（副本） | 启动时 template-sync 同步；本地副本为只读镜像 |

| 工艺规程(BOM/工序/工步/技术数据) | PLM | sccapp_process_data.db | 同步脚本；本地为快照 |

| 业务对象(Part/文档/变更等) | PLM | core_runtime.SCSAI_items / aras_items | 同步缓存 |

| 数字员工/规则/巡检结果 | 代码定义 + PLM | rule_engine.db / core_runtime.db | 代码生成 + 本地持久化 |

| 租户/用户/订单/反馈/质量卡 | 无 PLM 对应 | 各自本地库 | 纯本地，无 PLM 同步 |

当前一致性缺口：

• 元模型在 sciot-metadata.db（全量 1217 类型）与 rule_engine.db（部分）与 core_runtime.db（部分）三处都存在，且未强制同步。
• 巡检表 inspection_* 在 rule_engine 与 core_runtime 都建，ai-inspector 实际读 rule_engine 但建表逻辑在 aml.js 走的是另一个连接 → 缺表报错。

3. 表定义一致性风险（最要命的部分）

3.1 根因

1. 多库重复建表：同一批 sciot_ / inspection_ 表在 core_runtime 与 rule_engine 都建，无"库→职责"单一映射。
2. 建表语句散落各模块且会落错库：

• aml.js:168 在"统一数据库初始化"分支里 CREATE TABLE inspection_logs/inspection_issues，但落到哪个库取决于 aml 的 dbManager，与 ai-inspector 的 getDb() 不一致。
• dashboard-sync.js:35 的 risk_alerts 按旧 6 列建，CREATE IF NOT EXISTS 不补列，4 处代码用了第 7 列 related_item → 报错。
• 各 router 各自 CREATE TABLE IF NOT EXISTS，没有统一入口。

1. .gitignore 几乎把所有运行库排除出库：

   *.db                      # 全局忽略
   **/rule_engine.db         # 具体排除
   server/data/core_runtime.db
   server/data/sciot-metadata.db
   server/data/boss_analytics.db
   ...（bossagents.db / feedback.db / digital-staff.db 等全排除）
   

→ 换电脑/分支切换时，库的表定义和数据都不在版本控制里，只能靠运行期散落建表"碰运气"，丢了就丢、错了就错。

1. 双引擎 WAL 分裂：服务端用 better-sqlite3、脚本用 node:sqlite，并发写同一库会产生 -wal/-shm 分裂，导致"建了但另一连接读不到"。

3.2 已发生的事故（同根因）

4. 一致性保障方案（建议，待实现）

按"先方案后实现"原则，以下为方案，代码落地待确认。

4.1 集中 schema 真相源（首要）

新建 server/db/schema-migrations.js：

• 每个库一组 migrations：[{ up: 'CREATE TABLE IF NOT EXISTS ...' }, { up: 'ALTER TABLE x ADD COLUMN y' }, ...]
• 所有 CREATE/ALTER 从各模块收敛到此文件，模块不再各自建表。
• 导出 ensureAllSchemas()：启动时按"库→迁移列表"逐个执行，幂等、可重跑。

4.2 明确"库→职责"单一映射，消除重复

• sciot-metadata.db = 唯一元模型镜像（删 core_runtime/rule_engine 里的 sciot_* 副本）。
• rule_engine.db = 规则 + 数字员工 + 巡检（删 core_runtime 里的 inspection_* 副本）。
• core_runtime.db = PLM 同步缓存 + 本地业务表（BOM/订单/质量/文档等），不再放元模型。

4.3 把表定义纳入版本控制

• 方案 A（推荐）：*.db 仍不入库，但提交 server/db/schema-migrations.js（即表定义真相源进 Git）；运行期 ensureAllSchemas() 自动建表。换电脑拉代码即恢复表定义。
• 方案 B：关键小库（boss_tenants / bossagents / enterprise_store 等）经 Git LFS 入库，防数据丢失。
• 无论 A/B，都必须删 .gitignore 里对"库定义文件"的忽略，或改为只忽略大二进制(pps_process_data/sccapp)而保留 schema 脚本。

4.4 消除 WAL 分裂

• 统一数据库引擎（服务端+脚本都用 sqlite-compat 单例），禁止脚本侧直接用 node:sqlite 写运行库；写毕 PRAGMA wal_checkpoint(TRUNCATE)。

4.5 清理

• 删除空壳库：aml_store.db / digital-staff.db（数据在别处）/ aml_asset_library.db（确认无用后）。
• 删除临时库：server/data/tenants/lru_verify_*.db（20 个）。
• 文档对齐：本文取代 DATABASE_ARCHITECTURE.md，旧文档标注废弃。

5. 正确调用规范（沿用）

// ✅ 通过 sqlite-compat 单例（全进程一个连接，避免多连接 WAL 分裂）
const { createDatabase } = require('../sqlite-compat');
const meta = createDatabase('sciot-metadata.db');   // 元模型（唯一）
const re   = createDatabase('rule_engine.db');       // 规则/员工/巡检
const rt   = createDatabase('core_runtime.db');       // 运行时/业务缓存

// ❌ 禁止：脚本侧直接用 node:sqlite 写运行库（双引擎 WAL 分裂）
// ❌ 禁止：各模块自行 CREATE TABLE（应收敛到 schema-migrations.js）

6. 待办（按优先级）

| 优先级 | 事项 |

|---|---|

| 🔴 P0 | 落地 server/db/schema-migrations.js 集中建表 + 启动 ensureAllSchemas() |

| 🔴 P0 | 修订 .gitignore：保留 schema 脚本入库，仅排除超大二进制 |

| 🟡 P1 | 消除 core_runtime/rule_engine 重复 sciot_/inspection_ 表 |

| 🟡 P1 | 清理空壳库与 lru_verify 临时库（20+） |

| 🟢 P2 | 大库(pps_process_data/sccapp)经 Git LFS 入库防丢 |

| 🟢 P2 | DATABASE_ARCHITECTURE.md 标注废弃 |