08｜與 H13 端點目錄的對照

repo 裡已有一套由互動原型推導的 REST 規格：用戶需求/H_產品規格/H12_API共用規範.md、H13_API端點目錄.md、H14_畫面與API對照.md、_tools/openapi.yaml（59 個路徑，前綴 /api/v1/icu，狀態「未經院方／FPT／DB 核定」）。 本套 FHIR 規格（00–07）是同一批作業需求的另一種介面風格。這一份逐支對照，讓兩邊的人知道「H13 的哪一支＝FHIR 的哪一支」，以及 FHIR 這邊目前沒有承接、要補或要決定的地方。

對照日期 2026-09-19。H13 以 _tools/openapi.yaml 的 59 個路徑為準；FHIR 以 openapi/openapi.yaml 的 41 個 operation 為準。

H13 那一套也有自己的 Swagger 頁：實作/h13-api/swagger.html（npm run build 從原檔產生，不改原檔）；規格站上在 /h13/。

0. 共用規範的對應（H12 → FHIR）

H12 的規則 FHIR 這邊怎麼做 出處
三層分離（L1 我方 EMR／L2 HIS 唯讀鏡像／L3 回寫 HIS） 資源層級的 authority：Patient／Encounter／DiagnosticReport 等 L2 資源不接受 POST／PUT（422 READ-ONLY-SOURCE）；L3 只有 $submit 這一條路 01 §1.2、03 §3.2
認證 Authorization: Bearer <token>；正式環境 SMART on FHIR。參考實作用帳號當權杖（thucdv／nhungtt…） 05 §5.5
錯誤格式與錯誤碼 一律 OperationOutcome；details.coding.code 是本院錯誤碼（61 個），issue.code 是 R4 issue-type 05 §5.1–5.2
稽核 伺服器自動寫 AuditEvent（含讀取）；客戶端不可建立 05 §5.4
冪等 建立用 If-None-Exist（劑次唯一靠部分唯一索引）；$submit 用 idempotency_key（資源＋版本） 03 §3.5、06 §6.6
樂觀鎖 ETag: W/"n" ＋ If-Match；沒帶 412，過期 409 ＋ currentVersionId 03 §3.3
分頁 Bundle.link[next]（keyset 游標 _page），不用 OFFSET 03 §3.4
時間格式 ISO 8601 帶時區（+07:00），沒帶時區 422 TIMEZONE-REQUIRED 03 §3.9
版本快照 每次寫入 fhir_resource_version append-only；GET …/_history/{n} 讀舊版 07 §7.4

1. 逐支對照

圖例：✅ 已有對應　🔁 用既有資源組合（前端多打一次或用 batch）　⏳ FHIR 這邊尚未承接，列入待補　🚫 依 H8 裁定不提供

1.1 作業上下文與照護名單

H13 方法 FHIR 對應 狀態 備註
/me GET GET /Practitioner/$me ✅ 2026-09-20 補：回 Practitioner ＋ PractitionerRole（職稱、科別、班別）一組
/shifts/current GET GET /Practitioner/$me → PractitionerRole.extension[shift] ✅ 2026-09-20 補：班別跟人一起回，不另開端點
/assignments GET GET /Patient/$roster ✅ 回 Patient(match)＋CareTeam(include)＋作用中醫囑筆數
/assignments/confirm POST POST /Provenance（activity=roster-confirm） ✅ 確認是一筆溯源，不是 CareTeam 欄位
/worklist GET GET /Patient/$roster ＋ GET /Encounter?status=in-progress ＋ GET /Flag?status=active 🔁 2026-09-10 決議「全院內醫護可查閱」→ 醫護讀取不過濾（07 §7.12 更新）；床位在 Encounter.location[physicalType=bd]，特殊註記與嚴重度是 Flag

1.2 病人、就醫與 ICU 照護段

H13 方法 FHIR 對應 狀態 備註
/patients/{id} GET GET /Patient/{id} ✅ 監護人在 contact，健保文字在 extension[insuranceText]
/encounters/{id} GET GET /Encounter/{id} ✅ 主診斷 reasonCode.coding（ICD-10）、預計出院 extension[expectedDischargeDate]
/encounters/{id}/overview GET POST /（batch Bundle：Observation vital-signs、MedicationRequest active、DiagnosticReport 最新、Task） 🔁 五張卡沒有單一端點；用 batch 一次打回來，或前端並行四支
/encounters/{id}/timeline GET Encounter.location[] ＋ GET /Procedure?patient= 🔁 入科／轉床／手術都有時間
/episodes/{id} GET Encounter.location[physicalType=wa] 🔁 ICU 照護段＝科別那一段 location period；未另開 EpisodeOfCare

1.3 診斷、本日問題與目標

