医学无菌制剂 LIMS 检验管理系统 · 运维、部署与开发助手

概述

本技能封装了「无菌制剂 LIMS 检验管理系统」（Sterile Preparation LIMS）的完整前端源码与工程知识，使 WorkBuddy 能可靠地
一键部署、运行、排障、维护与二次开发这一系统。系统为纯静态前端：无后端数据库，数据存于浏览器 localStorage，
通过 Node.js (server.js) 或 file:// 直接打开即可运行，内置二级防火墙（访问网关 + 账号登录）、
电子签名、审计追踪、ALCOA+ 数据完整性与 CSV（IQ/OQ/PQ）验证等 GMP 合规特性。

源码随技能内置：assets/lims-system/（含 index.html、css/、js/、backend/、manifest.json、sw.js、guide.html）。
不再是外部固定目录引用——任何安装本技能的机器都能从零拉起一套可运行的 LIMS。

v4.0 新增：
- 离线容灾（js/resilience.js）：断网时写操作进 localStorage 队列，联网自动冲刷 + 自动备份；网络状态横幅与卡顿提醒。
- 数据校验（js/validation.js）：必填/数值范围（支持 95.0%-105.0% 格式）/日期顺序/重复/OOS 实时校验与 Toast 提醒。
- 药品追溯码识别（js/traceability.js）：20 位药品追溯码（Luhn 校验）、GS1 DataMatrix（GTIN-14/效期/批号/序列号）解析；手动输入 / 相机扫码（BarcodeDetector + jsQR 兜底、手电筒、摄像头切换、批量模式）/ 图片上传（拖拽、多图批量）三模式，扫码自动填表录入样品。
- PWA：manifest.json + sw.js，可安装为桌面应用并离线缓存核心资源。
- 零依赖 Node 后端（backend/，node:sqlite 内置，Node ≥22）：18 条 API 路由、JWT 登录、RBAC、服务端审计哈希链、备份恢复、应急改密 resetAdminPassword()。
- 完整软件化：install.bat（安装 + 桌面快捷方式 + 开机自启）、LIMS-Start.bat（健康检查 + 自动开浏览器）、uninstall.bat（卸载保留数据）、guide.html 快速使用指南。

v4.2 新增（本次升级）：
- 角色体系扩展：6 → 12 种角色，新增质量受权人(QP)、验证工程师、微生物检验员、理化检验员、留样管理员、设备管理员；后端 REGISTER_ROLES 同步放宽自注册工种。
- 4 个新模块：制药用水监测（water，PW/WFI/纯蒸汽，电导率/TOC/微生物限度/细菌内毒素等 9 项指标 + WATER_LIMITS 限值判定）、物料准入评价（admission，ADMISSION_INDEX 6 维 14 项加权评分）、AI辅助分析（ai，AI 项目登记台账 + 6 类场景库 + GMP/Part 11 合规提示）、工种与授权（workforce，标准工种库 + 资质矩阵 qualifications）。
- 新实体：waterSystems / admissionEvals / aiProjects / qualifications（实体总数 21 类）。
- 产品覆盖延伸：由无菌制剂扩展到生物制品、抗体药物、疫苗(mRNA/病毒载体)、细胞与基因治疗(CGT)、无菌医疗器械与药包材；检验项目库 42 项 / 4 组。
- RBAC 重构：backend/rbac.js 改为「角色分组」组合生成权限矩阵；新增 EQUIVALENCE_STEPS（等效性评价 6 步）等指标体系。
- 工作台按工种个性化：按当前角色/工种展示差异化待办与关注重点。

何时使用

• 用户要一键部署 / 新建一套可运行的 LIMS → 走部署流程（见下）。
• 用户报告「LIMS 无法启动 / 打不开 / 白屏」→ 走排障流程。
• 用户要启动、访问、迁移该系统。
• 用户要重置测试数据、改端口、改默认账号 / 网关密钥。
• 用户要在该系统上「加一个功能 / 模块」「改某个页面 / 表单」「对接新业务实体」。
• 用户询问系统有哪些模块、角色、账号、数据模型、合规特性。

核心能力

0. 一键部署（One-click Deploy）★ 新能力

本技能内置完整源码，可直接部署出一套全新的可运行实例，无需依赖任何外部目录。

方式 A — 用技能脚本（推荐，跨平台）：

# 部署到 ./lims-system 并后台启动 + 自动开浏览器
python "<技能目录>/scripts/deploy.py"

