首页 发现 帮助
注册 登录
wuzilong
/
zkxw
1
0
派生 0
文件 工单管理 0 合并请求 0 Wiki
分支: master
分支列表 标签列表
zkxw
/
docs
/
superpowers
/
specs
/
2026-05-20-storage-cert-insurance-management-design.md

2026-05-20-storage-cert-insurance-management-design.md 16 KB
永久链接 文件历史 原始文件

设计文档：储存证管理 + 满月待办管理 + 保险公司及项目价格

日期：2026-05-20 状态：已审批 涉及模块：细胞存储管理、基础信息管理

1. 需求概述

在系统中新增三个功能模块：

  1. 储存证管理（细胞存储管理 → 二级菜单）：对已生效且样本已入库的采集协议单，管理储存证的上传和状态。
  2. 满月待办管理（细胞存储管理 → 二级菜单）：对已生效且新生儿满月的采集协议单，管理保险相关信息（保险单号、保险公司、保险险种、保单费用、生效/失效时间等）。
  3. 保险公司及项目价格（基础信息管理 → 二级菜单）：维护保险公司基础信息、开票信息、保险项目价格，供满月待办业务使用。

1.1 现有系统关联

  • 储存证表 biz_protocol_storage_cert：已存在，当前作为采集协议单子资源管理，有 make_status、cert_image_urls、make_date 字段。后端 CRUD 已有 get_storage_cert()、upsert_storage_cert()。
  • 满月待办表 biz_protocol_fullmoon_todo：已存在，仅有基础字段（todo_status、handle_date、handle_remark、insurance_attachments），缺少保险相关字段。
  • 保险公司表：完全不存在，需新建。
  • 体检机构模式：系统中已有 biz_checkup_institution + biz_checkup_institution_invoice + biz_checkup_institution_project 的机构管理模式，保险公司模块参照此模式。

2. 数据库设计

2.1 模块 A：保险公司及项目价格（3 张新表）

2.1.1 biz_insurance_company — 保险公司主表

