草案，未經院方核定。病人、角色與臨床數值皆為虛構；品項與代碼取自 B 目錄快照。 本文件不構成臨床建議，也不可用於真實病歷。

00 · 給後端的對齊說明

十分鐘讀完。 這份是第一次溝通用的，講清楚「我們要的 FHIR 模式是什麼、不是什麼」， 以及前後端各自負責到哪裡。細節在後面的 01–07 與 Swagger，這裡不重複。

對象：EMR 後端開發。前端（Vue 3）與 Swagger 由我方負責。

1. 一句話

資料庫是你們自建的，API 的形狀照 HL7 FHIR R4。

伺服器不裝 HAPI FHIR，不改變這個結論——FHIR 在本專案是介面契約，不是儲存格式。 你們的表怎麼設計不受影響（就照 G1_物件目錄 那 71 個物件）， 要求只有一件事：對外那層 JSON 與 URL 長得像 FHIR。

Vue 前端  ──FHIR R4 JSON──>  你們的 API  ──SQL──>  你們的資料表
                                 │
                                 └──D1 事件──>  HIS

2. 為什麼不用 HAPI 也做得到

因為我們一開始就沒把 HAPI 才划算的功能寫進規格。整份規格要求的，是這幾件可以自己實作的事：

明確不做：chained search、_filter、GraphQL、Subscription、$everything、XML。 這些是 HAPI 的強項，也正是我們排除掉的部分。

3. 五條規則，違反了就不是 FHIR 模式

前四條是 FHIR 的形狀，第五條是這家醫院的臨床要求。

3.1 資源用名詞，動作用 HTTP 方法

✅ POST /MedicationRequest          ❌ POST /createMedicationOrder
✅ GET  /Observation?patient=…      ❌ GET  /getVitalSignsByPatient
✅ PUT  /Composition/{id}           ❌ POST /updateProgressNote

只有「多個副作用必須原子完成」才用自訂操作，本專案只有五支： $sign、$submit、$receive、$roster、$expand。

3.2 編碼一律帶 system ＋ code

// ✅
"medicationCodeableConcept": {
  "coding": [{ "system": "http://icu.emr.local/CodeSystem/his-medication",
               "code": "50631", "display": "Efferalgan 300 mg (Paracetamol)" }],
  "text": "Efferalgan 300 mg (Paracetamol)"
}

// ❌ 只有字串，下游無法比對，也無法對到 HIS 目錄
"medication": "Efferalgan 300mg"

只給 text 的請求要拒絕（錯誤碼 CODE-REQUIRED）。藥品碼、給藥途徑、服務碼都適用。

3.3 關聯用 Reference，不用裸 id

"subject":   { "reference": "Patient/demo-a" }        // ✅
"patientId": "demo-a"                                  // ❌

而且引用歷史資料時要帶版本："reference": "MedicationRequest/mr-x/_history/3"。 給藥執行指向的是「開立當下那一版醫囑」，病程引用的是「當時看到的那一筆檢驗值」。 之後醫囑被更正，這些引用也不會跟著改——這是稽核的基礎。

3.4 錯誤一律回 OperationOutcome

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "business-rule",
    "details": { "coding": [{ "system": "http://icu.emr.local/CodeSystem/api-error",
                              "code": "FIVE-RIGHTS-INCOMPLETE" }] },
    "diagnostics": "需逐項人工確認五對，不能由單次掃碼推定。",
    "expression": ["MedicationAdministration.extension('…/verificationChecklist')"]
  }]
}

四個欄位各有用途，缺一不可：

錯誤碼共 61 個，表在 05 §5.2， Swagger 的 ApiErrorCode 是同一份。

3.5 缺值不補、資料不覆寫

4. 誰能寫什麼：三層要先分清楚

這張表決定你們要寫多少程式，建議第一次會議就對完：

唯讀鏡像不需要版本控制、If-Match、業務規則驗證——工作量差很多。

另外有一件事想先講在前面：醫囑有三個獨立的狀態軸，不要合併成一個 status。

HIS 的 MedicationChangeStatus 1–5（新開立／審核／匯總領取／發放／急救車補充）沒有一個代表已給藥。 已給藥只有一個來源：護理師建立的 MedicationAdministration。

5. 五個具體例子

完整的 41 支在 Swagger（openapi/swagger.html，雙擊就能開，每支都附請求與回應範例）。 這裡先看最常用的五種形狀。