# 部署到指定目录 / 指定端口 / 不自动开浏览器
python "<技能目录>/scripts/deploy.py"  D:/my-lims  --port 9090
python "<技能目录>/scripts/deploy.py"  --no-browser
python "<技能目录>/scripts/deploy.py"  --no-server          # 仅复制源码
python "<技能目录>/scripts/deploy.py"  --foreground          # 前台阻塞(Ctrl+C 停止)

> 技能目录即 SKILL.md 所在目录；脚本会自动定位内置 assets/lims-system/ 源码，用户级 / 项目级安装均可用。

方式 B — 直接复制源码后双击启动器（Windows 一键）：
1. 把 assets/lims-system/ 整个目录复制到任意位置（如 D:/lims-system/）。
2. 双击其中的 start-server.bat → 自动起服务并打开 http://127.0.0.1:8080/index.html。

方式 C — 直接用浏览器打开（零依赖兜底）：
双击 assets/lims-system/index.html（file:// 协议，真实浏览器支持 localStorage，可正常启动）。

部署后访问 http://127.0.0.1:<端口>/index.html，默认测试账号 admin/admin。

1. 启动与访问

• 本地服务器（推荐）：运行部署目录里的 start-server.bat，用托管 Node 起
  server.js 8080（绑定 127.0.0.1，窗口隐藏、独立常驻），自动打开 http://127.0.0.1:8080/index.html。
• 直接双击 index.html（file://）：真实浏览器支持 localStorage，可正常启动，是绕开「后台进程被回收」的兜底方案。

2. 故障排查（最高频：「无法启动」）

绝大多数「无法启动」是本地服务在两次会话间被系统回收，并非代码错误。标准处理：
1. curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8080/index.html —— 200 即服务正常（强刷浏览器）；000 即服务掉了。
2. 重新双击部署目录的 start-server.bat 重启，再 curl 验证。
3. 彻底规避：直接 file:// 打开 index.html。
完整排查清单见 references/troubleshooting.md。

3. 模块与权限

系统含 31 个模块 / 6 个分组：概览（工作台、检验流程）、业务管理（样品、委托、结果、复核审批、报告、物料、供应商、药品追溯码）、
质量管理（偏差/OOS、稳定性、环境监测、制药用水、质控标准品、留样、物料准入评价、AI辅助分析）、资源管理（设备、人员、工种与授权、培训）、
系统管理（审计、检验项目库、设置、系统后台、数据健康检查）、合规与验证（CSV、ALCOA+、安全中心、CCS）。
完整清单与 routePermissions 权限映射见 references/modules.md。

4. 数据模型与账号

• 12 种角色：系统管理员、QA经理、质量受权人(QP)、QA专员、验证工程师、QC主管、QC检验员、微生物检验员、理化检验员、留样管理员、设备管理员、查看人员（RoleMeta 自动配部门/头像）。权限矩阵由「角色分组」组合生成（backend/rbac.js）；工种差异体现在工作台视图与检验项目授权（qualifications）。
• 默认测试账号（弱口令，仅测试环境）：
  admin/admin（系统管理员）、chenchen/123456、liuyang/123456、zhouqiang/123456、zhangming/123456（QC/QA 各角色）。
  切勿录入真实生产 / 放行数据。
• 全部 Store.getXxx() 读取入口与持久化约定见 references/data-model.md。

5. 二次开发指引

• 加模块：app.js 的 routes 追加 {path,title,icon,group}；按需加到 routePermissions；实现 render<Path>()（读 Store → 注入 #content → 绑表单 → 调 Store.add/update → 重渲染）。
• 加实体：data.js 增加种子 + get*/add*/update*，记得走安全存储封装。
• 改端口：仅改部署目录里 start-server.bat 的两处 8080。
• 改默认账号 / 密钥：data.js 的 seedUsers 与网关配置。
  详细步骤见 references/architecture.md §7。

资源

assets/lims-system/ —— 内置完整源码（可部署模板）

