Просмотр исходного кода

docs: add customer profile expand and protocol overwrite sync design.

Co-authored-by: Cursor <cursoragent@cursor.com>
zlwu 1 месяц назад
Родитель
Сommit
e69ddd0d32

+ 173 - 0
docs/superpowers/specs/2026-10-08-customer-profile-expand-sync-design.md

@@ -0,0 +1,173 @@
+# 客户主档扩展 + 协议单向覆盖同步设计
+
+> 日期: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` |
+
+当事人表已具备协议侧快照能力:查看协议读当事人字段,客户管理事后改主档不会冲掉旧协议展示值。
+
+缺口:
+
+1. `biz_customer` 缺少出生年月、民族、邮箱、住址,母亲扩展信息无法进入主档。
+2. `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 身份与撞库(沿用既有链路,补新字段)
+
+1. 有身份证 → 租户内查客户;命中则挂接并对可映射字段执行覆盖。
+2. 已关联 ID 但身份证撞到他人 → 合并改挂(引用改挂 + 软删临时客户)后,对目标客户覆盖。
+3. 无身份证、仅有姓名 → 有关联 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. 验收
+
+1. 协议填全母亲扩展字段并保存 → 当事人表有快照,且对应客户主档被覆盖为相同值。
+2. 客户管理改电话 → 旧协议查看仍显示当事人表旧电话。
+3. 再保存该协议(电话为新值)→ 客户主档电话被覆盖。
+4. 协议某字段清空再保存 → 客户该字段保持原值不被清空。
+5. 客户管理可独立增改四新字段并在查看中看到。
+6. 父亲/子女同步不因协议无邮箱等源字段而误清空客户已有邮箱/住址。
+
+---
+
+## 7. 实现顺序建议
+
+1. DB 迁移 + `BizCustomer` 模型 + CRUD/API/类型。
+2. 客户管理表单/查看(及可选列表列)。
+3. 扩展 `party_customer_sync` 覆盖逻辑与角色字段映射;补单测。
+4. 协议选人回填空位(可选增强,可与 3 同批或紧随)。
+5. 按第 6 节手工验收。
+
+---
+
+## 8. 决策记录
+
+| 决策 | 选择 |
+|------|------|
+| 客户表形态 | 通用个人档案(A) |
+| 协议→客户 | 有值覆盖、空不覆盖(B) |
+| 协议快照 | 继续用现有当事人宽表,不拆子表(方案 1) |
+| 客户→协议 | 不同步 |
+| 新生儿业务字段 | 仅当事人表 |