版控整備:PII 防護 gitignore + requirements pin 版 + 版本細節限管理員 + 部署手冊/計畫書/工具入庫¶

背景¶

工作區累積了多批未入庫的檔案與設定債,存在三個風險:

1. PII 外洩風險:使用者回報 dump(docs/*feedback*.json)、B1 測試樣本(sample_b1_*.json)、benchmark 報告等可能含病歷內容的檔案未被 gitignore,一次 git add -A 就可能推上 GitHub。
2. requirements.txt 版本失真:實際執行 chromadb 1.5.9,檔案卻寫 >=0.4.0;SapBERT 必需的 sentencepiece/tiktoken 未列 —— 部署機照檔安裝會直接打不開向量庫(#318 後 DB 格式與版本綁定)。
3. 一般使用者可點開版本紀錄看到內部變更細節;開發文件與工具散落未入庫。

變更內容¶

1. PII 防護 + benchmark 輸出整頓(.gitignore + 3 支測試腳本)¶

• .gitignore:docs/*feedback*.json(回報 dump,永不入庫)、backend/tests/sample_b1_*.json(測試樣本,可由 golden_dataset 重新合成)、backend/tests/reports/ 與 report_*/lookup_bench_*/vector_bench_*(一次性輸出);已 commit 的 4 個基準檔以 ! 白名單保留。
• 12 個一次性報告搬進 backend/tests/reports/(整目錄 ignore);刪除 debug_icd10_output.md。
• test_icd10_accuracy.py / run_lookup_benchmark.py / benchmark_vector_search.py:輸出路徑統一改寫 tests/reports/(自動 mkdir),之後不再散落。

2. requirements.txt pin 版(部署地雷根治)¶

• chromadb==1.5.9(DB 格式綁定,部署機不同版打不開向量庫)
• sentence-transformers==5.5.1、transformers==5.12.0(SapBERT CLS pooling 行為綁定)
• sentencepiece>=0.2.1、tiktoken>=0.13.0(SapBERT 必需、原漏列)
• 僅 pin「格式/行為綁定」者,其餘維持 >=;pip install --dry-run 驗證通過。

3. 版本細節僅管理員可見(frontend/src/app/page.tsx)¶

• 一般使用者:版本徽章為純文字(只顯示 vX.Y.Z,不可點)。
• 管理員(role === "admin"):維持可點開「版本紀錄」對話框。
• 雙層防護:非管理員無 onClick,且 Dialog 加 user?.role === "admin" 守門。tsc 通過。

4. 文件與工具入庫¶

• docs/UPDATE-hospital-302-to-330.md:本次醫院部署更新手冊(打包清單/步驟/驗證/回滾,均實測)。
• docs/icd10-popularity-ranking-plan.md:A1 使用習慣動態排序計畫書(待拍板)。
• docs/icd10-external-cause-plan.md:B4 外因碼計畫書。
• backend/scripts/scan_facet_anomalies.py、validate_facets_sample.py、test_faceted_query.py:B3 facet 異常掃描/驗證工具。
• scripts/create_ticket.py + .claude/commands/ship.md:/ship Redmine 建單基礎設施。

驗收標準¶

• git status 不再出現任何 feedback/sample/report json(被 ignore 蓋住);已 commit 的 4 個基準檔仍被追蹤。
• 新機器 pip install -r requirements.txt 後可直接打開現行 chroma_db(1.5.9 格式)並載入 SapBERT。
• 一般使用者帳號:版本徽章不可點、無法開啟版本紀錄;admin 帳號行為不變。
• 三支 benchmark 腳本輸出落在 backend/tests/reports/。

備註¶

• 待辦不變:B3 facet 複查(72 筆)、B2 per-injury 排序、B4 外因碼、C2 full-1100 baseline、A1 popularity(計畫書已入庫待拍板)。
• 後端啟動自檢(chromadb 版本/collection 齊全性檢查,失敗拒絕啟動)已拍板「拒絕啟動」,另案實作。