11 KiB
质检工单 · 用户费用摘要展示设计
日期:2026-06-12
状态:已实现
需求确认:方案 A — 当前快照(展示合同/已收/待缴/缴费状态,不含历史轨迹、不含与质检动作的联动规则)
1. 背景与目标
1.1 业务诉求
质检专员在 入库质检工单、出库质检工单 列表中处理工单时,需要快速了解关联来源单据上的 用户费用当前状态,避免在配置/执行质检时忽略欠费、待确认收款等情况。
1.2 展示范围(已确认)
| Tab | 来源 | 系统标识 | 是否展示费用 |
|---|---|---|---|
| 入库质检 | 采集协议单(细胞存储) | receptionSource = cell_storage |
是 |
| 入库质检 | 捐赠协议单(科研捐赠) | receptionSource = research_donation |
否(业务无缴费) |
| 出库质检 | 中试服务申请单 | bizType = pilot_service |
否(渠道扣费) |
| 出库质检 | 基础实验 | bizType = basic_experiment |
是 |
| 出库质检 | 临床应用 | bizType = clinical_application |
否(本期不做,架构预留) |
1.3 非目标
- 不展示费用 变更历史、操作日志、时间线
- 不根据费用状态 阻断或自动推进 质检流程
- 不在本模块 编辑 协议/申请单费用
- 不展示 质检检测自身费用(第三方检测
thirdPartyFeeTotal、任务feeAmount)——与用户协议/申请单费用分区展示,避免混淆
1.4 与现有 UI 的关系
- 列表层:新增紧凑「费用摘要条」,满足「特别关注」的扫视需求
- 查看弹窗层:补充完整只读缴费区块,可跳转来源单据详情
- 视觉对齐 Fresh Mint 规范;金额用
formatMoneyDisplay;状态用el-tag
2. 费用字段定义
2.1 入库 · 采集协议单(paymentSummary)
数据来源:biz_protocol_payment + biz_protocol_payment_detail(经 collection_protocol_id 关联)。
| 字段 | API 别名 | 说明 | 计算/口径 |
|---|---|---|---|
| 缴费模式 | payMode |
dj 趸交 / fq 分期 |
主表 |
| 缴费模式标签 | payModeLabel |
趸交 / 分期 | 后端或前端码表 |
| 合同金额 | contractAmount |
元 | 主表 contract_amount |
| 已收金额 | receivedAmount |
元 | 明细中 payStatus ∈ {yjf, jfqrz} 的 transferAmount 之和(与 ProtocolViewDialog 一致) |
| 待收金额 | pendingAmount |
元 | max(contractAmount - receivedAmount, 0),合同为空时返回 null |
| 缴费状态摘要 | statusHint |
如「已缴清」「1 期待确认」「2 期待缴费」 | 由明细 payStatus 聚合生成 |
| 整体缴费状态 Tag | overallPayStatus / overallPayStatusLabel |
用于摘要条 Tag | 见 §2.1.1 |
2.1.1 整体缴费状态(摘要 Tag 语义)
优先级从高到低:
- 存在
tfqrz(退费确认中)→ Tagwarning,文案「退费确认中」 - 存在
ytf且无其他未完结明细 → Taginfo,文案「已退费」 - 合同金额有效且
pendingAmount <= 0且不存在dfj/jfqrz→ Tagsuccess,文案「已缴清」 - 存在
jfqrz→ Tagwarning,文案「收款确认中」 - 存在
dfj→ Taginfo,文案「待缴费」 - 其他 → Tag
info,文案「—」
分期场景下 statusHint 附加明细计数,例如:「分期 · 2 期已缴 / 1 期待缴费」。
2.2 出库 · 基础实验(feeSummary)
数据来源:biz_pilot_infusion_schedule.amount(售卖金额)+ biz_pilot_payment(按 infusion_schedule_id 一对一)。
| 字段 | API 别名 | 说明 |
|---|---|---|
| 售卖金额 | saleAmount |
schedule.amount |
| 应缴金额 | paymentAmount |
BizPilotPayment.amount |
| 实收金额 | transferAmount |
已确认收款时的 transfer_amount,否则 null |
| 缴费状态 | payStatus |
dfj / jfqrz / yjf / tfqrz / ytf |
| 缴费状态标签 | payStatusLabel |
与临床应用缴费模块码表一致 |
| 缴费状态 Tag 类型 | payStatusTagType |
复用 payStatusTagType() |
无缴费记录时:paymentAmount、payStatus 等为 null,摘要展示「暂无缴费记录」。
3. 后端设计
3.1 列表 API 扩展
接口:现有 GET /web/admin/qc-work-orders(list_work_orders)
在 _enrich_list_items 流程末尾批量 enrich,避免 N+1:
入库 Tab(workOrderType=inbound)
- 收集本页工单的有效
collectionProtocolId(且receptionSource === cell_storage) - 批量查询 payment 主表 + 明细
- 为每条工单写入
paymentSummary(非 cell_storage 时为null)
出库 Tab(workOrderType=outbound)
- 收集本页
bizType === basic_experiment的infusionScheduleId - 批量查询
BizPilotPayment+ schedule.amount - 写入
feeSummary(非 basic_experiment 时为null)
新增工具函数建议位置:backend/app/crud/qc_work_order.py 或拆至 backend/app/services/qc_work_order_fee_summary.py
def build_protocol_payment_summaries(db, protocol_ids: List[str], tenant_no: str) -> Dict[str, dict]: ...
def build_basic_experiment_fee_summaries(db, schedule_ids: List[str], tenant_no: str) -> Dict[str, dict]: ...
3.2 详情 API(可选增强)
- 入库查看:现有工单详情接口增加
paymentSummary+paymentDetails(明细列表,供弹窗展开;可限制最多返回当前协议全部明细,通常 ≤ 分期期数) - 出库查看:
get_outbound_qc_detail增加feeSummary;OutboundQcViewDialog已有 schedule 区块,补充缴费只读段
本期 最低交付:列表摘要字段;详情弹窗至少与列表同级信息,推荐附带 1~3 条关键明细(分期时下一期应缴)。
3.3 数据库
无需 DDL。只读 join 现有表:
biz_protocol_payment/biz_protocol_payment_detailbiz_pilot_payment/biz_pilot_infusion_schedule
3.4 性能
- 列表 enrich 按 当前页 protocol_id / schedule_id 去重 后批量查询
- 单页默认 10~20 条,额外 1~2 次 batch query,可接受
4. 前端设计
4.1 入库 · 样本组费用摘要条
文件:web-admin/src/views/quality-inspection/qc-work-order/QcWorkOrderSampleGroup.vue
位置:.qc-sample-row__ctx 下方、工单 Tab 上方,仅当组内任一工单 receptionSource === 'cell_storage' 且存在 paymentSummary 时渲染。
布局(单行 flex,窄屏换行):
[协议费用] 趸交 · 合同 ¥28,000.00 · 已收 ¥28,000.00 · 待收 ¥0.00 · [已缴清]
- 背景:
#ecfdf5(--primary-bg),上边框与 ctx 区分 - 字体:12px,标签 muted,金额 semibold
- 右侧 Tag:
overallPayStatusLabel+ 语义色 - 点击摘要条或「查看缴费」链接:打开入库工单查看弹窗并滚动至缴费区(可选,P1)
组内多工单:费用按 collectionProtocolId 去重,同协议只展示一份(组 context 已按样本聚合)。
4.2 出库 · 基础实验卡片摘要
文件:web-admin/src/views/quality-inspection/qc-work-order/QcWorkOrderSingleCard.vue
条件:activeTypeTab === 'outbound' && row.bizType === 'basic_experiment' && row.feeSummary
位置:.qc-work-order-card__meta 末尾或独立 .qc-fee-summary 行(全宽 grid-column: 1 / -1)
[费用信息] 售卖 ¥12,000.00 · 应缴 ¥12,000.00 · [待缴费]
已缴费时追加:实收 ¥12,000.00
4.3 查看弹窗
| 场景 | 文件 | 新增区块 |
|---|---|---|
| 入库(cell_storage) | index.vue viewSections |
「协议缴费信息」:模式、合同、已收、待收、状态 Tag;分期时列 1 行下一期应缴(如有) |
| 出库(basic_experiment) | OutboundQcViewDialog.vue |
「缴费信息」:售卖、应缴、实收、状态;可复用 ClinicalPaymentSubmitReadonly 精简字段 |
跳转链接(可选 P1):
- 入库 →
/#/cell-storage/protocol并打开对应协议查看弹窗(需协议 id) - 出库 → 基础实验申请单查看(
applicationId若列表已有)
4.4 筛选修正
文件:index.vue 出库 Tab 筛选「业务类型」
补全选项:
<el-option label="基础实验" value="basic_experiment" />
与三种出库来源一致。
4.5 API 类型
文件:web-admin/src/api/qc-work-order.ts
export type QcProtocolPaymentSummary = {
payMode?: string
payModeLabel?: string
contractAmount?: number | null
receivedAmount?: number | null
pendingAmount?: number | null
statusHint?: string
overallPayStatus?: string
overallPayStatusLabel?: string
}
export type QcBasicExperimentFeeSummary = {
saleAmount?: number | null
paymentAmount?: number | null
transferAmount?: number | null
payStatus?: string
payStatusLabel?: string
}
// QcWorkOrder 扩展
paymentSummary?: QcProtocolPaymentSummary | null
feeSummary?: QcBasicExperimentFeeSummary | null
4.6 公共组件(可选)
若入库/出库摘要条样式一致,可抽 QcWorkOrderFeeSummaryBar.vue(props: variant: 'inbound-protocol' | 'outbound-basic' + summary object)。非必须,首版可在两处各写 scoped 块,YAGNI。
5. 交互与空态
| 情况 | 展示 |
|---|---|
| 科研捐赠入库工单 | 不渲染费用区块 |
| 中试/临床出库工单 | 不渲染费用区块 |
| 采集协议无 payment 主表 | 摘要:「暂无缴费信息」 |
| 基础实验无 payment 记录 | 摘要:「暂无缴费记录」;仍展示售卖金额(若有) |
| 金额为 null | 显示 — |
只读:摘要区无编辑、无确认收款按钮。
6. 测试要点
6.1 入库
- 细胞存储样本组显示协议费用摘要,数值与采集协议单查看弹窗一致
- 科研捐赠样本组不显示费用摘要
- 趸交已缴清 / 分期部分待缴 / 收款确认中 / 退费确认中 Tag 正确
- 同页多条工单同协议,摘要去重一致
6.2 出库
- 基础实验卡片显示售卖 + 缴费状态
- 中试服务、临床应用卡片无费用摘要
- 筛选「基础实验」可正确过滤
- 查看弹窗缴费区与列表摘要一致
6.3 回归
- 第三方检测费用展示不受影响
- 临时质检 Tab 无费用区块
- 列表分页、分组、Tab 切换正常
7. 影响文件清单
| 层级 | 文件 |
|---|---|
| 后端 | backend/app/crud/qc_work_order.py(+ 可选 services/qc_work_order_fee_summary.py) |
| 后端 Schema | backend/app/schemas/qc_work_order.py(若响应体走 Pydantic) |
| 前端 API | web-admin/src/api/qc-work-order.ts |
| 前端页面 | QcWorkOrderSampleGroup.vue、QcWorkOrderSingleCard.vue、index.vue、OutboundQcViewDialog.vue |
| 工具 | 复用 formatMoneyDisplay、payModeLabel、payStatusLabel、payStatusTagType |
8. 后续扩展(本期不做)
- 临床应用出库工单费用摘要(
feeSummary结构可复用BizPilotPayment) - 摘要条点击跳转来源单据
- 与「分期缴费用户预警」模块联动高亮欠费
9. 决策记录
| 日期 | 决策 |
|---|---|
| 2026-06-12 | 「费用变化」= 当前快照,不做历史轨迹 |
| 2026-06-12 | 入库仅 采集协议单;出库仅 基础实验 |
| 2026-06-12 | 列表摘要 + 查看弹窗详情,推荐实现路径 |