poieti/developers
資料與欄位

欄位對照

把 Poieti 欄位與選項代碼對應到院方欄位代碼:格式、編碼、審核與版本。

對照工作表#

每個紀錄功能的每個範本版本一份工作表,由正式範本產生,列出欄位對照必須對應或排除的每個欄位(重複資料列的子欄位寫成 父欄位[].子欄位)、型別、條件、選項代碼、限制、poieti-canonical 的值與可用編碼。院方填寫最後七欄後交給 Poieti。

功能版本欄位數工作表(CSV,UTF-8)
住院整合照護紀錄(aide-care-record)範本 v139 field-mapping-aide-care-record-v1.csv
輸出入量紀錄(intake-output)範本 v157 field-mapping-intake-output-v1.csv
管路紀錄(line-record)範本 v19 field-mapping-line-record-v1.csv
入院護理評估表(nursing-admission)範本 v1149 field-mapping-nursing-admission-v1.csv
傷口紀錄(wound-record)範本 v110 field-mapping-wound-record-v1.csv

病人身分欄位(patient.*)不在對照中:身分只經由 DeliveryV1 的 patient 區塊送出。

對照檔格式#

審核後的對照是版本化的 JSON 檔(schema: "poieti.his-mapping/1"),以 (id, version, feature.id, feature.templateVersion) 識別,發布後永不修改。以下為合成的示範對照(節錄):

demo-hospital.nursing-admission.t1.v1.json
{
  "schema": "poieti.his-mapping/1",
  "id": "demo-hospital",
  "version": 1,
  "description": "Synthetic demonstration mapping for the demo-hospital institution. The NUR_ADM form, its column codes and option codes are invented for tests and demos; they belong to no real hospital.",
  "feature": {
    "id": "nursing-admission",
    "templateVersion": 1
  },
  "target": {
    "form": "NUR_ADM",
    "formVersion": "2026.1",
    "timezone": "Asia/Taipei",
    "charset": "cp950"
  },
  "observedAt": {
    "date": "admission.wardDate",
    "time": "admission.wardTime"
  },
  "codeTables": {
    "NONE_YES": {
      "none": "N",
      "yes": "Y"
    }
  },
  "fields": [
    {
      "source": "basic.education",
      "encode": "code",
      "target": "EDU",
      "codes": {
        "illiterate": "0",
        "elementary": "1",
        "junior_high": "2",
        "senior_high": "3",
        "college": "4",
        "university_or_above": "5"
      },
      "required": true
    },
    {
      "source": "basic.languages",
      "encode": "joined",
      "target": "LANG",
      "separator": ",",
      "codes": {
        "mandarin": "zh",
        "taiwanese_hokkien": "tw",
        "hakka": "hak",
        "amis": "ami",
        "atayal": "tay",
        "rukai": "dru",
        "yami": "tao",
        "english": "en",
        "indonesian": "id",
        "japanese": "ja",
        "thai": "th",
        "filipino": "fil",
        "other": "oth"
      }
    }
  ],
  "excluded": [
    {
      "source": "contacts.contactPhone2",
      "reason": "NUR_ADM keeps one telephone number per contact."
    },
    {
      "source": "family.members[].note",
      "reason": "NUR_ADM has no free-text column for family members."
    }
  ]
}
成員說明
target院方表單 form、formVersion、時區 timezone(預設 Asia/Taipei)與字集 charset(utf-8 或 cp950)
observedAt組成臨床時間的日期與時間欄位
codeTables共用的選項代碼表
fields每個欄位的 source、encode、target 與編碼參數;required 表示院方必填
excluded不送出的欄位與原因;有值時列在 notSent

每個功能版本都有 poieti-canonical 對照:所有可寫欄位以原欄位 ID 為代碼、保留原始 JSON 型別、字集 UTF-8。可下載 demo-hospital.nursing-admission.t1.v1.json、 poieti-canonical.aide-care-record.t1.v1.json、 poieti-canonical.intake-output.t1.v1.json、 poieti-canonical.line-record.t1.v1.json、 poieti-canonical.nursing-admission.t1.v1.json、 poieti-canonical.wound-record.t1.v1.json。

