上線步驟
從端點、金鑰、欄位對照到驗收與正式啟用。
1. 端點與網路#
- 準備測試與正式兩個院方端點,各有公開的 HTTPS base URL(例如
https://his-test.example.org/poieti/v1)。Poieti 從 Cloudflare Workers 呼叫,沒有固定來源 IP,端點以簽章驗證來源。 - 放行端點主機對外 HTTPS 443:測試
his-dev.poieti.com、正式his.poieti.com(下載附件、上傳名單)。Cloudflare anycast 沒有固定 IP,請以主機名稱放行,並排除於 TLS 檢查之外。 - 告知 Poieti 端點主機對外的固定 IP 或網段(最多 32 筆),以設定機器憑證的來源限制。
2. 實作院方 API#
依院方 API實作 POST /deliveries、GET /deliveries/{deliveryId} 與 GET /health;開啟病房名單時再實作 GET /census/wards/{wardCode} 與 POST /patients/search。寫入 HIS 與記下 deliveryId 必須在同一個 HIS 交易中完成,並以 deliveryId 去重。每個請求先驗證 X-Poieti-Signature,並以測試向量確認實作。
3. 金鑰#
Poieti 設定院方端點時產生簽章金鑰(測試與正式各一把)並交付院方,端點用它驗證請求。
端點下載附件與上傳名單需要機器金鑰。在端點主機以檢查工具產生 secret,secret 不離開醫院;只把 SHA-256 交給 Poieti。
node poieti-his.mjs keygen --key-file poieti-his.keyPoieti 核發憑證後以電話念出 SHA-256 前 8 碼供核對,並提供 keyPrefix,完成金鑰檔:
node poieti-his.mjs keygen --prefix phis.dev.<hospitalId>.<credentialId>. --key-file poieti-his.key測試與正式各一把金鑰(phis.dev…、phis.prod…)。詳見連線與金鑰。
4. 提供欄位對照#
下載每個功能的對照工作表,填寫院方欄位代碼、編碼方式與代碼對照,交給 Poieti 審核後發布為版本化的對照檔。
| 功能 | 版本 | 欄位數 | 工作表 |
|---|---|---|---|
住院整合照護紀錄(aide-care-record) | 範本 v1 | 39 | field-mapping-aide-care-record-v1.csv |
輸出入量紀錄(intake-output) | 範本 v1 | 57 | field-mapping-intake-output-v1.csv |
管路紀錄(line-record) | 範本 v1 | 9 | field-mapping-line-record-v1.csv |
入院護理評估表(nursing-admission) | 範本 v1 | 149 | field-mapping-nursing-admission-v1.csv |
傷口紀錄(wound-record) | 範本 v1 | 10 | field-mapping-wound-record-v1.csv |
同時提供 HIS 病房代碼與員工編號對照。詳見欄位對照。
5. 院內檢查#
下載 poieti-his.mjs,對測試端點執行:
node poieti-his.mjs check --url https://his-test.example.org/poieti/v1 \
--signing-key-file signing.key --delivery delivery.json它以 Poieti 的方式簽署並送出請求、以 Poieti 的規則判讀回應,執行端點自己就能驗證的驗收案例;--delivery 是院方測試病人的 DeliveryV1。詳見檢查工具。
6. 驗收#
Poieti 把測試環境的機構指向院方測試端點並切換為 push,雙方跑完驗收案例中適用的推送、金鑰與名單案例,Poieti 核對結果。
7. 正式啟用#
換上正式的簽章金鑰、機器金鑰與 https://his.poieti.com,Poieti 設定正式端點並將機構切換為 push。之後在 Poieti 主控台查看待送、失敗與重試(主控台網頁開放前,由 Poieti 人員代為重試、重新送出或作廢);需要時由 Poieti 設定告警 webhook。