docs: 生产接收接种量文本化与冻存时间仅日期设计

明确接种量改为 VARCHAR(255) 自由文本,冻存时间交互与展示仅保留 YYYY-MM-DD。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zlwuandCursor committed 2026-08-31 14:54:22 +08:00
1 parent 9aa786a8c5
commit fdd219c1e7
1 file changed
+103
@@ -0,0 +1,103 @@
# 生产接收:接种量文本化、冻存时间仅日期 — 设计
> 日期:2026-08-31
> 状态:待实现
> 范围:`web-admin`「样本接收信息填写」弹窗(生产工单 / 我的生产任务共用);`backend` 生产接收 API/模型;`docs/sql` 迁移
> 方案:接种量 `VARCHAR(255)` 自由文本;冻存时间保留 `datetime` 列、交互与展示仅日期
> 影响页面:`/#/production-group/production/production-work-order`、`/#/production-group/production/my-production-task`
## 1. 背景与目标
现状:
- **接种量**(`inoculationAmount`)字段定义为 `kind: 'number'`,弹窗使用 `DecimalInput`,库表为 `decimal(18,4)`,无法录入单位或说明文案。
- **冻存时间**(`cryopreservationTime`)使用 `el-date-picker type="datetime"`,读写含时分秒。
目标:
- 接种量改为普通文本输入,支持数字 + 文字等自由组合,最长约一两句话(**`VARCHAR(255)`**)。
- 冻存时间不要时分秒:选择与展示均为 **`YYYY-MM-DD`**。
## 2. 已确认决策
| 决策点 | 结论 |
|--------|------|
| 接种量长度 | `VARCHAR(255)`(方案 B) |
| 接种量实现 | 库表改字符串 + 前后端按 string 读写 + `el-input` |
| 冻存时间库表 | 保持 `datetime`,不改为 `DATE` |
| 冻存时间交互 | 与「处理时间」一致:`type="date"`,`value-format="YYYY-MM-DD"` |
| 冻存时间落库 | 前端传日期串;后端 `parse_datetime` 解析为当日 `00:00:00` |
| 冻存时间展示 | 只读 / 回填均截取或格式化为 `YYYY-MM-DD` |
| 共用组件 | `SampleReceptionDialog.vue` 一处改,两页同时生效 |
| 本期不做 | 其它数值字段;备注替代接种量;冻存列改 `DATE` |
## 3. 字段行为
### 3.1 接种量
| 层 | 变更 |
|----|------|
| 字段定义 | `sample-production-reception-fields.ts`:`kind: 'text'`;类型 `inoculationAmount?: string` |
| 弹窗编辑 | `el-input`(已有 `kind === 'text'` 分支),`clearable`,`maxlength="255"`(建议 `show-word-limit` 可选,非必须) |
| 只读展示 | `formatProductionFieldValue` 原样字符串输出 |
| API / TS | `inoculationAmount?: string`(不再是 `number`) |
| Pydantic | `Optional[str]` |
| SQLAlchemy | `String(255)` |
| CRUD `_row_to_dict` | 返回 `row.inoculation_amount or ""`(或 `None` 按现有字符串字段习惯) |
| CRUD 写入 | `strip` 后写入;空串 → `NULL` |
| 校验 | 仍属 profile 必填字段时,非空字符串即可(沿用现有 `_validate_payload`) |
适用 profile(不变):
- `cell_storage` + 脐带间充质干细胞
- `research_donation` + 脐带间充质干细胞
### 3.2 冻存时间
| 层 | 变更 |
|----|------|
| 字段定义 | `kind` 由 `datetime` 改为 **`date`**(新增 kind,或与 datetime 分支并列) |
| 弹窗编辑 | `el-date-picker`:`type="date"`,`value-format="YYYY-MM-DD"`,placeholder「选择日期」 |
| 只读展示 | `formatDateOnly` / 与 `formatProcessTimeDate` 同类逻辑,输出 `YYYY-MM-DD` |
| 回填 | 历史带时分秒的值截取日期部分 |
| 后端 | 列类型不变;写入继续 `parse_datetime`(兼容 `YYYY-MM-DD` → 当日 0 点);读出可仍 `_fmt_dt`,由前端截日期,**或** API 对冻存时间直接返回日期串(二选一,推荐前端截取以少改 API) |
## 4. 数据库迁移
新增脚本(示例名):`docs/sql/2026-08-31-production-reception-inoculation-amount-varchar.sql`
```sql
-- 接种量:数值 → 自由文本(最长 255)
ALTER TABLE biz_sample_production_reception
MODIFY COLUMN inoculation_amount VARCHAR(255) NULL COMMENT '接种量';
```
- MySQL 会将既有 `decimal` 值转为对应数字字符串,可接受。
- 基线 `docs/sql/zkxw.sql` 若含该表定义,实现时同步改列类型,避免新环境与迁移不一致。
## 5. 改动文件清单(预期)
| 文件 | 变更要点 |
|------|----------|
| `docs/sql/2026-08-31-*.sql` | `ALTER` 迁移 |
| `docs/sql/zkxw.sql`(若含该列) | 列类型同步 |
| `backend/app/models/models.py` | `inoculation_amount` → `String(255)` |
| `backend/app/api/sample_production_reception.py` | body 字段类型 `Optional[str]` |
| `backend/app/crud/sample_production_reception.py` | 读写作字符串;必要时 trim |
| `web-admin/src/utils/sample-production-reception-fields.ts` | kind / 类型 / 展示 |
| `web-admin/src/api/sample-production-reception.ts` | TS 类型 |
| `web-admin/src/views/production/production-work-order/SampleReceptionDialog.vue` | `date` kind 渲染;text 支持 maxlength |
## 6. 验收要点
1. 脐带间充质干细胞场景:接种量可输入如「约 5×10⁶ cells,接种体积 2ml」,保存后回显一致,最长 255。
2. 冻存时间选择器无时分秒;保存后查看 / 再编辑仅见日期。
3. 历史冻存时间含时分秒的数据,打开弹窗回填为日期部分,不报错。
4. 生产工单与我的生产任务行为一致。
5. 围产期造血干细胞等其它 profile 字段行为不变。
## 7. 非目标
- 不改质检域样本接收。
- 不改接种量以外的 `DecimalInput` 字段。
- 不做冻存时间时区转换(与现网处理时间一致:本地日期)。