客户管理 · 需求文档（BM-03）

模块定位

客户管理是 WMS 的下游身份认证层（参见数据库文档 pub_customer 表注释），维护仓储作业与追溯业务所需的客户档案，供出库、销售、运输等模块引用。它不做客户主数据的生产方，只做 ERP 主数据的消费方与码上放心身份补充方；与供应商管理（BM-02）形成对称设计——供应商管理回答"货从哪里来"，客户管理回答"货送到哪里去"。

要解决的问题

• 客户资料若在 ERP / WMS 各录各的，极易不一致，直接导致销售出库挂错客户、追溯码绑定错企业、对账偏差。
• 多货主（3PL）场景下，同一客户可能归属不同货主，缺少 owner 维度会让客户"串户"。
• WMS 运营人员误改客户基础信息（如名称、银行账号、法人），事后无法判断以谁为准，且违反"单一权威源"原则。
• 药品追溯要求客户（收货/使用方）具备码上放心企业身份（企业名称、ent_id、ref_ent_id），但 ERP 通常不含这些字段，需要一套可批量补全的机制，逐条手填既慢又易错。

目标（可衡量）

• 客户主数据 100% 来自 ERP 接口，WMS 零手工编辑基本信息。
• 通过 (customer_id, owner_id) 联合主键，支撑"同客户多货主"隔离。
• 批量对照可将客户的码上放心企业身份（名称 / ent_id / ref_ent_id）批量补全，而非逐条手填，为后续核注、关联、追溯业务准备好企业身份基础。
• 基本信息只读、码上放心字段仅由对照写入，权责清晰、可审计。
• 同步与对照过程可监控、可回溯（时间、结果、失败明细）。

2.1 核心约束与设计原则

① 数据来源 —— 接口获取 ERP 客户资料。WMS 不生产客户主数据，只消费。ERP 是客户基础信息的权威源，WMS 通过接口（拉取/接收）落地。v1 默认单向同步（ERP → WMS），WMS 不回写客户主数据。

② 联合主键 —— customer_id + owner_id。customer_id 来自 ERP（客户唯一编码，对应 pub_customer.customer_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 数据模型（联合主键 customer_id + owner_id）

客户记录以 (customer_id, owner_id) 为联合主键，对应数据库文档 pub_customer 表（共 30 字段）。字段按"可编辑性"分为四类：

#	字段	来源 / 可编辑性	说明
1	customer_id	ERP · 只读PK	ERP 客户 ID，联合主键之一，来自 ERP（备注"ERP客户id"）
2	owner_id	WMS · 系统PK	货主 ID，由 WMS 提供，关联货主主数据 system_owner.id，联合主键之一
3	customer_code	ERP · 只读	客户编码
4	customer_name	ERP · 只读	客户名称（批量对照的匹配键之一）
5	short_name	ERP · 只读	客户简称
6	customer_opcode	ERP · 只读	助记码
7	contact_man	ERP · 只读	联系人
8	contact_tel	ERP · 只读	联系电话
9	legal	ERP · 只读	法人
10	bank_name	ERP · 只读	开户银行
11	bank_no	ERP · 只读	开户账号
12	regist_address	ERP · 只读	注册地址
13	store_address	ERP · 只读	仓库地址
14	province	ERP · 只读	省
15	city	ERP · 只读	市
16	area	ERP · 只读	区
17	town	ERP · 只读	村镇
18	is_print_no	WMS · 待定	是否打印贯标码（1 是 0 否）；编辑权限见 §五 开放问题（默认遵循"WMS不提供编辑"原则，由 ERP 同步或融合系统管理）
19	customer_account	WMS · 待定	客户融合系统登录账号；编辑权限见 §五 开放问题
20	customer_pwd	WMS · 待定	客户融合系统登录密码（敏感）；编辑权限见 §五 开放问题
21	码上放心企业名称 ent_name	码上放心 · 对照写入	批量对照调用货主码上放心接口获取；不可手改
22	码上放心企业 ent_id	码上放心 · 对照写入	码上放心企业标识，对照写入；不可手改
23	码上放心企业 ref_ent_id	码上放心 · 对照写入	码上放心企业引用标识，对照写入；不可手改
—	系统公共字段（status / creator / create_time / updater / update_time / deleted / tenant_id）	WMS · 系统	全库统一收尾 7 个字段；tenant_id 用于多租户隔离，status 控制有效/无效

