# 临时质检 · 外部质检对象编号（手写）设计

**日期：** 2026-08-20  
**状态：** 已评审待实现  
**范围：** web-admin 质检工单「临时质检」手动新增/编辑 + 列表/详情展示；backend `biz_qc_work_order` 字段与校验  

## 1. 背景与问题

当前「新增临时质检工单」弹窗中「质检对象」仅能从系统细胞产品主数据（`GET /web/admin/cell-products` → `biz_cell_product`）选择；创建/更新时后端强制校验 `cell_product_id` 必须存在。

客户场景：部分样品来自外部科研机构，**不在系统细胞产品库中**，希望能手写一个编号作为质检对象标识。

## 2. 需求结论（已确认）

| 项 | 结论 |
|---|---|
| 交互 | 方案 A：来源切换（系统细胞产品 / 外部科研编号） |
| 外部信息 | 只要一个编号 |
| 唯一性 | 不强制；同一编号可多次建单（复检/多批次） |
| 格式 | 无特殊格式；trim 后非空，最长 64 |
| 与细胞产品关联 | 不需要；全程不绑细胞产品，纯展示标识 |
| 范围 | 手动新增/编辑 + 列表/详情展示；**生产派发临时质检链路不动** |

## 3. 方案选择

采用 **方案 1：工单表增加外部编号字段**。

- 不借用 `sample_code` / `remark`（语义污染）
- 不为外部编号自动创建伪细胞产品（污染主数据，且与「不绑定」冲突）
- 不新增独立 `qc_target_source` 列：由 `cell_product_id` 与 `external_target_code` 互斥存在推导来源

## 4. 数据模型

### 4.1 表字段

表：`biz_qc_work_order`

| 字段 | 类型 | 可空 | 说明 |
|---|---|---|---|
| `external_target_code` | `VARCHAR(64)` | YES | 外部质检对象编号（手写） |

放置位置：业务字段区，建议紧挨 `cell_product_id` 之后。同步更新 SQLAlchemy `BizQcWorkOrder`、`docs/sql/` 增量脚本。

### 4.2 互斥不变量（仅临时工单手动创建/编辑）

对 `work_order_type = temporary` 的手动写入：

1. **系统产品**：`cell_product_id` 必填且在本租户存在；`external_target_code` 必须为空（写库时清空）
2. **外部编号**：`external_target_code` 必填（trim 后非空且 ≤64）；`cell_product_id` 必须为空（写库时清空）
3. 二者不可同时有值；亦不可同时为空

入库/出库工单、生产派发临时质检：**不应用上述外部编号写入路径**（派发仍只写既有 `cell_product_id` 逻辑）。

### 4.3 API 契约

**创建/更新请求（临时）：**

- 保留 `cellProductId`（可选）
- 新增 `externalTargetCode`（可选）
- 服务端按互斥规则校验并归一化（另一侧置空）

**列表/详情响应：**

- 继续返回 `cellProductId` / `cellProductCode` / `cellProductName` / 类型等（有关联时 enrich）
- 新增 `externalTargetCode`
- 不强制返回 `qcTargetSource`；前端可用字段有无推导

**列表 keyword：** 临时质检列表现有 keyword 仅匹配工单号；本期在临时工单（及通用列表在 `work_order_type=temporary` 或未限定类型时）keyword 条件中增加 `external_target_code` 模糊匹配。

## 5. 前端交互（方案 A）

文件焦点：`web-admin/src/views/quality-inspection/qc-work-order/index.vue` 新增/编辑弹窗。

1. **来源类型**：二选一（系统细胞产品 / 外部科研编号）
2. **质检对象**：
   - 系统：现有远程搜索下拉（`fetchCellProductList`）
   - 外部：单行输入，placeholder「请输入外部编号」
3. **备注**：不变

行为：

- 新增默认「系统细胞产品」
- 编辑：有 `cellProductId` → 系统并回填；有 `externalTargetCode` → 外部并回填
- 切换来源时清空另一侧已填值
- 提交只带当前来源字段；另一侧传空

前端校验与后端错误文案对齐：「请选择质检对象」「请填写外部编号」。

## 6. 列表 / 详情展示

| 场景 | 系统产品 | 外部编号 |
|---|---|---|
| 卡片主标题 `resolveTemporaryWorkOrderCardTitle` | `cellProductCode` | `externalTargetCode` |
| 卡片 meta（产品名称/类型等） | 照旧 | 增加「质检对象」展示外部编号；产品名称/类型显示 `—` |
| 详情 `buildTemporaryViewSections` | 产品编码/名称/类型等 | 「质检对象」= 外部编号 + Tag「外部」；产品字段 `—` |
| 任务子列表等同类「质检对象」展示 | 同步兜底外部编号 | 同上 |

列表卡片**不强制**加「外部」Tag（避免多色）；详情用 Tag 区分。

## 7. 改动面清单

| 层 | 内容 |
|---|---|
| SQL | `docs/sql/` 增加 `external_target_code` |
| Backend | `models` / `schemas` / `crud`：`create_temp_qc_work_order`、`update_qc_work_order`、列表 `_row_to_dict` / enrich、keyword |
| Frontend API | `QcWorkOrder` 类型增加 `externalTargetCode` |
| 弹窗 | `qc-work-order/index.vue` |
| 卡片 | `qc-work-order-card-meta.ts`（标题 + temporaryFields） |
| 详情 | `inbound-view-sections.ts` 中 `buildTemporaryViewSections`；相关任务子列表展示若有则一并 |

## 8. 明确不做

- 生产派发临时质检链路改造
- 外部编号唯一性、格式正则
- 自动创建细胞产品或事后关联回产品
- 入库/出库工单的质检对象模型变更

## 9. 验收标准

1. 系统产品路径：行为与现网一致（选产品、建单、列表/详情展示产品信息）
2. 外部编号路径：可建单、可编辑；可切换来源；库中 `cell_product_id` 为空且 `external_target_code` 有值
3. 同一外部编号可创建多张临时工单
4. 列表卡片标题与详情可见外部编号
5. 生产派发临时质检回归无回归问题（链路代码未改或行为不变）

## 10. 风险与注意

- 历史临时工单均无 `external_target_code`，展示逻辑须兼容「仅有 cell_product_id」
- 编辑时从外部切到系统（或反向）须清空对侧字段，避免脏数据写入
- `_validate_cell_product_id` 不可再对「外部路径」强制必填；拆成按来源分支校验