醫令外掛 Phase 4:薄殼 exe(pywebview)— TraumaFill 對接 + operationId 防重 + PyInstaller 打包¶

背景¶

接續 #384/#385/#386。本票完成薄殼 exe 本體:醫令外掛按鈕(SyncHUD)啟動
ER_note_NG.exe <病歷號> [工號] → WebView2 視窗載入 /plugin → 「帶回醫令」
經 JS↔Python 橋呼叫 TraumaFill.exe 預填回醫令。並吸收 TraumaFill 方新提供的
Python 對接規格:--context 查詢、encounterSeqNo、operationId(5 分防重複填)。
設計:his_plugin/DESIGN.md §6(本票同步定稿)。

變更內容¶

1. his_plugin/shell/ernote_plugin.py(新)— 薄殼 exe 主程式¶

• 參數承接:ER_note_NG.exe <病歷號> [醫師工號](病歷號轉 int;工號維持字串)
• 啟動核對:TraumaFill --context 取 HIS 畫面真值 → 病歷號不符/畫面未開 → 警告視窗
  (仍可先評估);取得 regSeq;工號以 --context/--whoami 為準,CLI 參數備援
• 開窗:<server>/plugin#pn=…&key=…&doctor=…(hash 不進伺服器 log);
  profile 存 %LOCALAPPDATA%\ERNotePlugin\webview
• 同病歷號重複啟動 → 聚焦既有視窗後自行結束(FindWindowW,已實測)
• JS 橋 Bridge.sendPayload(契約同 #386 凍結版):送出前再查一次 --context
  核對畫面病人,不符即中止(與 TraumaFill 端核對共兩層)→ 注入 encounterSeqNo
  → 呼叫 TraumaFill → 回 {ok, exitCode, message};內部例外一律回錯誤物件

2. his_plugin/shell/traumafill_client.py(新)— TraumaFill 呼叫封裝¶

• 填入:UTF-8 JSON 臨時檔(ensure_ascii=False)→ TraumaFill.exe <路徑> [區塊]
  → exit code 0/1/2 判讀 → 臨時檔即刪;逾時/不存在/未設定各有明確 ERROR 訊息
• 查詢:--whoami / --patient / --context → stdout JSON;CREATE_NO_WINDOW 防黑窗

3. his_plugin/shell/mock_traumafill.py(新)— 假 TraumaFill¶

TraumaFill 方提供,回應格式/exit code 與真品一致;無 HisApp 也能測完整鏈路

4. 設定與打包¶

• config.example.json(範本)→ 部署複製為 config.json(含金鑰,已入 .gitignore,
  連同 build/dist/spec 產物)
• build_exe.ps1:PyInstaller onefile windowed → ER_note_NG.exe(~18MB,打包實測成功)
• README.md:開發執行、打包、部署檢查表(TraumaFill 同伴檔、同 Windows 登入帳號
  (管道綁 SID)、WebView2 Runtime、SyncHUD 按鈕設定)

5. 前端:operationId(TraumaFill 新規格)¶

• plugin-session.tsx:BridgePayload 加 operationId;makeOperationId() 手刻 UUID v4
  (crypto.randomUUID 需 secure context,內網 HTTP 不可用;getRandomValues 無此限制)
• ReviewTab.tsx:失敗重試沿用同碼(中止型失敗零填入,重試乾淨)、
  成功後「再次帶回」換新碼(醫師明確意圖);TraumaFill 同碼 5 分內略過重填(防雙擊翻倍)

6. his_plugin/DESIGN.md — §6 依實作定稿 + Phase 4 標記完成¶

驗收標準(五層,全數 PASS)¶

• client↔mock 11 項:查詢三式(工號前導零保留)、全酬載填入、中文 SOAP UTF-8 無損、
  只帶診斷、exe 不存在/未設定的錯誤路徑
• Bridge 邏輯 7 項:payload 病歷號不符視窗擋下、醫令畫面病人不符中止並提示切回、
  TraumaFill 不可用明確回錯、payload=None/非數字不炸
• 真實 WebView2 視窗自測 3 項:頁面載入、js_api 注入、JS→Python→mock TraumaFill
  完整往返成功(回摘要「OK SOAP 診斷 填2…」)
• 前端 e2e 21 項(+3 新增):operationId 為 UUID v4、成功後再次帶回換新碼、
  失敗重試沿用同碼;原 18 項全數不退步
• 打包 exe 實測:視窗開啟、同病歷號第二實例自動聚焦舊窗並退出(exit 0)
• npm run build 過;ESLint 本票修改檔案零新增問題;backend 零改動 →
  smoke test 50 項全 PASS 不變

備註¶

• 依賴:pip install pywebview pyinstaller(開發/打包機;已裝 pywebview 6.2.1 +
  pyinstaller 6.21.0)。工作站只需 exe + config.json + WebView2 Runtime
• smoke_test.py 無需增修:未動任何 API endpoint;exe 為桌面程式,以上述五層
  實測替代(維護規約判定:同 #385/#386 前例)
• 版本號不動:exe 不在網頁 CHANGELOG 範疇;v0.5.0(#386)已涵蓋外掛功能面
• 開發教訓:PowerShell 對中文視窗標題的 FindWindowW 會 marshaling 失敗,
  驗證視窗一律用 Python ctypes(exe 內部本來就是 Python,不受影響)
• 下一步 Phase 5(需醫院現場):config 指向真 TraumaFill.exe、SyncHUD 按鈕串接、
  預跑程式對接 POST /plugin/context、緊湊佈局調校