zkxw/docs/superpowers/specs/2026-06-17-cleanroom-garment-design.md

洁净服管理 — 需求分析与设计

日期: 2026-06-17
状态: 已实施
范围: web-admin + backend（生产管理 · 洁净服台账、清洗/灭菌登记、超限提醒）
需求来源: 用户新增（V0.3 需求文档暂无对应章节）

---

1. 背景与目标

1.1 业务背景

洁净服是 GMP 生产环境中的可重复使用资产，需要：

1. 台账登记：编号、名称、入库日期、清洗/灭菌报废次数阈值、废弃日期等；
2. 日常登记：批量记录清洗、批量记录灭菌（时间、登记人、备注）；
3. 合规提醒：累计清洗或灭菌次数达到阈值时给出提醒，不阻断登记（产品决策 A）；
4. 手动废弃：用户可主动确认废弃；已废弃洁净服不可再清洗、灭菌。

1.2 与现有系统关系

维度	说明
菜单位置	生产 → 生产管理（PRM00000000000000000000000000001），与生产工单、细胞产品库同级
类似模块	设备管理（P01 主数据）、洁净室管理（主表 + 子记录弹窗）、体检批量登记（多选 + 统一表单）
非关联模块	洁净室管理（运营支撑）管理房间与人员进出，与洁净服无强制外键关联

1.3 目标

• 支持洁净服 CRUD 与分页筛选；
• 支持列表多选后 批量清洗登记、批量灭菌登记；
• 支持单件洁净服的清洗/灭菌历史查看（行内弹窗）；
• 累计次数达限时在列表、批量保存、查看详情处 提醒，仍允许继续登记（未废弃时）；
• 支持 手动确认废弃；废弃后禁止清洗/灭菌登记。

---

2. 产品决策

#	问题	决策	状态
D1	达限后是否禁止继续登记？	否 — 仅提醒，记录可超过阈值（未废弃时）	✅ 已确认（选项 A）
D2	达限是否自动废弃？	否 — 不自动写废弃日期、不自动改状态	✅ 已确认
D3	达限提醒	任一维度达限即标记对应提醒（清洗达限 / 灭菌达限可并存）	✅ 默认
D4	手动废弃	用户通过 「确认废弃」 操作主动废弃；写入 discard_date（默认当天，可改）并设 garment_status=yfq	✅ 已确认
D5	已废弃后清洗/灭菌	禁止 — 单条/批量 API 拒绝；前端隐藏/禁用相关按钮	✅ 已确认
D6	编号生成	手工录入，租户内唯一；不做系统自动编号	✅ 默认
D7	登记人	批量/单条登记均可填；默认当前登录用户姓名	✅ 默认
D8	即将达限预警	首版不做；仅「已达限 / 未达限」两档	✅ 默认
D9	与洁净室关联	首版不做外键	✅ 默认
D10	取消废弃	首版不做专用入口；若需纠错，仅管理员通过编辑表单改回 zc 并清空 discard_date	✅ 默认

---

3. 数据模型

3.1 表结构

biz_cleanroom_garment — 洁净服主表

字段	类型	必填	说明
id	VARCHAR(64)	是	UUID 主键
garment_code	VARCHAR(64)	是	编号，租户内唯一
garment_name	VARCHAR(100)	是	名称
wash_discard_limit	INT	是	清洗几次需废弃（阈值，≥1）
sterilize_discard_limit	INT	是	灭菌几次需废弃（阈值，≥1）
inbound_date	DATE	是	入库日期
discard_date	DATE	否	废弃日期；确认废弃时写入
garment_status	VARCHAR(16)	是	zc 正常 / yfq 已废弃；以状态为准判断是否允许清洗/灭菌
tenant_no … del_flag	—	—	公共字段

说明：累计次数 不冗余 在主表，列表/详情通过子表 COUNT 或子查询计算；若性能不足后续再加冗余字段。

biz_cleanroom_garment_wash_log — 清洗记录

字段	类型	必填	说明
id	VARCHAR(64)	是	UUID
garment_id	VARCHAR(64)	是	洁净服 ID
wash_time	DATETIME	是	清洗时间
operator_user_id	VARCHAR(64)	否	登记人用户 ID
operator_name	VARCHAR(100)	否	登记人姓名（冗余）
tenant_no … del_flag	—	—	公共字段

biz_cleanroom_garment_sterilize_log — 灭菌记录

字段	类型	必填	说明
id	VARCHAR(64)	是	UUID
garment_id	VARCHAR(64)	是	洁净服 ID
sterilize_time	DATETIME	是	灭菌时间
operator_user_id	VARCHAR(64)	否	登记人用户 ID
operator_name	VARCHAR(100)	否	登记人姓名（冗余）
tenant_no … del_flag	—	—	公共字段

3.2 计算字段（API 返回，非表列）

字段	计算方式
washCount	COUNT(wash_log WHERE del_flag=0)
sterilizeCount	COUNT(sterilize_log WHERE del_flag=0)
washLimitReached	washCount >= wash_discard_limit
sterilizeLimitReached	sterilizeCount >= sterilize_discard_limit
needAttention	washLimitReached OR sterilizeLimitReached

