Configure a Procedure Flow (How-To)

Short operator guide for tailoring the Procedure worklist (/procedure) per department — extra screening, pre-op / intra-op steps, renamed phases, gates, and the new photo / signature fields. No code needed — this is all configuration.

TL;DR

The procedure worklist is status-machine + feature-config, not a node graph. The 3 status tabs (Pending → In-Progress → Completed) are fixed; what you configure per department is which phases/features each procedure row exposes, what fields they collect, and which actions they gate.

• Where: /admin/procedure-workflow-config (select a department first).
• Built-in phases: toggle Sign-In, Time-Out, Intra-Op, Sign-Out, Recovery, PAR, Surgical Team, Surgical Type, Surgical History on/off + required.
• Custom features: author your own (e.g. “Pre-Procedure Screening”) with fields: checkbox / short-text / signature (canvas) / photo-file.
• Gates: a feature can block downstream actions (e.g. procedure_start) until it is complete.
• Resolution priority (first wins): visual-editor template (“Procedure Workflow Grouping”) → Supabase procedure_workflow_config → localStorage → static defaults.

Step-by-step

1. Go to /admin/procedure-workflow-config and pick the department (clinic / sub-clinic) you want to tailor. Features default OFF for any unseeded department.
2. Toggle built-in phases. For each of Sign-In / Time-Out / Intra-Op / Sign-Out / Recovery / PAR / Surgical Team / Surgical Type / Surgical History: set Enabled (mounts it as a tab/action on the procedure row) and Required (must be completed before the row can move to Completed).
3. Add a custom feature — click “+ Add custom”. In the builder:
   • Labels (Thai + English) — this is how you rename a step.
   • Group chip (safety / flow / reference / team / meta / custom).
   • Items — add fields, each with a kind:

     kind	renders as
     checkbox	a tick item
     text	a text area + speech-to-text dictation + AI “tidy” (recommender-mode)
     signature	a canvas signature pad (draw with mouse/finger → PNG)
     photo	photo / file upload (filestore/IPFS, image thumbnails)

   • Gating — optionally declare which ProcedureActions this feature blocks while incomplete, and enforcement: 'hard' | 'soft'.
4. Save. It persists to Supabase procedure_workflow_config (+ localStorage fallback). The procedure worklist for that department now shows the feature.

Worked example — “Pre-Procedure Screening” that gates the start

A ProcedureFeatureConfig (what the builder emits) for a screening step that collects identity + allergy checks, a site photo, notes, and a nurse signature, and blocks the procedure from starting until done:

{
  "featureId": "pre-procedure-screening",
  "isCustom": true,
  "enabled": true,
  "required": true,
  "labelTh": "คัดกรองก่อนทำหัตถการ",
  "labelEn": "Pre-Procedure Screening",
  "group": "safety",
  "hint": "Confirm identity, allergies, site; capture photo + screening-nurse signature before start.",
  "fieldOverrides": {
    "items": [
      { "id": "id-confirmed",  "kind": "checkbox",  "labelTh": "ยืนยันตัวตนผู้ป่วย", "labelEn": "Patient identity confirmed", "required": true },
      { "id": "allergy-rev",   "kind": "checkbox",  "labelTh": "ทบทวนประวัติแพ้",   "labelEn": "Allergy history reviewed",   "required": true },
      { "id": "vitals-note",   "kind": "text",      "labelTh": "สัญญาณชีพ / หมายเหตุ", "labelEn": "Vitals / notes",            "required": false },
      { "id": "site-photo",    "kind": "photo",     "labelTh": "รูปบริเวณที่ทำ",      "labelEn": "Site photo",                 "required": false },
      { "id": "nurse-sign",    "kind": "signature", "labelTh": "พยาบาลผู้คัดกรอง",    "labelEn": "Screening nurse",            "role": "circulating_nurse", "required": true }
    ]
  },
  "gate": { "blocks": ["fire:procedure_start"], "enforcement": "hard" }
}

Effect: the procedure row shows a Pre-Procedure Screening action; the start action stays blocked (hard) until the two required checkboxes + the signature are filled. The photo + notes are optional.

Alternative: author visually (workflow-store style)

Instead of the form, an admin can create a flow template of type “Procedure Workflow Grouping” in /admin-panel/edit-flow-management, scoped to the sub-clinic. It is converted to the same feature list (fetchEditFlowTemplateForDepartment → flowDataToTeatures in procedureWorkflowConfig.service.ts) and takes precedence over the form-based config. Note: the worklist consumes it as a flat feature/phase list

• gates — not as a branching node graph.

What this is NOT

• It does not add branching/edges or extra status tabs to the worklist (those are fixed: Pending / In-Progress / Completed).
• It is separate from the generic config-driven worklist (WorkflowConfigBasedTabs / workflow_templates) that /medical-worklist uses. For true node-graph branching + configurable columns on procedures, that would be a migration onto the generic system (a larger change).

Key files

Concern	File
Config types	web/src/services/procedure-workflow-config/procedureWorkflowConfig.types.ts
Resolver (4-tier) + visual-editor bridge	web/src/services/procedure-workflow-config/procedureWorkflowConfig.service.ts
Admin page	web/src/pages/admin/procedure-workflow-config.tsx
Custom-feature builder + item kinds	web/src/pages/admin/procedure-workflow-config-builder/CustomFeatureBuilderDialog.tsx
Row dialog (renders items by kind)	web/packages/medical-kit/src/procedure/components/work-list/ProcedureWorkListRowData.tsx
New field components	…/work-list/RichResultField.tsx (text+STT+AI), ProcedureSignaturePad.tsx, ProcedurePhotoAttachment.tsx