基础实验业务 — 功能设计文档

日期：2026-06-10
状态：已确认（2026-06-10：一产品一售卖计划）
模块：基础实验（新增一级菜单，独立于中试服务 / 临床应用）
需求来源：客户新增「基础实验」业务线（细胞产品售卖给客户做基础实验）

1. 背景与目标

1.1 业务定义

基础实验：将细胞产品售卖给客户用于基础实验。与中试服务（渠道 B 端）、临床应用（患者 C 端输注）不同，属于 B2B 一次性售卖 + 出库交付 模式。

1.2 与现有业务对比

维度	中试服务	临床应用（已隐藏）	基础实验
`biz_type`	`pilot_service`	`clinical_application`	`basic_experiment`
申请单号前缀	`ZSSQ`	`LCSQ`	`JCSY`
渠道	必选 + 服务订单扣费	选渠道，不绑订单	无
知情同意书 / 其他附件	有	有	无
标准附件	—	—	有（单上传区，图片/PDF）
患者信息	有	有	无
客户信息	走渠道	走渠道	自由填写：客户名称/联系人/联系方式
课题名称	—	—	有
方案语义	输注方案（多疗程）	输注方案（多疗程）	售卖方案（一次性多产品）
计划粒度	每疗程一条输注计划	每疗程一条输注计划	每个细胞产品一条售卖计划（独立提货时间）
产品费用	协议价/订单持仓	手填	从细胞产品价格体系带入，可修改
体检	有	无	无
缴费 / 财务确认	渠道扣费	独立缴费闭环	独立缴费闭环（同临床模式）
交付确认	有	有	有
输注确认	有	有	无
出库生产/质检工单	有	有	有
出库放行审核	有	有	有
出库交接	有	有	有

1.3 目标

在现有 biz_pilot_* 表结构与出库链路上，通过 biz_type=basic_experiment 新增第三条业务变体。
最大化复用中试/临床已验证的页面、API、出库组件；UI 文案按「售卖 / 提货 / 交付」映射，代码层可保留 infusion_* 命名。
前端采用 bizType 策略配置，避免 ApplicationFormDialog.vue 继续堆叠 if 分支。

1.4 非目标（本期不做）

客户主数据关联（biz_customer）
渠道、体检、输注确认
小程序端（若需要，另开需求）

2. 核心业务流程

基础实验申请单（JCSY，课题/客户/标准附件）
  └─ 售卖方案：多种细胞产品（价格可改）
       └─ 每个产品 → 一条售卖计划（独立提货时间）
            ├─ 自动：出库生产工单 + 出库质检工单（biz_type 继承）
            ├─ 自动：缴费记录（biz_pilot_payment，pay_status=dfj）
            ├─ 生产 / 质检执行
            ├─ 出库物料准备
            ├─ 出库交接
            ├─ 出库放行审核
            └─ 交付确认（biz_pilot_delivery，无输注确认）

2.1 售卖计划粒度（已确认）

一个申请单 对应 一个售卖方案（多产品行）。
每个细胞产品 独立生成 一条售卖计划（复用 biz_pilot_infusion_schedule），各自拥有：
- 独立 提货时间（映射 infusion_time）
- 独立费用（映射 amount，由产品价格带入后可改）
- 独立 出库生产/质检工单、缴费、交付、放行 链路

说明：与「一个批次共用一个提货时间」不同；当前采用产品级提货时间，故以「一产品一计划」驱动下游工单，避免单计划多提货时间的生产调度歧义。

3. 数据库变更

3.1 ALTER `biz_pilot_application` — 扩展 `biz_type` 与客户字段

-- biz_type 注释扩展（值域新增 basic_experiment）
ALTER TABLE biz_pilot_application
  MODIFY COLUMN biz_type VARCHAR(20) NOT NULL DEFAULT 'pilot_service'
    COMMENT '业务类型: pilot_service=中试服务, clinical_application=临床应用, basic_experiment=基础实验';

ALTER TABLE biz_pilot_application
  ADD COLUMN project_title VARCHAR(200) DEFAULT NULL COMMENT '课题名称（基础实验）' AFTER application_name,
  ADD COLUMN customer_name VARCHAR(200) DEFAULT NULL COMMENT '客户名称（基础实验，自由文本）' AFTER project_title,
  ADD COLUMN customer_contact VARCHAR(100) DEFAULT NULL COMMENT '客户联系人（基础实验）' AFTER customer_name,
  ADD COLUMN customer_phone VARCHAR(32) DEFAULT NULL COMMENT '客户联系方式（基础实验）' AFTER customer_contact;

字段使用约定（basic_experiment）

