From 22a6e1f4e44aea20a538696a65465e6478c0ee01 Mon Sep 17 00:00:00 2001 From: zlwu <704541015@qq.com> Date: Tue, 13 Oct 2026 11:04:45 +0800 Subject: [PATCH] docs: add customer-service management design and plan; note mobile follow-up. Co-authored-by: Cursor --- .../2026-10-13-customer-service-management.md | 688 ++++++++++++++++++ ...0-13-customer-service-management-design.md | 260 +++++++ 2 files changed, 948 insertions(+) create mode 100644 docs/superpowers/plans/2026-10-13-customer-service-management.md create mode 100644 docs/superpowers/specs/2026-10-13-customer-service-management-design.md diff --git a/docs/superpowers/plans/2026-10-13-customer-service-management.md b/docs/superpowers/plans/2026-10-13-customer-service-management.md new file mode 100644 index 00000000..75119f07 --- /dev/null +++ b/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 门禁。 diff --git a/docs/superpowers/specs/2026-10-13-customer-service-management-design.md b/docs/superpowers/specs/2026-10-13-customer-service-management-design.md new file mode 100644 index 00000000..46b3cba3 --- /dev/null +++ b/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;预置 + 手输回写 |