一句话区分：ERP · 只读 是"客户是谁"，来自 ERP，WMS 不能改；WMS · 系统 是 WMS 维护的主键/状态/租户等系统字段；码上放心 · 对照写入 是经"批量对照"由货主码上放心接口拉取、绝不可手改的追溯身份字段。WMS · 待定 为 pub_customer 中三项 WMS 侧字段（打印标志 / 融合系统账号密码），其编辑权限需按 §五 评审确认，默认不违反"WMS不提供客户编辑"原则。

2.3 ERP 接口设计（ERP → WMS 单向同步）

同步方向：ERP → WMS（v1 单向）。WMS 通过接口拉取或接收客户主数据，不回写。

同步触发：支持全量同步 + 增量同步；建议"定时批量 + 变更事件触发"双通道。当 ERP 在源头完成客户编辑后，应通过增量/事件方式重新同步到 WMS，使 WMS 副本自动覆盖更新，从而达成"WMS 不提供编辑、编辑在 ERP、再同步回 WMS"的数据一致性闭环。

主键与映射：customer_id 直接取自 ERP 报文；owner_id 不直接来自 ERP，需通过「货主 ↔ ERP 来源映射」绑定——每个货主配置其对应的 ERP 组织 / 客户来源编码，同步时据此把客户归属到正确的 owner_id。

幂等与落库：以 (customer_id, owner_id) 做 upsert；同一客户重复同步不新增记录，只更新字段值。

字段处理规则：ERP 字段覆盖 WMS 同名只读字段（含客户基本信息、银行账号、地址等）；码上放心三字段（ent_name / ent_id / ref_ent_id）不被 ERP 同步覆盖，其唯一写入通道是"批量对照"，避免对照结果被 ERP 报文抹掉；is_print_no / customer_account / customer_pwd 按 §五 确认的权限处理，不在本接口默认覆盖争议范围内。

失败与容错：单条记录失败不阻断整体批次，记录失败明细（customer_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。

结果处理与写入规则：

