客户主档扩展 + 协议单向覆盖同步设计

日期：2026-10-08
状态：已确认（2026-10-08）
范围：biz_customer 通用个人档案字段扩展；采集协议（及同源当事人同步）保存时以协议非空字段覆盖客户主档；协议快照仍用现有当事人表
关联：docs/superpowers/specs/2026-10-07-customer-family-protocol-link-design.md（三角色客户 ID 关联；本设计在其上扩展主档字段与覆盖策略）

1. 背景

采集协议「客户信息」中，母亲信息包含姓名、电话、身份证、出生年月、民族、邮箱、家庭住址；父亲包含姓名、电话、身份证；子女（新生儿）另有分娩相关业务字段。

当前分工：

表	作用
`biz_customer`	客户主档（活档）：姓名、性别、身份证、年龄、电话、标签、备注
`biz_protocol_party_customer`	协议当事人表（快照）：一单一行，冗余母亲/父亲/新生儿全套字段 + 三角色 `customer_id`

当事人表已具备协议侧快照能力：查看协议读当事人字段，客户管理事后改主档不会冲掉旧协议展示值。

缺口：

biz_customer 缺少出生年月、民族、邮箱、住址，母亲扩展信息无法进入主档。
party_customer_sync 同步偏窄（主要姓名/电话/身份证），且多为「空才补」，与产品选择的「协议有值则覆盖主档」不一致。

产品确认采用方案 1：扩客户表为通用个人档案 + 协议保存单向覆盖同步；不拆母亲/父亲/子女物理子表。

2. 目标与非目标

2.1 目标

biz_customer 增加通用个人字段：birth_ym、ethnic、email、address（角色不进客户表）。
协议保存：先写/更新当事人快照（现状保留）→ 再按角色以协议非空字段覆盖对应 biz_customer。
客户管理 UI/API 可独立录入与展示上述新字段。
细胞存储采集协议与科研捐赠等走同一套 party_customer_sync 的，同步规则一并升级。

2.2 非目标

不拆 biz_protocol_party_customer 为母亲/父亲/子女三张子表。
客户管理改主档不回写当事人表。
不做 biz_customer_history 变更履历表。
新生儿分娩业务字段（预产期、分娩方式、胎次、体重、Apgar 等）不进客户表。
本期不做「主档与协议快照差异」提示 UI。

3. 数据模型

3.1 `biz_customer` 新增列

列	类型	API / 前端	说明
`birth_ym`	`CHAR(6) NULL`	`birthYm`	出生年月 YYYYMM
`ethnic`	`VARCHAR(32) NULL`	`ethnic`	民族名称
`email`	`VARCHAR(128) NULL`	`email`	邮箱
`address`	`VARCHAR(512) NULL`	`address`	家庭住址

已有字段继续使用：customer_name、sex、id_card_no、age、phone_no、customer_tags、remark 及公共字段。

3.2 当事人表

不改结构。 biz_protocol_party_customer（及科研捐赠同源当事人表若结构平行）继续作为协议快照权威。

3.3 协议角色 → 客户字段映射

母亲 → customer_id：
  mother_name        → customer_name
  mother_phone       → phone_no
  mother_id_card     → id_card_no
  mother_birth_ym    → birth_ym
  mother_ethnic      → ethnic
  mother_email       → email
  mother_address     → address
  sex 默认 "1"（女）；有明确值则用明确值
  age：可由身份证推导则覆盖

父亲 → father_customer_id：
  father_name / father_phone / father_id_card → 对应主档字段
  sex 默认 "0"（男）
  birth_ym / ethnic / email / address：协议无源字段 → 不覆盖

子女 → newborn_customer_id：
  newborn_name / newborn_id_card / newborn_sex（及若有电话）→ 对应主档
  分娩业务字段不同步到客户表

4. 同步与覆盖规则

4.1 触发

采集协议（及同源）保存，当事人快照 upsert 之后，调用扩展后的 sync_party_customers。

4.2 覆盖策略（单向 B）

规则	行为
协议源字段有值（非空串）	覆盖客户对应字段
协议源字段为空	不覆盖（保留客户原值，禁止用空串清空主档）
`customer_tags` / `remark`	协议不同步；撞库合并时标签可继续逗号并集
年龄	身份证可推导则覆盖；否则不动

4.3 身份与撞库（沿用既有链路，补新字段）

有身份证 → 租户内查客户；命中则挂接并对可映射字段执行覆盖。
已关联 ID 但身份证撞到他人 → 合并改挂（引用改挂 + 软删临时客户）后，对目标客户覆盖。
无身份证、仅有姓名 → 有关联 ID 则更新该客户；无关联则新建。

4.4 单向边界

客户管理改档 → 不修改任何协议当事人快照。
协议再次保存 → 再以本单非空字段覆盖主档（主档追「最近一次协议保存认知」）。

5. API 与前端

5.1 后端

CustomerCreateBody / CustomerUpdateBody / _row_to_dict 增加 birthYm、ethnic、email、address。
create_customer / update_customer 支持写入。
party_customer_sync：母亲写入四新字段；父亲/子女按第 3.3 节；统一「有值覆盖、空不覆盖」。
迁移 SQL：docs/sql/migrations/2026-10-08-customer-profile-expand.sql（名称以实现时为准）；模型与工程 SQL 约定对齐。

5.2 客户管理 UI

新增/编辑/查看：出生年月、民族、邮箱、家庭住址（月份选择、民族下拉可对齐协议页习惯）。
列表：姓名/性别/身份证/电话/标签等保持主列；新字段至少在查看弹窗完整展示；列表是否加列按版面实现时取舍。

5.3 协议表单

选中已有客户时：可将主档已有字段填入表单空位（便于录入）。
保存仍以表单 → 当事人快照为准，再覆盖客户。
不做主档与快照差异提示。

6. 验收

协议填全母亲扩展字段并保存 → 当事人表有快照，且对应客户主档被覆盖为相同值。
客户管理改电话 → 旧协议查看仍显示当事人表旧电话。
再保存该协议（电话为新值）→ 客户主档电话被覆盖。
协议某字段清空再保存 → 客户该字段保持原值不被清空。
客户管理可独立增改四新字段并在查看中看到。
父亲/子女同步不因协议无邮箱等源字段而误清空客户已有邮箱/住址。

7. 实现顺序建议

DB 迁移 + BizCustomer 模型 + CRUD/API/类型。
客户管理表单/查看（及可选列表列）。
扩展 party_customer_sync 覆盖逻辑与角色字段映射；补单测。
协议选人回填空位（可选增强，可与 3 同批或紧随）。
按第 6 节手工验收。

8. 决策记录

决策	选择
客户表形态	通用个人档案（A）
协议→客户	有值覆盖、空不覆盖（B）
协议快照	继续用现有当事人宽表，不拆子表（方案 1）
客户→协议	不同步
新生儿业务字段	仅当事人表

2026-10-08-customer-profile-expand-sync-design.md 7.1 KB История Исходник