供应商管理 · 需求文档（BM-02）
供应商档案以 ERP 为唯一权威源，WMS 通过接口获取，不在 WMS 内手工编辑；供应商资料的增改统一在 ERP 完成，经接口重新同步回 WMS，确保两套系统数据一致。核心差异点：提供批量对照能力——勾选多条供应商，调用其所属货主的码上放心接口，自动拉取并写入 码上放心企业名称 / ent_id / ref_ent_id，为后续追溯、核注、关联关系等业务预留企业身份基础。核心约束：vendor_id + owner_id 联合主键、基本信息只读、码上放心字段仅由对照写入、不可手改。
模块定位
供应商管理是 WMS 的上下游身份认证层（参见数据库文档 pub_vendor 表注释），维护仓储作业与追溯业务所需的供应商档案，供入库、采购、出库、追溯码中台等模块引用。它不做供应商主数据的生产方，只做 ERP 主数据的消费方与码上放心身份补充方。
要解决的问题
- 供应商资料若在 ERP / WMS 各录各的，极易不一致，直接导致采购入库挂错供应商、追溯码绑定错企业、对账偏差。
- 多货主（3PL）场景下，同一供应商可能归属不同货主，缺少 owner 维度会让供应商"串货"。
- WMS 运营人员误改供应商基础信息（如名称、银行账号、法人），事后无法判断以谁为准，且违反"单一权威源"原则。
- 药品追溯要求供应商具备码上放心企业身份（企业名称、ent_id、ref_ent_id），但 ERP 通常不含这些字段，需要一套可批量补全的机制，逐条手填既慢又易错。
目标（可衡量）
- 供应商主数据 100% 来自 ERP 接口，WMS 零手工编辑基本信息。
- 通过 (vendor_id, owner_id) 联合主键，支撑"同供应商多货主"隔离。
- 批量对照可将供应商的码上放心企业身份（名称 / ent_id / ref_ent_id）批量补全，而非逐条手填，为后续核注、关联、追溯业务准备好企业身份基础。
- 基本信息只读、码上放心字段仅由对照写入，权责清晰、可审计。
- 同步与对照过程可监控、可回溯（时间、结果、失败明细）。
2.1 核心约束与设计原则
① 数据来源 —— 接口获取 ERP 供应商资料。WMS 不生产供应商主数据，只消费。ERP 是供应商基础信息的权威源，WMS 通过接口（拉取/接收）落地。v1 默认单向同步（ERP → WMS），WMS 不回写供应商主数据。
② 联合主键 —— vendor_id + owner_id。vendor_id 来自 ERP（供应商唯一编码，对应 pub_vendor.vendor_id，备注"ERP供应商id"）；owner_id 由 WMS 侧提供，关联"货主主数据 system_owner.id"。二者共同唯一标识一条供应商记录。之所以需要 owner_id：同一供应商在不同货主名下是两条独立实体，必须靠 owner 区分。
③ 只读控制 —— 基本信息部分不可编辑。所有来自 ERP 的基本信息字段在 WMS 内锁定/置灰，任何界面与接口都不允许 WMS 侧直接修改。供应商的编辑统一在 ERP 系统完成，ERP 改动后通过接口重新同步回 WMS（增量 / 事件触发），WMS 副本自动被覆盖，保证与 ERP 一致。此设计的目的即"为保证数据一致性，WMS 不提供供应商资料的编辑"。
④ 码上放心对照 —— 由"批量对照"写入，不可手改。码上放心企业信息（ent_name / ent_id / ref_ent_id）不来自 ERP、也不允许在 WMS 手工录入，只能通过"批量对照"动作调用货主码上放心接口获取后回写。该字段集是 WMS 在供应商档案上的唯一自有补充维度，且只能由系统经接口写入。
2.2 数据模型（联合主键 vendor_id + owner_id）
供应商记录以 (vendor_id, owner_id) 为联合主键，对应数据库文档 pub_vendor 表。字段按"可编辑性"分为四类：
| # | 字段 | 来源 / 可编辑性 | 说明 |
|---|---|---|---|
| 1 | vendor_id | ERP · 只读PK | ERP 供应商 ID，联合主键之一，来自 ERP |
| 2 | owner_id | WMS · 只读(系统)PK | 货主 ID，由 WMS 提供，关联货主主数据 system_owner.id，联合主键之一 |
| 3 | vendor_code | ERP · 只读 | 供应商编码 |
| 4 | vendor_name | ERP · 只读 | 供应商名称（批量对照的匹配键之一） |
| 5 | short_name | ERP · 只读 | 供应商简称 |
| 6 | vendor_opcode | ERP · 只读 | 助记码 |
| 7 | contact_man | ERP · 只读 | 联系人 |
| 8 | contact_tel | ERP · 只读 | 联系电话 |
| 9 | legal | ERP · 只读 | 法人 |
| 10 | post_code | ERP · 只读 | 邮政编码 |
| 11 | bank_name | ERP · 只读 | 开户银行 |
| 12 | bank_no | ERP · 只读 | 开户账号 |
| 13 | regist_address | ERP · 只读 | 注册地址 |
| 14 | store_address | ERP · 只读 | 仓库地址 |
| 15 | country_code | ERP · 只读 | 国家二字码 |
| 16 | province | ERP · 只读 | 省 |
| 17 | city | ERP · 只读 | 市 |
| 18 | area | ERP · 只读 | 区 |
| 19 | town | ERP · 只读 | 村镇 |
| 20 | 码上放心企业名称 ent_name | 码上放心 · 对照写入 | 批量对照调用货主码上放心接口获取；不可手改 |
| 21 | 码上放心企业 ent_id | 码上放心 · 对照写入 | 码上放心企业标识，对照写入；不可手改 |
| 22 | 码上放心企业 ref_ent_id | 码上放心 · 对照写入 | 码上放心企业引用标识，对照写入；不可手改 |
| — | 系统公共字段（status / creator / create_time / updater / update_time / deleted / tenant_id） | WMS · 系统 | 全库统一收尾 7 个字段；tenant_id 用于多租户隔离，status 控制有效/无效 |
一句话区分：ERP · 只读 是"供应商是谁"，来自 ERP，WMS 不能改；WMS · 系统 是 WMS 维护的主键/状态/租户等系统字段；码上放心 · 对照写入 是经"批量对照"由货主码上放心接口拉取、绝不可手改的追溯身份字段。
2.3 ERP 接口设计（ERP → WMS 单向同步）
同步方向：ERP → WMS（v1 单向）。WMS 通过接口拉取或接收供应商主数据，不回写。
同步触发：支持全量同步 + 增量同步；建议"定时批量 + 变更事件触发"双通道。当 ERP 在源头完成供应商编辑后，应通过增量/事件方式重新同步到 WMS，使 WMS 副本自动覆盖更新，从而达成"WMS 不提供编辑、编辑在 ERP、再同步回 WMS"的数据一致性闭环。
主键与映射：vendor_id 直接取自 ERP 报文；owner_id 不直接来自 ERP，需通过「货主 ↔ ERP 来源映射」绑定——每个货主配置其对应的 ERP 组织 / 供应商来源编码，同步时据此把供应商归属到正确的 owner_id。
幂等与落库：以 (vendor_id, owner_id) 做 upsert；同一供应商重复同步不新增记录，只更新字段值。
字段处理规则：ERP 字段覆盖 WMS 同名只读字段（含供应商基本信息、银行账号、地址等）；码上放心三字段（ent_name / ent_id / ref_ent_id）不被 ERP 同步覆盖，其唯一写入通道是"批量对照"，避免对照结果被 ERP 报文抹掉。
失败与容错：单条记录失败不阻断整体批次，记录失败明细（vendor_id、owner_id、错误原因），支持失败重试；批次级返回成功/失败计数与耗时。
2.4 批量对照接口设计（码上放心）
功能定位："批量对照"是供应商管理区别于其他主数据的核心能力。其目的是把 WMS 中的供应商与码上放心平台上的企业身份对应起来，补全 ent_name / ent_id / ref_ent_id，为后续核注、关联关系、追溯等业务提供企业身份基础。
接口归属：调用的是货主（owner）的码上放心接口，而非 WMS 自有接口。每个货主在 WMS 中需预先配置其码上放心接入凭证（app_key / secret 或 token）与接口地址；WMS 作为调用方，按供应商所属 owner 路由到对应货主的码上放心凭据。
操作流程（批量）：
- 在供应商列表勾选多条供应商记录（建议先按货主筛选，避免跨货主混批）；点击「批量对照」。
- 系统按所选供应商的 owner_id 取出对应货主的码上放心接口配置；若勾选跨多个货主，按 owner 分组分别调用。
- 以 ERP 供应商的供应商名称 / 统一社会信用代码（若 ERP 提供）作为码上放心企业查询的匹配入参。
- 调用货主侧码上放心「企业信息查询」接口，获取该企业身份。
- 将返回结果写入供应商记录：码上放心企业名称（ent_name）、码上放心企业 ent_id、码上放心企业 ref_ent_id。
结果处理与写入规则：
- 对照预览：调用前/后展示匹配结果——已匹配、未匹配、调用失败三类，供人工确认。
- 确认写入：预览无误后批量落库；写入属于"对照写入"，前端不提供这三个字段的手动编辑入口。
- 幂等：以 (vendor_id, owner_id) 定位，重复对照覆盖原值，不产生重复记录。
- 可重做 / 可清除：支持对单条或批量重新对照；支持清除已对照的码上放心字段（置空），用于纠错。
- 失败隔离：单条对照失败不阻断整批，记录失败明细（vendor_id、owner_id、失败原因），支持失败重试。
入参 / 出参（货主码上放心接口）：
| # | 项 | 方向 | 字段 / 说明 |
|---|---|---|---|
| 1 | 货主码上放心凭证 | WMS → 码上放心 | 按 owner_id 路由的 app_key / secret / token 与接口地址（由货主管理配置） |
| 2 | 匹配入参 | WMS → 码上放心 | 供应商名称 / 统一社会信用代码（来自 ERP 字段） |
| 3 | 码上放心企业名称 | 码上放心 → WMS | 映射写入 ent_name |
| 4 | 码上放心企业 ent_id | 码上放心 → WMS | 映射写入 ent_id |
| 5 | 码上放心企业 ref_ent_id | 码上放心 → WMS | 映射写入 ref_ent_id |
2.5 功能清单与详细需求
| # | 功能项 | 优先级 | 需求说明与验收要点 |
|---|---|---|---|
| 1 | ERP 接口接入与同步 | P0 | WMS 通过接口从 ERP 获取供应商主数据；支持全量/增量；以 (vendor_id, owner_id) upsert；ERP 编辑后经接口重新同步回 WMS。 验收：给定 ERP 报文可正确落库；重复同步不产生重复记录；单条失败不阻断整体并记日志。 |
| 2 | 货主(owner)绑定与映射 | P0 | owner_id 由 WMS 提供；维护「货主 ↔ ERP 来源映射」，同步时按映射归属 owner_id；同时为后续批量对照维护「货主 ↔ 码上放心接口凭证」配置。 验收：同一供应商按不同 owner 生成独立记录；映射缺失时报错并跳过，不误归属。 |
| 3 | 供应商主数据查看 | P0 | 列表（分页）+ 详情；支持按 owner、供应商编码/名称、状态、是否已对照码上放心搜索筛选；只读字段清晰标识来源 ERP，码上放心字段标识"对照写入"。 验收：可按上述条件检索；详情页区分只读/系统/对照字段。 |
| 4 | 基本信息只读控制 | P0 | ERP 来源字段在界面置灰/锁定，无编辑入口；WMS 不提供供应商资料的编辑 UI 与写接口；接口层同样禁止 WMS 直接改这些字段；ERP 的改动统一经接口重新同步覆盖。 验收：前端无编辑控件；后端对只读字段的写请求拒绝并记录；ERP 改动同步后 WMS 副本被覆盖更新。 |
| 5 | 批量对照（码上放心） | P0 | 勾选多条供应商 → 点击「批量对照」→ 按 owner_id 路由到对应货主码上放心接口 → 以供应商名称/信用代码为匹配键查询 → 回写 ent_name / ent_id / ref_ent_id；支持对照预览、确认写入、按 owner 分组调用、失败隔离。 验收：勾选 N 条可批量补全码上放心三字段；跨货主自动分组调用；单条失败不影响整批并记明细；未匹配/失败可定位到具体 (vendor_id, owner_id)。 |
| 6 | 同步监控与日志 | P1 | 展示最近 ERP 同步时间、成功/失败数、失败明细；支持手动触发全量同步与失败重试。 验收：可查看批次结果；失败记录可定位到具体 (vendor_id, owner) 与原因。 |
| 7 | 码上放心对照结果管理 | P1 | 查看每条供应商的码上放心对照状态（已对照/未对照/失败）；支持单条或批量重新对照、清除已对照字段（纠错）；码上放心三字段在任何界面均不可手改，只能通过对照写入。 验收：对照状态可筛选；重对照覆盖原值；清除可置空；手动编辑入口不存在。 |
Future（P2，本期不做但架构预留）：码上放心字段与追溯码/批次的关联视图；字段级变更对比与审计日志；供应商与商品、客户的统一主数据视图；供应商导出。
2.6 用户故事
- 作为基本信息维护员，我希望通过接口把 ERP 供应商主数据同步进 WMS，以便不用手工逐条录入，且保证与 ERP 一致。
- 作为基本信息维护员，我希望供应商资料在 WMS 里是只读锁定的，所有编辑都在 ERP 完成再同步回来，以便任何人都改不了、不会有"两套真相"。
- 作为基本信息维护员，我希望勾选一批供应商后一键「批量对照」，自动调用对应货主的码上放心接口补全企业名称 / ent_id / ref_ent_id，以便为后续追溯业务准备好企业身份，而不用逐条手填。
- 作为基本信息维护员，当某条供应商对照失败时我希望看到是哪家、为什么，以便及时处理而非整批重来。
- 作为仓储/采购运营人员，我希望按货主/名称/是否已对照码上放心快速查到某个供应商及其身份，以便作业与核对。
2.7 非目标（Non-goals）
- 不在 WMS 新建/编辑供应商基础信息——ERP 是唯一权威源，WMS 只消费，编辑统一在 ERP 完成后经接口重新同步。
- 不回写供应商主数据到 ERP（v1 单向；双向同步列入 P2）。
- 不手工录入码上放心字段——ent_name / ent_id / ref_ent_id 只能由"批量对照"经货主码上放心接口写入，WMS 不提供手动编辑入口。
- 不做定价 / 采购价 / 账期逻辑——属 ERP 域，WMS 仅取作业与追溯所需字段。
- 不替代货主管理、追溯码/批次管理——owner_id 与码上放心凭证来自货主主数据；追溯/批次为独立模块。
2.8 主要风险
- ERP 接口不稳定 / 字段缺失 → 同步失败，影响入库与追溯；缓解：失败隔离 + 重试 + 告警。
- owner_id 映射错误 → 供应商归属错乱、串货；缓解：映射缺失即跳过并告警，不允许模糊归属。
- 只读字段被绕过修改 → 与 ERP 不一致；缓解：前端置灰 + 后端写拦截 + 同步覆盖兜底。
- 货主码上放心凭证缺失 / 失效 → 批量对照无法调用；缓解：凭证缺失时该 owner 的对照请求直接失败并提示配置；码上放心三字段不被 ERP 同步覆盖以免丢失。
- 对照匹配不准 → 供应商名称与码上放心企业名不完全一致导致匹配失败或错配；缓解：支持信用代码作为更强匹配键，未匹配单独列出人工确认，不搞模糊自动落库。
- 大数据量全量同步性能 → 分页/分批、增量优先。
上游：货主管理（system_owner）
- owner_id 由 WMS 侧提供，来源于货主主数据；本模块依赖货主管理维护货主档案、「货主 ↔ ERP 来源映射」以及「货主 ↔ 码上放心接口凭证」配置。
- 货主管理未就绪时，供应商同步无法正确归属 owner_id，本模块应安全跳过并告警（不误归属）；码上放心凭证缺失时批量对照应明确失败并提示配置。
下游：入库管理 / 采购中心
- 采购订单、收货、门店请货、退货均以供应商为对象，引用本模块的 vendor 身份；供应商变更经 ERP 接口回流到本模块。
- 供应商「状态（status）」直接控制该 (vendor, owner) 是否可参与采购与入库作业。
下游：追溯码中台
- 码上放心企业身份（ent_name / ent_id / ref_ent_id）是核注、关联关系、追溯合规展示的底层身份数据，由本模块经批量对照补全后供追溯码中台引用。
- 基本信息（供应商名称、法人、注册地址）是追溯合规展示的补充数据。
下游：出库管理 / TMS 运输
- 出库单据、运输对象间接引用本模块的供应商身份与地址字段做发货与温控。
关联：客户管理、商品管理
- 三者同属基本信息，均采用"ERP 接口同步 + 联合主键 + 只读控制"的主数据治理模式；客户管理与供应商管理互为上下游交易主体。
- 性能：全量同步须分页/分批处理，单批失败不影响整体；供应商列表查询需支持分页与索引（按 owner_id、vendor_id、vendor_code、vendor_name），万级数据下响应可控；批量对照按货主分组并发调用，控制码上放心接口频限。
- 数据一致性：同步完成后 WMS 只读副本须与 ERP 主源一致；覆盖策略明确（ERP→只读字段覆盖，码上放心三字段不被 ERP 覆盖，只能由对照写入）。
- 安全性与权限：供应商基本信息前后端双重锁定（前端置灰 + 后端写拦截）；码上放心三字段仅允许"批量对照"通道写入，禁止手动写接口；多租户隔离——所有查询与写操作须按 owner_id / tenant_id 维度隔离，跨货主不可见彼此供应商。
- 可用性与容错：ERP 接口异常或货主码上放心凭证失效时，同步/对照可失败隔离、记录明细、支持手动重试，且查询功能不依赖实时成功；接口调用需超时与降级处理。
- 可维护性与扩展性：字段映射表可配置，便于 ERP 字段增减；接口协议（REST / 消息队列）可替换；货主码上放心凭证按 owner 配置，便于新增货主接入。
- 审计与监控：ERP 同步批次、码上放心对照批次、失败明细、字段变更可追溯（P2 补审计日志）；同步/对照成功率与及时率可观测。
- 兼容性：兼容增量与全量两种同步模式；字段增减向后兼容，不因新增可选字段导致旧报文失败。
评审核对清单
- 联合主键 (vendor_id, owner_id) 是否覆盖"同供应商多货主"真实场景，是否存在单 owner 即可的简化可能？
- owner_id 与 ERP 的映射基准是否明确（按货主 / 按 ERP 组织）？映射缺失时是否安全跳过而非模糊归属？
- 只读字段是否前后端双重锁定，且 ERP 重新同步覆盖作为兜底保障一致性？
- 同步是否幂等（重复同步不重复记录），upsert 逻辑是否正确？
- 码上放心三字段（ent_name / ent_id / ref_ent_id）是否被明确排除在 ERP 同步覆盖之外，且 WMS 无手动编辑入口？
- 批量对照的货主码上放心接口凭证由谁配置、存于何处（货主管理），跨货主分组调用与失败隔离是否到位？
- 对照匹配键是否明确（供应商名称 / 统一社会信用代码），未匹配是否单独列出人工确认而非模糊落库？
- 与货主管理、入库/采购、追溯码中台的关联口径是否对齐？
- 非目标边界是否清晰（不回写 ERP、不手改码上放心字段），避免范围蔓延？
- 多租户隔离（owner_id / tenant_id）是否满足安全与合规要求？
需用户 / 架构确认的开放问题
- 接口协议与同步频率：REST 拉取 / 消息推送？全量周期与增量触发方式？ERP 编辑后重新同步的触发机制？
- 同供应商跨多 owner 是否真实存在，决定联合主键是否必要（还是 owner_id 可省）？
- 货主码上放心接口的具体协议、凭证类型（app_key/secret 或 token）、频限与鉴权方式？
- 批量对照的匹配键优先级：信用代码优先还是名称优先？名称不一致时如何处理（仅人工确认，还是允许模糊匹配）？
- 码上放心接口返回字段是否仅取 ent_name / ent_id / ref_ent_id 三项，还是本期一并保留更多字段备用？
- WMS 可编辑字段范围最终确认（当前除系统字段与码上放心字段外均无 WMS 可编辑项，是否符合预期）？