• 对照预览：调用前/后展示匹配结果——已匹配、未匹配、调用失败三类，供人工确认。
• 确认写入：预览无误后批量落库；写入属于"对照写入"，前端不提供这三个字段的手动编辑入口。
• 幂等：以 (customer_id, owner_id) 定位，重复对照覆盖原值，不产生重复记录。
• 可重做 / 可清除：支持对单条或批量重新对照；支持清除已对照的码上放心字段（置空），用于纠错。
• 失败隔离：单条对照失败不阻断整批，记录失败明细（customer_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 获取客户主数据；支持全量/增量；以 (customer_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 条可批量补全码上放心三字段；跨货主自动分组调用；单条失败不影响整批并记明细；未匹配/失败可定位到具体 (customer_id, owner_id)。
6	同步监控与日志	P1	展示最近 ERP 同步时间、成功/失败数、失败明细；支持手动触发全量同步与失败重试。 验收：可查看批次结果；失败记录可定位到具体 (customer_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 同步覆盖以免丢失。
• 对照匹配不准 → 客户名称与码上放心企业名不完全一致导致匹配失败或错配；缓解：支持信用代码作为更强匹配键，未匹配单独列出人工确认，不搞模糊自动落库。
• is_print_no / customer_account / customer_pwd 编辑权限未确认 → 若误放进 WMS 编辑，可能违反"WMS不提供客户编辑"原则或与 ERP 冲突；缓解：§五 评审先定权限，默认按只读/ERP 同步处理。
• 大数据量全量同步性能 → 分页/分批、增量优先。

上游：货主管理（system_owner）

• owner_id 由 WMS 侧提供，来源于货主主数据；本模块依赖货主管理维护货主档案、「货主 ↔ ERP 来源映射」以及「货主 ↔ 码上放心接口凭证」配置。
• 货主管理未就绪时，客户同步无法正确归属 owner_id，本模块应安全跳过并告警（不误归属）；码上放心凭证缺失时批量对照应明确失败并提示配置。

下游：出库管理 / 销售中心

• 销售订单、发货、门店请货、退货均以客户为对象，引用本模块的客户身份；客户变更经 ERP 接口回流到本模块。
• 客户「状态（status）」直接控制该 (customer, owner) 是否可参与销售与出库作业。

下游：追溯码中台

• 码上放心企业身份（ent_name / ent_id / ref_ent_id）是核注、关联关系、追溯合规展示的底层身份数据，由本模块经批量对照补全后供追溯码中台引用（客户即"货送到哪里去"的追溯主体）。
• 基本信息（客户名称、法人、注册地址）是追溯合规展示的补充数据。

下游：TMS 运输

• 出库单据、运输对象间接引用本模块的客户身份与地址字段做收货与温控。

关联：供应商管理、商品管理

• 三者同属基本信息，均采用"ERP 接口同步 + 联合主键 + 只读控制"的主数据治理模式；客户管理与供应商管理互为上下游交易主体（供应商回答"货从哪里来"，客户回答"货送到哪里去"）。

• 性能：全量同步须分页/分批处理，单批失败不影响整体；客户列表查询需支持分页与索引（按 owner_id、customer_id、customer_code、customer_name），万级数据下响应可控；批量对照按货主分组并发调用，控制码上放心接口频限。
• 数据一致性：同步完成后 WMS 只读副本须与 ERP 主源一致；覆盖策略明确（ERP→只读字段覆盖，码上放心三字段不被 ERP 覆盖，只能由对照写入）。
• 安全性与权限：客户基本信息前后端双重锁定（前端置灰 + 后端写拦截）；码上放心三字段仅允许"批量对照"通道写入，禁止手动写接口；多租户隔离——所有查询与写操作须按 owner_id / tenant_id 维度隔离，跨货主不可见彼此客户；customer_pwd 等敏感字段须加密存储与脱敏展示。
• 可用性与容错：ERP 接口异常或货主码上放心凭证失效时，同步/对照可失败隔离、记录明细、支持手动重试，且查询功能不依赖实时成功；接口调用需超时与降级处理。
• 可维护性与扩展性：字段映射表可配置，便于 ERP 字段增减；接口协议（REST / 消息队列）可替换；货主码上放心凭证按 owner 配置，便于新增货主接入。
• 审计与监控：ERP 同步批次、码上放心对照批次、失败明细、字段变更可追溯（P2 补审计日志）；同步/对照成功率与及时率可观测。
• 兼容性：兼容增量与全量两种同步模式；字段增减向后兼容，不因新增可选字段导致旧报文失败。

评审核对清单

• 联合主键 (customer_id, owner_id) 是否覆盖"同客户多货主"真实场景，是否存在单 owner 即可的简化可能？
• owner_id 与 ERP 的映射基准是否明确（按货主 / 按 ERP 组织）？映射缺失时是否安全跳过而非模糊归属？
• 只读字段是否前后端双重锁定，且 ERP 重新同步覆盖作为兜底保障一致性？
• 同步是否幂等（重复同步不重复记录），upsert 逻辑是否正确？
• 码上放心三字段（ent_name / ent_id / ref_ent_id）是否被明确排除在 ERP 同步覆盖之外，且 WMS 无手动编辑入口？
• 批量对照的货主码上放心接口凭证由谁配置、存于何处（货主管理），跨货主分组调用与失败隔离是否到位？
• 对照匹配键是否明确（客户名称 / 统一社会信用代码），未匹配是否单独列出人工确认而非模糊落库？
• 与货主管理、出库/销售、追溯码中台的关联口径是否对齐？与供应商管理（BM-02）是否保持对称设计？
• 非目标边界是否清晰（不回写 ERP、不手改码上放心字段、WMS 不编辑客户资料），避免范围蔓延？
• 多租户隔离（owner_id / tenant_id）是否满足安全与合规要求？

需用户 / 架构确认的开放问题

• 接口协议与同步频率：REST 拉取 / 消息推送？全量周期与增量触发方式？ERP 编辑后重新同步的触发机制？
• 同客户跨多 owner 是否真实存在，决定联合主键是否必要（还是 owner_id 可省）？
• 货主码上放心接口的具体协议、凭证类型（app_key/secret 或 token）、频限与鉴权方式？
• 批量对照的匹配键优先级：信用代码优先还是名称优先？名称不一致时如何处理（仅人工确认，还是允许模糊匹配）？
• 码上放心接口返回字段是否仅取 ent_name / ent_id / ref_ent_id 三项，还是本期一并保留更多字段备用？
• pub_customer 中三项 WMS 侧字段（is_print_no 是否打印贯标码、customer_account 客户融合系统登录账号、customer_pwd 客户融合系统登录密码）的编辑权限：按"WMS不提供客户编辑"原则，默认应视为由 ERP 同步或融合系统管理、WMS 只读；但若 is_print_no 等确需 WMS 运营配置，需明确其编辑入口与权限边界，避免与只读原则冲突。