zkxw/docs/superpowers/specs/2026-10-13-customer-service-management-design.md

客户服务管理（细胞存储样本信息升级）— 设计

日期：2026-10-13
状态：Web 主路径已落地（2026-10-13）；移动端 market_sample 证险仍写协议级，明确跟版、禁止与样本级双写新入口
参考：中科兴皖采集大表20260720.xlsx sheet「客户服务管理」；现状页 web-admin/src/views/cell-storage/sample-info/UnifiedSampleInfoPage.vue
关联：docs/superpowers/specs/2026-10-05-unified-sample-info-design.md（统一样本信息；本设计在其细胞存储 Tab 上扩展，并将证/保险改为样本级）

---

1. 背景与目标

1.1 背景

Excel「客户服务管理」是市场客服运营台账：短信 → 回访 → 上户口 → 保险/发票/邮寄证 → 材料齐套。
现状「存储服务 → 样本信息管理」是样本进度 + 证/保险协议级轻量办理，缺少短信/回访/上户口/履约时间线等字段，列表也未对齐 Excel 宽表。

1.2 目标

1. 菜单显示名改为「客户服务管理」（权限码不变）。
2. 细胞存储 Tab：列表尽量对齐 Excel 全列（除「序号」）；横向滚动。
3. 工具栏 6+1 登记：入库 / 储存证 / 保险 / 短信 / 回访 / 履约 + 登记全部；交互与现有快捷登记一致（勾选 → 弹窗 → 批量保存）。
4. 客服字段与证/保险办理（含邮寄储存证时间、保单发送时间）均为样本级（tenant_no + sample_code）。
5. 四套租户字典，支持手输并回写字典。

1.3 非目标

• 科研捐赠 Tab 客服台账 / 证险样本级改造。
• 权限码、路由 path 重命名。
• 独立「字典管理」菜单页。
• 恢复历史短信提取 Tab；恢复保司/险种/保单号等完整险种录入。
• Excel 导入导出客户服务大表。
• 在本页改采集 / 接收 / 质检 / 入库业务状态（进度 Tag 只读保留）。

---

2. Excel 字段映射（细胞存储）

Excel 字段	系统处理
实验室流转编码	已有（实验室入库编码 / labStorageCode）
储存状态	协议单状态（非样本进度）
序号	不要（表格可用 UI index，非业务序号）
发送日期、短信发送情况	样本客服表；【登记短信】
协议编号	列表对应位展示 样本编码；列头文案用「样本编码」
母亲/父亲 姓名、电话、身份证	已有（列表展开展示）
微生物回访日期/情况、满月回访时间/情况、是否上户口	样本客服表；【登记回访】
宝宝姓名/身份证/性别、分娩时间	已有
购买保险时间	样本级保险办理 handle_time
保单发送时间	样本级保险新字段；【登记保险】
电子发票发送时间、有效地址	样本客服表；【登记履约】
邮寄储存证时间	样本级储存证新字段；【登记储存证】
市场专员、缴费方式、备注	已有（备注＝协议备注）
协议书	协议附件是否有
保险单	该样本保险已办理即为有
知情同意书 / 健康调查表	知情同意书附件 / 孕妇健康调查表附件

额外保留（Excel 无，业务需要）：预产期；采集/接收/质检/入库进度 Tag。

---

3. 数据模型

3.1 biz_sample_customer_service

关联键：tenant_no + sample_code；冗余 collection_protocol_id。
未删除行唯一索引：(tenant_no, sample_code)。

业务字段（公共字段按 database-conventions）：

列	说明
sms_send_date	发送日期
sms_send_status	短信发送情况
microbe_followup_date	微生物回访日期
microbe_followup_status	微生物回访情况
fullmoon_followup_date	满月回访时间
fullmoon_followup_status	满月回访情况
household_registered	是否上户口
einvoice_send_time	电子发票发送时间
effective_address	有效地址 VARCHAR(512)

