cykj/zkxw

0 Fork 0

Files

T

zlwu f269a994f4 提交

2026-05-18 16:21:38 +08:00

16 KiB

Raw Blame History

中试服务管理 — 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 清单：

BizCellProductType — biz_cell_product_type
BizCellProductSpec — biz_cell_product_spec
BizCellProductPrice — biz_cell_product_price
BizCellProductProjectSystem — biz_cell_product_project_system
BizCellProductProjectSystemItem — biz_cell_product_project_system_item
BizChannel — biz_channel
BizChannelAgreement — biz_channel_agreement
BizChannelAgreementProductPrice — biz_channel_agreement_product_price
BizChannelInvoice — biz_channel_invoice
BizChannelMailAddress — biz_channel_mail_address
BizCheckupInstitution — biz_checkup_institution
BizCheckupInstitutionInvoice — biz_checkup_institution_invoice
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 路由注册

backend/app/api/__init__.py — 添加 from app.api.pilot_service import router as pilot_service_router + __all__
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 中添加：

{
  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，后续按需添加

16 KiB Raw Blame History Unescape Escape