300 lines
14 KiB
Markdown
300 lines
14 KiB
Markdown
# 临床应用业务 — 功能设计文档
|
||
|
||
> 日期: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`,便于权限控制
|