編碼方式#

encode適用型別輸出
code單選、選單選項代碼 → 院方代碼(codes 或共用的 codeTable)
joined多選依範本選項順序以 separator(預設 ,)串接;空陣列為 ""
flags多選每個選項一個院方欄位,值為 mapping 的 true/false 字串
number數值decimals 0–4 位、選用 10 的次方 scale(例如公分轉毫米);小數位數不足時保留紀錄,不四捨五入;選用含端點的 min/max(院方單位,即乘上 scale 後),超出時保留紀錄(VALUE_OUT_OF_RANGE),不截到上下限
integer數值、整數選項整數字串;選用含端點的 min/max,超出時保留紀錄(VALUE_OUT_OF_RANGE)
boolean是/否mapping 的 true/false 字串
date日期YYYY-MM-DD、YYYYMMDD 或 ROC(民國 YYYMMDD,年三位補零)
time時間HH:mm 或 HHmm
partial-date部分日期text(ISO 8601 簡化格式,如 2026-10)、split(年/月/日三欄)或 reject(只收完整日期)
text文字maxLength(UTF-16 單位)、maxBytes(目標字集位元組);不截斷
rows重複資料列rowFields 對應子欄位、maxRows;更正時整組取代

院方對照中,每個輸出值都是字串,沒有值就省略。選項代碼表必須剛好涵蓋欄位的所有選項。

檢查與阻擋#

  • 發布前:來源都是可寫欄位、編碼符合型別、代碼表涵蓋所有選項、院方代碼不重複、每個可寫的非身分欄位都有對應或排除原因、代碼與分隔符號可在目標字集編碼、代碼表都有使用。
  • 產生時:每個字串都檢查可否編碼(VALUE_UNENCODABLE)與長度(VALUE_TOO_LONG),從不截斷或替換;無法對應的值為 VALUE_UNMAPPABLE;不支援的部分日期為 PARTIAL_DATE_UNSUPPORTED;超出欄位對照 min/max 的數值為 VALUE_OUT_OF_RANGE。這些紀錄會保留為待送,修正後重新產生。
  • cp950:只允許 MS950 能來回轉換的字元,排除各院不同的造字區(EUDC)。
  • missingRequired:依範本與院方必填、並考慮條件顯示與條件必填計算;只供參考,Poieti 仍會送出。

審核與版本#

  1. 院方填寫工作表(與病房代碼、員工編號對照)。
  2. Poieti 產生對照 JSON 並以範本驗證,雙方逐欄核對(含代碼表與字集)。
  3. 發布為新的對照檔與版本;已發布的版本永不修改,送出時記錄所用的對照版本。
  4. Poieti 為機構的每個功能版本選定對照版本後才會送出;缺少對照的紀錄保留為 MAPPING_UNAVAILABLE,發布後重新產生。
  5. 範本改版或院方欄位異動時,發布新的對照版本,並以驗收案例重新測試受影響的流程。

其他紀錄的欄位#

住院整合照護紀錄(aide-care-record v1)

