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

05 · 錯誤、安全與稽核

5.1 OperationOutcome

所有非 2xx 回應的 body 一律是 OperationOutcome，且每個 issue 必須齊備四項：

diagnostics 是使用者可見文字，不是給工程師的堆疊訊息。原型的訊息文字（例如「需逐項人工確認五對（模擬），不能由單次掃碼推定」）可直接沿用，去掉「（模擬）」字樣。

{
  "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')"]
  }]
}

5.2 錯誤碼表

5.3 HTTP 狀態碼使用

5.4 保存失敗的語義（與原型的重要差異）

原型的 store 在持久化失敗時仍把交易寫進記憶體，只顯示警告——那是 localStorage 原型的權宜做法。

正式 API 不得如此。 未持久化就不能回 2xx：

客戶端保留使用者輸入是 UI 的責任，不是靠伺服器回假成功。

scenario（保存失敗／來源缺漏／HIS 逾時）是原型的情境切換開關，正式 API 沒有這個端點。

5.5 認證與授權

5.5.1 SMART on FHIR

採 OAuth 2.0 ＋ SMART on FHIR user/ scopes（後端服務用 system/）。

存取權杖必須帶：

5.5.2 Scope 對照

（c=create、r=read、u=update、d=delete、s=search）

Scope 是必要條件，不是充分條件。 通過 scope 後仍要跑 04 的全部規則——例如護理師有 MedicationAdministration.c，但 BR-MED-002／BR-MED-003 仍可能擋下。

5.5.3 病人範圍

除了 scope，伺服器對每個請求做 compartment 檢查：

1. 從 fhirUser 取得作用中的 CareTeam 參與關係。
2. 照會醫師另外檢查是否有指派給他、且 status=active 的照會 ServiceRequest。
3. 目標資源的 subject／patient 不在集合內 → 403 PATIENT-OUT-OF-SCOPE。

搜尋一律隱含加上病人範圍過濾，不是回 403 而是回較少的結果——避免透過錯誤碼探測病人是否存在。單一資源 read 才回 403。

5.6 稽核

AuditEvent vs Provenance

兩者都要，用途不同：

AuditEvent 必填

{
  "resourceType": "AuditEvent",
  "type": { "system": "http://terminology.hl7.org/CodeSystem/audit-event-type", "code": "rest" },
  "subtype": [{ "system": "http://hl7.org/fhir/restful-interaction", "code": "create" }],
  "action": "C",
  "recorded": "2026-08-31T09:12:04+07:00",
  "outcome": "0",
  "agent": [{
    "who": { "reference": "PractitionerRole/d1" },
    "requestor": true,
    "network": { "address": "10.2.3.4", "type": "2" }
  }],
  "source": { "observer": { "reference": "Device/emr-api" } },
  "entity": [{
    "what": { "reference": "MedicationAdministration/9a2" },
    "type": { "code": "2" }
  }]
}

• 讀取也要記錄。 病歷閱覽（action=R）必須留軌跡。
• agent.network.address 對應規格 ServiceRequestCancelled 的 ipAddress / computerName（取得＝C，不可手打冒充）——由伺服器從連線取得，客戶端送的值忽略。
• 失敗的請求同樣要記錄（outcome 非 0），尤其是 403。

異動理由

audit_event.change_reason（S06 標為 M）→ 寫入時以 X-Change-Reason 標頭帶入，伺服器落到 AuditEvent.extension[changeReason]。診斷管理等需要理由的操作缺此標頭時回 422。

5.6.1 電子簽章驗證

Provenance.signature.data 的驗證結果（signature_hash 與驗證服務輸出，取得＝C）由伺服器產生，透過 Provenance 的 extension[signatureValidation] 回傳：valid / invalid / unverified（憑證服務不可用時用 unverified，不預設 valid）。

5.7 傳輸與記錄

• 僅接受 TLS 1.2 以上。
• 存取權杖不得出現在 URL。
• 應用程式日誌不得記錄請求／回應 body（含臨床內容）；只記錄方法、路徑樣板、狀態碼、AuditEvent.id。
• 搜尋參數會含病人識別碼，日誌中的 query string 必須遮蔽。