商品管理 · 需求文档（BM-01）
商品档案以 ERP 为唯一数据源，WMS 通过接口获取，不在 WMS 内手工新建或编辑基本信息；WMS 仅在自有维度（货主归属 owner_id、库内作业策略、启停状态）上做补充配置。核心约束：sku_id + owner_id 联合主键，owner_id 由 WMS 提供，基本信息只读。
模块定位
商品管理是 WMS 的主数据底座之一，维护仓储作业所需的商品档案，供入库、出库、库内、追溯、计费等模块引用。它不做商品主数据的生产方，只做 ERP 主数据的消费方与作业维度补充方。
要解决的问题
- 商品资料若在两套系统（ERP / WMS）各录各的，极易不一致，直接导致出入库错发、追溯码绑定错误、3PL 计费偏差。
- 多货主（3PL）场景下，同一 sku 可能归属不同货主，缺少 owner 维度会让库存"串货"。
- WMS 运营人员误改商品基础信息，事后无法判断以谁为准。
目标（可衡量）
- 商品主数据 100% 来自 ERP 接口，WMS 零手工录入基本信息。
- 通过 (sku_id, owner_id) 联合主键，支撑"同 sku 多货主"隔离。
- 基本信息只读、WMS 配置可编辑，权责清晰、可审计。
- 同步过程可监控、可回溯（时间、结果、失败明细）。
2.1 核心约束与设计原则
① 数据来源 —— 接口获取 ERP 商品资料。WMS 不生产商品主数据，只消费。ERP 是商品基础信息的权威源，WMS 通过接口（拉取/接收）落地。v1 默认单向同步（ERP → WMS），WMS 不回写商品主数据。
② 联合主键 —— sku_id + owner_id。sku_id 来自 ERP（商品唯一编码）；owner_id 由 WMS 侧提供，关联"货主主数据"（货主管理为独立模块）。二者共同唯一标识一条商品记录。之所以需要 owner_id：同一 sku 在不同货主名下是两条独立库存实体，必须靠 owner 区分。
③ 只读控制 —— 基本信息部分不可编辑。所有来自 ERP 的基本信息字段在 WMS 内锁定/置灰，任何界面与接口都不允许 WMS 侧直接修改；WMS 仅可维护"自有维度"配置（见 2.2）。同步时 ERP 字段自动覆盖 WMS 副本，保证与主源一致。
2.2 数据模型（联合主键 sku_id + owner_id）
商品记录以 (sku_id, owner_id) 为联合主键。字段按"可编辑性"分为三类：
| # | 字段 | 来源 / 可编辑性 | 说明 |
|---|---|---|---|
| 1 | sku_id | ERP · 只读 | 商品唯一编码，来自 ERP，联合主键之一 |
| 2 | owner_id | WMS · 只读(系统) | 货主 ID，由 WMS 提供，关联货主主数据，联合主键之一 |
| 3 | 商品名称 | ERP · 只读 | 基础信息，WMS 不可编辑 |
| 4 | 规格型号 | ERP · 只读 | 基础信息 |
| 5 | 计量单位 | ERP · 只读 | 盒 / 瓶 / 箱等，影响作业与计费 |
| 6 | 品牌 | ERP · 只读 | 基础信息 |
| 7 | 商品分类 | ERP · 只读 | 基础信息（品类/品种） |
| 8 | 条码（69 码） | ERP · 只读 | 用于扫码作业与追溯绑定 |
| 9 | 生产厂家 | ERP · 只读 | 基础信息 |
| 10 | 注册证号 / 国药准字 | ERP · 只读 | 药品属性，追溯合规需要 |
| 11 | 包装层级 | ERP · 只读 | 单品 / 中包 / 箱，决定拣货与追溯粒度 |
| 12 | 效期管理 | ERP · 只读 | 是否管效期、保质期天数（药品强相关） |
| 13 | 批号管理 | ERP · 只读 | 是否按批管理 |
| 14 | 重量 / 体积 / 长宽高 | ERP · 只读 | 用于上架、拣货、装载与计费 |
| 15 | 存储温区（建议值） | ERP 默认 · WMS 可改 | 常温 / 阴凉 / 冷藏 / 冷冻；ERP 给建议值，WMS 可据实际库区覆盖 |
| 16 | 默认库区 / 上架策略 | WMS · 可编辑 | WMS 自有作业配置 |
| 17 | 拣货策略 | WMS · 可编辑 | WMS 自有作业配置 |
| 18 | 安全库存 / 上下限 | WMS · 可编辑 | WMS 库存策略配置 |
| 19 | 复核方式 | WMS · 可编辑 | 扫码复核 / 播种复核等 |
| 20 | 计费属性 | WMS · 可编辑 | 3PL 计费方式 / 单价（仅 WMS 侧生效） |
| 21 | 启用状态 | WMS · 可编辑 | 该 (sku, owner) 在 WMS 是否启用 |
一句话区分：ERP · 只读 是"商品是什么"，WMS 不能改；WMS · 可编辑 是"WMS 怎么管这件货"，WMS 自己配；ERP 默认 · WMS 可改 是双方都能给、以 WMS 覆盖为准的少数共享字段。
2.3 ERP 接口设计（ERP → WMS 单向）
同步方向：ERP → WMS（v1 单向）。WMS 通过接口拉取或接收商品主数据，不回写。
同步方式：支持全量同步 + 增量同步；建议"定时批量 + 变更事件触发"双通道（具体频率待定，见评审要点）。
主键与映射：sku_id 直接取自 ERP 报文；owner_id 不直接来自 ERP，需通过「货主 ↔ ERP 来源映射」绑定——每个货主配置其对应的 ERP 组织 / 供应商 / 门店编码，同步时据此把商品归属到正确的 owner_id。
幂等与落库：以 (sku_id, owner_id) 做 upsert；同一商品重复同步不新增记录，只更新字段值。
字段处理规则：ERP 字段覆盖 WMS 同名只读字段（保证与主源一致）；WMS 自有字段（库区/拣货/计费/启停等）不被接口覆盖；共享字段（存储温区）以"ERP 给默认、WMS 已手动改则保留 WMS 值"为策略（待确认）。
失败与容错：单条记录失败不阻断整体批次，记录失败明细（sku_id、owner_id、错误原因），支持失败重试；批次级返回成功/失败计数与耗时。
2.4 功能清单与详细需求
| # | 功能项 | 优先级 | 需求说明与验收要点 |
|---|---|---|---|
| 1 | ERP 接口接入与同步 | P0 | WMS 通过接口从 ERP 获取商品主数据；支持全量/增量；以 (sku_id, owner_id) upsert。 验收：给定 ERP 报文可正确落库；重复同步不产生重复记录；单条失败不阻断整体并记日志。 |
| 2 | 货主(owner)绑定与映射 | P0 | owner_id 由 WMS 提供；维护「货主 ↔ ERP 来源映射」，同步时按映射归属 owner_id。 验收：同一 sku 按不同 owner 生成独立记录；映射缺失时报错并跳过，不误归属。 |
| 3 | 商品主数据查看 | P0 | 列表（分页）+ 详情；支持按 owner、分类、名称、条码、状态搜索筛选；只读字段展示清晰标识来源 ERP。 验收：可按上述条件检索；详情页区分只读/可编辑字段。 |
| 4 | 基本信息只读控制 | P0 | ERP 来源字段在界面置灰/锁定，无编辑入口；接口层同样禁止 WMS 直接改这些字段。 验收：前端无编辑控件；后端对只读字段的写请求拒绝并记录。 |
| 5 | WMS 侧运营配置 | P1 | 对 WMS 可编辑字段（库区/拣货/安全库存/复核/计费/启停）进行维护，且不被同步覆盖。 验收：修改后重新同步，这些字段值保持不变；启用状态可单独控制。 |
| 6 | 同步监控与日志 | P1 | 展示最近同步时间、成功/失败数、失败明细；支持手动触发全量同步与失败重试。 验收：可查看批次结果；失败记录可定位到具体 (sku, owner) 与原因。 |
Future（P2，本期不做但架构预留）：双向/事件驱动实时增量同步；商品与追溯码、批次的关联视图；字段级变更对比与审计日志；商品主数据导出。
2.5 用户故事
- 作为基本信息维护员，我希望通过接口把 ERP 商品主数据同步进 WMS，以便不用手工逐条录入，且保证与 ERP 一致。
- 作为基本信息维护员，我希望配置"货主 ↔ ERP 来源映射"，以便同步来的商品能正确归属到对应 owner_id。
- 作为基本信息维护员，我希望商品基本信息在 WMS 里是只读锁定的，以便任何人都改不了、不会有"两套真相"。
- 作为基本信息维护员，我希望维护 WMS 侧作业配置（库区/拣货/计费），以便仓储作业按我们的策略跑，且不被同步刷掉。
- 作为仓储运营人员，我希望按货主/分类/条码快速查到某件商品及其库存属性，以便作业与核对。
- 作为基本信息维护员，当同步失败时我希望看到是哪条 (sku, owner) 出错、为什么，以便及时处理而非整批重来。
2.6 非目标（Non-goals）
- 不在 WMS 新建/编辑商品基础信息——ERP 是唯一权威源，WMS 只消费。
- 不回写商品主数据到 ERP（v1 单向；双向同步列入 P2）。
- 不做定价 / 促销 / 采购价逻辑——属 ERP 域，WMS 仅取作业所需字段。
- 不替代货主管理、追溯码/批次管理——owner_id 来自货主主数据；追溯/批次为独立模块。
- 不做商品图片/详情营销内容——WMS 聚焦作业所需的结构化属性。
2.7 主要风险
- ERP 接口不稳定 / 字段缺失 → 同步失败，影响出入库与追溯；缓解：失败隔离 + 重试 + 告警。
- owner_id 映射错误 → 商品归属错乱、库存串货；缓解：映射缺失即跳过并告警，不允许模糊归属。
- 只读字段被绕过修改 → 与 ERP 不一致；缓解：前端置灰 + 后端写拦截 + 同步覆盖兜底。
- 大数据量全量同步性能 → 分页/分批、增量优先。
上游：货主管理（system_owner）
- owner_id 由 WMS 侧提供，来源于货主主数据；本模块依赖货主管理维护货主档案与「货主 ↔ ERP 来源映射」。
- 货主管理未就绪时，商品同步无法正确归属 owner_id，本模块应安全跳过并告警（不误归属）。
下游：仓储作业（入库 / 出库 / 库内）
- 入库管理、出库管理、库内作业引用本模块的商品主数据（sku、单位、温区、批号、效期、包装层级）做收货、上架、拣货、复核。
- 商品「启用状态」直接控制该 (sku, owner) 是否可参与出入库作业。
下游：追溯码中台
- 追溯码绑定到具体 (sku, owner)，依赖本模块提供的商品身份与包装层级，决定追溯粒度（单品/中包/箱）。
- 基本信息（生产厂家、注册证号、条码）是追溯合规展示的底层数据。
下游：采购中心
- 采购订单、门店请货、收货均以商品为对象，引用本模块的 sku 与单位；采购侧产生的 ERP 商品变更经接口回流到本模块。
下游：计费（3PL）
- 本模块维护的「计费属性」供费用计算引用；计费逻辑不在此模块内实现。
关联：TMS 运输
- 运输对象为出库单据中的商品，间接依赖本模块的商品重量/体积/温区等字段做装载与温控。
- 性能：全量同步须分页/分批处理，单批失败不影响整体；商品列表查询需支持分页与索引（按 owner_id、sku_id、条码），万级数据下响应可控。
- 数据一致性：同步完成后 WMS 只读副本须与 ERP 主源一致；覆盖策略明确（ERP→只读字段覆盖，WMS 自有字段不覆盖）。
- 安全性与权限：基本信息前后端双重锁定（前端置灰 + 后端写拦截）；多租户隔离——所有查询与写操作须按 owner_id / tenant_id 维度隔离，跨货主不可见彼此商品。
- 可用性与容错：ERP 接口异常时同步可失败隔离、记录明细、支持手动重试，且查询功能不依赖同步实时成功；接口调用需超时与降级处理。
- 可维护性与扩展性：字段映射表可配置，便于 ERP 字段增减；接口协议（REST / 消息队列）可替换；新增 WMS 可编辑字段不影响只读逻辑。
- 审计与监控：同步批次、失败明细、字段变更可追溯（P2 补审计日志）；同步成功率/及时率可观测。
- 兼容性：兼容增量与全量两种同步模式；字段增减向后兼容，不因新增可选字段导致旧报文失败。
评审核对清单
- 联合主键 (sku_id, owner_id) 是否覆盖"同 sku 多货主"真实场景，是否存在单 owner 即可的简化可能？
- owner_id 与 ERP 的映射基准是否明确（按货主 / 按 ERP 组织 / 按门店）？映射缺失时是否安全跳过而非模糊归属？
- 只读字段是否前后端双重锁定，且同步覆盖作为兜底保障一致性？
- 同步是否幂等（重复同步不重复记录），upsert 逻辑是否正确？
- WMS 可编辑字段范围是否最终确认，且明确"不被同步覆盖"？
- 失败隔离与重试机制是否到位，失败明细能否定位到具体 (sku, owner) 与原因？
- 与货主管理、入库/出库、追溯码中台、采购中心、计费的关联口径是否对齐？
- 商品字段清单是否已与 ERP 对齐（权威源、字段命名、类型）？
- 非目标边界是否清晰（不回写 ERP、不做定价等），避免范围蔓延？
- 多租户隔离（owner_id / tenant_id）是否满足安全与合规要求？
需用户 / 架构确认的开放问题
- 接口协议与同步频率：REST 拉取 / 消息推送？全量周期与增量触发方式？
- 同 sku 跨多 owner 是否真实存在，决定联合主键是否必要（还是 owner_id 可省）？
- 共享字段（存储温区）覆盖策略：ERP 默认优先，还是 WMS 手动值优先？
- WMS 可编辑字段范围最终确认（计费属性是否本期需要）？
- 字段权威清单与映射表以谁为准、由谁维护？