5.1 讀：搜尋回 Bundle，不是陣列

GET /fhir/r4/Observation?patient=Patient/demo-a&category=vital-signs
    &date=ge2026-08-30T19:00:00+07:00&date=le2026-08-31T19:00:00+07:00&_sort=-date
Accept: application/fhir+json

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 2,
  "link": [{ "relation": "self", "url": "…" },
           { "relation": "next", "url": "…" }],     // 分頁跟著 next 走，前端不自己拼 offset
  "entry": [
    { "fullUrl": "…/Observation/obs-bp-0831-1800",
      "resource": { "resourceType": "Observation", "…": "…" },
      "search": { "mode": "match" } }
  ]
}

同一個參數出現兩次＝ AND（上面的時間窗就是）。

5.2 血壓是一筆兩個 component，不是兩筆

{
  "resourceType": "Observation",
  "code": { "coding": [{ "system": "http://loinc.org", "code": "85354-9" }] },
  "effectiveDateTime": "2026-08-31T18:00:00+07:00",
  "component": [
    { "code": { "coding": [{ "system": "http://loinc.org", "code": "8480-6" }] },
      "valueQuantity": { "value": 92, "unit": "mmHg", "system": "http://unitsofmeasure.org", "code": "mm[Hg]" } },
    { "code": { "coding": [{ "system": "http://loinc.org", "code": "8462-4" }] },
      "valueQuantity": { "value": 54, "unit": "mmHg", "system": "http://unitsofmeasure.org", "code": "mm[Hg]" } }
  ]
}

拆成兩筆的話，收縮壓與舒張壓在時間軸上會失去配對，趨勢圖就錯了。

5.3 寫：一定要帶 If-Match

GET /fhir/r4/Composition/comp-progress-0831
→ 200 OK
  ETag: W/"4"

PUT /fhir/r4/Composition/comp-progress-0831
Content-Type: application/fhir+json
If-Match: W/"4"
→ 200 OK, ETag: W/"5"

5.4 同一劑藥不能給兩次：交給資料庫判斷

POST /fhir/r4/MedicationAdministration
If-None-Exist: identifier=http://icu.emr.local/occurrence-id|M3-V1-D1&status=completed

已有同劑次的完成紀錄 → 回 200 OK ＋ 既有資源（不是 201、不是 409）。 實作用唯一索引，不要「先查再寫」——兩個護理師同時操作時，先查再寫會兩個都通過。

5.5 多個副作用要原子：用 transaction Bundle

簽署一份病歷 ＝ 文件進版 ＋ 建立簽章 Provenance，兩件事必須同生同死：

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    { "fullUrl": "urn:uuid:…0001",
      "resource": { "resourceType": "Composition", "status": "final", "…": "…" },
      "request": { "method": "PUT", "url": "Composition/comp-progress-0831" } },
    { "fullUrl": "urn:uuid:…0002",
      "resource": { "resourceType": "Provenance",
                    "target": [{ "reference": "urn:uuid:…0001" }] },
      "request": { "method": "POST", "url": "Provenance" } }
  ]
}

任一筆失敗就整包回滾，不能留半套。

6. 分工

規格有疑義時：以 Swagger 的請求／回應範例為準，它是與規格文件同一份來源產生的。

建議的交付順序

M1 做完前端就能脫離假資料，建議優先。

7. 需要後端回覆的事

8. 先跑起來看（比讀文件快）

規格旁邊有一份可執行的參考實作（../fhir-server，Express ＋ SQLite，只有 express 一個相依）：

cd fhir-server && npm install && npm start
# 打開 http://127.0.0.1:8787/console.html

演練台左欄是一日流程 12 步（確認名單 → 寫病程 → 開醫囑 → 簽署 → 送 HIS → 給藥 → 判讀 → 交班）， 右欄是 8 個「故意犯錯」按鈕（忘了帶 If-Match、五對沒勾、用 0 代表沒量到、護理師開醫囑…）， 下方看得到每一次請求的完整 request／response。

它不是要你們照抄，是讓「規格說要擋」變成看得見的行為。三件事值得先看：

那 51 個測試全部走 HTTP，把 base URL 換掉就能對著你們自己的實作跑。

9. 這個資料夾怎麼讀

規格版本 0.1.0（草案，未經院方核定）。範例中的病人、數值、代碼皆為虛構。