全站部署煙霧測試 smoke_test.py(41 項全 endpoint)+ ship 測試門檻制度化¶

背景¶

使用者需求:「建立一套完整的全網站測試腳本,每次新增或修改功能時對應測試也要跟著改,讓每次升級或部署到其他電腦時能快速測出功能異常。」直接動機:2026-07-10 醫院部署後 /icd10-feedback 故障(Bug #357),既有測試資產全部集中在 ICD-10 品質面(golden dataset/benchmark),認證、病歷 CRUD、模板、admin、回報等 31 個 endpoint 完全零測試,故障無工具可即時發現。

三層測試架構已與使用者拍板:第 1 層 smoke test(本票) → 第 2 層 pytest(TestClient,另案)→ 第 3 層 Playwright E2E(暫緩)。

變更內容¶

1. backend/tests/smoke_test.py(新增,核心交付物)¶

對「已啟動的伺服器」經 HTTP 打全部 endpoint,共 41 項檢查:

• 公開端點:health、abbreviations、suggest(含代碼前綴模式)、search_icd10(epistaxis→R04.0 = 向量庫/embedding 模型整條鏈健檢;abrasions 複數 = 詞幹化)。
• 認證流程:註冊、重複註冊 400、錯誤密碼 401、登入、/users/me、無 token 401、改密碼(含舊密碼錯 400、新密碼可登入)。
• 病歷/模板 CRUD:建/列/讀/改/刪,含跨使用者隔離(B 讀 A 的病歷 → 404)與不存在 404。
• 兩種回報:POST /icd10-feedback(payload 與前端一致含 provider 欄 —— 即 Bug #357 故障點)、POST /search-feedback、admin 檢視/刪除。
• 權限反向測試:一般使用者打 /admin/* → 403;admin 停用帳號→登入 403→復原;admin 重設密碼。
• LLM 管線:預設打一發最小案例(scalp laceration → 預測非空 + S01 系列在候選);--skip-llm 可跳過。
• 自建自清:smoke_* 測試帳號×2 與所有測試資料結束時刪除,絕不動部署機既有資料。
• admin 帳密自動讀 backend/.env;任何 FAIL → exit code 1;Windows cp950 console 相容(stdout 強制 utf-8)。

實測:本機 8001 全 41 項 PASS(含真 LLM,137.7s;--skip-llm 102.7s)。

2. ship 流程測試門檻(.claude/commands/ship.md)¶

• 新增第 6 步:動到 API/使用者流程 → commit 前必跑 smoke test 全 PASS;endpoint 增修必須同一 commit 附上 smoke_test.py 對應檢查。
• 第 8 步改逐檔 git add(禁 -A,與實務一致,避免掃進本機設定/PII)。

3. 文件同步¶

• docs/UPDATE-hospital-302-to-330.md:§5 驗證改以 smoke test 為正式工具(手動檢查降為備援);新增 §9 v0.4.1 補丁章節(醫院機 git pull + 重啟即修復 Bug #357);一頁速查同步。
• backend/tests/README.md:置頂 smoke test 用法與維護規約。

驗收標準¶

• python smoke_test.py --base-url http://localhost:8001 全 PASS、exit 0(已實測,含/不含 LLM 兩種模式)。
• 任一檢查失敗 → 列出 FAIL 項目 + exit 1。
• 無 admin 帳密時:admin 區段 SKIP 並警告測試資料未清。
• 部署手冊驗證章節一條指令可用。

備註¶

• 待辦:第 2 層 pytest(TestClient + mock LLM,另案)→ #13 啟動自檢(拒絕啟動,已拍板另案)→ Playwright E2E 暫緩。
• 維護規約已同步存入開發者記憶:任何 API/流程變更,同票更新 smoke test。