aps-agent/docs/product/master-data-completion-audit-2026-09-09.md

# 主数据完成度专项审查

日期：2026-09-09；当前 main 工作区。作为 application-completion-audit-2026-09-09.md 的主数据补充。

## 1. 判断

基础档案、导入、部分编辑、版本快照和审批已有实现，但尚未形成可靠、统一、方便计划员使用的主数据管理模块。最关键的问题是“显示、编辑、导入、排产消费”使用的对象不完全一致。

本次为审查，没有修改业务代码或用户数据。三个验证在内存中构造数据，并通过 tests.conftest 将所有持久化路径隔离到临时目录；没有启动用户服务或读写现场数据库。

## 2. 三个已复现的问题

| 编号 | 操作与前提 | 本次实际结果 | 含义 |
|---|---|---|---|
| MD-F01 | materials 与 flexMaterials 均有同一产品 P1，库存都是 5；调用普通物料编辑将库存改为 123 | materials.stock=123，flexMaterials.stock=5 | 普通编辑没有同步到柔性排产数据，排产可能继续使用旧库存 |
| MD-F02 | 只有 flexRoutings 中存在 CUT 工艺；master_overview 生成 FLEX-IMPORT 显示行，步骤 ID=1；按 ID 编辑工时 | routingSteps 为空；返回“工艺步骤不存在：1” | 为显示临时生成的编号不是正式可编辑对象的编号 |
| MD-F03 | 周模板明确设置 workdays=[5,6]，生成 2026-09-12 至 2026-09-13 的生产日历 | generatedCount=0，skippedWeekendCount=2 | 页面允许选周末，生成逻辑却无条件跳过周末 |

这是领域函数的直接复现，不是浏览器 E2E。MD-F01 证明当前编辑函数存在不同步；不据此声称所有导入路径都不同步，因为物料批次导入确实同时更新两套表。

代码依据：

- server/aps_domain/masterdata.py：master_overview 的 flexBom/flexRoutings 显示投影；apply_master_action 的 master.material.upsert；normalize_routing_payload；apply_calendar_week_copy。
- server/aps_domain/importers.py：apply_import_commit 对 materials 同时写普通/柔性表，设备/工艺/日历主要进入 flex 表。
- server/state/store.py：加载时存在条件性的 flex→classic 投影，不构成所有入口的持续双向同步。

## 3. 分项完成情况

| 主数据类别 | 已有能力 | 剩余缺口 |
|---|---|---|
| 工厂、车间、产线、工位 | 资源树、已有产线属性编辑、工位 CRUD | 缺统一的从零建厂配置流程；master.line.upsert 是已有产线更新，未提供同等完整的工厂/车间/产线建档链 |
| 产品、原料、半成品 | 编码、名称、规格、类型、单位、库存、采购前置期维护 | 普通/柔性编辑口径不一致；来源权威、单位换算、未知与零、外部编码映射及受控改码流程不完整 |
| 产品用料表（BOM） | 多层用料在业务分解中已有消费，页面可建头、增删明细、改用量、标关键料、快照发布/回滚 | 导入柔性 BOM 的显示投影不等于正式编辑对象；缺统一的来源/修订/生效/订单绑定语义与完整维护体验 |
| 工序和工艺路线 | 工序池、前后顺序、准备/单件时间、外协标记、路线编辑和版本快照 | 导入工艺显示与编辑脱节；普通 routingSteps 与 flexRoutings 尚未统一；设备专属工时、适用条件、来源确认需更清晰 |
| 标准工时 | 工时维护、来源标记、缺失检查、推断提示 | 模板和推断还不是工艺人员确认的正式标准；部分路径缺值时存在 1 分钟/件兜底，虽有错误/冲突提示，不能作为可信生产参数 |
| 设备与加工能力 | 普通设备 CRUD、停用、效率/产能；柔性设备可导入、看能力池、改状态/区域等 | 柔性资源主页面是只读+导入，缺完整在线维护；普通设备变更与柔性设备没有统一对象；能力、适用产品、设备工时需统一维护 |
| 模具和工装 | 模具导入、寿命显示、锁定/解锁；数据模型有设备适配关系 | 日常建档、适配设备/产品、维护和寿命标定缺统一编辑流程；快速 patch 仅覆盖状态/寿命/区域等字段 |
| 人员、班组与技能 | flexTeams 数据、班组人数/技能/覆盖工序展示；算法有人力并发约束 | 当前页面无完整班组/成员/技能维护；通用导入也未覆盖 teams；人员可用日历、请假、资格及有效期未形成完整产品流程 |
| 班次、日历、休息、维保 | 多班次、周模板、节假日、复制周、维保窗口 | 周末配置与生成矛盾；shiftCalendar/flexCalendar 分属不同入口；设备/人员特例和工厂倒班需统一核验 |
| 换型与工厂经验 | 产品族换型矩阵、部分 SOP 规则编译 | 经验提取、条件/例外、缺省时长确认、历史回放和批准后生效仍不完整 |
| 库存、预留、在途、在制 | 基础库存/在途字段，另有 MRP/供应可信性与执行记录 | 基础物料档案和动态库存应区分；缺统一真实来源、时点、仓库/批次/预留口径及外部对账；不能只按物料上的库存数代表当前可用供应 |
| 客户、供应商与外部编码 | 订单客户字段、SAP/MES/WMS 模拟或适配流程 | 不必重做 ERP 全部档案，但缺标准引用、映射与权威来源，避免按名称匹配或默认创建 |
| 导入与数据检查 | 表头识别、批次校验、错误/跳过记录、确认入库 | 不同上传/编辑入口未合并；缺统一可保存映射、逐项纠错、重复冲突处理、增量变更预览和责任人确认 |
| 版本与变更影响 | BOM/工艺发布快照、回滚、确认、审计与排产检查点 | 发布当前主要保存快照；默认路线/BOM 查询仍按 isDefault。尚未形成“草稿编辑→验证→生效范围/日期→订单引用→影响提示”的一致机制 |
| 存储一致性 | world JSON 和数据库镜像/投影、变化指纹 | WorldStore 数据库同步异常可回退 JSON，DB 有数据时启动又以 DB 投影为准。主数据发生保存失败时，缺面向用户的明确同步状态和恢复/冲突处理；本次只查代码，未做故障注入 |

