# 由 build.mjs 產生（openapi.yaml ＋ examples.mjs）。不要手改這個檔。
openapi: 3.0.3
info:
  title: ICU EMR FHIR API（越南兒童醫院 Phase 1）
  version: 0.1.0
  description: |
    ICU 臨床工作站的 FHIR R4 (4.0.1) 介面。本文件用於與院方及 HIS 廠商溝通介面範圍與約束。

    ### 三個必須先講清楚的前提

    1. **這是 EMR 的介面，不是 HIS 的介面。** HIS 仍是病人、就醫、檢驗結果、處方號的權威來源。
       EMR 透過整合層與 HIS 往來（`PrescriptionCreated` / `ServiceRequest*` / `MedicationChangeStatus`），
       臨床端不直接觸碰那些契約。
    2. **醫囑有三個獨立狀態軸**：臨床狀態（`status`）、本地簽署（`Provenance.signature`）、
       HIS 傳輸（`extension[hisTransmissionStatus]`）。不可合併成單一 `status`。
       HIS 的 `MedicationChangeStatus` 1–5（新開立／審核／匯總領取／發放／急救車補充）**都不代表已給藥**。
    3. **缺值不補。** 沒有來源就用 `dataAbsentReason` 或省略元素，不送 0、不預設正常、不推定未執行。

    ### 資料權威（決定哪些欄位可寫）

    29 份 S／N 規格的 1,209 個欄位都標了「取得方式」，直接對映到 API 可寫性：

    | 取得 | 意義 | 欄位數 | API |
    | --- | --- | --- | --- |
    | M | 手動輸入 | 431 | 可寫 |
    | H | HIS 來源 | 425 | 唯讀，僅整合服務帳號可寫 |
    | P | 引用其他資源 | 264 | 唯讀，以 Reference 表達 |
    | C | 系統計算 | 88 | 唯讀，伺服器產生 |
    | D | 設備來源 | 1 | 唯讀 |

    ### 通則

    - 所有可寫互動要求 `If-Match`（樂觀鎖）。缺少時回 `412`。
    - **不提供 `DELETE`。** 誤建資料以 `status = entered-in-error` 標記。
    - 業務規則編號 `BR-*` 對應規格文件《04 業務規則與狀態機》，可直接作為測試案例編號。
    - 錯誤碼見 `OperationOutcome` schema 的 `ApiErrorCode` 列舉。

    ### Schema 範圍說明

    本文件的資源 schema **只列出本專案實際約束的元素**（必填、唯讀、本地擴充、值域限制），
    其餘元素依 FHIR R4 base 定義，未在此重複。因此所有資源 schema 皆為 `additionalProperties: true`。
  contact:
    name: ICU Phase 1 專案
  license:
    name: 院內文件，未對外授權
externalDocs:
  description: 完整規格（設計原則、資源對照、業務規則、HIS 整合）
  url: ../README.md
servers:
  - url: https://{host}/fhir/r4
    description: EMR FHIR Server
    variables:
      host:
        default: emr.icu.local
security:
  - smartOnFhir: []
tags:
  - name: 系統
    description: 能力宣告與 transaction
  - name: 病人與就醫
    description: HIS 唯讀資源，以及本班照護名單
  - name: 醫囑
    description: 藥物醫囑與醫令（檢驗／檢查／照護）
  - name: 實際執行
    description: 給藥執行、處置執行、醫師核對
  - name: 檢驗與量測
    description: 報告、檢驗指標、生命徵象
  - name: 病歷文件
    description: Admission／Progress／Discharge Note、會診回覆、SBAR 交班、同意書
  - name: 工作與交班
    description: 臨床工作待辦與交班承接
  - name: 溯源與稽核
    description: Provenance（臨床溯源）與 AuditEvent（安全稽核）
  - name: 診斷與溝通
    description: 診斷與問題清單、本日目標、照會回覆與必要溝通（2026-09-20 補）
  - name: 目錄
    description: B 目錄品項查詢
