poieti/developers
院方端點

檢查工具

poieti-his.mjs:產生機器金鑰,並以 Poieti 的方式對測試端點執行驗收案例。

不需安裝任何套件的 Node.js 程式(Node.js 22 以上),由院方資訊人員在院內執行。正式運作不需要它:紀錄由 Poieti 推送到端點,工具只用來產生金鑰,以及在上線前檢查端點。

SHA-256 acb0f4834627b3a3cd0172026dae74603e76fdc22409f90d9454fd889d77f05e

產生機器金鑰#

端點下載附件(deliveries 範圍)與上傳病房名單(census 範圍)用的機器金鑰。secret 在院內產生、不離開醫院,Poieti 只收到它的 SHA-256:

產生 secret,只顯示 SHA-256
node poieti-his.mjs keygen --key-file poieti-his.key

Poieti 核發憑證後以電話念出 SHA-256 前 8 碼供核對,並提供 keyPrefix,完成金鑰檔:

完成金鑰檔
node poieti-his.mjs keygen --prefix phis.dev.<hospitalId>.<credentialId>. --key-file poieti-his.key

在 Linux 與 macOS 上,金鑰檔只有執行的帳號可讀;在 Windows 上請以 icacls 限制只有端點服務帳號可讀。keygen 不會覆寫既有的檔案。

檢查端點#

對測試端點執行
node poieti-his.mjs check --url https://his-test.example.org/poieti/v1 \
  --signing-key-file signing.key --delivery delivery.json
參數說明
--url端點的 base URL,與 Poieti 設定的相同
--signing-key-filePoieti 交付的簽章金鑰(43 個 base64url 字元)所在的檔案
--delivery一份 DeliveryV1,病人為測試 HIS 中住院中的測試病人(可從 delivery-create.json 修改)。工具改用新的 deliveryId 與紀錄 ID,以不含附件的 create 送出
--token-file端點設定為 Bearer token 時,token 所在的檔案
--unknown-chart測試 HIS 中不存在的病歷號(預設 POIETI-CHECK-404)
--wait回 202 之後查詢狀態的最長秒數(預設 120)

每次執行會在測試 HIS 寫入一筆測試紀錄,請只對測試端點執行。結束代碼:0 全部通過(可有略過)、1 有案例未通過、2 參數、檔案或金鑰錯誤。

執行的案例#

案例檢查
push.health簽署的 GET /health 回 200
push.signature-stale600 秒前簽署的請求回 401
push.signature-replayed簽給另一個路徑的簽章回 401
push.signature-rotation端點的金鑰在第二個 v1 時仍接受(輪替)
push.signature-valid簽署的 POST /deliveries 不回 401/403
push.accepted-202回 202 時,查詢狀態直到寫入(端點不排入佇列時略過)
push.create-written新增寫入,回 hisRecordId
push.timeout-after-commit同一 deliveryId 第 2 次嘗試回同一個 hisRecordId
push.status-unknown未知 deliveryId 的狀態查詢回 404
push.identity-rejected不存在的病歷號回有代碼、不可重試的 4xx(例如 422 PATIENT_NOT_FOUND)
push.census-fetchdelivery 病人所在病房的名單是合格的 CensusSnapshotV1(沒有 patient.wardCode 時略過)
push.patient-search以 delivery 的病歷號查詢,回該病房、不含臨床資料的結果(同上)
push.oversized-response每個回應在 64 KB 內(名單 2 MB)

其他驗收案例需要 Poieti 推送或注入狀況(例如逾時、中斷、更正),在測試環境與 Poieti 一起驗收。

Poieti · HIS 介接contracts/his v1.0.0

搜尋文件

OpenAPI 契約 3.1