日期/时间列类型约定：纯日期用 DATE（或与库内一致的 CHAR(8) YYYYMMDD，实现计划与现有协议日期风格统一二选一）；含时分的办理类继续用 DATETIME（与现 handle_time 一致）。mail_cert_time / policy_send_time / einvoice_send_time 默认 DATETIME（允许只选日期、时间 00:00:00）。

3.2 样本级储存证 / 保险

新建（实现计划可微调表名，语义不变）：

• biz_sample_storage_cert：对齐现 biz_protocol_storage_cert 轻量办理字段 + sample_code + mail_cert_time（邮寄储存证时间）。
• biz_sample_insurance：对齐现保险轻量办理字段（handle_time、handler_user_id、insurance_attachments、handle_remark、todo_status 等）+ sample_code + policy_send_time（保单发送时间）。

已办理判定（样本级）：handle_time 非空；兼容迁移数据上 make_status/todo_status = 1 或旧日期非空（与统一样本信息设计一致，维度改为样本）。

旧表 biz_protocol_storage_cert / biz_protocol_fullmoon_todo：迁移后本功能停止写入；可短期保留只读兼容，不以协议级作为客户服务页数据源。

3.3 迁移

对每条未删除协议级证/保险：取同租户协议下全部 del_flag=0 协议样本，按 sample_code 各复制一行到样本级表（办理字段相同；mail_cert_time / policy_send_time 为空）。
幂等：目标已存在 (tenant_no, sample_code) 则跳过。

3.4 biz_customer_service_dict

列	说明
dict_type	sms_send_status | microbe_followup_status | fullmoon_followup_status | household_registered
dict_value	选项文案
is_system	预置=1，手输=0

唯一：(tenant_no, dict_type, dict_value)（del_flag=0）。

预置种子（Excel 样例）：

• 短信：已发、合并发、/（表示未发或无需）
• 微生物/满月回访：回访成功、无人接听、挂机、微信通知（满月常用；两套字典可共用种子，手输分 type 隔离）
• 上户口：是、否、未回复

登记手输新值：先 upsert 字典，再写业务字段。无独立字典管理页。

---

4. API 契约

4.1 权限

一律要求 cell-storage:sample-info:list（与现列表/快捷登记一致）。

4.2 列表

扩展 GET /web/admin/protocol-sample-collections/list：enrich 客服字段、样本级证/保险、材料齐套布尔/文案、协议状态作「储存状态」、父母证件与电话等宽表所需字段。

4.3 登记

扩展现有：

POST /web/admin/sample-info/quick-register

{
  "action": "storage | storage_cert | insurance | sms | followup | fulfillment | all",
  "sampleCodes": ["..."],
  "payload": { }
}

action	写入	payload 要点
storage	现状入库	不变
storage_cert	样本级证	办理字段 + mailCertTime
insurance	样本级保险	办理字段 + policySendTime
sms	客服表	smsSendDate、smsSendStatus
followup	客服表	微生物/满月日期与情况、householdRegistered
fulfillment	客服表	einvoiceSendTime、effectiveAddress
all	合并	分区块；空字段不覆盖

规则：

• 仅细胞存储样本；按 sampleCode 去重写入（证险不再按协议去重）。
• null / '' / 未传字段：不更新该列。
• 附件：未传不改；传 [] 清空。
• 整批同一事务：任一样本失败则整批回滚；错误信息含 sampleCode。

4.4 字典

GET /web/admin/customer-service-dict?dictType= → 预置 + 本租户手输列表。

4.5 旧协议级办理 API / 移动端

• Web 客户服务页、快捷登记、协议详情办理面板（从本页打开时）：改为样本级（按当前行 sampleCode）。
• 旧 PUT .../storage-certs/{protocolId}、.../fullmoon-todos/{protocolId}/handle：废弃或仅兼容；不得再作为本页主路径。
• market_sample 等移动端办理：实现计划中评估同版改造；若跟不上，标注「移动端跟版」，禁止协议级与样本级双写新数据。

---

5. 前端

5.1 菜单