字段	用法
`channel_id` / `channel_name` / `channel_service_order_id`	留空，不校验
`consent_form_urls`	不使用
`attachment_urls`	承载标准附件（单上传区，逗号分隔 URL）
`project_title`	课题名称，必填
`customer_name` / `customer_contact` / `customer_phone`	客户信息，必填
`application_name`	可选，申请单名称

3.2 `biz_pilot_infusion_plan` — 售卖方案容器

不新增表。基础实验创建申请单时自动创建一条 biz_pilot_infusion_plan 作为售卖方案容器：

total_course_count 固定为产品行数或 1（实现时取产品行数，便于统计）
course_interval / infusion_start_date / infusion_route 留空
UI 不展示「疗程」概念

3.3 `biz_pilot_infusion_schedule` — 售卖计划（一产品一条）

复用现有表，语义映射：

DB 字段	基础实验 UI 文案
`infusion_time`	提货时间
`amount`	售卖金额（元）
`cell_type` / `spec_text`	取自产品行
`infusion_location` / `infusion_method`	不展示（可留空）
`schedule_status`	待生产 / 已生产 / 已交付 / 已取消（文案可映射为「待出库」等，码值不变）
`infusion_status`	基础实验不使用输注确认；列表/查看态映射为「—」或隐藏
`qc_status`	同中试/临床

3.4 `biz_pilot_infusion_schedule_product` — 产品明细

每条 schedule 关联一条 product 记录（一产品一计划）。价格字段：

price_id → biz_cell_product_price.id
agreement_price → 价格体系参考价（带入）
actual_price → 用户可修改的实际单价
quantity → 份数，默认 1

3.5 `biz_pilot_payment` — 缴费记录

复用 biz_pilot_payment，扩展 biz_type 支持 basic_experiment：

ALTER TABLE biz_pilot_payment
  MODIFY COLUMN biz_type VARCHAR(20) NOT NULL DEFAULT 'clinical_application'
    COMMENT '业务类型: clinical_application=临床应用, basic_experiment=基础实验';

每个售卖计划（schedule）创建时自动插入一条 pay_status=dfj 记录。
amount 取自对应 schedule 的 amount。

3.6 不使用的表（`basic_experiment`）

表	说明
`biz_pilot_patient`	不创建
`biz_pilot_checkup`	不创建
`biz_pilot_infusion_confirm`	不创建、不展示

3.7 复用的出库/交付表

表	关联键	说明
`biz_production_work_order`	`infusion_schedule_id`, `biz_type=basic_experiment`	出库生产工单
`biz_qc_work_order`	`infusion_schedule_id`, `biz_type=basic_experiment`	出库质检工单
`biz_outbound_release_review`	`infusion_schedule_id`	出库放行审核
`biz_outbound_release_material`	放行审核	出库物料
`biz_outbound_handover`	交接	出库交接
`biz_pilot_delivery`	`infusion_schedule_id`	交付确认

4. 后端 API 设计

4.1 申请单 / 售卖计划 — 扩展 `pilot_application` CRUD

文件：backend/app/crud/pilot_application.py、backend/app/api/pilot_application.py

变更点	说明
`_generate_application_no`	`biz_type=basic_experiment` → 前缀 `JCSY`
`create_application`	跳过渠道/服务订单校验；校验课题/客户/标准附件；不写 patient
`update_application`	支持 `projectTitle/customerName/customerContact/customerPhone`
`_row_to_dict_application`	输出新字段
售卖计划创建	按产品行批量创建 schedule + product + 工单 + payment
`list` / `get`	`bizType=basic_experiment` 过滤

售卖计划创建规则

用户在一个表单中维护多行产品（细胞产品、参考价、实际价、份数、提货时间）。
保存时：每个产品行 → 1 条 BizPilotInfusionSchedule + 1 条 BizPilotInfusionScheduleProduct。
每条 schedule 自动调用现有：
- create_outbound_production_work_order(..., biz_type='basic_experiment')
- create_outbound_qc_work_order(..., biz_type='basic_experiment')
- clinical_payment.auto_create_payment（扩展支持 basic_experiment）

产品选型：从 biz_cell_product_price 加载（同临床），actual_price 默认等于 unit_price，前端可改。

4.2 缴费 API — 扩展 `clinical_payment`

文件：backend/app/crud/clinical_payment.py（或重命名为 pilot_payment）、backend/app/api/clinical_payment.py

列表/详情/确认/退费接口增加 bizType 查询参数，默认不过滤；基础实验菜单请求时传 bizType=basic_experiment。
auto_create_payment：biz_type in ('clinical_application', 'basic_experiment') 时创建。
列表列：基础实验展示 课题名称、客户名称 替代患者/渠道。

4.3 出库放行审核 — 扩展 `outbound_release_review`

