Bläddra i källkod

docs: add customer-service management design and plan; note mobile follow-up.

Co-authored-by: Cursor <cursoragent@cursor.com>
zlwu 1 månad sedan
förälder
incheckning
22a6e1f4e4

+ 688 - 0
docs/superpowers/plans/2026-10-13-customer-service-management.md

@@ -0,0 +1,688 @@
+# 客户服务管理 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 将存储服务「样本信息管理」升级为「客户服务管理」:细胞存储 Tab 对齐 Excel 客服台账宽表,样本级证/保险 + 客服字段,工具栏 6+1 登记。
+
+**Architecture:** 新表 `biz_sample_customer_service` / `biz_customer_service_dict` / `biz_sample_storage_cert` / `biz_sample_insurance`;协议级证险迁移后按样本复制;扩展 `POST /web/admin/sample-info/quick-register` 的 `kind`(保留现有 `kind`+`items` 形态,不引入平行 `action`/`sampleCodes`);列表 enrich 与前端宽表/弹窗。
+
+**Tech Stack:** MySQL 5.7 / FastAPI + SQLAlchemy / pytest / Vue 3 + Element Plus / pnpm
+
+**Design Doc:** `docs/superpowers/specs/2026-10-13-customer-service-management-design.md`
+
+**API shape note(相对 design §4.3):** 落地沿用现网 `QuickRegisterBody`:`kind`、`receptionSource`、`items[{sampleCode,protocolId}]`,并扩展可选字段;`kind` 取值增加 `sms` | `followup` | `fulfillment` | `all`。证险改为按 `sampleCode` 写入样本级表。
+
+---
+
+## File Structure Map
+
+### New files
+
+| File | Responsibility |
+|------|----------------|
+| `docs/sql/migrations/2026-10-13-customer-service-tables.sql` | 客服表 + 字典表 + 种子 |
+| `docs/sql/migrations/2026-10-13-sample-storage-cert-insurance.sql` | 样本级证/保险表 + 从协议级迁移 |
+| `docs/sql/migrations/2026-10-13-rename-sample-info-menu-to-customer-service.sql` | 菜单改名 |
+| `backend/app/crud/sample_customer_service.py` | 客服行 upsert / 批量 get |
+| `backend/app/crud/customer_service_dict.py` | 字典 list / ensure |
+| `backend/app/crud/sample_storage_cert.py` | 样本级储存证 |
+| `backend/app/crud/sample_insurance.py` | 样本级保险 |
+| `backend/app/services/sample_customer_service_register.py` | 各 kind 登记 + 空不覆盖 + 字典回写 |
+| `backend/app/api/customer_service_dict.py` | GET 字典 |
+| `backend/tests/test_sample_customer_service_register.py` | 空不覆盖、字典、all |
+| `backend/tests/test_sample_cert_insurance_sample_level.py` | 样本级证险 + 迁移幂等辅助 |
+
+### Modified files
+
+| File | Change |
+|------|--------|
+| `backend/app/models/models.py` | 四个新 Model |
+| `backend/app/api/__init__.py` / `app/main.py` | 注册字典 router |
+| `backend/app/api/protocol_sample_collection.py` | QuickRegisterBody 扩展;分发新 kind |
+| `backend/app/crud/sample_info_quick_register.py` | 证险改样本级;委托客服登记 |
+| `backend/app/services/sample_info_list_enrich.py` | 样本级证险 + 客服字段 + 材料推导 |
+| `backend/app/services/sample_info_progress.py` | 若需,样本级 handled 判定复用 |
+| `backend/app/api/menu.py` | title 客户服务管理 |
+| `backend/app/services/market_sample.py`(评估) | 证险读写改样本级或文档注明跟版 |
+| `web-admin/src/router/modules/sqxp.ts` | meta.title |
+| `web-admin/src/api/sample-info-handle.ts` | kind 与 payload 类型 |
+| `web-admin/src/api/customer-service-dict.ts` | 新建 API 封装 |
+| `web-admin/src/views/cell-storage/sample-info/UnifiedSampleInfoPage.vue` | 工具栏 + 宽表 |
+| `web-admin/src/views/cell-storage/sample-info/SampleInfoQuickRegisterDialog.vue` | 多 kind 表单 |
+| `web-admin/src/components/business/protocol-handle-panel/index.vue`(及 ProtocolViewDialog 调用处) | 按 sampleCode 样本级保存 |
+
+---
+
+### Task 1: SQL — 客服表 + 字典 + 菜单改名
+
+**Files:**
+- Create: `docs/sql/migrations/2026-10-13-customer-service-tables.sql`
+- Create: `docs/sql/migrations/2026-10-13-rename-sample-info-menu-to-customer-service.sql`
+
+- [ ] **Step 1: 写客服表 + 字典迁移**
+
+```sql
+-- 2026-10-13 客户服务:样本客服扩展表 + 租户字典
+-- 对齐 docs/superpowers/specs/2026-10-13-customer-service-management-design.md
+
+CREATE TABLE IF NOT EXISTS biz_sample_customer_service (
+  id VARCHAR(64) NOT NULL COMMENT '主键ID',
+  sample_code VARCHAR(32) NOT NULL COMMENT '样本编码',
+  collection_protocol_id VARCHAR(64) DEFAULT NULL COMMENT '采集协议单ID冗余',
+  sms_send_date DATE DEFAULT NULL COMMENT '短信发送日期',
+  sms_send_status VARCHAR(64) DEFAULT NULL COMMENT '短信发送情况',
+  microbe_followup_date DATE DEFAULT NULL COMMENT '微生物回访日期',
+  microbe_followup_status VARCHAR(64) DEFAULT NULL COMMENT '微生物回访情况',
+  fullmoon_followup_date DATE DEFAULT NULL COMMENT '满月回访时间',
+  fullmoon_followup_status VARCHAR(64) DEFAULT NULL COMMENT '满月回访情况',
+  household_registered VARCHAR(64) DEFAULT NULL COMMENT '是否上户口',
+  einvoice_send_time DATETIME DEFAULT NULL COMMENT '电子发票发送时间',
+  effective_address VARCHAR(512) DEFAULT NULL COMMENT '有效地址',
+  tenant_no VARCHAR(64) NOT NULL DEFAULT 'zkxw' COMMENT '租户编号',
+  order_num INT DEFAULT NULL COMMENT '排序号',
+  remark VARCHAR(512) DEFAULT NULL COMMENT '备注',
+  create_by VARCHAR(64) DEFAULT NULL COMMENT '创建人id',
+  create_dept_id VARCHAR(64) NOT NULL DEFAULT '' COMMENT '创建人部门ID',
+  create_time DATETIME NOT NULL COMMENT '创建时间',
+  update_by VARCHAR(64) DEFAULT NULL COMMENT '更新人id',
+  update_time DATETIME NOT NULL COMMENT '更新时间',
+  del_flag SMALLINT NOT NULL DEFAULT 0 COMMENT '删除标记',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_bscs_tenant_sample (tenant_no, sample_code, del_flag),
+  KEY idx_bscs_protocol (tenant_no, collection_protocol_id, del_flag)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='样本客户服务扩展';
+
+CREATE TABLE IF NOT EXISTS biz_customer_service_dict (
+  id VARCHAR(64) NOT NULL COMMENT '主键ID',
+  dict_type VARCHAR(64) NOT NULL COMMENT '字典类型',
+  dict_value VARCHAR(128) NOT NULL COMMENT '选项值',
+  is_system CHAR(1) NOT NULL DEFAULT '0' COMMENT '1预置 0手输',
+  tenant_no VARCHAR(64) NOT NULL DEFAULT 'zkxw' COMMENT '租户编号',
+  order_num INT DEFAULT NULL COMMENT '排序号',
+  remark VARCHAR(512) DEFAULT NULL COMMENT '备注',
+  create_by VARCHAR(64) DEFAULT NULL COMMENT '创建人id',
+  create_dept_id VARCHAR(64) NOT NULL DEFAULT '' COMMENT '创建人部门ID',
+  create_time DATETIME NOT NULL COMMENT '创建时间',
+  update_by VARCHAR(64) DEFAULT NULL COMMENT '更新人id',
+  update_time DATETIME NOT NULL COMMENT '更新时间',
+  del_flag SMALLINT NOT NULL DEFAULT 0 COMMENT '删除标记',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_bcsd_tenant_type_value (tenant_no, dict_type, dict_value, del_flag)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='客户服务字典';
+
+-- 种子:对已有租户各插一套预置(示例用 zkxw;实现时可用 INSERT…SELECT DISTINCT tenant_no FROM sys_tenant 或业务表)
+-- dict_type: sms_send_status | microbe_followup_status | fullmoon_followup_status | household_registered
+```
+
+种子插入用幂等 `INSERT IGNORE` 或 `NOT EXISTS`,值为:`已发`/`合并发`/`/`;回访两 type:`回访成功`/`无人接听`/`挂机`/`微信通知`;上户口:`是`/`否`/`未回复`。`is_system='1'`。
+
+注意:MySQL 5.7 上 `UNIQUE (tenant_no, sample_code, del_flag)` 在多次软删时可能冲突;若项目其它表用「仅 del_flag=0 唯一」的应用层保证,则改为普通索引 + 服务层唯一校验(与 `biz_sample_storage_cert_qc` 对齐即可)。
+
+- [ ] **Step 2: 写菜单改名 SQL**
+
+```sql
+-- 样本信息管理 → 客户服务管理
+-- id: 50000000000000000000000000000013
+-- perms: cell-storage:sample-info:list
+UPDATE sys_menu
+SET menu_name = '客户服务管理',
+    update_time = NOW()
+WHERE del_flag = 0
+  AND (
+    id = '50000000000000000000000000000013'
+    OR perms = 'cell-storage:sample-info:list'
+  )
+  AND menu_type = 'C'
+  AND menu_name <> '客户服务管理';
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add docs/sql/migrations/2026-10-13-customer-service-tables.sql \
+  docs/sql/migrations/2026-10-13-rename-sample-info-menu-to-customer-service.sql
+git commit -m "$(cat <<'EOF'
+docs(sql): add customer-service tables and rename sample-info menu.
+
+EOF
+)"
+```
+
+---
+
+### Task 2: SQL — 样本级储存证 / 保险 + 迁移
+
+**Files:**
+- Create: `docs/sql/migrations/2026-10-13-sample-storage-cert-insurance.sql`
+
+- [ ] **Step 1: 建表**
+
+`biz_sample_storage_cert`:在 `biz_protocol_storage_cert` 列基础上增加 `sample_code VARCHAR(32) NOT NULL`、`mail_cert_time DATETIME NULL`;唯一键按 Task 1 约定处理。
+
+`biz_sample_insurance`:从 `biz_protocol_fullmoon_todo` 轻量字段复制 + `sample_code` + `policy_send_time DATETIME NULL`(可省略保司/险种等本页不用的列,或整表对齐便于迁移)。
+
+- [ ] **Step 2: 迁移 SQL(幂等)**
+
+伪逻辑(写成真实 INSERT…SELECT):
+
+```sql
+-- 储存证:协议级 → 协议下每个未删样本一行
+INSERT INTO biz_sample_storage_cert (
+  id, sample_code, collection_protocol_id, make_status, cert_image_urls,
+  make_date, handle_time, handler_user_id, mail_cert_time,
+  tenant_no, order_num, remark, create_by, create_dept_id, create_time,
+  update_by, update_time, del_flag
+)
+SELECT
+  REPLACE(UUID(),'-',''),  -- 或应用层生成;MySQL 可用 UUID()
+  ps.sample_code,
+  c.collection_protocol_id,
+  c.make_status, c.cert_image_urls, c.make_date, c.handle_time, c.handler_user_id,
+  NULL,
+  c.tenant_no, c.order_num, c.remark, c.create_by, c.create_dept_id, NOW(),
+  c.update_by, NOW(), 0
+FROM biz_protocol_storage_cert c
+INNER JOIN biz_protocol_sample ps
+  ON ps.collection_protocol_id = c.collection_protocol_id
+ AND ps.tenant_no = c.tenant_no
+ AND ps.del_flag = 0
+WHERE c.del_flag = 0
+  AND NOT EXISTS (
+    SELECT 1 FROM biz_sample_storage_cert t
+    WHERE t.tenant_no = c.tenant_no AND t.sample_code = ps.sample_code AND t.del_flag = 0
+  );
+```
+
+保险表同理(源 `biz_protocol_fullmoon_todo`,`policy_send_time` 置 NULL)。
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add docs/sql/migrations/2026-10-13-sample-storage-cert-insurance.sql
+git commit -m "$(cat <<'EOF'
+docs(sql): add sample-level storage cert and insurance with migrate-from-protocol.
+
+EOF
+)"
+```
+
+---
+
+### Task 3: SQLAlchemy Models
+
+**Files:**
+- Modify: `backend/app/models/models.py`(插在 `BizProtocolStorageCert` / `BizProtocolFullmoonTodo` 附近)
+
+- [ ] **Step 1: 增加四个 Model 类**
+
+类名:`BizSampleCustomerService`、`BizCustomerServiceDict`、`BizSampleStorageCert`、`BizSampleInsurance`;列与 Task 1/2 SQL 一致;`__tablename__` 对应。
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add backend/app/models/models.py
+git commit -m "$(cat <<'EOF'
+feat(backend): add models for customer-service and sample-level cert/insurance.
+
+EOF
+)"
+```
+
+---
+
+### Task 4: 字典 CRUD + API(TDD)
+
+**Files:**
+- Create: `backend/app/crud/customer_service_dict.py`
+- Create: `backend/app/api/customer_service_dict.py`
+- Create: `backend/tests/test_customer_service_dict.py`
+- Modify: `backend/app/api/__init__.py`、`backend/app/main.py`
+
+- [ ] **Step 1: 写失败测试**
+
+```python
+# backend/tests/test_customer_service_dict.py
+from app.crud.customer_service_dict import ensure_dict_value, list_dict_values
+
+def test_ensure_dict_value_is_idempotent_and_returns_value():
+    # 使用 sqlite/内存或 mock Session 时按项目既有测试风格;
+    # 若无 DB fixture,先测纯函数 normalize:
+    from app.services.sample_customer_service_register import normalize_dict_value
+    assert normalize_dict_value("  已发  ") == "已发"
+    assert normalize_dict_value("") is None
+```
+
+若项目测试多为纯函数(见 `test_sample_info_handle.py`),优先把 `normalize_dict_value` / `merge_partial_fields` 放 service 并单测。
+
+- [ ] **Step 2: 实现**
+
+`list_dict_values(db, tenant_no, dict_type) -> List[str]`  
+`ensure_dict_value(db, tenant_no, dict_type, value, *, user_id, is_system=False) -> str`:trim 后若不存在则 insert。
+
+API:
+
+```python
+@router.get("/customer-service-dict")
+async def get_customer_service_dict(
+    dictType: str = Query(...),
+    db: Session = Depends(get_db),
+    user: dict = Depends(require_any_menu_code("cell-storage:sample-info:list")),
+):
+    ...
+    return success_response({"list": values})
+```
+
+- [ ] **Step 3: 跑测**
+
+```bash
+cd backend && source venv/bin/activate
+pytest tests/test_customer_service_dict.py -v
+```
+
+Expected: PASS
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add backend/app/crud/customer_service_dict.py backend/app/api/customer_service_dict.py \
+  backend/app/api/__init__.py backend/app/main.py backend/tests/test_customer_service_dict.py
+git commit -m "$(cat <<'EOF'
+feat(backend): add customer-service dict list and ensure-on-write helpers.
+
+EOF
+)"
+```
+
+---
+
+### Task 5: 客服字段 upsert + 空不覆盖(TDD)
+
+**Files:**
+- Create: `backend/app/crud/sample_customer_service.py`
+- Create: `backend/app/services/sample_customer_service_register.py`
+- Create: `backend/tests/test_sample_customer_service_register.py`
+
+- [ ] **Step 1: 写失败测试(纯函数)**
+
+```python
+from app.services.sample_customer_service_register import merge_customer_service_fields
+
+def test_merge_skips_empty_and_keeps_existing():
+    existing = {"sms_send_status": "已发", "effective_address": "合肥"}
+    incoming = {"sms_send_status": "", "effective_address": "亳州", "household_registered": "是"}
+    merged = merge_customer_service_fields(existing, incoming)
+    assert merged["sms_send_status"] == "已发"
+    assert merged["effective_address"] == "亳州"
+    assert merged["household_registered"] == "是"
+
+def test_merge_all_sections_partial():
+    existing = {"sms_send_status": "已发", "microbe_followup_status": None}
+    incoming = {"microbe_followup_status": "回访成功"}  # sms 未传
+    merged = merge_customer_service_fields(existing, incoming)
+    assert merged["sms_send_status"] == "已发"
+    assert merged["microbe_followup_status"] == "回访成功"
+```
+
+- [ ] **Step 2: 实现 merge + upsert CRUD**
+
+`upsert_by_sample_code(...)`:无行则创建,有行则只更新 merge 后有变更的列。
+
+字典字段在写入前 `ensure_dict_value`。
+
+- [ ] **Step 3: pytest 通过后 Commit**
+
+```bash
+git add backend/app/crud/sample_customer_service.py \
+  backend/app/services/sample_customer_service_register.py \
+  backend/tests/test_sample_customer_service_register.py
+git commit -m "$(cat <<'EOF'
+feat(backend): upsert sample customer-service fields with empty-skip merge.
+
+EOF
+)"
+```
+
+---
+
+### Task 6: 样本级证/保险 CRUD + 改造 quick-register 证险路径
+
+**Files:**
+- Create: `backend/app/crud/sample_storage_cert.py`
+- Create: `backend/app/crud/sample_insurance.py`
+- Modify: `backend/app/crud/sample_info_quick_register.py`
+- Modify: `backend/app/services/sample_info_progress.py`(handled 判定改为读样本行)
+- Create: `backend/tests/test_sample_cert_insurance_sample_level.py`
+
+- [ ] **Step 1: 测试「按 sample_code 批量办理,同协议两样本互不影响」**(纯函数或 crud 辅助)
+
+```python
+def test_storage_cert_handled_true_when_handle_time_set():
+    from types import SimpleNamespace
+    from app.services.sample_info_progress import storage_cert_handled
+    assert storage_cert_handled(SimpleNamespace(handle_time=object(), make_status="0", make_date=None)) is True
+    assert storage_cert_handled(None) is False
+```
+
+- [ ] **Step 2: 实现样本级 get_map / upsert_handle**
+
+字段:`handle_time`、`handler_user_id`、附件、备注、`mail_cert_time` / `policy_send_time`;空不覆盖规则与客服表一致(办理时间:若 kind 为证/保险且未传 handleTime,保持旧行为「必填」——仅 `storage`/`storage_cert`/`insurance` 在「登记该块且用户填写了办理」时必填;`all` 中证险区块全空则跳过该样本证险写入)。
+
+- [ ] **Step 3: 改 `batch_handle_storage_certs` / `batch_handle_insurance`**
+
+签名改为接收 `items: List[{sampleCode, protocolId}]`(或 sample_codes),按 sample 去重写入样本级表,**不再**按 protocol_id 去重写协议表。
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add backend/app/crud/sample_storage_cert.py backend/app/crud/sample_insurance.py \
+  backend/app/crud/sample_info_quick_register.py backend/app/services/sample_info_progress.py \
+  backend/tests/test_sample_cert_insurance_sample_level.py
+git commit -m "$(cat <<'EOF'
+feat(backend): write storage cert and insurance at sample level in quick-register.
+
+EOF
+)"
+```
+
+---
+
+### Task 7: 扩展 QuickRegisterBody + 新 kind 分发
+
+**Files:**
+- Modify: `backend/app/api/protocol_sample_collection.py`
+- Modify: `backend/app/services/sample_customer_service_register.py`(batch 入口)
+- Modify: `backend/tests/test_sample_info_handle.py`(若有)或扩展 Task 5 测试
+
+- [ ] **Step 1: 扩展 Body**
+
+```python
+class QuickRegisterBody(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+    kind: str
+    reception_source: str = Field(..., alias="receptionSource")
+    items: List[QuickRegisterItem]
+    handle_time: Optional[str] = Field(None, alias="handleTime")
+    handler_user_id: Optional[str] = Field(None, alias="handlerUserId")
+    attachments: Optional[str] = None
+    remark: Optional[str] = None
+    # 新增(均可选)
+    mail_cert_time: Optional[str] = Field(None, alias="mailCertTime")
+    policy_send_time: Optional[str] = Field(None, alias="policySendTime")
+    sms_send_date: Optional[str] = Field(None, alias="smsSendDate")
+    sms_send_status: Optional[str] = Field(None, alias="smsSendStatus")
+    microbe_followup_date: Optional[str] = Field(None, alias="microbeFollowupDate")
+    microbe_followup_status: Optional[str] = Field(None, alias="microbeFollowupStatus")
+    fullmoon_followup_date: Optional[str] = Field(None, alias="fullmoonFollowupDate")
+    fullmoon_followup_status: Optional[str] = Field(None, alias="fullmoonFollowupStatus")
+    household_registered: Optional[str] = Field(None, alias="householdRegistered")
+    einvoice_send_time: Optional[str] = Field(None, alias="einvoiceSendTime")
+    effective_address: Optional[str] = Field(None, alias="effectiveAddress")
+```
+
+- [ ] **Step 2: 分发逻辑**
+
+- `storage`:保持;仍要求 `handleTime`。
+- `storage_cert` / `insurance`:要求办理时间(与现网一致);写入样本级 + 可选 mail/policy 时间。
+- `sms` / `followup` / `fulfillment`:**不要求** `handleTime`;至少有一个业务字段非空,否则 400。
+- `all`:不要求全局 handleTime;各子块有值才写;整批一事务。
+
+仅 `reception_source == cell_storage` 允许客服/证险 kind(`storage` 仍允许科研)。
+
+- [ ] **Step 3: 手动或 pytest 覆盖 kind 校验后 Commit**
+
+```bash
+git add backend/app/api/protocol_sample_collection.py \
+  backend/app/services/sample_customer_service_register.py \
+  backend/tests/test_sample_customer_service_register.py
+git commit -m "$(cat <<'EOF'
+feat(backend): extend sample-info quick-register for sms/followup/fulfillment/all.
+
+EOF
+)"
+```
+
+---
+
+### Task 8: 列表 enrich 宽表字段
+
+**Files:**
+- Modify: `backend/app/services/sample_info_list_enrich.py`
+- Modify: 协议样本列表 `_row_to_dict` 所在 crud(保证母亲电话/身份证、父亲、宝宝、分娩、市场专员、缴费方式、协议备注、附件 URL 可被列表拿到或在 enrich 中二次查询)
+
+- [ ] **Step 1: enrich 改为按 sample_code 读样本级证/保险**
+
+替换现按 `collection_protocol_id` 查 `BizProtocolStorageCert` / `BizProtocolFullmoonTodo` 的逻辑。
+
+- [ ] **Step 2: 批量挂客服字段**
+
+对 page 内 sample_codes 查 `biz_sample_customer_service`,写入 camelCase:`smsSendDate`、`smsSendStatus`、…、`effectiveAddress`。
+
+- [ ] **Step 3: 材料齐套**
+
+- `protocolAttachmentPresent`:协议附件字段非空  
+- `insuranceDocPresent`:该样本 `insuranceHandled`  
+- `informedConsentPresent` / `healthSurveyPresent`:对应附件字段非空  
+
+(字段名以协议表实际列为准,实现时对照 `ProtocolViewDialog` / protocol `_row_to_dict`。)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add backend/app/services/sample_info_list_enrich.py \
+  backend/app/crud/protocol_sample_collection.py  # 若需扩展 list dict
+git commit -m "$(cat <<'EOF'
+feat(backend): enrich cell-storage sample list with customer-service wide columns.
+
+EOF
+)"
+```
+
+---
+
+### Task 9: 菜单文案 + 前端 API
+
+**Files:**
+- Modify: `backend/app/api/menu.py`(`meta.title`: 客户服务管理)
+- Modify: `web-admin/src/router/modules/sqxp.ts`(`CellStorageSampleInfo` 的 `meta.title`)
+- Modify: `web-admin/src/api/sample-info-handle.ts`
+- Create: `web-admin/src/api/customer-service-dict.ts`
+
+- [ ] **Step 1: 改两处 title**
+
+```ts
+title: '客户服务管理',
+menuCode: 'cell-storage:sample-info:list'
+```
+
+- [ ] **Step 2: 扩展 fetchSampleInfoQuickRegister 类型**
+
+`kind` 增加 `'sms' | 'followup' | 'fulfillment' | 'all'`;`handleTime` 改为可选;增加 mail/policy/sms/followup/fulfillment 可选字段。
+
+- [ ] **Step 3: 字典 API**
+
+```ts
+export function fetchCustomerServiceDict(dictType: string) {
+  return request.get({ url: '/web/admin/customer-service-dict', params: { dictType } })
+}
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add backend/app/api/menu.py web-admin/src/router/modules/sqxp.ts \
+  web-admin/src/api/sample-info-handle.ts web-admin/src/api/customer-service-dict.ts
+git commit -m "$(cat <<'EOF'
+feat: rename sample-info menu label and extend quick-register client API.
+
+EOF
+)"
+```
+
+---
+
+### Task 10: QuickRegister 弹窗多 kind
+
+**Files:**
+- Modify: `web-admin/src/views/cell-storage/sample-info/SampleInfoQuickRegisterDialog.vue`
+
+- [ ] **Step 1: 扩展 `QuickRegisterKind` 与标题 map**
+
+```ts
+export type QuickRegisterKind =
+  | 'storage' | 'storage_cert' | 'insurance'
+  | 'sms' | 'followup' | 'fulfillment' | 'all'
+```
+
+- [ ] **Step 2: 按 kind 显示表单区块**
+
+- storage / storage_cert / insurance:保留办理时间/人/附件/备注;cert 加邮寄时间;insurance 加保单发送时间。  
+- sms:发送日期 + 短信情况(select allow-create,options 来自 dict)。  
+- followup:微生物日期/情况、满月日期/情况、上户口。  
+- fulfillment:电子发票时间、有效地址。  
+- all:以上分区全部展示;提交时把有值字段一并传入;提示文案「未填写的项不会覆盖已有数据」。
+
+校验:storage/cert/insurance 单独登记时办理时间必填;sms/followup/fulfillment/all 按「至少一项有值」。
+
+- [ ] **Step 3: 本地手动点开各 kind 冒烟后 Commit**
+
+```bash
+git add web-admin/src/views/cell-storage/sample-info/SampleInfoQuickRegisterDialog.vue
+git commit -m "$(cat <<'EOF'
+feat(web-admin): expand sample quick-register dialog for customer-service kinds.
+
+EOF
+)"
+```
+
+---
+
+### Task 11: 列表工具栏 6+1 + Excel 宽表
+
+**Files:**
+- Modify: `web-admin/src/views/cell-storage/sample-info/UnifiedSampleInfoPage.vue`
+- Modify: `web-admin/src/App.vue`(若 `panelTitleBarTextRules` 需登记「客户服务管理」竖条标题)
+
+- [ ] **Step 1: 工具栏按钮**
+
+在「登记保险」后增加:登记短信、登记回访、登记履约、登记全部;均 `v-if="isCellStorage"`(入库对科研仍可用);调用 `openQuickRegister(kind)`。
+
+- [ ] **Step 2: 细胞存储列**
+
+按 design §5.3 增加/调整列;`储存状态` 用现有协议状态 Tag(可把列 label 改为「储存状态」或保留「协议状态」——**采用「储存状态」** 对齐 Excel);材料四列用 Tag;横向滚动依赖现有 `list-table` 宽 min-width 即可。
+
+保留预产期与采集/接收/质检/入库列。
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add web-admin/src/views/cell-storage/sample-info/UnifiedSampleInfoPage.vue web-admin/src/App.vue
+git commit -m "$(cat <<'EOF'
+feat(web-admin): customer-service toolbar and Excel-aligned wide list columns.
+
+EOF
+)"
+```
+
+---
+
+### Task 12: 协议详情办理面板改为样本级
+
+**Files:**
+- Modify: `web-admin/src/components/business/protocol-handle-panel/index.vue`(或等价)
+- Modify: `web-admin/src/views/cell-storage/protocol/ProtocolViewDialog.vue`
+- Modify: `web-admin/src/api/sample-info-handle.ts`(新增按 sampleCode 的 PUT,或复用 quick-register 单条)
+
+- [ ] **Step 1: API**
+
+优先新增:
+
+- `PUT /web/admin/sample-storage-certs/{sampleCode}`  
+- `PUT /web/admin/sample-insurances/{sampleCode}`  
+
+body 与现协议级 handle 对齐 + `mailCertTime` / `policySendTime`。权限同 sample-info。
+
+(也可详情保存直接调 `quick-register` 单 sample;二选一,推荐独立 PUT 便于详情。)
+
+- [ ] **Step 2: ProtocolViewDialog 打开办理时传入当前 `sampleCode`**,面板保存走样本级 API;展示该样本办理数据。
+
+- [ ] **Step 3: 旧协议级 PUT 标记废弃:返回 410 或内部转发「禁止双写」——实现选 **日志警告 + 仍可读旧表仅迁移用**,Web 本页不再调用。
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add backend/app/api/... web-admin/src/components/business/protocol-handle-panel \
+  web-admin/src/views/cell-storage/protocol/ProtocolViewDialog.vue \
+  web-admin/src/api/sample-info-handle.ts
+git commit -m "$(cat <<'EOF'
+feat: switch protocol view cert/insurance handle panels to sample level.
+
+EOF
+)"
+```
+
+---
+
+### Task 13: 移动端评估 + 回归测试 + 图谱
+
+**Files:**
+- Modify or note: `backend/app/services/market_sample.py`
+- Run: pytest 相关文件
+- Run: `./scripts/update-graph.sh backend`(若改了 backend 结构)
+
+- [ ] **Step 1: 检查 market_sample 是否写协议级证险**
+
+若写:同版改为样本级;若工期不够:在 design/plan 旁注「移动端跟版」,并确保新 Web 写入只打样本级表(禁止双写)。
+
+- [ ] **Step 2: 跑测试**
+
+```bash
+cd backend && source venv/bin/activate
+pytest tests/test_customer_service_dict.py \
+  tests/test_sample_customer_service_register.py \
+  tests/test_sample_cert_insurance_sample_level.py \
+  tests/test_sample_info_handle.py -v
+```
+
+Expected: PASS
+
+- [ ] **Step 3: 更新图谱**
+
+```bash
+./scripts/update-graph.sh backend
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add backend/graphify-out backend/app/services/market_sample.py  # 若有改动
+git commit -m "$(cat <<'EOF'
+chore: verify customer-service tests and refresh backend graphify.
+
+EOF
+)"
+```
+
+---
+
+## Spec coverage checklist
+
+| Spec 项 | Task |
+|---------|------|
+| 菜单改名、权限码不变 | 1, 9 |
+| 客服表 + 字典 + 手输回写 | 1, 4, 5 |
+| 样本级证/保险 + 邮寄/保单发送时间 | 2, 6, 7, 10, 12 |
+| 协议级迁移复制 | 2 |
+| 6+1 登记 + 空不覆盖 + all | 5, 7, 10, 11 |
+| 列表对齐 Excel | 8, 11 |
+| 材料齐套推导 | 8, 11 |
+| 详情样本级办理 | 12 |
+| 科研捐赠不改客服 | 7, 11 |
+| 移动端跟版/同改 | 13 |
+
+---
+
+## Self-review notes
+
+- 与 design 的差异已写明:API 继续用 `kind`/`items`,不用平行 `action`/`sampleCodes`。  
+- 唯一索引含 `del_flag` 在 MySQL 软删场景的风险已提示,实现时与 `biz_sample_storage_cert_qc` 对齐。  
+- 无 TBD 步骤;筛选 P1 不纳入本 plan 门禁。

+ 260 - 0
docs/superpowers/specs/2026-10-13-customer-service-management-design.md

@@ -0,0 +1,260 @@
+# 客户服务管理(细胞存储样本信息升级)— 设计
+
+> 日期: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`
+
+```json
+{
+  "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;预置 + 手输回写 |