paths:
  /metadata:
    get:
      tags:
        - 系統
      summary: 能力宣告
      operationId: getCapabilityStatement
      description: 回傳 CapabilityStatement，列出本伺服器支援的資源、互動與搜尋參數。
      security: []
      responses:
        '200':
          description: 能力宣告
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 能力宣告（節錄）
                  value:
                    resourceType: CapabilityStatement
                    status: draft
                    date: '2026-08-31'
                    publisher: 越南兒童醫院 ICU EMR
                    kind: instance
                    fhirVersion: 4.0.1
                    format:
                      - application/fhir+json
                    rest:
                      - mode: server
                        security:
                          service:
                            - coding:
                                - system: http://terminology.hl7.org/CodeSystem/restful-security-service
                                  code: SMART-on-FHIR
                        resource:
                          - type: MedicationRequest
                            interaction:
                              - code: read
                              - code: vread
                              - code: search-type
                              - code: create
                              - code: update
                              - code: patch
                              - code: history-instance
                            versioning: versioned-update
                            updateCreate: false
                            searchParam:
                              - name: patient
                                type: reference
                              - name: status
                                type: token
                            operation:
                              - name: sign
                                definition: http://icu.emr.local/OperationDefinition/MedicationRequest-sign
                          - type: DiagnosticReport
                            interaction:
                              - code: read
                              - code: vread
                              - code: search-type
                            versioning: versioned
                        interaction:
                          - code: transaction
                          - code: batch
  /:
    post:
      tags:
        - 系統
      summary: 提交 Bundle（transaction / batch）
      operationId: submitBundle
      description: |
        **transaction**（原子，全成功或全失敗）用於以下情境：

        | 情境 | 內容 |
        | --- | --- |
        | 一次開立多項醫囑 | N × MedicationRequest／ServiceRequest，共用 `orderSet` |
        | 簽署文件 | Composition 更新 ＋ Provenance 建立 |
        | 接收交班 | Provenance 建立 ＋ N × Task.owner 更新 |
        | 病歷更正 | 新 Composition 建立 ＋ 舊版 status 更新 |
        | HIS 檢驗結果落地 | Specimen ＋ N × Observation ＋ DiagnosticReport |

        **batch** 僅限唯讀批次載入，含寫入時回 `422`。

        一次批次建立的醫囑只保證「建立」原子；後續簽署、送出、執行、回報各自獨立（BR-ORD-009）。
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Bundle'
            examples:
              example:
                summary: 一次開立兩筆醫囑（transaction，共用同一套組）
                value:
                  resourceType: Bundle
                  type: transaction
                  entry:
                    - fullUrl: urn:uuid:5f0e1d00-0000-0000-0000-000000000001
                      resource:
                        resourceType: MedicationRequest
                        status: draft
                        intent: order
                        category:
                          - coding:
                              - system: http://terminology.hl7.org/CodeSystem/medicationrequest-category
                                code: inpatient
                        medicationCodeableConcept:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/his-medication
                              code: '33795'
                              display: Meropenem 抗生素醫囑
                          text: Meropenem 抗生素醫囑
                        subject:
                          reference: Patient/p1
                        encounter:
                          reference: Encounter/enc-p1
                        dosageInstruction:
                          - text: 劑量依體重 7.2 kg · 每 8 小時
                        dispenseRequest:
                          validityPeriod:
                            start: '2026-06-17T07:30:00+07:00'
                        extension:
                          - url: http://icu.emr.local/StructureDefinition/orderSet
                            valueIdentifier:
                              system: http://icu.emr.local/CodeSystem/order-set
                              value: OS-POSTOP-CARDIAC
                      request:
                        method: POST
                        url: MedicationRequest
                    - fullUrl: urn:uuid:5f0e1d00-0000-0000-0000-000000000002
                      resource:
                        resourceType: ServiceRequest
                        status: draft
                        intent: order
                        priority: routine
                        category:
                          - coding:
                              - system: http://icu.emr.local/CodeSystem/service-category
                                code: laboratory
                                display: 檢驗
                            text: 檢驗
                        code:
                          coding:
                            - code: CBC
                              display: 全血球計數
                          text: 全血球計數
                        subject:
                          reference: Patient/p1
                        encounter:
                          reference: Encounter/enc-p1
                        quantityInteger: 1
                        occurrencePeriod:
                          start: '2026-06-17T06:00:00+07:00'
                        extension:
                          - url: http://icu.emr.local/StructureDefinition/orderSet
                            valueIdentifier:
                              system: http://icu.emr.local/CodeSystem/order-set
                              value: OS-POSTOP-CARDIAC
                      request:
                        method: POST
                        url: ServiceRequest
      responses:
        '200':
          description: 每個 entry 的個別結果（`Bundle.type = transaction-response`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 全部成功（entry 順序與請求相同）
                  value:
                    resourceType: Bundle
                    type: transaction-response
                    entry:
                      - response:
                          status: 201 Created
                          location: MedicationRequest/mr-p1-mero/_history/1
                          etag: W/"1"
                          lastModified: '2026-08-31T08:05:12+07:00'
                      - response:
                          status: 201 Created
                          location: ServiceRequest/sr-p1-cbc/_history/1
                          etag: W/"1"
                          lastModified: '2026-08-31T08:05:12+07:00'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 其中一筆違規 → 整包回滾（沒有任何資源被建立）
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: PROGRESS-NOTE-REQUIRED
                        diagnostics: 第 1 筆醫囑未指定病程來源，整批未建立。請補上病程來源後重送。
                        expression:
                          - Bundle.entry[0].resource.supportingInformation
  /Patient:
    get:
      tags:
        - 病人與就醫
      summary: 搜尋病人（HIS 唯讀）
      operationId: searchPatient
      description: |
        結果一律隱含加上病人範圍過濾（只回操作者照護中的病人）。
        **不會因為無權而回 403，而是回較少的結果**——避免透過錯誤碼探測病人是否存在。
      parameters:
        - name: identifier
          in: query
          schema:
            type: string
          description: 病歷號或身分識別碼
        - name: name
          in: query
          schema:
            type: string
        - name: birthdate
          in: query
          schema:
            type: string
          description: FHIR date 前綴語法，例：ge2020-01-01
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/sort'
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 以病歷號搜尋
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 1
                    link:
                      - relation: self
                        url: https://icu.emr.local/fhir/r4/Patient?identifier=004512&_count=20
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/Patient/p1
                        resource:
                          resourceType: Patient
                          id: p1
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:42:00+07:00'
                            extension:
                              - url: http://icu.emr.local/StructureDefinition/hisSyncedAt
                                valueInstant: '2026-06-17T07:42:00+07:00'
                          identifier:
                            - use: usual
                              system: http://icu.emr.local/CodeSystem/his-patient-id
                              value: 24-0158
                            - type:
                                coding:
                                  - system: http://terminology.hl7.org/CodeSystem/v2-0203
                                    code: MR
                              system: http://icu.emr.local/CodeSystem/medical-record-number
                              value: 24-0158
                          active: true
                          name:
                            - text: Trần Bảo An
                          gender: male
                          birthDate: '2025-10-24'
                          address:
                            - text: 河內市棟多郡朗下坊朗下街 12 巷 42 號
                          contact:
                            - relationship:
                                - text: 監護人
                              name:
                                text: 母 · Lê Thị Hoa
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/insuranceText
                              valueString: 健保 — 6 歲以下兒童 · TE1 01 01 2258 1234
                        search:
                          mode: match
        '401':
          description: 未認證或權杖失效
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 權杖失效
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: login
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: UNKNOWN-ACTOR
                        diagnostics: 無法辨識操作者身分，請重新登入。
  /Patient/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags:
        - 病人與就醫
      summary: 讀取病人
      operationId: readPatient
      responses:
        '200':
          description: 病人
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Patient'
              examples:
                example:
                  summary: 病人（HIS 唯讀鏡像）
                  value:
                    resourceType: Patient
                    id: p1
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T07:42:00+07:00'
                      extension:
                        - url: http://icu.emr.local/StructureDefinition/hisSyncedAt
                          valueInstant: '2026-06-17T07:42:00+07:00'
                    identifier:
                      - use: usual
                        system: http://icu.emr.local/CodeSystem/his-patient-id
                        value: 24-0158
                      - type:
                          coding:
                            - system: http://terminology.hl7.org/CodeSystem/v2-0203
                              code: MR
                        system: http://icu.emr.local/CodeSystem/medical-record-number
                        value: 24-0158
                    active: true
                    name:
                      - text: Trần Bảo An
                    gender: male
                    birthDate: '2025-10-24'
                    address:
                      - text: 河內市棟多郡朗下坊朗下街 12 巷 42 號
                    contact:
                      - relationship:
                          - text: 監護人
                        name:
                          text: 母 · Lê Thị Hoa
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/insuranceText
                        valueString: 健保 — 6 歲以下兒童 · TE1 01 01 2258 1234
        '304':
          description: 未變更（`If-None-Match` 命中）
        '403':
          description: |
            已認證但無權（角色限制；寫入時病人不在照護範圍；照會醫師讀取沒有照會單的病人）。

            **不因無權而回 404**——權限問題一律 403，資源不存在才 404。
            但搜尋是例外：一律回較少的結果而非 403，避免探測病人是否存在。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 病人不在照護範圍
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: forbidden
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: PATIENT-OUT-OF-SCOPE
                        diagnostics: 此病人不在您的照護範圍內。如需查閱請循病歷調閱流程。
        '404':
          description: 資源不存在
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 資源不存在
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: not-found
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: NOT-FOUND
                        diagnostics: 找不到 Patient。請確認識別碼；若為權限問題會回 403 而非 404。
  /Patient/$roster:
    get:
      tags:
        - 病人與就醫
      summary: 本班照護名單
      operationId: getRoster
      description: |
        回傳目前登入者的照護名單（Patient ＋ CareTeam ＋ 作用中醫囑計數）。

        - 主責醫師／護理師：取其 `CareTeam` 參與關係。
        - 照會醫師：只回**已指派給他且尚未完成**的照會病人。
        - 作用中醫囑計數只計 `status=active` 且 `hisTransmissionStatus=accepted` 者。
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 本班照護名單（Patient ＋ CareTeam ＋ 作用中醫囑筆數）
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 1
                    link:
                      - relation: self
                        url: https://icu.emr.local/fhir/r4/Patient/$roster
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/Patient/p1
                        resource:
                          resourceType: Patient
                          id: p1
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:42:00+07:00'
                            extension:
                              - url: http://icu.emr.local/StructureDefinition/hisSyncedAt
                                valueInstant: '2026-06-17T07:42:00+07:00'
                          identifier:
                            - use: usual
                              system: http://icu.emr.local/CodeSystem/his-patient-id
                              value: 24-0158
                            - type:
                                coding:
                                  - system: http://terminology.hl7.org/CodeSystem/v2-0203
                                    code: MR
                              system: http://icu.emr.local/CodeSystem/medical-record-number
                              value: 24-0158
                          active: true
                          name:
                            - text: Trần Bảo An
                          gender: male
                          birthDate: '2025-10-24'
                          address:
                            - text: 河內市棟多郡朗下坊朗下街 12 巷 42 號
                          contact:
                            - relationship:
                                - text: 監護人
                              name:
                                text: 母 · Lê Thị Hoa
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/insuranceText
                              valueString: 健保 — 6 歲以下兒童 · TE1 01 01 2258 1234
                        search:
                          mode: match
                        extension:
                          - url: http://icu.emr.local/StructureDefinition/activeOrderCount
                            valueInteger: 6
                      - fullUrl: https://icu.emr.local/fhir/r4/CareTeam/ct-p1
                        resource:
                          resourceType: CareTeam
                          id: ct-p1
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:42:00+07:00'
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/assignmentSource
                              valueString: 示範院區預先分派
                            - url: http://icu.emr.local/StructureDefinition/rosterConfirmation
                              extension:
                                - url: by
                                  valueReference:
                                    reference: PractitionerRole/thucdv
                                    display: 博士醫師 Đặng Văn Thức
                                - url: at
                                  valueInstant: '2026-09-19T17:28:35+07:00'
                          status: active
                          subject:
                            reference: Patient/p1
                          encounter:
                            reference: Encounter/enc-p1
                          period:
                            start: '2026-06-15T21:12:00+07:00'
                          participant:
                            - member:
                                reference: PractitionerRole/thucdv
                                display: 博士醫師 Đặng Văn Thức
                              role:
                                - text: 主治醫師
                              period:
                                start: '2026-06-15T21:12:00+07:00'
                            - member:
                                reference: PractitionerRole/nhungtt
                                display: 護理師 Phạm Thị Hồng Nhung
                              role:
                                - text: 照護護理師
                              period:
                                start: '2026-06-15T21:12:00+07:00'
                        search:
                          mode: include
        '401':
          description: 未認證或權杖失效
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 權杖失效
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: login
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: UNKNOWN-ACTOR
                        diagnostics: 無法辨識操作者身分，請重新登入。
  /Encounter:
    get:
      tags:
        - 病人與就醫
      summary: 搜尋就醫事件（HIS 唯讀）
      operationId: searchEncounter
      parameters:
        - $ref: '#/components/parameters/patient'
        - name: status
          in: query
          schema:
            type: string
        - name: date
          in: query
          schema:
            type: string
        - name: identifier
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 本次住院（含科別與床位期間）
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 1
                    link:
                      - relation: self
                        url: https://icu.emr.local/fhir/r4/Encounter?patient=Patient/p1&status=in-progress
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/Encounter/enc-p1
                        resource:
                          resourceType: Encounter
                          id: enc-p1
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:42:00+07:00'
                          identifier:
                            - system: http://icu.emr.local/CodeSystem/his-encounter-number
                              value: 25-08842
                          status: in-progress
                          class:
                            system: http://terminology.hl7.org/CodeSystem/v3-ActCode
                            code: IMP
                          subject:
                            reference: Patient/p1
                          period:
                            start: '2026-06-15T21:12:00+07:00'
                          reasonCode:
                            - coding:
                                - system: http://hl7.org/fhir/sid/icd-10
                                  code: Q26.2
                              text: 肺靜脈回流異常術後 – 第 1 天
                          location:
                            - location:
                                reference: Location/bed-201A-1
                                display: 201A-1
                              status: active
                              physicalType:
                                coding:
                                  - system: http://terminology.hl7.org/CodeSystem/location-physical-type
                                    code: bd
                              period:
                                start: '2026-06-15T21:12:00+07:00'
                            - location:
                                reference: Location/picu
                                display: 心臟外科加護
                              status: active
                              physicalType:
                                coding:
                                  - system: http://terminology.hl7.org/CodeSystem/location-physical-type
                                    code: wa
                              period:
                                start: '2026-06-15T21:12:00+07:00'
                            - location:
                                reference: Location/room-201A
                                display: 室 201A
                              status: active
                              physicalType:
                                coding:
                                  - system: http://terminology.hl7.org/CodeSystem/location-physical-type
                                    code: ro
                              period:
                                start: '2026-06-15T21:12:00+07:00'
                        search:
                          mode: match
  /CareTeam:
    get:
      tags:
        - 病人與就醫
      summary: 搜尋照護團隊
      operationId: searchCareTeam
      parameters:
        - $ref: '#/components/parameters/patient'
        - name: participant
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 本班照護名單
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 1
                    link:
                      - relation: self
                        url: https://icu.emr.local/fhir/r4/CareTeam?patient=Patient/p1&status=active
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/CareTeam/ct-p1
                        resource:
                          resourceType: CareTeam
                          id: ct-p1
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:42:00+07:00'
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/assignmentSource
                              valueString: 示範院區預先分派
                            - url: http://icu.emr.local/StructureDefinition/rosterConfirmation
                              extension:
                                - url: by
                                  valueReference:
                                    reference: PractitionerRole/thucdv
                                    display: 博士醫師 Đặng Văn Thức
                                - url: at
                                  valueInstant: '2026-09-19T17:28:35+07:00'
                          status: active
                          subject:
                            reference: Patient/p1
                          encounter:
                            reference: Encounter/enc-p1
                          period:
                            start: '2026-06-15T21:12:00+07:00'
                          participant:
                            - member:
                                reference: PractitionerRole/thucdv
                                display: 博士醫師 Đặng Văn Thức
                              role:
                                - text: 主治醫師
                              period:
                                start: '2026-06-15T21:12:00+07:00'
                            - member:
                                reference: PractitionerRole/nhungtt
                                display: 護理師 Phạm Thị Hồng Nhung
                              role:
                                - text: 照護護理師
                              period:
                                start: '2026-06-15T21:12:00+07:00'
                        search:
                          mode: match
    post:
      tags:
        - 病人與就醫
      summary: 建立照護團隊
      operationId: createCareTeam
      description: |
        「確認照護名單」這個動作**不是** CareTeam 上的一個時間欄位，而是另建一筆
        `Provenance`（`activity = roster-confirm`，`target = CareTeam/…`）。
        理由：同一份名單可被不同班別、不同人各自確認一次，每次都要留人與時間。
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/CareTeam'
            examples:
              example:
                summary: 確認本班照護名單
                value:
                  resourceType: CareTeam
                  status: active
                  subject:
                    reference: Patient/p1
                    display: Trần Bảo An
                  encounter:
                    reference: Encounter/enc-p1
                  period:
                    start: '2026-08-31T07:00:00+07:00'
                    end: '2026-08-31T19:00:00+07:00'
                  participant:
                    - member:
                        reference: PractitionerRole/thucdv
                        display: 博士醫師 Đặng Văn Thức
                      role:
                        - text: 主責醫師
                    - member:
                        reference: PractitionerRole/nhungtt
                        display: 護理師 Phạm Thị Hồng Nhung
                      role:
                        - text: 主護
      responses:
        '201':
          description: 已建立
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 已建立（確認動作另記在 Provenance）
                  value:
                    resourceType: CareTeam
                    id: ct-p1
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T07:42:00+07:00'
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/assignmentSource
                        valueString: 示範院區預先分派
                      - url: http://icu.emr.local/StructureDefinition/rosterConfirmation
                        extension:
                          - url: by
                            valueReference:
                              reference: PractitionerRole/thucdv
                              display: 博士醫師 Đặng Văn Thức
                          - url: at
                            valueInstant: '2026-09-19T17:28:35+07:00'
                    status: active
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    period:
                      start: '2026-06-15T21:12:00+07:00'
                    participant:
                      - member:
                          reference: PractitionerRole/thucdv
                          display: 博士醫師 Đặng Văn Thức
                        role:
                          - text: 主治醫師
                        period:
                          start: '2026-06-15T21:12:00+07:00'
                      - member:
                          reference: PractitionerRole/nhungtt
                          display: 護理師 Phạm Thị Hồng Nhung
                        role:
                          - text: 照護護理師
                        period:
                          start: '2026-06-15T21:12:00+07:00'
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 指派對象不可被指派
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: business-rule
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: ACTOR-NOT-ASSIGNABLE
                        diagnostics: 該人員不在可指派名單中，請確認職稱與值班設定。
                        expression:
                          - CareTeam.participant[1].member
  /Flag:
    get:
      tags:
        - 病人與就醫
      summary: 搜尋病人特殊註記（過敏／隔離／管路天數／嚴重度）
      operationId: searchFlag
      description: |
        病人清單上的彩色標籤（設計稿 EMR-TW 的「Penicillin 過敏」「飛沫隔離」「CVC 第 3 天」「重症」）。
        嚴重度（極重症／中等／穩定）也是一面旗（`category = severity`），不是 Patient 的欄位——
        判定規則與維護責任仍是院方待決（F2 回問 #5），所以它必須可以獨立更新、留歷史。

        本輪唯讀（來源：護理評估與 HIS）；建立／更新待院方核定判定規則後再開。
      parameters:
        - $ref: '#/components/parameters/patient'
        - name: encounter
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum:
              - active
              - inactive
              - entered-in-error
        - name: category
          in: query
          schema:
            type: string
          description: allergy | isolation | device | treatment | risk | severity | status | monitoring
        - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 病人 p1 的特殊註記（嚴重度＋過敏）
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 2
                    link:
                      - relation: self
                        url: https://icu.emr.local/fhir/r4/Flag?patient=Patient/p1&status=active
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/Flag/flag-p1-1
                        resource:
                          resourceType: Flag
                          id: flag-p1-1
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:42:00+07:00'
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/flagTone
                              valueCode: red
                          status: active
                          category:
                            - coding:
                                - system: http://icu.emr.local/CodeSystem/flag-category
                                  code: severity
                          code:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/flag-code
                                code: red
                            text: 極重症
                          subject:
                            reference: Patient/p1
                          encounter:
                            reference: Encounter/enc-p1
                          period:
                            start: '2026-06-15T21:12:00+07:00'
                        search:
                          mode: match
                      - fullUrl: https://icu.emr.local/fhir/r4/Flag/flag-p1-3
                        resource:
                          resourceType: Flag
                          id: flag-p1-3
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:42:00+07:00'
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/flagTone
                              valueCode: red
                          status: active
                          category:
                            - coding:
                                - system: http://icu.emr.local/CodeSystem/flag-category
                                  code: allergy
                          code:
                            text: Penicillin 過敏
                          subject:
                            reference: Patient/p1
                          encounter:
                            reference: Encounter/enc-p1
                          period:
                            start: '2026-06-15T21:12:00+07:00'
                        search:
                          mode: match
  /Flag/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags:
        - 病人與就醫
      summary: 讀取特殊註記
      operationId: readFlag
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Flag'
              examples:
                example:
                  summary: 一面旗：Penicillin 過敏
                  value:
                    resourceType: Flag
                    id: flag-p1-3
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T07:42:00+07:00'
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/flagTone
                        valueCode: red
                    status: active
                    category:
                      - coding:
                          - system: http://icu.emr.local/CodeSystem/flag-category
                            code: allergy
                    code:
                      text: Penicillin 過敏
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    period:
                      start: '2026-06-15T21:12:00+07:00'
        '404':
          description: 資源不存在
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 資源不存在
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: not-found
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: NOT-FOUND
                        diagnostics: 找不到 Flag。請確認識別碼；若為權限問題會回 403 而非 404。
  /Practitioner:
    get:
      tags:
        - 病人與就醫
      summary: 搜尋人員（HIS／人事唯讀）
      operationId: searchPractitioner
      parameters:
        - name: name
          in: query
          schema:
            type: string
        - name: identifier
          in: query
          schema:
            type: string
          description: 帳號
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 依姓名找人員
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 1
                    link:
                      - relation: self
                        url: https://icu.emr.local/fhir/r4/Practitioner?name=Th
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/Practitioner/thucdv
                        resource:
                          resourceType: Practitioner
                          id: thucdv
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:42:00+07:00'
                          identifier:
                            - system: http://icu.emr.local/CodeSystem/staff-account
                              value: thucdv
                          active: true
                          name:
                            - text: 博士醫師 Đặng Văn Thức
                              family: Đặng Văn Thức
                              prefix:
                                - 博士醫師
                        search:
                          mode: match
  /Practitioner/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags:
        - 病人與就醫
      summary: 讀取人員
      operationId: readPractitioner
      responses:
        '200':
          description: OK
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Practitioner'
              examples:
                example:
                  summary: 人員（HIS／人事唯讀）
                  value:
                    resourceType: Practitioner
                    id: thucdv
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T07:42:00+07:00'
                    identifier:
                      - system: http://icu.emr.local/CodeSystem/staff-account
                        value: thucdv
                    active: true
                    name:
                      - text: 博士醫師 Đặng Văn Thức
                        family: Đặng Văn Thức
                        prefix:
                          - 博士醫師
        '404':
          description: 資源不存在
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 資源不存在
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: not-found
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: NOT-FOUND
                        diagnostics: 找不到 Practitioner。請確認識別碼；若為權限問題會回 403 而非 404。
  /Practitioner/$me:
    get:
      tags:
        - 病人與就醫
      summary: 我是誰（權杖對應的人＋角色）
      operationId: getMe
      description: |
        登入後畫面要顯示姓名、職稱、科別、班別。回 collection Bundle：`entry[0]` Practitioner、`entry[1]` PractitionerRole
        （`code` 職稱、`specialty`／`location` 科別、`extension[shift]` 班別）。取代 H13 的 `/me` 與 `/shifts/current`。
      responses:
        '200':
          description: OK
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 權杖對應的人＋角色
                  value:
                    resourceType: Bundle
                    type: collection
                    entry:
                      - fullUrl: http://127.0.0.1:8787/fhir/r4/Practitioner/thucdv
                        resource:
                          resourceType: Practitioner
                          id: thucdv
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:42:00+07:00'
                          identifier:
                            - system: http://icu.emr.local/CodeSystem/staff-account
                              value: thucdv
                          active: true
                          name:
                            - text: 博士醫師 Đặng Văn Thức
                              family: Đặng Văn Thức
                              prefix:
                                - 博士醫師
                      - fullUrl: http://127.0.0.1:8787/fhir/r4/PractitionerRole/thucdv
                        resource:
                          resourceType: PractitionerRole
                          id: thucdv
                          meta:
                            versionId: '1'
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/shift
                              valueCoding:
                                system: http://icu.emr.local/CodeSystem/shift
                                code: D1
                                display: 日班
                          active: true
                          practitioner:
                            reference: Practitioner/thucdv
                            display: 博士醫師 Đặng Văn Thức
                          code:
                            - coding:
                                - system: http://icu.emr.local/CodeSystem/staff-role
                                  code: doctor
                                  display: 醫師
                              text: 醫師
                          specialty:
                            - text: 心臟外科加護
                          location:
                            - reference: Location/picu
                              display: 心臟外科加護
        '401':
          description: 未認證或權杖失效
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 權杖無效
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: login
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: UNKNOWN-ACTOR
                        diagnostics: 無法辨識操作者身分，請重新登入。
  /PractitionerRole/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags:
        - 病人與就醫
      summary: 讀取人員在本院的角色（職稱、科別、班別）
      operationId: readPractitionerRole
      responses:
        '200':
          description: OK
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/PractitionerRole'
              examples:
                example:
                  summary: 職稱、科別、班別
                  value:
                    resourceType: PractitionerRole
                    id: thucdv
                    meta:
                      versionId: '1'
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/shift
                        valueCoding:
                          system: http://icu.emr.local/CodeSystem/shift
                          code: D1
                          display: 日班
                    active: true
                    practitioner:
                      reference: Practitioner/thucdv
                      display: 博士醫師 Đặng Văn Thức
                    code:
                      - coding:
                          - system: http://icu.emr.local/CodeSystem/staff-role
                            code: doctor
                            display: 醫師
                        text: 醫師
                    specialty:
                      - text: 心臟外科加護
                    location:
                      - reference: Location/picu
                        display: 心臟外科加護
        '404':
          description: 資源不存在
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 資源不存在
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: not-found
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: NOT-FOUND
                        diagnostics: 找不到 PractitionerRole。請確認識別碼；若為權限問題會回 403 而非 404。
  /Condition:
    get:
      tags:
        - 診斷與溝通
      summary: 搜尋診斷與問題清單
      operationId: searchCondition
      description: |
        入院診斷／入科診斷／出院診斷／問題各一列（`category`）。「診斷演變時間軸」不另設資源：
        每次確立、排除、改角色都是一次版本推進，`GET /Condition/{id}/_history/{n}` 就是歷程。
      parameters:
        - $ref: '#/components/parameters/patient'
        - name: encounter
          in: query
          schema:
            type: string
        - name: category
          in: query
          schema:
            type: string
            enum:
              - admission
              - ward
              - discharge
              - problem
        - name: clinical-status
          in: query
          schema:
            type: string
        - name: verification-status
          in: query
          schema:
            type: string
            enum:
              - confirmed
              - provisional
              - differential
              - refuted
        - name: code
          in: query
          schema:
            type: string
          description: ICD-10，可寫 system|code
        - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: p1 入科診斷：主診斷、合併症、已排除的鑑別
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 2
                    link:
                      - relation: self
                        url: https://icu.emr.local/fhir/r4/Condition?patient=Patient/p1&category=ward
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/Condition/cond-p1-ward-main
                        resource:
                          resourceType: Condition
                          id: cond-p1-ward-main
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-16T20:30:00+07:00'
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/diagnosisRole
                              valueCode: primary
                            - url: http://icu.emr.local/StructureDefinition/diagnosisEvidence
                              valueString: 都卜勒心臟超音波・手術紀錄
                          clinicalStatus:
                            coding:
                              - system: http://terminology.hl7.org/CodeSystem/condition-clinical
                                code: active
                          verificationStatus:
                            coding:
                              - system: http://terminology.hl7.org/CodeSystem/condition-ver-status
                                code: confirmed
                          category:
                            - coding:
                                - system: http://icu.emr.local/CodeSystem/condition-category
                                  code: ward
                          code:
                            coding:
                              - system: http://hl7.org/fhir/sid/icd-10
                                code: Q21.0
                                display: 心室中隔缺損
                            text: 心室中隔缺損
                          subject:
                            reference: Patient/p1
                          encounter:
                            reference: Encounter/enc-p1
                          recordedDate: '2026-06-16T20:30:00+07:00'
                          recorder:
                            reference: PractitionerRole/thucdv
                          note:
                            - text: 術後第 1 天，血液動力學改善。
                        search:
                          mode: match
                      - fullUrl: https://icu.emr.local/fhir/r4/Condition/cond-p1-ward-diff
                        resource:
                          resourceType: Condition
                          id: cond-p1-ward-diff
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-16T20:30:00+07:00'
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/diagnosisEvidence
                              valueString: 心臟超音波 EF 58%
                          clinicalStatus:
                            coding:
                              - system: http://terminology.hl7.org/CodeSystem/condition-clinical
                                code: inactive
                          verificationStatus:
                            coding:
                              - system: http://terminology.hl7.org/CodeSystem/condition-ver-status
                                code: refuted
                          category:
                            - coding:
                                - system: http://icu.emr.local/CodeSystem/condition-category
                                  code: ward
                          code:
                            coding:
                              - system: http://hl7.org/fhir/sid/icd-10
                                code: I50.9
                                display: 心臟衰竭
                            text: 心臟衰竭
                          subject:
                            reference: Patient/p1
                          encounter:
                            reference: Encounter/enc-p1
                          recordedDate: '2026-06-16T20:30:00+07:00'
                          recorder:
                            reference: PractitionerRole/thucdv
                          note:
                            - text: 術後心輸出量改善，排除。
                        search:
                          mode: match
    post:
      tags:
        - 診斷與溝通
      summary: 新增診斷（限醫師；ICD-10 必須自目錄選）
      operationId: createCondition
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Condition'
            examples:
              example:
                summary: 新增入科診斷（ICD-10 自目錄選）
                value:
                  resourceType: Condition
                  extension:
                    - url: http://icu.emr.local/StructureDefinition/diagnosisRole
                      valueCode: primary
                    - url: http://icu.emr.local/StructureDefinition/diagnosisEvidence
                      valueString: 都卜勒心臟超音波・手術紀錄
                  clinicalStatus:
                    coding:
                      - system: http://terminology.hl7.org/CodeSystem/condition-clinical
                        code: active
                  verificationStatus:
                    coding:
                      - system: http://terminology.hl7.org/CodeSystem/condition-ver-status
                        code: confirmed
                  category:
                    - coding:
                        - system: http://icu.emr.local/CodeSystem/condition-category
                          code: ward
                  code:
                    coding:
                      - system: http://hl7.org/fhir/sid/icd-10
                        code: Q21.0
                        display: 心室中隔缺損
                    text: 心室中隔缺損
                  subject:
                    reference: Patient/p1
                  encounter:
                    reference: Encounter/enc-p1
                  note:
                    - text: 術後第 1 天，血液動力學改善。
      responses:
        '201':
          description: 已建立
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 建立
                  value:
                    resourceType: Condition
                    id: cond-p1-ward-main
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-16T20:30:00+07:00'
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/diagnosisRole
                        valueCode: primary
                      - url: http://icu.emr.local/StructureDefinition/diagnosisEvidence
                        valueString: 都卜勒心臟超音波・手術紀錄
                    clinicalStatus:
                      coding:
                        - system: http://terminology.hl7.org/CodeSystem/condition-clinical
                          code: active
                    verificationStatus:
                      coding:
                        - system: http://terminology.hl7.org/CodeSystem/condition-ver-status
                          code: confirmed
                    category:
                      - coding:
                          - system: http://icu.emr.local/CodeSystem/condition-category
                            code: ward
                    code:
                      coding:
                        - system: http://hl7.org/fhir/sid/icd-10
                          code: Q21.0
                          display: 心室中隔缺損
                      text: 心室中隔缺損
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    recordedDate: '2026-06-16T20:30:00+07:00'
                    recorder:
                      reference: PractitionerRole/thucdv
                    note:
                      - text: 術後第 1 天，血液動力學改善。
        '403':
          description: |
            已認證但無權（角色限制；寫入時病人不在照護範圍；照會醫師讀取沒有照會單的病人）。

            **不因無權而回 404**——權限問題一律 403，資源不存在才 404。
            但搜尋是例外：一律回較少的結果而非 403，避免探測病人是否存在。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 護理師不能建立診斷
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: forbidden
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: ROLE-DOCTOR-ONLY
                        diagnostics: 建立診斷僅限醫師。
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 代碼不在 ICD-10 目錄
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: CODE-REQUIRED
                        diagnostics: ICD-10 目錄裡沒有 Q99.9，請重新選取。
                        expression:
                          - Condition.code.coding[0].code
  /Condition/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags:
        - 診斷與溝通
      summary: 讀取診斷
      operationId: readCondition
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Condition'
              examples:
                example:
                  summary: 診斷
                  value:
                    resourceType: Condition
                    id: cond-p1-ward-main
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-16T20:30:00+07:00'
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/diagnosisRole
                        valueCode: primary
                      - url: http://icu.emr.local/StructureDefinition/diagnosisEvidence
                        valueString: 都卜勒心臟超音波・手術紀錄
                    clinicalStatus:
                      coding:
                        - system: http://terminology.hl7.org/CodeSystem/condition-clinical
                          code: active
                    verificationStatus:
                      coding:
                        - system: http://terminology.hl7.org/CodeSystem/condition-ver-status
                          code: confirmed
                    category:
                      - coding:
                          - system: http://icu.emr.local/CodeSystem/condition-category
                            code: ward
                    code:
                      coding:
                        - system: http://hl7.org/fhir/sid/icd-10
                          code: Q21.0
                          display: 心室中隔缺損
                      text: 心室中隔缺損
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    recordedDate: '2026-06-16T20:30:00+07:00'
                    recorder:
                      reference: PractitionerRole/thucdv
                    note:
                      - text: 術後第 1 天，血液動力學改善。
        '404':
          description: 資源不存在
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 資源不存在
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: not-found
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: NOT-FOUND
                        diagnostics: 找不到 Condition。請確認識別碼；若為權限問題會回 403 而非 404。
    put:
      tags:
        - 診斷與溝通
      summary: 確立／排除／改角色／補依據（代碼不可換）
      operationId: updateCondition
      description: 換診斷＝把這筆標 `refuted` 後另建新的，演變歷程才留得住。需 `If-Match`。
      parameters:
        - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Condition'
            examples:
              example:
                summary: 排除鑑別診斷（verificationStatus → refuted，代碼不變）
                value:
                  resourceType: Condition
                  id: cond-p1-ward-diff
                  meta:
                    versionId: '1'
                    lastUpdated: '2026-06-16T20:30:00+07:00'
                  extension:
                    - url: http://icu.emr.local/StructureDefinition/diagnosisEvidence
                      valueString: 心臟超音波 EF 58%
                  clinicalStatus:
                    coding:
                      - system: http://terminology.hl7.org/CodeSystem/condition-clinical
                        code: inactive
                  verificationStatus:
                    coding:
                      - system: http://terminology.hl7.org/CodeSystem/condition-ver-status
                        code: refuted
                  category:
                    - coding:
                        - system: http://icu.emr.local/CodeSystem/condition-category
                          code: ward
                  code:
                    coding:
                      - system: http://hl7.org/fhir/sid/icd-10
                        code: I50.9
                        display: 心臟衰竭
                    text: 心臟衰竭
                  subject:
                    reference: Patient/p1
                  encounter:
                    reference: Encounter/enc-p1
                  recordedDate: '2026-06-16T20:30:00+07:00'
                  recorder:
                    reference: PractitionerRole/thucdv
                  note:
                    - text: 術後心輸出量改善，排除。
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Condition'
              examples:
                example:
                  summary: 版本推進；_history 就是演變時間軸
                  value:
                    resourceType: Condition
                    id: cond-p1-ward-diff
                    meta:
                      versionId: '2'
                      lastUpdated: '2026-06-17T08:40:00+07:00'
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/diagnosisEvidence
                        valueString: 心臟超音波 EF 58%
                    clinicalStatus:
                      coding:
                        - system: http://terminology.hl7.org/CodeSystem/condition-clinical
                          code: inactive
                    verificationStatus:
                      coding:
                        - system: http://terminology.hl7.org/CodeSystem/condition-ver-status
                          code: refuted
                    category:
                      - coding:
                          - system: http://icu.emr.local/CodeSystem/condition-category
                            code: ward
                    code:
                      coding:
                        - system: http://hl7.org/fhir/sid/icd-10
                          code: I50.9
                          display: 心臟衰竭
                      text: 心臟衰竭
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    recordedDate: '2026-06-16T20:30:00+07:00'
                    recorder:
                      reference: PractitionerRole/thucdv
                    note:
                      - text: 術後心輸出量改善，排除。
        '409':
          description: |
            版本衝突，或目前狀態不允許此操作。

            版本衝突時必須帶目前版本，讓客戶端就地合併——**內容不會被覆寫**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 版本落後
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: conflict
                        details:
                          text: currentVersionId=2
                        diagnostics: 資源已被其他工作階段更新至 versionId=2。請重新讀取後合併，內容未被覆寫。
        '412':
          description: 缺少 `If-Match` 標頭
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 缺 If-Match
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: PRECONDITION-REQUIRED
                        diagnostics: 缺少 If-Match 標頭。所有可寫互動都必須帶目前版本，不接受盲目覆寫。
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 想就地換代碼
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: VALUE-INVALID
                        diagnostics: 診斷代碼不可就地更換；請把這筆標為 refuted 後另建新診斷，演變歷程才留得住。
                        expression:
                          - Condition.code
  /Goal:
    get:
      tags:
        - 診斷與溝通
      summary: 搜尋本日問題與目標
      operationId: searchGoal
      parameters:
        - $ref: '#/components/parameters/patient'
        - name: encounter
          in: query
          schema:
            type: string
        - name: lifecycle-status
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 本日目標
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 1
                    link:
                      - relation: self
                        url: https://icu.emr.local/fhir/r4/Goal?patient=Patient/p1&lifecycle-status=active
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/Goal/goal-p1-1
                        resource:
                          resourceType: Goal
                          id: goal-p1-1
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:30:00+07:00'
                          lifecycleStatus: active
                          description:
                            text: 血氣穩定後脫離呼吸器
                          subject:
                            reference: Patient/p1
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/goalEncounter
                              valueReference:
                                reference: Encounter/enc-p1
                          target:
                            - detailString: 每 6 小時血氣；pH ≥ 7.35 且 FiO₂ ≤ 30% 時評估拔管
                              dueDate: '2026-06-17'
                          addresses:
                            - reference: Condition/cond-p1-ward-main
                          expressedBy:
                            reference: PractitionerRole/thucdv
                          statusDate: '2026-06-17'
                        search:
                          mode: match
    post:
      tags:
        - 診斷與溝通
      summary: 新增本日目標（限主治）
      operationId: createGoal
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Goal'
            examples:
              example:
                summary: 新增本日目標
                value:
                  resourceType: Goal
                  lifecycleStatus: active
                  description:
                    text: 血氣穩定後脫離呼吸器
                  subject:
                    reference: Patient/p1
                  extension:
                    - url: http://icu.emr.local/StructureDefinition/goalEncounter
                      valueReference:
                        reference: Encounter/enc-p1
                  target:
                    - detailString: 每 6 小時血氣；pH ≥ 7.35 且 FiO₂ ≤ 30% 時評估拔管
                      dueDate: '2026-06-17'
                  addresses:
                    - reference: Condition/cond-p1-ward-main
      responses:
        '201':
          description: 已建立
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 建立
                  value:
                    resourceType: Goal
                    id: goal-p1-1
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T07:30:00+07:00'
                    lifecycleStatus: active
                    description:
                      text: 血氣穩定後脫離呼吸器
                    subject:
                      reference: Patient/p1
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/goalEncounter
                        valueReference:
                          reference: Encounter/enc-p1
                    target:
                      - detailString: 每 6 小時血氣；pH ≥ 7.35 且 FiO₂ ≤ 30% 時評估拔管
                        dueDate: '2026-06-17'
                    addresses:
                      - reference: Condition/cond-p1-ward-main
                    expressedBy:
                      reference: PractitionerRole/thucdv
                    statusDate: '2026-06-17'
        '403':
          description: |
            已認證但無權（角色限制；寫入時病人不在照護範圍；照會醫師讀取沒有照會單的病人）。

            **不因無權而回 404**——權限問題一律 403，資源不存在才 404。
            但搜尋是例外：一律回較少的結果而非 403，避免探測病人是否存在。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 限主治
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: forbidden
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: ROLE-DOCTOR-ONLY
                        diagnostics: 建立本日目標僅限醫師。
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 沒有描述
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: VALUE-INVALID
                        diagnostics: 目標必須有描述。
                        expression:
                          - Goal.description
  /Goal/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags:
        - 診斷與溝通
      summary: 讀取目標
      operationId: readGoal
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Goal'
              examples:
                example:
                  summary: 目標
                  value:
                    resourceType: Goal
                    id: goal-p1-1
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T07:30:00+07:00'
                    lifecycleStatus: active
                    description:
                      text: 血氣穩定後脫離呼吸器
                    subject:
                      reference: Patient/p1
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/goalEncounter
                        valueReference:
                          reference: Encounter/enc-p1
                    target:
                      - detailString: 每 6 小時血氣；pH ≥ 7.35 且 FiO₂ ≤ 30% 時評估拔管
                        dueDate: '2026-06-17'
                    addresses:
                      - reference: Condition/cond-p1-ward-main
                    expressedBy:
                      reference: PractitionerRole/thucdv
                    statusDate: '2026-06-17'
        '404':
          description: 資源不存在
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 資源不存在
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: not-found
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: NOT-FOUND
                        diagnostics: 找不到 Goal。請確認識別碼；若為權限問題會回 403 而非 404。
    put:
      tags:
        - 診斷與溝通
      summary: 更新目標（完成／取消／改描述）
      operationId: updateGoal
      parameters:
        - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Goal'
            examples:
              example:
                summary: 完成目標
                value:
                  resourceType: Goal
                  id: goal-p1-1
                  meta:
                    versionId: '1'
                    lastUpdated: '2026-06-17T07:30:00+07:00'
                  lifecycleStatus: completed
                  description:
                    text: 血氣穩定後脫離呼吸器
                  subject:
                    reference: Patient/p1
                  extension:
                    - url: http://icu.emr.local/StructureDefinition/goalEncounter
                      valueReference:
                        reference: Encounter/enc-p1
                  target:
                    - detailString: 每 6 小時血氣；pH ≥ 7.35 且 FiO₂ ≤ 30% 時評估拔管
                      dueDate: '2026-06-17'
                  addresses:
                    - reference: Condition/cond-p1-ward-main
                  expressedBy:
                    reference: PractitionerRole/thucdv
                  statusDate: '2026-06-17'
      responses:
        '200':
          description: OK
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Goal'
              examples:
                example:
                  summary: 已完成
                  value:
                    resourceType: Goal
                    id: goal-p1-1
                    meta:
                      versionId: '2'
                      lastUpdated: '2026-06-17T18:00:00+07:00'
                    lifecycleStatus: completed
                    description:
                      text: 血氣穩定後脫離呼吸器
                    subject:
                      reference: Patient/p1
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/goalEncounter
                        valueReference:
                          reference: Encounter/enc-p1
                    target:
                      - detailString: 每 6 小時血氣；pH ≥ 7.35 且 FiO₂ ≤ 30% 時評估拔管
                        dueDate: '2026-06-17'
                    addresses:
                      - reference: Condition/cond-p1-ward-main
                    expressedBy:
                      reference: PractitionerRole/thucdv
                    statusDate: '2026-06-17'
        '409':
          description: |
            版本衝突，或目前狀態不允許此操作。

            版本衝突時必須帶目前版本，讓客戶端就地合併——**內容不會被覆寫**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 版本落後
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: conflict
                        details:
                          text: currentVersionId=2
                        diagnostics: 資源已被其他工作階段更新至 versionId=2。請重新讀取後合併，內容未被覆寫。
        '412':
          description: 缺少 `If-Match` 標頭
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 缺 If-Match
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: PRECONDITION-REQUIRED
                        diagnostics: 缺少 If-Match 標頭。所有可寫互動都必須帶目前版本，不接受盲目覆寫。
  /Communication:
    get:
      tags:
        - 診斷與溝通
      summary: 搜尋照會回覆與必要溝通
      operationId: searchCommunication
      parameters:
        - $ref: '#/components/parameters/patient'
        - name: category
          in: query
          schema:
            type: string
            enum:
              - consult-reply
              - essential
        - name: based-on
          in: query
          schema:
            type: string
          description: 照會單 ServiceRequest
        - name: sender
          in: query
          schema:
            type: string
        - name: recipient
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 照會回覆＋必要溝通
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 2
                    link:
                      - relation: self
                        url: https://icu.emr.local/fhir/r4/Communication?patient=Patient/p1
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/Communication/comm-p1-reply
                        resource:
                          resourceType: Communication
                          id: comm-p1-reply
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:05:00+07:00'
                          status: completed
                          category:
                            - coding:
                                - system: http://icu.emr.local/CodeSystem/communication-category
                                  code: consult-reply
                          priority: urgent
                          basedOn:
                            - reference: ServiceRequest/sr-p1-consult
                          subject:
                            reference: Patient/p1
                          encounter:
                            reference: Encounter/enc-p1
                          sent: '2026-06-17T07:05:00+07:00'
                          sender:
                            reference: PractitionerRole/phuongdt
                          recipient:
                            - reference: PractitionerRole/thucdv
                          payload:
                            - contentString: 術後心律規則、竇性 148 次/分，無心律不整。建議 Milrinon 維持 0.5 µg/kg/分至明晨再評估；Adrenalin 可逐步減量。
                        search:
                          mode: match
                      - fullUrl: https://icu.emr.local/fhir/r4/Communication/comm-p1-essential
                        resource:
                          resourceType: Communication
                          id: comm-p1-essential
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T06:20:00+07:00'
                          status: completed
                          category:
                            - coding:
                                - system: http://icu.emr.local/CodeSystem/communication-category
                                  code: essential
                          priority: routine
                          subject:
                            reference: Patient/p1
                          encounter:
                            reference: Encounter/enc-p1
                          sent: '2026-06-17T06:20:00+07:00'
                          sender:
                            reference: PractitionerRole/nhungtt
                          recipient:
                            - reference: PractitionerRole/thucdv
                          payload:
                            - contentString: 06:00 縱膈引流 10 ml/6h 淡血性，較昨夜減少；家屬詢問今日是否可探視，已告知依科規。
                        search:
                          mode: match
    post:
      tags:
        - 診斷與溝通
      summary: 回覆照會／新增必要溝通（只新增，不修改）
      operationId: createCommunication
      description: |
        `category = consult-reply` 必須 `basedOn` 指向照會單（`ServiceRequest`，category = consultation），限醫師；
        照會醫師只能回覆，不能建立必要溝通（BR-AUTH-003）。會診只提建議，開單仍由主治（24 項 #3）。
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Communication'
            examples:
              example:
                summary: 照會醫師回覆照會（basedOn 指向照會單）
                value:
                  resourceType: Communication
                  category:
                    - coding:
                        - system: http://icu.emr.local/CodeSystem/communication-category
                          code: consult-reply
                  priority: urgent
                  basedOn:
                    - reference: ServiceRequest/sr-p1-consult
                  subject:
                    reference: Patient/p1
                  encounter:
                    reference: Encounter/enc-p1
                  recipient:
                    - reference: PractitionerRole/thucdv
                  payload:
                    - contentString: 術後心律規則、竇性 148 次/分，無心律不整。建議 Milrinon 維持 0.5 µg/kg/分至明晨再評估；Adrenalin 可逐步減量。
      responses:
        '201':
          description: 已建立
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 建立
                  value:
                    resourceType: Communication
                    id: comm-p1-reply
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T07:05:00+07:00'
                    status: completed
                    category:
                      - coding:
                          - system: http://icu.emr.local/CodeSystem/communication-category
                            code: consult-reply
                    priority: urgent
                    basedOn:
                      - reference: ServiceRequest/sr-p1-consult
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    sent: '2026-06-17T07:05:00+07:00'
                    sender:
                      reference: PractitionerRole/phuongdt
                    recipient:
                      - reference: PractitionerRole/thucdv
                    payload:
                      - contentString: 術後心律規則、竇性 148 次/分，無心律不整。建議 Milrinon 維持 0.5 µg/kg/分至明晨再評估；Adrenalin 可逐步減量。
        '403':
          description: |
            已認證但無權（角色限制；寫入時病人不在照護範圍；照會醫師讀取沒有照會單的病人）。

            **不因無權而回 404**——權限問題一律 403，資源不存在才 404。
            但搜尋是例外：一律回較少的結果而非 403，避免探測病人是否存在。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 照會醫師建立必要溝通
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: forbidden
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: CONSULT-READ-ONLY
                        diagnostics: 照會醫師僅能回覆照會，不可建立必要溝通。
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 回覆沒指向照會單
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: VALUE-INVALID
                        diagnostics: 照會回覆必須指向一張照會單（ServiceRequest，category = consultation）。
                        expression:
                          - Communication.basedOn
  /Communication/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags:
        - 診斷與溝通
      summary: 讀取一則溝通
      operationId: readCommunication
      responses:
        '200':
          description: OK
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Communication'
              examples:
                example:
                  summary: 一則溝通
                  value:
                    resourceType: Communication
                    id: comm-p1-reply
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T07:05:00+07:00'
                    status: completed
                    category:
                      - coding:
                          - system: http://icu.emr.local/CodeSystem/communication-category
                            code: consult-reply
                    priority: urgent
                    basedOn:
                      - reference: ServiceRequest/sr-p1-consult
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    sent: '2026-06-17T07:05:00+07:00'
                    sender:
                      reference: PractitionerRole/phuongdt
                    recipient:
                      - reference: PractitionerRole/thucdv
                    payload:
                      - contentString: 術後心律規則、竇性 148 次/分，無心律不整。建議 Milrinon 維持 0.5 µg/kg/分至明晨再評估；Adrenalin 可逐步減量。
        '404':
          description: 資源不存在
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 資源不存在
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: not-found
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: NOT-FOUND
                        diagnostics: 找不到 Communication。請確認識別碼；若為權限問題會回 403 而非 404。
  /List:
    get:
      tags:
        - 目錄
      summary: 搜尋常用清單（個人常用／科常用）
      operationId: searchList
      parameters:
        - name: code
          in: query
          schema:
            type: string
            enum:
              - favorites-personal
              - favorites-dept
        - name: source
          in: query
          schema:
            type: string
          description: PractitionerRole/{id}：個人常用的主人
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 個人常用與科常用
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 2
                    link:
                      - relation: self
                        url: https://icu.emr.local/fhir/r4/List?status=current
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/List/list-fav-thucdv
                        resource:
                          resourceType: List
                          id: list-fav-thucdv
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:42:00+07:00'
                          status: current
                          mode: working
                          title: 個人常用（thucdv）
                          code:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/list-code
                                code: favorites-personal
                          source:
                            reference: PractitionerRole/thucdv
                          entry:
                            - item:
                                identifier:
                                  system: http://icu.emr.local/CodeSystem/his-medication
                                  value: '33795'
                                display: Meropenem
                            - item:
                                identifier:
                                  system: http://icu.emr.local/CodeSystem/his-medication
                                  value: '27841'
                                display: Voxin (Vancomycin)
                            - item:
                                identifier:
                                  system: http://icu.emr.local/CodeSystem/his-medication
                                  value: '33809'
                                display: Paracetamol
                            - item:
                                identifier:
                                  system: http://icu.emr.local/CodeSystem/his-service
                                  value: '1020'
                                display: 全血球計數
                        search:
                          mode: match
                      - fullUrl: https://icu.emr.local/fhir/r4/List/list-fav-picu
                        resource:
                          resourceType: List
                          id: list-fav-picu
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:42:00+07:00'
                          status: current
                          mode: working
                          title: 科常用（心臟外科加護）
                          code:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/list-code
                                code: favorites-dept
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/department
                              valueCode: picu
                          entry:
                            - item:
                                identifier:
                                  system: http://icu.emr.local/CodeSystem/his-medication
                                  value: '33795'
                                display: Meropenem
                            - item:
                                identifier:
                                  system: http://icu.emr.local/CodeSystem/his-medication
                                  value: '40903'
                                display: Sun-nicar (Nicardipin)
                            - item:
                                identifier:
                                  system: http://icu.emr.local/CodeSystem/his-service
                                  value: '646'
                                display: 血液電解質
                            - item:
                                identifier:
                                  system: http://icu.emr.local/CodeSystem/his-service
                                  value: '537'
                                display: 血氣
                            - item:
                                identifier:
                                  system: http://icu.emr.local/CodeSystem/his-service
                                  value: '11352'
                                display: CRP
                        search:
                          mode: match
    post:
      tags:
        - 目錄
      summary: 建立常用清單
      operationId: createList
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/List'
            examples:
              example:
                summary: 建立個人常用
                value:
                  resourceType: List
                  status: current
                  mode: working
                  title: 個人常用（thucdv）
                  code:
                    coding:
                      - system: http://icu.emr.local/CodeSystem/list-code
                        code: favorites-personal
                  entry:
                    - item:
                        identifier:
                          system: http://icu.emr.local/CodeSystem/his-medication
                          value: '33795'
                        display: Meropenem
                    - item:
                        identifier:
                          system: http://icu.emr.local/CodeSystem/his-medication
                          value: '27841'
                        display: Voxin (Vancomycin)
                    - item:
                        identifier:
                          system: http://icu.emr.local/CodeSystem/his-medication
                          value: '33809'
                        display: Paracetamol
                    - item:
                        identifier:
                          system: http://icu.emr.local/CodeSystem/his-service
                          value: '1020'
                        display: 全血球計數
      responses:
        '201':
          description: 已建立
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 建立
                  value:
                    resourceType: List
                    id: list-fav-thucdv
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T07:42:00+07:00'
                    status: current
                    mode: working
                    title: 個人常用（thucdv）
                    code:
                      coding:
                        - system: http://icu.emr.local/CodeSystem/list-code
                          code: favorites-personal
                    source:
                      reference: PractitionerRole/thucdv
                    entry:
                      - item:
                          identifier:
                            system: http://icu.emr.local/CodeSystem/his-medication
                            value: '33795'
                          display: Meropenem
                      - item:
                          identifier:
                            system: http://icu.emr.local/CodeSystem/his-medication
                            value: '27841'
                          display: Voxin (Vancomycin)
                      - item:
                          identifier:
                            system: http://icu.emr.local/CodeSystem/his-medication
                            value: '33809'
                          display: Paracetamol
                      - item:
                          identifier:
                            system: http://icu.emr.local/CodeSystem/his-service
                            value: '1020'
                          display: 全血球計數
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 品項不在目錄
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: CODE-REQUIRED
                        diagnostics: 目錄 his-medication 裡沒有 99999。
                        expression:
                          - List.entry[0].item
  /List/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags:
        - 目錄
      summary: 讀取常用清單
      operationId: readList
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/List'
              examples:
                example:
                  summary: 常用清單
                  value:
                    resourceType: List
                    id: list-fav-thucdv
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T07:42:00+07:00'
                    status: current
                    mode: working
                    title: 個人常用（thucdv）
                    code:
                      coding:
                        - system: http://icu.emr.local/CodeSystem/list-code
                          code: favorites-personal
                    source:
                      reference: PractitionerRole/thucdv
                    entry:
                      - item:
                          identifier:
                            system: http://icu.emr.local/CodeSystem/his-medication
                            value: '33795'
                          display: Meropenem
                      - item:
                          identifier:
                            system: http://icu.emr.local/CodeSystem/his-medication
                            value: '27841'
                          display: Voxin (Vancomycin)
                      - item:
                          identifier:
                            system: http://icu.emr.local/CodeSystem/his-medication
                            value: '33809'
                          display: Paracetamol
                      - item:
                          identifier:
                            system: http://icu.emr.local/CodeSystem/his-service
                            value: '1020'
                          display: 全血球計數
        '404':
          description: 資源不存在
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 資源不存在
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: not-found
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: NOT-FOUND
                        diagnostics: 找不到 List。請確認識別碼；若為權限問題會回 403 而非 404。
    put:
      tags:
        - 目錄
      summary: 加入／移除常用（整份 List 送回；個人常用只有主人能改）
      operationId: updateList
      parameters:
        - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/List'
            examples:
              example:
                summary: 加入一項常用（整份送回）
                value:
                  resourceType: List
                  id: list-fav-thucdv
                  meta:
                    versionId: '1'
                    lastUpdated: '2026-06-17T07:42:00+07:00'
                  status: current
                  mode: working
                  title: 個人常用（thucdv）
                  code:
                    coding:
                      - system: http://icu.emr.local/CodeSystem/list-code
                        code: favorites-personal
                  source:
                    reference: PractitionerRole/thucdv
                  entry:
                    - item:
                        identifier:
                          system: http://icu.emr.local/CodeSystem/his-medication
                          value: '33795'
                        display: Meropenem
                    - item:
                        identifier:
                          system: http://icu.emr.local/CodeSystem/his-medication
                          value: '27841'
                        display: Voxin (Vancomycin)
                    - item:
                        identifier:
                          system: http://icu.emr.local/CodeSystem/his-medication
                          value: '33809'
                        display: Paracetamol
                    - item:
                        identifier:
                          system: http://icu.emr.local/CodeSystem/his-service
                          value: '1020'
                        display: 全血球計數
                    - item:
                        identifier:
                          system: http://icu.emr.local/CodeSystem/his-service
                          value: '646'
                        display: 血液電解質
      responses:
        '200':
          description: OK
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/List'
              examples:
                example:
                  summary: 已更新
                  value:
                    resourceType: List
                    id: list-fav-thucdv
                    meta:
                      versionId: '2'
                      lastUpdated: '2026-06-17T09:00:00+07:00'
                    status: current
                    mode: working
                    title: 個人常用（thucdv）
                    code:
                      coding:
                        - system: http://icu.emr.local/CodeSystem/list-code
                          code: favorites-personal
                    source:
                      reference: PractitionerRole/thucdv
                    entry:
                      - item:
                          identifier:
                            system: http://icu.emr.local/CodeSystem/his-medication
                            value: '33795'
                          display: Meropenem
                      - item:
                          identifier:
                            system: http://icu.emr.local/CodeSystem/his-medication
                            value: '27841'
                          display: Voxin (Vancomycin)
                      - item:
                          identifier:
                            system: http://icu.emr.local/CodeSystem/his-medication
                            value: '33809'
                          display: Paracetamol
                      - item:
                          identifier:
                            system: http://icu.emr.local/CodeSystem/his-service
                            value: '1020'
                          display: 全血球計數
                      - item:
                          identifier:
                            system: http://icu.emr.local/CodeSystem/his-service
                            value: '646'
                          display: 血液電解質
        '403':
          description: |
            已認證但無權（角色限制；寫入時病人不在照護範圍；照會醫師讀取沒有照會單的病人）。

            **不因無權而回 404**——權限問題一律 403，資源不存在才 404。
            但搜尋是例外：一律回較少的結果而非 403，避免探測病人是否存在。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 改別人的個人常用
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: forbidden
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: ROLE-DOCTOR-ONLY
                        diagnostics: 只能修改自己的個人常用清單。
        '409':
          description: |
            版本衝突，或目前狀態不允許此操作。

            版本衝突時必須帶目前版本，讓客戶端就地合併——**內容不會被覆寫**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 版本落後
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: conflict
                        details:
                          text: currentVersionId=2
                        diagnostics: 資源已被其他工作階段更新至 versionId=2。請重新讀取後合併，內容未被覆寫。
        '412':
          description: 缺少 `If-Match` 標頭
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 缺 If-Match
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: PRECONDITION-REQUIRED
                        diagnostics: 缺少 If-Match 標頭。所有可寫互動都必須帶目前版本，不接受盲目覆寫。
  /PlanDefinition:
    get:
      tags:
        - 目錄
      summary: 搜尋套組／衛教組套（院方核准前 status = draft，唯讀）
      operationId: searchPlanDefinition
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum:
              - order-set
              - education-set
        - name: status
          in: query
          schema:
            type: string
        - name: title
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 套組與衛教組套（介面示例，draft）
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 2
                    link:
                      - relation: self
                        url: https://icu.emr.local/fhir/r4/PlanDefinition?status=draft
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/PlanDefinition/SET-DEMO-ICU-01
                        resource:
                          resourceType: PlanDefinition
                          id: SET-DEMO-ICU-01
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:00:00+07:00'
                          status: draft
                          type:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/plan-type
                                code: order-set
                          title: ICU 轉入基線檢驗（介面示例）
                          description: 逐項加入待開清單；每項可移除，各自簽署、送出、執行與回報。
                          action:
                            - title: 全血球計數
                              code:
                                - coding:
                                    - system: http://icu.emr.local/CodeSystem/his-service
                                      code: '1020'
                                      display: 全血球計數
                            - title: 血液電解質
                              code:
                                - coding:
                                    - system: http://icu.emr.local/CodeSystem/his-service
                                      code: '646'
                                      display: 血液電解質
                            - title: 血氣
                              code:
                                - coding:
                                    - system: http://icu.emr.local/CodeSystem/his-service
                                      code: '537'
                                      display: 血氣
                        search:
                          mode: match
                      - fullUrl: https://icu.emr.local/fhir/r4/PlanDefinition/EDU-SET-MED-01
                        resource:
                          resourceType: PlanDefinition
                          id: EDU-SET-MED-01
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:00:00+07:00'
                          status: draft
                          type:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/plan-type
                                code: education-set
                          title: 用藥與警訊
                          action:
                            - description: 已說明出院用藥需依正式處方上的藥名、劑量與頻率使用；若出現不適、疑似過敏或無法依計畫用藥，應依院方提供的聯絡方式尋求協助。
                        search:
                          mode: match
  /PlanDefinition/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags:
        - 目錄
      summary: 讀取套組（action[] 是目錄品項；展開到待開清單後每項仍各自簽署）
      operationId: readPlanDefinition
      responses:
        '200':
          description: OK
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/PlanDefinition'
              examples:
                example:
                  summary: 套組
                  value:
                    resourceType: PlanDefinition
                    id: SET-DEMO-ICU-01
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T07:00:00+07:00'
                    status: draft
                    type:
                      coding:
                        - system: http://icu.emr.local/CodeSystem/plan-type
                          code: order-set
                    title: ICU 轉入基線檢驗（介面示例）
                    description: 逐項加入待開清單；每項可移除，各自簽署、送出、執行與回報。
                    action:
                      - title: 全血球計數
                        code:
                          - coding:
                              - system: http://icu.emr.local/CodeSystem/his-service
                                code: '1020'
                                display: 全血球計數
                      - title: 血液電解質
                        code:
                          - coding:
                              - system: http://icu.emr.local/CodeSystem/his-service
                                code: '646'
                                display: 血液電解質
                      - title: 血氣
                        code:
                          - coding:
                              - system: http://icu.emr.local/CodeSystem/his-service
                                code: '537'
                                display: 血氣
        '404':
          description: 資源不存在
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 資源不存在
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: not-found
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: NOT-FOUND
                        diagnostics: 找不到 PlanDefinition。請確認識別碼；若為權限問題會回 403 而非 404。
  /MedicationRequest:
    get:
      tags:
        - 醫囑
      summary: 搜尋藥物醫囑
      operationId: searchMedicationRequest
      description: |
        建議搭配 `_revinclude=MedicationAdministration:request` 一次帶回執行紀錄，
        這正好是 eMAR 工作表的資料需求。
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/encounter'
        - name: status
          in: query
          schema:
            type: string
            enum:
              - draft
              - active
              - on-hold
              - cancelled
              - completed
              - stopped
              - entered-in-error
              - unknown
        - name: intent
          in: query
          schema:
            type: string
        - name: authoredon
          in: query
          schema:
            type: string
        - name: requester
          in: query
          schema:
            type: string
        - name: identifier
          in: query
          schema:
            type: string
          description: HIS 處方號或每行藥品碼
        - name: code
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/revinclude'
        - $ref: '#/components/parameters/include'
        - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: eMAR 工作表：作用中醫囑 ＋ 對應執行紀錄
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 1
                    link:
                      - relation: self
                        url: >-
                          https://icu.emr.local/fhir/r4/MedicationRequest?patient=Patient/p1&status=active&_revinclude=MedicationAdministration:request
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/MedicationRequest/mr-p1-mero
                        resource:
                          resourceType: MedicationRequest
                          id: mr-p1-mero
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-14T06:00:00+07:00'
                            source: 設計稿示範醫囑；品項未對應 B 目錄代碼
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/hisTransmissionStatus
                              valueCode: accepted
                            - url: http://icu.emr.local/StructureDefinition/hisTransmissionEvent
                              extension:
                                - url: sentAt
                                  valueInstant: '2026-06-14T06:00:00+07:00'
                                - url: respondedAt
                                  valueInstant: '2026-06-14T06:00:00+07:00'
                            - url: http://icu.emr.local/StructureDefinition/catalogSnapshot
                              extension:
                                - url: catalogVersion
                                  valueString: 20260617-tw
                            - url: http://icu.emr.local/StructureDefinition/signedAt
                              valueInstant: '2026-06-14T06:00:00+07:00'
                          identifier:
                            - system: http://icu.emr.local/CodeSystem/his-prescription-number
                              value: HP-mr-p1-mero
                          status: active
                          intent: order
                          category:
                            - coding:
                                - system: http://terminology.hl7.org/CodeSystem/medicationrequest-category
                                  code: inpatient
                          medicationCodeableConcept:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/his-medication
                                code: '33795'
                                display: Meropenem
                            text: Meropenem
                          subject:
                            reference: Patient/p1
                          encounter:
                            reference: Encounter/enc-p1
                          authoredOn: '2026-06-14T06:00:00+07:00'
                          requester:
                            reference: PractitionerRole/thucdv
                          dosageInstruction:
                            - text: 抗生素 · 靜脈 120′ · ×3 每 8h，靜脈注射，每 8 小時
                              timing:
                                repeat:
                                  frequency: 3
                                  period: 1
                                  periodUnit: d
                              route:
                                coding:
                                  - system: http://icu.emr.local/CodeSystem/his-route
                                    code: '996316'
                                    display: 靜脈注射
                                  - system: http://icu.emr.local/CodeSystem/tdl
                                    code: TDL.0401
                                text: 靜脈注射
                              doseAndRate:
                                - doseQuantity:
                                    value: 160
                                    unit: mg
                                    system: http://unitsofmeasure.org
                                    code: mg
                          dispenseRequest:
                            validityPeriod:
                              start: '2026-06-14T06:00:00+07:00'
                        search:
                          mode: match
                      - fullUrl: https://icu.emr.local/fhir/r4/MedicationAdministration/ma-mr-p3-oresol-1
                        resource:
                          resourceType: MedicationAdministration
                          id: ma-mr-p3-oresol-1
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:42:00+07:00'
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/verificationChecklist
                              extension:
                                - url: rightPatient
                                  valueBoolean: true
                                - url: rightMedication
                                  valueBoolean: true
                                - url: rightDose
                                  valueBoolean: true
                                - url: rightRoute
                                  valueBoolean: true
                                - url: rightTime
                                  valueBoolean: true
                          identifier:
                            - system: http://icu.emr.local/CodeSystem/occurrence-id
                              value: mr-p3-oresol-06:00
                          status: completed
                          medicationCodeableConcept:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/his-medication
                                code: '43513'
                                display: Oresol（補液）
                            text: Oresol（補液）
                          subject:
                            reference: Patient/p3
                          context:
                            reference: Encounter/enc-p3
                          effectiveDateTime: '2026-06-17T06:00:00+07:00'
                          performer:
                            - function:
                                coding:
                                  - system: http://terminology.hl7.org/CodeSystem/med-admin-perform-function
                                    code: performer
                              actor:
                                reference: PractitionerRole/nhungtt
                          request:
                            reference: MedicationRequest/mr-p3-oresol/_history/1
                          dosage:
                            text: 依體重
                            route:
                              coding:
                                - system: http://icu.emr.local/CodeSystem/his-route
                                  code: '913'
                                  display: 口服
                                - system: http://icu.emr.local/CodeSystem/tdl
                                  code: TDL.0401
                              text: 口服
                        search:
                          mode: include
    post:
      tags:
        - 醫囑
      summary: 開立藥物醫囑（草稿）
      operationId: createMedicationRequest
      description: |
        建立後為 `status=draft`、未簽署、`hisTransmissionStatus=notSent`。

        **必須通過的規則**

        | 規則 | 內容 |
        | --- | --- |
        | BR-AUTH-002 | 限主責醫師（照會醫師不可開立） |
        | BR-CTX-002 | 寫入時病人必須在操作者照護範圍內（讀取：醫護可讀全科，照會醫師限有照會單） |
        | BR-CTX-004 | 必須已確認本班照護名單 |
        | BR-ORD-001 | 必須指定病程來源（同病人、同作者、已存在的 Composition） |
        | BR-MED-001 | 藥品碼與給藥途徑必須帶 `coding.system` ＋ `code`，只給 `text` 拒絕 |
        | BR-CAT-001 | 停用品項不可用於新開立 |

        `requester` 一律取自存取權杖，客戶端送的值被忽略（BR-AUTH-006）。
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/MedicationRequest'
            examples:
              example:
                summary: 開立草稿（requester 由權杖決定，客戶端不必送）
                value:
                  resourceType: MedicationRequest
                  status: draft
                  intent: order
                  category:
                    - coding:
                        - system: http://terminology.hl7.org/CodeSystem/medicationrequest-category
                          code: inpatient
                  medicationCodeableConcept:
                    coding:
                      - system: http://icu.emr.local/CodeSystem/his-medication
                        code: '33795'
                        display: Meropenem 抗生素醫囑
                    text: Meropenem 抗生素醫囑
                  subject:
                    reference: Patient/p1
                  encounter:
                    reference: Encounter/enc-p1
                  dosageInstruction:
                    - text: 劑量依體重 7.2 kg · 每 8 小時
                  dispenseRequest:
                    validityPeriod:
                      start: '2026-06-17T07:30:00+07:00'
      responses:
        '201':
          description: 已建立
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 已建立：draft ＋ notSent ＋ 目錄快照
                  value:
                    resourceType: MedicationRequest
                    id: mr-p1-draft1
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T07:30:00+07:00'
                      source: 設計稿示範醫囑；品項未對應 B 目錄代碼
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/hisTransmissionStatus
                        valueCode: notSent
                      - url: http://icu.emr.local/StructureDefinition/catalogSnapshot
                        extension:
                          - url: catalogVersion
                            valueString: 20260617-tw
                    status: draft
                    intent: order
                    category:
                      - coding:
                          - system: http://terminology.hl7.org/CodeSystem/medicationrequest-category
                            code: inpatient
                    medicationCodeableConcept:
                      coding:
                        - system: http://icu.emr.local/CodeSystem/his-medication
                          code: '33795'
                          display: Meropenem 抗生素醫囑
                      text: Meropenem 抗生素醫囑
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    authoredOn: '2026-06-17T07:30:00+07:00'
                    requester:
                      reference: PractitionerRole/thucdv
                    dosageInstruction:
                      - text: 劑量依體重 7.2 kg · 每 8 小時
                    dispenseRequest:
                      validityPeriod:
                        start: '2026-06-17T07:30:00+07:00'
        '403':
          description: |
            已認證但無權（角色限制；寫入時病人不在照護範圍；照會醫師讀取沒有照會單的病人）。

            **不因無權而回 404**——權限問題一律 403，資源不存在才 404。
            但搜尋是例外：一律回較少的結果而非 403，避免探測病人是否存在。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 照會醫師不可開立
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: forbidden
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: CONSULT-READ-ONLY
                        diagnostics: 照會醫師僅能檢視與回覆照會，不可開立醫囑。
        '409':
          description: |
            版本衝突，或目前狀態不允許此操作。

            版本衝突時必須帶目前版本，讓客戶端就地合併——**內容不會被覆寫**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 尚未確認本班照護名單
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: business-rule
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: ROSTER-NOT-CONFIRMED
                        diagnostics: 請先確認本班照護名單，再開立醫囑。
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 只給品名、沒給代碼
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: CODE-REQUIRED
                        diagnostics: 藥品與給藥途徑必須自目錄選取（需代碼系統與代碼），不接受僅輸入品名。
                        expression:
                          - MedicationRequest.medicationCodeableConcept.coding
  /MedicationRequest/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags:
        - 醫囑
      summary: 讀取藥物醫囑
      operationId: readMedicationRequest
      responses:
        '200':
          description: 藥物醫囑
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/MedicationRequest'
              examples:
                active:
                  $ref: '#/components/examples/MedicationRequestActive'
        '404':
          description: 資源不存在
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 資源不存在
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: not-found
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: NOT-FOUND
                        diagnostics: 找不到 MedicationRequest。請確認識別碼；若為權限問題會回 403 而非 404。
    put:
      tags:
        - 醫囑
      summary: 更新藥物醫囑
      operationId: updateMedicationRequest
      description: |
        **可寫範圍取決於狀態（BR-ORD-006）**

        | 狀態 | 可改 | 不可改 |
        | --- | --- | --- |
        | `draft` 未簽 | 全部欄位 | — |
        | 已簽、未送出 | `status`（→ `cancelled`） | 藥品、劑量、途徑、頻次 |
        | 已送出 HIS | 無 | 全部 |
        | `active`（HIS 已接受） | `status`（→ `stopped`） | 其餘 |

        已送出的醫囑要改內容**必須取消再重開**——HIS 端 `hisPrescriptionNumber` 已產生，
        就地改會讓兩端不一致。
      parameters:
        - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/MedicationRequest'
            examples:
              example:
                summary: 草稿階段改劑量（整份送回，含 meta.versionId）
                value:
                  resourceType: MedicationRequest
                  id: mr-p1-draft1
                  meta:
                    versionId: '1'
                    lastUpdated: '2026-06-17T07:30:00+07:00'
                    source: 設計稿示範醫囑；品項未對應 B 目錄代碼
                  extension:
                    - url: http://icu.emr.local/StructureDefinition/hisTransmissionStatus
                      valueCode: notSent
                    - url: http://icu.emr.local/StructureDefinition/catalogSnapshot
                      extension:
                        - url: catalogVersion
                          valueString: 20260617-tw
                  status: draft
                  intent: order
                  category:
                    - coding:
                        - system: http://terminology.hl7.org/CodeSystem/medicationrequest-category
                          code: inpatient
                  medicationCodeableConcept:
                    coding:
                      - system: http://icu.emr.local/CodeSystem/his-medication
                        code: '33795'
                        display: Meropenem 抗生素醫囑
                    text: Meropenem 抗生素醫囑
                  subject:
                    reference: Patient/p1
                  encounter:
                    reference: Encounter/enc-p1
                  authoredOn: '2026-06-17T07:30:00+07:00'
                  requester:
                    reference: PractitionerRole/thucdv
                  dosageInstruction:
                    - text: 450 mg（1.5 錠），口服，BID（每日 2 次）
                      timing:
                        repeat:
                          frequency: 2
                          period: 1
                          periodUnit: d
                        code:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/tdl
                              code: TDL.1049
                              display: BID
                      route:
                        coding:
                          - system: http://icu.emr.local/CodeSystem/his-route
                            code: '913'
                            display: Uống
                          - system: http://icu.emr.local/CodeSystem/tdl
                            code: TDL.0401
                        text: Uống（口服）
                      doseAndRate:
                        - doseQuantity:
                            value: 450
                            unit: mg
                            system: http://unitsofmeasure.org
                            code: mg
                  dispenseRequest:
                    validityPeriod:
                      start: '2026-06-17T07:30:00+07:00'
      responses:
        '200':
          description: 已更新
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 已更新（ETag 進版）
                  value:
                    resourceType: MedicationRequest
                    id: mr-p1-draft1
                    meta:
                      versionId: '2'
                      lastUpdated: '2026-08-31T08:07:20+07:00'
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/hisTransmissionStatus
                        valueCode: notSent
                      - url: http://icu.emr.local/StructureDefinition/catalogSnapshot
                        extension:
                          - url: catalogVersion
                            valueString: 20260617-tw
                    status: draft
                    intent: order
                    category:
                      - coding:
                          - system: http://terminology.hl7.org/CodeSystem/medicationrequest-category
                            code: inpatient
                    medicationCodeableConcept:
                      coding:
                        - system: http://icu.emr.local/CodeSystem/his-medication
                          code: '33795'
                          display: Meropenem 抗生素醫囑
                      text: Meropenem 抗生素醫囑
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    authoredOn: '2026-06-17T07:30:00+07:00'
                    requester:
                      reference: PractitionerRole/thucdv
                    dosageInstruction:
                      - text: 450 mg（1.5 錠），口服，BID（每日 2 次）
                        timing:
                          repeat:
                            frequency: 2
                            period: 1
                            periodUnit: d
                          code:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/tdl
                                code: TDL.1049
                                display: BID
                        route:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/his-route
                              code: '913'
                              display: Uống
                            - system: http://icu.emr.local/CodeSystem/tdl
                              code: TDL.0401
                          text: Uống（口服）
                        doseAndRate:
                          - doseQuantity:
                              value: 450
                              unit: mg
                              system: http://unitsofmeasure.org
                              code: mg
                    dispenseRequest:
                      validityPeriod:
                        start: '2026-06-17T07:30:00+07:00'
        '409':
          description: |
            版本衝突，或目前狀態不允許此操作。

            版本衝突時必須帶目前版本，讓客戶端就地合併——**內容不會被覆寫**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 已送出 HIS，不可就地修改
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: conflict
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: ORDER-IMMUTABLE-AFTER-SUBMIT
                        diagnostics: 醫囑已送出 HIS，不可就地修改。請取消後重新開立。
        '412':
          description: 缺少 `If-Match` 標頭
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 缺 If-Match
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: PRECONDITION-REQUIRED
                        diagnostics: 缺少 If-Match 標頭。所有可寫互動都必須帶目前版本，不接受盲目覆寫。
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 停用品項
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: business-rule
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: CATALOG-INACTIVE
                        diagnostics: 該品項已停用，不可用於新開立。既有醫囑仍可檢視。
                        expression:
                          - MedicationRequest.medicationCodeableConcept.coding[0].code
    patch:
      tags:
        - 醫囑
      summary: 部分更新（JSON Patch）
      operationId: patchMedicationRequest
      description: 主要用途是標記 `entered-in-error`，或在允許的狀態下改 `status`。
      parameters:
        - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/JsonPatch'
            example:
              - op: replace
                path: /status
                value: entered-in-error
      responses:
        '200':
          description: 已更新
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 已標記為誤建（資源仍可讀，預設不出現在搜尋結果）
                  value:
                    resourceType: MedicationRequest
                    id: mr-p1-draft1
                    meta:
                      versionId: '4'
                      lastUpdated: '2026-08-31T11:20:08+07:00'
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/hisTransmissionStatus
                        valueCode: notSent
                      - url: http://icu.emr.local/StructureDefinition/catalogSnapshot
                        extension:
                          - url: catalogVersion
                            valueString: 20260617-tw
                    status: entered-in-error
                    intent: order
                    category:
                      - coding:
                          - system: http://terminology.hl7.org/CodeSystem/medicationrequest-category
                            code: inpatient
                    medicationCodeableConcept:
                      coding:
                        - system: http://icu.emr.local/CodeSystem/his-medication
                          code: '33795'
                          display: Meropenem 抗生素醫囑
                      text: Meropenem 抗生素醫囑
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    authoredOn: '2026-06-17T07:30:00+07:00'
                    requester:
                      reference: PractitionerRole/thucdv
                    dosageInstruction:
                      - text: 劑量依體重 7.2 kg · 每 8 小時
                    dispenseRequest:
                      validityPeriod:
                        start: '2026-06-17T07:30:00+07:00'
        '409':
          description: |
            版本衝突，或目前狀態不允許此操作。

            版本衝突時必須帶目前版本，讓客戶端就地合併——**內容不會被覆寫**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 版本落後
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: conflict
                        details:
                          text: currentVersionId=6
                        diagnostics: 資源已被其他工作階段更新至 versionId=6。請重新讀取後合併，內容未被覆寫。
        '412':
          description: 缺少 `If-Match` 標頭
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 缺 If-Match
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: PRECONDITION-REQUIRED
                        diagnostics: 缺少 If-Match 標頭。所有可寫互動都必須帶目前版本，不接受盲目覆寫。
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: patch 後的資源違反狀態規則
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: conflict
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: SIGNED-IMMUTABLE
                        diagnostics: 已簽署的醫囑不可改動內容，僅能變更狀態。
  /MedicationRequest/{id}/$sign:
    parameters:
      - $ref: '#/components/parameters/id'
    post:
      tags:
        - 醫囑
      summary: 簽署醫囑（模擬電子簽章）
      operationId: signMedicationRequest
      description: |
        原子完成三件事：

        1. 驗證病程來源存在且屬於同病人、同作者（BR-ORD-001）。
        2. 把病程來源的**當下版本**快照寫入 `supportingInformation`（帶版本 Reference，BR-ORD-003）。
        3. 建立 `Provenance.signature`。

        只能簽自己建立且尚未簽署的醫囑（BR-ORD-002）。
        簽署前重新驗證品項仍有效；已停用則回 `409 CATALOG-CHANGED`（BR-CAT-003）。
      parameters:
        - $ref: '#/components/parameters/ifMatch'
      responses:
        '200':
          description: 已簽署，回傳更新後的醫囑與新建的 Provenance
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 醫囑進版 ＋ 新建簽章 Provenance
                  value:
                    resourceType: Bundle
                    type: collection
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/MedicationRequest/mr-p1-draft1
                        resource:
                          resourceType: MedicationRequest
                          id: mr-p1-draft1
                          meta:
                            versionId: '2'
                            lastUpdated: '2026-06-17T08:06:40+07:00'
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/hisTransmissionStatus
                              valueCode: notSent
                            - url: http://icu.emr.local/StructureDefinition/catalogSnapshot
                              extension:
                                - url: catalogVersion
                                  valueString: 20260617-tw
                            - url: http://icu.emr.local/StructureDefinition/signedAt
                              valueInstant: '2026-06-17T08:06:40+07:00'
                          status: draft
                          intent: order
                          category:
                            - coding:
                                - system: http://terminology.hl7.org/CodeSystem/medicationrequest-category
                                  code: inpatient
                          medicationCodeableConcept:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/his-medication
                                code: '33795'
                                display: Meropenem 抗生素醫囑
                            text: Meropenem 抗生素醫囑
                          subject:
                            reference: Patient/p1
                          encounter:
                            reference: Encounter/enc-p1
                          authoredOn: '2026-06-17T07:30:00+07:00'
                          requester:
                            reference: PractitionerRole/thucdv
                          dosageInstruction:
                            - text: 劑量依體重 7.2 kg · 每 8 小時
                          dispenseRequest:
                            validityPeriod:
                              start: '2026-06-17T07:30:00+07:00'
                      - fullUrl: https://icu.emr.local/fhir/r4/Provenance/prov-sign-mr-p1-mero
                        resource:
                          resourceType: Provenance
                          id: prov-sign-mr-p1-mero
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-14T06:00:00+07:00'
                          target:
                            - reference: MedicationRequest/mr-p1-mero/_history/1
                          recorded: '2026-06-14T06:00:00+07:00'
                          activity:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/provenance-activity
                                code: sign
                          agent:
                            - type:
                                coding:
                                  - system: http://terminology.hl7.org/CodeSystem/provenance-participant-type
                                    code: author
                              who:
                                reference: PractitionerRole/thucdv
                          signature:
                            - type:
                                - system: urn:iso-astm:E1762-95:2013
                                  code: 1.2.840.10065.1.12.1.1
                                  display: Author's Signature
                              when: '2026-06-14T06:00:00+07:00'
                              who:
                                reference: PractitionerRole/thucdv
                              targetFormat: application/fhir+json
                              sigFormat: application/jose
                              data: dGh1Y2R2fG1yLXAxLW1lcm98MQ==
        '403':
          description: |
            已認證但無權（角色限制；寫入時病人不在照護範圍；照會醫師讀取沒有照會單的病人）。

            **不因無權而回 404**——權限問題一律 403，資源不存在才 404。
            但搜尋是例外：一律回較少的結果而非 403，避免探測病人是否存在。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 只能簽自己的草稿
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: forbidden
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: SIGN-OWN-DRAFT-ONLY
                        diagnostics: 僅能簽署自己建立且尚未簽署的醫囑。
        '409':
          description: |
            版本衝突，或目前狀態不允許此操作。

            版本衝突時必須帶目前版本，讓客戶端就地合併——**內容不會被覆寫**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 簽署前重驗，品項已停用
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: conflict
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: CATALOG-CHANGED
                        diagnostics: 品項自開立後已變更或停用，請重新確認後再簽署。
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 沒有病程來源
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: PROGRESS-NOTE-REQUIRED
                        diagnostics: 簽署前必須指定病程來源（同病人、同作者）。
                        expression:
                          - MedicationRequest.supportingInformation
  /MedicationRequest/{id}/$submit:
    parameters:
      - $ref: '#/components/parameters/id'
    post:
      tags:
        - 醫囑
      summary: 送出至 HIS
      operationId: submitMedicationRequest
      description: |
        產生 `PrescriptionCreated` 事件並設 `hisTransmissionStatus=sent`。**冪等**：
        同一資源同一版本重送會回傳首次結果，不重打 HIS。

        **僅接受「已簽署且 `notSent`」**（BR-ORD-004）。

        ### 送出前阻擋條件（回 422，醫囑維持已簽未送）

        | 編號 | 條件 | 錯誤碼 |
        | --- | --- | --- |
        | BR-INT-001 | 病程來源為空 | `PROGRESS-NOTE-REQUIRED` |
        | BR-INT-002 | 缺 `dispenseStockCode` 對照 | `DISPENSE-STOCK-UNMAPPED` |
        | BR-INT-003 | `medicationConsultationRequest` 為 null（三態未解析） | `TRISTATE-NOT-RESOLVED` |
        | BR-INT-005 | 四時段單位不一致 | `DOSE-UNIT-INCONSISTENT` |
        | BR-INT-006 | `archiveId` 非本次就醫的當前值 | `ARCHIVE-ID-STALE` |

        ### `hisTransmissionStatus = unknown` 時禁止重送

        回 `409 RESEND-BLOCKED-UNKNOWN`。必須由人確認 HIS 端的實際結果，
        自動重送可能造成重複處方（BR-ORD-007）。
      parameters:
        - $ref: '#/components/parameters/ifMatch'
      responses:
        '200':
          description: 已送出並取得 HIS 回應
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/MedicationRequest'
              examples:
                example:
                  summary: 已送出，HIS 回處方號
                  value:
                    resourceType: MedicationRequest
                    id: mr-p1-mero
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-14T06:00:00+07:00'
                      source: 設計稿示範醫囑；品項未對應 B 目錄代碼
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/hisTransmissionStatus
                        valueCode: accepted
                      - url: http://icu.emr.local/StructureDefinition/hisTransmissionEvent
                        extension:
                          - url: sentAt
                            valueInstant: '2026-06-14T06:00:00+07:00'
                          - url: respondedAt
                            valueInstant: '2026-06-14T06:00:00+07:00'
                      - url: http://icu.emr.local/StructureDefinition/catalogSnapshot
                        extension:
                          - url: catalogVersion
                            valueString: 20260617-tw
                      - url: http://icu.emr.local/StructureDefinition/signedAt
                        valueInstant: '2026-06-14T06:00:00+07:00'
                    identifier:
                      - system: http://icu.emr.local/CodeSystem/his-prescription-number
                        value: HP-mr-p1-mero
                    status: active
                    intent: order
                    category:
                      - coding:
                          - system: http://terminology.hl7.org/CodeSystem/medicationrequest-category
                            code: inpatient
                    medicationCodeableConcept:
                      coding:
                        - system: http://icu.emr.local/CodeSystem/his-medication
                          code: '33795'
                          display: Meropenem
                      text: Meropenem
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    authoredOn: '2026-06-14T06:00:00+07:00'
                    requester:
                      reference: PractitionerRole/thucdv
                    dosageInstruction:
                      - text: 抗生素 · 靜脈 120′ · ×3 每 8h，靜脈注射，每 8 小時
                        timing:
                          repeat:
                            frequency: 3
                            period: 1
                            periodUnit: d
                        route:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/his-route
                              code: '996316'
                              display: 靜脈注射
                            - system: http://icu.emr.local/CodeSystem/tdl
                              code: TDL.0401
                          text: 靜脈注射
                        doseAndRate:
                          - doseQuantity:
                              value: 160
                              unit: mg
                              system: http://unitsofmeasure.org
                              code: mg
                    dispenseRequest:
                      validityPeriod:
                        start: '2026-06-14T06:00:00+07:00'
        '409':
          description: 狀態不允許送出，或 `unknown` 狀態禁止重送
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              example:
                resourceType: OperationOutcome
                issue:
                  - severity: error
                    code: business-rule
                    details:
                      coding:
                        - system: http://icu.emr.local/CodeSystem/api-error
                          code: RESEND-BLOCKED-UNKNOWN
                    diagnostics: 介接回應未知，結果無法確認。請先查明原送出請求，不可重送。
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 送出前阻擋（醫囑維持已簽未送）
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: business-rule
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: TRISTATE-NOT-RESOLVED
                        diagnostics: 藥事諮詢欄位為未解析狀態，送出前必須由人選定是或否。
                        expression:
                          - MedicationRequest.extension
        '502':
          description: HIS 不可用
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: HIS 不可用
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: transient
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: HIS-UNAVAILABLE
                        diagnostics: HIS 目前無法連線，醫囑已保存為已簽未送。請稍後重送。
        '504':
          description: |
            HIS 逾時。本地醫囑仍持久化為已送出，`hisTransmissionStatus=unknown`，
            並產生人工查明 Task。**之後禁止自動重送。**
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: HIS 逾時 → 進入 unknown，禁止自動重送
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: timeout
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: HIS-TIMEOUT
                        diagnostics: HIS 逾時未回應，結果未知。已建立人工查明工作，請勿重送。
  /ServiceRequest:
    get:
      tags:
        - 醫囑
      summary: 搜尋醫令（檢驗／檢查／照護／跨科照會）
      operationId: searchServiceRequest
      description: 跨科照會也是 ServiceRequest，以 `category=consultation` 區分。
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/encounter'
        - name: status
          in: query
          schema:
            type: string
        - name: category
          in: query
          schema:
            type: string
        - name: code
          in: query
          schema:
            type: string
        - name: priority
          in: query
          schema:
            type: string
            enum:
              - routine
              - urgent
              - asap
              - stat
        - name: performer
          in: query
          schema:
            type: string
        - name: identifier
          in: query
          schema:
            type: string
          description: HIS 需求單號或詳細行碼
        - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 本次就醫的檢驗醫令
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 1
                    link:
                      - relation: self
                        url: >-
                          https://icu.emr.local/fhir/r4/ServiceRequest?patient=Patient/p1&status=active&category=laboratory
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/ServiceRequest/sr-p1-cbc
                        resource:
                          resourceType: ServiceRequest
                          id: sr-p1-cbc
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T06:00:00+07:00'
                            source: 設計稿示範檢驗；未對應 B 目錄代碼
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/hisTransmissionStatus
                              valueCode: accepted
                          identifier:
                            - system: http://icu.emr.local/CodeSystem/order-number
                              value: CD-sr-p1-cbc
                          status: completed
                          intent: order
                          priority: routine
                          category:
                            - coding:
                                - system: http://icu.emr.local/CodeSystem/service-category
                                  code: laboratory
                                  display: 檢驗
                              text: 檢驗
                          code:
                            coding:
                              - code: CBC
                                display: 全血球計數
                            text: 全血球計數
                          subject:
                            reference: Patient/p1
                          encounter:
                            reference: Encounter/enc-p1
                          quantityInteger: 1
                          occurrencePeriod:
                            start: '2026-06-17T06:00:00+07:00'
                          authoredOn: '2026-06-17T06:00:00+07:00'
                          requester:
                            reference: PractitionerRole/thucdv
                        search:
                          mode: match
    post:
      tags:
        - 醫囑
      summary: 開立醫令
      operationId: createServiceRequest
      description: |
        規則同藥物醫囑（BR-AUTH-002、BR-CTX-002/004、BR-ORD-001、BR-CAT-001）。

        **`priority` 值域衝突（未決事項 Q-05）**：HIS 建立用 `severity` 1 正常／2 急／3 特急，
        修改介面則無值域，兩者不能直接互換。EMR 內部一律用 FHIR `priority`，
        由整合層對映；**修改時不送 priority**。
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/ServiceRequest'
            examples:
              example:
                summary: 開立 CBC（草稿）
                value:
                  resourceType: ServiceRequest
                  status: draft
                  intent: order
                  priority: routine
                  category:
                    - coding:
                        - system: http://icu.emr.local/CodeSystem/service-category
                          code: laboratory
                          display: 檢驗
                      text: 檢驗
                  code:
                    coding:
                      - code: CBC
                        display: 全血球計數
                    text: 全血球計數
                  subject:
                    reference: Patient/p1
                  encounter:
                    reference: Encounter/enc-p1
                  quantityInteger: 1
                  occurrencePeriod:
                    start: '2026-06-17T06:00:00+07:00'
      responses:
        '201':
          description: 已建立
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 已建立
                  value:
                    resourceType: ServiceRequest
                    id: sr-p1-cbc
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-08-31T07:30:12+07:00'
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/hisTransmissionStatus
                        valueCode: notSent
                    status: draft
                    intent: order
                    priority: routine
                    category:
                      - coding:
                          - system: http://icu.emr.local/CodeSystem/service-category
                            code: laboratory
                            display: 檢驗
                        text: 檢驗
                    code:
                      coding:
                        - code: CBC
                          display: 全血球計數
                      text: 全血球計數
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    quantityInteger: 1
                    occurrencePeriod:
                      start: '2026-06-17T06:00:00+07:00'
                    authoredOn: '2026-06-17T06:00:00+07:00'
                    requester:
                      reference: PractitionerRole/thucdv
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 缺服務代碼
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: CODE-REQUIRED
                        diagnostics: 檢查項目必須自目錄選取（需代碼系統與代碼）。
                        expression:
                          - ServiceRequest.code.coding
  /ServiceRequest/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags:
        - 醫囑
      summary: 讀取醫令
      operationId: readServiceRequest
      responses:
        '200':
          description: 醫令
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/ServiceRequest'
              examples:
                example:
                  summary: 已送出並被 HIS 接受的醫令
                  value:
                    resourceType: ServiceRequest
                    id: sr-p1-cbc
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T06:00:00+07:00'
                      source: 設計稿示範檢驗；未對應 B 目錄代碼
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/hisTransmissionStatus
                        valueCode: accepted
                    identifier:
                      - system: http://icu.emr.local/CodeSystem/order-number
                        value: CD-sr-p1-cbc
                    status: completed
                    intent: order
                    priority: routine
                    category:
                      - coding:
                          - system: http://icu.emr.local/CodeSystem/service-category
                            code: laboratory
                            display: 檢驗
                        text: 檢驗
                    code:
                      coding:
                        - code: CBC
                          display: 全血球計數
                      text: 全血球計數
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    quantityInteger: 1
                    occurrencePeriod:
                      start: '2026-06-17T06:00:00+07:00'
                    authoredOn: '2026-06-17T06:00:00+07:00'
                    requester:
                      reference: PractitionerRole/thucdv
        '404':
          description: 資源不存在
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 資源不存在
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: not-found
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: NOT-FOUND
                        diagnostics: 找不到 ServiceRequest。請確認識別碼；若為權限問題會回 403 而非 404。
    put:
      tags:
        - 醫囑
      summary: 更新醫令
      operationId: updateServiceRequest
      description: |
        送 HIS 的 `ServiceRequestUpdated` 有兩種語義，取決於是否帶舊詳細行碼：

        | 帶不帶 `serviceRequestNumber` | HIS 行為 | FHIR 表達 |
        | --- | --- | --- |
        | 帶舊詳細行碼 | HIS 取消舊服務並新增新服務 | 舊筆 `status=revoked`，新建一筆 `replaces` 舊的 |
        | 不帶 | 純新增 | 新建 ServiceRequest |
      parameters:
        - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/ServiceRequest'
            examples:
              example:
                summary: 改優先度（修改時不送 priority 給 HIS，見 Q-05）
                value:
                  resourceType: ServiceRequest
                  id: sr-p1-cbc
                  meta:
                    versionId: '1'
                    lastUpdated: '2026-06-17T06:00:00+07:00'
                    source: 設計稿示範檢驗；未對應 B 目錄代碼
                  extension:
                    - url: http://icu.emr.local/StructureDefinition/hisTransmissionStatus
                      valueCode: accepted
                  identifier:
                    - system: http://icu.emr.local/CodeSystem/order-number
                      value: CD-sr-p1-cbc
                  status: completed
                  intent: order
                  priority: stat
                  category:
                    - coding:
                        - system: http://icu.emr.local/CodeSystem/service-category
                          code: laboratory
                          display: 檢驗
                      text: 檢驗
                  code:
                    coding:
                      - code: CBC
                        display: 全血球計數
                    text: 全血球計數
                  subject:
                    reference: Patient/p1
                  encounter:
                    reference: Encounter/enc-p1
                  quantityInteger: 1
                  occurrencePeriod:
                    start: '2026-06-17T06:00:00+07:00'
                  authoredOn: '2026-06-17T06:00:00+07:00'
                  requester:
                    reference: PractitionerRole/thucdv
      responses:
        '200':
          description: 已更新
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 已更新
                  value:
                    resourceType: ServiceRequest
                    id: sr-p1-cbc
                    meta:
                      versionId: '3'
                      lastUpdated: '2026-08-31T07:45:02+07:00'
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/hisTransmissionStatus
                        valueCode: accepted
                    identifier:
                      - system: http://icu.emr.local/CodeSystem/order-number
                        value: CD-sr-p1-cbc
                    status: completed
                    intent: order
                    priority: stat
                    category:
                      - coding:
                          - system: http://icu.emr.local/CodeSystem/service-category
                            code: laboratory
                            display: 檢驗
                        text: 檢驗
                    code:
                      coding:
                        - code: CBC
                          display: 全血球計數
                      text: 全血球計數
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    quantityInteger: 1
                    occurrencePeriod:
                      start: '2026-06-17T06:00:00+07:00'
                    authoredOn: '2026-06-17T06:00:00+07:00'
                    requester:
                      reference: PractitionerRole/thucdv
        '409':
          description: |
            版本衝突，或目前狀態不允許此操作。

            版本衝突時必須帶目前版本，讓客戶端就地合併——**內容不會被覆寫**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 版本落後
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: conflict
                        details:
                          text: currentVersionId=4
                        diagnostics: 資源已被其他工作階段更新至 versionId=4。請重新讀取後合併，內容未被覆寫。
        '412':
          description: 缺少 `If-Match` 標頭
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 缺 If-Match
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: PRECONDITION-REQUIRED
                        diagnostics: 缺少 If-Match 標頭。所有可寫互動都必須帶目前版本，不接受盲目覆寫。
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 報告已回，不可改醫令
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: conflict
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: ORDER-IMMUTABLE-AFTER-SUBMIT
                        diagnostics: 該醫令已有檢驗結果回報，不可修改。如需重驗請另開醫令。
  /MedicationAdministration:
    get:
      tags:
        - 實際執行
      summary: 搜尋給藥執行紀錄
      operationId: searchMedicationAdministration
      parameters:
        - $ref: '#/components/parameters/patient'
        - name: request
          in: query
          schema:
            type: string
          description: 來源醫囑
        - name: status
          in: query
          schema:
            type: string
            enum:
              - in-progress
              - not-done
              - on-hold
              - completed
              - entered-in-error
              - stopped
              - unknown
        - name: effective-time
          in: query
          schema:
            type: string
        - name: performer
          in: query
          schema:
            type: string
        - name: identifier
          in: query
          schema:
            type: string
          description: 劑次識別碼
        - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 本班已完成的給藥
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 1
                    link:
                      - relation: self
                        url: >-
                          https://icu.emr.local/fhir/r4/MedicationAdministration?patient=Patient/p1&effective-time=ge2026-08-31T07:00:00%2B07:00&effective-time=le2026-08-31T19:00:00%2B07:00
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/MedicationAdministration/ma-mr-p3-oresol-1
                        resource:
                          resourceType: MedicationAdministration
                          id: ma-mr-p3-oresol-1
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:42:00+07:00'
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/verificationChecklist
                              extension:
                                - url: rightPatient
                                  valueBoolean: true
                                - url: rightMedication
                                  valueBoolean: true
                                - url: rightDose
                                  valueBoolean: true
                                - url: rightRoute
                                  valueBoolean: true
                                - url: rightTime
                                  valueBoolean: true
                          identifier:
                            - system: http://icu.emr.local/CodeSystem/occurrence-id
                              value: mr-p3-oresol-06:00
                          status: completed
                          medicationCodeableConcept:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/his-medication
                                code: '43513'
                                display: Oresol（補液）
                            text: Oresol（補液）
                          subject:
                            reference: Patient/p3
                          context:
                            reference: Encounter/enc-p3
                          effectiveDateTime: '2026-06-17T06:00:00+07:00'
                          performer:
                            - function:
                                coding:
                                  - system: http://terminology.hl7.org/CodeSystem/med-admin-perform-function
                                    code: performer
                              actor:
                                reference: PractitionerRole/nhungtt
                          request:
                            reference: MedicationRequest/mr-p3-oresol/_history/1
                          dosage:
                            text: 依體重
                            route:
                              coding:
                                - system: http://icu.emr.local/CodeSystem/his-route
                                  code: '913'
                                  display: 口服
                                - system: http://icu.emr.local/CodeSystem/tdl
                                  code: TDL.0401
                              text: 口服
                        search:
                          mode: match
    post:
      tags:
        - 實際執行
      summary: 記錄給藥執行
      operationId: createMedicationAdministration
      description: |
        **建立後不可修改。** 誤建以 `entered-in-error` 標記後重建。

        ### 必須通過的規則

        | 規則 | 內容 |
        | --- | --- |
        | BR-AUTH-004 | 限護理師 |
        | BR-MED-002 | 來源醫囑必須 `status=active` **且** `hisTransmissionStatus=accepted` |
        | BR-MED-003 | `completed` 時五對核對必須**全部** `true`，不可由單次掃碼推定 |
        | BR-MED-004 | 實際值與醫囑不同、或狀態非 `completed` 時，原因必填 |
        | BR-MED-005 | 同一劑次至多一筆 `completed` |
        | BR-MED-006 | 實際時間必須落在該醫囑版本有效期間 `[start, end)` |
        | BR-MED-007 | `completed` 時實際劑量與途徑必填，不得以醫囑預定值當事實 |

        ### 劑次唯一性用條件式建立

        帶 `If-None-Exist`；已存在同劑次完成紀錄時回 **`200`**（回傳既有資源）而非 `201`。
        比「先查再寫」安全：不會有兩個護理師同時通過檢查的競態。
      parameters:
        - $ref: '#/components/parameters/ifNoneExist'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/MedicationAdministration'
            examples:
              completed:
                $ref: '#/components/examples/MedicationAdministrationCompleted'
      responses:
        '200':
          description: 本劑次已有完成紀錄，回傳既有資源（`DOSE-ALREADY-ADMINISTERED`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/MedicationAdministration'
              examples:
                example:
                  summary: 同劑次已存在（條件式建立命中）→ 回既有資源，不重複建立
                  value:
                    resourceType: MedicationAdministration
                    id: ma-mr-p3-oresol-1
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T07:42:00+07:00'
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/verificationChecklist
                        extension:
                          - url: rightPatient
                            valueBoolean: true
                          - url: rightMedication
                            valueBoolean: true
                          - url: rightDose
                            valueBoolean: true
                          - url: rightRoute
                            valueBoolean: true
                          - url: rightTime
                            valueBoolean: true
                    identifier:
                      - system: http://icu.emr.local/CodeSystem/occurrence-id
                        value: mr-p3-oresol-06:00
                    status: completed
                    medicationCodeableConcept:
                      coding:
                        - system: http://icu.emr.local/CodeSystem/his-medication
                          code: '43513'
                          display: Oresol（補液）
                      text: Oresol（補液）
                    subject:
                      reference: Patient/p3
                    context:
                      reference: Encounter/enc-p3
                    effectiveDateTime: '2026-06-17T06:00:00+07:00'
                    performer:
                      - function:
                          coding:
                            - system: http://terminology.hl7.org/CodeSystem/med-admin-perform-function
                              code: performer
                        actor:
                          reference: PractitionerRole/nhungtt
                    request:
                      reference: MedicationRequest/mr-p3-oresol/_history/1
                    dosage:
                      text: 依體重
                      route:
                        coding:
                          - system: http://icu.emr.local/CodeSystem/his-route
                            code: '913'
                            display: 口服
                          - system: http://icu.emr.local/CodeSystem/tdl
                            code: TDL.0401
                        text: 口服
        '201':
          description: 已建立
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 已記錄
                  value:
                    resourceType: MedicationAdministration
                    id: ma-mr-p3-oresol-1
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T07:42:00+07:00'
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/verificationChecklist
                        extension:
                          - url: rightPatient
                            valueBoolean: true
                          - url: rightMedication
                            valueBoolean: true
                          - url: rightDose
                            valueBoolean: true
                          - url: rightRoute
                            valueBoolean: true
                          - url: rightTime
                            valueBoolean: true
                    identifier:
                      - system: http://icu.emr.local/CodeSystem/occurrence-id
                        value: mr-p3-oresol-06:00
                    status: completed
                    medicationCodeableConcept:
                      coding:
                        - system: http://icu.emr.local/CodeSystem/his-medication
                          code: '43513'
                          display: Oresol（補液）
                      text: Oresol（補液）
                    subject:
                      reference: Patient/p3
                    context:
                      reference: Encounter/enc-p3
                    effectiveDateTime: '2026-06-17T06:00:00+07:00'
                    performer:
                      - function:
                          coding:
                            - system: http://terminology.hl7.org/CodeSystem/med-admin-perform-function
                              code: performer
                        actor:
                          reference: PractitionerRole/nhungtt
                    request:
                      reference: MedicationRequest/mr-p3-oresol/_history/1
                    dosage:
                      text: 依體重
                      route:
                        coding:
                          - system: http://icu.emr.local/CodeSystem/his-route
                            code: '913'
                            display: 口服
                          - system: http://icu.emr.local/CodeSystem/tdl
                            code: TDL.0401
                        text: 口服
        '403':
          description: |
            已認證但無權（角色限制；寫入時病人不在照護範圍；照會醫師讀取沒有照會單的病人）。

            **不因無權而回 404**——權限問題一律 403，資源不存在才 404。
            但搜尋是例外：一律回較少的結果而非 403，避免探測病人是否存在。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 非護理師角色
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: forbidden
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: ROLE-NURSE-ONLY
                        diagnostics: 給藥執行僅限護理師記錄。
        '409':
          description: 來源醫囑不在可執行狀態
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 醫囑狀態不可執行
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: business-rule
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: ORDER-NOT-EXECUTABLE
                        diagnostics: 該醫囑尚未生效或已停用，不可執行給藥。
        '422':
          description: 違反業務規則（五對未完成、缺實際值、時間超出有效期間…）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                fiveRights:
                  $ref: '#/components/examples/FiveRightsIncomplete'
  /Procedure:
    post:
      tags:
        - 實際執行
      summary: 記錄照護／處置執行
      operationId: createProcedure
      description: |
        照護醫令以 ServiceRequest 開立、以 Procedure 記錄執行。建立後不可修改。

        手術紀錄在 Phase 1 為**唯讀接收**，EMR 不提供編修或代簽。
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Procedure'
            examples:
              example:
                summary: 記錄一次照護處置（建立後不可改）
                value:
                  resourceType: Procedure
                  status: completed
                  code:
                    coding:
                      - system: http://icu.emr.local/CodeSystem/his-service
                        code: '24.0117'
                        display: Chăm sóc vết mổ
                    text: 傷口照護
                  subject:
                    reference: Patient/p1
                    display: Trần Bảo An
                  encounter:
                    reference: Encounter/enc-p1
                  basedOn:
                    - reference: ServiceRequest/sr-p1-cbc/_history/2
                  performedDateTime: '2026-08-31T10:25:00+07:00'
      responses:
        '201':
          description: 已建立
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 已建立
                  value:
                    resourceType: Procedure
                    id: proc-C1-0831
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-08-31T10:30:12+07:00'
                    status: completed
                    code:
                      coding:
                        - system: http://icu.emr.local/CodeSystem/his-service
                          code: '24.0117'
                          display: Chăm sóc vết mổ
                      text: 傷口照護
                    subject:
                      reference: Patient/p1
                      display: Trần Bảo An
                    encounter:
                      reference: Encounter/enc-p1
                    basedOn:
                      - reference: ServiceRequest/sr-p1-cbc/_history/2
                    performedDateTime: '2026-08-31T10:25:00+07:00'
                    performer:
                      - actor:
                          reference: PractitionerRole/nhungtt
                          display: 護理師 Phạm Thị Hồng Nhung
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 未執行但沒填原因
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: VARIANCE-REASON-REQUIRED
                        diagnostics: 標記未執行時必須填寫原因。
                        expression:
                          - Procedure.statusReason
    get:
      tags:
        - 實際執行
      summary: 搜尋處置執行
      operationId: searchProcedure
      parameters:
        - $ref: '#/components/parameters/patient'
        - name: based-on
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
        - name: date
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 照護醫令的執行紀錄
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 1
                    link:
                      - relation: self
                        url: https://icu.emr.local/fhir/r4/Procedure?patient=Patient/p1&date=ge2026-08-31
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/Procedure/proc-C1-0831
                        resource:
                          resourceType: Procedure
                          id: proc-C1-0831
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-08-31T10:30:12+07:00'
                          status: completed
                          category:
                            text: 護理處置
                          code:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/his-service
                                code: '24.0117'
                                display: Chăm sóc vết mổ
                            text: 傷口照護
                          subject:
                            reference: Patient/p1
                            display: Trần Bảo An
                          encounter:
                            reference: Encounter/enc-p1
                          basedOn:
                            - reference: ServiceRequest/sr-p1-cbc/_history/2
                          performedDateTime: '2026-08-31T10:25:00+07:00'
                          performer:
                            - actor:
                                reference: PractitionerRole/nhungtt
                                display: 護理師 Phạm Thị Hồng Nhung
                        search:
                          mode: match
  /DiagnosticReport:
    get:
      tags:
        - 檢驗與量測
      summary: 搜尋檢驗／檢查報告（HIS 唯讀）
      operationId: searchDiagnosticReport
      description: |
        一次載入 S13 檢驗結果頁所需的完整資料：

        ```
        GET /DiagnosticReport?patient=Patient/abc&issued=ge2026-08-30
            &_include=DiagnosticReport:result
            &_include=DiagnosticReport:specimen
            &_revinclude=Provenance:target
        ```

        帶回報告、逐項數值、檢體，以及已閱／判讀的 Provenance。

        **無 `interpretation` 的結果不得歸類為正常**（BR-RPT-005）。
        要查正常值必須明寫 `interpretation=N`。
      parameters:
        - $ref: '#/components/parameters/patient'
        - name: status
          in: query
          schema:
            type: string
            enum:
              - registered
              - partial
              - preliminary
              - final
              - amended
              - corrected
              - appended
              - cancelled
              - entered-in-error
              - unknown
        - name: category
          in: query
          schema:
            type: string
        - name: code
          in: query
          schema:
            type: string
        - name: issued
          in: query
          schema:
            type: string
        - name: based-on
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/include'
        - $ref: '#/components/parameters/revinclude'
        - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: S13 檢驗結果頁：報告 ＋ 逐項數值 ＋ 已閱判讀
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 1
                    link:
                      - relation: self
                        url: >-
                          https://icu.emr.local/fhir/r4/DiagnosticReport?patient=Patient/p1&date=ge2026-08-31&_include=DiagnosticReport:result&_revinclude=Provenance:target
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/DiagnosticReport/dr-p1-cbc
                        resource:
                          resourceType: DiagnosticReport
                          id: dr-p1-cbc
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T06:00:00+07:00'
                            source: 設計稿示範報告；數值為虛構
                          identifier:
                            - system: http://icu.emr.local/CodeSystem/order-number
                              value: CD-sr-p1-cbc
                          basedOn:
                            - reference: ServiceRequest/sr-p1-cbc
                          status: final
                          category:
                            - coding:
                                - system: http://terminology.hl7.org/CodeSystem/v2-0074
                                  code: LAB
                          code:
                            coding:
                              - code: CBC
                                display: 全血球計數
                            text: 全血球計數
                          subject:
                            reference: Patient/p1
                          encounter:
                            reference: Encounter/enc-p1
                          effectiveDateTime: '2026-06-17T06:00:00+07:00'
                          issued: '2026-06-17T06:00:00+07:00'
                          result:
                            - reference: Observation/dr-p1-cbc-1
                            - reference: Observation/dr-p1-cbc-2
                            - reference: Observation/dr-p1-cbc-3
                            - reference: Observation/dr-p1-cbc-4
                        search:
                          mode: match
                      - fullUrl: https://icu.emr.local/fhir/r4/Observation/dr-p1-cbc-1
                        resource:
                          resourceType: Observation
                          id: dr-p1-cbc-1
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T06:00:00+07:00'
                          status: final
                          category:
                            - coding:
                                - system: http://terminology.hl7.org/CodeSystem/observation-category
                                  code: laboratory
                          code:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/lab-indicator
                                code: L1
                                display: 白血球（WBC）
                            text: 白血球（WBC）
                          subject:
                            reference: Patient/p1
                          encounter:
                            reference: Encounter/enc-p1
                          effectiveDateTime: '2026-06-17T06:00:00+07:00'
                          issued: '2026-06-17T06:00:00+07:00'
                          valueQuantity:
                            value: 18.4
                            unit: G/L
                            system: http://unitsofmeasure.org
                            code: G/L
                          interpretation:
                            - coding:
                                - system: http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation
                                  code: H
                          partOf:
                            - reference: DiagnosticReport/dr-p1-cbc
                          note:
                            - text: 參考區間 6,0–17,5
                        search:
                          mode: include
                      - fullUrl: https://icu.emr.local/fhir/r4/Provenance/prov-review-ma-mr-p3-oresol-1
                        resource:
                          resourceType: Provenance
                          id: prov-review-ma-mr-p3-oresol-1
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-08-31T10:12:05+07:00'
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/reviewOutcome
                              valueCode: reviewed
                            - url: http://icu.emr.local/StructureDefinition/reviewNote
                              valueString: 對照醫囑劑量與執行時間，無差異。
                          target:
                            - reference: MedicationAdministration/ma-mr-p3-oresol-1
                          recorded: '2026-08-31T10:12:05+07:00'
                          activity:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/provenance-activity
                                code: clinical-review
                                display: 臨床核對
                          agent:
                            - type:
                                coding:
                                  - system: http://terminology.hl7.org/CodeSystem/provenance-participant-type
                                    code: verifier
                              who:
                                reference: PractitionerRole/thucdv
                                display: 博士醫師 Đặng Văn Thức
                          entity:
                            - role: source
                              what:
                                reference: MedicationRequest/mr-p1-mero/_history/3
                        search:
                          mode: include
  /DiagnosticReport/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags:
        - 檢驗與量測
      summary: 讀取報告
      operationId: readDiagnosticReport
      description: |
        **EMR 不可寫入報告。** 臨床端的「已閱」「判讀」一律另建 `Provenance`，
        不去改報告本身（BR-RPT-001）。
      responses:
        '200':
          description: 報告
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/DiagnosticReport'
              examples:
                example:
                  summary: 報告表頭（逐項數值在 result[]）
                  value:
                    resourceType: DiagnosticReport
                    id: dr-p1-cbc
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T06:00:00+07:00'
                      source: 設計稿示範報告；數值為虛構
                    identifier:
                      - system: http://icu.emr.local/CodeSystem/order-number
                        value: CD-sr-p1-cbc
                    basedOn:
                      - reference: ServiceRequest/sr-p1-cbc
                    status: final
                    category:
                      - coding:
                          - system: http://terminology.hl7.org/CodeSystem/v2-0074
                            code: LAB
                    code:
                      coding:
                        - code: CBC
                          display: 全血球計數
                      text: 全血球計數
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    effectiveDateTime: '2026-06-17T06:00:00+07:00'
                    issued: '2026-06-17T06:00:00+07:00'
                    result:
                      - reference: Observation/dr-p1-cbc-1
                      - reference: Observation/dr-p1-cbc-2
                      - reference: Observation/dr-p1-cbc-3
                      - reference: Observation/dr-p1-cbc-4
        '404':
          description: 資源不存在
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 資源不存在
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: not-found
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: NOT-FOUND
                        diagnostics: 找不到 DiagnosticReport。請確認識別碼；若為權限問題會回 403 而非 404。
    put:
      tags:
        - 檢驗與量測
      summary: 更新報告（僅整合服務帳號）
      operationId: updateDiagnosticReport
      description: |
        臨床使用者帳號呼叫一律回 `422 READ-ONLY-SOURCE`。
        僅具 `system/DiagnosticReport.u` scope 的整合服務可寫。
      parameters:
        - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/DiagnosticReport'
            examples:
              example:
                summary: 整合服務帳號落回 HIS 更正後的報告
                value:
                  resourceType: DiagnosticReport
                  id: dr-p1-cbc
                  meta:
                    versionId: '1'
                    lastUpdated: '2026-06-17T06:00:00+07:00'
                    source: 設計稿示範報告；數值為虛構
                  identifier:
                    - system: http://icu.emr.local/CodeSystem/order-number
                      value: CD-sr-p1-cbc
                  basedOn:
                    - reference: ServiceRequest/sr-p1-cbc
                  status: final
                  category:
                    - coding:
                        - system: http://terminology.hl7.org/CodeSystem/v2-0074
                          code: LAB
                  code:
                    coding:
                      - code: CBC
                        display: 全血球計數
                    text: 全血球計數
                  subject:
                    reference: Patient/p1
                  encounter:
                    reference: Encounter/enc-p1
                  effectiveDateTime: '2026-06-17T06:00:00+07:00'
                  issued: '2026-06-17T06:00:00+07:00'
                  result:
                    - reference: Observation/dr-p1-cbc-1
                    - reference: Observation/dr-p1-cbc-2
                    - reference: Observation/dr-p1-cbc-3
                    - reference: Observation/dr-p1-cbc-4
                  conclusion: Bạch cầu tăng（白血球上升）。2026-08-31 18:00 更正：檢體溶血，建議複驗。
      responses:
        '200':
          description: 已更新
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 已更新（版本進位，原版本仍可 vread）
                  value:
                    resourceType: DiagnosticReport
                    id: dr-p1-cbc
                    meta:
                      versionId: '2'
                      lastUpdated: '2026-08-31T18:12:44+07:00'
                    identifier:
                      - system: http://icu.emr.local/CodeSystem/order-number
                        value: CD-sr-p1-cbc
                    basedOn:
                      - reference: ServiceRequest/sr-p1-cbc
                    status: final
                    category:
                      - coding:
                          - system: http://terminology.hl7.org/CodeSystem/v2-0074
                            code: LAB
                    code:
                      coding:
                        - code: CBC
                          display: 全血球計數
                      text: 全血球計數
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    effectiveDateTime: '2026-06-17T06:00:00+07:00'
                    issued: '2026-06-17T06:00:00+07:00'
                    result:
                      - reference: Observation/dr-p1-cbc-1
                      - reference: Observation/dr-p1-cbc-2
                      - reference: Observation/dr-p1-cbc-3
                      - reference: Observation/dr-p1-cbc-4
                    conclusion: Bạch cầu tăng（白血球上升）。2026-08-31 18:00 更正：檢體溶血，建議複驗。
        '422':
          description: 臨床帳號嘗試寫入 HIS 來源
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              example:
                resourceType: OperationOutcome
                issue:
                  - severity: error
                    code: business-rule
                    details:
                      coding:
                        - system: http://icu.emr.local/CodeSystem/api-error
                          code: READ-ONLY-SOURCE
                    diagnostics: DiagnosticReport 由 HIS 提供，EMR 不接受寫入。已閱與判讀請建立 Provenance。
                    expression:
                      - DiagnosticReport.issued
  /Observation:
    get:
      tags:
        - 檢驗與量測
      summary: 搜尋量測與檢驗指標
      operationId: searchObservation
      description: |
        **時間窗查詢**（對應工作站的三種時間窗）：

        | 時間窗 | 查詢 |
        | --- | --- |
        | 24 小時 | `date=ge2026-08-30T19:00:00+07:00&date=le2026-08-31T19:00:00+07:00` |
        | 本班起訖 | 由客戶端依班別起訖換算後帶入相同格式 |
        | 全部 | 不帶 `date` |

        伺服器**不提供** `window=shift` 這種語意參數——班別起訖屬排班資料，
        換算責任在客戶端，避免伺服器對「本班」有隱含定義。
      parameters:
        - $ref: '#/components/parameters/patient'
        - name: code
          in: query
          schema:
            type: string
        - name: component-code
          in: query
          schema:
            type: string
          description: 血壓子項用，例：收縮壓 8480-6
        - name: date
          in: query
          schema:
            type: string
        - name: category
          in: query
          schema:
            type: string
            enum:
              - vital-signs
              - laboratory
              - procedure
        - name: part-of
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 24 小時生命徵象（血壓以 component 成對回傳）
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 2
                    link:
                      - relation: self
                        url: >-
                          https://icu.emr.local/fhir/r4/Observation?patient=Patient/p1&category=vital-signs&date=ge2026-08-30T19:00:00%2B07:00&_sort=-date
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/Observation/obs-p1-bp
                        resource:
                          resourceType: Observation
                          id: obs-p1-bp
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-08-31T18:02:10+07:00'
                          status: final
                          category:
                            - coding:
                                - system: http://terminology.hl7.org/CodeSystem/observation-category
                                  code: vital-signs
                          code:
                            coding:
                              - system: http://loinc.org
                                code: 85354-9
                                display: Blood pressure panel
                            text: 血壓
                          subject:
                            reference: Patient/p1
                            display: Trần Bảo An
                          encounter:
                            reference: Encounter/enc-p1
                          effectiveDateTime: '2026-08-31T18:00:00+07:00'
                          issued: '2026-08-31T18:02:10+07:00'
                          performer:
                            - reference: PractitionerRole/nhungtt
                              display: 護理師 Phạm Thị Hồng Nhung
                          component:
                            - code:
                                coding:
                                  - system: http://loinc.org
                                    code: 8480-6
                                    display: Systolic blood pressure
                                  - system: http://icu.emr.local/CodeSystem/tdl
                                    code: TDL.0094
                              valueQuantity:
                                value: 92
                                unit: mmHg
                                system: http://unitsofmeasure.org
                                code: mm[Hg]
                            - code:
                                coding:
                                  - system: http://loinc.org
                                    code: 8462-4
                                    display: Diastolic blood pressure
                                  - system: http://icu.emr.local/CodeSystem/tdl
                                    code: TDL.0095
                              valueQuantity:
                                value: 54
                                unit: mmHg
                                system: http://unitsofmeasure.org
                                code: mm[Hg]
                        search:
                          mode: match
                      - fullUrl: https://icu.emr.local/fhir/r4/Observation/obs-p1-hr
                        resource:
                          resourceType: Observation
                          id: obs-p1-hr
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T07:42:00+07:00'
                          status: final
                          category:
                            - coding:
                                - system: http://terminology.hl7.org/CodeSystem/observation-category
                                  code: vital-signs
                          code:
                            coding:
                              - system: http://loinc.org
                                code: 8867-4
                                display: 心率
                            text: 心率
                          subject:
                            reference: Patient/p1
                          encounter:
                            reference: Encounter/enc-p1
                          effectiveDateTime: '2026-06-17T06:00:00+07:00'
                          performer:
                            - reference: PractitionerRole/nhungtt
                          valueQuantity:
                            value: 148
                            unit: /min
                            system: http://unitsofmeasure.org
                            code: /min
                        search:
                          mode: match
    post:
      tags:
        - 檢驗與量測
      summary: 記錄生理量測
      operationId: createObservation
      description: |
        建立後不可修改。

        | 規則 | 內容 |
        | --- | --- |
        | BR-AUTH-004 | 限護理師 |
        | BR-OBS-001 | 項目須在支援清單內，數值須為非負有限數 |
        | BR-OBS-002 | **血壓必須以單一 Observation 的兩個 component 表達，且兩子項同時提供** |
        | BR-OBS-003 | 缺值一律 `dataAbsentReason`，**禁止送 0 代替** |
        | BR-OBS-004 | 輸注速率觀察須 `partOf` 一筆執行紀錄，且 `notCountedAsIntake=true` |

        血壓拆成兩筆獨立 Observation 會讓收縮／舒張壓在時間軸上失去配對，因此明文禁止。
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Observation'
            examples:
              bloodPressure:
                $ref: '#/components/examples/ObservationBloodPressure'
      responses:
        '201':
          description: 已建立
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 已記錄
                  value:
                    resourceType: Observation
                    id: obs-p1-bp
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-08-31T18:02:10+07:00'
                    status: final
                    category:
                      - coding:
                          - system: http://terminology.hl7.org/CodeSystem/observation-category
                            code: vital-signs
                    code:
                      coding:
                        - system: http://loinc.org
                          code: 85354-9
                          display: Blood pressure panel
                      text: 血壓
                    subject:
                      reference: Patient/p1
                      display: Trần Bảo An
                    encounter:
                      reference: Encounter/enc-p1
                    effectiveDateTime: '2026-08-31T18:00:00+07:00'
                    issued: '2026-08-31T18:02:10+07:00'
                    performer:
                      - reference: PractitionerRole/nhungtt
                        display: 護理師 Phạm Thị Hồng Nhung
                    component:
                      - code:
                          coding:
                            - system: http://loinc.org
                              code: 8480-6
                              display: Systolic blood pressure
                            - system: http://icu.emr.local/CodeSystem/tdl
                              code: TDL.0094
                        valueQuantity:
                          value: 92
                          unit: mmHg
                          system: http://unitsofmeasure.org
                          code: mm[Hg]
                      - code:
                          coding:
                            - system: http://loinc.org
                              code: 8462-4
                              display: Diastolic blood pressure
                            - system: http://icu.emr.local/CodeSystem/tdl
                              code: TDL.0095
                        valueQuantity:
                          value: 54
                          unit: mmHg
                          system: http://unitsofmeasure.org
                          code: mm[Hg]
        '403':
          description: |
            已認證但無權（角色限制；寫入時病人不在照護範圍；照會醫師讀取沒有照會單的病人）。

            **不因無權而回 404**——權限問題一律 403，資源不存在才 404。
            但搜尋是例外：一律回較少的結果而非 403，避免探測病人是否存在。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 不在照護範圍
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: forbidden
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: PATIENT-OUT-OF-SCOPE
                        diagnostics: 此病人不在您的照護範圍內，無法記錄量測。
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 血壓只送了收縮壓
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: BP-COMPONENTS-REQUIRED
                        diagnostics: 血壓必須同時填寫收縮壓與舒張壓，不可只記一項。
                        expression:
                          - Observation.component
  /Composition:
    get:
      tags:
        - 病歷文件
      summary: 搜尋病歷文件
      operationId: searchComposition
      description: |
        | 文件 | `type` |
        | --- | --- |
        | Admission Note | LOINC `34117-2` |
        | Progress Note（SOAP） | LOINC `11506-3` |
        | Discharge Summary | LOINC `18842-5` |
        | 會診／照會回覆 | LOINC `11488-4` |
        | 護理紀錄 | 本地碼【待確認】 |
        | SBAR 交班 | 本地碼【未決事項 Q-04】 |
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/encounter'
        - name: type
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum:
              - preliminary
              - final
              - amended
              - entered-in-error
        - name: date
          in: query
          schema:
            type: string
        - name: author
          in: query
          schema:
            type: string
        - name: related-id
          in: query
          schema:
            type: string
          description: 依 relatesTo 目標查更正鏈
        - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 本次就醫的病程紀錄
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 1
                    link:
                      - relation: self
                        url: >-
                          https://icu.emr.local/fhir/r4/Composition?patient=Patient/p1&type=11506-3&_sort=-date&_count=20
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/Composition/comp-p1-n2
                        resource:
                          resourceType: Composition
                          id: comp-p1-n2
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-17T06:30:00+07:00'
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/signedAt
                              valueInstant: '2026-06-17T06:52:00+07:00'
                          status: final
                          type:
                            coding:
                              - system: http://loinc.org
                                code: 11506-3
                                display: Progress note
                          subject:
                            reference: Patient/p1
                          encounter:
                            reference: Encounter/enc-p1
                          date: '2026-06-17T06:30:00+07:00'
                          title: 病歷單 第 5 號 · 早班
                          author:
                            - reference: PractitionerRole/thucdv
                          section:
                            - title: S
                              code:
                                coding:
                                  - system: http://icu.emr.local/CodeSystem/soap-section
                                    code: S
                              text:
                                status: generated
                                div: <div xmlns="http://www.w3.org/1999/xhtml">病童鎮靜下安睡、無躁動。家屬陳述病童較昨日呼吸較不費力。</div>
                            - title: O
                              code:
                                coding:
                                  - system: http://icu.emr.local/CodeSystem/soap-section
                                    code: O
                              text:
                                status: generated
                                div: >-
                                  <div xmlns="http://www.w3.org/1999/xhtml">減少鎮靜時清醒，雙側瞳孔 2mm，對光反射(+)。呼吸器 SIMV FiO₂
                                  40%，SpO₂ 94%。心律規則 148 次/分，血壓 90/53。兩肺通氣對稱。腹部柔軟，肝臟未腫大。縱膈引流 10 ml/6h 淡血性液。</div>
                            - title: A
                              code:
                                coding:
                                  - system: http://icu.emr.local/CodeSystem/soap-section
                                    code: A
                              text:
                                status: generated
                                div: >-
                                  <div xmlns="http://www.w3.org/1999/xhtml">法洛氏四重症完全矯正術後第 1 天 —
                                  血液動力學改善，仍依賴低劑量血管活性藥。監測低心輸出量。</div>
                            - title: P
                              code:
                                coding:
                                  - system: http://icu.emr.local/CodeSystem/soap-section
                                    code: P
                              text:
                                status: generated
                                div: >-
                                  <div xmlns="http://www.w3.org/1999/xhtml">續用 Milrinon，逐步減少 Adrenalin。抗生素 Meropenem +
                                  Voxin。利尿 Furosemid。血液氣體分析穩定後脫離呼吸器。每 6h 驗血液氣體、全血球計數、CRP。第一級照護。</div>
                        search:
                          mode: match
    post:
      tags:
        - 病歷文件
      summary: 建立病歷文件（草稿）
      operationId: createComposition
      description: |
        建立為 `status=preliminary`（草稿）。

        ### 各類型必填段落

        | 類型 | 必填 | 規則 |
        | --- | --- | --- |
        | Progress Note | S／O／A／P 四段 | BR-DOC-001 |
        | Admission Note | CC／PI／PH／入院生命徵象／初步評估 | BR-DOC-002 |
        | Discharge Summary | 入出院日期與診斷、檢驗檢查、手術處置、已執行醫囑、住院經過、追蹤計畫、轉診建議 | BR-DOC-003 |

        ### 自動帶入的約束

        - 自動帶入的內容一律保留來源編號（`section.entry` 用**帶版本**的 Reference，BR-DOC-008），
          這樣「引用當時看到的數值」不會被後來的更正改掉。
        - 複製前一日病程須帶 `copyTrace`，記錄複製來源與**哪些 SOAP 段落被改過**。
          **複製不視為已核對**（BR-DOC-007）。
        - 草稿依作者、病人、文件類型分開儲存，切換類型不互相覆寫（BR-DOC-010）。
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Composition'
            examples:
              example:
                summary: 建立 SOAP 病程草稿（O 段引用帶版本）
                value:
                  resourceType: Composition
                  status: preliminary
                  type:
                    coding:
                      - system: http://loinc.org
                        code: 11506-3
                        display: Progress note
                  subject:
                    reference: Patient/p1
                  encounter:
                    reference: Encounter/enc-p1
                  date: '2026-06-17T06:30:00+07:00'
                  title: 病歷單 第 5 號 · 早班
                  section:
                    - title: S
                      code:
                        coding:
                          - system: http://icu.emr.local/CodeSystem/soap-section
                            code: S
                      text:
                        status: generated
                        div: <div xmlns="http://www.w3.org/1999/xhtml">病童鎮靜下安睡、無躁動。家屬陳述病童較昨日呼吸較不費力。</div>
                    - title: O
                      code:
                        coding:
                          - system: http://icu.emr.local/CodeSystem/soap-section
                            code: O
                      text:
                        status: generated
                        div: >-
                          <div xmlns="http://www.w3.org/1999/xhtml">減少鎮靜時清醒，雙側瞳孔 2mm，對光反射(+)。呼吸器 SIMV FiO₂ 40%，SpO₂
                          94%。心律規則 148 次/分，血壓 90/53。兩肺通氣對稱。腹部柔軟，肝臟未腫大。縱膈引流 10 ml/6h 淡血性液。</div>
                    - title: A
                      code:
                        coding:
                          - system: http://icu.emr.local/CodeSystem/soap-section
                            code: A
                      text:
                        status: generated
                        div: >-
                          <div xmlns="http://www.w3.org/1999/xhtml">法洛氏四重症完全矯正術後第 1 天 —
                          血液動力學改善，仍依賴低劑量血管活性藥。監測低心輸出量。</div>
                    - title: P
                      code:
                        coding:
                          - system: http://icu.emr.local/CodeSystem/soap-section
                            code: P
                      text:
                        status: generated
                        div: >-
                          <div xmlns="http://www.w3.org/1999/xhtml">續用 Milrinon，逐步減少 Adrenalin。抗生素 Meropenem + Voxin。利尿
                          Furosemid。血液氣體分析穩定後脫離呼吸器。每 6h 驗血液氣體、全血球計數、CRP。第一級照護。</div>
      responses:
        '201':
          description: 已建立
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 已建立草稿
                  value:
                    resourceType: Composition
                    id: comp-p1-n2
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T06:30:00+07:00'
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/signedAt
                        valueInstant: '2026-06-17T06:52:00+07:00'
                    status: final
                    type:
                      coding:
                        - system: http://loinc.org
                          code: 11506-3
                          display: Progress note
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    date: '2026-06-17T06:30:00+07:00'
                    title: 病歷單 第 5 號 · 早班
                    author:
                      - reference: PractitionerRole/thucdv
                    section:
                      - title: S
                        code:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/soap-section
                              code: S
                        text:
                          status: generated
                          div: <div xmlns="http://www.w3.org/1999/xhtml">病童鎮靜下安睡、無躁動。家屬陳述病童較昨日呼吸較不費力。</div>
                      - title: O
                        code:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/soap-section
                              code: O
                        text:
                          status: generated
                          div: >-
                            <div xmlns="http://www.w3.org/1999/xhtml">減少鎮靜時清醒，雙側瞳孔 2mm，對光反射(+)。呼吸器 SIMV FiO₂ 40%，SpO₂
                            94%。心律規則 148 次/分，血壓 90/53。兩肺通氣對稱。腹部柔軟，肝臟未腫大。縱膈引流 10 ml/6h 淡血性液。</div>
                      - title: A
                        code:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/soap-section
                              code: A
                        text:
                          status: generated
                          div: >-
                            <div xmlns="http://www.w3.org/1999/xhtml">法洛氏四重症完全矯正術後第 1 天 —
                            血液動力學改善，仍依賴低劑量血管活性藥。監測低心輸出量。</div>
                      - title: P
                        code:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/soap-section
                              code: P
                        text:
                          status: generated
                          div: >-
                            <div xmlns="http://www.w3.org/1999/xhtml">續用 Milrinon，逐步減少 Adrenalin。抗生素 Meropenem +
                            Voxin。利尿 Furosemid。血液氣體分析穩定後脫離呼吸器。每 6h 驗血液氣體、全血球計數、CRP。第一級照護。</div>
        '403':
          description: |
            已認證但無權（角色限制；寫入時病人不在照護範圍；照會醫師讀取沒有照會單的病人）。

            **不因無權而回 404**——權限問題一律 403，資源不存在才 404。
            但搜尋是例外：一律回較少的結果而非 403，避免探測病人是否存在。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 角色不可撰寫病程
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: forbidden
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: ROLE-DOCTOR-ONLY
                        diagnostics: 病程紀錄僅限醫師撰寫。
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: SOAP 段落不全
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: SECTION-REQUIRED
                        diagnostics: 病程紀錄的 S／O／A／P 四段皆為必填。
                        expression:
                          - Composition.section[2].text
  /Composition/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags:
        - 病歷文件
      summary: 讀取病歷文件
      operationId: readComposition
      responses:
        '200':
          description: 病歷文件
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Composition'
              examples:
                example:
                  summary: 病程紀錄
                  value:
                    resourceType: Composition
                    id: comp-p1-n2
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-06-17T06:30:00+07:00'
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/signedAt
                        valueInstant: '2026-06-17T06:52:00+07:00'
                    status: final
                    type:
                      coding:
                        - system: http://loinc.org
                          code: 11506-3
                          display: Progress note
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    date: '2026-06-17T06:30:00+07:00'
                    title: 病歷單 第 5 號 · 早班
                    author:
                      - reference: PractitionerRole/thucdv
                    section:
                      - title: S
                        code:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/soap-section
                              code: S
                        text:
                          status: generated
                          div: <div xmlns="http://www.w3.org/1999/xhtml">病童鎮靜下安睡、無躁動。家屬陳述病童較昨日呼吸較不費力。</div>
                      - title: O
                        code:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/soap-section
                              code: O
                        text:
                          status: generated
                          div: >-
                            <div xmlns="http://www.w3.org/1999/xhtml">減少鎮靜時清醒，雙側瞳孔 2mm，對光反射(+)。呼吸器 SIMV FiO₂ 40%，SpO₂
                            94%。心律規則 148 次/分，血壓 90/53。兩肺通氣對稱。腹部柔軟，肝臟未腫大。縱膈引流 10 ml/6h 淡血性液。</div>
                      - title: A
                        code:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/soap-section
                              code: A
                        text:
                          status: generated
                          div: >-
                            <div xmlns="http://www.w3.org/1999/xhtml">法洛氏四重症完全矯正術後第 1 天 —
                            血液動力學改善，仍依賴低劑量血管活性藥。監測低心輸出量。</div>
                      - title: P
                        code:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/soap-section
                              code: P
                        text:
                          status: generated
                          div: >-
                            <div xmlns="http://www.w3.org/1999/xhtml">續用 Milrinon，逐步減少 Adrenalin。抗生素 Meropenem +
                            Voxin。利尿 Furosemid。血液氣體分析穩定後脫離呼吸器。每 6h 驗血液氣體、全血球計數、CRP。第一級照護。</div>
        '404':
          description: 資源不存在
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 資源不存在
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: not-found
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: NOT-FOUND
                        diagnostics: 找不到 Composition。請確認識別碼；若為權限問題會回 403 而非 404。
    put:
      tags:
        - 病歷文件
      summary: 更新病歷文件
      operationId: updateComposition
      description: |
        | 狀態 | 可改 |
        | --- | --- |
        | `preliminary`（草稿） | 全部欄位 |
        | `final`（已簽） | **無**。更正一律新建 Composition ＋ `relatesTo[replaces]` ＋ 更正原因必填 |
        | `amended` | 無 |

        更正是**新增**不是修改：舊版轉 `amended`，內容完整保留（BR-DOC-005）。
        理由：`_history` 是技術稽核軌跡，臨床閱讀者需要在當前資源集合裡就看到「這份有更正版」。
      parameters:
        - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Composition'
            examples:
              example:
                summary: 草稿階段補 A 段內容
                value:
                  resourceType: Composition
                  id: comp-p1-n2
                  meta:
                    versionId: '1'
                    lastUpdated: '2026-06-17T06:30:00+07:00'
                  extension:
                    - url: http://icu.emr.local/StructureDefinition/signedAt
                      valueInstant: '2026-06-17T06:52:00+07:00'
                  status: final
                  type:
                    coding:
                      - system: http://loinc.org
                        code: 11506-3
                        display: Progress note
                  subject:
                    reference: Patient/p1
                  encounter:
                    reference: Encounter/enc-p1
                  date: '2026-06-17T06:30:00+07:00'
                  title: 病歷單 第 5 號 · 早班
                  author:
                    - reference: PractitionerRole/thucdv
                  section:
                    - title: S
                      code:
                        coding:
                          - system: http://icu.emr.local/CodeSystem/soap-section
                            code: S
                      text:
                        status: generated
                        div: <div xmlns="http://www.w3.org/1999/xhtml">病童鎮靜下安睡、無躁動。家屬陳述病童較昨日呼吸較不費力。</div>
                    - title: O
                      code:
                        coding:
                          - system: http://icu.emr.local/CodeSystem/soap-section
                            code: O
                      text:
                        status: generated
                        div: >-
                          <div xmlns="http://www.w3.org/1999/xhtml">減少鎮靜時清醒，雙側瞳孔 2mm，對光反射(+)。呼吸器 SIMV FiO₂ 40%，SpO₂
                          94%。心律規則 148 次/分，血壓 90/53。兩肺通氣對稱。腹部柔軟，肝臟未腫大。縱膈引流 10 ml/6h 淡血性液。</div>
                    - title: A
                      code:
                        coding:
                          - system: http://icu.emr.local/CodeSystem/soap-section
                            code: A
                      text:
                        status: generated
                        div: <div xmlns="http://www.w3.org/1999/xhtml">術後第 3 天，血行動力學穩定；白血球上升，先觀察並複驗。</div>
                    - title: P
                      code:
                        coding:
                          - system: http://icu.emr.local/CodeSystem/soap-section
                            code: P
                      text:
                        status: generated
                        div: >-
                          <div xmlns="http://www.w3.org/1999/xhtml">續用 Milrinon，逐步減少 Adrenalin。抗生素 Meropenem + Voxin。利尿
                          Furosemid。血液氣體分析穩定後脫離呼吸器。每 6h 驗血液氣體、全血球計數、CRP。第一級照護。</div>
      responses:
        '200':
          description: 已更新
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 已更新
                  value:
                    resourceType: Composition
                    id: comp-p1-n2
                    meta:
                      versionId: '2'
                      lastUpdated: '2026-08-31T08:20:31+07:00'
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/signedAt
                        valueInstant: '2026-06-17T06:52:00+07:00'
                    status: final
                    type:
                      coding:
                        - system: http://loinc.org
                          code: 11506-3
                          display: Progress note
                    subject:
                      reference: Patient/p1
                    encounter:
                      reference: Encounter/enc-p1
                    date: '2026-06-17T06:30:00+07:00'
                    title: 病歷單 第 5 號 · 早班
                    author:
                      - reference: PractitionerRole/thucdv
                    section:
                      - title: S
                        code:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/soap-section
                              code: S
                        text:
                          status: generated
                          div: <div xmlns="http://www.w3.org/1999/xhtml">病童鎮靜下安睡、無躁動。家屬陳述病童較昨日呼吸較不費力。</div>
                      - title: O
                        code:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/soap-section
                              code: O
                        text:
                          status: generated
                          div: >-
                            <div xmlns="http://www.w3.org/1999/xhtml">減少鎮靜時清醒，雙側瞳孔 2mm，對光反射(+)。呼吸器 SIMV FiO₂ 40%，SpO₂
                            94%。心律規則 148 次/分，血壓 90/53。兩肺通氣對稱。腹部柔軟，肝臟未腫大。縱膈引流 10 ml/6h 淡血性液。</div>
                      - title: A
                        code:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/soap-section
                              code: A
                        text:
                          status: generated
                          div: >-
                            <div xmlns="http://www.w3.org/1999/xhtml">法洛氏四重症完全矯正術後第 1 天 —
                            血液動力學改善，仍依賴低劑量血管活性藥。監測低心輸出量。</div>
                      - title: P
                        code:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/soap-section
                              code: P
                        text:
                          status: generated
                          div: >-
                            <div xmlns="http://www.w3.org/1999/xhtml">續用 Milrinon，逐步減少 Adrenalin。抗生素 Meropenem +
                            Voxin。利尿 Furosemid。血液氣體分析穩定後脫離呼吸器。每 6h 驗血液氣體、全血球計數、CRP。第一級照護。</div>
        '409':
          description: 已簽文件不可修改
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              example:
                resourceType: OperationOutcome
                issue:
                  - severity: error
                    code: conflict
                    details:
                      coding:
                        - system: http://icu.emr.local/CodeSystem/api-error
                          code: SIGNED-IMMUTABLE
                    diagnostics: 已簽署的文件不可修改。請建立更正版本並填寫更正原因，原文會完整保留。
        '412':
          description: 缺少 `If-Match` 標頭
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 缺 If-Match
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: PRECONDITION-REQUIRED
                        diagnostics: 缺少 If-Match 標頭。所有可寫互動都必須帶目前版本，不接受盲目覆寫。
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 已簽署的文件不可就地修改
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: conflict
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: SIGNED-IMMUTABLE
                        diagnostics: 已簽署的病歷不可修改。更正請建立新版本並註明理由。
  /Composition/{id}/$sign:
    parameters:
      - $ref: '#/components/parameters/id'
    post:
      tags:
        - 病歷文件
      summary: 簽署文件
      operationId: signComposition
      description: |
        只能簽自己的 `preliminary` 文件（BR-DOC-004）。
        簽署後 `status` 轉 `final` 並建立 `Provenance.signature`。

        簽章驗證結果由伺服器產生，透過 `extension[signatureValidation]` 回傳：
        `valid` / `invalid` / `unverified`。憑證服務不可用時用 `unverified`，**不預設 valid**。
      parameters:
        - $ref: '#/components/parameters/ifMatch'
      responses:
        '200':
          description: 已簽署，回傳更新後的文件與 Provenance
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 文件轉 final ＋ 新建簽章 Provenance
                  value:
                    resourceType: Bundle
                    type: collection
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/Composition/comp-p1-n2
                        resource:
                          resourceType: Composition
                          id: comp-p1-n2
                          meta:
                            versionId: '3'
                            lastUpdated: '2026-08-31T08:22:10+07:00'
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/signedAt
                              valueInstant: '2026-08-31T08:22:10+07:00'
                          status: final
                          type:
                            coding:
                              - system: http://loinc.org
                                code: 11506-3
                                display: Progress note
                          subject:
                            reference: Patient/p1
                          encounter:
                            reference: Encounter/enc-p1
                          date: '2026-06-17T06:30:00+07:00'
                          title: 病歷單 第 5 號 · 早班
                          author:
                            - reference: PractitionerRole/thucdv
                          section:
                            - title: S
                              code:
                                coding:
                                  - system: http://icu.emr.local/CodeSystem/soap-section
                                    code: S
                              text:
                                status: generated
                                div: <div xmlns="http://www.w3.org/1999/xhtml">病童鎮靜下安睡、無躁動。家屬陳述病童較昨日呼吸較不費力。</div>
                            - title: O
                              code:
                                coding:
                                  - system: http://icu.emr.local/CodeSystem/soap-section
                                    code: O
                              text:
                                status: generated
                                div: >-
                                  <div xmlns="http://www.w3.org/1999/xhtml">減少鎮靜時清醒，雙側瞳孔 2mm，對光反射(+)。呼吸器 SIMV FiO₂
                                  40%，SpO₂ 94%。心律規則 148 次/分，血壓 90/53。兩肺通氣對稱。腹部柔軟，肝臟未腫大。縱膈引流 10 ml/6h 淡血性液。</div>
                            - title: A
                              code:
                                coding:
                                  - system: http://icu.emr.local/CodeSystem/soap-section
                                    code: A
                              text:
                                status: generated
                                div: >-
                                  <div xmlns="http://www.w3.org/1999/xhtml">法洛氏四重症完全矯正術後第 1 天 —
                                  血液動力學改善，仍依賴低劑量血管活性藥。監測低心輸出量。</div>
                            - title: P
                              code:
                                coding:
                                  - system: http://icu.emr.local/CodeSystem/soap-section
                                    code: P
                              text:
                                status: generated
                                div: >-
                                  <div xmlns="http://www.w3.org/1999/xhtml">續用 Milrinon，逐步減少 Adrenalin。抗生素 Meropenem +
                                  Voxin。利尿 Furosemid。血液氣體分析穩定後脫離呼吸器。每 6h 驗血液氣體、全血球計數、CRP。第一級照護。</div>
                      - fullUrl: https://icu.emr.local/fhir/r4/Provenance/prov-sign-comp-p1-n2
                        resource:
                          resourceType: Provenance
                          id: prov-sign-comp-p1-n2
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-06-14T06:00:00+07:00'
                          target:
                            - reference: Composition/comp-p1-n2/_history/3
                          recorded: '2026-08-31T08:22:10+07:00'
                          activity:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/provenance-activity
                                code: sign
                          agent:
                            - type:
                                coding:
                                  - system: http://terminology.hl7.org/CodeSystem/provenance-participant-type
                                    code: author
                              who:
                                reference: PractitionerRole/thucdv
                          signature:
                            - type:
                                - system: urn:iso-astm:E1762-95:2013
                                  code: 1.2.840.10065.1.12.1.1
                                  display: Author's Signature
                              when: '2026-06-14T06:00:00+07:00'
                              who:
                                reference: PractitionerRole/thucdv
                              targetFormat: application/fhir+json
                              sigFormat: application/jose
                              data: dGh1Y2R2fG1yLXAxLW1lcm98MQ==
        '403':
          description: |
            已認證但無權（角色限制；寫入時病人不在照護範圍；照會醫師讀取沒有照會單的病人）。

            **不因無權而回 404**——權限問題一律 403，資源不存在才 404。
            但搜尋是例外：一律回較少的結果而非 403，避免探測病人是否存在。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 只能簽自己的草稿
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: forbidden
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: SIGN-OWN-DRAFT-ONLY
                        diagnostics: 僅能簽署自己撰寫且尚未簽署的文件。
        '409':
          description: |
            版本衝突，或目前狀態不允許此操作。

            版本衝突時必須帶目前版本，讓客戶端就地合併——**內容不會被覆寫**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 已是 final
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: conflict
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: SIGNED-IMMUTABLE
                        diagnostics: 文件已簽署，不可重複簽署。
  /Composition/{id}/$receive:
    parameters:
      - $ref: '#/components/parameters/id'
    post:
      tags:
        - 工作與交班
      summary: 接收交班
      operationId: receiveHandover
      description: |
        交班版本是 `Composition`（SBAR），接收是 `Provenance`。本操作原子完成：

        1. 建立 `Provenance`（`activity = handover-receive`）。
        2. 把交出者名下**未完成**的 Task `owner` 轉移給接收者（已完成的不動，BR-HO-004）。

        ### 拒絕條件

        | 規則 | 條件 | 錯誤碼 |
        | --- | --- | --- |
        | BR-HO-003 | 接收者角色與交班角色不符 | `HANDOVER-ROLE-MISMATCH` |
        | BR-HO-005 | 該版本已被更正 | `HANDOVER-SUPERSEDED` |
        | BR-HO-006 | 同一版本重複接收 | `HANDOVER-ALREADY-RECEIVED` |

        交班內容含交出當下未結工作的**快照**，快照不隨後續變動而改（BR-HO-007）。
      responses:
        '200':
          description: 已接收，回傳 Provenance 與被轉移的 Task
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 接收交班：建立 Provenance ＋ 同一交易內轉移 Task.owner
                  value:
                    resourceType: Bundle
                    type: transaction-response
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/Provenance/prov-handover-0831
                        resource:
                          resourceType: Provenance
                          id: prov-handover-0831
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-08-31T18:52:07+07:00'
                          target:
                            - reference: Composition/H-N1-V2/_history/2
                          recorded: '2026-08-31T18:52:07+07:00'
                          activity:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/provenance-activity
                                code: handover-receive
                                display: 交班接收
                          agent:
                            - who:
                                reference: PractitionerRole/hanlt
                                display: 護理師 Lê Thu Hà
                        response:
                          status: 201 Created
                          location: Provenance/prov-handover-0831/_history/1
                      - fullUrl: https://icu.emr.local/fhir/r4/Task/task-n-nt1
                        resource:
                          resourceType: Task
                          id: task-n-nt1
                          meta:
                            versionId: '3'
                            lastUpdated: '2026-08-31T18:45:03+07:00'
                          status: accepted
                          intent: order
                          description: 追蹤 WBC 複驗結果並回報主責醫師
                          for:
                            reference: Patient/p1
                            display: Trần Bảo An
                          encounter:
                            reference: Encounter/enc-p1
                          focus:
                            reference: DiagnosticReport/dr-p1-cbc
                          owner:
                            reference: PractitionerRole/hanlt
                            display: 護理師 Lê Thu Hà
                          authoredOn: '2026-08-31T09:10:00+07:00'
                          note:
                            - time: '2026-08-31T18:45:03+07:00'
                              text: 日班交班轉移給夜班
                        response:
                          status: 200 OK
                          location: Task/task-n-nt1/_history/3
                          etag: W/"3"
        '403':
          description: |
            已認證但無權（角色限制；寫入時病人不在照護範圍；照會醫師讀取沒有照會單的病人）。

            **不因無權而回 404**——權限問題一律 403，資源不存在才 404。
            但搜尋是例外：一律回較少的結果而非 403，避免探測病人是否存在。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 接收者不是指定的接班人
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: forbidden
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: HANDOVER-ROLE-MISMATCH
                        diagnostics: 您不是這份交班的指定接班者，無法接收。
        '409':
          description: |
            版本衝突，或目前狀態不允許此操作。

            版本衝突時必須帶目前版本，讓客戶端就地合併——**內容不會被覆寫**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 已被接收過
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: duplicate
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: HANDOVER-ALREADY-RECEIVED
                        diagnostics: 這份交班已被接收，不可重複接收。
  /Task:
    get:
      tags:
        - 工作與交班
      summary: 搜尋臨床工作
      operationId: searchTask
      parameters:
        - $ref: '#/components/parameters/patient'
        - name: status
          in: query
          schema:
            type: string
            enum:
              - draft
              - requested
              - received
              - accepted
              - rejected
              - ready
              - cancelled
              - in-progress
              - on-hold
              - failed
              - completed
              - entered-in-error
        - name: owner
          in: query
          schema:
            type: string
        - name: focus
          in: query
          schema:
            type: string
          description: 來源單據（報告、醫令、文件）
        - name: business-status
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 我的未結工作
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 1
                    link:
                      - relation: self
                        url: >-
                          https://icu.emr.local/fhir/r4/Task?patient=Patient/p1&owner=PractitionerRole/hanlt&status=accepted
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/Task/task-n-nt1
                        resource:
                          resourceType: Task
                          id: task-n-nt1
                          meta:
                            versionId: '3'
                            lastUpdated: '2026-08-31T18:45:03+07:00'
                          status: accepted
                          intent: order
                          description: 追蹤 WBC 複驗結果並回報主責醫師
                          for:
                            reference: Patient/p1
                            display: Trần Bảo An
                          encounter:
                            reference: Encounter/enc-p1
                          focus:
                            reference: DiagnosticReport/dr-p1-cbc
                          owner:
                            reference: PractitionerRole/hanlt
                            display: 護理師 Lê Thu Hà
                          authoredOn: '2026-08-31T09:10:00+07:00'
                          note:
                            - time: '2026-08-31T18:45:03+07:00'
                              text: 日班交班轉移給夜班
                        search:
                          mode: match
    post:
      tags:
        - 工作與交班
      summary: 建立臨床工作
      operationId: createTask
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Task'
            examples:
              example:
                summary: 從檢驗報告開一件追蹤工作
                value:
                  resourceType: Task
                  status: requested
                  intent: order
                  description: 追蹤 WBC 複驗結果並回報主責醫師
                  for:
                    reference: Patient/p1
                    display: Trần Bảo An
                  encounter:
                    reference: Encounter/enc-p1
                  focus:
                    reference: DiagnosticReport/dr-p1-cbc
                  owner:
                    reference: PractitionerRole/nhungtt
                    display: 護理師 Phạm Thị Hồng Nhung
      responses:
        '201':
          description: 已建立
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 已建立
                  value:
                    resourceType: Task
                    id: task-n-nt1
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-08-31T09:10:00+07:00'
                    status: requested
                    intent: order
                    description: 追蹤 WBC 複驗結果並回報主責醫師
                    for:
                      reference: Patient/p1
                      display: Trần Bảo An
                    encounter:
                      reference: Encounter/enc-p1
                    focus:
                      reference: DiagnosticReport/dr-p1-cbc
                    owner:
                      reference: PractitionerRole/nhungtt
                      display: 護理師 Phạm Thị Hồng Nhung
                    authoredOn: '2026-08-31T09:10:00+07:00'
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 指派對象不合法
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: ASSIGNEE-INVALID
                        diagnostics: 指派對象不在可指派名單中。
                        expression:
                          - Task.owner
  /Task/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    put:
      tags:
        - 工作與交班
      summary: 更新工作狀態
      operationId: updateTask
      description: |
        | 規則 | 內容 |
        | --- | --- |
        | BR-TASK-001 | 只有目前 `owner` 可更新 |
        | BR-TASK-002 | 結案必填完成證據（`output`）；若 `focus` 是檢驗報告，該報告必須**已回報且已有判讀紀錄** |
        | BR-TASK-003 | 狀態異動一律追加歷程，不覆寫 |

        BR-TASK-002 的用意：待回結果尚未完成處理就不能結案，避免工作被形式上關掉。

        原型狀態對映：`open`→`requested`、`accepted`→`accepted`、`waiting`→`on-hold`、`done`→`completed`。
      parameters:
        - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Task'
            examples:
              example:
                summary: 結案並附完成證據
                value:
                  resourceType: Task
                  id: task-n-nt1
                  meta:
                    versionId: '3'
                    lastUpdated: '2026-08-31T18:45:03+07:00'
                  status: completed
                  intent: order
                  description: 追蹤 WBC 複驗結果並回報主責醫師
                  for:
                    reference: Patient/p1
                    display: Trần Bảo An
                  encounter:
                    reference: Encounter/enc-p1
                  focus:
                    reference: DiagnosticReport/dr-p1-cbc
                  owner:
                    reference: PractitionerRole/hanlt
                    display: 護理師 Lê Thu Hà
                  authoredOn: '2026-08-31T09:10:00+07:00'
                  note:
                    - time: '2026-08-31T18:45:03+07:00'
                      text: 日班交班轉移給夜班
                  output:
                    - type:
                        text: 完成證據
                      valueString: 18:40 已向主責醫師口頭回報，醫師指示明晨複驗。
      responses:
        '200':
          description: 已更新
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 已結案
                  value:
                    resourceType: Task
                    id: task-n-nt1
                    meta:
                      versionId: '4'
                      lastUpdated: '2026-08-31T18:41:12+07:00'
                    status: completed
                    intent: order
                    description: 追蹤 WBC 複驗結果並回報主責醫師
                    for:
                      reference: Patient/p1
                      display: Trần Bảo An
                    encounter:
                      reference: Encounter/enc-p1
                    focus:
                      reference: DiagnosticReport/dr-p1-cbc
                    owner:
                      reference: PractitionerRole/hanlt
                      display: 護理師 Lê Thu Hà
                    authoredOn: '2026-08-31T09:10:00+07:00'
                    note:
                      - time: '2026-08-31T18:45:03+07:00'
                        text: 日班交班轉移給夜班
                    output:
                      - type:
                          text: 完成證據
                        valueString: 18:40 已向主責醫師口頭回報，醫師指示明晨複驗。
        '403':
          description: |
            已認證但無權（角色限制；寫入時病人不在照護範圍；照會醫師讀取沒有照會單的病人）。

            **不因無權而回 404**——權限問題一律 403，資源不存在才 404。
            但搜尋是例外：一律回較少的結果而非 403，避免探測病人是否存在。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 不是這件工作的負責人
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: forbidden
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: TASK-NOT-OWNER
                        diagnostics: 只有工作負責人可以變更狀態。如需接手請先承接。
        '409':
          description: |
            版本衝突，或目前狀態不允許此操作。

            版本衝突時必須帶目前版本，讓客戶端就地合併——**內容不會被覆寫**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 來源報告尚未判讀
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: business-rule
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: SOURCE-NOT-PROCESSED
                        diagnostics: 來源報告尚未有判讀紀錄，不可結案。
        '412':
          description: 缺少 `If-Match` 標頭
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 缺 If-Match
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: PRECONDITION-REQUIRED
                        diagnostics: 缺少 If-Match 標頭。所有可寫互動都必須帶目前版本，不接受盲目覆寫。
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 結案沒附證據
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: EVIDENCE-REQUIRED
                        diagnostics: 結案必須填寫完成證據。
                        expression:
                          - Task.output
  /Provenance:
    get:
      tags:
        - 溯源與稽核
      summary: 搜尋溯源紀錄
      operationId: searchProvenance
      parameters:
        - name: target
          in: query
          schema:
            type: string
          description: 被溯源的資源
        - name: agent
          in: query
          schema:
            type: string
        - name: recorded
          in: query
          schema:
            type: string
        - name: activity
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 某份報告的已閱與判讀紀錄
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 1
                    link:
                      - relation: self
                        url: https://icu.emr.local/fhir/r4/Provenance?target=DiagnosticReport/dr-p1-cbc&_sort=-recorded
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/Provenance/prov-review-ma-mr-p3-oresol-1
                        resource:
                          resourceType: Provenance
                          id: prov-review-ma-mr-p3-oresol-1
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-08-31T10:12:05+07:00'
                          extension:
                            - url: http://icu.emr.local/StructureDefinition/reviewOutcome
                              valueCode: reviewed
                            - url: http://icu.emr.local/StructureDefinition/reviewNote
                              valueString: 對照醫囑劑量與執行時間，無差異。
                          target:
                            - reference: MedicationAdministration/ma-mr-p3-oresol-1
                          recorded: '2026-08-31T10:12:05+07:00'
                          activity:
                            coding:
                              - system: http://icu.emr.local/CodeSystem/provenance-activity
                                code: clinical-review
                                display: 臨床核對
                          agent:
                            - type:
                                coding:
                                  - system: http://terminology.hl7.org/CodeSystem/provenance-participant-type
                                    code: verifier
                              who:
                                reference: PractitionerRole/thucdv
                                display: 博士醫師 Đặng Văn Thức
                          entity:
                            - role: source
                              what:
                                reference: MedicationRequest/mr-p1-mero/_history/3
                        search:
                          mode: match
    post:
      tags:
        - 溯源與稽核
      summary: 建立溯源紀錄
      operationId: createProvenance
      description: |
        **僅新增，永不修改。**

        ### activity 值域

        | code | 用途 | 系統 |
        | --- | --- | --- |
        | `READ` | 記錄已閱（真正的讀取動作） | `v3-DataOperation` |
        | `clinical-review` | 判讀結果／核對護理執行 | 本地 |
        | `handover-receive` | 交班接收 | 本地 |
        | `roster-confirm` | 照護名單確認 | 本地 |
        | `sign` | 簽署 | 本地 |

        「判讀」「核對」「交班接收」「名單確認」是**臨床業務動作，不是資料操作**，
        `v3-DataOperation` 沒有對應碼（該系統只有 OPERATE／CREATE／READ／UPDATE／DELETE／APPEND／MODIFYSTATUS 等），
        因此改用本地 CodeSystem，不硬套語義不符的標準碼。

        ### 相關規則

        - BR-MED-008／BR-RPT-003：`clinical-review` 的 `reviewNote` 必填，前次核對結論全部保留。
        - BR-RPT-002：記錄已閱／判讀時，報告必須已回報且來源未缺漏。
        - BR-RPT-004：**已閱、判讀、工作結案彼此獨立**；任一項完成不影響其他待回項目。
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Provenance'
            examples:
              executionReview:
                $ref: '#/components/examples/ProvenanceExecutionReview'
      responses:
        '201':
          description: 已建立
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 已記錄核對
                  value:
                    resourceType: Provenance
                    id: prov-review-ma-mr-p3-oresol-1
                    meta:
                      versionId: '1'
                      lastUpdated: '2026-08-31T10:12:05+07:00'
                    extension:
                      - url: http://icu.emr.local/StructureDefinition/reviewOutcome
                        valueCode: reviewed
                      - url: http://icu.emr.local/StructureDefinition/reviewNote
                        valueString: 對照醫囑劑量與執行時間，無差異。
                    target:
                      - reference: MedicationAdministration/ma-mr-p3-oresol-1
                    recorded: '2026-08-31T10:12:05+07:00'
                    activity:
                      coding:
                        - system: http://icu.emr.local/CodeSystem/provenance-activity
                          code: clinical-review
                          display: 臨床核對
                    agent:
                      - type:
                          coding:
                            - system: http://terminology.hl7.org/CodeSystem/provenance-participant-type
                              code: verifier
                        who:
                          reference: PractitionerRole/thucdv
                          display: 博士醫師 Đặng Văn Thức
                    entity:
                      - role: source
                        what:
                          reference: MedicationRequest/mr-p1-mero/_history/3
        '403':
          description: |
            已認證但無權（角色限制；寫入時病人不在照護範圍；照會醫師讀取沒有照會單的病人）。

            **不因無權而回 404**——權限問題一律 403，資源不存在才 404。
            但搜尋是例外：一律回較少的結果而非 403，避免探測病人是否存在。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 角色不可核對
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: forbidden
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: ROLE-DOCTOR-ONLY
                        diagnostics: 護理執行的核對僅限醫師記錄。
        '409':
          description: |
            版本衝突，或目前狀態不允許此操作。

            版本衝突時必須帶目前版本，讓客戶端就地合併——**內容不會被覆寫**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 目標資源不存在或已被標為誤建
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: business-rule
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: REPORT-NOT-AVAILABLE
                        diagnostics: 目標資源目前不可判讀，請重新整理後再試。
        '422':
          description: |
            資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
            `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 判定有差異但沒寫依據
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: required
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: REVIEW-NOTE-REQUIRED
                        diagnostics: 核對結論為「有差異」時必須填寫依據說明。
                        expression:
                          - Provenance.extension
  /AuditEvent:
    get:
      tags:
        - 溯源與稽核
      summary: 查詢稽核軌跡（限稽核角色）
      operationId: searchAuditEvent
      description: |
        伺服器自動產生，每個請求一筆，**包含讀取**（`action=R`）。失敗的請求同樣記錄（尤其 403）。

        `agent.network.address` 由伺服器從連線取得，客戶端送的值忽略——
        對應規格中 `ipAddress`／`computerName`「不可手打冒充」的要求。

        臨床帳號不可查詢此端點。
      parameters:
        - $ref: '#/components/parameters/patient'
        - name: agent
          in: query
          schema:
            type: string
        - name: date
          in: query
          schema:
            type: string
        - name: action
          in: query
          schema:
            type: string
            enum:
              - C
              - R
              - U
              - D
              - E
        - name: outcome
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: 搜尋結果（`Bundle.type = searchset`）
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
              examples:
                example:
                  summary: 某病人的存取軌跡（伺服器產生，不可寫入）
                  value:
                    resourceType: Bundle
                    type: searchset
                    total: 128
                    link:
                      - relation: self
                        url: https://icu.emr.local/fhir/r4/AuditEvent?patient=Patient/p1&date=ge2026-08-31&_count=20
                      - relation: next
                        url: >-
                          https://icu.emr.local/fhir/r4/AuditEvent?patient=Patient/p1&date=ge2026-08-31&_count=20&_page=2
                    entry:
                      - fullUrl: https://icu.emr.local/fhir/r4/AuditEvent/ae-0831-090233
                        resource:
                          resourceType: AuditEvent
                          id: ae-0831-090233
                          meta:
                            versionId: '1'
                            lastUpdated: '2026-08-31T09:02:33+07:00'
                          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:02:33+07:00'
                          outcome: '0'
                          agent:
                            - who:
                                reference: PractitionerRole/nhungtt
                                display: 護理師 Phạm Thị Hồng Nhung
                              requestor: true
                              network:
                                address: 10.20.30.41
                                type: '2'
                          source:
                            observer:
                              display: ICU EMR FHIR API
                          entity:
                            - what:
                                reference: MedicationAdministration/ma-mr-p3-oresol-1
                              type:
                                system: http://terminology.hl7.org/CodeSystem/audit-entity-type
                                code: '2'
                            - what:
                                reference: Patient/p1
                                display: Trần Bảo An
                              type:
                                system: http://terminology.hl7.org/CodeSystem/audit-entity-type
                                code: '1'
                        search:
                          mode: match
        '403':
          description: |
            已認證但無權（角色限制；寫入時病人不在照護範圍；照會醫師讀取沒有照會單的病人）。

            **不因無權而回 404**——權限問題一律 403，資源不存在才 404。
            但搜尋是例外：一律回較少的結果而非 403，避免探測病人是否存在。
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              examples:
                example:
                  summary: 一般臨床帳號不可查閱全院稽核
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: forbidden
                        details:
                          coding:
                            - system: http://icu.emr.local/CodeSystem/api-error
                              code: ROLE-DOCTOR-ONLY
                        diagnostics: 稽核紀錄查詢需具備稽核角色。
  /ValueSet/{valueSetId}/$expand:
    parameters:
      - name: valueSetId
        in: path
        required: true
        schema:
          type: string
          enum:
            - his-medication
            - his-service
            - his-route
            - his-unit
            - icd-10
            - diet
            - supply
    get:
      tags:
        - 目錄
      summary: 展開 B 目錄品項
      operationId: expandValueSet
      description: |
        B 目錄共 31,146 筆（藥品 2,935／服務 7,892／ICD-10 15,994／途徑 62／單位 216／飲食 285／耗材 3,752）。
        品項查詢走 `$expand`，**不走資源搜尋**。

        - `ValueSet.version` 帶目錄版本（例：`20260831-b1`）。
        - 回應帶 `Cache-Control: max-age=3600`。
        - **中文譯名未核定**：`display` 一律填來源原文（越文／英文），
          譯名放 `extension[reviewTranslation]`，避免未核定譯名被當正式名稱往下游傳。
        - 停用品項（`active=false`）會回傳但標記為 inactive，不得用於新開立（BR-CAT-001）。
      parameters:
        - name: filter
          in: query
          schema:
            type: string
          description: 關鍵字，支援代碼、越文、英文模糊比對
        - name: count
          in: query
          schema:
            type: integer
            default: 20
            maximum: 200
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: 展開結果
          headers:
            Cache-Control:
              schema:
                type: string
              example: max-age=3600
          content:
            application/fhir+json:
              schema:
                type: object
                additionalProperties: true
              examples:
                example:
                  summary: 藥品目錄查詢（帶目錄版本，可快取一小時）
                  value:
                    resourceType: ValueSet
                    id: his-medication
                    url: http://icu.emr.local/ValueSet/his-medication
                    version: 20260831-b1
                    status: active
                    expansion:
                      identifier: urn:uuid:7b1c2f30-0000-0000-0000-000000000001
                      timestamp: '2026-08-31T08:00:00+07:00'
                      total: 3
                      offset: 0
                      parameter:
                        - name: filter
                          valueString: paracetamol
                        - name: count
                          valueInteger: 20
                      contains:
                        - system: http://icu.emr.local/CodeSystem/his-medication
                          code: '50631'
                          display: Efferalgan 300 mg (Paracetamol)
                        - system: http://icu.emr.local/CodeSystem/his-medication
                          code: '50632'
                          display: Paracetamol 500 mg viên
                        - system: http://icu.emr.local/CodeSystem/his-medication
                          code: '50640'
                          display: Paracetamol 150 mg/100 ml truyền TM
                          inactive: true
components:
  securitySchemes:
    smartOnFhir:
      type: oauth2
      description: |
        OAuth 2.0 ＋ SMART on FHIR。存取權杖必須帶：

        | Claim | 內容 |
        | --- | --- |
        | `sub` | 使用者識別 |
        | `fhirUser` | `PractitionerRole/{id}`，決定角色與科別 |
        | `shift` | 班別代碼，決定「本班」時間窗與交班對象 |

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

        除 scope 外，伺服器對每個請求另做病人範圍（compartment）檢查。
      flows:
        authorizationCode:
          authorizationUrl: https://auth.icu.local/authorize
          tokenUrl: https://auth.icu.local/token
          scopes:
            user/Patient.rs: 讀取與搜尋病人
            user/Encounter.rs: 讀取與搜尋就醫事件
            user/MedicationRequest.cru: 開立與維護藥物醫囑（主責醫師）
            user/MedicationRequest.rs: 讀取藥物醫囑（護理師）
            user/MedicationAdministration.cs: 記錄給藥執行（護理師）
            user/ServiceRequest.cru: 開立與維護醫令（主責醫師）
            user/Observation.crs: 記錄與讀取量測（護理師）
            user/Observation.rs: 讀取量測（醫師）
            user/DiagnosticReport.rs: 讀取檢驗報告
            user/Composition.cru: 撰寫與維護病歷文件
            user/Composition.rs: 唯讀病歷（照會醫師）
            user/Task.cru: 臨床工作
            user/Provenance.cs: 建立溯源紀錄
            user/Communication.cs: 必要溝通
            user/Condition.cru: 診斷管理（主責醫師）
            user/Goal.cru: 查房問題與目標（主責醫師）
            user/CarePlan.cs: 照顧重點
            system/DiagnosticReport.cu: 整合服務落地檢驗結果
            system/Patient.cu: 整合服務同步病人
            system/Encounter.cu: 整合服務同步就醫事件
  parameters:
    id:
      name: id
      in: path
      required: true
      description: 資源的 EMR 內部主鍵。**絕不等於任何 HIS 號碼。**
      schema:
        type: string
    patient:
      name: patient
      in: query
      description: 病人 Reference，例 `Patient/abc`
      schema:
        type: string
    encounter:
      name: encounter
      in: query
      schema:
        type: string
    count:
      name: _count
      in: query
      description: 每頁筆數。分頁一律跟隨 `Bundle.link[next]` 的 URL，不得自行拼 offset。
      schema:
        type: integer
        default: 20
        maximum: 200
    sort:
      name: _sort
      in: query
      schema:
        type: string
    include:
      name: _include
      in: query
      description: 一併帶回被引用的資源，減少往返
      schema:
        type: string
    revinclude:
      name: _revinclude
      in: query
      description: 一併帶回反向引用本資源的資源
      schema:
        type: string
    ifMatch:
      name: If-Match
      in: header
      required: true
      description: |
        樂觀鎖，值為讀取時取得的 `ETag`（例 `W/"4"`）。
        **缺少時直接回 `412`**，不允許盲目覆寫。
      schema:
        type: string
      example: W/"4"
    ifNoneExist:
      name: If-None-Exist
      in: header
      description: |
        條件式建立。符合條件的資源已存在時回 `200`（回傳既有資源）而非 `201`。

        給藥劑次唯一性用：
        `identifier=http://icu.emr.local/CodeSystem/occurrence-id|M1-V1-D1&status=completed`
      schema:
        type: string
  headers:
    ETag:
      description: 資源版本，用於後續 `If-Match`
      schema:
        type: string
      example: W/"4"
    Location:
      description: 新建資源的 URL
      schema:
        type: string
  responses:
    SearchSet:
      description: 搜尋結果（`Bundle.type = searchset`）
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/Bundle'
    Created:
      description: 已建立
      headers:
        Location:
          $ref: '#/components/headers/Location'
        ETag:
          $ref: '#/components/headers/ETag'
      content:
        application/fhir+json:
          schema:
            type: object
            additionalProperties: true
    Updated:
      description: 已更新
      headers:
        ETag:
          $ref: '#/components/headers/ETag'
      content:
        application/fhir+json:
          schema:
            type: object
            additionalProperties: true
    BadRequest:
      description: 語法錯誤（JSON 壞掉、參數不合法）
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
    Unauthorized:
      description: 未認證或權杖失效
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
    Forbidden:
      description: |
        已認證但無權（角色限制；寫入時病人不在照護範圍；照會醫師讀取沒有照會單的病人）。

        **不因無權而回 404**——權限問題一律 403，資源不存在才 404。
        但搜尋是例外：一律回較少的結果而非 403，避免探測病人是否存在。
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
    NotFound:
      description: 資源不存在
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
    Conflict:
      description: |
        版本衝突，或目前狀態不允許此操作。

        版本衝突時必須帶目前版本，讓客戶端就地合併——**內容不會被覆寫**。
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
          example:
            resourceType: OperationOutcome
            issue:
              - severity: error
                code: conflict
                details:
                  text: currentVersionId=6
                diagnostics: 資源已被其他工作階段更新至 versionId=6。請重新讀取後合併，內容未被覆寫。
    PreconditionFailed:
      description: 缺少 `If-Match` 標頭
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
    BusinessRuleViolation:
      description: |
        資源結構合法但違反業務規則。`issue.details.coding.code` 是本院錯誤碼，
        `issue.diagnostics` 是**可直接顯示給臨床使用者的繁中訊息**。
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
    HisUnavailable:
      description: HIS 不可用
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
    HisTimeout:
      description: |
        HIS 逾時。本地醫囑仍持久化為已送出，`hisTransmissionStatus=unknown`，
        並產生人工查明 Task。**之後禁止自動重送。**
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
  schemas:
    Coding:
      type: object
      additionalProperties: true
      properties:
        system:
          type: string
        code:
          type: string
        display:
          type: string
          description: B 目錄品項一律填來源原文；中文譯名未核定，放 extension
    CodeableConcept:
      type: object
      additionalProperties: true
      properties:
        coding:
          type: array
          items:
            $ref: '#/components/schemas/Coding'
        text:
          type: string
    Identifier:
      type: object
      additionalProperties: true
      properties:
        use:
          type: string
        system:
          type: string
        value:
          type: string
    Reference:
      type: object
      additionalProperties: true
      properties:
        reference:
          type: string
          description: |
            資源參照。引用臨床來源時**必須帶版本**（例 `Composition/abc/_history/2`），
            這樣引用當時看到的內容不會被後來的更正改掉。
          example: MedicationRequest/8f3a/_history/3
        display:
          type: string
    Quantity:
      type: object
      additionalProperties: true
      properties:
        value:
          type: number
        unit:
          type: string
        system:
          type: string
        code:
          type: string
    Meta:
      type: object
      additionalProperties: true
      properties:
        versionId:
          type: string
        lastUpdated:
          type: string
          format: date-time
        source:
          type: string
          description: 這筆資料的來源說明（示範資料會註明是虛構的）。沒有來源說明時不送這個欄位
    Extension:
      type: object
      additionalProperties: true
      properties:
        url:
          type: string
    ApiErrorCode:
      type: string
      description: 本院錯誤碼（`system = http://icu.emr.local/CodeSystem/api-error`）
      enum:
        - UNKNOWN-ACTOR
        - ROLE-DOCTOR-ONLY
        - ROLE-NURSE-ONLY
        - CONSULT-READ-ONLY
        - ACTOR-NOT-ASSIGNABLE
        - PATIENT-REQUIRED
        - PATIENT-OUT-OF-SCOPE
        - ENCOUNTER-MISMATCH
        - ROSTER-NOT-CONFIRMED
        - SOURCE-PATIENT-MISMATCH
        - READ-ONLY-SOURCE
        - PROGRESS-NOTE-REQUIRED
        - SIGN-OWN-DRAFT-ONLY
        - SUBMIT-STATE-INVALID
        - HIS-RESPONSE-INVALID
        - ORDER-IMMUTABLE-AFTER-SUBMIT
        - RESEND-BLOCKED-UNKNOWN
        - CODE-REQUIRED
        - ORDER-NOT-EXECUTABLE
        - FIVE-RIGHTS-INCOMPLETE
        - VARIANCE-REASON-REQUIRED
        - DOSE-ALREADY-ADMINISTERED
        - TIME-OUT-OF-ORDER-PERIOD
        - ACTUAL-VALUE-REQUIRED
        - REVIEW-NOTE-REQUIRED
        - VALUE-INVALID
        - BP-COMPONENTS-REQUIRED
        - ZERO-AS-MISSING
        - INFUSION-SOURCE-REQUIRED
        - REPORT-NOT-AVAILABLE
        - SECTION-REQUIRED
        - SIGNED-IMMUTABLE
        - AMEND-REASON-REQUIRED
        - NO-COPYABLE-PROGRESS
        - CATALOG-INACTIVE
        - CATALOG-CHANGED
        - TASK-NOT-OWNER
        - EVIDENCE-REQUIRED
        - SOURCE-NOT-PROCESSED
        - SUMMARY-REQUIRED
        - HANDOVER-SUPERSEDED
        - HANDOVER-ROLE-MISMATCH
        - HANDOVER-ALREADY-RECEIVED
        - ASSIGNEE-INVALID
        - CONSULT-NOT-ASSIGNEE
        - CONSULT-ALREADY-ANSWERED
        - RECOMMENDATION-REQUIRED
        - TIMEZONE-REQUIRED
        - TIME-INVALID
        - NOT-FOUND
        - PRECONDITION-REQUIRED
        - DISPENSE-STOCK-UNMAPPED
        - TRISTATE-NOT-RESOLVED
        - DOSE-UNIT-INCONSISTENT
        - ARCHIVE-ID-STALE
        - PERFORMING-PLACE-UNMAPPED
        - PRICE-TYPE-MISSING
        - SPECIMEN-CODE-UNMAPPED
        - PATIENT-TYPE-INVALID
        - HIS-UNAVAILABLE
        - HIS-TIMEOUT
    OperationOutcome:
      type: object
      required:
        - resourceType
        - issue
      additionalProperties: true
      properties:
        resourceType:
          type: string
          enum:
            - OperationOutcome
        issue:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - severity
              - code
              - details
              - diagnostics
            properties:
              severity:
                type: string
                enum:
                  - fatal
                  - error
                  - warning
                  - information
              code:
                type: string
                description: FHIR R4 標準 issue-type
                enum:
                  - invalid
                  - structure
                  - required
                  - value
                  - invariant
                  - security
                  - login
                  - forbidden
                  - processing
                  - not-supported
                  - duplicate
                  - not-found
                  - conflict
                  - transient
                  - timeout
                  - business-rule
                  - exception
                  - throttled
                  - informational
              details:
                type: object
                properties:
                  coding:
                    type: array
                    items:
                      type: object
                      properties:
                        system:
                          type: string
                          example: http://icu.emr.local/CodeSystem/api-error
                        code:
                          $ref: '#/components/schemas/ApiErrorCode'
                  text:
                    type: string
              diagnostics:
                type: string
                description: '**給臨床使用者看的繁中訊息**，可直接顯示在畫面。不是給工程師的堆疊訊息。'
              expression:
                type: array
                description: 欄位層級錯誤時必填，FHIRPath 路徑
                items:
                  type: string
    JsonPatch:
      type: array
      items:
        type: object
        required:
          - op
          - path
        properties:
          op:
            type: string
            enum:
              - add
              - remove
              - replace
              - move
              - copy
              - test
          path:
            type: string
          value: {}
    Bundle:
      type: object
      required:
        - resourceType
        - type
      additionalProperties: true
      properties:
        resourceType:
          type: string
          enum:
            - Bundle
        type:
          type: string
          enum:
            - searchset
            - transaction
            - transaction-response
            - batch
            - batch-response
            - history
            - collection
        total:
          type: integer
        link:
          type: array
          description: 分頁連結。客戶端一律跟隨 `next`，不得自行拼 offset。
          items:
            type: object
            properties:
              relation:
                type: string
                enum:
                  - self
                  - next
                  - previous
                  - first
                  - last
              url:
                type: string
        entry:
          type: array
          items:
            type: object
            properties:
              fullUrl:
                type: string
              resource:
                type: object
                additionalProperties: true
              search:
                type: object
                properties:
                  mode:
                    type: string
                    enum:
                      - match
                      - include
                      - outcome
              request:
                type: object
                description: transaction／batch 必填
                properties:
                  method:
                    type: string
                    enum:
                      - GET
                      - POST
                      - PUT
                      - PATCH
                      - DELETE
                  url:
                    type: string
                  ifMatch:
                    type: string
                  ifNoneExist:
                    type: string
              response:
                type: object
                properties:
                  status:
                    type: string
                  location:
                    type: string
                  etag:
                    type: string
    Patient:
      type: object
      required:
        - resourceType
      additionalProperties: true
      description: |
        **HIS 唯讀。** 臨床帳號寫入一律回 `422 READ-ONLY-SOURCE`。

        年齡不落地——由客戶端從 `birthDate` 於檢視時點計算。
      properties:
        resourceType:
          type: string
          enum:
            - Patient
        id:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        identifier:
          type: array
          items:
            $ref: '#/components/schemas/Identifier'
        name:
          type: array
          items:
            type: object
            additionalProperties: true
        gender:
          type: string
          enum:
            - male
            - female
            - other
            - unknown
        birthDate:
          type: string
          format: date
        contact:
          type: array
          description: 監護人（`relationship[0].text = 監護人`，`name.text` 如「母 · Lê Thị Hoa」）。正式欄位對照 A2 的家屬關係人。
          items:
            type: object
            additionalProperties: true
        extension:
          type: array
          description: |
            | url 尾段 | 用途 |
            | --- | --- |
            | `insuranceText` | 健保身分文字（例：健保 — 6 歲以下兒童 · TE1 …），D1 未定版前暫放這裡 |
          items:
            $ref: '#/components/schemas/Extension'
    Flag:
      type: object
      required:
        - resourceType
        - status
        - category
        - code
        - subject
      additionalProperties: true
      description: 病人清單上的特殊註記。`code.text` 是顯示文字；`extension[flagTone]` 是畫面色調（red／amber／purple／blue／teal／gray）。
      properties:
        resourceType:
          type: string
          enum:
            - Flag
        id:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        status:
          type: string
          enum:
            - active
            - inactive
            - entered-in-error
        category:
          type: array
          description: >-
            `http://icu.emr.local/CodeSystem/flag-category`：allergy | isolation | device | treatment | risk | severity |
            status | monitoring
          items:
            $ref: '#/components/schemas/CodeableConcept'
        code:
          allOf:
            - $ref: '#/components/schemas/CodeableConcept'
          description: severity 類：coding.code = red | amber | teal；其餘只有 text
        subject:
          $ref: '#/components/schemas/Reference'
        encounter:
          $ref: '#/components/schemas/Reference'
        period:
          type: object
          additionalProperties: true
        extension:
          type: array
          items:
            $ref: '#/components/schemas/Extension'
    Practitioner:
      type: object
      required:
        - resourceType
      additionalProperties: true
      description: 人員（HIS／人事唯讀）。`identifier[staff-account]` 是帳號；`name[0].prefix` 是職稱。
      properties:
        resourceType:
          type: string
          enum:
            - Practitioner
        id:
          type: string
        identifier:
          type: array
          items:
            $ref: '#/components/schemas/Identifier'
        name:
          type: array
          items:
            type: object
            additionalProperties: true
    PractitionerRole:
      type: object
      required:
        - resourceType
      additionalProperties: true
      description: 人員在本院的角色：`code` 職稱（doctor／nurse／consultant）、`specialty`／`location` 科別、`extension[shift]` 班別。
      properties:
        resourceType:
          type: string
          enum:
            - PractitionerRole
        id:
          type: string
        practitioner:
          $ref: '#/components/schemas/Reference'
        code:
          type: array
          items:
            $ref: '#/components/schemas/CodeableConcept'
        specialty:
          type: array
          items:
            $ref: '#/components/schemas/CodeableConcept'
        location:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
        extension:
          type: array
          items:
            $ref: '#/components/schemas/Extension'
    Condition:
      type: object
      required:
        - resourceType
        - code
        - subject
        - encounter
      additionalProperties: true
      description: >
        診斷與問題清單。`category`：admission／ward／discharge／problem；`verificationStatus`：confirmed／provisional／differential／refuted。


        | url 尾段 | 用途 |

        | --- | --- |

        | `diagnosisRole` | primary／comorbidity／complication |

        | `diagnosisEvidence` | 依據（例：都卜勒心臟超音波・檢驗） |
      properties:
        resourceType:
          type: string
          enum:
            - Condition
        id:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        clinicalStatus:
          $ref: '#/components/schemas/CodeableConcept'
        verificationStatus:
          $ref: '#/components/schemas/CodeableConcept'
        category:
          type: array
          items:
            $ref: '#/components/schemas/CodeableConcept'
        code:
          allOf:
            - $ref: '#/components/schemas/CodeableConcept'
          description: ICD-10：`coding[0].system = http://hl7.org/fhir/sid/icd-10`，代碼必須在 ValueSet/icd10 裡
        subject:
          $ref: '#/components/schemas/Reference'
        encounter:
          $ref: '#/components/schemas/Reference'
        recordedDate:
          type: string
          format: date-time
        recorder:
          $ref: '#/components/schemas/Reference'
        note:
          type: array
          items:
            type: object
            additionalProperties: true
        extension:
          type: array
          items:
            $ref: '#/components/schemas/Extension'
    Goal:
      type: object
      required:
        - resourceType
        - lifecycleStatus
        - description
        - subject
      additionalProperties: true
      description: 本日問題與目標。R4 Goal 沒有 encounter，就醫事件放 `extension[goalEncounter]`；`addresses` 指向 Condition。
      properties:
        resourceType:
          type: string
          enum:
            - Goal
        id:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        lifecycleStatus:
          type: string
          enum:
            - proposed
            - active
            - completed
            - cancelled
            - entered-in-error
        description:
          $ref: '#/components/schemas/CodeableConcept'
        subject:
          $ref: '#/components/schemas/Reference'
        target:
          type: array
          items:
            type: object
            additionalProperties: true
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
        expressedBy:
          $ref: '#/components/schemas/Reference'
        extension:
          type: array
          items:
            $ref: '#/components/schemas/Extension'
    Communication:
      type: object
      required:
        - resourceType
        - status
        - category
        - subject
        - encounter
        - payload
      additionalProperties: true
      description: 照會回覆（`category = consult-reply`，`basedOn` 指向照會單）與必要溝通（`essential`）。只新增不修改。
      properties:
        resourceType:
          type: string
          enum:
            - Communication
        id:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        status:
          type: string
          enum:
            - completed
            - entered-in-error
        category:
          type: array
          items:
            $ref: '#/components/schemas/CodeableConcept'
        priority:
          type: string
          enum:
            - routine
            - urgent
            - asap
            - stat
        basedOn:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
        subject:
          $ref: '#/components/schemas/Reference'
        encounter:
          $ref: '#/components/schemas/Reference'
        sent:
          type: string
          format: date-time
        sender:
          $ref: '#/components/schemas/Reference'
        recipient:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
        payload:
          type: array
          items:
            type: object
            properties:
              contentString:
                type: string
    List:
      type: object
      required:
        - resourceType
        - status
        - mode
        - code
      additionalProperties: true
      description: >-
        個人常用（`code = favorites-personal`，`source` 是主人）／科常用（`favorites-dept`）。`entry[].item.identifier`：system 是目錄、value
        是代碼。
      properties:
        resourceType:
          type: string
          enum:
            - List
        id:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        status:
          type: string
          enum:
            - current
            - retired
            - entered-in-error
        mode:
          type: string
          enum:
            - working
        title:
          type: string
        code:
          $ref: '#/components/schemas/CodeableConcept'
        source:
          $ref: '#/components/schemas/Reference'
        entry:
          type: array
          items:
            type: object
            additionalProperties: true
    PlanDefinition:
      type: object
      required:
        - resourceType
        - status
      additionalProperties: true
      description: 套組（`type = order-set`）與衛教組套（`education-set`）。院方核准前 `status = draft`，唯讀；展開到待開清單後每項仍各自簽署。
      properties:
        resourceType:
          type: string
          enum:
            - PlanDefinition
        id:
          type: string
        status:
          type: string
          enum:
            - draft
            - active
            - retired
        type:
          $ref: '#/components/schemas/CodeableConcept'
        title:
          type: string
        description:
          type: string
        action:
          type: array
          items:
            type: object
            additionalProperties: true
    CareTeam:
      type: object
      required:
        - resourceType
        - status
      additionalProperties: true
      properties:
        resourceType:
          type: string
          enum:
            - CareTeam
        id:
          type: string
        status:
          type: string
          enum:
            - proposed
            - active
            - suspended
            - inactive
            - entered-in-error
        subject:
          $ref: '#/components/schemas/Reference'
        encounter:
          $ref: '#/components/schemas/Reference'
        participant:
          type: array
          items:
            type: object
            additionalProperties: true
            properties:
              member:
                $ref: '#/components/schemas/Reference'
              role:
                type: array
                items:
                  $ref: '#/components/schemas/CodeableConcept'
        extension:
          type: array
          description: >
            | url 尾段 | 用途 |

            | --- | --- |

            | `assignmentSource` | 分派來源說明 |

            | `rosterConfirmation` | **唯讀**：誰（`by`）在何時（`at`）確認過這份名單；權威仍是 activity = `roster-confirm` 的
            `Provenance`。同一份名單可被不同班別各自確認 |
          items:
            $ref: '#/components/schemas/Extension'
    MedicationRequest:
      type: object
      required:
        - resourceType
        - status
        - intent
        - subject
      additionalProperties: true
      description: |
        ### 三軸狀態

        | 軸 | 表達 |
        | --- | --- |
        | 臨床狀態 | `status`：`draft` → `active` → `stopped`／`cancelled` |
        | 本地簽署 | 存在指向該版本的 `Provenance.signature` |
        | HIS 傳輸 | `extension[hisTransmissionStatus]` |

        **只有 `status=active` ＋ `hisTransmissionStatus=accepted` 才是護理端可執行狀態。**
      properties:
        resourceType:
          type: string
          enum:
            - MedicationRequest
        id:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        extension:
          type: array
          description: |
            本地擴充：

            | url 尾段 | 型別 | 用途 |
            | --- | --- | --- |
            | `hisTransmissionStatus` | code | `notSent`／`sent`／`accepted`／`rejected`／`unknown` |
            | `hisTransmissionEvent` | complex | `requestId`、`sentAt`、`respondedAt`、`message` |
            | `catalogSnapshot` | complex | 開立當下的目錄品項快照（`catalogVersion`、`sourceSHA256`） |
            | `orderSet` | Identifier | 套組來源 |
            | `doseSafetyDisplay` | code | 劑量安全**畫面示例**的選擇結果，非臨床判定 |
            | `signedAt` | instant | **唯讀**：本地簽署軸的時間；權威仍是 `Provenance.signature` |
          items:
            $ref: '#/components/schemas/Extension'
        identifier:
          type: array
          description: HIS 處方號（`his-prescription-number`）與每行藥品碼（`his-medication-request-id`）。取消處方必須用**處方號**，不是每行碼。
          items:
            $ref: '#/components/schemas/Identifier'
        status:
          type: string
          enum:
            - draft
            - active
            - on-hold
            - cancelled
            - completed
            - stopped
            - entered-in-error
            - unknown
        intent:
          type: string
          enum:
            - proposal
            - plan
            - order
            - original-order
        medicationCodeableConcept:
          allOf:
            - $ref: '#/components/schemas/CodeableConcept'
          description: 必須帶 `coding.system` ＋ `code`，且來自已同步目錄。只給 `text` 回 422（BR-MED-001）。
        subject:
          $ref: '#/components/schemas/Reference'
        encounter:
          $ref: '#/components/schemas/Reference'
        authoredOn:
          type: string
          format: date-time
          description: 必須帶時區位移
        requester:
          allOf:
            - $ref: '#/components/schemas/Reference'
          description: 一律取自存取權杖，客戶端送的值被忽略（BR-AUTH-006）
        supportingInformation:
          type: array
          description: 病程來源，簽署時寫入**帶版本**的 Reference（BR-ORD-003）
          items:
            $ref: '#/components/schemas/Reference'
        dosageInstruction:
          type: array
          items:
            type: object
            additionalProperties: true
            properties:
              text:
                type: string
              timing:
                type: object
                additionalProperties: true
              route:
                allOf:
                  - $ref: '#/components/schemas/CodeableConcept'
                description: 須與 HIS 藥品目錄一致，**不能用本地 PO/IV 假定等值**
              doseAndRate:
                type: array
                items:
                  type: object
                  additionalProperties: true
                  properties:
                    doseQuantity:
                      $ref: '#/components/schemas/Quantity'
                    rateQuantity:
                      allOf:
                        - $ref: '#/components/schemas/Quantity'
                      description: 需單位與濃度，**不把 mg/kg/min 直接當 mL/h**
    MedicationAdministration:
      type: object
      required:
        - resourceType
        - status
        - subject
        - effectiveDateTime
      additionalProperties: true
      description: '**建立後不可修改。** 沒有紀錄 ≠ `not-done`——沒建立資源就是「尚未記錄」。'
      properties:
        resourceType:
          type: string
          enum:
            - MedicationAdministration
        id:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        extension:
          type: array
          description: |
            `verificationChecklist`（五對人工核對）：
            `rightPatient`／`rightMedication`／`rightDose`／`rightRoute`／`rightTime` 五個 boolean ＋ `checkedBy`。
            `status=completed` 時五項必須全為 `true`（BR-MED-003）。
          items:
            $ref: '#/components/schemas/Extension'
        identifier:
          type: array
          description: 劑次識別碼（`occurrence-id`），用於 `If-None-Exist` 保證同劑次至多一筆完成紀錄
          items:
            $ref: '#/components/schemas/Identifier'
        status:
          type: string
          enum:
            - in-progress
            - not-done
            - on-hold
            - completed
            - entered-in-error
            - stopped
            - unknown
          description: 原型對映：`done`→`completed`、`held`→`on-hold`、`notDone`→`not-done`
        statusReason:
          type: array
          description: '`not-done` 時必填'
          items:
            $ref: '#/components/schemas/CodeableConcept'
        medicationCodeableConcept:
          $ref: '#/components/schemas/CodeableConcept'
        subject:
          $ref: '#/components/schemas/Reference'
        context:
          $ref: '#/components/schemas/Reference'
        effectiveDateTime:
          type: string
          format: date-time
          description: 實際執行時間（護理師填）。與伺服器產生的記錄時間分開儲存（BR-TIME-003）
        performer:
          type: array
          items:
            type: object
            additionalProperties: true
        request:
          allOf:
            - $ref: '#/components/schemas/Reference'
          description: 來源醫囑，**帶版本**
        dosage:
          type: object
          additionalProperties: true
          description: '`completed` 時 `dose` 與 `route` 必填，不得以醫囑預定值當事實（BR-MED-007）'
          properties:
            text:
              type: string
            route:
              $ref: '#/components/schemas/CodeableConcept'
            dose:
              $ref: '#/components/schemas/Quantity'
            rateQuantity:
              $ref: '#/components/schemas/Quantity'
        note:
          type: array
          description: 實際值與醫囑不同、或狀態非 `completed` 時必填（BR-MED-004）
          items:
            type: object
            additionalProperties: true
    ServiceRequest:
      type: object
      required:
        - resourceType
        - status
        - intent
        - subject
      additionalProperties: true
      properties:
        resourceType:
          type: string
          enum:
            - ServiceRequest
        id:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        identifier:
          type: array
          description: '`order-number`（整張需求單）與 `service-request-number`（單內一行）。**兩者不可互相代入。**'
          items:
            $ref: '#/components/schemas/Identifier'
        status:
          type: string
          enum:
            - draft
            - active
            - on-hold
            - revoked
            - completed
            - entered-in-error
            - unknown
        intent:
          type: string
          enum:
            - proposal
            - plan
            - order
            - original-order
        category:
          type: array
          description: 跨科照會用 `consultation`
          items:
            $ref: '#/components/schemas/CodeableConcept'
        priority:
          type: string
          enum:
            - routine
            - urgent
            - asap
            - stat
          description: 送 HIS 建立時對映為 severity 1／2／3；**修改時不送**（Q-05）
        code:
          $ref: '#/components/schemas/CodeableConcept'
        subject:
          $ref: '#/components/schemas/Reference'
        encounter:
          $ref: '#/components/schemas/Reference'
        authoredOn:
          type: string
          format: date-time
        requester:
          $ref: '#/components/schemas/Reference'
        performer:
          type: array
          description: 跨科照會的受照會醫師
          items:
            $ref: '#/components/schemas/Reference'
        orderDetail:
          type: array
          description: |
            補充的醫令資訊，以 `coding.code` 區分：
            `route` = 執行方式原文（例：床邊）、`quantity` = 數量原文（例：一次）。
            結構化數量仍在 `quantityInteger`；這裡保留的是**給人看的原文**。
          items:
            $ref: '#/components/schemas/CodeableConcept'
        occurrenceTiming:
          type: object
          additionalProperties: true
          description: '`code.text` 放頻次原文（例：本次示範）'
        occurrencePeriod:
          type: object
          additionalProperties: true
          description: 醫令的有效期間
          properties:
            start:
              type: string
              format: date-time
            end:
              type: string
              format: date-time
        supportingInfo:
          type: array
          description: 病程來源，**必須帶版本**（`Composition/…/_history/n`，BR-ORD-001）
          items:
            $ref: '#/components/schemas/Reference'
        extension:
          type: array
          description: |
            `hisTransmissionStatus`（HIS 傳輸軸）與 `signedAt`（本地簽署軸，唯讀）。
            三軸狀態不可合併成單一 `status`。
          items:
            $ref: '#/components/schemas/Extension'
        specimen:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
        bodySite:
          type: array
          description: 採樣／拍攝部位。**不混用檢體類型。**
          items:
            $ref: '#/components/schemas/CodeableConcept'
    Procedure:
      type: object
      required:
        - resourceType
        - status
        - subject
      additionalProperties: true
      properties:
        resourceType:
          type: string
          enum:
            - Procedure
        id:
          type: string
        status:
          type: string
          enum:
            - preparation
            - in-progress
            - not-done
            - on-hold
            - stopped
            - completed
            - entered-in-error
            - unknown
        basedOn:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
        subject:
          $ref: '#/components/schemas/Reference'
        encounter:
          $ref: '#/components/schemas/Reference'
        performedDateTime:
          type: string
          format: date-time
        performer:
          type: array
          items:
            type: object
            additionalProperties: true
        statusReason:
          $ref: '#/components/schemas/CodeableConcept'
    DiagnosticReport:
      type: object
      required:
        - resourceType
        - status
        - code
      additionalProperties: true
      description: |
        **HIS 唯讀。** 每個檢驗指標必須是獨立的 `Observation`（由 `result` 引用），
        不可塞進 `conclusion` 的文字——趨勢圖需要逐指標時間序列。

        無關聯醫囑時 `basedOn` 留空並在 UI 顯示「未提供來源醫囑關聯」，
        **不按名稱猜測配對**（名稱相近就自動綁定會產生錯誤的醫囑－結果對應）。
      properties:
        resourceType:
          type: string
          enum:
            - DiagnosticReport
        id:
          type: string
        identifier:
          type: array
          items:
            $ref: '#/components/schemas/Identifier'
        status:
          type: string
          enum:
            - registered
            - partial
            - preliminary
            - final
            - amended
            - corrected
            - appended
            - cancelled
            - entered-in-error
            - unknown
          description: '`registered` = 待回。醫囑被 HIS 接受時自動建立（BR-ORD-008）。重發用 `corrected`，舊版保留。'
        code:
          $ref: '#/components/schemas/CodeableConcept'
        subject:
          $ref: '#/components/schemas/Reference'
        encounter:
          $ref: '#/components/schemas/Reference'
        basedOn:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
        issued:
          type: string
          format: date-time
        specimen:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
        result:
          type: array
          description: 逐項檢驗指標
          items:
            $ref: '#/components/schemas/Reference'
        conclusion:
          type: string
          description: 待回時**不填**，不可預設「正常」
    Observation:
      type: object
      required:
        - resourceType
        - status
        - code
      additionalProperties: true
      description: |
        **建立後不可修改。**

        血壓必須用單一 Observation 的兩個 `component`（收縮 8480-6／TDL.0094、
        舒張 8462-4／TDL.0095），拆成兩筆會失去配對。

        已確認可用的 LOINC：心率 `8867-4`、體溫 `8310-5`、呼吸頻率 `9279-1`、
        SpO₂ `59408-5`、體重 `29463-7`。
        **檢驗指標字典（Q-02）與出入量項目（Q-03）在來源查不到對照，
        只帶院內／TDL 碼，不自行指派 LOINC。**
      properties:
        resourceType:
          type: string
          enum:
            - Observation
        id:
          type: string
        extension:
          type: array
          description: '`notCountedAsIntake`（boolean）：輸注速率觀察不列入出入量彙總'
          items:
            $ref: '#/components/schemas/Extension'
        status:
          type: string
          enum:
            - registered
            - preliminary
            - final
            - amended
            - corrected
            - cancelled
            - entered-in-error
            - unknown
        category:
          type: array
          items:
            $ref: '#/components/schemas/CodeableConcept'
        code:
          $ref: '#/components/schemas/CodeableConcept'
        subject:
          $ref: '#/components/schemas/Reference'
        encounter:
          $ref: '#/components/schemas/Reference'
        effectiveDateTime:
          type: string
          format: date-time
        valueQuantity:
          $ref: '#/components/schemas/Quantity'
        dataAbsentReason:
          allOf:
            - $ref: '#/components/schemas/CodeableConcept'
          description: |
            缺值時填此欄並**省略** `value[x]`。**禁止送 0 代替缺值**（BR-OBS-003）。
            本專案只用：`unknown`／`not-performed`／`not-asked`／`error`／`masked`。
        interpretation:
          type: array
          description: '**只有來源提供旗標時才填。無旗標 ≠ 正常**（BR-RPT-005）。'
          items:
            $ref: '#/components/schemas/CodeableConcept'
        device:
          allOf:
            - $ref: '#/components/schemas/Reference'
          description: 設備來源（取得＝D）時標示
        partOf:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
        component:
          type: array
          description: 血壓等多子項量測。子項共用同一 `effectiveDateTime`。
          items:
            type: object
            additionalProperties: true
            properties:
              code:
                $ref: '#/components/schemas/CodeableConcept'
              valueQuantity:
                $ref: '#/components/schemas/Quantity'
              dataAbsentReason:
                $ref: '#/components/schemas/CodeableConcept'
    Composition:
      type: object
      required:
        - resourceType
        - status
        - type
        - date
        - author
        - title
      additionalProperties: true
      properties:
        resourceType:
          type: string
          enum:
            - Composition
        id:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        extension:
          type: array
          description: |
            | url 尾段 | 用途 |
            | --- | --- |
            | `copyTrace` | 前一日病程複製軌跡（`from`、`copiedAt`、`changedSections[]`） |
            | `handoverReceiver` | 交班對象 |
            | `educationTemplate` | 衛教組套來源（在 `section` 上） |
            | `amendReason` | 病歷更正理由（與 `relatesTo[replaces]` 併用，BR-DOC-005） |
            | `signedAt` | **唯讀**：本地簽署時間；權威仍是 `Provenance.signature` |
          items:
            $ref: '#/components/schemas/Extension'
        status:
          type: string
          enum:
            - preliminary
            - final
            - amended
            - entered-in-error
          description: '`preliminary`=草稿、`final`=已簽、`amended`=已被更正'
        type:
          $ref: '#/components/schemas/CodeableConcept'
        subject:
          $ref: '#/components/schemas/Reference'
        encounter:
          $ref: '#/components/schemas/Reference'
        date:
          type: string
          format: date-time
          description: 臨床時間（病程時間），非建立時間
        author:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
        title:
          type: string
        relatesTo:
          type: array
          description: 更正鏈。更正一律新建並以 `replaces` 指向舊版，舊版內容完整保留。
          items:
            type: object
            additionalProperties: true
            properties:
              code:
                type: string
                enum:
                  - replaces
                  - transforms
                  - signs
                  - appends
              targetReference:
                $ref: '#/components/schemas/Reference'
        section:
          type: array
          items:
            type: object
            additionalProperties: true
            properties:
              title:
                type: string
              code:
                $ref: '#/components/schemas/CodeableConcept'
              text:
                type: object
                additionalProperties: true
              entry:
                type: array
                description: 引用來源，**必須帶版本**（BR-DOC-008）
                items:
                  $ref: '#/components/schemas/Reference'
    Task:
      type: object
      required:
        - resourceType
        - status
        - intent
      additionalProperties: true
      properties:
        resourceType:
          type: string
          enum:
            - Task
        id:
          type: string
        status:
          type: string
          enum:
            - draft
            - requested
            - received
            - accepted
            - rejected
            - ready
            - cancelled
            - in-progress
            - on-hold
            - failed
            - completed
            - entered-in-error
        intent:
          type: string
        description:
          type: string
        for:
          $ref: '#/components/schemas/Reference'
        encounter:
          $ref: '#/components/schemas/Reference'
        focus:
          allOf:
            - $ref: '#/components/schemas/Reference'
          description: 來源單據（DiagnosticReport／ServiceRequest／Composition）
        owner:
          allOf:
            - $ref: '#/components/schemas/Reference'
          description: 交班接收時由伺服器轉移
        output:
          type: array
          description: 完成證據。結案必填（BR-TASK-002）。
          items:
            type: object
            additionalProperties: true
        note:
          type: array
          description: 承接／變更歷程，一律追加不覆寫
          items:
            type: object
            additionalProperties: true
    Provenance:
      type: object
      required:
        - resourceType
        - target
        - recorded
        - agent
      additionalProperties: true
      description: '**僅新增，永不修改。** 與 `AuditEvent` 分工：Provenance 是臨床溯源（畫面可見），AuditEvent 是安全稽核（僅稽核人員）。'
      properties:
        resourceType:
          type: string
          enum:
            - Provenance
        id:
          type: string
        extension:
          type: array
          description: |
            | url 尾段 | 用途 |
            | --- | --- |
            | `reviewOutcome` | `reviewed`／`difference` |
            | `reviewNote` | 核對依據／判讀處理紀錄（必填） |
            | `signatureValidation` | `valid`／`invalid`／`unverified`。**憑證服務不可用時用 `unverified`，不預設 valid** |
          items:
            $ref: '#/components/schemas/Extension'
        target:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Reference'
        recorded:
          type: string
          format: date-time
        activity:
          $ref: '#/components/schemas/CodeableConcept'
        agent:
          type: array
          minItems: 1
          items:
            type: object
            additionalProperties: true
            properties:
              type:
                $ref: '#/components/schemas/CodeableConcept'
              who:
                $ref: '#/components/schemas/Reference'
        entity:
          type: array
          items:
            type: object
            additionalProperties: true
        signature:
          type: array
          description: 電子簽章。`signature_hash` 與驗證結果由伺服器產生，客戶端不可送。
          items:
            type: object
            additionalProperties: true
  examples:
    MedicationRequestActive:
      summary: 生效中的藥物醫囑（p1 的 Meropenem，伺服器實際輸出）
      value:
        resourceType: MedicationRequest
        id: mr-p1-mero
        meta:
          versionId: '1'
          lastUpdated: '2026-06-14T06:00:00+07:00'
          source: 設計稿示範醫囑；品項未對應 B 目錄代碼
        extension:
          - url: http://icu.emr.local/StructureDefinition/hisTransmissionStatus
            valueCode: accepted
          - url: http://icu.emr.local/StructureDefinition/hisTransmissionEvent
            extension:
              - url: sentAt
                valueInstant: '2026-06-14T06:00:00+07:00'
              - url: respondedAt
                valueInstant: '2026-06-14T06:00:00+07:00'
          - url: http://icu.emr.local/StructureDefinition/catalogSnapshot
            extension:
              - url: catalogVersion
                valueString: 20260617-tw
          - url: http://icu.emr.local/StructureDefinition/signedAt
            valueInstant: '2026-06-14T06:00:00+07:00'
        identifier:
          - system: http://icu.emr.local/CodeSystem/his-prescription-number
            value: HP-mr-p1-mero
        status: active
        intent: order
        category:
          - coding:
              - system: http://terminology.hl7.org/CodeSystem/medicationrequest-category
                code: inpatient
        medicationCodeableConcept:
          coding:
            - system: http://icu.emr.local/CodeSystem/his-medication
              code: '33795'
              display: Meropenem
          text: Meropenem
        subject:
          reference: Patient/p1
        encounter:
          reference: Encounter/enc-p1
        authoredOn: '2026-06-14T06:00:00+07:00'
        requester:
          reference: PractitionerRole/thucdv
        dosageInstruction:
          - text: 抗生素 · 靜脈 120′ · ×3 每 8h，靜脈注射，每 8 小時
            timing:
              repeat:
                frequency: 3
                period: 1
                periodUnit: d
            route:
              coding:
                - system: http://icu.emr.local/CodeSystem/his-route
                  code: '996316'
                  display: 靜脈注射
                - system: http://icu.emr.local/CodeSystem/tdl
                  code: TDL.0401
              text: 靜脈注射
            doseAndRate:
              - doseQuantity:
                  value: 160
                  unit: mg
                  system: http://unitsofmeasure.org
                  code: mg
        dispenseRequest:
          validityPeriod:
            start: '2026-06-14T06:00:00+07:00'
    MedicationAdministrationCompleted:
      summary: 已給藥（五對齊全）
      value:
        resourceType: MedicationAdministration
        extension:
          - url: http://icu.emr.local/StructureDefinition/verificationChecklist
            extension:
              - url: rightPatient
                valueBoolean: true
              - url: rightMedication
                valueBoolean: true
              - url: rightDose
                valueBoolean: true
              - url: rightRoute
                valueBoolean: true
              - url: rightTime
                valueBoolean: true
              - url: checkedBy
                valueReference:
                  reference: PractitionerRole/nhungtt
        identifier:
          - system: http://icu.emr.local/CodeSystem/occurrence-id
            value: mr-p1-mero-2026-06-17-08:00
        status: completed
        medicationCodeableConcept:
          coding:
            - system: http://icu.emr.local/CodeSystem/his-medication
              code: '33795'
        subject:
          reference: Patient/p1
        context:
          reference: Encounter/enc-p1
        effectiveDateTime: '2026-08-31T09:00:00+07:00'
        performer:
          - actor:
              reference: PractitionerRole/nhungtt
        request:
          reference: MedicationRequest/mr-p1-mero/_history/1
        dosage:
          text: 160 mg + NaCl 0,9% 5 ml
          route:
            coding:
              - system: http://icu.emr.local/CodeSystem/his-route
                code: '913'
          dose:
            value: 160
            unit: mg
            system: http://unitsofmeasure.org
            code: mg
    ObservationBloodPressure:
      summary: 血壓（單一 Observation ＋ 兩個 component）
      value:
        resourceType: Observation
        status: final
        category:
          - coding:
              - system: http://terminology.hl7.org/CodeSystem/observation-category
                code: vital-signs
        code:
          coding:
            - system: http://loinc.org
              code: 85354-9
              display: Blood pressure panel
          text: 血壓
        subject:
          reference: Patient/p1
        effectiveDateTime: '2026-08-31T18:00:00+07:00'
        component:
          - code:
              coding:
                - system: http://loinc.org
                  code: 8480-6
                - system: http://icu.emr.local/CodeSystem/tdl
                  code: TDL.0094
                  display: 收縮壓
            valueQuantity:
              value: 125
              unit: mmHg
              system: http://unitsofmeasure.org
              code: mm[Hg]
          - code:
              coding:
                - system: http://loinc.org
                  code: 8462-4
                - system: http://icu.emr.local/CodeSystem/tdl
                  code: TDL.0095
                  display: 舒張壓
            valueQuantity:
              value: 77
              unit: mmHg
              system: http://unitsofmeasure.org
              code: mm[Hg]
    ProvenanceExecutionReview:
      summary: 醫師核對護理執行（差異待追蹤）
      value:
        resourceType: Provenance
        extension:
          - url: http://icu.emr.local/StructureDefinition/reviewOutcome
            valueCode: difference
          - url: http://icu.emr.local/StructureDefinition/reviewNote
            valueString: 實際給藥時間較預定晚 45 分鐘，已與護理端確認原因並列入追蹤。
        target:
          - reference: MedicationAdministration/ma-m3-d1
        recorded: '2026-08-31T10:15:03+07:00'
        activity:
          coding:
            - system: http://icu.emr.local/CodeSystem/provenance-activity
              code: clinical-review
              display: 臨床核對／判讀
        agent:
          - type:
              coding:
                - system: http://terminology.hl7.org/CodeSystem/provenance-participant-type
                  code: verifier
            who:
              reference: PractitionerRole/thucdv
    FiveRightsIncomplete:
      summary: 五對核對未完成
      value:
        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').extension('rightDose')