docs: add customer profile expand and protocol overwrite sync design.
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zlwuandCursor committed
1 parent
85b315a0cf
commit
e69ddd0d32
1 file changed
+173
@@ -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） |
|
||||
| 客户→协议 | 不同步 |
|
||||
| 新生儿业务字段 | 仅当事人表 |
|
||||
Reference in new issue
Block a user