提交
This commit is contained in:
1 parent
2a4767a014
commit
f269a994f4
61 files changed
+27430
-8
No files matched your search
@@ -0,0 +1,359 @@
|
||||
# 中试服务管理 — 6 模块实现设计规格
|
||||
|
||||
> 日期: 2026-05-17
|
||||
> 状态: DRAFT
|
||||
> 需求来源: `docs/中科兴皖需求V0.3.md` §2.3
|
||||
|
||||
---
|
||||
|
||||
## 1. 概述
|
||||
|
||||
一次性实现中试服务管理下 6 个基础数据管理模块,涵盖后端 API、前端页面、路由和菜单配置。数据库表已全部建好(`docs/sql/zkxw.sql`),无数据。
|
||||
|
||||
### 模块清单
|
||||
|
||||
| # | 模块 | 表 | 前端模板 | 复杂度 |
|
||||
|---|------|-----|----------|--------|
|
||||
| 2.3.1 | 细胞产品类型管理 | `biz_cell_product_type` | `unit/index.vue` | 简单 CRUD |
|
||||
| 2.3.2 | 细胞产品规格管理 | `biz_cell_product_spec` | `unit/index.vue` | 简单 CRUD |
|
||||
| 2.3.3 | 细胞产品价格体系管理 | `biz_cell_product_price` | `unit/index.vue` | 中等 — 含下拉关联 |
|
||||
| 2.3.4 | 细胞产品项目价格管理 | `biz_cell_product_project_system` + `biz_cell_product_project_system_item` | `category/index.vue` | 较复杂 — 主子表 |
|
||||
| 2.3.5 | 渠道信息管理 | `biz_channel` + 4 张子表 | `product/index.vue` | 复杂 — 多 tab + 子表 |
|
||||
| 2.3.6 | 体检机构及项目价格 | `biz_checkup_institution` + 2 张子表 | `category/index.vue` | 较复杂 — 主子表 |
|
||||
|
||||
### 实现顺序
|
||||
|
||||
```
|
||||
2.3.1 → 2.3.2 → 2.3.3 → 2.3.4 → 2.3.6 → 2.3.5
|
||||
```
|
||||
|
||||
理由:2.3.3 依赖 2.3.1/2.3.2 的下拉数据;2.3.4 依赖 2.3.3;2.3.5 渠道协议价格引用 2.3.1/2.3.2/2.3.3。
|
||||
|
||||
---
|
||||
|
||||
## 2. 架构决策
|
||||
|
||||
| 决策 | 选择 | 理由 |
|
||||
|------|------|------|
|
||||
| 后端路由文件 | `backend/app/api/pilot_service.py` 单文件 | 6 模块关联紧密,跟随 `basic_info.py` 模式 |
|
||||
| 后端 CRUD 文件 | `backend/app/crud/pilot_service.py` 单文件 | 与路由文件对应 |
|
||||
| 后端 Model | 在 `backend/app/models/models.py` 中追加 | 遵循现有单文件模式 |
|
||||
| 前端 API | 在 `web-admin/src/api/admin.ts` 中追加 | 遵循现有模式 |
|
||||
| 前端页面目录 | `web-admin/src/views/pilot-service/{module}/index.vue` | 独立一级路由 |
|
||||
| 前端路由 | `web-admin/src/router/modules/sqxp.ts` 中追加 | 现有中试服务路由位置 |
|
||||
| 菜单 SQL | `docs/sql/sys_menu_pilot_service.sql` | 独立增量 SQL |
|
||||
| 渠道协议价格来源 | 同时支持价格体系(2.3.3)和项目价格体系(2.3.4) | 用户确认,方便渠道自由组合 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 后端设计
|
||||
|
||||
### 3.1 Model(`backend/app/models/models.py`)
|
||||
|
||||
在文件末尾追加 13 个 SQLAlchemy Model 类。所有 Model 遵循现有模式:
|
||||
|
||||
```
|
||||
id → 业务字段 → tenant_no, order_num, remark, create_by, create_dept_id, create_time, update_by, update_time, del_flag
|
||||
```
|
||||
|
||||
新增 Model 清单:
|
||||
|
||||
1. `BizCellProductType` — `biz_cell_product_type`
|
||||
2. `BizCellProductSpec` — `biz_cell_product_spec`
|
||||
3. `BizCellProductPrice` — `biz_cell_product_price`
|
||||
4. `BizCellProductProjectSystem` — `biz_cell_product_project_system`
|
||||
5. `BizCellProductProjectSystemItem` — `biz_cell_product_project_system_item`
|
||||
6. `BizChannel` — `biz_channel`
|
||||
7. `BizChannelAgreement` — `biz_channel_agreement`
|
||||
8. `BizChannelAgreementProductPrice` — `biz_channel_agreement_product_price`
|
||||
9. `BizChannelInvoice` — `biz_channel_invoice`
|
||||
10. `BizChannelMailAddress` — `biz_channel_mail_address`
|
||||
11. `BizCheckupInstitution` — `biz_checkup_institution`
|
||||
12. `BizCheckupInstitutionInvoice` — `biz_checkup_institution_invoice`
|
||||
13. `BizCheckupInstitutionProject` — `biz_checkup_institution_project`
|
||||
|
||||
### 3.2 CRUD(`backend/app/crud/pilot_service.py`)
|
||||
|
||||
单文件,按模块分段组织,每段包含:
|
||||
|
||||
- `_row_to_dict_xxx()` — 转换为 camelCase 字典
|
||||
- `list_xxx()` — 分页列表 + keyword 搜索 + tenant_no 过滤
|
||||
- `get_xxx()` — 单条查询
|
||||
- `xxx_code_exists()` — 唯一性校验(编码字段)
|
||||
- `create_xxx()` — 新增
|
||||
- `update_xxx()` — 更新
|
||||
- `soft_delete_xxx()` — 软删除
|
||||
|
||||
子表额外函数:
|
||||
- `list_xxx_items(parent_id)` — 按 parent_id 查子表列表
|
||||
- `create_xxx_item()` / `update_xxx_item()` / `soft_delete_xxx_item()` — 子表 CRUD
|
||||
|
||||
### 3.3 Route(`backend/app/api/pilot_service.py`)
|
||||
|
||||
单文件,`APIRouter(prefix="/web/admin", tags=["中试服务管理"])`。
|
||||
|
||||
每个实体提供 4 个标准端点:
|
||||
|
||||
| 方法 | 路径 | 说明 | 权限 |
|
||||
|------|------|------|------|
|
||||
| GET | `/cell-product-types` | 分页列表 | `require_menu_code` |
|
||||
| POST | `/cell-product-types` | 新增 | `require_admin_or_super_admin` |
|
||||
| PUT | `/cell-product-types/{id}` | 更新 | `require_admin_or_super_admin` |
|
||||
| DELETE | `/cell-product-types/{id}` | 删除 | `require_admin_or_super_admin` |
|
||||
|
||||
子表额外端点(如项目价格体系明细、渠道子表等):
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/cell-product-project-systems/{id}/items` | 获取子表明细 |
|
||||
| POST | `/cell-product-project-systems/{id}/items` | 新增子表行 |
|
||||
| PUT | `/project-system-items/{id}` | 更新子表行 |
|
||||
| DELETE | `/project-system-items/{id}` | 删除子表行 |
|
||||
|
||||
Pydantic Body Model 定义在路由文件内部,使用 `alias` 支持 camelCase。
|
||||
|
||||
渠道信息管理(2.3.5)因其复杂度,需要以下额外端点:
|
||||
- 渠道基础信息 CRUD(含渠道协议附件上传)
|
||||
- 渠道开票信息 CRUD(子表)
|
||||
- 渠道邮寄地址 CRUD(子表)
|
||||
- 渠道协议 CRUD(子表,含状态变更:生效/作废)
|
||||
- 渠道协议-产品价格 CRUD(协议的子表)
|
||||
- 协议状态变更端点:`PUT /channel-agreements/{id}/activate` 和 `PUT /channel-agreements/{id}/void`
|
||||
|
||||
### 3.4 路由注册
|
||||
|
||||
1. `backend/app/api/__init__.py` — 添加 `from app.api.pilot_service import router as pilot_service_router` + `__all__`
|
||||
2. `backend/app/main.py` — `from app.api import ..., pilot_service_router` + `app.include_router(pilot_service_router, prefix=settings.API_V1_PREFIX)`
|
||||
|
||||
---
|
||||
|
||||
## 4. 前端设计
|
||||
|
||||
### 4.1 API 函数(`web-admin/src/api/admin.ts`)
|
||||
|
||||
追加以下 API 函数(每个实体 4 个:list / create / update / delete):
|
||||
|
||||
```
|
||||
// 2.3.1 细胞产品类型
|
||||
fetchCellProductTypeList / fetchCreateCellProductType / fetchUpdateCellProductType / fetchDeleteCellProductType
|
||||
|
||||
// 2.3.2 细胞产品规格
|
||||
fetchCellProductSpecList / fetchCreateCellProductSpec / fetchUpdateCellProductSpec / fetchDeleteCellProductSpec
|
||||
|
||||
// 2.3.3 细胞产品价格体系
|
||||
fetchCellProductPriceList / fetchCreateCellProductPrice / fetchUpdateCellProductPrice / fetchDeleteCellProductPrice
|
||||
|
||||
// 2.3.4 细胞产品项目价格体系
|
||||
fetchProjectSystemList / fetchCreateProjectSystem / fetchUpdateProjectSystem / fetchDeleteProjectSystem
|
||||
fetchProjectSystemItems / fetchCreateProjectSystemItem / fetchUpdateProjectSystemItem / fetchDeleteProjectSystemItem
|
||||
|
||||
// 2.3.5 渠道信息
|
||||
fetchChannelList / fetchCreateChannel / fetchUpdateChannel / fetchDeleteChannel
|
||||
fetchChannelInvoices / fetchCreateChannelInvoice / fetchUpdateChannelInvoice / fetchDeleteChannelInvoice
|
||||
fetchChannelMailAddresses / fetchCreateChannelMailAddress / fetchUpdateChannelMailAddress / fetchDeleteChannelMailAddress
|
||||
fetchChannelAgreements / fetchCreateChannelAgreement / fetchUpdateChannelAgreement / fetchDeleteChannelAgreement
|
||||
fetchChannelAgreementPrices / fetchCreateChannelAgreementPrice / fetchUpdateChannelAgreementPrice / fetchDeleteChannelAgreementPrice
|
||||
fetchActivateChannelAgreement / fetchVoidChannelAgreement
|
||||
|
||||
// 2.3.6 体检机构
|
||||
fetchCheckupInstitutionList / fetchCreateCheckupInstitution / fetchUpdateCheckupInstitution / fetchDeleteCheckupInstitution
|
||||
fetchCheckupInstitutionInvoices / fetchCreateCheckupInstitutionInvoice / ...
|
||||
fetchCheckupInstitutionProjects / fetchCreateCheckupInstitutionProject / ...
|
||||
```
|
||||
|
||||
### 4.2 页面文件
|
||||
|
||||
```
|
||||
web-admin/src/views/pilot-service/
|
||||
├── cell-product-type/index.vue # 2.3.1 — 复制 unit/index.vue
|
||||
├── cell-product-spec/index.vue # 2.3.2 — 复制 unit/index.vue
|
||||
├── cell-product-price/index.vue # 2.3.3 — 复制 unit/index.vue,表单含下拉关联
|
||||
├── project-price-system/index.vue # 2.3.4 — 复制 category/index.vue,主子表
|
||||
├── channel/index.vue # 2.3.5 — 复制 product/index.vue,多 tab + 子表
|
||||
└── checkup-institution/index.vue # 2.3.6 — 复制 category/index.vue,主子表
|
||||
```
|
||||
|
||||
### 4.3 页面详细设计
|
||||
|
||||
#### 2.3.1 细胞产品类型管理(简单 CRUD)
|
||||
|
||||
- **列表列**: 序号、类型编码(`product_type_code`)、类型名称(`product_type_name`)、排序号、备注、创建时间、操作
|
||||
- **新增/编辑弹窗**: 2 列表单,字段:类型编码(必填)、类型名称(必填)、排序号、备注
|
||||
- **查看弹窗**: `SystemViewDialog`,展示基本信息
|
||||
- **搜索**: keyword 搜索编码/名称
|
||||
|
||||
#### 2.3.2 细胞产品规格管理(简单 CRUD)
|
||||
|
||||
- **列表列**: 序号、规格编码(`spec_code`)、规格名称(`spec_name`)、排序号、备注、创建时间、操作
|
||||
- **新增/编辑弹窗**: 2 列表单,字段:规格编码(必填)、规格名称(必填)、排序号、备注
|
||||
- **查看弹窗**: `SystemViewDialog`
|
||||
- **搜索**: keyword 搜索编码/名称
|
||||
|
||||
#### 2.3.3 细胞产品价格体系管理(含下拉关联)
|
||||
|
||||
- **列表列**: 序号、项目名称(`project_name`)、项目编码(`project_code`)、细胞类型名称(`cell_type_name`)、规格(`spec_text`)、单价(`unit_price`)、排序号、备注、创建时间、操作
|
||||
- **新增/编辑弹窗**: 2 列表单,字段:
|
||||
- 项目名称(必填)、项目编码(必填)
|
||||
- 细胞产品类型(下拉,从 2.3.1 获取,选择后填充 `cell_type_code` + `cell_type_name`)
|
||||
- 规格(下拉,从 2.3.2 获取,选择后填充 `spec_id` + `spec_text`)
|
||||
- 单价(元,数字输入)、排序号、备注
|
||||
- **搜索**: keyword + 细胞类型下拉筛选
|
||||
|
||||
#### 2.3.4 细胞产品项目价格管理(主子表)
|
||||
|
||||
- **列表列**: 序号、体系名称(`system_name`)、体系编码(`system_code`)、状态(tag)、排序号、备注、创建时间、操作
|
||||
- **新增/编辑弹窗**:
|
||||
- 顶部:体系名称(必填)、体系编码(必填)、状态(下拉:正常/停用)、排序号、备注
|
||||
- 下方:明细表格(可编辑表格)
|
||||
- 操作列:添加行(从价格体系 2.3.3 选择)、删除行
|
||||
- 列:项目名称、项目编码、细胞类型名称、规格、单价(可修改)
|
||||
- 选择后自动填充:`source_price_id`, `project_name`, `project_code`, `cell_type_code`, `cell_type_name`, `spec_text`, `spec_id`, `cell_product_type_id`
|
||||
- `unit_price` 默认带入选中的价格,但可修改
|
||||
- **查看弹窗**: 展示主表信息 + 明细列表
|
||||
|
||||
#### 2.3.5 渠道信息管理(多 Tab + 子表)
|
||||
|
||||
- **列表列**: 序号、渠道名称(`channel_name`)、统一社会信用代码(`credit_code`)、渠道类型(tag)、联系人、联系电话、排序号、创建时间、操作
|
||||
- **新增/编辑弹窗**: 使用 Tab 分区
|
||||
- **Tab 1 基础信息**: 渠道名称(必填)、统一社会信用代码、渠道类型(下拉:yy/hzjg/zs/zfjg/qt)、联系人姓名、联系电话、联系邮箱、渠道协议附件(上传)、排序号、备注
|
||||
- **Tab 2 开票信息**: 子表列表 + 新增/编辑/删除
|
||||
- 字段:单位名称(必填)、税号、单位地址、电话、开户银行、银行账号
|
||||
- **Tab 3 邮寄地址**: 子表列表 + 新增/编辑/删除
|
||||
- 字段:邮寄地址(必填)、邮寄联系人、邮寄联系电话
|
||||
- **Tab 4 协议信息**: 子表列表 + 新增/编辑/删除
|
||||
- 每个协议可展开查看/编辑协议价格明细
|
||||
- 协议字段:协议类型(必填,下拉 kyxy/zsxy/lcxy)、业务类型(随协议类型自动填充)、结算方式(下拉)、授信额度、生效日期、到期日期、协议状态(tag)
|
||||
- 操作按钮:生效、作废(仅状态变更)
|
||||
- **协议价格明细子表**:
|
||||
- 可从价格体系(2.3.3)或项目价格体系(2.3.4)中选择添加
|
||||
- 选择后自动填充:项目名称、项目编码、细胞类型编码、细胞类型名称、规格
|
||||
- 原价(自动带入,可修改)、协议价(必填)
|
||||
|
||||
#### 2.3.6 体检机构及项目价格(主子表)
|
||||
|
||||
- **列表列**: 序号、机构名称(`institution_name`)、机构地址、联系人、联系电话、状态(tag)、排序号、创建时间、操作
|
||||
- **新增/编辑弹窗**: 使用 Tab 分区
|
||||
- **Tab 1 基础信息**: 机构名称(必填)、机构地址、联系人、联系电话、状态(正常/停用)、排序号、备注
|
||||
- **Tab 2 开票信息**: 子表列表 + 新增/编辑/删除
|
||||
- 字段:单位名称(必填)、税号、单位地址、电话、开户银行、银行账号
|
||||
- **Tab 3 项目及价格**: 子表列表 + 新增/编辑/删除
|
||||
- 字段:项目名称(必填)、项目费用(元)
|
||||
|
||||
### 4.4 路由配置
|
||||
|
||||
在 `web-admin/src/router/modules/sqxp.ts` 中添加:
|
||||
|
||||
```typescript
|
||||
{
|
||||
id: '80000000000000000000000000000001',
|
||||
name: 'PilotService',
|
||||
path: '/pilot-service',
|
||||
component: '/index/index',
|
||||
meta: {
|
||||
title: '中试服务管理',
|
||||
icon: 'ri:flask-line',
|
||||
keepAlive: false,
|
||||
roles: ['admin']
|
||||
},
|
||||
children: [
|
||||
{
|
||||
id: '80000000000000000000000000000002',
|
||||
name: 'CellProductType',
|
||||
path: 'cell-product-type',
|
||||
component: '/pilot-service/cell-product-type/index',
|
||||
meta: { title: '细胞产品类型管理', keepAlive: true }
|
||||
},
|
||||
{
|
||||
id: '80000000000000000000000000000003',
|
||||
name: 'CellProductSpec',
|
||||
path: 'cell-product-spec',
|
||||
component: '/pilot-service/cell-product-spec/index',
|
||||
meta: { title: '细胞产品规格管理', keepAlive: true }
|
||||
},
|
||||
{
|
||||
id: '80000000000000000000000000000004',
|
||||
name: 'CellProductPrice',
|
||||
path: 'cell-product-price',
|
||||
component: '/pilot-service/cell-product-price/index',
|
||||
meta: { title: '细胞产品价格体系管理', keepAlive: true }
|
||||
},
|
||||
{
|
||||
id: '80000000000000000000000000000005',
|
||||
name: 'ProjectPriceSystem',
|
||||
path: 'project-price-system',
|
||||
component: '/pilot-service/project-price-system/index',
|
||||
meta: { title: '细胞产品项目价格管理', keepAlive: true }
|
||||
},
|
||||
{
|
||||
id: '80000000000000000000000000000006',
|
||||
name: 'Channel',
|
||||
path: 'channel',
|
||||
component: '/pilot-service/channel/index',
|
||||
meta: { title: '渠道信息管理', keepAlive: true }
|
||||
},
|
||||
{
|
||||
id: '80000000000000000000000000000007',
|
||||
name: 'CheckupInstitution',
|
||||
path: 'checkup-institution',
|
||||
component: '/pilot-service/checkup-institution/index',
|
||||
meta: { title: '体检机构及项目价格', keepAlive: true }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 菜单 SQL
|
||||
|
||||
新增文件 `docs/sql/sys_menu_pilot_service.sql`,包含:
|
||||
- 一级菜单目录:中试服务管理(parent_id 指向 Web 端根菜单,即 `id=2`)
|
||||
- 6 个二级菜单项
|
||||
- 与路由 id 保持一致
|
||||
|
||||
---
|
||||
|
||||
## 6. UI 规范遵循
|
||||
|
||||
所有页面严格遵循 `docs/web-admin-ui-spec-fresh-mint.md` 和 AGENTS.md 中的 UI 约定:
|
||||
|
||||
- **颜色**: 主色 `#10b981`(Fresh Mint),不使用小程序颜色
|
||||
- **表单**: `label-position="top"`,使用 `.dialog-form-layout` + `.form-grid-2`
|
||||
- **弹窗**: `backdrop-filter: none`,`max-height: calc(100vh - 100px)` 只 body 滚动
|
||||
- **标题**: `panel-top` → `h2.title-bar-heading` 带竖线
|
||||
- **按钮**: 每行只有一个 `type="primary"`,工具栏"已选 N 项"在前
|
||||
- **排序字段**: 列表和弹窗中默认不展示 `order_num` 排序字段(按 AGENTS.md 约定)
|
||||
- **操作列**: `fixed="right"`,`min-width ≥ 260px`
|
||||
|
||||
---
|
||||
|
||||
## 7. 交付物清单
|
||||
|
||||
| # | 文件 | 操作 |
|
||||
|---|------|------|
|
||||
| 1 | `backend/app/models/models.py` | 追加 13 个 Model |
|
||||
| 2 | `backend/app/crud/pilot_service.py` | 新建 |
|
||||
| 3 | `backend/app/api/pilot_service.py` | 新建 |
|
||||
| 4 | `backend/app/api/__init__.py` | 追加 import + __all__ |
|
||||
| 5 | `backend/app/main.py` | 追加 include_router |
|
||||
| 6 | `web-admin/src/api/admin.ts` | 追加 API 函数 |
|
||||
| 7 | `web-admin/src/views/pilot-service/cell-product-type/index.vue` | 新建 |
|
||||
| 8 | `web-admin/src/views/pilot-service/cell-product-spec/index.vue` | 新建 |
|
||||
| 9 | `web-admin/src/views/pilot-service/cell-product-price/index.vue` | 新建 |
|
||||
| 10 | `web-admin/src/views/pilot-service/project-price-system/index.vue` | 新建 |
|
||||
| 11 | `web-admin/src/views/pilot-service/channel/index.vue` | 新建 |
|
||||
| 12 | `web-admin/src/views/pilot-service/checkup-institution/index.vue` | 新建 |
|
||||
| 13 | `web-admin/src/router/modules/sqxp.ts` | 追加路由 |
|
||||
| 14 | `docs/sql/sys_menu_pilot_service.sql` | 新建 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 不在范围内
|
||||
|
||||
以下内容不在本次实现中(后续模块需要):
|
||||
|
||||
- 2.3.7 渠道服务购买订单管理
|
||||
- 2.3.8 渠道服务购买订单管理(财务确认)
|
||||
- 2.3.9 中试服务单管理
|
||||
- 工作流集成
|
||||
- 数据权限(`apply_data_scope`)— 本次使用 `require_admin_or_super_admin`,后续按需添加
|
||||
@@ -0,0 +1,224 @@
|
||||
# 生产管理模块设计规格
|
||||
|
||||
## 概述
|
||||
实现需求文档 2.5 节中生产管理下的 7 个子模块(工艺路线配置暂不实现)。
|
||||
新增一级菜单【生产管理】,下设 7 个二级菜单。按依赖关系分 2 批实现。
|
||||
|
||||
## 范围
|
||||
| 批次 | 模块 | 需求章节 | 依赖 |
|
||||
|------|------|----------|------|
|
||||
| 第1批 | 耗材管理 | 2.5.1 | 无 |
|
||||
| 第1批 | 试剂管理 | 2.5.3 | 物品单位管理(已有) |
|
||||
| 第1批 | SOP文档 | 2.5.4 | 无(附件上传) |
|
||||
| 第1批 | 工艺工序分类 | 2.5.5 | 无 |
|
||||
| 第1批 | 工艺产出物类型 | 2.3.6 | 无 |
|
||||
| 第2批 | 耗材包管理 | 2.5.2 | 耗材管理 |
|
||||
| 第2批 | 工艺库管理 | 2.3.7 | 试剂、耗材、SOP、工序分类、产出物类型 |
|
||||
|
||||
**不在范围内**: 工艺路线配置[2.3.8] — 留待下次迭代。
|
||||
|
||||
## SQL 表(需新建 11 张)
|
||||
|
||||
### 第1批:单表模块(5 张)
|
||||
|
||||
#### 1. biz_consumable — 耗材
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | VARCHAR(64) PK | UUID |
|
||||
| consumable_code | VARCHAR(64) NOT NULL | 耗材编码 |
|
||||
| consumable_name | VARCHAR(100) NOT NULL | 耗材名称 |
|
||||
| spec_model | VARCHAR(200) DEFAULT NULL | 规格型号 |
|
||||
| standard_usage | VARCHAR(100) DEFAULT NULL | 标准用量 |
|
||||
| description | VARCHAR(500) DEFAULT NULL | 描述 |
|
||||
| + 公共字段 | | tenant_no ~ del_flag |
|
||||
|
||||
#### 2. biz_reagent — 试剂
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | VARCHAR(64) PK | UUID |
|
||||
| reagent_code | VARCHAR(64) NOT NULL | 试剂编码 |
|
||||
| reagent_name | VARCHAR(100) NOT NULL | 试剂名称 |
|
||||
| spec | VARCHAR(200) DEFAULT NULL | 规格 |
|
||||
| standard_usage | VARCHAR(100) DEFAULT NULL | 标准用量 |
|
||||
| unit | VARCHAR(64) DEFAULT NULL | 单位(下拉自物品单位管理) |
|
||||
| description | VARCHAR(500) DEFAULT NULL | 描述 |
|
||||
| + 公共字段 | | |
|
||||
|
||||
#### 3. biz_sop_document — SOP文档
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | VARCHAR(64) PK | UUID |
|
||||
| sop_code | VARCHAR(64) NOT NULL | SOP编号 |
|
||||
| sop_name | VARCHAR(200) NOT NULL | SOP文档名称 |
|
||||
| version_no | VARCHAR(50) DEFAULT NULL | 版本号 |
|
||||
| sop_attachments | VARCHAR(2000) DEFAULT NULL | SOP文档附件(逗号分隔URL) |
|
||||
| + 公共字段 | | |
|
||||
|
||||
#### 4. biz_process_category — 工艺工序分类
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | VARCHAR(64) PK | UUID |
|
||||
| category_code | VARCHAR(64) NOT NULL | 分类编码 |
|
||||
| category_name | VARCHAR(100) NOT NULL | 分类名称 |
|
||||
| + 公共字段 | | |
|
||||
|
||||
#### 5. biz_output_type — 工艺产出物类型
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | VARCHAR(64) PK | UUID |
|
||||
| type_code | VARCHAR(64) NOT NULL | 类型编码 |
|
||||
| type_name | VARCHAR(100) NOT NULL | 类型名称 |
|
||||
| + 公共字段 | | |
|
||||
|
||||
### 第2批:主表+子表模块(6 张)
|
||||
|
||||
#### 6. biz_consumable_pack — 耗材包主表
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | VARCHAR(64) PK | UUID |
|
||||
| pack_code | VARCHAR(64) NOT NULL | 编号 |
|
||||
| pack_name | VARCHAR(100) NOT NULL | 名称 |
|
||||
| usage_scene | VARCHAR(200) DEFAULT NULL | 使用场景 |
|
||||
| pack_type | VARCHAR(20) DEFAULT NULL | 类型(bzhcb-标准耗材包、zdyhcb-自定义耗材包) |
|
||||
| status | CHAR(1) DEFAULT '1' | 状态(1-启用、0-停用) |
|
||||
| + 公共字段 | | |
|
||||
|
||||
#### 7. biz_consumable_pack_item — 耗材包耗材明细
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | VARCHAR(64) PK | UUID |
|
||||
| pack_id | VARCHAR(64) NOT NULL | 耗材包id |
|
||||
| consumable_code | VARCHAR(64) DEFAULT NULL | 耗材编码 |
|
||||
| consumable_name | VARCHAR(100) DEFAULT NULL | 耗材名称 |
|
||||
| spec_model | VARCHAR(200) DEFAULT NULL | 耗材规格型号 |
|
||||
| standard_usage | VARCHAR(100) DEFAULT NULL | 标准用量 |
|
||||
| remark | VARCHAR(512) DEFAULT NULL | 备注 |
|
||||
| + 公共字段 | | |
|
||||
|
||||
#### 8. biz_process — 工艺库主表
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | VARCHAR(64) PK | UUID |
|
||||
| process_code | VARCHAR(64) NOT NULL | 工序代码 |
|
||||
| category_id | VARCHAR(64) DEFAULT NULL | 工序分类id(下拉自工艺工序分类) |
|
||||
| process_name | VARCHAR(100) NOT NULL | 工序名称 |
|
||||
| description | VARCHAR(500) DEFAULT NULL | 描述 |
|
||||
| equipment_name | VARCHAR(200) DEFAULT NULL | 预计使用设备名称 |
|
||||
| estimated_duration | VARCHAR(100) DEFAULT NULL | 预估耗时 |
|
||||
| sop_ids | VARCHAR(1000) DEFAULT NULL | 关联SOP文档id(逗号分隔) |
|
||||
| + 公共字段 | | |
|
||||
|
||||
#### 9. biz_process_reagent — 工艺-试剂关联
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | VARCHAR(64) PK | UUID |
|
||||
| process_id | VARCHAR(64) NOT NULL | 工艺id |
|
||||
| reagent_code | VARCHAR(64) DEFAULT NULL | 试剂编码 |
|
||||
| reagent_name | VARCHAR(100) DEFAULT NULL | 试剂名称 |
|
||||
| spec | VARCHAR(200) DEFAULT NULL | 规格 |
|
||||
| standard_usage | VARCHAR(100) DEFAULT NULL | 标准用量 |
|
||||
| unit | VARCHAR(64) DEFAULT NULL | 单位 |
|
||||
| is_key_material | CHAR(1) DEFAULT '0' | 是否关键物料(0-否、1-是) |
|
||||
| + 公共字段 | | |
|
||||
|
||||
#### 10. biz_process_consumable — 工艺-耗材关联
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | VARCHAR(64) PK | UUID |
|
||||
| process_id | VARCHAR(64) NOT NULL | 工艺id |
|
||||
| consumable_code | VARCHAR(64) DEFAULT NULL | 耗材编码 |
|
||||
| consumable_name | VARCHAR(100) DEFAULT NULL | 耗材名称 |
|
||||
| spec_model | VARCHAR(200) DEFAULT NULL | 耗材规格型号 |
|
||||
| standard_usage | VARCHAR(100) DEFAULT NULL | 标准用量 |
|
||||
| is_required | CHAR(1) DEFAULT '1' | 是否必需(1-必须、0-可选) |
|
||||
| remark | VARCHAR(512) DEFAULT NULL | 备注 |
|
||||
| + 公共字段 | | |
|
||||
|
||||
#### 11. biz_process_output — 工艺-产出关联
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | VARCHAR(64) PK | UUID |
|
||||
| process_id | VARCHAR(64) NOT NULL | 工艺id |
|
||||
| output_type_id | VARCHAR(64) DEFAULT NULL | 产出类型(下拉自工艺产出物类型) |
|
||||
| output_name | VARCHAR(200) DEFAULT NULL | 产出物名称 |
|
||||
| output_barcode | VARCHAR(200) DEFAULT NULL | 产出物条码(生产时才有数据) |
|
||||
| + 公共字段 | | |
|
||||
|
||||
## 模块设计
|
||||
|
||||
### 模块 1-5: 耗材/试剂/SOP/工序分类/产出物类型(简单 CRUD)
|
||||
- **类型**: 标准列表模式
|
||||
- **后端**: Model + CRUD + API 路由(完全参照 `item_unit.py` 模式)
|
||||
- **前端**: 参照 `system/unit/index.vue` 标准列表
|
||||
- **特殊**: 试剂管理的"单位"字段下拉数据从物品单位管理获取;SOP文档需要附件上传
|
||||
|
||||
### 模块 6: 耗材包管理(主表+明细)
|
||||
- **类型**: 标准列表 + 弹窗内明细表格
|
||||
- **后端**: 主表 CRUD + 明细子表 CRUD(级联创建/更新/删除)
|
||||
- **前端**: 列表参照 `unit/index.vue`;新增/编辑弹窗中嵌入耗材明细表格,支持:
|
||||
- 从耗材库逐条添加(下拉选择耗材后自动带入编码/名称/规格/用量)
|
||||
- 行内编辑标准用量
|
||||
- 行内删除
|
||||
- **API**: `/web/admin/consumable-packs` + `/web/admin/consumable-packs/{id}` (含明细一起提交)
|
||||
|
||||
### 模块 7: 工艺库管理(主表+3个关联子表)
|
||||
- **类型**: 标准列表 + Tab式编辑弹窗
|
||||
- **后端**: 主表 CRUD + 3 个子表 CRUD(级联操作)
|
||||
- **前端**: 列表页标准列表;新增/编辑弹窗分 4 个 Tab:
|
||||
- Tab1「基本信息」: 工序代码、工序分类(下拉)、工序名称、描述、设备名称、预估耗时、关联SOP(多选下拉)
|
||||
- Tab2「试剂关联」: 表格形式,下拉选试剂后自动带入编码/名称/规格/用量/单位,可改标准用量,标记是否关键物料
|
||||
- Tab3「耗材关联」: 表格形式,支持从耗材包批量导入或从耗材库逐条添加;可改标准用量,标记是否必需
|
||||
- Tab4「产出物」: 表格形式,下拉选产出类型 + 填产出物名称
|
||||
- **API**: `/web/admin/processes` + `/web/admin/processes/{id}` (含所有子表一起提交)
|
||||
|
||||
## 路由与菜单
|
||||
|
||||
### 前端路由
|
||||
在 `sqxp.ts` 新增顶级路由组:
|
||||
```
|
||||
/production
|
||||
/production/consumable 耗材管理
|
||||
/production/reagent 试剂管理
|
||||
/production/sop SOP文档
|
||||
/production/process-category 工艺工序分类
|
||||
/production/output-type 工艺产出物类型
|
||||
/production/consumable-pack 耗材包管理
|
||||
/production/process 工艺库管理
|
||||
```
|
||||
|
||||
### 后端 API
|
||||
统一路由前缀 `/web/admin`,新增以下端点:
|
||||
```
|
||||
GET/POST /consumables 耗材列表/创建
|
||||
GET/PUT/DELETE /consumables/{id} 耗材详情/更新/删除
|
||||
GET/POST /reagents 试剂列表/创建
|
||||
GET/PUT/DELETE /reagents/{id} 试剂详情/更新/删除
|
||||
GET/POST /sop-documents SOP列表/创建
|
||||
GET/PUT/DELETE /sop-documents/{id} SOP详情/更新/删除
|
||||
GET/POST /process-categories 工序分类列表/创建
|
||||
GET/PUT/DELETE /process-categories/{id} 工序分类详情/更新/删除
|
||||
GET/POST /output-types 产出物类型列表/创建
|
||||
GET/PUT/DELETE /output-types/{id} 产出物类型详情/更新/删除
|
||||
GET/POST /consumable-packs 耗材包列表/创建
|
||||
GET/PUT/DELETE /consumable-packs/{id} 耗材包详情/更新/删除
|
||||
GET/POST /processes 工艺库列表/创建
|
||||
GET/PUT/DELETE /processes/{id} 工艺库详情/更新/删除
|
||||
```
|
||||
|
||||
### 菜单 SQL
|
||||
在 `sys_menu` 中新增生产管理顶级菜单(parent_id 指向 Web 端菜单根节点)及 7 个子菜单项。
|
||||
|
||||
## 技术规范
|
||||
- 后端模式:flat 函数式 CRUD(参照 `app/crud/item_unit.py`),不用 service 层
|
||||
- 前端模式:API 函数加入 `production.ts`,路由加入 `sqxp.ts`
|
||||
- 所有查询带 `tenant_no` 过滤,删除为软删除
|
||||
- Fresh Mint 配色 (`--primary #10b981`)
|
||||
- 附件使用 MinIO,多附件逗号分隔 URL
|
||||
- 编码字段需做唯一性校验(同 tenant_no + del_flag=0 下)
|
||||
|
||||
## 实施顺序
|
||||
1. **第1批**(5 个简单模块,可并行):
|
||||
- SQL DDL → Model → CRUD → API → 注册 → 前端 API → 路由 → 页面
|
||||
2. **第2批**(2 个复杂模块,串行):
|
||||
- 耗材包管理 → 工艺库管理
|
||||
3. **菜单 SQL**:与第1批一起执行
|
||||
@@ -0,0 +1,231 @@
|
||||
# 科研捐赠管理模块设计文档
|
||||
|
||||
> 日期:2026-05-17
|
||||
> 方案:C — 独立业务 + 共享基础数据
|
||||
> 状态:已确认
|
||||
|
||||
## 背景与需求
|
||||
|
||||
客户现有「细胞存储管理」业务,现需新增「科研捐赠」业务。两者关系:
|
||||
|
||||
- **独立新建**:科研捐赠可以直接创建
|
||||
- **双向转化**:细胞存储协议可「转科研」→ 科研捐赠;科研捐赠可「转存储」→ 细胞存储协议
|
||||
- **核心区别**:
|
||||
1. 科研捐赠不收费(无缴费相关流程)
|
||||
2. 科研捐赠必须上传知情同意书附件
|
||||
- **相同部分**:当事人信息、采集信息、样本信息、审核流程、状态生命周期
|
||||
|
||||
## 方案选型
|
||||
|
||||
| 方案 | 描述 | 结论 |
|
||||
|------|------|------|
|
||||
| A. 完全复制+裁剪 | Clone 细胞存储全部代码,删缴费/储存证书 | 代码重复严重 |
|
||||
| B. 共享表+类型区分 | 同一套表,用 business_type 区分 | 耦合高,维护难 |
|
||||
| **C. 独立业务+共享基础数据** | 独立表和 CRUD,复用基础数据和前端组件 | **已选择** |
|
||||
|
||||
选择理由:符合项目现有模式(每业务独立路由/CRUD),风险最低,独立演进。
|
||||
|
||||
---
|
||||
|
||||
## Section 1:数据库设计
|
||||
|
||||
### 新建表(6 张)
|
||||
|
||||
#### `biz_research_donation` — 主表
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | VARCHAR(64) UUID | 主键 |
|
||||
| `donation_no` | VARCHAR(64) | 捐赠协议编号 |
|
||||
| `status` | VARCHAR(20) | 状态:dsx/sxz/ygq/yzf/zckc |
|
||||
| `donation_date` | DATE | 捐赠日期 |
|
||||
| `source_type` | VARCHAR(20) | 来源类型:`direct`(独立新建)/ `from_storage`(从存储转来) |
|
||||
| `source_protocol_id` | VARCHAR(64) | 来源协议 ID(from_storage 时填源细胞存储协议 ID) |
|
||||
| `consent_form_urls` | TEXT | 知情同意书附件 URL(逗号分隔,必填) |
|
||||
| `attachment_urls` | TEXT | 其他附件 URL(逗号分隔,可选) |
|
||||
| `remark` | VARCHAR(500) | 备注 |
|
||||
| `tenant_no` | VARCHAR(64) | 租户编号 |
|
||||
| `order_num` | INT | 排序号 |
|
||||
| `create_by` | VARCHAR(64) | 创建人 |
|
||||
| `create_dept_id` | VARCHAR(64) | 创建部门 |
|
||||
| `create_time` | DATETIME | 创建时间 |
|
||||
| `update_by` | VARCHAR(64) | 更新人 |
|
||||
| `update_time` | DATETIME | 更新时间 |
|
||||
| `del_flag` | CHAR(1) DEFAULT '0' | 删除标记 |
|
||||
|
||||
#### `biz_research_donation_audit` — 审核记录
|
||||
|
||||
结构与 `biz_protocol_audit` 一致:审核状态(shtg/shth)+ 备注 + 审核人 + 审核时间。
|
||||
|
||||
#### `biz_research_donation_party` — 当事人信息
|
||||
|
||||
结构与 `biz_protocol_party_customer` 一致:母亲/父亲/新生儿信息。
|
||||
|
||||
#### `biz_research_donation_collection` — 采集信息
|
||||
|
||||
结构与 `biz_protocol_collection_info` 一致:区域/医院/采集人/时间。
|
||||
|
||||
#### `biz_research_donation_sample` — 样本信息
|
||||
|
||||
参照 `biz_protocol_sample`,**去掉**金额/费用相关字段,保留:样本类型、编码、数量、储存年限。
|
||||
|
||||
#### `biz_research_donation_sample_transport` — 样本运输信息
|
||||
|
||||
结构与 `biz_protocol_sample_transport` 一致。
|
||||
|
||||
### 不新建的表
|
||||
|
||||
| 细胞存储表 | 原因 |
|
||||
|---|---|
|
||||
| `biz_protocol_payment` | 科研捐赠不收费 |
|
||||
| `biz_protocol_payment_detail` | 科研捐赠不收费 |
|
||||
| `biz_protocol_storage_cert` | 科研捐赠无储存证书 |
|
||||
|
||||
### 复用的基础数据表(不新建)
|
||||
|
||||
- `biz_customer` — 客户主数据
|
||||
- `biz_cell_sample_type` — 样本类型
|
||||
- `biz_collection_region` / `biz_collection_hospital` — 采集区域/医院
|
||||
- `biz_sample_code` — 样本编码池
|
||||
- `biz_attachment` — 通用附件
|
||||
|
||||
### 状态生命周期
|
||||
|
||||
```
|
||||
科研捐赠:dsx(待生效) → sxz(生效中) → ygq(已过期) / yzf(已作废) / zckc(转细胞存储)
|
||||
细胞存储:dsx(待生效) → sxz(生效中) → ygq(已过期) / yzf(已作废) / zky(转科研)
|
||||
```
|
||||
|
||||
### 双向转化机制
|
||||
|
||||
- **细胞存储 → 科研捐赠**:细胞存储协议状态变为 `zky`,新建科研捐赠记录(`source_type=from_storage`, `source_protocol_id=源协议ID`)
|
||||
- **科研捐赠 → 细胞存储**:科研捐赠状态变为 `zckc`,新建细胞存储协议记录(缴费信息留空待补填),科研捐赠记录保留关联
|
||||
|
||||
---
|
||||
|
||||
## Section 2:后端架构
|
||||
|
||||
### 文件结构
|
||||
|
||||
```
|
||||
backend/app/
|
||||
├── api/
|
||||
│ ├── research_donation.py # 新建:科研捐赠 API 路由
|
||||
│ └── __init__.py # 注册新路由
|
||||
├── crud/
|
||||
│ └── research_donation.py # 新建:科研捐赠 CRUD/业务逻辑
|
||||
├── models/
|
||||
│ └── models.py # 新增 6 个 Model 类
|
||||
├── schemas/
|
||||
│ └── research_donation.py # 新建:Pydantic schemas
|
||||
└── main.py # 注册新路由
|
||||
```
|
||||
|
||||
### API 路由
|
||||
|
||||
前缀:`/web/admin/research-donations`,tag `"科研捐赠管理"`
|
||||
|
||||
| 端点 | 方法 | 说明 |
|
||||
|---|---|---|
|
||||
| `/` | GET | 列表查询(分页、关键字、状态筛选) |
|
||||
| `/` | POST | 新建科研捐赠 |
|
||||
| `/{id}` | GET | 详情(含所有子资源) |
|
||||
| `/{id}` | PUT | 更新 |
|
||||
| `/{id}` | DELETE | 删除(软删除) |
|
||||
| `/batch-delete` | POST | 批量删除 |
|
||||
| `/audit/list` | GET | 审核列表 |
|
||||
| `/audit/submit` | POST | 提交审核(单个/批量) |
|
||||
| `/status-change` | POST | 状态变更(生效/过期/作废/转存储) |
|
||||
| `/convert-from-storage` | POST | 从细胞存储协议转化 |
|
||||
| `/convert-to-storage` | POST | 转为细胞存储 |
|
||||
|
||||
### CRUD 层
|
||||
|
||||
参照 `collection_protocol.py` 模式,简化(无缴费逻辑):
|
||||
|
||||
- 子资源整体 upsert
|
||||
- 审核逻辑(shtg/shth + remark)
|
||||
- 状态机校验
|
||||
- 转化逻辑(双向数据复制 + 关联)
|
||||
- 租户隔离 + 数据权限过滤
|
||||
|
||||
### Schemas
|
||||
|
||||
- `ResearchDonationCreate` / `ResearchDonationUpdate`
|
||||
- `ResearchDonationResponse` / `ResearchDonationListResponse`
|
||||
- `ResearchDonationAuditSubmit`
|
||||
- `ResearchDonationStatusChange`
|
||||
- `ConvertFromStorageRequest` / `ConvertToStorageRequest`
|
||||
|
||||
### 代码复用策略
|
||||
|
||||
- **复用**:基础数据查询函数、附件处理工具、字段命名转换工具
|
||||
- **不复用**:CRUD 代码(独立文件,避免耦合)
|
||||
|
||||
---
|
||||
|
||||
## Section 3:前端结构
|
||||
|
||||
### 路由注册(`sqxp.ts`)
|
||||
|
||||
```
|
||||
科研捐赠管理 (id: 6000...)
|
||||
├── /research-donation/list → 捐赠协议单管理
|
||||
├── /research-donation/audit → 捐赠协议审核
|
||||
```
|
||||
|
||||
### 页面与组件
|
||||
|
||||
```
|
||||
web-admin/src/
|
||||
├── views/research-donation/
|
||||
│ ├── list/
|
||||
│ │ ├── index.vue # 列表页
|
||||
│ │ ├── DonationFormDialog.vue # 新增/编辑弹窗(5 Tab)
|
||||
│ │ ├── DonationViewDialog.vue # 查看详情弹窗
|
||||
│ │ ├── DonationAuditDialog.vue # 审核弹窗
|
||||
│ │ └── DonationStatusChangeDialog.vue # 状态变更弹窗(含转存储)
|
||||
│ └── audit/
|
||||
│ └── index.vue # 审核管理页
|
||||
├── api/
|
||||
│ └── research-donation.ts # API 模块
|
||||
└── components/ # 从细胞存储提取的公共组件
|
||||
├── party-info/ # 当事人信息(Form + View)
|
||||
├── collection-info/ # 采集信息(Form + View)
|
||||
└── sample-info/ # 样本信息(Form + View,捐赠版去金额)
|
||||
```
|
||||
|
||||
### 捐赠表单弹窗(5 个 Tab)
|
||||
|
||||
| Tab | 说明 | 来源 |
|
||||
|---|---|---|
|
||||
| 基本信息 | 协议编号、状态、日期、来源类型、备注 | 新写 |
|
||||
| 当事人信息 | 母亲/父亲/新生儿 | 提取公共组件 `PartyInfoForm` |
|
||||
| 采集信息 | 区域/医院/采集人/时间 | 提取公共组件 `CollectionInfoForm` |
|
||||
| 样本信息 | 样本类型/编码/数量/储存年限(无金额) | 提取公共组件 `SampleInfoForm` |
|
||||
| 附件 | 知情同意书(必传)+ 其他附件 | 新写 |
|
||||
|
||||
### 知情同意书上传
|
||||
|
||||
在「附件」Tab 中分两个区域:
|
||||
1. **知情同意书**(必传)— 红色 `*` 标注,提交时校验至少 1 份
|
||||
2. **其他附件** — 可选
|
||||
|
||||
### 细胞存储端最小改动
|
||||
|
||||
- `ProtocolStatusChangeDialog.vue` 增加 `zky`(转科研)操作
|
||||
- 列表页状态筛选增加「转科研」选项
|
||||
- 不改表结构,不改现有 CRUD 逻辑
|
||||
|
||||
---
|
||||
|
||||
## 实施顺序建议
|
||||
|
||||
1. SQL 建表脚本 → `docs/sql/`
|
||||
2. 后端 Model + Schema
|
||||
3. 后端 CRUD(子资源 upsert、审核、状态机)
|
||||
4. 后端 API 路由 + 注册
|
||||
5. 提取前端公共组件(当事人/采集/样本)
|
||||
6. 前端页面(列表 → 表单弹窗 → 查看弹窗 → 审核弹窗 → 状态变更)
|
||||
7. 双向转化功能(转科研 + 转存储)
|
||||
8. 联调测试
|
||||
@@ -0,0 +1,240 @@
|
||||
# 体检机构项目套餐设计文档
|
||||
|
||||
> 日期: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 补充)
|
||||
|
||||
| 议题 | 结论 |
|
||||
|------|------|
|
||||
| 套餐编码 | **必填**;机构内未删除套餐编码唯一 |
|
||||
| 删除被套餐引用的机构项目 | **允许软删除**;套餐明细**不自动移除**;靠快照保证历史展示;业务带入时跳过无效源项目 |
|
||||
Reference in new issue
Block a user