cykj/zkxw

0 Fork 0

Files

T

zlwu 09afdb1d65 提交

2026-06-02 09:39:50 +08:00

11 KiB

Raw Blame History

样本质检信息 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`

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 共用，无需新菜单）：

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. 业务流程图

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. 待确认项（评审门禁）

短信文案：上述通过/不通过模板是否可用？是否需要包含完成日期？
列表范围：是否仅「工单已完成 ywc」？是否还需要展示「进行中 ypz」供提前通知？（建议：仅 ywc，与入库 Tab 只展示终态一致）
权限：是否沿用 cell-storage:sample-info:list，无需新菜单权限？

10. 工作量评估

模块	预估
后端（表+CRUD+API）	0.5～1 天
前端 Tab + API	0.5 天
联调与边界验证	0.5 天
合计	约 1.5～2 天

11 KiB Raw Blame History Unescape Escape