ashuein/OpenQC

# OpenQC [](https://www.gnu.org/licenses/gpl-3.0) [](https://www.python.org/) [](https://vuejs.org/) [](https://fastapi.tiangolo.com/) [](https://www.sqlite.org/) 一款针对 PCR 诊断实验室的 Westgard Green Belt + Black Belt 开源替代方案——提供 Levey-Jennings 图表绘制、完整的 Westgard 规则实现、Six Sigma 分析、检测方法验证报告、符合 CDSCO/CE-IVD 要求的加密审计日志，以及基于 CDSCO 和 ICMR 指南训练的内置法规助手。免费、本地运行、无需订阅。 ## 功能 - **QC Monitor** -- 上传来自 QuantStudio、CFX Manager 及其他 PCR 仪器的 Excel 导出文件。应用全部 6 条 Westgard 规则（1-2s, 1-3s, 2-2s, R-4s, 4-1s, 10x），具备实时违规检测和 Levey-Jennings 图表绘制功能。 - **Sigma 分析** -- 计算每个检测项目的 Six Sigma 指标，绘制 NMEDx 标准化决策图表，并根据 sigma 性能获取自动 QC 规则推荐。 - **检测验证** -- 包含 LOD、LOQ、批内/批间精密度和线性度计算，支持用户自定义验收标准和结构化的合格/不合格报告。 - **审计追踪** -- 上传时进行 SHA-256 文件哈希、哈希链完整性验证、防篡改检测，并导出带有签名的 JSON/PDF 审计报告以满足 CDSCO 合规要求。 - **批次追踪器** -- 试剂和对照品批次登记册，具备效期追踪功能，并在批次变更时自动重置 Westgard 历史记录。 - **报告导出** -- 通过 WeasyPrint 生成 QC 运行、验证、sigma 分析和审计追踪的 PDF 报告。 - **法规助手** -- 通过本地 RAG 管道查询 CDSCO MD-15、ICMR 和 ISO 15189 指导文件，并提供带有引用来源的参考。 ## 技术栈 | 层级 | 技术 | |-------|-----------| | 前端 | Vue 3 + Vite, Pinia, Vue Router, Tailwind CSS v4, shadcn-vue 原语 (radix-vue), ECharts, Plotly.js | | 后端 | Python FastAPI, SQLAlchemy, Pydantic v2 | | 存储 | SQLite（结构化数据），ChromaDB（RAG embeddings） | | PDF 导出 | WeasyPrint + Jinja2 模板 | | RAG 管道 | PyMuPDF, pdfplumber, sentence-transformers, Anthropic Claude API | ## 架构 ``` ┌──────────── Design Workflow ────────────┐ │ Figma screen spec ──▶ UI implementation │ └──────────────────────┬──────────────────┘ │ ┌──────────────────────────── Frontend (Vue 3 + Vite) ────────────────────────────┐ │ App Shell │ Views │ shadcn-vue Primitives │ Stores │ API Clients │ Charts │ └───────────────────────────────┬─────────────────────────────────────────────────┘ │ HTTP/JSON ┌───────────────────────────────▼─────────────────────────────────────────────────┐ │ FastAPI Routers │ │ qc │ sigma │ validation │ audit │ lots │ rag │ └───────────────┬───────────────────────┬───────────────────────┬─────────────────┘ │ │ │ ┌───────▼───────┐ ┌────────▼────────┐ ┌──────▼────────┐ │ Engines │ │ Parsers │ │ Report Engine │ │ westgard │ │ instrument .xlsx │ │ PDF rendering │ │ sigma │ │ generic .xlsx │ └───────────────┘ │ validation │ │ regulatory .pdf │ │ audit │ └────────┬─────────┘ │ rag │ │ └───────┬────────┘ ┌───────▼────────┐ │ │ Regulatory Docs │ │ │ local PDF corpus│ │ └────────────────┘ ┌───────▼───────────┐ │ Repositories / DB │ │ SQLite │ │ ChromaDB │ └───────────────────┘ ``` ## 快速开始 ### 前置条件 - **Python 3.12+** — [python.org/downloads](https://www.python.org/downloads/) - **Node.js 18+** 和 **npm 9+** — [nodejs.org](https://nodejs.org/) - **Git** — [git-scm.com](https://git-scm.com/) ### 1. 克隆仓库 ``` git clone https://github.com/ashuein/OpenQC.git cd OpenQC ``` ### 2. 安装后端依赖 ``` pip install -r backend/requirements.txt ``` 这将安装核心技术栈（FastAPI, SQLAlchemy, Pydantic, openpyxl）。特定功能所需的大型可选依赖项可以稍后添加——请参阅下表。 ### 3. 安装前端依赖 ``` cd frontend npm install cd .. ``` ### 4. 启动开发服务器 在项目根目录下打开两个终端： **终端 1 — 后端 API：** ``` uvicorn backend.main:app --reload --port 8000 ``` 数据库（`backend/data/openqc.db`）将在首次启动时自动创建。 **终端 2 — 前端开发服务器：** ``` cd frontend npm run dev ``` ### 5. 打开应用 - **前端 UI：** http://localhost:5173 - **后端 Swagger 文档：** http://localhost:8000/docs - **健康检查：** http://localhost:8000/ ### 6. 使用示例数据试用 示例 Excel 文件包含在 `backend/data/samples/` 中。通过 QC Monitor 上传 `sample_qc_violations.xlsx`，以查看 Westgard 违规检测的实际效果。 要重新生成示例文件： ``` python backend/data/samples/generate_samples.py ``` ### 可选依赖 核心应用无需这些依赖即可运行。可根据特定功能的需要安装： | 功能 | 包 | 安装命令 | 备注 | |---------|---------|---------|-------| | PDF 报告 | WeasyPrint | `pip install weasyprint` | 需要系统 GTK 库（[设置指南](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html)） | | RAG 摄取 | PyMuPDF, pdfplumber | `pip install PyMuPDF pdfplumber` | 用于解析法规 PDF | | RAG Embeddings | sentence-transformers | `pip install sentence-transformers` | 下载大小约 500 MB，可在 CPU 上运行 | | RAG 回答 | Anthropic SDK | `pip install anthropic` | 设置 `ANTHROPIC_API_KEY` 环境变量 | | 向量存储 | ChromaDB | `pip install chromadb` | 本地持久化存储 | ### RAG 设置（可选） 要使用法规助手： 1. 将法规 PDF（CDSCO MD-15、ICMR 指南等）放置在 `backend/data/regulatory_docs/` 中 2. 安装 RAG 依赖：`pip install PyMuPDF pdfplumber chromadb sentence-transformers anthropic` 3. 设置你的 API 密钥：`export ANTHROPIC_API_KEY=sk-ant-...` 4. 启动后端并在法规助手视图中点击 **Ingest Documents**（一次性操作，在 CPU 上需 2-5 分钟） ## API 文档 后端运行时，访问 http://localhost:8000/docs 查看交互式 Swagger UI。 ## 项目结构 ``` OpenQC/ ├── backend/ │ ├── main.py # FastAPI app entry point │ ├── routers/ # API endpoint handlers │ ├── engine/ # Pure business logic │ ├── parsers/ # Excel/PDF file parsers │ ├── models/ # Pydantic schemas + SQLAlchemy ORM │ ├── db/ # Database + ChromaDB clients │ ├── utils/ # Stats, hashing, PDF templates │ ├── data/ # SQLite DB, regulatory docs, samples │ └── tests/ # pytest test suite ├── frontend/ │ ├── src/ │ │ ├── views/ # Page components │ │ ├── components/ # Reusable UI components │ │ ├── stores/ # Pinia state management │ │ ├── api/ # Backend API clients │ │ └── router/ # Vue Router config │ └── ... └── docs/ ├── ARCHITECTURE.md # System design ├── AI-ROUTING.md # Agent routing guide └── specs/ # Feature specifications ``` ## 运行测试 ``` # Backend 测试 python -m pytest backend/tests/ -v # Frontend build 检查 cd frontend npm run build ``` ## Westgard 规则参考 | 规则 | 触发条件 | 动作 | |------|---------|--------| | 1-2s | 1 个点 > mean +/- 2SD | 警告 | | 1-3s | 1 个点 > mean +/- 3SD | 拒绝 | | 2-2s | 连续 2 个点 > mean +/- 2SD（同侧） | 拒绝 | | R-4s | 批内极差 > 4SD | 拒绝 | | 4-1s | 连续 4 个点 > mean +/- 1SD（同侧） | 拒绝 | | 10x | 连续 10 个点在均值同一侧 | 拒绝 | ## 设计原则 - 本地优先：完全在单台工作站上运行，无需云服务 - 模块隔离：各引擎互不导入 - 文档优先：规范定义行为，代码遵循规范 - 临床美学：深色主题，灰度基调，仅针对 QC 状态使用语义颜色 ## 许可证 本项目基于 [GNU General Public License v3.0](LICENSE) 授权。 ## 未来规划 - 多用户及基于角色的访问控制 - Docker Compose 部署 - LIS/LIMS 集成（HL7 2.x） - Probit LOD 分析 - 同行组比对 - 仪器漂移检测 - 多轮 RAG 对话

标签：AV绕过, CDSCO合规, FastAPI, Force Graph, IVD体外诊断, Levey-Jennings图表, PCR检测, PDF报告导出, Python, SHA-256校验, Six Sigma分析, SQLite, Vue 3, Westgard规则, 医疗实验室软件, 合规性审计, 实验室信息管理, 开源医疗软件, 无后门, 检测分析验证, 试剂批号追踪, 质量控制系统, 逆向工具