diff --git a/docs/superpowers/specs/2026-10-13-research-donation-list-excel-parity-design.md b/docs/superpowers/specs/2026-10-13-research-donation-list-excel-parity-design.md new file mode 100644 index 00000000..dd9492fe --- /dev/null +++ b/docs/superpowers/specs/2026-10-13-research-donation-list-excel-parity-design.md @@ -0,0 +1,203 @@ +# 科研捐赠列表对齐 Excel「科研表」— 设计 + +> 日期:2026-10-13 +> 状态:待用户审阅 +> 参考:`中科兴皖采集大表20260720.xlsx` sheet「科研表」 +> 页面:`/#/market/cell-storage/protocol-audit?tab=research_donation` +> 源码:`web-admin/src/views/cell-storage/protocol-audit/DonationProtocolTab.vue` +> 小程序:`mobile-oa-h5` 协议模块 `research_donation` 列表卡片(`list-presenter.js` / `modules/protocol.js`) +> 表:`biz_research_donation`(模型 `backend/app/models/research_donation.py`) + +--- + +## 1. 背景与目标 + +### 1.1 背景 + +客户 Excel「科研表」是科研捐赠采集台账。当前 Web「采集协议单 · 科研捐赠」列表列偏少(缺状态、废弃原因、临床字段、附件有无、备注等),且与 Excel 对照不便。小程序协议列表对科研捐赠也未按该台账字段展示。 + +### 1.2 目标 + +1. Web 科研捐赠列表列对齐 Excel「科研表」字段映射(见 §3),去掉运费与「是否同存」。 +2. 新增业务字段 **当月核量号**(创建时生成,历史不回填),仅列表展示。 +3. 小程序科研捐赠列表卡片字段集合与 Web 对齐(布局可折叠/多行,但字段不缺)。 +4. 知情同意书 / 传染病检测报告 / 协议书(其他附件)在列表仅显示「有」或「—」。 + +### 1.3 非目标 + +- 不改【细胞存储】Tab 列表。 +- 详情弹窗、新建/编辑表单不展示当月核量号。 +- 不回填历史当月核量号。 +- 不展示运费(多协议共享,不适合单行协议列表)。 +- 不做 Excel 导入/导出。 +- 不改附件上传业务规则,仅列表读现有 URL 字段判断有无。 + +--- + +## 2. 已确认决策 + +| 项 | 结论 | +|----|------| +| 落地方案 | **方案 1**:`biz_research_donation` 新增字段 + 创建时取号 | +| 当月核量号格式 | `YYYYMM` + 三位序号,如 `202508001` | +| 取号年月 | 一律按 **创建时间** 所在年月(不看采集时间) | +| 取号时机 | **创建**科研捐赠单时 | +| 历史数据 | **不回填**;旧单该列显示「—」 | +| 展示范围 | **仅列表**(Web + 小程序科研捐赠列表) | +| 附件列 | 有附件 →「有」;无 →「—」 | +| 年/月/日 | 继续用 **采集日期** 一列(不拆三列) | +| 储存状态 | 用 **协议单状态**(`donationStatus`) | +| 协议书 | 对应附件字段 **其他附件**(`attachmentUrls`) | +| 「台词」 | 按 **胎次**(`birthOrder`)理解 | +| 是否同存 | 科研捐赠列表 **去掉** | +| 运费 | **不展示** | +| 软删占用 | 已占用序号 **不回收**(含 `del_flag=1` 计入已用最大序号) | + +--- + +## 3. Excel「科研表」→ 系统映射 + +| Excel 字段 | 系统处理 | +|------------|----------| +| 序号 | 列表 UI 行号(已有) | +| 年份 / 月 / 日 | **采集日期**(`sampleCollectTime` 日期部分) | +| 当月核量号 | **新字段** `monthly_verify_no` / API `monthlyVerifyNo` | +| 实验室编码 | 已有:实验室流转编号(样本 `labStorageCode` / 样本编码侧展示,与现网「实验室流转编号」一致) | +| 储存状态 | 协议状态 `donationStatus`(Tag) | +| 废弃原因 | 已有:作废相关描述(优先 `voidDesc`;若列表需补充类型文案可用 `voidType` 字典标签,实现时与现网状态变更字段对齐) | +| 母亲姓名 | 已有 | +| 围产期造血干细胞(Excel 品类/去向混用) | 系统展示 **样本类型**(已有) | +| 采集地区 / 采集医院 | 已有 | +| 分娩时间 / 采集时间 | 已有(分娩时间=`newbornDeliveryTime`,采集时间=`sampleCollectTime`) | +| 市场专员 / 地区经理 / 运输方式 | 已有 | +| 运费 | **不要** | +| 性别 / 新生儿体重 / 分娩方式 / 胎次 / 母血采集时间 | 已有 | +| 知情同意书 | `consentFormUrls` 非空 →「有」 | +| (额外)传染病检测报告 | `infectiousDiseaseReportUrls` 非空 →「有」 | +| (额外)协议书 | `attachmentUrls`(其他附件)非空 →「有」 | +| 备注 | 协议备注 `remark` | + +--- + +## 4. UI 规格 + +### 4.1 Web(`DonationProtocolTab.vue`) + +骨架不变:筛选 → 工具栏 → `el-table` → 分页。 +视觉:Fresh Mint;状态用 `el-tag`;操作列 `fixed="right"`,`min-width` ≥ 260。 + +**表格列(从左到右):** + +| 列 | 来源 | 说明 | +|----|------|------| +| 选择 | — | 已有 | +| 序号 | 前端 | 当前页行号 | +| 采集日期 | `sampleCollectTime` | `YYYY-MM-DD`;无则「—」 | +| 当月核量号 | `monthlyVerifyNo` | 空则「—」;建议 monospace | +| 实验室流转编号 | 样本实验室编码 | 与现网一致;无则「—」 | +| 协议状态 | `donationStatus` | Tag;列头可用「协议状态」(对应 Excel 储存状态) | +| 废弃原因 | `voidDesc`(及必要时类型标签) | 无则「—」 | +| 母亲姓名 | `motherName` | | +| 样本类型 | 样本类型名 | | +| 采集地区 | `regionName` | | +| 采集医院 | `hospitalName` | | +| 分娩时间 | `newbornDeliveryTime` | | +| 采集时间 | `sampleCollectTime` | 完整时间 | +| 市场专员 | `salesUserName` | | +| 地区经理 | `regionManagerUserName` | | +| 运输方式 | 运输相关字段 | 与现网一致 | +| 新生儿性别 | `newbornSex` | | +| 新生儿体重 | `newbornWeightGram` | | +| 分娩方式 | `deliveryMode` | | +| 胎次 | `birthOrder` | | +| 母血采集时间 | `maternalBloodCollectTime` | | +| 知情同意书 | 附件有无 | 「有」/「—」 | +| 传染病检测报告 | 附件有无 | 「有」/「—」 | +| 协议书 | 附件有无 | 「有」/「—」 | +| 备注 | `remark` | | +| 操作 | — | 已有 | + +宽表允许横向滚动;列均用 `min-width`。 + +### 4.2 小程序(`mobile-oa-h5`) + +- 仅当 `source === 'research_donation'` 时切换卡片字段集(细胞存储卡片不变)。 +- 卡片标题/副标题可保留母亲姓名 + 实验室流转编号/样本编码;**fields** 覆盖上表业务字段(除选择/序号/操作)。 +- 附件三列同样「有」/「—」。 +- 当月核量号展示在靠前字段(建议紧随采集日期或实验室编码之后)。 + +--- + +## 5. 数据与后端 + +### 5.1 字段 + +表 `biz_research_donation` 新增: + +| DB 列 | 类型 | 可空 | 说明 | +|-------|------|------|------| +| `monthly_verify_no` | `VARCHAR(16)` | YES | 当月核量号,如 `202508001`;历史为空 | + +ORM / `_donation_to_dict` / 列表聚合响应增加 `monthlyVerifyNo`。 + +建议索引(租户内按号查询与防重): + +- `UNIQUE (tenant_no, monthly_verify_no)` — MySQL 下多行 `NULL` 不冲突,符合历史留空。 + +SQL 迁移放入 `docs/sql/migrations/2026-10-13-research-donation-monthly-verify-no.sql`。 + +### 5.2 取号算法 + +创建捐赠单成功写入前: + +1. `ym = create_time` 格式化为 `YYYYMM`(服务器时间与写入 `create_time` 一致)。 +2. 在同 `tenant_no` 下查询 `monthly_verify_no` 以 `ym` 为前缀的最大序号(**包含** `del_flag=1`,避免软删回收号)。 +3. `next = max_seq + 1`;格式化为三位,拼成 `f"{ym}{next:03d}"`。 +4. 写入 `monthly_verify_no`;唯一约束冲突时重试有限次。 + +并发:优先「查最大 + 唯一索引 + 重试」;若实现中发现冲突频繁,可再评估复用 `biz_biz_no_sequence`(本设计不强制新计数器表)。 + +### 5.3 列表 API + +- Web:`fetchResearchDonationList` 所用列表接口须返回本设计所需字段(含 `monthlyVerifyNo`、附件 URL 或布尔有无、临床/采集/作废字段)。若现网列表已 join party/collection/sample,则补序列化即可;缺字段则在 list DTO 中补齐。 +- 小程序:`market` 协议列表 `research_donation` 同源字段对齐,供 `protocolCard` 使用。 +- 附件有无:**前端**对列表已有 URL 字段(`consentFormUrls` / `infectiousDiseaseReportUrls` / `attachmentUrls`)判非空即可;若某端列表当前未返回这些字段,则在该端 list 序列化中补齐 URL 字符串(不新增布尔字段)。 + +### 5.4 不变 + +- 创建以外路径(编辑、状态变更、转换细胞存储等)**不重算、不修改**当月核量号。 +- 详情/表单 API 可带上该字段但 UI 不展示(可选,避免双源;最小改动可只在 list 序列化中输出)。 + +--- + +## 6. 测试要点 + +1. 新建科研捐赠:同月连续创建得到 `…001`、`…002`;跨月前缀变化且序号从 `001` 起。 +2. 历史单据:迁移后 `monthlyVerifyNo` 为空,列表显示「—」;新建不受历史空值干扰(从 `001` 或已有最大+1)。 +3. 软删后再创建:不复用已删单号。 +4. Web 列顺序与有无符合 §4.1;无「是否同存」、无运费。 +5. 附件:三类 URL 有/无时分别显示「有」/「—」。 +6. 小程序科研捐赠卡片字段与 Web 集合一致;细胞存储卡片回归不变。 + +--- + +## 7. 影响面 + +| 区域 | 文件(预期) | +|------|----------------| +| SQL | `docs/sql/migrations/2026-10-13-research-donation-monthly-verify-no.sql` | +| Model / CRUD | `backend/app/models/research_donation.py`,`backend/app/crud/research_donation.py`(create + list 序列化) | +| Market list(若独立) | `backend/app/services/market_protocol.py` 等科研列表装配 | +| Web 列表 | `DonationProtocolTab.vue`;必要时 `research-donation` API 类型 | +| 小程序 | `mobile-oa-h5/src/market/list-presenter.js`(及对应测试) | +| 测试 | 后端取号单测;前端/小程序列表字段契约测试 | + +--- + +## 8. 验收标准 + +- [ ] 科研捐赠 Web 列表列与 §4.1 一致,细胞存储 Tab 无回归。 +- [ ] 新创建单据有正确当月核量号;历史为空显示「—」。 +- [ ] 附件三列仅「有」/「—」。 +- [ ] 小程序科研捐赠列表字段对齐;细胞存储卡片不变。 +- [ ] 迁移 SQL 与模型字段一致,可通过字段一致性相关检查(若适用)。