## 4. 对计划员最直接的影响

1. 不确定该在哪个页面修改；同名设备或产品可能出现在不同视图和数据表。
2. 已经修改的数据未必进入本次使用的排产模型，造成“明明改了，为什么还这样排”。
3. 能看到导入结果，却不一定能原地纠错或发布其正式版本。
4. 有设备和工艺记录不代表两者能正确关联，更不代表工时、日历和材料已确认。
5. 库存未知、模板工艺和推断工时如果与正式值混在一起，会损害排产结果的可信度。

## 5. 应该形成的用户流程

界面可叫“排产资料”，内部保留标准模型。按计划员要回答的问题组织：

- 做什么：产品、订单引用、数量和交期。
- 怎么做：加工步骤、先后关系、每步工时与来源。
- 用什么料：每件用量、可替代材料和使用规则。
- 谁来做、用什么做：设备、模具、人员资格和容量。
- 什么时候能做：班次、休息、停机、维护和人员可用时间。
- 哪些必须遵守：已确认的工厂规则与例外。

Pi 数据 Agent 先读取项目资料和连接器快照，识别字段、对齐关系，生成待核对清单。对缺工时、缺能力等直接指出影响哪张订单的哪道工序；经验/规则 Agent 可提出候选，但不能把猜测直接当成正式值。

默认操作是“核对并采用本次资料”；高级页面再维护编码、映射和修订。任何采用动作都说明影响的产品、订单、现有方案，并保存可回溯版本。

## 6. 优先修复顺序和验收

1. 修复 MD-F01/F02/F03，首先证明“改了就生效、看到就能按正确对象编辑、选了周末就能生成周末班次”。
2. 明确唯一标准模型和编辑入口，固定/柔性算法改成消费该模型的不同投影；不能只给两个页面换名称。
3. 将普通/柔性导入映射到稳定对象 ID，给已有数据制定迁移、冲突核对和回退方案。
4. 补齐设备能力、模具适配、班组技能和人员日历的在线维护。
5. 分开事实数据、候选模板和临时假设；按本次订单做关联校验和确认，不用单一“可开排”掩盖缺项。
6. 把主数据修订/生效与排产版本、已发布工单和外部来源绑定；变更提供影响预览。
7. 通过统一连接器持续同步 ERP/MES/WMS 的权威数据，APS 维护自身排产补充项与经确认规则。

核心验收场景：改库存能改变缺料判断；停用设备后相关算法不再分配；改工时后新方案采用新值且历史版本不被改写；周末班次真实可排；导入工艺可原地纠错；重复导入不产生重复设备；未确认模板不会被描述为已验证工厂标准。