• index.html —— UI 外壳（登录 / 网关 / 主应用三段式），加载 js/data.js → js/app.js → js/resilience.js → js/validation.js → js/traceability.js。
• css/style.css —— 全部样式（暗色主题、登录卡、侧边栏、表格、表单、告警条等）。
• js/data.js —— 数据仓库层 Store（安全存储封装、角色/部门映射、种子数据、读写方法、网关/审计/备份/验证）。
• js/app.js —— 应用层 App（路由、权限、各模块视图、电子签名、CSV、ALCOA+ 等），v4.2 新增制药用水 / 物料准入 / AI辅助分析 / 工种与授权路由，共 31 个模块。
• js/resilience.js —— 离线写队列、联网冲刷与自动备份、网络监测横幅/Toast。
• js/validation.js —— 表单数据校验规则引擎（必填/范围/日期/重复/OOS）。
• js/traceability.js —— 药品追溯码识别（手动 / 相机扫码 / 图片上传三 Tab，GS1 DataMatrix + 20 位追溯码）。
• backend/ —— 零依赖 Node/SQLite 后端：server.js（18 条 API 路由 + 静态托管）、db.js（WAL、审计哈希链、备份、应急改密）、rbac.js（角色权限）、crypto.js（口令哈希）。
• manifest.json + sw.js —— PWA 清单与 Service Worker（可安装桌面应用、离线缓存）。
• guide.html —— 快速使用指南（安装、登录、核心模块、追溯码、FAQ）。
• package.json —— npm start 即 node backend/server.js（Node ≥22）。
• start-server.bat / LIMS-Start.bat / install.bat / uninstall.bat / stop-server.bat —— Windows 启动器与安装/卸载器（仅本地使用；SkillHub 上传时自动排除 .bat）。
• server.js —— 纯静态兜底服务器（无后端 API 场景）。

scripts/

• deploy.py —— 一键部署脚本：复制 assets/lims-system/ 到目标目录并启动本地服务器（后台 + 自动开浏览器）。

references/

• architecture.md —— 内置源码结构、App.init 访问流程、启动方式、存储模型、合规特性、二次开发总指引。
• modules.md —— 31 模块总表、routePermissions 权限映射、检验闭环主线。
• data-model.md —— 角色、seedUsers 默认账号、Store 读取方法清单、持久化约定。
• troubleshooting.md —— 「无法启动」修复、端口占用、jsdom 自检、网关/防火墙、重置数据、开发速查。
• first-deploy-checklist.md —— 首次部署清单：环境前置、三种部署方式、登录与二级防火墙、默认账号、演示数据确认、重置、排障、升级迁移、合规底线。
• agent-architecture-evaluation.md —— 本系统改造为 AGENT 架构的可行性评估：模块与流程按自主度分层（T0 全自动 → T3 强制人决策禁区）、关键能力与技术挑战、收益与风险对比、渐进式改造路径与旁路架构方案；结论为「有条件可行」——GMP / 21 CFR Part 11 红线决定 Agent 只能承担提示、人确认辅助与流程编排。
• engine-serviceization.md —— 引擎能力服务化改造 + 黄金用例集建设方案：7 项确定性引擎能力的服务边界、13 个接口定义与错误码/版本兼容策略、部署解耦、性能与可观测性目标、分阶段实施与灰度回滚，以及黄金用例集的准入标准、字段结构、断言口径与脱敏门禁。

版本变更记录

• 4.2.1：修正模块数量表述（实测 app.js 的 routes 为 31 个模块，此前误写为 32）——仅为文档勘误，无代码变更。
• 4.2.0（本次）：角色体系 6 → 12；新增制药用水监测、物料准入评价、AI辅助分析、工种与授权 4 个模块；新增 waterSystems / admissionEvals / aiProjects / qualifications 实体；产品覆盖延伸至生物制品、疫苗与 CGT、无菌医疗器械与药包材；RBAC 权限矩阵重构为角色分组生成；工作台按工种个性化；修正 package.json 版本号（原 3.2.0）与前端 v4.2.0 不一致；新增 Agent 架构评估与引擎服务化方案两份参考文档。
• 4.0.0：离线容灾、数据校验、药品追溯码识别（相机扫码 / 图片上传）、PWA、零依赖 Node/SQLite 后端、安装器 / 启动器 / 卸载器、快速使用指南。

安全与合规底线

• 系统存放的是 GMP 制药检验数据，含二级防火墙与电子签名。任何改动不得削弱访问控制、审计追踪或数据完整性。
• 默认账号 / 网关密钥为演示弱口令，仅用于测试环境；涉及真实身份、放行、生产数据时必须走合规通道，不对外部泄露密钥或测试数据。
• 改动代码前先确认当前是「测试环境」，避免误触真实业务数据。