3.3 ER 关系

biz_cleanroom_garment 1 ── * biz_cleanroom_garment_wash_log
biz_cleanroom_garment 1 ── * biz_cleanroom_garment_sterilize_log

---

4. 后端 API

路由前缀: /web/admin（production.py 或独立 cleanroom_garment.py，注册于 main.py）
权限: require_menu_code("production:cleanroom-garment:list") + apply_data_scope

4.1 洁净服主数据

方法	路径	说明
GET	/cleanroom-garments	分页列表
GET	/cleanroom-garments/{id}	详情（含累计次数与达限标志）
POST	/cleanroom-garments	新增
PUT	/cleanroom-garments/{id}	编辑
DELETE	/cleanroom-garments/{id}	软删
DELETE	/cleanroom-garments/batch	批量软删
POST	/cleanroom-garments/{id}/discard	确认废弃（单件）
POST	/cleanroom-garments/batch-discard	批量确认废弃

列表查询参数：

参数	说明
page, pageSize	分页
keyword	编号/名称模糊
garmentStatus	zc / yfq
needAttention	1 时仅返回 garment_status=zc 且 wash 或 sterilize 任一侧达限
washLimitReached	可选，清洗侧达限
sterilizeLimitReached	可选，灭菌侧达限

CreateBody / UpdateBody 字段（与 _row_to_dict 对齐，可写字段）：

garmentCode, garmentName, washDiscardLimit, sterilizeDiscardLimit, inboundDate, remark

只读字段（通过废弃接口写入，普通 Update 不可改）：

garmentStatus, discardDate

校验：

• garment_code 租户内唯一；
• wash_discard_limit、sterilize_discard_limit ≥ 1；
• inbound_date 必填；
• 新增时 garment_status 固定为 zc，discard_date 为空；
• 编辑表单 不直接提供 改状态/废弃日期（避免误操作）；废弃走专用接口。

确认废弃 Body（单件 / 批量共用字段）：

{
  "discardDate": "2026-06-17",
  "remark": "可选备注"
}

批量废弃 Body：

{
  "garmentIds": ["id1", "id2"],
  "discardDate": "2026-06-17",
  "remark": "可选"
}

废弃逻辑：

1. 仅 garment_status=zc 可废弃；已废弃返回 400「该洁净服已废弃」；
2. 设置 garment_status=yfq、discard_date（缺省为当天）、可选更新 remark；
3. 批量接口跳过已废弃项，返回 { successCount, skippedCount, skippedItems[] }。

4.2 清洗记录

方法	路径	说明
GET	/cleanroom-garment-wash-logs	按 garmentId 分页
POST	/cleanroom-garment-wash-logs	单条新增
PUT	/cleanroom-garment-wash-logs/{id}	编辑
DELETE	/cleanroom-garment-wash-logs/{id}	软删
POST	/cleanroom-garment-wash-logs/batch	批量清洗登记

批量清洗 Body：

{
  "garmentIds": ["id1", "id2"],
  "washTime": "2026-06-17 14:30:00",
  "operatorUserId": "可选",
  "operatorName": "张三",
  "remark": "备注"
}

批量逻辑：

1. 校验 garmentIds 非空，均属当前租户且未软删；
2. 若任一 garment_status=yfq，整批拒绝（400，列出编号），或前端预过滤仅提交正常项（后端仍强校验）；
3. 事务内逐条插入 wash_log；
4. 返回 { successCount, items: [{ garmentId, garmentCode, washCount, washLimitReached, ... }] } 供前端提示；
5. 不因达限拒绝（D1）；已废弃必拒绝（D5）。

单条新增/编辑清洗记录时，同样校验所属洁净服 garment_status=zc。

4.3 灭菌记录

与清洗对称，路径前缀 cleanroom-garment-sterilize-logs，字段 sterilizeTime。
同样禁止对已废弃洁净服新增/批量登记。

---

5. 前端设计

5.1 界面模式

部分	模式	参考
主列表	P01	views/production/equipment/index.vue
行内清洗/灭菌历史	P06 变体	views/operations/clean-room/index.vue（人员进出 / 紫外线消毒弹窗）
批量登记	批量表单弹窗	views/pilot-service/checkup-management/CheckupRegisterDialog.vue

Hash: /#/production-group/production/cleanroom-garment
源码: web-admin/src/views/production/cleanroom-garment/index.vue
menuCode: production:cleanroom-garment:list

5.2 页面结构

panel-top: 洁净服管理（panelTitleBarTextRules 注册）
filter-block:
  - 关键词（编号/名称）
  - 状态（正常/已废弃）
  - 需关注（checkbox：任一侧达限）
list-toolbar:
  - 已选 N 项
  - [新增洁净服] primary
  - [批量清洗登记] [批量灭菌登记]（仅选中项均为 zc 时可用）
  - [批量确认废弃]（仅选中项均为 zc 时可用）
  - [批量删除]
