From e69ddd0d32d0755a15cd58b4a2114492add6ba0d Mon Sep 17 00:00:00 2001
From: zlwu <704541015@qq.com>
Date: Thu, 8 Oct 2026 17:54:26 +0800
Subject: [PATCH] docs: add customer profile expand and protocol overwrite sync
 design.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 ...-08-customer-profile-expand-sync-design.md | 173 ++++++++++++++++++
 1 file changed, 173 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-10-08-customer-profile-expand-sync-design.md

diff --git a/docs/superpowers/specs/2026-10-08-customer-profile-expand-sync-design.md b/docs/superpowers/specs/2026-10-08-customer-profile-expand-sync-design.md
new file mode 100644
index 00000000..23b6eeb2
--- /dev/null
+++ b/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） |
+| 客户→协议 | 不同步 |
+| 新生儿业务字段 | 仅当事人表 |