# 科研捐赠管理模块 Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** 实现科研捐赠管理模块——独立的新业务模块,支持协议 CRUD、审核、状态流转、与细胞存储的双向转化。 **Architecture:** 方案 C — 独立数据库表(6 张)+ 独立后端 API/CRUD + 独立前端页面,复用基础数据表和提取公共前端组件。不侵入现有细胞存储代码。 **Tech Stack:** MySQL 5.7 · SQLAlchemy · Pydantic v2 · FastAPI · Vue 3 · Element Plus · Tailwind CSS 4 · TypeScript **Design Spec:** `docs/superpowers/specs/2026-05-17-research-donation-module-design.md` --- ## File Structure ### New Files (Backend) - `docs/sql/research_donation_tables.sql` — 6 张新建表 DDL - `backend/app/models/research_donation.py` — 6 个 SQLAlchemy Model(独立文件避免 models.py 过大) - `backend/app/schemas/research_donation.py` — Pydantic schemas(注意:细胞存储没有独立 schema 文件,但科研捐赠新建一个更清晰) - `backend/app/crud/research_donation.py` — CRUD/业务逻辑 - `backend/app/api/research_donation.py` — API 路由 ### Modified Files (Backend) - `backend/app/models/__init__.py` — import 新 models - `backend/app/api/__init__.py` — 注册新路由 - `backend/app/main.py` — include 新路由 ### New Files (Frontend) - `web-admin/src/api/research-donation.ts` — API 模块 - `web-admin/src/views/research-donation/list/index.vue` — 捐赠协议列表页 - `web-admin/src/views/research-donation/list/DonationFormDialog.vue` — 新增/编辑弹窗 - `web-admin/src/views/research-donation/list/DonationViewDialog.vue` — 查看详情弹窗 - `web-admin/src/views/research-donation/list/DonationAuditDialog.vue` — 审核弹窗 - `web-admin/src/views/research-donation/list/DonationStatusChangeDialog.vue` — 状态变更弹窗 - `web-admin/src/views/research-donation/audit/index.vue` — 审核管理页 ### Modified Files (Frontend) - `web-admin/src/router/modules/sqxp.ts` — 新增科研捐赠菜单路由 - `web-admin/src/views/cell-storage/protocol/ProtocolStatusChangeDialog.vue` — 增加「转科研」操作 ### Reference Files (DO NOT MODIFY — 用于参照模式) - `backend/app/models/models.py:707-937` — 细胞存储 Model 定义 - `backend/app/api/collection_protocol.py` — 细胞存储 API 路由模式 - `backend/app/crud/collection_protocol.py` — 细胞存储 CRUD 模式 - `web-admin/src/views/cell-storage/protocol/index.vue` — 协议列表页模式 - `web-admin/src/views/cell-storage/protocol/ProtocolFormDialog.vue` — 表单弹窗模式 - `web-admin/src/views/cell-storage/protocol/ProtocolViewDialog.vue` — 查看弹窗模式 - `web-admin/src/views/cell-storage/protocol/ProtocolAuditDialog.vue` — 审核弹窗模式 - `web-admin/src/views/cell-storage/protocol/ProtocolStatusChangeDialog.vue` — 状态变更弹窗模式 - `web-admin/src/views/cell-storage/protocol-audit/index.vue` — 审核管理页模式 - `web-admin/src/api/collection-protocol.ts` — API 模块模式 - `web-admin/src/router/modules/sqxp.ts:204-252` — 细胞存储路由注册 --- ## Task 1: SQL 建表脚本 **Files:** - Create: `docs/sql/research_donation_tables.sql` **Reference:** `docs/sql/qc_item_param_and_task_result.sql`(SQL 格式参考),`backend/app/models/models.py:707-937`(字段定义参考) - [ ] **Step 1: 编写 6 张表的 DDL** 创建 `docs/sql/research_donation_tables.sql`,包含以下 6 张表的 `CREATE TABLE IF NOT EXISTS` 语句: ```sql -- ============================================================ -- 科研捐赠管理模块 — 建表脚本 -- ============================================================ -- 1. 科研捐赠主表 CREATE TABLE IF NOT EXISTS `biz_research_donation` ( `id` varchar(64) NOT NULL COMMENT '主键ID', `donation_no` varchar(64) NOT NULL COMMENT '捐赠协议编号', `donation_status` varchar(16) NOT NULL DEFAULT 'dsx' COMMENT '状态 dsx待生效 sxz生效中 ygq已过期 yzf已作废 zckc转细胞存储', `donation_date` char(8) DEFAULT NULL COMMENT '捐赠日期YYYYMMDD', `source_type` varchar(20) NOT NULL DEFAULT 'direct' COMMENT '来源类型 direct独立新建 from_storage从细胞存储转来', `source_protocol_id` varchar(64) DEFAULT NULL COMMENT '来源协议ID(from_storage时填源细胞存储协议ID)', `consent_form_urls` text DEFAULT NULL COMMENT '知情同意书附件URL(逗号分隔,必填)', `attachment_urls` text DEFAULT NULL COMMENT '其他附件URL(逗号分隔)', `collector_user_id` varchar(64) DEFAULT NULL COMMENT '采集专员用户ID', `effective_time` datetime DEFAULT NULL COMMENT '生效时间', `effective_desc` varchar(512) DEFAULT NULL COMMENT '生效描述', `expire_time` datetime DEFAULT NULL COMMENT '过期时间', `expire_desc` varchar(512) DEFAULT NULL COMMENT '过期描述', `void_time` datetime DEFAULT NULL COMMENT '作废时间', `void_desc` varchar(512) DEFAULT NULL COMMENT '作废描述', `to_storage_time` datetime DEFAULT NULL COMMENT '转存储时间', `to_storage_desc` varchar(512) DEFAULT NULL COMMENT '转存储描述', `tenant_no` varchar(64) NOT NULL DEFAULT 'zkxw' COMMENT '租户编号', `order_num` int(11) DEFAULT NULL COMMENT '排序号', `remark` varchar(512) DEFAULT NULL COMMENT '备注信息', `create_by` varchar(64) DEFAULT NULL COMMENT '创建人id', `create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建人部门ID', `create_time` datetime NOT NULL COMMENT '创建时间', `update_by` varchar(64) DEFAULT NULL COMMENT '更新人id', `update_time` datetime NOT NULL COMMENT '更新时间', `del_flag` tinyint(4) NOT NULL DEFAULT '0' COMMENT '删除标记', PRIMARY KEY (`id`), KEY `idx_rd_tenant_status` (`tenant_no`, `donation_status`, `del_flag`), KEY `idx_rd_collector` (`collector_user_id`, `del_flag`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='科研捐赠主表'; -- 2. 科研捐赠审核记录 CREATE TABLE IF NOT EXISTS `biz_research_donation_audit` ( `id` varchar(64) NOT NULL COMMENT '主键ID', `research_donation_id` varchar(64) NOT NULL COMMENT '科研捐赠ID', `auditor_user_id` varchar(64) DEFAULT NULL COMMENT '审核人', `audit_remark` varchar(1000) DEFAULT NULL COMMENT '审核备注', `audit_status` varchar(16) NOT NULL COMMENT '审核状态 shtg审核通过 shth审核驳回', `tenant_no` varchar(64) NOT NULL DEFAULT 'zkxw' COMMENT '租户编号', `order_num` int(11) DEFAULT NULL COMMENT '排序号', `remark` varchar(512) DEFAULT NULL COMMENT '备注', `create_by` varchar(64) DEFAULT NULL COMMENT '创建人id', `create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建人部门ID', `create_time` datetime NOT NULL COMMENT '创建时间', `update_by` varchar(64) DEFAULT NULL COMMENT '更新人id', `update_time` datetime NOT NULL COMMENT '更新时间', `del_flag` tinyint(4) NOT NULL DEFAULT '0' COMMENT '删除标记', PRIMARY KEY (`id`), KEY `idx_rda_donation` (`research_donation_id`, `del_flag`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='科研捐赠审核记录'; -- 3. 科研捐赠当事人信息 CREATE TABLE IF NOT EXISTS `biz_research_donation_party` ( `id` varchar(64) NOT NULL COMMENT '主键ID', `research_donation_id` varchar(64) NOT NULL COMMENT '科研捐赠ID', `customer_id` varchar(64) DEFAULT NULL COMMENT '客户ID', `mother_name` varchar(100) DEFAULT NULL COMMENT '母亲姓名', `mother_phone` varchar(32) DEFAULT NULL COMMENT '母亲电话', `mother_id_card` varchar(32) DEFAULT NULL COMMENT '母亲身份证号', `mother_birth_ym` char(6) DEFAULT NULL COMMENT '母亲出生年月YYYYMM', `mother_ethnic` varchar(32) DEFAULT NULL COMMENT '母亲民族', `mother_address` varchar(512) DEFAULT NULL COMMENT '母亲地址', `father_name` varchar(100) DEFAULT NULL COMMENT '父亲姓名', `father_phone` varchar(32) DEFAULT NULL COMMENT '父亲电话', `father_id_card` varchar(32) DEFAULT NULL COMMENT '父亲身份证号', `newborn_name` varchar(100) DEFAULT NULL COMMENT '新生儿姓名', `newborn_id_card` varchar(32) DEFAULT NULL COMMENT '新生儿身份证号', `newborn_delivery_time` datetime DEFAULT NULL COMMENT '新生儿分娩时间', `newborn_sex` char(1) DEFAULT NULL COMMENT '新生儿性别', `delivery_mode` varchar(16) DEFAULT NULL COMMENT '分娩方式', `birth_order` int(11) DEFAULT NULL COMMENT '出生顺序', `newborn_weight_gram` int(11) DEFAULT NULL COMMENT '新生儿体重(克)', `apgar_1min` decimal(4,1) DEFAULT NULL COMMENT 'Apgar 1分钟评分', `apgar_5min` decimal(4,1) DEFAULT NULL COMMENT 'Apgar 5分钟评分', `collector_user_id` varchar(64) DEFAULT NULL COMMENT '采集专员用户ID', `tenant_no` varchar(64) NOT NULL DEFAULT 'zkxw' COMMENT '租户编号', `order_num` int(11) DEFAULT NULL COMMENT '排序号', `remark` varchar(512) DEFAULT NULL COMMENT '备注', `create_by` varchar(64) DEFAULT NULL COMMENT '创建人id', `create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建人部门ID', `create_time` datetime NOT NULL COMMENT '创建时间', `update_by` varchar(64) DEFAULT NULL COMMENT '更新人id', `update_time` datetime NOT NULL COMMENT '更新时间', `del_flag` tinyint(4) NOT NULL DEFAULT '0' COMMENT '删除标记', PRIMARY KEY (`id`), KEY `idx_rdp_donation` (`research_donation_id`, `del_flag`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='科研捐赠当事人信息'; -- 4. 科研捐赠采集信息 CREATE TABLE IF NOT EXISTS `biz_research_donation_collection` ( `id` varchar(64) NOT NULL COMMENT '主键ID', `research_donation_id` varchar(64) NOT NULL COMMENT '科研捐赠ID', `region_id` varchar(64) DEFAULT NULL COMMENT '区域ID', `hospital_id` varchar(64) DEFAULT NULL COMMENT '医院ID', `medical_staff` varchar(200) DEFAULT NULL COMMENT '医护人员', `sales_user_id` varchar(64) DEFAULT NULL COMMENT '销售人员用户ID', `sample_collect_time` datetime DEFAULT NULL COMMENT '样本采集时间', `maternal_blood_collect_time` datetime DEFAULT NULL COMMENT '母血采集时间', `tenant_no` varchar(64) NOT NULL DEFAULT 'zkxw' COMMENT '租户编号', `order_num` int(11) DEFAULT NULL COMMENT '排序号', `remark` varchar(512) DEFAULT NULL COMMENT '备注', `create_by` varchar(64) DEFAULT NULL COMMENT '创建人id', `create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建人部门ID', `create_time` datetime NOT NULL COMMENT '创建时间', `update_by` varchar(64) DEFAULT NULL COMMENT '更新人id', `update_time` datetime NOT NULL COMMENT '更新时间', `del_flag` tinyint(4) NOT NULL DEFAULT '0' COMMENT '删除标记', PRIMARY KEY (`id`), KEY `idx_rdc_donation` (`research_donation_id`, `del_flag`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='科研捐赠采集信息'; -- 5. 科研捐赠样本信息(无金额字段) CREATE TABLE IF NOT EXISTS `biz_research_donation_sample` ( `id` varchar(64) NOT NULL COMMENT '主键ID', `research_donation_id` varchar(64) NOT NULL COMMENT '科研捐赠ID', `sample_type_id` varchar(64) DEFAULT NULL COMMENT '样本类型ID', `sample_code_id` varchar(64) DEFAULT NULL COMMENT '样本编码ID', `sample_code` varchar(32) DEFAULT NULL COMMENT '样本编码', `collect_amount` decimal(18,4) DEFAULT NULL COMMENT '采集量', `unit_id` varchar(64) DEFAULT NULL COMMENT '单位ID', `storage_years` int(11) DEFAULT NULL COMMENT '存储年限', `sample_status` varchar(16) DEFAULT NULL COMMENT '样本状态', `storage_in_date` char(8) DEFAULT NULL COMMENT '入库日期YYYYMMDD', `detect_start_date` char(8) DEFAULT NULL COMMENT '检测开始日期YYYYMMDD', `void_date` char(8) DEFAULT NULL COMMENT '作废日期YYYYMMDD', `storage_expire_date` char(8) DEFAULT NULL COMMENT '存储到期日期YYYYMMDD', `tenant_no` varchar(64) NOT NULL DEFAULT 'zkxw' COMMENT '租户编号', `order_num` int(11) DEFAULT NULL COMMENT '排序号', `remark` varchar(512) DEFAULT NULL COMMENT '备注', `create_by` varchar(64) DEFAULT NULL COMMENT '创建人id', `create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建人部门ID', `create_time` datetime NOT NULL COMMENT '创建时间', `update_by` varchar(64) DEFAULT NULL COMMENT '更新人id', `update_time` datetime NOT NULL COMMENT '更新时间', `del_flag` tinyint(4) NOT NULL DEFAULT '0' COMMENT '删除标记', PRIMARY KEY (`id`), KEY `idx_rds_donation` (`research_donation_id`, `del_flag`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='科研捐赠样本信息'; -- 6. 科研捐赠样本运输 CREATE TABLE IF NOT EXISTS `biz_research_donation_sample_transport` ( `id` varchar(64) NOT NULL COMMENT '主键ID', `research_donation_id` varchar(64) NOT NULL COMMENT '科研捐赠ID', `sample_id` varchar(64) NOT NULL COMMENT '样本ID', `transport_type` varchar(16) NOT NULL COMMENT 'kdys快递运输 ryxd人员携带', `express_company_id` varchar(64) DEFAULT NULL COMMENT '快递公司ID', `waybill_no` varchar(128) DEFAULT NULL COMMENT '快递单号', `dest_site_id` varchar(64) DEFAULT NULL COMMENT '目的站点ID', `express_fee` decimal(18,2) DEFAULT NULL COMMENT '快递费用(元)', `eta_time` datetime DEFAULT NULL COMMENT '预计到达时间', `carrier_name` varchar(100) DEFAULT NULL COMMENT '携带人员姓名', `carrier_phone` varchar(32) DEFAULT NULL COMMENT '携带人员联系电话', `tenant_no` varchar(64) NOT NULL DEFAULT 'zkxw' COMMENT '租户编号', `order_num` int(11) DEFAULT NULL COMMENT '排序号', `remark` varchar(512) DEFAULT NULL COMMENT '备注', `create_by` varchar(64) DEFAULT NULL COMMENT '创建人id', `create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建人部门ID', `create_time` datetime NOT NULL COMMENT '创建时间', `update_by` varchar(64) DEFAULT NULL COMMENT '更新人id', `update_time` datetime NOT NULL COMMENT '更新时间', `del_flag` tinyint(4) NOT NULL DEFAULT '0' COMMENT '删除标记', PRIMARY KEY (`id`), KEY `idx_rdst_donation` (`research_donation_id`, `del_flag`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='科研捐赠样本运输'; ``` - [ ] **Step 2: 提交** ```bash git add docs/sql/research_donation_tables.sql git commit -m "feat: 科研捐赠管理模块建表脚本" ``` --- ## Task 2: 后端 Model 定义 **Files:** - Create: `backend/app/models/research_donation.py` - Modify: `backend/app/models/__init__.py` **Reference:** `backend/app/models/models.py:707-937`(细胞存储 Model 定义模式) - [ ] **Step 1: 创建 research_donation.py Model 文件** 创建 `backend/app/models/research_donation.py`,包含 6 个 Model 类。模式完全对齐 `models.py` 中的细胞存储 Model(Column 定义风格、公共字段、default 值): ```python """科研捐赠管理 — 数据模型""" from datetime import datetime from sqlalchemy import Column, DateTime, Integer, Numeric, SmallInteger, String from sqlalchemy.ext.declarative import declarative_base from app.models.base import Base class BizResearchDonation(Base): """科研捐赠主表 biz_research_donation""" __tablename__ = "biz_research_donation" id = Column(String(64), primary_key=True, comment="主键ID") donation_no = Column(String(64), nullable=False, comment="捐赠协议编号") donation_status = Column(String(16), nullable=False, default="dsx", comment="状态 dsx/sxz/ygq/yzf/zckc") donation_date = Column(String(8), nullable=True, comment="捐赠日期YYYYMMDD") source_type = Column(String(20), nullable=False, default="direct", comment="来源类型 direct/from_storage") source_protocol_id = Column(String(64), nullable=True, comment="来源协议ID") consent_form_urls = Column(String(4000), nullable=True, comment="知情同意书附件URL(逗号分隔)") attachment_urls = Column(String(4000), nullable=True, comment="其他附件URL(逗号分隔)") collector_user_id = Column(String(64), nullable=True, comment="采集专员用户ID") effective_time = Column(DateTime, nullable=True, comment="生效时间") effective_desc = Column(String(512), nullable=True, comment="生效描述") expire_time = Column(DateTime, nullable=True, comment="过期时间") expire_desc = Column(String(512), nullable=True, comment="过期描述") void_time = Column(DateTime, nullable=True, comment="作废时间") void_desc = Column(String(512), nullable=True, comment="作废描述") to_storage_time = Column(DateTime, nullable=True, comment="转存储时间") to_storage_desc = Column(String(512), nullable=True, comment="转存储描述") tenant_no = Column(String(64), nullable=False, default="zkxw", comment="租户编号") order_num = Column(Integer, nullable=True, comment="排序号") remark = Column(String(512), nullable=True, comment="备注信息") create_by = Column(String(64), nullable=True, comment="创建人id") create_dept_id = Column(String(64), nullable=False, default="", comment="创建人部门ID") create_time = Column(DateTime, nullable=False, default=datetime.now, comment="创建时间") update_by = Column(String(64), nullable=True, comment="更新人id") update_time = Column(DateTime, nullable=False, default=datetime.now, onupdate=datetime.now, comment="更新时间") del_flag = Column(SmallInteger, nullable=False, default=0, comment="删除标记") class BizResearchDonationAudit(Base): """科研捐赠审核记录 biz_research_donation_audit""" __tablename__ = "biz_research_donation_audit" id = Column(String(64), primary_key=True, comment="主键ID") research_donation_id = Column(String(64), nullable=False, comment="科研捐赠ID") auditor_user_id = Column(String(64), nullable=True, comment="审核人") audit_remark = Column(String(1000), nullable=True, comment="审核备注") audit_status = Column(String(16), nullable=False, comment="审核状态 shtg/shth") tenant_no = Column(String(64), nullable=False, default="zkxw", comment="租户编号") order_num = Column(Integer, nullable=True, comment="排序号") remark = Column(String(512), nullable=True, comment="备注") create_by = Column(String(64), nullable=True, comment="创建人id") create_dept_id = Column(String(64), nullable=False, default="", comment="创建人部门ID") create_time = Column(DateTime, nullable=False, default=datetime.now, comment="创建时间") update_by = Column(String(64), nullable=True, comment="更新人id") update_time = Column(DateTime, nullable=False, default=datetime.now, onupdate=datetime.now, comment="更新时间") del_flag = Column(SmallInteger, nullable=False, default=0, comment="删除标记") class BizResearchDonationParty(Base): """科研捐赠当事人信息 biz_research_donation_party""" __tablename__ = "biz_research_donation_party" id = Column(String(64), primary_key=True, comment="主键ID") research_donation_id = Column(String(64), nullable=False, comment="科研捐赠ID") customer_id = Column(String(64), nullable=True, comment="客户ID") mother_name = Column(String(100), nullable=True, comment="母亲姓名") mother_phone = Column(String(32), nullable=True, comment="母亲电话") mother_id_card = Column(String(32), nullable=True, comment="母亲身份证号") mother_birth_ym = Column(String(6), nullable=True, comment="母亲出生年月YYYYMM") mother_ethnic = Column(String(32), nullable=True, comment="母亲民族") mother_address = Column(String(512), nullable=True, comment="母亲地址") father_name = Column(String(100), nullable=True, comment="父亲姓名") father_phone = Column(String(32), nullable=True, comment="父亲电话") father_id_card = Column(String(32), nullable=True, comment="父亲身份证号") newborn_name = Column(String(100), nullable=True, comment="新生儿姓名") newborn_id_card = Column(String(32), nullable=True, comment="新生儿身份证号") newborn_delivery_time = Column(DateTime, nullable=True, comment="新生儿分娩时间") newborn_sex = Column(String(1), nullable=True, comment="新生儿性别") delivery_mode = Column(String(16), nullable=True, comment="分娩方式") birth_order = Column(Integer, nullable=True, comment="出生顺序") newborn_weight_gram = Column(Integer, nullable=True, comment="新生儿体重(克)") apgar_1min = Column(Numeric(4, 1), nullable=True, comment="Apgar 1分钟评分") apgar_5min = Column(Numeric(4, 1), nullable=True, comment="Apgar 5分钟评分") collector_user_id = Column(String(64), nullable=True, comment="采集专员用户ID") tenant_no = Column(String(64), nullable=False, default="zkxw", comment="租户编号") order_num = Column(Integer, nullable=True, comment="排序号") remark = Column(String(512), nullable=True, comment="备注") create_by = Column(String(64), nullable=True, comment="创建人id") create_dept_id = Column(String(64), nullable=False, default="", comment="创建人部门ID") create_time = Column(DateTime, nullable=False, default=datetime.now, comment="创建时间") update_by = Column(String(64), nullable=True, comment="更新人id") update_time = Column(DateTime, nullable=False, default=datetime.now, onupdate=datetime.now, comment="更新时间") del_flag = Column(SmallInteger, nullable=False, default=0, comment="删除标记") class BizResearchDonationCollection(Base): """科研捐赠采集信息 biz_research_donation_collection""" __tablename__ = "biz_research_donation_collection" id = Column(String(64), primary_key=True, comment="主键ID") research_donation_id = Column(String(64), nullable=False, comment="科研捐赠ID") region_id = Column(String(64), nullable=True, comment="区域ID") hospital_id = Column(String(64), nullable=True, comment="医院ID") medical_staff = Column(String(200), nullable=True, comment="医护人员") sales_user_id = Column(String(64), nullable=True, comment="销售人员用户ID") sample_collect_time = Column(DateTime, nullable=True, comment="样本采集时间") maternal_blood_collect_time = Column(DateTime, nullable=True, comment="母血采集时间") tenant_no = Column(String(64), nullable=False, default="zkxw", comment="租户编号") order_num = Column(Integer, nullable=True, comment="排序号") remark = Column(String(512), nullable=True, comment="备注") create_by = Column(String(64), nullable=True, comment="创建人id") create_dept_id = Column(String(64), nullable=False, default="", comment="创建人部门ID") create_time = Column(DateTime, nullable=False, default=datetime.now, comment="创建时间") update_by = Column(String(64), nullable=True, comment="更新人id") update_time = Column(DateTime, nullable=False, default=datetime.now, onupdate=datetime.now, comment="更新时间") del_flag = Column(SmallInteger, nullable=False, default=0, comment="删除标记") class BizResearchDonationSample(Base): """科研捐赠样本信息 biz_research_donation_sample(无金额字段)""" __tablename__ = "biz_research_donation_sample" id = Column(String(64), primary_key=True, comment="主键ID") research_donation_id = Column(String(64), nullable=False, comment="科研捐赠ID") sample_type_id = Column(String(64), nullable=True, comment="样本类型ID") sample_code_id = Column(String(64), nullable=True, comment="样本编码ID") sample_code = Column(String(32), nullable=True, comment="样本编码") collect_amount = Column(Numeric(18, 4), nullable=True, comment="采集量") unit_id = Column(String(64), nullable=True, comment="单位ID") storage_years = Column(Integer, nullable=True, comment="存储年限") sample_status = Column(String(16), nullable=True, comment="样本状态") storage_in_date = Column(String(8), nullable=True, comment="入库日期YYYYMMDD") detect_start_date = Column(String(8), nullable=True, comment="检测开始日期YYYYMMDD") void_date = Column(String(8), nullable=True, comment="作废日期YYYYMMDD") storage_expire_date = Column(String(8), nullable=True, comment="存储到期日期YYYYMMDD") tenant_no = Column(String(64), nullable=False, default="zkxw", comment="租户编号") order_num = Column(Integer, nullable=True, comment="排序号") remark = Column(String(512), nullable=True, comment="备注") create_by = Column(String(64), nullable=True, comment="创建人id") create_dept_id = Column(String(64), nullable=False, default="", comment="创建人部门ID") create_time = Column(DateTime, nullable=False, default=datetime.now, comment="创建时间") update_by = Column(String(64), nullable=True, comment="更新人id") update_time = Column(DateTime, nullable=False, default=datetime.now, onupdate=datetime.now, comment="更新时间") del_flag = Column(SmallInteger, nullable=False, default=0, comment="删除标记") class BizResearchDonationSampleTransport(Base): """科研捐赠样本运输 biz_research_donation_sample_transport""" __tablename__ = "biz_research_donation_sample_transport" id = Column(String(64), primary_key=True, comment="主键ID") research_donation_id = Column(String(64), nullable=False, comment="科研捐赠ID") sample_id = Column(String(64), nullable=False, comment="样本ID") transport_type = Column(String(16), nullable=False, comment="kdys快递运输 ryxd人员携带") express_company_id = Column(String(64), nullable=True, comment="快递公司ID") waybill_no = Column(String(128), nullable=True, comment="快递单号") dest_site_id = Column(String(64), nullable=True, comment="目的站点ID") express_fee = Column(Numeric(18, 2), nullable=True, comment="快递费用(元)") eta_time = Column(DateTime, nullable=True, comment="预计到达时间") carrier_name = Column(String(100), nullable=True, comment="携带人员姓名") carrier_phone = Column(String(32), nullable=True, comment="携带人员联系电话") tenant_no = Column(String(64), nullable=False, default="zkxw", comment="租户编号") order_num = Column(Integer, nullable=True, comment="排序号") remark = Column(String(512), nullable=True, comment="备注") create_by = Column(String(64), nullable=True, comment="创建人id") create_dept_id = Column(String(64), nullable=False, default="", comment="创建人部门ID") create_time = Column(DateTime, nullable=False, default=datetime.now, comment="创建时间") update_by = Column(String(64), nullable=True, comment="更新人id") update_time = Column(DateTime, nullable=False, default=datetime.now, onupdate=datetime.now, comment="更新时间") del_flag = Column(SmallInteger, nullable=False, default=0, comment="删除标记") ``` - [ ] **Step 2: 在 models/__init__.py 中注册** 读取 `backend/app/models/__init__.py`,在 import 区增加: ```python from app.models.research_donation import ( # noqa: F401 BizResearchDonation, BizResearchDonationAudit, BizResearchDonationParty, BizResearchDonationCollection, BizResearchDonationSample, BizResearchDonationSampleTransport, ) ``` - [ ] **Step 3: 提交** ```bash git add backend/app/models/research_donation.py backend/app/models/__init__.py git commit -m "feat: 科研捐赠管理模块 — SQLAlchemy Model 定义" ``` --- ## Task 3: 后端 CRUD 层 **Files:** - Create: `backend/app/crud/research_donation.py` **Reference:** `backend/app/crud/collection_protocol.py`(CRUD 模式参考,但大幅简化:无缴费逻辑) 这是后端最核心的文件,包含以下功能模块: ### 功能清单 1. **列表查询** `list_donations(db, tenant_no, page, page_size, keyword, donation_status, collector_user_id)` — 分页、关键字搜索(编号/母亲姓名)、状态过滤、数据权限 2. **详情查询** `get_donation_detail(db, donation_id)` — 主表 + 所有子资源(当事人、采集、样本+运输) 3. **创建** `create_donation(db, data, tenant_no, user_id)` — 主表 + 子资源整体创建 4. **更新** `update_donation(db, donation_id, data, tenant_no, user_id)` — 子资源 upsert(先删后插) 5. **删除** `delete_donation(db, donation_id, tenant_no)` — 软删除主表 + 所有子资源 6. **批量删除** `batch_delete_donations(db, ids, tenant_no)` 7. **审核列表** `list_audits(db, tenant_no, page, page_size, keyword, audit_status)` 8. **提交审核** `submit_audit(db, donation_id, audit_status, audit_remark, user_id, tenant_no)` 9. **状态变更** `change_status(db, donation_id, new_status, desc, user_id, tenant_no)` — 含状态机校验 10. **从细胞存储转化** `convert_from_storage(db, protocol_id, tenant_no, user_id)` — 读源协议 → 创建捐赠记录 11. **转为细胞存储** `convert_to_storage(db, donation_id, tenant_no, user_id)` — 读捐赠 → 创建协议记录 ### 关键模式(参照 collection_protocol.py) - UUID 生成:`import uuid; uuid.uuid4().hex` - camelCase → snake_case 转换:参照 `_normalize_fields()` 模式 - 附件处理:`urls_to_attachment_list()` 复用 - 子资源 upsert:先删除旧数据 `del_flag=1`,再批量 insert 新数据 - 租户隔离:所有查询加 `tenant_no` 过滤 - 软删除:设置 `del_flag=1`,查询默认 `del_flag=0` ### 状态机 ``` 合法转换: dsx → sxz(生效) dsx → yzf(作废) sxz → ygq(过期) sxz → yzf(作废) sxz → zckc(转细胞存储) ``` > 注意:审核通过后才允许从 dsx → sxz。审核驳回后状态不变。 **实现指导:** 参照 `backend/app/crud/collection_protocol.py` 的整体结构,但去掉所有 payment/payment_detail/storage_cert 相关函数。CRUD 文件预计 600-800 行。 - [ ] **Step 1: 创建 crud/research_donation.py** 编写完整的 CRUD 文件,包含上述 11 个功能。关键点: - `create_donation` 接收一个包含所有子资源的 dict,在事务中创建主表 + party + collection + samples + transports - `update_donation` 对子资源使用"软删旧 + 插新"的 upsert 模式 - `convert_from_storage` 读取 `BizCollectionProtocol` 及其子资源,映射到捐赠字段 - `convert_to_storage` 反向操作 - [ ] **Step 2: 提交** ```bash git add backend/app/crud/research_donation.py git commit -m "feat: 科研捐赠管理模块 — CRUD 业务逻辑层" ``` --- ## Task 4: 后端 API 路由 **Files:** - Create: `backend/app/api/research_donation.py` - Modify: `backend/app/api/__init__.py` - Modify: `backend/app/main.py` **Reference:** `backend/app/api/collection_protocol.py`(API 路由模式) - [ ] **Step 1: 创建 API 路由文件** 创建 `backend/app/api/research_donation.py`: ```python """科研捐赠管理 — API 路由""" from typing import Any, Dict, List, Optional from fastapi import APIRouter, Depends, Query from pydantic import BaseModel, Field from sqlalchemy.orm import Session from app.core.database import get_db from app.core.menu_guard import require_admin_or_super_admin from app.core.response import error_response, success_response from app.crud import research_donation as rd_svc from app.models.models import SysUser router = APIRouter(prefix="/web/admin", tags=["科研捐赠管理"]) ``` 端点定义(参照 collection_protocol.py 的装饰器模式): | 端点 | 方法 | 路径 | 说明 | |---|---|---|---| | 列表 | GET | `/research-donations` | page/pageSize/keyword/donationStatus 参数 | | 详情 | GET | `/research-donations/{id}` | 返回主表 + 所有子资源 | | 创建 | POST | `/research-donations` | 整体提交含子资源 | | 更新 | PUT | `/research-donations/{id}` | 整体提交含子资源 | | 删除 | DELETE | `/research-donations/{id}` | 软删除 | | 批量删除 | POST | `/research-donations/batch-delete` | body: `{ids: []}` | | 审核列表 | GET | `/research-donations/audits` | page/pageSize/keyword/auditStatus | | 提交审核 | POST | `/research-donations/{id}/audit` | body: `{auditStatus, auditRemark}` | | 状态变更 | POST | `/research-donations/{id}/status-change` | body: `{donationStatus, desc, time}` | | 从存储转化 | POST | `/research-donations/convert-from-storage` | body: `{protocolId}` | | 转为存储 | POST | `/research-donations/{id}/convert-to-storage` | body: `{desc}` | 每个端点的模式: ```python @router.get("/research-donations") def list_research_donations( page: int = Query(1, ge=1), pageSize: int = Query(20, ge=1, le=200), keyword: Optional[str] = Query(None), donationStatus: Optional[str] = Query(None), db: Session = Depends(get_db), user: dict = Depends(require_admin_or_super_admin), ): tenant_no = _get_tenant_no(db, user) collector_user_id = _get_current_user_id(user) result = rd_svc.list_donations(db, tenant_no, page, pageSize, keyword, donationStatus, collector_user_id) return success_response(result) ``` - [ ] **Step 2: 注册路由** 在 `backend/app/api/__init__.py` 增加: ```python from app.api.research_donation import router as research_donation_router ``` 并在 `__all__` 列表增加 `"research_donation_router"`。 在 `backend/app/main.py` 的 import 行和 include_router 行增加 `research_donation_router`。 - [ ] **Step 3: 提交** ```bash git add backend/app/api/research_donation.py backend/app/api/__init__.py backend/app/main.py git commit -m "feat: 科研捐赠管理模块 — API 路由定义与注册" ``` --- ## Task 5: 前端路由与 API 模块 **Files:** - Create: `web-admin/src/api/research-donation.ts` - Modify: `web-admin/src/router/modules/sqxp.ts` **Reference:** `web-admin/src/api/collection-protocol.ts`(API 模式),`web-admin/src/router/modules/sqxp.ts:204-252`(路由注册模式) - [ ] **Step 1: 创建 API 模块** 创建 `web-admin/src/api/research-donation.ts`: ```typescript import request from '@/utils/http' type PageList = { list: T[] total: number page: number pageSize: number totalPages: number } export type ResearchDonationRow = Record // 列表 export function fetchResearchDonationList(params?: { page?: number pageSize?: number keyword?: string donationStatus?: string }) { return request.get>({ url: '/web/admin/research-donations', params }) } // 详情 export function fetchResearchDonationDetail(id: string) { return request.get<{ donation: Record party: Record | null collection: Record | null samples: Array> | null attachments?: Array> }>({ url: `/web/admin/research-donations/${id}` }) } // 创建 export function fetchCreateResearchDonation(data: Record) { return request.post({ url: '/web/admin/research-donations', data, showSuccessMessage: true }) } // 更新 export function fetchUpdateResearchDonation(id: string, data: Record) { return request.put({ url: `/web/admin/research-donations/${id}`, data, showSuccessMessage: true }) } // 删除 export function fetchDeleteResearchDonation(id: string) { return request.del({ url: `/web/admin/research-donations/${id}`, showSuccessMessage: true }) } // 批量删除 export function fetchBatchDeleteResearchDonation(ids: string[]) { return request.post({ url: '/web/admin/research-donations/batch-delete', data: { ids }, showSuccessMessage: true }) } // 审核列表 export function fetchResearchDonationAuditList(params?: { page?: number pageSize?: number keyword?: string auditStatus?: string }) { return request.get>>({ url: '/web/admin/research-donations/audits', params }) } // 提交审核 export function fetchSubmitDonationAudit( donationId: string, data: { auditStatus: string; auditRemark?: string }, options?: { showSuccessMessage?: boolean } ) { return request.post({ url: `/web/admin/research-donations/${donationId}/audit`, data, showSuccessMessage: options?.showSuccessMessage ?? true }) } // 状态变更 export function fetchDonationStatusChange( donationId: string, data: { donationStatus: string; desc?: string; time?: string } ) { return request.post({ url: `/web/admin/research-donations/${donationId}/status-change`, data, showSuccessMessage: true }) } // 从细胞存储转化 export function fetchConvertFromStorage(protocolId: string) { return request.post({ url: '/web/admin/research-donations/convert-from-storage', data: { protocolId }, showSuccessMessage: true }) } // 转为细胞存储 export function fetchConvertToStorage( donationId: string, data?: { desc?: string } ) { return request.post({ url: `/web/admin/research-donations/${donationId}/convert-to-storage`, data: data || {}, showSuccessMessage: true }) } ``` - [ ] **Step 2: 添加路由定义** 在 `web-admin/src/router/modules/sqxp.ts` 的细胞存储路由组之后(约 line 252),增加: ```typescript { id: '60000000000000000000000000000001', name: 'ResearchDonation', path: '/research-donation', component: '/index/index', meta: { title: '科研捐赠管理', icon: 'ri:hand-heart-line', keepAlive: false, roles: ['admin'] }, children: [ { id: '60000000000000000000000000000002', name: 'ResearchDonationList', path: 'list', component: '/research-donation/list/index', meta: { title: '捐赠协议单', keepAlive: true } }, { id: '60000000000000000000000000000003', name: 'ResearchDonationAudit', path: 'audit', component: '/research-donation/audit/index', meta: { title: '捐赠协议审核', keepAlive: true } } ] } ``` - [ ] **Step 3: 提交** ```bash git add web-admin/src/api/research-donation.ts web-admin/src/router/modules/sqxp.ts git commit -m "feat: 科研捐赠管理模块 — 前端 API 模块与路由定义" ``` --- ## Task 6: 前端 — 捐赠协议列表页 **Files:** - Create: `web-admin/src/views/research-donation/list/index.vue` **Reference:** `web-admin/src/views/cell-storage/protocol/index.vue`(列表页模式) **实现指导:** 参照 `cell-storage/protocol/index.vue` 的完整模式创建列表页,关键差异: 1. **搜索条件**:关键字(编号/母亲姓名)+ 状态下拉(dsx/sxz/ygq/yzf/zckc) 2. **表格列**:捐赠编号、捐赠日期、母亲姓名、状态、来源类型、采集专员、创建时间、操作 3. **操作按钮**:新增、批量删除、导出(可选) 4. **行操作**:查看、编辑、审核、状态变更、删除 5. **状态标签颜色**:dsx=info, sxz=success, ygq=warning, yzf=danger, zckc=primary 6. **无缴费相关按钮和筛选**(与细胞存储的关键区别) 组件导入:DonationFormDialog, DonationViewDialog, DonationAuditDialog, DonationStatusChangeDialog - [ ] **Step 1: 创建列表页** - [ ] **Step 2: 提交** ```bash git add web-admin/src/views/research-donation/list/index.vue git commit -m "feat: 科研捐赠管理模块 — 捐赠协议列表页" ``` --- ## Task 7: 前端 — 新增/编辑弹窗 **Files:** - Create: `web-admin/src/views/research-donation/list/DonationFormDialog.vue` **Reference:** `web-admin/src/views/cell-storage/protocol/ProtocolFormDialog.vue`(表单弹窗模式) **实现指导:** 参照 ProtocolFormDialog.vue 的模式,5 个 Tab: | Tab | 字段 | 说明 | |---|---|---| | 基本信息 | donationNo, donationDate, sourceType, remark | 编号自动/手动、日期、来源类型只读 | | 当事人信息 | 母亲/父亲/新生儿全部字段 | 与细胞存储一致 | | 采集信息 | 区域/医院/采集人/时间 | 与细胞存储一致 | | 样本信息 | 样本类型/编码/数量/储存年限(**无 price 字段**) | 可多行添加删除 | | 附件 | 知情同意书(**必传**)+ 其他附件 | 知情同意书独立上传区域 | 关键点: - 宽度 `1200px`,`label-position="top"` - 知情同意书 Tab 中分两个区域:必传的知情同意书 + 可选的其他附件 - 提交时校验 `consentFormUrls` 不能为空 - 样本 Tab 无金额/费用相关字段 - [ ] **Step 1: 创建表单弹窗组件** - [ ] **Step 2: 提交** ```bash git add web-admin/src/views/research-donation/list/DonationFormDialog.vue git commit -m "feat: 科研捐赠管理模块 — 新增/编辑弹窗(5 Tab)" ``` --- ## Task 8: 前端 — 查看/审核/状态变更弹窗 **Files:** - Create: `web-admin/src/views/research-donation/list/DonationViewDialog.vue` - Create: `web-admin/src/views/research-donation/list/DonationAuditDialog.vue` - Create: `web-admin/src/views/research-donation/list/DonationStatusChangeDialog.vue` **Reference:** - `web-admin/src/views/cell-storage/protocol/ProtocolViewDialog.vue` - `web-admin/src/views/cell-storage/protocol/ProtocolAuditDialog.vue` - `web-admin/src/views/cell-storage/protocol/ProtocolStatusChangeDialog.vue` - [ ] **Step 1: 创建 DonationViewDialog.vue** 参照 ProtocolViewDialog.vue,5 个 Tab 只读展示。宽度 `1600px`。 - [ ] **Step 2: 创建 DonationAuditDialog.vue** 参照 ProtocolAuditDialog.vue。审核状态选择(shtg/shth)+ 备注。支持批量。 - [ ] **Step 3: 创建 DonationStatusChangeDialog.vue** 参照 ProtocolStatusChangeDialog.vue。支持的操作: - 生效(dsx → sxz) - 过期(sxz → ygq) - 作废(dsx/sxz → yzf) - **转细胞存储**(sxz → zckc)— 新增操作 每个操作有时间 + 描述字段。 - [ ] **Step 4: 提交** ```bash git add web-admin/src/views/research-donation/list/DonationViewDialog.vue \ web-admin/src/views/research-donation/list/DonationAuditDialog.vue \ web-admin/src/views/research-donation/list/DonationStatusChangeDialog.vue git commit -m "feat: 科研捐赠管理模块 — 查看/审核/状态变更弹窗" ``` --- ## Task 9: 前端 — 审核管理页 **Files:** - Create: `web-admin/src/views/research-donation/audit/index.vue` **Reference:** `web-admin/src/views/cell-storage/protocol-audit/index.vue` - [ ] **Step 1: 创建审核管理页** 参照 protocol-audit/index.vue 模式: - 列表展示待审核/已审核的捐赠记录 - 批量审核、批量生效、批量作废等操作 - 调用 `fetchResearchDonationAuditList` API - [ ] **Step 2: 提交** ```bash git add web-admin/src/views/research-donation/audit/index.vue git commit -m "feat: 科研捐赠管理模块 — 审核管理页" ``` --- ## Task 10: 细胞存储端 — 增加「转科研」操作 **Files:** - Modify: `web-admin/src/views/cell-storage/protocol/ProtocolStatusChangeDialog.vue` **Reference:** 读取现有文件,在状态变更操作中增加 `zky`(转科研)选项 - [ ] **Step 1: 修改 ProtocolStatusChangeDialog.vue** 在现有的状态变更操作中增加「转科研」选项: - 操作类型增加 `zky` - 调用 `fetchConvertFromStorage(protocolId)` API(从 research-donation.ts 导入) - 成功后刷新列表 - [ ] **Step 2: 提交** ```bash git add web-admin/src/views/cell-storage/protocol/ProtocolStatusChangeDialog.vue git commit -m "feat: 细胞存储协议 — 增加转科研操作" ``` --- ## Task 11: 联调与验证 - [ ] **Step 1: 后端验证** ```bash cd backend && source venv/bin/activate python -c "from app.models.research_donation import *; print('Models OK')" python -c "from app.api.research_donation import router; print('Router OK')" ``` - [ ] **Step 2: 前端验证** ```bash cd web-admin && pnpm build ``` 预期:构建通过,无 TS 错误。 - [ ] **Step 3: 数据库建表** 在开发环境执行 `docs/sql/research_donation_tables.sql`。 - [ ] **Step 4: 功能验证清单** | 功能 | 验证方式 | |------|---------| | 列表展示 | 访问 `/#/research-donation/list` | | 新增捐赠 | 填写 5 个 Tab,提交 | | 知情同意书必填校验 | 不传知情同意书,提交应报错 | | 编辑捐赠 | 修改后保存 | | 查看详情 | 5 Tab 只读展示 | | 删除(单个/批量) | 软删除 | | 审核流程 | 审核页面操作 | | 状态变更 | 生效/过期/作废 | | 转细胞存储 | 捐赠 → 细胞存储协议 | | 细胞存储转科研 | 细胞存储 → 科研捐赠 |