院方端點#
院方端點收到 Poieti 推送時的行為。以 signature-vectors.json 驗證簽章。
push.signature-valid
The endpoint accepts a correctly signed request.
- 測試資料
delivery-create.json(DeliveryV1)
- 注入狀況
- 無
- 院方應做
- Verify signature vector
push-delivery and accept it.
- Poieti 預期
- 狀態:
written - 院內檢查
poieti-his.mjs check 會執行
push.signature-replayed
A signature replayed on another path is rejected.
- 測試資料
- —
- 注入狀況
signature-replayed Send verification vector reject-replayed-path.
- 院方應做
- Reject with 401 and write nothing.
- Poieti 預期
- 說明:Hospital-side check; no Poieti state.
- 院內檢查
poieti-his.mjs check 會執行
push.signature-stale
A signature older than 300 s is rejected.
- 測試資料
- —
- 注入狀況
stale-signature Send verification vector reject-stale.
- 院方應做
- Reject with 401 and write nothing.
- Poieti 預期
- 說明:Hospital-side check; no Poieti state.
- 院內檢查
poieti-his.mjs check 會執行
push.signature-rotation
During a key rotation either key verifies.
- 測試資料
delivery-create.json(DeliveryV1)
- 注入狀況
key-rotation Send verification vector accept-rotation-previous-key to an endpoint that still holds only the previous key.
- 院方應做
- Accept when any v1 matches any held key.
- Poieti 預期
- 狀態:
written - 院內檢查
poieti-his.mjs check 會執行
push.create-written
A create is written synchronously.
- 測試資料
delivery-create.json(DeliveryV1)
- 注入狀況
- 無
- 院方應做
- Write once, store (delivery_id, his_record_id) and answer 201
{hisRecordId}.
- Poieti 預期
- 狀態:
written
嘗試次數:1 - 院內檢查
poieti-his.mjs check 會執行
push.timeout-after-commit
A retry after a timed-out request does not write twice.
- 測試資料
delivery-create.json(DeliveryV1)
- 注入狀況
timeout-after-commit The HIS commits but the response arrives after Poieti's timeout; Poieti retries with the same Idempotency-Key and identical body.
- 院方應做
- Answer the retry with 200 and the original hisRecordId (or 409
DUPLICATE_DELIVERY with hisRecordId); keep one HIS record.
- Poieti 預期
- 狀態:
written
嘗試次數:2 - 院內檢查
poieti-his.mjs check 會執行
push.rejection-not-stored
A rejection is not cached against the deliveryId.
- 測試資料
delivery-create.json(DeliveryV1)
- 注入狀況
rejected-then-fixed Answer 422 PATIENT_NOT_FOUND, then fix the HIS; hospital IT retries the delivery from the console.
- 院方應做
- Process the retried deliveryId again and answer 201
{hisRecordId}.
- Poieti 預期
- 狀態:
written
push.correction-replaces
A correction replaces the record named by supersedes.hisRecordId in full.
- 測試資料
delivery-correction.json(DeliveryV1)
- 注入狀況
- 無
- 院方應做
- Find the HIS record NA-20261016-0012 and replace every mapped field with this version, even if its admission is closed; identity comes from the original record. Answer 200
{hisRecordId} with the resulting HIS record id (the same id or a new one).
- Poieti 預期
- 狀態:
written
類型:correction
push.rows-replaced
Repeatable rows replace the stored row set as a whole.
- 測試資料
delivery-correction.json(DeliveryV1){
"fields": {
"FAMILY": [
{
"REL": "02",
"LIVES_WITH": "true"
}
]
}
}
- 注入狀況
rows-removed Version 1 in the HIS has two FAMILY rows; this correction has one.
- 院方應做
- Store exactly one FAMILY row: delete the rows that are not in the delivery. Answer 200
{hisRecordId}.
- Poieti 預期
- 狀態:
written
類型:correction
push.partial-date
A partial date is stored as rendered.
- 測試資料
delivery-create.json(DeliveryV1)
- 注入狀況
- 無
- 院方應做
- Store ONSET as
2026-10 (the mapping's text rendering); never invent a day or month. Answer 200 {hisRecordId}.
- Poieti 預期
- 狀態:
written
push.attachment-verified
Attachment bytes are fetched and verified before writing.
- 測試資料
delivery-create.json(DeliveryV1)
- 注入狀況
- 無
- 院方應做
- GET /his/v1/deliveries/{deliveryId}/attachments/{attachmentId} with a
deliveries key; check Content-Length = 183204 and SHA-256 = attachments[0].sha256 before writing; answer 200 {hisRecordId}.
- Poieti 預期
- 狀態:
written
push.attachment-mismatch
Attachment bytes that fail verification are not written.
- 測試資料
delivery-create.json(DeliveryV1)
- 注入狀況
attachment-corrupted The attachment route serves bytes whose SHA-256 differs from the delivery.
- 院方應做
- Do not write. Answer a coded 4xx with
{code: "ATTACHMENT_MISMATCH", retryable: true}.
- Poieti 預期
- 狀態:
pending
錯誤碼:ATTACHMENT_MISMATCH
可重試:true
說明:Poieti posts the same body again after the backoff, with X-Poieti-Attempt: 2.
push.missing-required
missingRequired lists a hospital-required field without a value.
- 測試資料
delivery-correction.json(DeliveryV1)
- 注入狀況
- 無
- 院方應做
- Apply the hospital's documented policy: write without FOOD_ALG and flag it, or answer 422 with a non-retryable code such as
REQUIRED_FIELD_MISSING. Never fill in a default. notSent is informational.
- Poieti 預期
- 狀態之一:
written / failed
push.identity-rejected
The HIS does not know the patient.
- 測試資料
delivery-create.json(DeliveryV1){
"patient": {
"medicalRecordNumber": "DEMO-404"
}
}
- 注入狀況
unknown-patient DEMO-404 does not exist in the test HIS.
- 院方應做
- Do not write. Answer 422
{code: "PATIENT_NOT_FOUND", retryable: false}.
- Poieti 預期
- 狀態:
failed
錯誤碼:PATIENT_NOT_FOUND
可重試:false
說明:Nurses can fix the patient and resend. - 院內檢查
poieti-his.mjs check 會執行
push.identity-resend
After a nurse fixes the patient, the resend arrives as a new generation.
- 測試資料
delivery-create.json(DeliveryV1){
"deliveryId": "7c6b5a49-3827-4615-9d4c-3b2a1f0e9d8c",
"generation": 2
}
- 注入狀況
nurse-resend The generation-1 delivery failed with PATIENT_NOT_FOUND and the nurse resent it.
- 院方應做
- Treat it as a new deliveryId: look it up, write once, answer 200
{hisRecordId}.
- Poieti 預期
- 狀態:
written
代次:2
push.retryable-failure
A temporary HIS failure is retried with the same deliveryId and body.
- 測試資料
delivery-create.json(DeliveryV1)
- 注入狀況
his-temporarily-unavailable The HIS table is locked during attempt 1.
- 院方應做
- Answer a coded 4xx such as 423 with
{code: "HIS_LOCKED", retryable: true}. When the delivery returns (X-Poieti-Attempt: 2, identical body), write it and answer 200 {hisRecordId}.
- Poieti 預期
- 狀態:
written
嘗試次數:2
說明:After the first report the delivery is pending until its backoff ends.
push.unencodable-text
Text the HIS column cannot hold is reported, never altered.
- 測試資料
delivery-create.json(DeliveryV1){
"target": {
"charset": "utf-8"
},
"fields": {
"CARE_NOTE": "傷口周圍皮膚完整𠀋"
}
}
- 注入狀況
unencodable-text The CARE_NOTE column is Big5 and cannot store U+2000B.
- 院方應做
- Do not truncate, drop or replace characters with
?. Answer 422 {code: "VALUE_UNENCODABLE", retryable: false} (or VALUE_TOO_LONG for an over-long value).
- Poieti 預期
- 狀態:
failed
錯誤碼:VALUE_UNENCODABLE
可重試:false
push.redeliver
After hospital-side data loss a written delivery is redelivered as a new generation.
- 測試資料
delivery-create.json(DeliveryV1){
"deliveryId": "1e0d9c8b-7a69-4f58-8e47-3d2c1b0a9f8e",
"generation": 2
}
- 注入狀況
hospital-data-loss The HIS record of generation 1 was lost; hospital IT redelivered it from the console.
- 院方應做
- Treat the new deliveryId as new: write once and answer 200
{hisRecordId}.
- Poieti 預期
- 狀態:
written
代次:2
push.accepted-202
A queued write is followed up by status polling.
- 測試資料
delivery-create.json(DeliveryV1)
- 注入狀況
async-import Answer 202; the status route answers 202 once, then 200 {hisRecordId}.
- 院方應做
- Serve GET /deliveries/{deliveryId}: 202 while processing, 200 with hisRecordId when written.
- Poieti 預期
- 狀態:
written - 院內檢查
poieti-his.mjs check 會執行
push.accepted-then-failed
A queued write is rejected by the import job.
- 測試資料
delivery-create.json(DeliveryV1)
- 注入狀況
staging-import-rejected Answer 202; the import job then rejects the queued write.
- 院方應做
- Answer GET /deliveries/{deliveryId} with a coded 4xx such as 422
{code: "IMPORT_REJECTED"}.
- Poieti 預期
- 狀態:
failed
錯誤碼:IMPORT_REJECTED
push.status-unknown
A status 404 makes Poieti post the delivery again.
- 測試資料
delivery-create.json(DeliveryV1)
- 注入狀況
status-unknown Answer 202, then lose the queued item so GET /deliveries/{deliveryId} answers 404.
- 院方應做
- Accept the repeated POST (same key, identical body) and write once.
- Poieti 預期
- 狀態:
written - 院內檢查
poieti-his.mjs check 會執行
push.coded-rejection
A coded 4xx fails the delivery with that code.
- 測試資料
delivery-correction.json(DeliveryV1)
- 注入狀況
coded-rejection Answer 422 {code: "ENCOUNTER_CLOSED", retryable: false}.
- 院方應做
- None further.
- Poieti 預期
- 狀態:
failed
錯誤碼:ENCOUNTER_CLOSED
可重試:false
push.uncoded-rejection
An uncoded 4xx with a healthy probe fails only that delivery.
- 測試資料
delivery-create.json(DeliveryV1)
- 注入狀況
waf-block A gateway answers 400 with an HTML body for this delivery; GET /health answers 200.
- 院方應做
- None; hospital IT reviews the gateway rule.
- Poieti 預期
- 狀態:
failed
錯誤碼:HIS_REJECTED
斷路器:{"open":false}
push.outage
An endpoint outage pauses dispatch without failing deliveries.
- 測試資料
delivery-create.json(DeliveryV1)
- 注入狀況
outage POST /deliveries answers 503 and GET /health fails for an hour.
- 院方應做
- None; dispatch resumes after /health recovers.
- Poieti 預期
- 狀態:
pending
斷路器:{"open":true,"reason":"unreachable"}
說明:The attempt is not counted; one his.push.paused alert, then his.push.resumed on recovery.
push.auth-failure
401/403 pause dispatch until the endpoint token changes.
- 測試資料
delivery-create.json(DeliveryV1)
- 注入狀況
bad-token The endpoint answers 401 to every request.
- 院方應做
- Hospital IT and Poieti staff fix the token with set-his-endpoint.
- Poieti 預期
- 狀態:
pending
斷路器:{"open":true,"reason":"auth"}
push.health
The probe route answers a signed GET.
- 測試資料
- —
- 注入狀況
- 無
- 院方應做
- Verify signature vector
push-health and answer 200.
- Poieti 預期
- 說明:Used by the gateway before charging suspect responses.
- 院內檢查
poieti-his.mjs check 會執行
push.census-fetch
Poieti fetches a ward census.
- 測試資料
census-snapshot-context.json(CensusSnapshotV1)
- 注入狀況
- 無
- 院方應做
- Answer GET /census/wards/8B with the ward's CensusSnapshotV1.
- Poieti 預期
- 回應:
{"status":200}
說明:Applied like an upload; context rows replaced per kind. - 院內檢查
poieti-his.mjs check 會執行
push.patient-search
A nurse lookup returns verification data for the requested ward.
- 測試資料
patient-search-request.json(PatientSearchRequest)
- 注入狀況
- 無
- 院方應做
- Answer with patients carrying wardCode and no clinical context, as in patient-search-response.json.
- Poieti 預期
- 回應:
{"status":200} - 院內檢查
poieti-his.mjs check 會執行
push.oversized-response
A response body over 64 KB is endpoint-suspect.
- 測試資料
delivery-create.json(DeliveryV1)
- 注入狀況
oversized-response Answer 201 with a 70 KB body.
- 院方應做
- Keep delivery responses small.
- Poieti 預期
- 狀態之一:
pending / failed
說明:Probe passes → failed HIS_REJECTED; probe fails → deferred and circuit opens. - 院內檢查
poieti-his.mjs check 會執行
病房名單上傳#
PUT /his/v1/census/wards/{wardCode} 的套用、重送與拒收。需要 census 範圍的金鑰與機構的名單開關。
census.upload
A snapshot is applied. Before: DEMO-001 is an HIS patient of 8B, DEMO-003 an active HIS patient, DEMO-009 a manual patient with another name and no matching encounter, DEMO-007 an HIS patient of 8B; DEMO-002 is unknown.
- 測試資料
census-snapshot.json(CensusSnapshotV1)
- 注入狀況
- 無
- 院方應做
- PUT /his/v1/census/wards/8B with the snapshot.
- Poieti 預期
- 回應:
{"status":200,"replayed":false}
名單結果:{"created":1,"updated":1,"discharged":1,"missing":1,"rejected":[{"medicalRecordNumber":"DEMO-009","code":"IDENTITY_CONFLICT"}]}
census.replay
The same snapshot uploaded again changes nothing.
- 測試資料
census-snapshot.json(CensusSnapshotV1)
- 注入狀況
replayed-snapshot Upload census.upload's snapshot a second time.
- 院方應做
- None.
- Poieti 預期
- 回應:
{"status":200,"replayed":true}
名單結果:{"created":0,"updated":0,"discharged":0,"missing":0}
census.stale
An older snapshot is refused.
- 測試資料
census-snapshot.json(CensusSnapshotV1){
"asOf": "2026-10-16T14:40:00+08:00"
}
- 注入狀況
stale-snapshot Upload after census.upload.
- 院方應做
- Discard the old snapshot; send the next one with a newer asOf.
- Poieti 預期
- 回應:
{"status":409,"code":"CENSUS_STALE"}
census.same-asof-changed
A changed snapshot must carry a new asOf.
- 測試資料
census-snapshot.json(CensusSnapshotV1){
"patients": [
{
"medicalRecordNumber": "DEMO-001",
"encounterId": "A2026101601",
"displayName": "示範病人",
"bed": "8B-14"
}
]
}
- 注入狀況
same-asof-changed Upload after census.upload with the same asOf and different patients.
- 院方應做
- Take a fresh snapshot with its own asOf.
- Poieti 預期
- 回應:
{"status":409,"code":"CENSUS_STALE"}
census.missing-offset
asOf without an offset is invalid.
- 測試資料
census-snapshot.json(CensusSnapshotV1),契約本身即拒收的測試資料{
"asOf": "2026-10-16T15:40:00"
}
- 注入狀況
- 無
- 院方應做
- Send RFC 3339 times with an offset, for example +08:00.
- Poieti 預期
- 回應:
{"status":422,"code":"HIS_CENSUS_INVALID"}
census.duplicate-chart-number
A chart number that appears twice invalidates the snapshot.
- 測試資料
census-snapshot.json(CensusSnapshotV1){
"patients": [
{
"medicalRecordNumber": "DEMO-001",
"encounterId": "A2026101601",
"displayName": "示範病人"
},
{
"medicalRecordNumber": "DEMO-001",
"encounterId": "A2026101699",
"displayName": "示範病人"
}
]
}
- 注入狀況
- 無
- 院方應做
- Fix the HIS query so each patient appears once.
- Poieti 預期
- 回應:
{"status":422,"code":"HIS_CENSUS_INVALID"}
census.unknown-ward
An unknown ward code is refused.
- 測試資料
census-snapshot.json(CensusSnapshotV1)
- 注入狀況
unknown-ward PUT to /his/v1/census/wards/ZZ, which no ward uses.
- 院方應做
- Ask Poieti staff to set the ward's HIS code.
- Poieti 預期
- 回應:
{"status":404,"code":"WARD_NOT_FOUND"}
census.context-outside-push
Clinical context is refused unless the institution is in push mode.
- 測試資料
census-snapshot-context.json(CensusSnapshotV1)
- 注入狀況
context-outside-push Upload to an institution in mode off with census on.
- 院方應做
- Send identity and admission data only.
- Poieti 預期
- 回應:
{"status":422,"code":"CENSUS_CONTEXT_DISABLED"}
census.absent-not-discharged
A patient missing from a complete snapshot is flagged, not discharged.
- 測試資料
census-snapshot.json(CensusSnapshotV1)
- 注入狀況
patient-absent DEMO-007 is an HIS patient of 8B and is not in the snapshot.
- 院方應做
- Send
discharged: true to discharge a patient.
- Poieti 預期
- 名單結果:
{"missing":1,"discharged":1}
說明:DEMO-007 stays active with census_missing_since set; only DEMO-003 is discharged.
census.ward-scope
A credential limited to other census wards cannot upload this ward.
- 測試資料
census-snapshot.json(CensusSnapshotV1)
- 注入狀況
ward-not-allowed The credential's census wards are [8A].
- 院方應做
- Use a credential that covers the ward.
- Poieti 預期
- 回應:
{"status":403,"code":"HIS_SCOPE_DENIED"}
census.disabled
Uploads are refused while census is off for the institution.
- 測試資料
census-snapshot.json(CensusSnapshotV1)
- 注入狀況
census-disabled The institution's census switch is off.
- 院方應做
- Stop uploading until Poieti staff enable census.
- Poieti 預期
- 回應:
{"status":409,"code":"HIS_CENSUS_DISABLED"}