数据库统一管理方案（文档统一 + PLM 分类 + 管理功能）

状态：方案（待拍板后实现）

日期：2026-08-30

依据：代码调研（Explore agent）+ docs/DATABASE_GUIDE.md（现状基线）+ 用户指令

目标：保证数据库一致性——①文档/表定义统一去重 ②明确 PLM 对应关系 ③在系统管理里"管起来"（查看/云端下载/PLM 同步，可单向可双向）

0. 现状基线（已查清的硬事实）

0.1 现有后端骨架（可复用，不必从零）

server/routes/platform-asset.js（已挂载 /api/platform、/api/db-datasource、/api/db-metadata、/api/db-sync、/api/db-mapping、/api/unified-assets）已实现：

• GET /api/platform/databases —— 扫描 data/ 列出所有 .db（含大小、描述）
• GET /api/platform/databases/:name/tables —— 读 sqlite_master 返回表名 + 建表 SQL + 行数
• GET /api/platform/databases/:name/download —— 以附件下载 .db
• /api/db-datasource（数据源 CRUD+测试）、/api/db-metadata（元数据/列采集）、/api/db-sync（数据同步）、/api/db-mapping（表→对象映射）
• 支撑：server/services/db-metadata-collector.js（~1050 行，连接器工厂 + 元数据/行数采集 + 表→ItemType 映射）

前端：src/views/DatabaseManager.vue（路由 /database-manager，导航组"集成与日志"）已能列表/看表/下载；src/views/DataCollectionView.vue（/metadata-collection）是数据源/元数据/映射/同步向导。

已有集中建表入口（但只管自己库）：server/database1.js(DatabaseManager)、server/services/db-schema-init.js、server/db/migrations/v2_incremental.js、server/db/dialect.js（SQLite/MySQL 方言）。

0.2 现存缺口（即本次要补的）

1. 表定义无统一真相源：全仓 server/ 下 ~90 处 CREATE TABLE 散落各模块；core_runtime.db(140表) 与 rule_engine.db(64表) **重复建了 sciot_ / inspection_ 一批表；会落错库、不补列（已发事故：risk_alerts 缺列、inspection_logs 缺表）。
2. PLM 对应关系无分类：哪些表必须有 PLM、哪些本地-only、同步方向如何——全在项目成员脑子里，无记录。
3. 无"云端下载/恢复"：唯一"下载"是本地文件下载；无 OSS/COS/远程快照拉取。
4. PLM 同步状态不可见：同步逻辑散落（sccapp-sync-service、sync-SCSAI-meta、staff-persistence 等），无统一调度/状态面板；DatabaseManager.vue 不展示"是否 PLM 镜像/最后同步时间/差异"。
5. .gitignore 用 *.db 全局忽略 → 表定义随 .db 不入库，换电脑重跑即丢定义。

1. 统一 Schema 注册表（文档统一 + 去重复）

1.1 设计原则：注册表 = 单一真相源，且"生成+策展"双层，杜绝文档与实况漂移

• 生成层（自动）：脚本扫描所有运行态 DB 的 sqlite_master / PRAGMA table_info，产出机器可读的当前实况 server/db/schema-registry.generated.json（库→表→列名/类型/约束/行数/所属文件）。
• 策展层（人工维护）：server/db/schema-classification.json 叠加每张表的权威归属与分类：ownerDb（消除重复，重复表只留一个 owner）、plmClass、syncDirection、category、description。
• 人读文档 docs/DATABASE_GUIDE.md 改为由这两份 JSON 渲染生成**，不再手维护 → 永远不漂移。

1.2 去重复：明确"库→职责"单一映射（提案，待你确认）

| 库（唯一职责） | 拥有表（owner） | 需从其他库清除的重复表 |

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

| sciot-metadata.db | 元模型镜像：sciot_item_types/sciot_properties/sciot_relationships/sciot_templates/sciot_lifecycle_maps | 删 core_runtime/rule_engine 中的 sciot_* 副本 |

| rule_engine.db | 规则+数字员工+巡检：sciot_rules_v2、digital_staff、inspection_logs/inspection_issues、sccapp_（工艺缓存） | 删 core_runtime 中的 inspection_ 副本 |