CREATE TABLE `biz_insurance_company` (
  `id` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '主键ID',
  `company_name` varchar(200) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '保险公司名称',
  `company_address` varchar(512) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '公司地址',
  `contact_name` varchar(100) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '联系人',
  `contact_phone` varchar(32) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '联系电话',
  `status` char(1) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT '1' COMMENT '1正常 0停用',
  `tenant_no` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT 'zkxw' COMMENT '租户编号',
  `order_num` int(11) DEFAULT NULL COMMENT '排序号',
  `remark` varchar(512) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '备注',
  `create_by` varchar(64) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '创建人id',
  `create_dept_id` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT '' COMMENT '创建人部门ID',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_by` varchar(64) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '更新人id',
  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `del_flag` tinyint(4) NOT NULL DEFAULT '0' COMMENT '删除标记：0-正常 1-已删除',
  PRIMARY KEY (`id`),
  KEY `idx_ins_company` (`tenant_no`,`del_flag`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='保险公司';

2.1.2 biz_insurance_company_invoice — 保险公司开票信息（1:N）

CREATE TABLE `biz_insurance_company_invoice` (
  `id` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '主键ID',
  `insurance_company_id` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '保险公司ID',
  `company_name` varchar(200) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '单位名称',
  `tax_no` varchar(64) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '税号',
  `company_address` varchar(512) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '单位地址',
  `company_phone` varchar(64) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '电话',
  `bank_name` varchar(200) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '开户银行',
  `bank_account` varchar(64) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '银行账号',
  `tenant_no` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT 'zkxw' COMMENT '租户编号',
  `order_num` int(11) DEFAULT NULL COMMENT '排序号',
  `remark` varchar(512) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '备注',
  `create_by` varchar(64) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '创建人id',
  `create_dept_id` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT '' COMMENT '创建人部门ID',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_by` varchar(64) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '更新人id',
  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `del_flag` tinyint(4) NOT NULL DEFAULT '0' COMMENT '删除标记：0-正常 1-已删除',
  PRIMARY KEY (`id`),
  KEY `idx_ins_inv` (`insurance_company_id`,`del_flag`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='保险公司开票信息';

2.1.3 biz_insurance_project_price — 保险项目价格（1:N）

CREATE TABLE `biz_insurance_project_price` (
  `id` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '主键ID',
  `insurance_company_id` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '保险公司ID',
  `project_name` varchar(200) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '项目名称',
  `project_fee` decimal(18,2) DEFAULT NULL COMMENT '项目费用（元）',
  `status` char(1) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT '1' COMMENT '1正常 0停用',
  `tenant_no` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT 'zkxw' COMMENT '租户编号',
  `order_num` int(11) DEFAULT NULL COMMENT '排序号',
  `remark` varchar(512) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '备注',
  `create_by` varchar(64) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '创建人id',
  `create_dept_id` varchar(64) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT '' COMMENT '创建人部门ID',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_by` varchar(64) COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '更新人id',
  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `del_flag` tinyint(4) NOT NULL DEFAULT '0' COMMENT '删除标记：0-正常 1-已删除',
  PRIMARY KEY (`id`),
  KEY `idx_ins_proj` (`insurance_company_id`,`del_flag`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='保险项目价格';

2.2 模块 B：满月待办管理（ALTER 扩展现有表）

在现有 biz_protocol_fullmoon_todo 表上新增 8 个字段：

ALTER TABLE `biz_protocol_fullmoon_todo`
  ADD COLUMN `insurance_company_id` varchar(64) DEFAULT NULL COMMENT '保险公司ID' AFTER `insurance_attachments`,
  ADD COLUMN `insurance_company_name` varchar(200) DEFAULT NULL COMMENT '保险公司名称（冗余快照）' AFTER `insurance_company_id`,
  ADD COLUMN `insurance_type` varchar(200) DEFAULT NULL COMMENT '保险险种' AFTER `insurance_company_name`,
  ADD COLUMN `insurance_policy_no` varchar(100) DEFAULT NULL COMMENT '保险单号' AFTER `insurance_type`,
  ADD COLUMN `insurance_effective_date` char(8) DEFAULT NULL COMMENT '保险单生效时间YYYYMMDD' AFTER `insurance_policy_no`,
  ADD COLUMN `insurance_expiry_date` char(8) DEFAULT NULL COMMENT '保险单失效时间YYYYMMDD' AFTER `insurance_effective_date`,
  ADD COLUMN `insurance_subscribed` char(1) DEFAULT '0' COMMENT '是否已订购保险（1是 0否）' AFTER `insurance_expiry_date`,
  ADD COLUMN `insurance_fee` decimal(18,2) DEFAULT NULL COMMENT '保单费用（元）' AFTER `insurance_subscribed`;

数据筛选逻辑：满月待办列表仅展示满足以下条件的采集协议单：

  • biz_collection_protocol.protocol_status = 'sxz'（生效中）
  • biz_protocol_party_customer.newborn_delivery_time + 30天 ≤ 当前日期（新生儿已满月）

字段语义说明：

  • todo_status：满月待办整体完成状态（'0'未办保险 → '1'已办保险），表示整个流程是否结束
  • insurance_subscribed：是否已订购保险（'0'否 → '1'是），表示保险购买这一步骤是否完成
  • 两者关系：insurance_subscribed='1' 是 todo_status='1' 的前提条件之一，但不是充分条件（办结需人工确认待办状态）
  • 前端更新保险信息时，如果 insurance_subscribed 设为 '1'，可联动将 todo_status 更新为 '1'（用户可覆盖）

2.3 模块 C：储存证管理（复用现有表）

复用现有 biz_protocol_storage_cert 表，不修改表结构。

数据筛选逻辑：储存证管理列表仅展示满足以下条件的采集协议单：

  • biz_collection_protocol.protocol_status = 'sxz'（生效中）
  • 关联的 biz_protocol_sample 中存在 sample_status = 'yrk'（已入库）

3. 后端设计

3.1 模块 A：保险公司及项目价格

新增文件

文件 说明
backend/app/api/insurance_company.py API 路由文件，参照 pilot_service.py 中体检机构的路由模式

API 接口设计

保险公司 CRUD：

  • GET /web/admin/insurance-companies — 分页列表
  • POST /web/admin/insurance-companies — 新增
  • PUT /web/admin/insurance-companies/{id} — 修改
  • DELETE /web/admin/insurance-companies/{id} — 软删除

开票信息 CRUD：

  • GET /web/admin/insurance-company-invoices?insurance_company_id=xxx — 按公司查列表
  • POST /web/admin/insurance-company-invoices — 新增
  • PUT /web/admin/insurance-company-invoices/{id} — 修改
  • DELETE /web/admin/insurance-company-invoices/{id} — 软删除

保险项目价格 CRUD：

  • GET /web/admin/insurance-project-prices?insurance_company_id=xxx — 按公司查列表
  • POST /web/admin/insurance-project-prices — 新增
  • PUT /web/admin/insurance-project-prices/{id} — 修改
  • DELETE /web/admin/insurance-project-prices/{id} — 软删除

修改文件

文件 变更
backend/app/models/models.py 新增 3 个 Model：BizInsuranceCompany、BizInsuranceCompanyInvoice、BizInsuranceProjectPrice
backend/app/api/__init__.py 导入 insurance_company_router
backend/app/main.py 注册 insurance_company_router

CRUD 函数

CRUD 函数直接写在 insurance_company.py 路由文件中（参照项目既有模式：pilot_service.py 中体检机构 CRUD 内联在路由文件中），使用 _X_to_dict() 手动序列化模式。

3.2 模块 B：满月待办管理

修改文件

文件 变更
backend/app/api/collection_protocol.py 新增满月待办列表接口 + 保险信息更新接口
backend/app/models/models.py BizProtocolFullmoonTodo 模型新增 8 个字段

API 接口设计

  • GET /web/admin/fullmoon-todos — 满月待办分页列表（自动筛选已生效+已满月的协议单，关联查询客户信息和保险信息）
  • PUT /web/admin/fullmoon-todos/{id}/insurance — 更新保险信息（保险公司、保险险种、保险单号、保单费用、生效/失效时间、是否已订购保险、保险附件）

满月待办列表返回数据结构

{
  "id": "满月待办ID",
  "collection_protocol_id": "协议单ID",
  "protocol_no": "采集协议号",
  "mother_name": "母亲姓名",
  "newborn_delivery_time": "新生儿分娩时间",
  "fullmoon_date": "满月日期（计算值：分娩时间+30天）",
  "todo_status": "满月待办状态",
  "insurance_company_id": "保险公司ID",
  "insurance_company_name": "保险公司名称",
  "insurance_type": "保险险种",
  "insurance_policy_no": "保险单号",
  "insurance_effective_date": "保险生效时间",
  "insurance_expiry_date": "保险失效时间",
  "insurance_subscribed": "是否已订购保险",
  "insurance_fee": "保单费用",
  "insurance_attachments": "保险附件",
  "handle_date": "办理日期",
  "handle_remark": "办理备注"
}

3.3 模块 C：储存证管理

修改文件

文件 变更
backend/app/api/collection_protocol.py 新增储存证管理列表接口

API 接口设计

  • GET /web/admin/storage-certs — 储存证管理分页列表（自动筛选已生效+样本已入库的协议单，关联查询储存证信息）
  • 现有 upsert_storage_cert() 函数可复用，前端通过采集协议单编辑接口保存储存证

储存证列表返回数据结构

{
  "id": "储存证ID",
  "collection_protocol_id": "协议单ID",
  "protocol_no": "采集协议号",
  "mother_name": "母亲姓名",
  "newborn_delivery_time": "新生儿分娩时间",
  "sample_info": "样本信息概要（类型+编码）",
  "make_status": "制作状态（0未制作 1已制作）",
  "cert_image_urls": "储存证图片URL列表",
  "make_date": "制作日期",
  "storage_in_date": "入库日期"
}

4. 前端设计

4.1 菜单注册（sqxp.ts 变更）

细胞存储管理（id: 50000000000000000000000000000001）新增 2 个 children：

{
  id: '50000000000000000000000000000006',
  name: 'CellStorageStorageCert',
  path: 'storage-cert',
  component: '/cell-storage/storage-cert/index',
  meta: { title: '储存证管理', keepAlive: true, menuCode: 'cell-storage:storage-cert' }
},
{
  id: '50000000000000000000000000000008',
  name: 'CellStorageFullmoonTodo',
  path: 'fullmoon-todo',
  component: '/cell-storage/fullmoon-todo/index',
  meta: { title: '满月待办管理', keepAlive: true, menuCode: 'cell-storage:fullmoon-todo' }
}

基础信息管理（id: 40000000000000000000000000000001）新增 1 个 child：

{
  id: '40000000000000000000000000000007',
  name: 'BasicInfoInsuranceCompany',
  path: 'insurance-company',
  component: '/basic-info/insurance-company/index',
  meta: { title: '保险公司及项目价格', keepAlive: true, menuCode: 'basic-info:insurance-company' }
}

4.2 新增页面文件

文件路径 参照模板 说明
web-admin/src/views/cell-storage/storage-cert/index.vue system/unit/index.vue 储存证管理列表页，含查看弹窗 + 上传储存证弹窗
web-admin/src/views/cell-storage/fullmoon-todo/index.vue system/order/index.vue 满月待办管理列表页（复杂列表），含保险信息编辑弹窗
web-admin/src/views/basic-info/insurance-company/index.vue pilot-service/checkup-institution/index.vue 保险公司管理页，含 Tab 切换（开票信息 / 项目价格）

4.3 API 接口函数

新增文件或在现有 web-admin/src/api/admin.ts 中追加：

  • 储存证列表：getStorageCertList(params)
  • 满月待办列表：getFullmoonTodoList(params)
  • 满月待办保险更新：updateFullmoonTodoInsurance(id, data)
  • 保险公司 CRUD：getInsuranceCompanyList(params)、createInsuranceCompany(data)、updateInsuranceCompany(id, data)、deleteInsuranceCompany(id)
  • 开票信息 CRUD：getInsuranceInvoiceList(params)、createInsuranceInvoice(data)、updateInsuranceInvoice(id, data)、deleteInsuranceInvoice(id)
  • 项目价格 CRUD：getInsuranceProjectPriceList(params)、createInsuranceProjectPrice(data)、updateInsuranceProjectPrice(id, data)、deleteInsuranceProjectPrice(id)

5. 菜单数据初始化

需在 sys_menu 表中插入 3 条新菜单记录，父菜单为 web 端对应的二级菜单节点。同时需要在角色的菜单权限中授权。

6. 约束与规范

  • 所有表遵循公共字段规范（id, tenant_no, order_num, remark, create_by, create_dept_id, create_time, update_by, update_time, del_flag）
  • 所有查询必须加 tenant_no 过滤 + 数据权限过滤
  • 前端遵循 Fresh Mint 配色（--primary #10b981）
  • 弹窗表单 label-position="top"
  • 状态字段使用 <el-tag> 渲染
  • 附件使用 MinIO，多个附件逗号分隔
  • 列表默认按 create_time DESC 排序