欄位 ID名稱型別限制poieti-canonical 值可用編碼
record.date日期date 日期—string "YYYY-MM-DD"date
record.shift班別single 單選—string(選項代碼)code
record.aides照護輔佐人員text 文字最多 2000 字stringtext
record.orientation_date環境介紹日期date 日期—string "YYYY-MM-DD"date
record.primary_caregiver主要照顧者text 文字最多 200 字stringtext
record.items本班執行項目multi 多選—string[](選項代碼,範本順序)joined flags
care.hair_wash洗頭text 文字最多 2000 字stringtext
care.face_wash洗臉text 文字最多 2000 字stringtext
care.oral_care口腔清潔text 文字最多 2000 字stringtext
care.bath身體清潔text 文字最多 2000 字stringtext
care.perineal_care會陰清潔text 文字最多 2000 字stringtext
care.nail_care剪指甲text 文字最多 2000 字stringtext
care.breakfast早餐text 文字最多 2000 字stringtext
care.lunch中餐text 文字最多 2000 字stringtext
care.dinner晚餐text 文字最多 2000 字stringtext
care.toileting如廁text 文字最多 2000 字stringtext
output.urine尿量repeatable 重複資料列0–50 列object[](整組取代)rows
output.urine[].time時間time 時間—string "HH:mm"time
output.urine[].amount量number 數值單位 mL;0–5000numbernumber integer
output.urine[].color顏色single 單選—string(選項代碼)code
output.stool大便repeatable 重複資料列0–50 列object[](整組取代)rows
output.stool[].time時間time 時間—string "HH:mm"time
output.stool[].amount量single 單選—string(選項代碼)code
output.stool[].color顏色single 單選—string(選項代碼)code
care.turning翻身text 文字最多 2000 字stringtext
care.percussion拍痰text 文字最多 2000 字stringtext
care.bed_exercise床上運動text 文字最多 2000 字stringtext
care.sitting下床坐text 文字最多 2000 字stringtext
care.walking下床走text 文字最多 2000 字stringtext
activity.weight量體重repeatable 重複資料列0–10 列object[](整組取代)rows
activity.weight[].time時間time 時間—string "HH:mm"time
activity.weight[].weight體重number 數值單位 kg;1–300numbernumber integer
care.bedding床邊整理text 文字最多 2000 字stringtext
care.rounds巡視text 文字最多 2000 字stringtext
care.safety安全維護text 文字最多 2000 字stringtext
care.ng_tube鼻胃管護理text 文字最多 2000 字stringtext
care.steam蒸氣吸入text 文字最多 2000 字stringtext
care.other其它text 文字最多 2000 字stringtext
handover.note特殊交班text 文字最多 2000 字stringtext

身分欄位 不在對照中。

輸出入量紀錄(intake-output v1)

