Files
zkxw/docs/superpowers/specs/2026-05-27-clinical-application-design.md
T
2026-05-28 13:05:46 +08:00

300 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 临床应用业务 — 功能设计文档
> 日期:2026-05-27
> 状态:待审阅
> 模块:中试服务管理 > 临床应用
> 需求来源:用户提出新增临床应用业务线
---
## 1. 背景与目标
### 现状
中试服务已完成完整业务闭环:渠道管理 → 渠道服务购买订单 → 中试申请单 → 体检 → 输注计划 → 出库生产/质检/放行 → 交付 → 输注确认。现需新增**临床应用**业务线。
### 临床应用 vs 中试服务差异
| 维度 | 中试服务 | 临床应用 |
|------|---------|---------|
| 渠道充值 | 渠道有充值/余额管理,从余额扣款 | 不充值,直接按次缴费 |
| 缴费主体 | 渠道方(B 端) | 患者(C 端) |
| 金额计算 | 从渠道协议产品价格自动带入 | 手动填写 |
| 缴费流程 | 嵌入渠道服务订单内部 | 独立缴费流程(参照细胞存储缴费) |
| 其他流程 | 完整链路 | **完全一致** |
### 目标
1. 在现有中试服务的表结构和代码基础上,通过 `biz_type` 字段区分两条业务线
2. 新增缴费信息/缴费确认/退费确认三个独立菜单,实现临床应用的缴费闭环
3. 最大化复用现有页面和组件,最小化代码改动
---
## 2. 数据库变更
### 2.1 ALTER `biz_pilot_application` — 新增 `biz_type` 字段
```sql
ALTER TABLE biz_pilot_application
ADD COLUMN biz_type VARCHAR(20) NOT NULL DEFAULT 'pilot_service'
COMMENT '业务类型: pilot_service=中试服务, clinical_application=临床应用'
AFTER channel_name;
-- 更新已有数据
UPDATE biz_pilot_application SET biz_type = 'pilot_service' WHERE biz_type = 'pilot_service';
```
**影响**:
- `channel_service_order_id` 对临床应用可为 NULL(不走渠道充值)
- `channel_id` 已有,临床应用直接关联渠道
- 申请单号前缀:中试 `ZSSQ`,临床应用 `LCSQ`(需调整生成逻辑)
### 2.2 ALTER `biz_pilot_infusion_schedule` — 新增 `amount` 字段
```sql
ALTER TABLE biz_pilot_infusion_schedule
ADD COLUMN amount DECIMAL(18,2) DEFAULT NULL
COMMENT '临床应用-手动填写的输注金额(中试为NULL,从协议价格计算)'
AFTER qc_status;
```
### 2.3 新建 `biz_pilot_payment` — 缴费记录表
临床采用趸交模式,一个输注计划一条缴费记录,无需主表/明细二层结构。
```sql
CREATE TABLE biz_pilot_payment (
id VARCHAR(64) NOT NULL COMMENT '主键ID',
pilot_application_id VARCHAR(64) NOT NULL COMMENT '临床申请单ID',
infusion_schedule_id VARCHAR(64) NOT NULL COMMENT '输注计划ID(唯一约束)',
biz_type VARCHAR(20) NOT NULL DEFAULT 'clinical_application' COMMENT '业务类型',
amount DECIMAL(18,2) NOT NULL COMMENT '缴费金额(手动填写)',
transfer_type VARCHAR(16) DEFAULT NULL COMMENT '转账方式: wxzz微信 zzfbzz支付宝 yhkzz银行卡 xj现金',
transfer_amount DECIMAL(18,2) DEFAULT NULL COMMENT '实际转账金额',
transfer_time DATETIME DEFAULT NULL COMMENT '转账时间',
transfer_attachments TEXT DEFAULT NULL COMMENT '转账凭证附件(逗号分隔URL)',
pay_status VARCHAR(32) NOT NULL DEFAULT 'dfj' COMMENT '缴费状态: dfj待缴费 jfqrz缴费确认中 yjf已缴费 tfqrz退费确认中 ytf已退费',
finance_confirm_attachments TEXT DEFAULT NULL COMMENT '财务确认收款附件',
finance_remark VARCHAR(512) DEFAULT NULL COMMENT '财务确认收款备注',
finance_confirm_time DATETIME DEFAULT NULL COMMENT '财务确认收款时间',
refund_amount DECIMAL(18,2) DEFAULT NULL COMMENT '退费金额',
refund_remark VARCHAR(512) DEFAULT NULL COMMENT '退费备注',
refund_attachments TEXT DEFAULT NULL COMMENT '退费附件(逗号分隔URL)',
refund_apply_by VARCHAR(64) DEFAULT NULL COMMENT '退费申请人ID',
refund_apply_time DATETIME DEFAULT NULL COMMENT '退费申请时间',
refund_finance_confirm_attachments TEXT DEFAULT NULL COMMENT '退费财务确认附件',
refund_finance_remark VARCHAR(512) DEFAULT NULL COMMENT '退费财务确认备注',
refund_finance_confirm_time DATETIME DEFAULT NULL COMMENT '退费财务确认时间',
tenant_no VARCHAR(64) NOT NULL DEFAULT 'zkxw' COMMENT '租户编号',
order_num INT(11) 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 DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
update_by VARCHAR(64) DEFAULT NULL COMMENT '更新人id',
update_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
del_flag TINYINT(4) NOT NULL DEFAULT '0' COMMENT '删除标记: 0-正常 1-已删除',
PRIMARY KEY (id),
UNIQUE KEY uk_infusion_schedule (infusion_schedule_id, del_flag),
KEY idx_pilot_app (pilot_application_id, del_flag),
KEY idx_pay_status (pay_status, del_flag),
KEY idx_tenant (tenant_no, del_flag)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='临床应用缴费记录';
```
---
## 3. 缴费状态流转
```
[dfj 待缴费] ── 市场发起缴费确认 ──→ [jfqrz 缴费确认中]
│
财务确认收款
│
▼
[yjf 已缴费]
│
市场发起退费
│
▼
[tfqrz 退费确认中]
│
财务确认退费
│
▼
[ytf 已退费]
```
复用已有状态枚举 `payStatus`(`status-tag-registry.ts`):
- `dfj` 待缴费 → `info`
- `jfqrz` 缴费确认中 → `warning`
- `yjf` 已缴费 → `success`
- `tfqrz` 退费确认中 → `warning`
- `ytf` 已退费 → `danger`
---
## 4. 后端 API 设计
新建 `backend/app/api/clinical_payment.py`,前缀 `/web/admin`。
### 4.1 缴费信息页面
| 方法 | 路径 | 功能 | 状态变更 |
|------|------|------|---------|
| GET | `/clinical-payments` | 缴费列表(按 payStatus 筛选) | — |
| GET | `/clinical-payments/{id}` | 缴费详情 | — |
| POST | `/clinical-payments/{id}/submit-receipt` | 单条缴费确认 | dfj → jfqrz |
| POST | `/clinical-payments/submit-receipt-batch` | 批量缴费确认 | dfj → jfqrz |
| POST | `/clinical-payments/{id}/submit-refund` | 发起退费(填退费金额/备注/附件) | yjf → tfqrz |
| POST | `/clinical-payments/submit-refund-batch` | 批量发起退费 | yjf → tfqrz |
### 4.2 缴费确认(财务)
| 方法 | 路径 | 功能 | 状态变更 |
|------|------|------|---------|
| GET | `/clinical-payments/receipt-pending` | 待确认收款列表(jfqrz) | — |
| GET | `/clinical-payments/receipt-confirmed` | 已确认收款列表(yjf) | — |
| POST | `/clinical-payments/{id}/confirm-receipt` | 确认收款(填财务备注/附件) | jfqrz → yjf |
### 4.3 退费确认(财务)
| 方法 | 路径 | 功能 | 状态变更 |
|------|------|------|---------|
| GET | `/clinical-payments/refund-pending` | 待确认退费列表(tfqrz) | — |
| GET | `/clinical-payments/refund-confirmed` | 已确认退费列表(ytf) | — |
| POST | `/clinical-payments/{id}/confirm-refund` | 确认退费(填财务备注/附件) | tfqrz → ytf |
### 4.4 自动创建缴费记录
当临床应用的输注计划创建时,自动在 `biz_pilot_payment` 中生成一条 `pay_status=dfj` 的缴费记录。触发点:`pilot_application.py` 中创建输注计划的 API,当 `biz_type='clinical_application'` 时自动插入。
---
## 5. 前端页面设计
### 5.1 菜单结构
```
临床应用管理(一级菜单,独立于"中试服务管理")
├── 临床申请单
├── 体检管理
├── 输注计划管理
├── 缴费信息 ← 独立菜单
├── 缴费确认(财务) ← 独立菜单
├── 退费确认(财务) ← 独立菜单
└── 出库放行审核
```
### 5.2 页面复用策略
| 菜单 | 前端页面目录 | 复用方式 |
|------|------------|---------|
| 临床申请单 | `pilot-service/pilot-application/` | 共用组件,路由 prop `bizType='clinical_application'`,隐藏渠道订单选择器 |
| 体检管理 | `pilot-service/checkup-management/` | 完全共用 |
| 输注计划管理 | `pilot-service/infusion-schedule-management/` | 共用,临床多渲染"金额"列和"缴费状态"列 |
| **缴费信息** | **新建** `pilot-service/clinical-payment-info/` | 参照 `cell-storage/payment-info/index.vue` |
| **缴费确认(财务)** | **新建** `pilot-service/clinical-payment-confirm/` | 参照 `cell-storage/payment-confirm/index.vue` |
| **退费确认(财务)** | **新建** `pilot-service/clinical-refund-confirm/` | 参照 `cell-storage/refund-confirm/index.vue` |
| 出库放行审核 | `pilot-service/outbound-release-review/` | 共用,按 `biz_type` 过滤 |
### 5.3 缴费信息页面 (`clinical-payment-info/index.vue`)
参照 `cell-storage/payment-info/index.vue`,核心结构:
- **Tab 切换**:`dfj` 待缴费 / `yjf` 已缴费(退费操作入口)
- **列表表格列**:申请单号、患者姓名、渠道名称、细胞类型/规格、输注时间、缴费金额、缴费状态、操作
- **操作按钮**:
- 待缴费 Tab:单条缴费确认、批量缴费确认
- 已缴费 Tab:单条退费、批量退费
- **缴费确认弹窗**:展示缴费明细只读信息,无需额外填写(直接提交)
- **退费弹窗**:填写退费金额(必填)+ 退费备注 + 退费附件
### 5.4 缴费确认页面 (`clinical-payment-confirm/index.vue`)
参照 `cell-storage/payment-confirm/index.vue`:
- **Tab 切换**:待确认(jfqrz)/ 已确认(yjf)
- **操作**:确认收款 → 弹窗填财务备注 + 财务附件
- **复用组件**:`ProtocolFinanceConfirmFields`(备注 + 附件上传表单)
### 5.5 退费确认页面 (`clinical-refund-confirm/index.vue`)
参照 `cell-storage/refund-confirm/index.vue`:
- **Tab 切换**:待确认(tfqrz)/ 已确认(ytf)
- **操作**:确认退费 → 弹窗展示退费申请信息(只读)+ 财务确认表单
- **复用组件**:`ProtocolFinanceConfirmFields`
### 5.6 申请单页面改造
`pilot-application/` 组件通过路由 prop `bizType` 控制行为差异:
| 字段/行为 | 中试 (`pilot_service`) | 临床 (`clinical_application`) |
|----------|----------------------|------------------------------|
| 渠道订单选择器 | 显示(必选) | **隐藏** |
| 渠道选择器 | 从订单自动带入 | **直接选择渠道** |
| 输注方案-协议价格 | 从渠道协议产品价格带入 | **不显示** |
| 输注方案-细胞产品 | 从渠道协议/服务订单持仓选择 | **从细胞价格体系**(`biz_cell_product_price`)选择,见 `2026-05-28-clinical-application-cell-product-design.md` |
| 输注计划-金额 | 不显示(从产品价格计算) | **手动填写** |
| 是否需要体检 | 患者信息可配置 | **隐藏**,固定不体检 |
| 申请单号前缀 | ZSSQ | LCSQ |
### 5.7 输注计划管理页面改造
`infusion-schedule-management/` 新增:
- 当 `bizType === 'clinical_application'` 时,表格新增"缴费金额"列和"缴费状态"列
- 缴费状态使用 `payStatusLabel` + `payStatusTagType` 渲染
---
## 6. 复用清单
### 后端复用
| 复用项 | 来源 | 说明 |
|--------|------|------|
| `pilot_application.py` | 申请单 API | 加 `biz_type` 参数过滤和差异化逻辑 |
| `pilot_checkup.py` | 体检 API | 按 `biz_type` 过滤申请单 |
| `pilot_infusion_schedule_mgmt.py` | 输注计划管理 | 共用,临床多返回金额和缴费状态 |
| `outbound_release_review.py` | 出库放行审核 | 按 `biz_type` 过滤 |
| `crud/pilot_outbound_status_sync.py` | 出库状态同步 | 共用 |
| `crud/pilot_application.py` | 申请单 CRUD | 加 `biz_type` 字段处理 |
### 前端复用
| 复用项 | 来源 | 说明 |
|--------|------|------|
| `payStatusLabel` / `payStatusTagType` | `status-tag-registry.ts` | 缴费状态枚举直接复用 |
| `ProtocolFinanceConfirmFields` | `components/business/` | 财务确认表单(备注+附件) |
| `ProtocolPaymentDetailReadonly` | `components/business/` | 缴费明细只读展示(需微调字段映射) |
| `formatMoneyDisplay` | 金额格式化工具 | 金额展示 |
| 申请单页面组件 | `pilot-application/` | 共用,通过 prop 区分行为 |
---
## 7. 改动量估算
| 层级 | 改动内容 | 工作量 |
|------|---------|--------|
| SQL | 2 个 ALTER + 1 个 CREATE TABLE | 小 |
| 后端模型 | `BizPilotApplication` + `BizPilotInfusionSchedule` 加字段 + 新增 `BizPilotPayment` | 小 |
| 后端 CRUD | 新增 `clinical_payment.py`,改造 `pilot_application.py` | 中 |
| 后端 API | 新增 `clinical_payment.py`(10 个端点),改造申请单/输注计划 API | 中 |
| 后端注册 | `api/__init__.py` + `main.py` 注册新路由 | 小 |
| 前端路由 | `sqxp.ts` 新增临床应用一级菜单 + 7 个子路由 | 小 |
| 前端页面 | 新建 3 个缴费页面,改造申请单/输注计划页面 | 中 |
| 前端 API | `business.ts` 新增 clinical payment 接口 | 小 |
---
## 8. 约束与风险
1. **`biz_type` 一致性**:所有查询必须带 `biz_type` 过滤,防止中试和临床数据混在一起
2. **缴费记录自动创建**:输注计划创建时自动生成 `dfj` 记录,需确保事务一致性
3. **`channel_service_order_id` 可空**:临床应用不走服务订单,该字段为 NULL,需确认现有代码是否有 NOT NULL 校验
4. **前端 prop 传递**:共用页面通过路由 prop 传入 `bizType`,需确保所有子组件都能正确接收
5. **权限区分**:临床应用菜单和中试服务菜单需要独立的 `menuCode`,便于权限控制