• SQL：sys_menu 中样本信息管理显示名 →「客户服务管理」（id / cell-storage:sample-info:list）。
• 同步：web-admin/src/router/modules/sqxp.ts、backend/app/api/menu.py 的 meta.title。
• path / component / menuCode 不变。

5.2 工具栏（细胞存储）

「已选 N 项」最前；仅「登记入库」为 type="primary"。其后：登记储存证、登记保险、登记短信、登记回访、登记履约、登记全部。
无勾选禁用。按钮过多时可第二行或「更多」；登记全部保持可见。

科研捐赠：不增加客服登记按钮；入库逻辑不变。

5.3 列表列（细胞存储）

对齐 Excel（无业务序号列），横向滚动。建议顺序：

实验室流转编码 → 储存状态（协议状态 Tag）→ 发送日期 → 短信发送情况 → 样本编码 → 母亲姓名/电话/身份证 → 父亲姓名/电话/身份证 → 微生物回访日期/情况 → 满月回访时间/情况 → 是否上户口 → 宝宝姓名/身份证/性别 → 分娩时间 → 购买保险时间 → 保单发送时间 → 电子发票发送时间 → 邮寄储存证时间 → 有效地址 → 市场专员 → 缴费方式 → 备注 → 协议书 / 保险单 / 知情同意书 / 健康调查表 →（保留）预产期与采集/接收/质检/入库 Tag → 操作。

材料四列：推导 Tag（有/无），不可列表内编辑。

5.4 登记弹窗

扩展 SampleInfoQuickRegisterDialog（或等价组件）：

• 各 action 对应字段见 §4.3；all 分区展示，提示「空白不覆盖已有」。
• dialog-form-layout、label-position="top"；证/保险附件卡片化。
• 字典字段：el-select + filterable + allow-create（或等价可手输）。

5.5 详情

查看仍打开 ProtocolViewDialog；证/保险办理改为当前样本维度。列表主路径以快捷登记为准。

5.6 筛选（P1 可选）

关键词保持；可选增加短信情况、是否上户口、样本级证/保险已办理。非第一期门禁。

---

6. 验收要点

1. 侧栏显示「客户服务管理」，原权限角色无需重配。
2. 细胞存储宽表列齐备；储存状态=协议状态；样本编码列正确。
3. 6+1 登记行为正确；空不覆盖；登记全部可部分填写。
4. 同协议多样本证/保险可分别已办/未办。
5. 迁移幂等；历史协议级数据出现在各样本行。
6. 字典预置可选，手输后同租户同 type 可选到。
7. 材料四列推导正确。
8. 科研捐赠 Tab 无回归。

---

7. 风险

风险	缓解
证险协议→样本改动面大	Web 本页先切样本级；移动端同版评估或明确跟版、禁止双写
宽表难用	第一期按 Excel；后续可做列显示配置
手输字典脏数据	仅本租户；暂不提供删除 UI

---

8. 主要改动面（实现时拆任务）

区域	路径（示意）
SQL	docs/sql/migrations/2026-10-13-customer-service-*.sql（建表、字典种子、菜单改名、证险迁移）
Model/CRUD/Service	biz_sample_customer_service、样本级证/保险、dict、quick-register 扩展、list enrich
API	protocol_sample_collection / 新 router；废弃协议级办理主路径
Web	UnifiedSampleInfoPage.vue、SampleInfoQuickRegisterDialog.vue、办理面板样本维度、菜单文案
测试	迁移幂等、各 action 空不覆盖、样本级证险、字典 upsert

---

9. 决策记录

决策	结论
实现方案	样本客服扩展表 + 证/保险样本级表（方案 1）
登记交互	勾选 → 上方按钮 → 弹窗批量
按钮	6+1（含登记全部）
粒度	客服字段与证险办理均为样本级
迁移	协议级按样本复制后只维护样本级
列表	对齐 Excel 全列（除序号）
菜单	改显示名；权限码不变
字典	租户 + 四 type；预置 + 手输回写