list-table:
  - 编号、名称、入库日期
  - 清洗（已洗/阈值，如 48/50）
  - 灭菌（已灭/阈值）
  - 提醒 Tag（见 §5.4）
  - 状态、废弃日期
  - 操作：查看 | 清洗记录 | 灭菌记录 | 确认废弃（仅 zc） | 编辑/删除
  - 已废弃行：清洗记录/灭菌记录可 **只读查看**；无「新增」按钮

5.3 弹窗

弹窗	宽度	内容
新增/编辑	720px	form-grid-2：编号、名称、两阈值、入库日期、备注（不含状态/废弃日期）
确认废弃	560px	废弃日期（默认今天）、备注；二次确认文案
批量确认废弃	560px	展示将废弃 N 件 + 统一废弃日期
查看	SystemViewDialog	主数据 + 累计次数 + 达限 Tag
清洗记录	960px	该服历史列表 + 单条增删改
灭菌记录	960px	同上
批量清洗登记	1000px	上：已选洁净服表；下：清洗时间、登记人、备注
批量灭菌登记	1000px	同上，灭菌时间

5.4 提醒与废弃交互

场景	行为
列表 Tag	washLimitReached → <el-tag type="warning"> 清洗达限；sterilizeLimitReached → 灭菌达限；garment_status=yfq → <el-tag type="info"> 已废弃
达限 + 未废弃	批量清洗/灭菌 允许；成功后 ElMessage.warning 提示「N 件已达报废次数，请安排废弃」
已废弃	批量/单条清洗灭菌按钮 禁用；API 返回 400
确认废弃	ElMessageBox.confirm → 调用 discard API → 成功提示；行状态刷新为已废弃
批量登记选中有废弃项	打开弹窗前过滤或提示「已自动排除 N 件已废弃洁净服」

status-tag-registry.ts 新增：

• garmentStatus: zc → success 正常, yfq → info 已废弃
• 达限 Tag 使用 column template 内联 warning，不必注册为独立枚举

5.5 API 函数（admin.ts 或 production 域）

fetchCleanroomGarmentList, fetchCleanroomGarmentDetail, fetchCreateCleanroomGarment, …
fetchDiscardCleanroomGarment, fetchBatchDiscardCleanroomGarments, …
fetchBatchCreateCleanroomGarmentWashLogs, fetchBatchCreateCleanroomGarmentSterilizeLogs, …

---

6. 菜单与路由

6.1 sys_menu INSERT

字段	值
id	95000000000000000000000000000003
menu_name	洁净服管理
parent_id	PRM00000000000000000000000000001
menu_type	C
path	cleanroom-garment
component	/production/cleanroom-garment/index
perms	production:cleanroom-garment:list
order_num	8（样本接收信息完善之后，实施时按现有 order 微调）

6.2 同步文件

• docs/sql/migrations/2026-06-17-cleanroom-garment.sql
• backend/app/api/menu.py — 生产管理 children
• web-admin/src/router/modules/sqxp.ts — 同上

---

7. 实施清单（概要）

7.1 Backend

1. docs/sql/migrations/2026-06-17-cleanroom-garment.sql — 3 表 + 菜单
2. app/models/ — 3 个 Model（或 production_cleanroom_garment.py）
3. app/crud/cleanroom_garment.py — _row_to_dict、列表含 count 子查询、批量事务
4. app/api/production.py（或新模块）— 路由 + 权限
5. app/main.py + app/api/__init__.py 注册
6. python scripts/check_field_consistency.py

7.2 Frontend

1. src/api/admin.ts — API 封装
2. src/views/production/cleanroom-garment/index.vue — 主页面
3. 可选拆分：WashLogDialog.vue, SterilizeLogDialog.vue, BatchWashDialog.vue, BatchSterilizeDialog.vue
4. App.vue — panelTitleBarTextRules 增加「洁净服管理」
5. ./scripts/update-graph.sh backend web-admin

---

8. 测试要点

#	场景	期望
T1	新增洁净服	编号唯一，阈值 ≥1
T2	批量清洗 3 件	3 条 log，列表 washCount +3
T3	washCount 达到阈值	列表出现「清洗达限」Tag，仍可继续批量清洗
T4	确认废弃	状态变 yfq，写入 discard_date；清洗/灭菌 API 返回 400
T5	已废弃洁净服批量清洗	前端按钮禁用或后端拒绝
T6	批量确认废弃	多件 zc → yfq；已废弃项 skipped
T7	筛选「需关注」	仅返回任一侧达限且仍为 zc 的记录（已废弃不出现在需关注）
T8	软删洁净服	列表不可见，日志保留
T9	租户隔离	跨租户不可见
T10	权限	无 menuCode 不可访问 API

---

9. 不在首版范围

• 与洁净室/人员绑定
• 即将达限（剩余 N 次）预警
• 达限自动废弃
• 取消废弃 / 恢复为正常（专用入口）
• 导出 Excel、消息推送

---

10. 修订记录

日期	说明
2026-06-17	初稿；D1 确认选项 A（达限仅提醒，不阻断）
2026-06-17	补充 D4/D5：支持手动确认废弃；已废弃禁止清洗/灭菌