| core_runtime.db | 运行时/业务缓存+本地业务：SCSAI_items/aras_items/pps_*、订单/BOM/质量/文档业务表 | 不再放元模型/巡检 |

| sccapp_process_data.db | 工艺主数据镜像（唯一） | — |

| 本地业务库（boss_tenants/bossagents/feedback/quality_/kb//enterprise_store/boss_analytics） | 各自表 | — |

这一层"谁拥有哪张重复表"是关键决策点，下面会请你确认。

1.3 注册表文件落地

• 新增 scripts/gen-schema-registry.cjs：扫 server/data/*.db（排除 release8/小程序端/快照/临时库），写 server/db/schema-registry.generated.json。
• 新增 server/db/schema-classification.json：人工策展层（首次由脚本从 generated 派生骨架，人工填 ownerDb/plmClass/syncDirection）。
• 新增 server/db/schema-registry.js：读两份 JSON，提供 getRegistry()、getTable(ownerDb,table)、listByPlmClass()、diffAgainstLive()（运行时比对实况与注册表，发现漂移即告警）。
• 所有模块的"自建表"收敛：模块不再 CREATE TABLE，改为在 schema-classification.json 声明，由统一 ensureAllSchemas() 建表（见 §3.2）。

2. PLM 对应关系分类（必须有 PLM / 可本地-only + 同步方向）

2.1 三级分类模型

2.2 分类矩阵（提案，按库）

| 库 / 表 | 分类 | 方向 | 说明 |

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

| sciot-metadata.db / sciot_* | PLM_SOURCE | PLM→本地 | 元模型全量镜像，由 sync-SCSAI-meta 拉 |

| sccapp_process_data.db / sccapp_* | PLM_SOURCE | PLM→本地 | 工艺主数据镜像 |

| core_runtime / SCSAI_items, aras_items, pps_* | PLM_SOURCE | PLM→本地 | 业务对象同步缓存 |

| core_runtime / ARTICLE, STAFF_TASK, EXECUTION_LOG, RULE_INTERPRETATION | PLM_SHADOW | 双向 | 内容域整改后已在 PLM 建类并写回 |

| core_runtime / DIGITAL_EMPLOYEE, AGENT | PLM_SHADOW | 双向 | staff-persistence 已推 PLM |

| rule_engine / digital_staff, sciot_rules_v2 | PLM_SHADOW | 双向 | 数字员工/规则在 PLM 有对应 |

| boss_tenants / bossagents / feedback / quality_ / kb/ / enterprise_store / boss_analytics | LOCAL_ONLY | 无 | 纯本地业务/租户/知识/遥测 |

注：ARTICLE 等是本轮整改新建的 PLM 类；DIGITAL_EMPLOYEE/AGENT 前轮已推。其余本地库无 PLM 对应属既定事实。

3. 数据库管理功能设计（在"系统管理"内管起来）

3.1 入口整合

• 在系统管理下新增"数据管理"独立导航组（或并入现有 admin 体系），把现有 DatabaseManager.vue 升级为统一控制台，新增 Tab：

1. 概览：所有库卡片（大小/表数/owner 职责/PLM 分类徽标/最后同步时间/健康状态）
2. Schema 浏览：选库→树状表→列定义（来自注册表，标注 owner/分类/同步方向）
3. SQL 控制台（只读沙箱）：SELECT 白名单，禁 DROP/DELETE/UPDATE/INSERT（防误删）
4. 云端同步：从云端拉取快照并恢复（见 3.3）
5. PLM 同步：每张 PLM 类表显示方向/最后同步/差异，支持手动触发"拉/推"（见 3.4）

3.2 后端新增/扩展（server/routes/database-manager.js，挂 /api/db）

复用 platform-asset.js 现有能力，新增：

• GET /api/db/registry —— 返回统一注册表（含分类/方向/owner），前端概览与 Schema 浏览的数据源
• GET /api/db/registry/diff —— 运行时比对实况 vs 注册表，返回漂移（缺表/缺列/多余重复表）
• POST /api/db/ensure —— 触发 ensureAllSchemas()，按注册表在所有库建/补表（自愈入口，替代散落 CREATE）
• GET /api/db/plm-status —— 汇总各 PLM 镜像库最后同步时间/记录数/差异（读各 sync 服务的状态表）
• POST /api/db/plm-sync {db,table,direction} —— 触发单项 PLM 拉/推（委托现有 sccapp-sync / sync-SCSAI-meta / staff-persistence）
• ~~POST /api/db/cloud-pull~~ 云端拉取已由既有 GET /api/platform/databases/:name/download 承担（见 §3.3 勘误）
• 只读 SQL：POST /api/db/query {db,sql}（白名单沙箱）

3.3 云端下载/恢复 —— ✅ 已实现，无需新建适配层（2026-08-31 更正）

勘误：本节原判断"当前为零，需新建 cloud-snapshot.js 适配层"是错的——编写时未充分核对现有代码。

云端同步早已存在且接进产品（非文档）：

• 后端 server/routes/platform-asset.js → handleDatabaseManagerRoutes()：
• GET /api/platform/databases（列云端库）、GET /api/platform/databases/:name/download（从云端 ylxt.chat 下载 .db 到本地）、.../:name/tables。
• 桌面端 electron-app/main.js 的 db-download/db-list-remote IPC：先 https://ylxt.chat/api/platform/databases 回退 localhost:3006。
• 前端 src/views/DatabaseManager.vue 挂在 集成与日志 → 数据库管理 菜单。
• PLM 双向同步见 handleSchemaRegistryRoutes() 的 pull/sync-data 端点。
• 一键自愈入口：npm run db:bootstrap（收敛建表 → >100MB 大库经现有 download 端点拉取 → PLM 镜像库跑同步脚本 → 一致性报告）。
• ⚠️ 运维铁律：跑 sql.js 同步/维护脚本前必须先停 :3006 server（safeSaveDb 会拒绝覆盖被占用的库，防陈旧 WAL 损坏）。
• 曾按旧方案新建的 server/services/cloud-snapshot.js 平行通道已删除（与现有端点重复）。

3.4 PLM 同步引擎（统一调度 + 状态）

• 新增 server/services/db-plm-sync.js：以注册表的 plmClass/syncDirection 为驱动。
• PLM_SOURCE：只能"拉"（本地只读镜像），提供 pull(db,table) 委托现有 sync-SCSAI-meta/sccapp-sync。
• PLM_SHADOW：支持"拉+推"，push(db,table) 委托 staff-persistence/SCSAI-process-sync/content-store 等现有写回逻辑；冲突策略（PLM 优先 / 时间戳新者胜）可配置。
• 每次同步写 sync_state 表（库/表/方向/最后成功时间/记录数/差异数），供 /api/db/plm-status 与前端展示。
• 管理界面展示"哪些表从未同步/同步失败/漂移"，可手动或定时触发。

3.5 版本控制与防丢失（根治 .gitignore 问题）

• 表定义进 Git：server/db/schema-classification.json + schema-registry.js + ensureAllSchemas() 进版本控制（这些是"表定义真相源"，非二进制）。
• .gitignore 修订：保留 /.db 忽略，但显式取消对 schema 脚本/JSON 的忽略；超大二进制库（sccapp_process_data.db/大 kb/*.db）继续忽略或走 Git LFS。
• 换电脑：拉代码 → ensureAllSchemas() 自动建全部表定义 → 解决"表定义丢失/不一致"。

4. 实施阶段（待拍板后按序推进）

5. 待你拍板的关键决策

1. 去重复归属（§1.2）：确认 sciot_ 归 sciot-metadata.db、inspection_ 归 rule_engine.db、core_runtime 只留业务缓存——是否同意此单一映射？
2. ~~云端源定义~~（§3.3）：已解决——云端即 ylxt.chat 的 server/data/ 目录，经既有 platform-asset 端点同步，无需新适配器。
3. P0 是否现在开工：确认后我先落地统一注册表 + ensureAllSchemas + .gitignore 修订（P0），再继续 P1。

6. 演进：把数据库元数据本身也建模为 PLM 对象类

触发：用户决策——"既然都这样了，不如把 SQLite 数据库和表管理也作为对象类存放到 PLM 中，这样更好统一。"

这是 §2 PLM 分类模型的自然延伸：此前我们只把"业务对象"建模进 PLM；现在把"系统自身的元数据（库/表/列）"也对象化，让 PLM 成为全部对象模型（业务 + 系统元数据）的统一真相源与可关联目录。

6.1 价值（为什么更好统一）

1. 全对象模型一处可见：业务对象（Part/BOM/工艺/文章/数字员工…）与"数据库长什么样"（库/表/列）都在 PLM 里，统一检索、统一权限、统一审计、统一版本。
2. 本地表 ↔ PLM 对象双向可追溯：通过关系 R_DB_TABLE_ITEMTYPE，一张本地表能直接关联到它对应的 PLM ItemType（如 ARTICLE 表 ↔ ARTICLE ItemType），回答"这张本地表对应 PLM 哪个对象""哪些 PLM 对象还没本地表承接"。
3. 跨电脑容灾闭环：本地 .db 因 .gitignore 不入库会丢定义；现在 PLM 里常驻一份"数据库对象模型目录"，本地库丢了可据 PLM + ensureAllSchemas() 重建。
4. 符合用户铁律"基础数据模型在 PLM、对象模型驱动、关系驱动"。

6.2 对象模型（复用 PLM 既有 sjzcpt_ 数据采集中平台模型，不新建）

经核实，PLM(114) 已存在一套完整的数据采集中平台对象模型（sjzcpt_ 前缀），层级与我们的"库/表/列"一一对应：

• sjzcpt_sjy（数据源） ← 我们的 库：fdatabasename(库文件名)/fdatabasetype(SQLite)/fserviceaddr(路径)/floginaccount/fconfigpath/fgatherpath/fissynchronized/fsyncname…
• sjzcpt_ysj（元数据/源数据） ← 我们的 表：fname(表名)/fcode/fsjyobjid(→所属数据源 sjzcpt_sjy)/ftype/fdesc/forderid/fissynchronized
• sjzcpt_ysj_ysjsx（元数据属性=数据列表项） ← 我们的 列：name/ftype(类型)/fiskey(主键)/fisfkey(外键)/fismust(必填)/max_length/sort_order/sjyid(→所属表 sjzcpt_ysj)
• sjzcpt_sjytype（数据源类型字典）：fcode/fname/fparent（需确认有"SQLite"类型项）
• sjzcpt_spq（采集/数据包）：fgatherid/ftoolid

关系已内置：RelationshipType sjzcpt_ysj_ysjsx 连接 元数据↔属性；sjzcpt_ysj.fsjyobjid、sjzcpt_ysj_ysjsx.sjyid 为字段级引用。该模型已有 3 个示例实例，是可用的活模型。

方向纠正：此前本节（旧 §6.2）设计新建 DB_INSTANCE/DB_TABLE ItemType 是错的——PLM 已有等价且更完整的 sjzcpt_ 模型，应直接复用，不重复造轮子。这同时也解决了"3300 列式实例臃肿"的担忧：sjzcpt_ysj_ysjsx 本就是字段级模型，逐列写入是设计内的。

6.3 字段映射（本地 registry → PLM sjzcpt_）

6.4 现有代码已具备复用基础（无需从零）

• server/services/db-metadata-collector.js：已完整实现"采集→映射（表→ItemType/字段→Property/外键→RelationshipType）→对象化→本地落库"，且 _getSCSAIDataSourceConfig（:993）已能从 PLM sjzcpt_sjy 读回数据源配置。其本地落库表 db_datasources/db_metadata_tables/db_metadata_columns 结构可直接映射。
• server/routes/platform-asset.js：已有 /api/db-datasource、/api/db-metadata、/api/db-mapping、/api/unified-assets 路由。
• 缺口：现有代码只"本地落库 + 从 PLM 读回"，没有"把采集结果写入 PLM sjzcpt_ 模型"的反向适配器——这就是要补的。

6.5 同步方向

• 采集源 = 本地 schema-registry（generated 实况 + classification 策展）= 唯一真相源。
• 写入目标 = PLM sjzcpt_ 模型：新增 scripts/push-schema-to-plm.cjs，用 SCSAIClient.sendAML/applyItem 把 库→sjy、表→ysj、列→ysjsx 幂等 upsert（按 fcode/name 定位，update 不 delete，规避端点 delete 限制；孤儿靠 Aras 管理端清）。
• PLM 成为"数据库对象模型目录"，与业务对象（ItemType）同处一个统一真相源。

6.6 与现有体系关系（杜绝双真相源）

• 本地 registry（generated+classification）= 采集/策展真相源；sjzcpt_ 模型 = PLM 侧的"对象化登记处 + 可关联目录"。
• 流程：gen-schema-registry 生成实况 → classification 叠加分类 → 推送适配器写 PLM sjzcpt_ → PLM 统一目录。可挂启动/CI 自动跑。

6.7 实现步骤（落到 P1）

1. 确认 sjzcpt_sjytype 是否已有 "SQLite" 类型项；没有则 createItem 补一条。
2. 新增 scripts/push-schema-to-plm.cjs：getSharedClient() → 读 generated+classification → 逐库建/更 sjzcpt_sjy、逐表建/更 sjzcpt_ysj（fsjyobjid 关联）、逐列建/更 sjzcpt_ysj_ysjsx（sjyid 关联）。用 applyItem 的 where/keyed 定位做幂等。
3. （可选）为 sjzcpt_ysj 加 fplmitemtype 属性（smartRepairItemType），写入 classification.tableItemTypeMap，实现"本地表↔PLM 业务对象"标注。
4. 验证：PLM 实查 sjzcpt_sjy≥31、sjzcpt_ysj≥332、sjzcpt_ysj_ysjsx≈总列数；抽查 1 库的 ysj→sjy、ysjsx→ysj 引用链完整。

6.8 风险与约束（实测确认，重要）

• PLM sjzcpt_ 族物理表缺 SOURCE_ID/RELATED_ID 列（系统性缺陷）：经逐项实测，sjzcpt_sjy、sjzcpt_ysj、sjzcpt_ysj_ysjsx 三类的底层物理表都缺 SOURCE_ID/RELATED_ID 列，导致：
• 实例 create 成功；但创建后 edit/delete 全部报错——edit 报 列名 'SOURCE_ID' 无效，delete 报 列名 'SOURCE_ID' 无效。列名 'RELATED_ID' 无效。，关系 edit/delete 报 MissingCriteriaException。
• 推论：已建实例既不可改、也不可经 API 删（孤儿只能由 Aras 管理端或底层 DB 修正）。推送脚本一律按"查重→存在则跳过、不存在则创建"的幂等策略，绝不依赖 update/delete。
• 列是关系类型，不能独立 createItem：sjzcpt_ysj_ysjsx 是 RelationshipType（源=sjzcpt_ysj）。用 SCSAIClient.createItem('sjzcpt_ysj_ysjsx', props) 会报 The source item has to be specified in order to add a relationship.；正确做法是 sendAML 在关系项内显式带 =ysj.id 创建（已验证 OK）。查重用 过滤（自定义字段，可作查询条件）。
• sjzcpt_ 字段为 f 前缀（中文系属性），写时严格对齐字段名（已核实，见 §6.2）。

6.9 已拍板（实现细节）

• A 写入触发：手动脚本 scripts/push-schema-to-plm.cjs 一次性推（已落地）。用法：SCOPE=db,table / SCOPE=column / SCOPE=all，可加 LIMIT=n 先小批量验证。
• B 列粒度：逐列写 sjzcpt_ysj_ysjsx（已落地，见 §6.10）。
• C 表↔PLM 对象标注（部分受阻）：已给 sjzcpt_ysj 类加 fplmitemtype 属性，但因 §6.8 的 edit 缺陷，332 个已建表实例的 fplmitemtype 值无法回填（旧实例不可改/删）。实际处理：① plmClass+category+action 已写入每个表的 fdesc 文本，故"表↔PLM对象"映射在 PLM 内仍可文本检索；② classification.json 本就是该映射的唯一真相源；③ 仅 12 个表有非空 plmClass（8 个 PLM_SHADOW 如 ARTICLE/STAFF_TASK/EXECUTION_LOG… + 4 个 PLM_SOURCE/LOCAL_ONLY），其余 320 个表本就是纯本地 schema 元数据（sjzcpt_ysj 即其在 PLM 中的表示），无需单列映射。→ 结论：fplmitemtype 结构化字段对其余表非必需，映射可用性已由 fdesc + classification 保证；若要为那 12 个表补齐结构化标注，须走 Aras 管理端修正物理表或清理重推（但 delete 亦受限，故只能加列解决）。

6.10 实测落地状态（截至当前）

• ✅ sjzcpt_sjytype：已补 "SQLite" 类型项（fcode=SQLITE/fname=SQLite）。
• ✅ sjzcpt_sjy（库）：31 个本地库全部进入 PLM（与 registry 31 库一一对应；PLM 总 39 条含 8 条既有其他数据源，不冲突）。
• ✅ sjzcpt_ysj（表）：332 个本地表全部进入 PLM（核验：332/332 本地表的 fcode=库::表 均能在 PLM 查到；PLM 总 779 条含 447 条既有其他系统数据，按 fcode 隔离互不覆盖）。
• ✅ fplmitemtype 属性：已成功加到 sjzcpt_ysj 类（类级存在，待未来新建实例或管理端回填历史值）。
• ✅ sjzcpt_ysj_ysjsx（列）：3922 列全量推送完成（关系类型 + source_id 创建；SCOPE=column 实跑 ok=3916/fail=0，干跑表已建 6 列被跳过，合计 3922；PLM 我们表的列实测 3923，多 1 个调试 junk 列 _reltest_a）。PLM 现有 6329 列均为既有其他系统数据，我们的 3922 列按其所属 ysj 的 source_id 隔离。端到端核验：331/332 表列数精确匹配（唯 data/bossagents.db::changes 因 junk 列为 7 vs 6）；抽查确认列 source_id == 所属表 ysjId，引用链完整。
• ⚠️ 已知 junk：一次调试在 data/bossagents.db::changes 下留了 1 个测试列 _reltest_a（因 delete 受限无法经 API 清除，命名明显、不与真实列撞名，无害；如需清除须 Aras 管理端）。

6.11 管理控制台（基于上述建模成果补全，2026-08-30）

• 目的：把"库/表/列已建模进 PLM"这件事做成可浏览、可检索、可实时查看数据的 Web 管理功能，落在「集成与日志 / 数据库管理」模块的「元数据注册表」标签页。
• 后端 server/routes/platform-asset.js 新增 /api/platform/schema-registry*：
• GET /schema-registry → 三级树（库→表→列统计）+ 统计 chips；按 schema-classification.json 注入 role/plmClass/syncDirection/deprecated/plmSynced（注意 classification 键用 server/data/...、注册表 db.path 用 data/...，已用 normKey 归一化）。
• GET /schema-registry/columns?db=&table= → 单列级元数据。
• GET /schema-registry/data?db=&table=&limit= → 实时数据预览（sqlite-compat 只读打开真实库，表名/db 均校验自注册表，防注入/越权读）。
• POST /schema-registry/sync（后台子进程重推 PLM）+ GET /schema-registry/sync（轮询进度）。
• 前端 src/views/SchemaRegistry.vue（自包含）：库/表/列三级下钻、PLM 分类标签、实时数据预览、按名称/角色/PLM分类过滤、一键重推 PLM。挂在 DatabaseManager.vue 第三个 tab。
• 关键修复：scripts/push-schema-to-plm.cjs 的 upsert 改为存在即跳过（原 updateItem 对 sjzcpt_ 实例必失败），保证重推幂等无误报。
• 验证：node --check 通过；handler 直连真实注册表跑通 tree(31/332/3922)/columns/data；vite build 成功。运行中的 server.js 需重启才加载新路由（前端 dist 已重建）。