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

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zlwuandCursor committed 2026-10-13 11:04:45 +08:00
1 parent efbf8f6ac9
commit 22a6e1f4e4
2 files changed
+948

No files matched your search

@@ -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 门禁。
@@ -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;预置 + 手输回写 |