H13 方法 FHIR 對應 狀態 備註
/encounters/{id}/goals GET／POST GET／POST /Condition?encounter=（診斷）＋ GET／POST /Goal?encounter=（本日目標） ✅ 2026-09-20 補：兩個資源都限醫師；診斷 ICD-10 必在目錄、代碼不可就地換、排除＝verificationStatus=refuted 留版本，_history 就是「診斷演變時間軸」
/encounters/{id}/care-focuses GET／POST Goal（description 寫照顧重點）或 Composition section 🔁 原型已併入 goals；FHIR 這邊用 Goal 承接，不另開資源

1.4 醫囑開立

H13 方法 FHIR 對應 狀態 備註
/encounters/{id}/orders GET GET /MedicationRequest?encounter=&_revinclude=MedicationAdministration:request ＋ GET /ServiceRequest?encounter= ✅ 藥囑與檢驗檢查是兩個資源
/encounters/{id}/orders POST POST /MedicationRequest／POST /ServiceRequest ✅ 建立即草稿（draft、notSent）
/encounters/{id}/orders:batch POST POST /（transaction Bundle） ✅ 全成功或全失敗；urn:uuid 內部引用
/encounters/{id}/order-cart GET 草稿＝MedicationRequest?status=draft&requester=me 🔁 伺服器端購物車＝status=draft 的醫囑，不另設資源
/order-cart/items POST POST /MedicationRequest（draft） 🔁
/order-cart/items:batch POST transaction Bundle 🔁 套組展開後逐筆仍各自簽署
/order-cart/items/{key} DELETE PUT status=cancelled（草稿） 🔁 本 API 不提供 DELETE
/orders/{id} GET GET /MedicationRequest/{id}／ServiceRequest/{id} ✅
/orders/{id}/sign POST POST /MedicationRequest/{id}/$sign ✅ 驗證病程來源、只能簽自己的草稿
/orders/{id}/send POST POST /MedicationRequest/{id}/$submit ✅ 冪等；逾時→unknown、斷線→維持已簽未送
/order-safety/assess POST — 🚫 H8 §4.4 裁定：院方未核定體重／年齡／腎功能規則前不顯示安全綠燈；不提供

1.5 品項目錄與常用

H13 方法 FHIR 對應 狀態 備註
/catalog/items GET GET /ValueSet/{his-medication|his-service|his-route}/$expand?filter= ✅ 可快取一小時
/catalog/items/{key} GET $expand?filter= 後由客戶端比對 code 🔁 建議補 CodeSystem/$lookup 精確查一筆
/catalog/taxonomy GET GET /ValueSet/order-category/$expand ✅ 2026-09-20 補：七分類＋套組共 8 筆；院方核定前內容可換，介面不變
/catalog/frequencies GET GET /ValueSet/frequency/$expand ✅ 2026-09-20 補：19 筆，六組頻率；自訂頻率仍走 Dosage.text
/catalog/icd10 GET GET /ValueSet/icd10/$expand?filter= ✅ 2026-09-20 補：15,994 筆（B 目錄 CSV 匯入），filter 同時比對代碼、越文、英文名
/catalog/routes GET GET /ValueSet/his-route/$expand ✅
/favorites、/favorites/{key} GET／PUT GET /List?code=favorites-personal|favorites-dept&source=、PUT /List/{id}（整份送回） ✅ 2026-09-20 補：品項必在目錄；個人常用只有主人能改，科常用另有 favorites-dept
/order-sets GET GET /PlanDefinition?type=order-set ✅ 2026-09-20 補：唯讀、status=draft，院方核准前只當介面示例

1.6 醫囑執行

H13 方法 FHIR 對應 狀態 備註
/orders/{id}/executions GET GET /MedicationAdministration?request=／GET /Procedure?based-on= ✅
/orders/{id}/executions POST POST /MedicationAdministration（If-None-Exist）／POST /Procedure ✅ 五對逐項、劑次唯一、差異原因
/executions/{id}/review POST POST /Provenance（activity=clinical-review，target=MedicationAdministration） ✅
/orders/{id}/infusion-checks POST POST /Observation（partOf=MedicationAdministration） ✅ INFUSION-SOURCE-REQUIRED

1.7 生理量測與檢驗檢查

H13 方法 FHIR 對應 狀態 備註
/encounters/{id}/observations GET／POST GET／POST /Observation?category=vital-signs ✅ 血壓兩個 component；缺值不補 0
/encounters/{id}/observations/series GET GET /Observation?code=&date=ge…&_sort=date 🔁 趨勢由客戶端畫
/encounters/{id}/lab-results GET GET /DiagnosticReport?patient=&_include=DiagnosticReport:result ✅ 矩陣／逐項／趨勢共用
/encounters/{id}/reports GET GET /DiagnosticReport?patient= ✅
/reports/{id} GET GET /DiagnosticReport/{id} ✅ HIS 唯讀
/reports/{id}/seen POST POST /Provenance（activity=clinical-review，reviewOutcome=seen） ✅ 已閱與判讀都是 Provenance，報告本身不動
/reports/{id}/processed POST POST /Provenance（reviewOutcome=reviewed／difference＋reviewNote） ✅
/encounters/{id}/procedures GET GET /Procedure?patient= ✅ 手術／麻醉唯讀摘要

