Files
zkxw/docs/superpowers/specs/2026-05-18-checkup-project-package-design.md
T
2026-05-18 16:21:38 +08:00

241 lines
10 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-18
> 状态:已确认
> 父模块:中试服务管理 §2.3.6 体检机构及项目价格
> 需求来源:`docs/中科兴皖需求V0.3.md` §2.3.6(增强)、探索结论 2026-05-18
---
## 1. 背景与目标
运营在维护各体检机构的**原子项目**后,常需将多项组合成固定搭配(如「基础套餐」「全面套餐」),供后续业务人员一键选用,减少逐条勾选与漏项。
**目标**
- 在机构维度维护「套餐」:勾选多个本机构项目,可调整套餐内各行费用。
- **套餐总价 = 所含项目费用之和**(不单独维护打包价,口径简单、易解释)。
- 业务落单(中试申请单体检预约等)时**展开为明细行**写入现有 `biz_pilot_checkup_reserve_item`,不引入新的结算实体。
**非目标(首期不做)**
- 跨机构共用套餐模板库
- 套餐固定优惠价(与明细之和不一致)
- 仅保存套餐头、不展开明细的预约模型
---
## 2. 已确认业务规则
| 规则 | 说明 |
|------|------|
| 套餐总价 | **始终**为明细 `project_fee` 之和;**不存**套餐头「一口价」字段 |
| 明细价格 | 从机构项目带入默认费用后,**可在套餐内单独修改**;修改仅影响该套餐行,**不回写**机构项目主数据 |
| 套餐归属 | 仅属于一个 `checkup_institution_id`,不跨机构 |
| 项目引用 | 明细行关联 `checkup_institution_project_id`;保存时校验项目属于同一机构且未删除 |
| 停用项目 | 套餐保存/启用时:若含 `status=0` 的项目,**禁止保存或禁止启用**(二选一实现,推荐禁止保存含停用项) |
| 历史业务单 | 下游预约/实际明细为快照(名称+费用),套餐后续调价**不影响**已生成单据 |
| 名称快照 | 明细行冗余 `project_name`(与 2.3.4 项目价格体系明细一致),避免主数据改名后历史套餐展示歧义 |
| **套餐编码** | **必填**;同一机构下未删除(`del_flag=0`)的套餐编码**唯一**(应用层校验) |
| **删除机构项目** | **允许软删除**,不因被套餐引用而拦截;**不级联**删除或修改套餐明细行 |
| 删除后展示 | 套餐明细仍按行内 `project_name` / `project_fee` 快照展示;源项目已删时 UI 标注「源项目已删除」,**不影响历史查看与合计** |
### 2.1 机构项目软删除与套餐的关系
```
运营删除机构项目(del_flag=1)
│
├─► 套餐明细行:保留,不自动移除
│ 展示:project_name(快照)+ 可选标签「源项目已删除」
│ 合计:仍计入该行 project_fee(套餐定义不变)
│
├─► 编辑套餐:不可再「添加」已删除/停用的源项目;已有行可删除或改价
│
└─► Phase 2 从套餐带入预约:仅展开源项目仍有效(del_flag=0 且 status=1)的行;
已删除源项目行跳过(快照仅用于套餐档案展示)
```
与中试单预约/实际明细一致:业务单落库为快照,**机构项目删除不影响已生成业务单展示**。
---
## 3. 数据模型
### 3.1 ER 关系
```
biz_checkup_institution
│
├──1:N── biz_checkup_institution_project (原子项目,已有)
│
└──1:N── biz_checkup_institution_package (套餐头,新增)
│
└──1:N── biz_checkup_institution_package_item (套餐明细,新增)
│
└──N:1── biz_checkup_institution_project
```
### 3.2 表:`biz_checkup_institution_package`(套餐头)
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | VARCHAR(64) | 主键 UUID |
| `checkup_institution_id` | VARCHAR(64) | 所属体检机构 |
| `package_name` | VARCHAR(200) | 套餐名称(必填) |
| `package_code` | VARCHAR(64) | 套餐编码(**必填**,机构内 `del_flag=0` 唯一) |
| `status` | CHAR(1) | `1` 正常 / `0` 停用 |
| `tenant_no` … `del_flag` | — | 公共字段(见 database-conventions) |
**不建字段**:`package_fee` / `total_fee`(总价由明细汇总计算)。
### 3.3 表:`biz_checkup_institution_package_item`(套餐明细)
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | VARCHAR(64) | 主键 |
| `package_id` | VARCHAR(64) | 套餐头 ID |
| `checkup_institution_project_id` | VARCHAR(64) | 来源机构项目 ID |
| `project_name` | VARCHAR(200) | 项目名称快照(从项目带入,可展示用) |
| `project_fee` | DECIMAL(18,2) | **套餐内**项目费用(元),可编辑 |
| `tenant_no` … `del_flag` | — | 公共字段 |
**约束**
- 同一 `package_id` 下 `checkup_institution_project_id` 不重复。
- `project_fee` ≥ 0;允许为 NULL 时按 0 参与合计(建议表单必填 ≥0)。
### 3.4 API 派生字段
列表/详情响应增加只读字段(不落库):
```json
{
"totalFee": 1280.00,
"itemCount": 5
}
```
`totalFee = SUM(package_item.project_fee)`,后端计算返回。
---
## 4. 后端设计
沿用 `pilot_service.py` + `pilot_service.py` CRUD 分段模式。
### 4.1 端点
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/checkup-institutions/{institution_id}/packages` | 机构下套餐列表(含 `totalFee`、`itemCount`) |
| POST | `/checkup-institutions/{institution_id}/packages` | 新增套餐(Body 含 `items[]`) |
| GET | `/checkup-institution-packages/{package_id}` | 套餐详情 + 明细 |
| PUT | `/checkup-institution-packages/{package_id}` | 更新套餐头 + 全量替换明细(与 2.3.4 主子表保存方式一致) |
| DELETE | `/checkup-institution-packages/{package_id}` | 软删除套餐及明细 |
权限、租户隔离、数据权限与现有中试服务接口一致。
### 4.2 保存逻辑(要点)
1. 校验 `package_code`、`package_name` 非空;`package_code` 在同机构未删除套餐中唯一。
2. 校验 `items` 非空(至少 1 项)。
3. **新增/全量替换明细**时:每项 `checkup_institution_project_id` 须属于当前机构、`del_flag=0`、`status=1`。
4. **更新且明细含历史行**(源项目已软删):允许保留该行(`project_name` / `project_fee` 以 Body 或库内快照为准),不允许新增指向已删项目的行。
5. 写入明细时:`project_name` 默认取机构项目当前名称;`project_fee` 取 Body 传入值。
6. 不写入、不校验套餐头总价字段。
### 4.3 机构项目删除(`soft_delete_checkup_institution_project`)
- **不检查**套餐引用,直接软删除机构项目。
- **不修改** `biz_checkup_institution_package_item` 任意字段。
- 列表/详情 join 源项目时附带 `sourceProjectDeleted: true`(源 `del_flag=1` 或不存在时),供前端展示标签。
### 4.4 Model
在 `backend/app/models/models.py` 追加:
- `BizCheckupInstitutionPackage`
- `BizCheckupInstitutionPackageItem`
---
## 5. 前端设计(web-admin)
### 5.1 入口
在 **体检机构及项目价格** 页(`checkup-institution/index.vue`)的「项目价格配置」弹窗内增加 Tab 或并列入口:
- **Tab 1:项目列表**(现有)
- **Tab 2:套餐管理**(新增)
也可采用「套餐配置」独立按钮 + 弹窗,与「项目价格配置」同级;以不挤占单弹窗高度为准。
### 5.2 套餐列表
列:序号、套餐名称、套餐编码、项目数、**合计费用(元)**、状态、备注、操作(编辑/删除)。
合计费用列展示 API 返回的 `totalFee`(只读)。
### 5.3 套餐新增/编辑弹窗
**头部**:套餐名称(必填)、**套餐编码(必填)**、状态(正常/停用)、备注。
**明细区**(可编辑表格,对齐 `project-price-system` 明细交互):
| 操作 | 说明 |
|------|------|
| 添加项目 | 从当前机构「正常」状态项目中多选/逐条添加 |
| 删除行 | 移除明细 |
| 项目名称 | 只读展示(快照);源项目已删时后缀 muted 文案「源项目已删除」 |
| 项目费用(元) | **可编辑** `el-input-number`,默认 = 机构项目当前 `projectFee` |
| 合计 | 弹窗底部展示「套餐合计:¥ xxx.xx」= 各行费用实时求和 |
保存时提交 `items: [{ checkupInstitutionProjectId, projectName, projectFee }, ...]`,不传 `totalFee`。
### 5.4 UI 规范
- 遵循 Fresh Mint 与 `dialog-form-layout`、`form-grid-2`、列表工具栏等既有约定。
- 树/路径无涉;明细勾选来自 flat 项目列表。
---
## 6. 与下游业务对接(Phase 2)
中试申请单体检模块(`biz_pilot_checkup` + `reserve_item`)实现时:
1. 选择机构后,提供 **「从套餐添加」**:选套餐 → 将有效 `package_item` 展开为预约明细行(`project_name` + `project_fee`)。
2. **有效行**:源机构项目 `del_flag=0` 且 `status=1`;源已删/停用的套餐行**跳过**,不写入预约明细(套餐档案仍完整展示)。
3. 展开后各行仍可在预约单内微调(与 V0.3 明细模型一致)。
4. 可选:明细行增加 `source_package_id` 字段便于统计(**非首期必需**)。
---
## 7. 实现分期
| 阶段 | 范围 |
|------|------|
| **Phase 1** | 表结构 + 后端 CRUD + web-admin 套餐维护(本文 §3–5) |
| **Phase 2** | 中试申请单体检预约「从套餐添加」展开明细 |
---
## 8. SQL 增量
见 `docs/sql/checkup_institution_package.sql`(`CREATE TABLE` 两张 + 索引)。
---
## 9. 与 V0.3 / 原设计的关系
- V0.3 §2.3.6 仅定义机构级原子项目;本设计为**已确认增强**,不改变下游明细表结构。
- 模式对齐 §2.3.4「细胞产品项目价格体系」主子表,降低实现与认知成本。
---
## 10. 产品确认记录(2026-05-18 补充)
| 议题 | 结论 |
|------|------|
| 套餐编码 | **必填**;机构内未删除套餐编码唯一 |
| 删除被套餐引用的机构项目 | **允许软删除**;套餐明细**不自动移除**;靠快照保证历史展示;业务带入时跳过无效源项目 |