_BIZ_TYPE_LABELS 增加 basic_experiment: 基础实验。
列表 bizType=basic_experiment 过滤（已有模式）。
详情聚合：申请单新字段 + 售卖计划（提货时间、金额）+ 产品明细；不返回患者。

4.4 出库工单查看 — 扩展 QC / 生产 CRUD

文件：qc_work_order.py、production_work_order.py、pilot_infusion_schedule_mgmt.py

出库详情接口返回 application 时包含 projectTitle/customerName/...。
patient 对 basic_experiment 返回 null。
infusionPlan 可返回简化字段或 null（查看弹窗按 variant 决定是否展示）。

4.5 交付 API — 复用 `pilot_delivery`

不按 biz_type 限制；基础实验在申请单详情 / 售卖计划操作中进入「交付确认」。
每条 schedule 独立维护 biz_pilot_delivery（与中试一致）。
不调用 pilot_infusion_confirm 相关接口。

4.6 状态同步 — 扩展 `pilot_outbound_status_sync`

_OUTBOUND_BIZ_TYPES 增加 basic_experiment。

5. 前端设计

5.1 菜单结构

基础实验（一级菜单）
  ├── 基础实验申请单        menuCode: basic-experiment:application:list
  ├── 缴退费财务确认        menuCode: basic-experiment:payment-confirm:list
  └── 出库放行审核          menuCode: basic-experiment:outbound-release-review:list

路由模块 sqxp.ts（props.bizType: 'basic_experiment'）：

路由 name	path	组件
`BasicExperiment`	`/basic-experiment`	layout
`BasicExperimentApplication`	`application`	`pilot-application/index`
`BasicExperimentPaymentConfirm`	`payment-confirm`	`clinical-payment-confirm/index`（传 bizType）
`BasicExperimentOutboundRelease`	`outbound-release-review`	`outbound-release-review/index`

缴费信息 Tab 内嵌于申请单页（同临床），不单独做侧栏菜单；旧路径可做重定向。

5.2 申请单页 Tab 结构

Tab	组件	说明
基础实验申请单	`PilotApplicationTab`	列表 + 新增/编辑/查看
售卖计划管理	`InfusionScheduleTab`	文案改为「售卖计划」；列含提货时间、金额、缴费状态
缴费信息	`ClinicalPaymentTab` 或抽取共用 Tab	`bizType=basic_experiment`

不展示：体检 Tab、输注确认相关入口。

5.3 `bizType` 策略配置（推荐新建）

新建 web-admin/src/config/pilot-biz-type.ts（名称可调整），集中定义：

export type PilotBizType = 'pilot_service' | 'clinical_application' | 'basic_experiment'

export interface PilotBizTypeConfig {
  applicationNoPrefix: string
  showChannel: boolean
  showPatient: boolean
  showConsent: boolean
  showOtherAttachments: boolean
  showStandardAttachments: boolean
  showCheckup: boolean
  showInfusionConfirm: boolean
  showDelivery: boolean
  showPayment: boolean
  planLabel: string        // 输注方案 / 售卖方案
  scheduleLabel: string    // 输注计划 / 售卖计划
  pickupTimeLabel: string  // 输注时间 / 提货时间
  // ...
}

ApplicationFormDialog.vue、ApplicationViewDialog.vue、InfusionScheduleTab.vue 等读取配置，替代散落 isClinical。

5.4 申请单表单字段（`basic_experiment`）

申请单区块

字段	必填	说明
申请单号	自动	`JCSY` + 日期 + 序号
申请单名称	否
课题名称	是	`projectTitle`
客户名称	是	自由文本
客户联系人	是
客户联系方式	是
标准附件	否	单上传区，图片/PDF，卡片布局同规范
备注	否

隐藏：渠道、服务订单、知情同意书、其他附件、患者信息整块。

售卖方案区块（原输注方案 Tab 内）

列	说明
细胞产品	从 `biz_cell_product_price` 选择
规格	随产品带入
参考单价	只读
实际单价	可编辑，默认=参考单价
份数	默认 1
提货时间	每行独立 `datetime`
金额	可 `实际单价 × 份数` 自动算，可改（写入 schedule.amount）

保存逻辑：N 行产品 → N 条 schedule（见 §4.1）。

5.5 出库质检 / 生产工单 — 查看弹窗

扩展 outbound-qc-pilot-view-sections.ts：

export type OutboundViewContextVariant =
  | 'pilot_service'
  | 'clinical_application'
  | 'basic_experiment'

basic_experiment 展示区块

基础实验申请信息：申请单号、课题名称、客户名称、联系人、联系方式、申请单状态
售卖计划信息：提货时间、售卖金额、计划/质检状态
细胞产品明细：项目、规格、参考价、实际价、份数