1.8 病歷撰寫與簽署

H13 方法 FHIR 對應 狀態 備註
/encounters/{id}/compositions GET／POST GET／POST /Composition ✅ SOAP 四段必填；author 由權杖填
/encounters/{id}/notes POST POST /Composition（type=nursing-note） 🔁 護理自由文字也是文件
/compositions/previous-progress GET GET /Composition?type=11506-3&author=me&status=final&_sort=-date&_count=1 ✅ 複製前一日病程；複製軌跡放 relatesTo／section 引用
/encounters/{id}/writer-sources GET batch：Observation、DiagnosticReport、MedicationRequest active 🔁 側欄帶入來源
/compositions/{id} GET GET /Composition/{id} ✅ section.entry 一律帶版本
/compositions/{id}/sign POST POST /Composition/{id}/$sign ✅
/compositions/{id}/amend POST POST /Composition（relatesTo.replaces ＋ extension[amendReason]） ✅ 留痕更正＝新文件，舊版不動
/education-sets GET GET /PlanDefinition?type=education-set ✅ 2026-09-20 補：與套組同一資源，type 區分
/drafts/{kind} GET／PUT／DELETE Composition status=preliminary 🔁 草稿就是未簽署的文件；不另設 draft 儲存

1.9 照會、必要溝通、工作、交班、稽核

H13 方法 FHIR 對應 狀態 備註
/encounters/{id}/consultations GET／POST GET／POST /ServiceRequest?category=consultation ✅ 照會醫師的病人範圍由照會單決定
/consultations/{id}/response POST POST /Communication（category=consult-reply，basedOn=ServiceRequest） ✅ 2026-09-20 補：必須指向照會單；照會醫師可回覆，但不能寫必要溝通；只新增不修改
/encounters/{id}/communications GET／POST GET／POST /Communication?encounter=&category=essential ✅ 2026-09-20 補：醫護都能寫，說過的話不能改（PUT → SIGNED-IMMUTABLE）
/tasks GET／POST GET／POST /Task ✅
/tasks/{id} PATCH PUT /Task/{id}（If-Match） ✅ 結案要證據；來源報告要已判讀
/handovers GET／POST GET／POST /Composition?type=handover-sbar ✅ S／B／A／R 必填、指定接班者
/handovers/{id}/receipts POST POST /Composition/{id}/$receive ✅ 同交易內轉移 Task.owner
/audit-events GET GET /AuditEvent ✅ 讀取也有紀錄

2. 統計

數量
H13 路徑 59
✅ 一對一有對應 44（2026-09-19 是 33）
🔁 用既有資源組合 14（2026-09-19 是 13）
⏳ FHIR 尚未承接（要決定資源） 0（2026-09-19 是 12）
🚫 依裁定不提供 1

3. 待補清單 → 2026-09-20 已全部補上

2026-09-19 列的六項，2026-09-20 都補進 FHIR 這一套（規格 02 §2.9a／§2.11a、參考實作、Swagger 範例、test/new-resources.test.js、流程導覽第六章）：

原順位 補什麼 補成什麼 H13 那邊
1 Condition／Goal（診斷、本日問題與目標、診斷演變） Condition（category 入院／入科／出院／問題；diagnosisRole／diagnosisEvidence；排除留版本）＋ Goal（goalEncounter） 仍只有 /encounters/{id}/goals，缺診斷與歷程（09 §3 #9）
2 Communication（照會回覆、必要溝通） Communication（consult-reply 要 basedOn 照會單；essential 醫護可寫；只新增） 有 /consultations/{id}/response、/communications，缺按病人／類別查與單筆讀（09 §3 #11）
3 Practitioner/$me＋值班 GET /Practitioner/$me 回 Practitioner ＋ PractitionerRole（職稱、科別、extension[shift]）；另有 Practitioner 搜尋／讀取 有 /me、/shifts/current，缺職稱／科別與找人（09 §3 #10）
4 ICD-10 ValueSet ValueSet/icd10（15,994 筆，CSV 匯入，filter 比對代碼／越文／英文） 有 /catalog/icd10
5 List／PlanDefinition List（favorites-personal／favorites-dept，整份 PUT，品項必在目錄）＋ PlanDefinition（order-set／education-set，唯讀 draft） 有 /favorites、/order-sets、/education-sets；缺科常用（09 §3 #12）
6 頻率 ValueSet、七分類映射 ValueSet/frequency（19）＋ ValueSet/order-category（8） 有 /catalog/frequencies、/catalog/taxonomy

還沒承接的只剩「值班表」本身（誰今天上哪一班的排班維護）：本套只回目前登入者的班別，排班仍由 HIS／人事系統維護。

4. 追溯方式