欄位 ID名稱型別限制poieti-canonical 值可用編碼
record.date紀錄日期date 日期—string "YYYY-MM-DD"date
record.kinds本次記錄項目multi 多選—string[](選項代碼,範本順序)joined flags
record.time結算時間time 時間—string "HH:mm"time
intake.injection注射量repeatable 重複資料列0–50 列object[](整組取代)rows
intake.injection[].time時間time 時間—string "HH:mm"time
intake.injection[].amount量number 數值單位 mL;0–10000numbernumber integer
intake.injection[].drug藥名text 文字最多 200 字stringtext
intake.injection[].loss另有未計量(+LOSS)boolean 是/否—booleanboolean
intake.injection[].note備註text 文字最多 200 字stringtext
intake.transfusion輸血量repeatable 重複資料列0–50 列object[](整組取代)rows
intake.transfusion[].time時間time 時間—string "HH:mm"time
intake.transfusion[].amount量number 數值單位 mL;0–10000numbernumber integer
intake.transfusion[].product血品text 文字最多 200 字stringtext
intake.transfusion[].loss另有未計量(+LOSS)boolean 是/否—booleanboolean
intake.transfusion[].note備註text 文字最多 200 字stringtext
intake.diet飲食量repeatable 重複資料列0–50 列object[](整組取代)rows
intake.diet[].time時間time 時間—string "HH:mm"time
intake.diet[].amount量number 數值單位 mL;0–10000numbernumber integer
intake.diet[].method進食方式text 文字最多 200 字stringtext
intake.diet[].loss另有未計量(+LOSS)boolean 是/否—booleanboolean
intake.diet[].note備註text 文字最多 200 字stringtext
intake.other其他輸入量repeatable 重複資料列0–50 列object[](整組取代)rows
intake.other[].time時間time 時間—string "HH:mm"time
intake.other[].amount量number 數值單位 mL;0–10000numbernumber integer
intake.other[].loss另有未計量(+LOSS)boolean 是/否—booleanboolean
intake.other[].note備註text 文字最多 200 字stringtext
output.urine小便量repeatable 重複資料列0–50 列object[](整組取代)rows
output.urine[].time時間time 時間—string "HH:mm"time
output.urine[].amount量number 數值單位 mL;0–10000numbernumber integer
output.urine[].loss另有未計量(+LOSS)boolean 是/否—booleanboolean
output.urine[].note備註text 文字最多 200 字stringtext
output.stool大便量repeatable 重複資料列0–50 列object[](整組取代)rows
output.stool[].time時間time 時間—string "HH:mm"time
output.stool[].amount量number 數值單位 mL;0–10000numbernumber integer
output.stool[].loss另有未計量(+LOSS)boolean 是/否—booleanboolean
output.stool[].note備註text 文字最多 200 字stringtext
output.sputum痰量repeatable 重複資料列0–50 列object[](整組取代)rows
output.sputum[].time時間time 時間—string "HH:mm"time
output.sputum[].amount量number 數值單位 mL;0–10000numbernumber integer
output.sputum[].loss另有未計量(+LOSS)boolean 是/否—booleanboolean
output.sputum[].note備註text 文字最多 200 字stringtext
output.drainage引流量repeatable 重複資料列0–50 列object[](整組取代)rows
output.drainage[].time時間time 時間—string "HH:mm"time
output.drainage[].amount量number 數值單位 mL;0–10000numbernumber integer
output.drainage[].type引流種類text 文字最多 200 字stringtext
output.drainage[].loss另有未計量(+LOSS)boolean 是/否—booleanboolean
output.drainage[].note備註text 文字最多 200 字stringtext
output.other其他輸出量repeatable 重複資料列0–50 列object[](整組取代)rows
output.other[].time時間time 時間—string "HH:mm"time
output.other[].amount量number 數值單位 mL;0–10000numbernumber integer
output.other[].loss另有未計量(+LOSS)boolean 是/否—booleanboolean
output.other[].note備註text 文字最多 200 字stringtext
output.dialysis洗腎脫水量repeatable 重複資料列0–50 列object[](整組取代)rows
output.dialysis[].time時間time 時間—string "HH:mm"time
output.dialysis[].amount量number 數值單位 mL;0–10000numbernumber integer
output.dialysis[].loss另有未計量(+LOSS)boolean 是/否—booleanboolean
output.dialysis[].note備註text 文字最多 200 字stringtext

身分欄位 不在對照中。

管路紀錄(line-record v1)

欄位 ID名稱型別限制poieti-canonical 值可用編碼
record.date紀錄日期date 日期—string "YYYY-MM-DD"date
record.time紀錄時間time 時間—string "HH:mm"time
line.type管路種類text 文字最多 2000 字stringtext
line.size規格/尺寸text 文字最多 2000 字stringtext
line.site置入部位text 文字最多 2000 字stringtext
line.action本次處置text 文字最多 2000 字stringtext
line.condition管路及部位狀況text 文字最多 2000 字stringtext
line.dressing敷料與固定text 文字最多 2000 字stringtext
line.care照護紀錄text 文字最多 2000 字stringtext

身分欄位 不在對照中。

傷口紀錄(wound-record v1)

欄位 ID名稱型別限制poieti-canonical 值可用編碼
record.date紀錄日期date 日期—string "YYYY-MM-DD"date
record.time紀錄時間time 時間—string "HH:mm"time
wound.site傷口部位text 文字最多 2000 字stringtext
wound.lengthCm傷口長度number 數值單位 公分;0–100numbernumber integer
wound.widthCm傷口寬度number 數值單位 公分;0–100numbernumber integer
wound.appearance傷口外觀text 文字最多 2000 字stringtext
wound.exudate滲液狀況text 文字最多 2000 字stringtext
wound.surrounding周圍皮膚text 文字最多 2000 字stringtext
wound.pain疼痛分數number 數值單位 /10;0–10numbernumber integer
wound.care清潔與敷料處置text 文字最多 2000 字stringtext

身分欄位 不在對照中。

入院護理評估的 149 個欄位見入院護理評估欄位。

Poieti · HIS 介接contracts/his v1.0.0

搜尋文件

OpenAPI 契約 3.1