别再让“Unknown”搞砸你的产品数据：一次关系链修复的实战复盘

# 别再让“Unknown”搞砸你的产品数据：一次关系链修复的实战复盘 ## 开篇：一个“Unknown”引发的灾难 想象一下这个场景：你的产品经理在系统中创建了一个新产品，信心满满地点击“保存”，结果前端页面立刻报错——404。排查半天，发现系统里多了一个 `type="Unknown"` 的幽灵节点，它像病毒一样蔓延，导致产品与型号的关系断裂，后续所有关联查询全部失效。 这不是科幻片，这是我们刚刚真实踩过的坑。更让人头疼的是，这个问题不是偶发，而是每次创建产品都会稳定复现。团队花了整整两天，从数据库到前端代码，再到服务端持久化机制，层层剥茧，才揪出真正的元凶。 如果你也遇到过类似问题——数据莫名其妙丢失、关系链断裂、重启后问题复现——这篇文章或许能帮你省下几个通宵。 ## 现象：从一次“正常”的产品创建说起 我们的系统支持创建产品时附带型号（Model）关系。前端通过 `useCapabilityCreate` 这个组合式函数来发起请求。按理说，一切应该顺滑：你填好产品信息，勾选型号，提交，系统自动建立关联。 但现实是，当你创建产品时，系统会生成一个 `Model` 关系，但关系类型字段 `related_item_type` 却变成了 `'Unknown'`。这个 `Unknown` 随后会被解析成 `` 这样的非法 AML 节点，导致前端渲染崩溃、后端接口返回 404。 更诡异的是，这个 `Unknown` 不是每次都有，而是 **稳定复现**——只要创建产品，必出问题。 ## 根因链：一个空字段引发的连锁反应 我们花了整整一天来定位问题，最终梳理出一条清晰的因果链： ### 第一环：数据库里的“空心”关系 问题出在本地数据库 `rule_engine.db` 中的 `sciot_relationships` 表。这张表里存储了所有 ItemType（如 Product、Model）之间的关系定义。我们检查发现，`Product→Model` 这一行记录的 `related_item_type` 和 `relationship_item_type` 两个字段都是空的。 为什么是空的？因为原始数据源（一个 JSON 文件）中就没有填充这两个字段。数据缺陷从这里开始。 ### 第二环：前端的“善意”兜底 前端代码 `useCapabilityCreate.js` 的第 528 行，有一段逻辑：当 `related_item_type` 为空时，代码会 fallback 到一个默认值 `'Unknown'`。这原本是为了防止程序崩溃而设计的“安全垫”，但在这里，它成了帮凶。 代码逻辑是这样的： ``` if (related_item_type 为空) { related_item_type = 'Unknown'; } ``` 于是，每个空的关系都被赋予了一个 `Unknown` 标签。 ### 第三环：类型判断的“误判” 系统中有两种关系类型：Type A 和 Type B。判断逻辑是 `isTypeB = relationship_type === related_item_type`。当 `related_item_type` 为空时，这个比较变成了 `'Model' === ''`，结果为 `false`，所以系统认为这是 Type A 关系。 Type A 关系会生成 `` 这样的节点。而 Type B 关系（如 Model 关系）本应生成 ``。这一误判直接导致了非法 AML 的产生。 ### 第四环：数据库持久化的“陷阱” 找到问题后，我们尝试直接修改数据库文件，把空的字段填上正确值。但重启服务器后，问题又回来了。为什么？ 因为 `server.js` 启动时有一个逻辑：如果 `sciot_item_types` 表为空，它会从 `generated/full-aml-extract.json` 这个全量 JSON 文件重新同步所有类型数据。而旧服务器进程退出时，sqlite-compat 的 exit 处理器会把内存中的状态（298 个类型）写回文件，覆盖我们手动做的修复。 换句话说，**直接改数据库文件是没用的**——只要服务器重启，你的修改就会被覆盖。这是一个典型的“持久化陷阱”。 ## 修复：两阶段协作，彻底解决问题 我们采取了两个阶段的修复方案，一个治标，一个治本。 ### 阶段A：数据源的“手术级”修复 我们写了一个专门的修复脚本 `sync-rels.mjs`。这个脚本有几个关键设计： **1. 绕过代理层，直连数据库** 我们使用 `sqlite-compat` 直接连接数据库，绕过了 `db-adapter` 代理层。为什么？因为代理层在快速退出时，`save()` 函数的防抖机制可能不会触发，或者代理分裂导致修改丢失。直连可以确保每次写入都立即生效。 **2. 从真实 SCSAI 系统拉取权威数据** 我们没有自己编造数据，而是从真正的 SCSAI 系统中拉取了 600 条关系记录，作为权威数据源来回填本地数据库。具体修复内容包括： - 回填 `related_item_type`：从 431 个空值减少到 117 个空值（覆盖了核心业务关系） - 插入缺失的 ItemType：311 个新类型，总数从 298 增加到 609 - 校正 6 个 `is_relationship` 标志位 **3. 安全的落盘机制** 我们改用 `db.close()` 方法（内部执行 export + writeFileSync）来确保数据完整写入磁盘。修复完成后，用独立进程验证数据完整性：确认 609 个类型、117 个空值、Model 类型存在。 **4. 关键操作步骤** 修复后，必须**关闭所有 server 进程再启动**。如果有一个旧进程还在运行，它的 exit 处理器会在退出时把旧数据写回，覆盖我们的修复。这一点非常重要。 ### 阶段B：前端的“防火墙”兜底 数据层修复后，我们还需要给前端加一道防火墙。在 `useCapabilityCreate.js` 的第 528 行，我们增加了第二个 fallback：当 `related_item_type` 为空时，使用 `r.name`（关系名称）作为兜底值。 为什么这个有效？因为对于 Type B 关系（如 Model），关系名称本身就是 ItemType 的名称。所以 `r.name` 就是 `'Model'`，这能确保即使数据库里还有残留的空字段，前端也不会再生成 `Unknown`。 ## 验证：在真实 SCSAI 上跑通全链路 修复完成后，我们在真实 SCSAI 系统上做了端到端验证： **接口验证：** - `GET /api/sciot/type-template/Product` 返回 `Model→related_item_type=Model` - `GET /api/sciot/type-template/Model` 返回 `is_relationship=1` **创建验证：** - 调用 `POST /api/unified/create` 创建产品（含 Model 关系） - 返回体确认 `含 type="Unknown": false` - 直连真实 SCSAI 查回，确认 Product 对象下有 `` 节点，类型为 `type="Model"` - Model 对象真实创建并链上（name=验证车型_1783613355657） **关键发现：** 早期测试中，我们曾因请求体误用 `properties` 字段（正确字段是 `related_items`）导致关系未落库，误判为 server 漏建关系。改用正确契约后，关系完整落库，证明非 server bug。 ## 残留问题：117 个“顽固分子” 虽然核心 6 类业务关系（Project/Product/Part/Vendor/Customer/ECN）已全部覆盖，但仍有 117 行 `related_item_type` 为空。这些主要是 `z_*` 子系统或文档层级的关系，因为本地 name 写法与 SCSAI 关系名不匹配。不过，由于前端的 `r.name` fallback 机制已经覆盖，这些残留不会产生 `Unknown`。 ## 工具沉淀：可复用的修复脚本 我们保留了以下工具，方便后续维护： - `sync-rels.mjs`：可重跑的修复脚本，用于数据回填 - `verify-capability-line.mjs`：能力线验证脚本 同时，我们清理了本次诊断用的所有 probe/sr 脚本，保持代码库整洁。 ## 总结：BossAgents 能为你做什么？ 这次修复经历告诉我们，企业级系统的数据问题往往不是单一原因造成的，而是多个环节的“小问题”叠加成“大灾难”。从数据库的空字段，到前端的善意兜底，再到服务端的持久化陷阱，任何一个环节的疏忽都可能导致生产事故。 作为 **BossAgents（左帮右臂）** 智能体公司，我们专注于帮助企业解决这类复杂的技术问题。我们的智能体能够： - **自动化根因分析**：快速定位数据链断裂的根本原因 - **智能修复方案**：提供可重跑的修复脚本，避免手动操作风险 - **端到端验证**：在真实环境中验证修复效果，确保全链路工作正常 - **知识沉淀**：将每次修复经验转化为可复用的智能体能力 如果你的系统也遇到类似的问题——数据不一致、关系链断裂、重启后问题复现——不妨联系我们。BossAgents 的智能体团队，随时准备为你“左帮右臂”，让技术问题不再成为业务发展的绊脚石。