fbientrigo/westgard-sim

# westgard-sim 用于临床实验室内部质量控制 (QC) 的可复现模拟器 + 本地创作工作流，用于生成 UI/web 使用的静态数据。 ## TL;DR（可运行的最简流程） 在 PowerShell 中，从仓库根目录运行： ``` # 1) 创建/激活环境（仅首次） py -3.11 -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt # 2) 验证环境和 catalogo .\westgard_ops.ps1 -Action preflight # 3) 打开 authoring UI .\westgard_ops.ps1 -Action ui # 4) 生成真实静态输出 .\westgard_ops.ps1 -Action release # 5) 检查导出的结构 .\westgard_ops.ps1 -Action verify ``` 如果仅执行 `-Action ui`，在运行 export/release 之前，系统不会自动在 `outputs/web_data` 中生成 payloads。 ## 1. 环境要求 - Python `>=3.11`（在 `pyproject.toml` 中定义） - Windows 上推荐使用 PowerShell 7+ - 可用的 `pip` 验证版本： ``` python --version ``` ## 2. 环境配置（分步指南） ### Windows (PowerShell) ``` # 在 repo 根目录下 py -3.11 -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade pip pip install -r requirements.txt ``` 如果 PowerShell 阻止了脚本运行： ``` Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass .\.venv\Scripts\Activate.ps1 ``` ### macOS / Linux (bash/zsh) ``` python3.11 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip pip install -r requirements.txt ``` ## 3. 主要命令 ### 本地创作 UI ``` .\run_authoring_ui.ps1 ``` 或通过操作包装器： ``` .\westgard_ops.ps1 -Action ui ``` ### 可复现的操作 Pipeline ``` .\westgard_ops.ps1 -Action preflight .\westgard_ops.ps1 -Action release .\westgard_ops.ps1 -Action verify ``` ### 技术模拟与导出（无 UI） ``` python scripts/run_demo.py python scripts/export_web_data.py --output-dir outputs/web_data ``` 使用完整目录： ``` python scripts/export_web_data.py --catalog content/experiment_catalog.json --output-dir outputs/web_data ``` ### 测试 ``` pytest ``` ### 抽认卡：编辑与导出 当前可编辑的卡组： - `content/flashcards/westgard_qc_basics.deck.json` 详细指南： - `docs/FLASHCARDS_GUIDE.md` 推荐使用仓库的 `.venv` 环境执行命令： ``` .\.venv\python.exe scripts\export_flashcards.py --deck content/flashcards/westgard_qc_basics.deck.json --output-dir outputs/flashcards/westgard_qc_basics ``` 预期输出： - `outputs/flashcards/westgard_qc_basics/westgard_qc_basics.csv` - `outputs/flashcards/westgard_qc_basics/preview.html` - `outputs/flashcards/westgard_qc_basics/flashcards.css` - `outputs/flashcards/westgard_qc_basics/manifest.json` - `outputs/flashcards/westgard_qc_basics/study_deck.json` 即时可视化检查点： - 打开 `outputs/flashcards/westgard_qc_basics/preview.html` - 将数据同步至 Web：`cd apps/student-web && npm run sync:data` ### Web 端抽认卡 学生 Web 端现已包含带有三个卡组及本地进度记录的交互式抽认卡功能。 推荐工作流： ``` # 1) 导出 deck .\.venv\python.exe scripts\export_flashcards.py --deck content/flashcards/westgard_qc_basics.deck.json --output-dir outputs/flashcards/westgard_qc_basics # 2) 将静态 assets 同步到 frontend cd apps/student-web npm run sync:data # 3) 运行本地 web npm run dev ``` Web 端路由： - `/#/flashcards` Web 端调用的文件： - `public/flashcards/westgard_qc_basics/study_deck.json` MVP 行为说明： - 三个卡组：新卡、练习中和复习 - 无后端；进度保存在 `localStorage` 中 - 基础控制按钮：`Mostrar respuesta`、`Repetir`、`La supe` - 如果答错卡片，则退回至卡组 1 - 如果答对卡片，则前进至下一个卡组 ## 4. 生成 UI 数据的正确工作流 推荐的创作工作流如下： 1. `preflight`：验证文件、依赖项和 schema。 2. `ui`：编辑/验证创作目录。 3. `release`：构建技术目录 + 静态导出 + 验证 + 备份。 4. `verify`：对导出结果进行独立检查。 操作工作流的默认路径： - 创作输入：`content/authoring_catalog.example.json` - 生成的技术目录：`content/experiment_catalog.generated.json` - Web 导出：`outputs/web_data` - 备份：`outputs/backups` 执行 `release` 后的最小预期输出： - `outputs/web_data/index.json` - `outputs/web_data/experiments//manifest.json` - `outputs/web_data/experiments//.json` ## 5. 学生端前端（包含在此仓库中） 前端位于 `apps/student-web`，直接调用由 Python 导出的契约数据。 ### 快速本地工作流 1. 生成数据集： ``` .\westgard_ops.ps1 -Action release ``` 2. 安装前端依赖（首次执行）： ``` .\student_web_ops.ps1 -Action install ``` 3. 同步数据集 + 可选的教育内容： ``` .\student_web_ops.ps1 -Action sync ``` 4. 运行前端： ``` .\student_web_ops.ps1 -Action dev ``` ### 在 GitHub Pages 上构建与部署 - 工作流：`.github/workflows/student-pages.yml` - 该工作流会执行以下操作： - 使用 Python 导出数据集， - 使用 Python 导出抽认卡， - 将 `outputs/web_data` 同步至 `apps/student-web/public/web_data`， - 将 `outputs/flashcards` 同步至 `apps/student-web/public/flashcards`， - 使用 Pages 的 base path 编译前端， - 发布 `apps/student-web/dist`。 面向学生的预期最终 URL： - `https://.github.io//` - 如果仓库为 `.github.io`，则 URL 为 `https://.github.io/` ### 在 Vercel 上构建与部署 该前端也可以部署在 Vercel 上，而无需将教育内容迁移至 Supabase。 设置： - 根目录 (Root Directory)：`apps/student-web` - 安装命令 (Install Command)：`npm install` - 构建命令 (Build Command)：`npm run build:vercel` - 输出目录 (Output Directory)：`dist` 可选环境变量： - `VITE_SUPABASE_URL` - `VITE_SUPABASE_ANON_KEY` 如果缺少这些变量，应用程序仍可使用静态数据和 `localStorage` 中的进度正常运行。配置这些变量后， 将出现 magic link 登录选项，且抽认卡的进度会同步至 Supabase。手动 SQL 脚本位于 `apps/student-web/supabase/001_identity_and_progress.sql`。 ## 6. 实验创建指南 要了解目录中的各个字段并进行正确编辑，请参阅： - [docs/crear_experimento.md](docs/crear_experimento.md) ## 7. 项目结构 ``` qc_lab_simulator/ # motor de simulacion, reglas, metricas, export content/ # catalogos y contratos de authoring apps/student-web/ # frontend React + TS para estudiantes docs/ # guias operativas del piloto scripts/ # scripts CLI para demo/build/export/ops tests/ # pruebas automaticas ``` ## 8. 相关文档（按需阅读） 总索引： - `docs/README.md` 入门与操作： - `docs/PILOT_QUICKSTART_5_MIN.md` - `docs/BEA_PILOT_CHECKLIST.md` 创作 UI 使用说明： - `docs/AUTHORING_MVP_TUTORIAL.md` - `docs/AUTHORING_MVP_GUIDE.md` - `docs/crear_experimento.md` - `docs/FLASHCARDS_GUIDE.md` 学生前端： - `apps/student-web/README.md` - `docs/STUDENT_FRONTEND_PLAN.md` - `docs/STUDENT_FRONTEND_GUIDE.md` 故障与恢复： - `docs/PILOT_TROUBLESHOOTING.md` - `docs/PILOT_RECOVERY_GUIDE.md` ## 9. 常见故障排查 - 在 `.ps1` 脚本中出现 `No se encontro Python` 错误： - 在根目录创建 `.venv`，或者安装 Python 3.11 并将其添加到 PATH 中。 - UI 打开后但未显示导出的文件： - 在 UI 中执行 `Build technical catalog` 和 `Export static web data`，或运行 `westgard_ops.ps1 -Action release`。 - 缺少依赖项导致错误： - 在激活的环境下执行 `pip install -r requirements.txt`。 - `verify` 失败： - 检查 `outputs/web_data/index.json` 以及错误提示中缺失的 manifests/payloads。 - 前端未显示实验内容： - 执行 `.\student_web_ops.ps1 -Action sync` 并确认 `apps/student-web/public/web_data/index.json` 已生成。 ## 10. 开源许可 MIT (`LICENSE`)。

标签：AI合规, Python, Westgard规则, 临床检验, 医疗健康, 后端开发, 数据模拟, 无后门, 质量控制, 逆向工具