# 样本质检信息 Tab — 短信通知功能设计 > 状态:已实现 > 日期:2026-06-01 > 需求来源:样本信息管理页新增「样本质检信息」Tab,质检完成后向客户发送短信(线下复制发送) ## 1. 背景与目标 ### 1.1 现状 「样本信息管理」页面(`/#/cell-storage/sample-info`)当前有两个 Tab: | 顺序 | Tab | 能力 | |------|-----|------| | 1 | 样本接收信息 | 接收结论 + 短信提取/标记通知 | | 2 | 样本入库信息 | 入库结论 + 短信提取/标记通知 | 业务链路:**接收 → 质检 → 入库**。质检环节完成后同样需要通知客户,但当前缺少对应 Tab 与后端能力。 ### 1.2 目标 在「样本接收信息」与「样本入库信息」之间插入 **样本质检信息** Tab,交互与「样本入库信息」一致: - 筛选 + 分页列表 - 查看协议单(`ProtocolViewDialog`) - **提取短信**(复制到剪贴板) - **标记已/未通知** **关键约束**(与现有两个 Tab 一致):系统不自动发短信,仅生成内容供运营线下发送。 ### 1.3 参考实现 | 层级 | 样本入库信息(克隆源) | |------|------------------------| | 前端 Tab | `StorageEntryInfoTab.vue` | | 前端 API | `storage-entry-sms-notification.ts` | | 后端 API | `storage_entry_sms_notification.py` | | CRUD | `storage_entry_sms_notification.py` | | 通知表 | `biz_storage_entry_sms_notification` | | 业务数据源 | `biz_storage_release_review` | 设计文档参考:`docs/superpowers/specs/2025-05-23-storage-entry-sms-notification-design.md` --- ## 2. 数据范围 ### 2.1 主数据源 **`biz_qc_work_order`(质检工单)**,筛选条件: | 字段 | 值 | 说明 | |------|-----|------| | `reception_source` | `cell_storage` | 仅细胞存储协议样本,不含科研捐赠 | | `qc_biz_type` | `inbound` | 入库质检(接收后自动创建的工单类型) | | `work_order_status` | `ywc` | 工单已完成(所有质检任务均完成) | | `del_flag` | `0` | 未删除 | 不展示:`dpz`(待配置)、`ypz`(已配置未完成)、`yzf`(已作废)。 ### 2.2 质检结论(派生字段) 工单表无单一「综合结论」字段,需从 **`biz_qc_task`** 派生: ``` 若任一已完成任务的 conclusion = 'btg' → 综合结论 = 不通过 (btg) 否则(全部任务 conclusion = 'tg')→ 综合结论 = 通过 (tg) ``` 任务结论码:`tg` / `btg`(与 `status-tag-registry.ts` 中 `qcConclusion` 一致)。 ### 2.3 质检完成时间(展示字段) 取该工单下所有 `task_status = 'ywc'` 任务的 **`completed_time` 最大值**;若无则回退工单 `update_time`(状态变为 `ywc` 时更新)。 ### 2.4 关联键 与现有细胞存储跨表约定一致:**`tenant_no` + `sample_code`** 关联协议样本、当事人信息(参见 OpenSpec `api-conventions` § 细胞存储样本跨表关联键)。 联查路径: ``` BizQcWorkOrder → BizProtocolSample (sample_code + tenant_no) → BizCollectionProtocol → BizProtocolPartyCustomer → BizQcSmsNotification (懒创建,qc_work_order_id) ``` --- ## 3. 方案对比 | 方案 | 描述 | 优点 | 缺点 | 建议 | |------|------|------|------|------| | **A. 全量克隆入库短信模块(推荐)** | 新建 `biz_qc_sms_notification` 表 + CRUD + API + Tab | 与现有模式一致;隔离清晰;改动面可控 | 需新建表与 5+ 文件 | ✅ 采用 | | B. 扩展质检工单列表 API | 在 `qc_work_order` 列表加 SMS 字段 | 少一个 API 模块 | 职责混杂;权限与筛选语义不同;改动质检模块风险高 | ❌ | | C. 合并到样本接收/入库通知表 | 一张表多类型 | 表少 | 破坏现有独立表设计;联查与模板逻辑耦合 | ❌ | **推荐方案 A**:与 2025-05-23 入库短信设计同一套路,团队已有成熟模板。 --- ## 4. 后端设计 ### 4.1 新建表 `biz_qc_sms_notification` ```sql CREATE TABLE biz_qc_sms_notification ( id VARCHAR(64) NOT NULL COMMENT 'UUID主键', qc_work_order_id VARCHAR(64) NOT NULL COMMENT '关联 biz_qc_work_order.id', protocol_id VARCHAR(64) DEFAULT NULL COMMENT '冗余协议单ID', sms_content VARCHAR(500) DEFAULT NULL COMMENT '生成的短信内容', sms_notified TINYINT(1) NOT NULL DEFAULT 0 COMMENT '0=未通知 1=已通知', notified_by VARCHAR(64) DEFAULT NULL, notified_by_name VARCHAR(64) DEFAULT NULL, notified_time DATETIME DEFAULT NULL, tenant_no VARCHAR(64) DEFAULT NULL, order_num INT DEFAULT 0, remark VARCHAR(512) DEFAULT NULL, create_by VARCHAR(64) DEFAULT NULL, create_dept_id VARCHAR(64) DEFAULT NULL, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, update_by VARCHAR(64) DEFAULT NULL, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, del_flag CHAR(1) DEFAULT '0', PRIMARY KEY (id), KEY idx_qc_work_order_id (qc_work_order_id), KEY idx_tenant_no (tenant_no) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='样本质检短信通知'; ``` ### 4.2 CRUD 要点(`qc_sms_notification.py`) - **list_notifications**:联查 + 租户隔离 + `apply_data_scope` - **懒创建**:列表加载时为已完成工单自动插入 `sms_notified=0` 记录 - **toggle_notification_status**:标记已/未通知,记录操作人与时间 - **generate_sms_content**:按综合结论生成模板并持久化到 `sms_content` 列表 `_row_to_dict` 返回字段(驼峰): | 字段 | 说明 | |------|------| | id | 通知记录 ID | | qcWorkOrderId | 质检工单 ID | | collectionProtocolId | 协议单 ID | | protocolNo / protocolStatus | 协议号与状态 | | motherName / newbornName | 当事人 | | sampleCode / sampleTypeName | 样本 | | qcCompleteTime | 质检完成时间 | | qcConclusion / qcConclusionLabel | tg/btg 及中文标签 | | smsNotified / smsContent | 通知状态与内容 | ### 4.3 短信模板(初稿,待产品确认) ``` 通过:尊敬的{母亲}女士,您的样本(编码:{code})已完成质检,结果合格。如有疑问请联系客服。 不通过:尊敬的{母亲}女士,您的样本(编码:{code})质检未通过。如有疑问请联系客服。 ``` 变量:`mother_name` ← 当事人表;`code` ← 工单 `sample_code`;日期可选加入完成日期。 ### 4.4 API 端点 前缀 `/api/web/admin`: | 方法 | 路径 | 功能 | |------|------|------| | GET | `/qc-sms-notifications/list` | 分页列表 | | PUT | `/qc-sms-notifications/{id}/toggle-status` | 切换通知状态 | | POST | `/qc-sms-notifications/{id}/generate-sms` | 生成短信 | **权限码**(与样本信息管理 Tab 共用,无需新菜单): ```python require_any_menu_code( "cell-storage:sample-info:list", "cell-storage:sample-qc-info:list", # 可选:预留独立权限 ) ``` 初期建议仅 `cell-storage:sample-info:list`,与入库/接收 API 策略一致。 Query 参数: | 参数 | 说明 | |------|------| | keyword | 协议号/姓名/样本编码 | | qcConclusion | `tg` / `btg` | | smsNotified | `0` / `1` | | qcCompleteTimeStart / qcCompleteTimeEnd | 完成时间范围 | 默认时间范围:**近 30 天**(与另外两个 Tab 一致)。 --- ## 5. 前端设计 ### 5.1 Tab 入口 修改 `web-admin/src/views/cell-storage/sample-info/index.vue`: | 顺序 | key | 标题 | 图标建议 | |------|-----|------|----------| | 1 | sample-reception | 样本接收信息 | Box | | 2 | **sample-qc** | **样本质检信息** | **DocumentChecked** | | 3 | storage-entry | 样本入库信息 | FolderOpened | `VALID_TABS` 增加 `sample-qc`;样式类由 `--dual` 改为 `--triple`(三 Tab 布局)。 ### 5.2 新建组件 `web-admin/src/views/cell-storage/protocol-audit/SampleQcInfoTab.vue` (与 `SampleReceptionInfoTab` / `StorageEntryInfoTab` 同目录,便于复用) **筛选区**: | 字段 | 控件 | 绑定 | |------|------|------| | 关键词 | el-input | keyword | | 质检结论 | el-select | qcConclusion(通过 tg / 不通过 btg) | | 通知状态 | el-select | smsNotified | | 质检完成时间 | daterange | qcCompleteTimeRange | **表格列**(全部 `min-width`,居中,状态用 `el-tag`): 协议号、协议状态、母亲姓名、新生儿姓名、样本编码、样本类型、**质检完成时间**、**质检结论**、通知状态、操作(查看 / 提取短信 / 标记通知)。 **查看**:`ProtocolViewDialog`(`show-audit-history` 等同入库 Tab)。 ### 5.3 新建 API 模块 `web-admin/src/api/qc-sms-notification.ts` — 3 个函数,镜像 `storage-entry-sms-notification.ts`。 --- ## 6. 业务流程图 ```mermaid flowchart LR A[样本接收 js] --> B[创建入库质检工单] B --> C[配置并执行质检任务] C --> D{全部任务完成?} D -->|是| E[工单状态 ywc] E --> F[样本质检信息 Tab 展示] F --> G[提取短信 / 标记已通知] G --> H[运营线下发送] E --> I[后续入库放行...] ``` --- ## 7. 边界情况 | 场景 | 处理 | |------|------| | 工单 ywc 但部分任务无 conclusion | 不纳入列表,或结论显示「待确认」;实现时需明确(建议:无 conclusion 不展示) | | 科研捐赠样本 | `reception_source != cell_storage` 过滤排除 | | 出库/临时质检 | `qc_biz_type != inbound` 过滤排除 | | 缺少协议单 | 查看按钮提示,不打开弹窗 | | 旧书签 `?tab=sample-qc` | sample-info 页 onMounted 解析 query | --- ## 8. 文件清单(预估) ### 新建 | 文件 | 说明 | |------|------| | `docs/sql/biz_qc_sms_notification.sql` | 建表 DDL | | `docs/sql/migration-2026-06-01-qc-sms-notification.sql` | 增量迁移 | | `backend/app/crud/qc_sms_notification.py` | CRUD | | `backend/app/api/qc_sms_notification.py` | API | | `web-admin/src/api/qc-sms-notification.ts` | 前端 API | | `web-admin/src/views/cell-storage/protocol-audit/SampleQcInfoTab.vue` | Tab 组件 | ### 修改 | 文件 | 修改 | |------|------| | `backend/app/models/models.py` | `BizQcSmsNotification` 模型 | | `backend/app/api/__init__.py` / `main.py` | 注册路由 | | `web-admin/src/views/cell-storage/sample-info/index.vue` | 增加 Tab | | `docs/sql/zkxw.sql` | 全量基线同步 | **不做的事**:不自动发短信;不改动质检工单执行逻辑;不修改接收/入库 Tab。 --- ## 9. 待确认项(评审门禁) 1. **短信文案**:上述通过/不通过模板是否可用?是否需要包含完成日期? 2. **列表范围**:是否仅「工单已完成 ywc」?是否还需要展示「进行中 ypz」供提前通知?(建议:仅 ywc,与入库 Tab 只展示终态一致) 3. **权限**:是否沿用 `cell-storage:sample-info:list`,无需新菜单权限? --- ## 10. 工作量评估 | 模块 | 预估 | |------|------| | 后端(表+CRUD+API) | 0.5~1 天 | | 前端 Tab + API | 0.5 天 | | 联调与边界验证 | 0.5 天 | | **合计** | **约 1.5~2 天** |