无菌制剂 LIMS 检验管理流程系统
Overview
本技能沉淀一套无菌制剂检验 LIMS 的业务流程、合规要求与可复用实现。它把"无菌制剂从
取样到批检验放行"的全链路数字化，保证数据满足 ALCOA+（可追溯、清晰、同步、原始、准确
+ 完整、一致、持久、可用）与 21 CFR Part 11 / 中国 GMP（药品数据管理规范） 的强制要求。
核心设计原则：
- 数据库是唯一可信源。前端只是视图；所有写操作必须落库并由服务端记录审计。
- 审计不可篡改。每条审计记录带 SHA-256 哈希链（
prevHash → 本记录哈希），任何篡改都会
在校验时暴露。 - 权限到操作级（RBAC）。角色决定能读/写哪些实体类型，服务端强制校验，前端校验只是体验。
- 演示/生产同一套代码。通过"是否接真实后端"切换；不要为测试环境单独写一套逻辑。
何时使用
- 搭建或扩展无菌制剂检验 LIMS（样品、检验委托、检验结果、设备、人员、报告等模块）。
- 设计符合 GMP 数据完整性的流程：电子签名、审计追踪、权限分级、关键数据复核。
- 实现 CSV/JSON 数据导出、每日自动备份、数据导入/恢复。
- 校验已有的 LIMS 导出包或审计追踪是否被篡改。
- 容器化 / 外网部署 LIMS，并加固静态资源（禁止公网访问数据库文件）。
合规基线（必读）
| 维度 | 要求 |
|---|---|
| 法规 | GMP（无菌药品附录）、21 CFR Part 11、中国药典 2025、药品记录与数据管理规范 |
| 数据完整性 | ALCOA+：可追溯、清晰、同步、原始、准确 + 完整、一致、持久、可用 |
| 审计追踪 | 关键操作（增删改、登录、导出、恢复）自动留痕，哈希链防篡改，可导出校验 |
| 电子记录/签名 | 操作者实名、时间戳、操作前后值（oldValue/newValue） |
| 权限 | 角色级 RBAC：系统管理员、质量负责人、QA 审核员、QC 检验员、生产操作员、设备管理员 |
| 放行 | 检验结果 → 复核 → 偏差/OOS 调查 → 报告 → 质量负责人电子放行 |
核心实体（17 类）
系统用单张宽表 entities(type, id, data JSON) 存储以下文档型实体：
samples（样品）、testOrders（检验委托/批检验）、testResults（检验结果）、equipment（设备/仪器）、
personnel（人员/培训）、reports（检验报告书）、qcStandards（质量标准/检验依据）、
deviations（偏差）、stability（稳定性考察）、envMonitoring（洁净区环境监测，含警戒限/行动限判定）、
validation（方法/工艺验证）、integrity（数据完整性检查）、materials（物料/原辅料）、
suppliers（供应商）、retentions（留样）、trainings（培训记录）、ccs（污染控制策略，7 大污染要素风险登记 + 基于风险的 EM 监测计划 + CCS 年度回顾）。
> 约定：导出/CSV 用的实体类型键取复数形式（与上面一致）。
标准检验流程（Workflow）
1. 取样/收样 samples（登记编码、批号、物料、取样量、存储条件、状态=已接收）
2. 检验委托 testOrders（关联样品，列明检验项目、依据标准、计划完成日期，状态=待检验）
3. 检验实施 testResults（逐项录入原始数据、判定、检验人/复核人，状态=检验中/已完成）
4. 数据复核 QA 复核 testResults（录入 oldValue/newValue，记录复核结论）
5. 偏差/OOS deviations（超标/偏差触发调查，关联 testOrders，闭环后关闭）
6. 报告书 reports（汇总结果、结论，质量负责人电子签名放行）
7. 留样/稳定性 retentions + stability（留样观察、长期/加速稳定性考察）
8. 环境监测/校验 envMonitoring（洁净区浮游菌/沉降菌/压差/温湿度）+ equipment（计量校验状态）
9. 审计追踪 所有写操作自动写入 audit_logs（哈希链）
任何一步的"写"都必须：① 落库 ② 服务端 addAudit 留痕。前端仅做乐观更新。
审计追踪哈希链（不可篡改实现）
每条审计记录字段：seq, timestamp, userId, userName, action, module, entityType, entityId, details, oldValue, newValue, hash。
哈希算法（与后端 db.js 完全一致，可据此离线校验）：
prevHash = 上一条记录的 hash；链首 prevHash = '0'*64
hash = SHA256( '|'.join([ prevHash, seq, timestamp, userName, action, module,
entityType, entityId, details ]) )
verifyAuditIntegrity()：从 seq=1 起逐条用上式重算，若与存储 hash 不符则该记录（及之后）不可信。
配套脚本 scripts/verify_export.py 可对任意导出的 limis-export-v1 JSON 离线校验审计链。
角色权限（RBAC 概要）
| 角色 | 典型操作 |
|---|---|
| 系统管理员 | 用户管理、设置、备份/恢复、导入/导出 |
| 质量负责人 | 报告电子放行、偏差关闭、审计查看 |
| QA 审核员 | 检验结果复核、偏差调查、环境监测审核 |
| QC 检验员 | 样品录入、检验实施、结果登记 |
| 生产操作员 | 取样登记、批生产信息 |
| 设备管理员 | 设备/仪器台账、校验计划 |
服务端 can(role, action, type) 决定允许的操作（create/read/update/delete）；无权限返回 403。
数据导出 / 备份 / 恢复
- CSV 导出：
/api/export/csv?type=某实体类型或audit或all，服务端读取权威数据并扁平化（含 UTF-8 BOM，Excel 中文不乱码）。 - 全量 JSON：
/api/export/json（管理员），结构{ _meta, entities, users, audit, settings }，format: "lims-export-v1"。 - 每日自动备份：物理拷贝
lims.db，默认每日 02:00，保留最近 20 个；开关写服务端设置。 - 导入/恢复：按实体 ID upsert；审计与用户不被覆盖；恢复采用"当前连接内整表覆盖"，避免替换文件导致连接崩溃。
手机号注册与短信验证码（v1.0.2）
系统支持手机号 + 短信验证码注册（GMP 环境不建议开放，测试/演示/外网运营按需开启）：
注册流程：登录页「📱 手机号注册」→ 填手机号/姓名/密码 → 获取验证码 → 校验通过创建账号并自动登录。
服务端强制校验（防刷）：
- 验证码：6 位数字，5 分钟有效，一次性使用，用完即作废；
- 防刷：同一手机号 60 秒冷却不可重发；最多错 5 次自动作废；
- 查重：已注册手机号不可重复注册（直接提示登录）；
- 角色限制：自注册仅可选「QC检验员 / 查看人员」，管理员后台可调整；
- 审计：发码/注册/登录全部写入哈希链审计（details 标注发送通道）。
三种发送通道（按优先级自动切换，失败自动降级不阻塞注册）：
| 优先级 | 通道 | 配置方式 |
|---|---|---|
| ① | 腾讯云短信直连（推荐，零依赖） | 系统设置「安全中心」填 SecretId / SecretKey / SDKAppID / 签名 / 模板ID；或环境变量 TENCENT_SMS_SECRET_ID/KEY/APP_ID/SIGN/TEMPLATE_ID。内置 TC3-HMAC-SHA256 签名直连 sms.tencentcloudapi.com（SendSms, Version 2021-01-11），模板参数 {1}=验证码、{2}=有效分钟 |
| ② | 通用 HTTP 网关（Webhook） | 安全中心「短信网关地址」或 SMS_GATEWAY_URL；服务端向该地址 POST {phone, code, scene:"register", ttlMinutes:5}，由网关转发真实短信 |
| ③ | 开发模式（默认） | 全部留空时验证码打印服务器控制台 [LIMS-SMS] ...，并随接口返回 devCode 自动回填表单 |
登录接口兼容手机号：POST /api/auth/login 的 username 传手机号也可登录（先按用户名匹配，再按手机号匹配）。
腾讯云开通 8 步：实名认证 → 开通短信服务 → 创建应用（拿 SDKAppID）→ 申请签名（1 个工作日过审）→ 申请验证码模板（如「您的验证码为{1}，{2}分钟内有效…」）→ CAM 创建 API 密钥 → 填入系统 → 发码实测。
代码示例与快速上手（可直接运行）
本技能附带零依赖（仅 Python 标准库）的可运行示例，演示完整闭环与合规要点，并可直接被
正式系统接受。推荐先读 examples/USAGE.md（含真实命令与输出）。
# 1) 跑一套完整检验闭环（取样→委托→结果→偏差→报告→审计），并导出国标 JSON
python examples/demo_lims.py --db ./run/lims.db --out ./run/export.json
# 2) 离线校验审计哈希链（不可篡改）
python scripts/verify_export.py ./run/export.json # → [OK] 共 N 条，未被篡改
# 3) 部署成只读 HTTP 服务（查看系统状态 / 导出包）
python examples/deploy.py --dir ./run --port 8080
脚本健壮性（v1.0.1 新增）：
- 文件路径写错 / 目录不存在 / 无写（读）权限时，不崩溃，打印明确的「如何修改」提示；
- 每一步业务操作都有 [步骤 N/6] 与 [写] 提示信息；
- 关键逻辑均有中文用法注释；deploy.py 端口被占用也会提示换端口。
系统版本对照（v1.0.2）：SKILL.md 知识库对应生产系统 v3.4（含手机号注册 + 短信验证码 + 腾讯云短信直连 + 开机自启）。
Resources
examples/（v1.0.1 新增 · 可直接运行）
demo_lims.py— 完整可运行的无菌制剂 LIMS 示例（sqlite3 + 审计哈希链 + 导出limis-export-v1）。
用法：python demo_lims.py [--db 路径] [--out 路径] [--no-seed]。deploy.py— 部署辅助：校验环境、播种数据、启动只读 HTTP 状态服务。
用法：python deploy.py [--dir 目录] [--port 端口] [--no-serve]。USAGE.md— 真实命令行示例与预期输出（含篡改演示、错误处理示例）。
scripts/
verify_export.py— 校验导出的 LIMS JSON（lims-export-v1）审计哈希链完整性。用法：
python verify_export.py <path-to-export.json>。输出每条断链位置，退出码 0=完整 / 1=被篡改 / 2=路径或权限错误（带修改提示）。
references/
api_reference.md— LIMS 后端 API 速查（鉴权、实体 CRUD、导出、备份、审计、设置）。
assets/
- （无；本技能为流程/知识型，不打包二进制模板。）
Any unneeded directories can be deleted. 本技能保留 scripts/、references/ 与 examples/，assets/ 可删。
