醫令外掛 Phase 1:backend 外掛 API(X-API-Key + 病人脈絡/草稿 72h 暫存 + 共用模板)¶

背景¶

本系統將以「外掛」形式整合進醫院急診醫令系統:SyncHUD(醫令介面按鈕系統)啟動薄殼 exe
(ER_note_NG.exe <病歷號> [醫師工號])開啟 /plugin 頁,完成創傷評估後產出
{patientNo, soap, diagCodes[], orderCodes[]} 交 TraumaFill.exe 預填回醫令(Clinic002)。
完整設計與決策紀錄:his_plugin/DESIGN.md(本票一併入庫)。

外掛版無會員登入(歸責由醫令系統承擔),故需要:

1. 機器憑證保護 API(內網不可裸奔——背後是 OpenAI key 與檢傷資料)
2. 病人脈絡暫存:背景預跑程式先擷取檢傷資訊+預抽 ICD,開窗即自動帶入
3. 草稿暫存:防誤關視窗整份評估重來
4. 共用模板:無帳號後個人模板失效,改用 admin 名下模板唯讀取用

本票為分階段實作的 Phase 1(backend);Phase 2 起為 /plugin 前端路由、帶回 UI、薄殼 exe。

變更內容¶

1. backend/auth.py — 機器憑證 require_plugin_key ¶

• 驗 X-API-Key 標頭,比對 .env 的 PLUGIN_API_KEY(hmac 恆時比較)
• 未設定金鑰一律 503(fail closed);缺鑰/錯鑰 401

2. backend/models.py — 兩張短時效快取表¶

• plugin_context:patient_no(int, PK)、age、sex、triage_text、pre_icd(JSON)、updated_at
• plugin_draft:patient_no(int, PK)、form_state(JSON)、updated_at
• patient_no 採整數:HIS 內部即 int,前導零僅 8 位顯示格式無語意(已查證 HIS 原始碼)

3. backend/main.py — 7 個 /plugin/* 端點 + TTL¶

• 72h TTL(涵蓋急診留觀過夜/跨日):每次外掛存取順手清過期列,免排程
• /predict_icd10 本來即無需登入,外掛/預跑程式直接呼叫,零改動
• 既有 JWT 端點與網頁版行為完全不動

4. backend/tests/smoke_test.py — 新增第 9 區段(9 項,同票入庫)¶

無鑰 401/錯鑰 401、context 上傳/讀回(含 pre_icd)、draft 暫存/讀回、
共用模板列表、admin 模板出現在共用清單、DELETE 自清(測試零殘留)

5. his_plugin/DESIGN.md — 完整設計文件(新入庫)¶

架構、12 條決策紀錄、TraumaFill 對接規格(§6.1/6.2)、分階段計畫

驗收標準¶

• 全站 smoke test 50 項全 PASS(41 既有零迴歸 + 9 新增;含 LLM 管線)
• 無鑰/錯鑰請求被拒(401),未設 PLUGIN_API_KEY 時 503 fail closed
• context/draft upsert + 讀回一致 + DELETE 冪等
• TTL 實測:塞 100h 前資料 → 觸發清理 → 確實刪除且 GET 404;1h 前資料存活
• 共用模板:admin 名下模板出現於 /plugin/templates,一般使用者模板不出現

備註¶

• 部署:部署機 backend/.env 需新增 PLUGIN_API_KEY=<隨機金鑰>(本機已產生一把,
  部署機應另產;持鑰者僅預跑程式與薄殼 exe)。新表由 create_all 於啟動時自動建立,舊 DB 免遷移
• 版本號不動:純 backend 基礎設施,網頁版無任何可見變更;版號待 Phase 2/3(外掛前端)一併調升
• 預跑程式對接格式(snake_case)已定稿於 DESIGN.md §4.2:
  POST /plugin/context/{病歷號} + {age, sex, triage_text, pre_icd:[{code,name}]}
• plugin_context/draft 含病歷號與檢傷資訊(PII),存於 er_note.db,沿用既有防護(不入 git)