不展示：患者信息、输注方案（疗程）、输注地点/方式。

使用处：

qc-work-order/OutboundQcViewDialog.vue
production-work-order/index.vue 出库查看
outbound-release-review 查看弹窗（若共用 section builder）

5.6 缴退费财务确认

复用 clinical-payment-confirm/index.vue + RefundConfirmTab.vue：

路由 props: { bizType: 'basic_experiment' }
列表 API 带 bizType=basic_experiment
表格列：申请单号、课题名称、客户名称、细胞产品、提货时间、金额、缴费状态

5.7 交付确认

复用 ApplicationDetailDialog.vue 内交付 Tab / 交付弹窗逻辑：

basic_experiment 显示「交付信息」Tab
隐藏「输注确认」Tab（若有）
交付操作粒度：按售卖计划（schedule），与中试一致

5.8 状态标签

status-tag-registry.ts 增加：

basic_experiment: { label: '基础实验', tagType: 'primary' } // 色值待定，勿与中试重复语义

6. 权限与菜单码

menuCode	菜单
`basic-experiment:application:list`	基础实验申请单
`basic-experiment:payment-confirm:list`	缴退费财务确认
`basic-experiment:outbound-release-review:list`	出库放行审核

角色授权需同步 sys_menu（SQL 迁移脚本）。

7. 实现策略与文件清单

7.1 推荐方案

biz_type 扩展 + 前端 bizType 策略配置（参见临床应用设计，避免独立建表）。

7.2 改动清单（按优先级）

优先级	层级	文件/模块
P0	SQL	`docs/sql/migrations/2026-06-10-basic-experiment.sql`
P0	Model	`backend/app/models/models.py`
P0	CRUD	`pilot_application.py`, `clinical_payment.py`
P0	API Schema	`pilot_application` Create/Update body
P0	路由	`sqxp.ts`, `menu.py`
P0	前端配置	`pilot-biz-type.ts`（新）
P0	表单/列表	`ApplicationFormDialog.vue`, `PilotApplicationTab.vue`, `InfusionScheduleTab.vue`
P1	出库查看	`outbound-qc-pilot-view-sections.ts`, QC/生产查看弹窗
P1	放行审核	`outbound-release-review/*`
P1	缴费	`clinical-payment-confirm/*`, `ClinicalPaymentTab.vue`
P1	交付	`ApplicationDetailDialog.vue`
P1	状态同步	`pilot_outbound_status_sync.py`, `outbound_release_review.py`
P2	字段一致性	`check_field_consistency.py`
P2	测试	申请单创建、多产品多计划、工单/auto payment 联动

7.3 风险与缓解

风险	缓解
`ApplicationFormDialog.vue` 过大	本期引入 `pilot-biz-type.ts` 配置；后续可拆子表单组件
`infusion_*` 命名与售卖语义不符	UI 全面使用「售卖/提货」；DB/代码保留旧名
一产品一计划导致列表行数多	售卖计划 Tab 按产品行展示，申请单列表仍按申请单聚合
缴费模块命名 `clinical_*`	API 层扩展 `bizType` 参数，暂不 rename 模块

8. 验收标准

侧栏可见「基础实验」一级菜单及三个二级菜单；临床应用仍隐藏。
可创建 JCSY 前缀申请单，填写课题/客户/标准附件，无渠道与患者字段。
售卖方案可添加多行细胞产品，每行独立提货时间与可改价格；保存后生成 N 条售卖计划。
每条售卖计划自动产生出库生产工单、出库质检工单、待缴费记录。
出库质检/生产工单「查看」弹窗展示基础实验申请信息 + 售卖计划 + 产品明细，无患者区块。
出库放行审核、出库交接、交付确认可按 schedule 正常操作。
缴费信息 + 缴退费财务确认流程与临床一致（状态机 dfj→jfqrz→yjf→tfqrz→ytf），数据按 biz_type 隔离。
中试/临床列表不出现 JCSY 申请单；基础实验列表不出现 ZSSQ/LCSQ。

9. 已确认需求摘要（2026-06-10）

问题	结论
缴费/财务确认	需要
体检	无
交付/输注确认	有交付确认，无输注确认
申请单号前缀	`JCSY`
客户信息	自由文本
售卖计划粒度	每细胞产品一个提货时间 → 一产品一售卖计划
标准附件	单上传区，图片/PDF，卡片布局
产品费用	从细胞产品价格体系带入，可修改
客户主数据	不关联

10. 后续步骤

用户审阅本 spec — 确认后进入实现计划（writing-plans）。
编写 docs/superpowers/plans/2026-06-10-basic-experiment.md 任务拆解。
按 P0 → P1 分期实现与联调。

2026-06-10-basic-experiment-design.md 19 KB Lịch sử Raw