Booking Workflow Statuses — 4-Axis System

Created: 2026-03-17 | Updated: 2026-03-24 | Status: 🔄 Upgrading (Approach A Retrofit)

Overview

4-axis booking workflow status system per workflow_ptx.md SOP, retrofitting the original 3-track to a full 4-axis model. Each axis managed by a specific department. Uses existing BPM models (ProcessType, BookingStatusDef, BookingStatusTransition, ProcessInstance).

Change from v1: Added Track 3 (booking_source) as new independent axis. Renamed booking_purchasing → booking_accounting with expanded statuses. Added 6 missing statuses to booking_order.

Architecture

Status Definitions

Track 1: CS Status (booking_order)

Managed by CS Department. Tracks guest service lifecycle.

Step	Key	Label	Color	Terminal	Description
0	not_started	Not Started	#94A3B8	No	NEW — Booking synced, CS chưa xử lý
1	contacted	Contacted (A)	#3B82F6	No	CS đã liên hệ được với khách hàng
1b	cannot_contact	Cannot Contact	#F97316	No	NEW — Không liên hệ được khách
2a	confirmed_checkin_time	Confirmed Check-in Time	#8B5CF6	No	Đã xác nhận thời gian nhận phòng cụ thể
2b	cancelled_guest_fault	Cancelled (Guest Fault)	#EF4444	✅	Hủy do lỗi từ phía khách hàng
2c	cancelled_ptx_problem	Cancelled (PTX Problem)	#DC2626	✅	Hủy do lỗi phía công ty
3	cfm_apt	CFM APT	#F59E0B	No	Xác nhận chốt căn hộ
3b	relocate	Relocate	#D946EF	No	NEW — Chuyển phòng/căn hộ
4a	checkin_already	Checked-In (C)	#22C55E	No	Khách đã nhận phòng thành công
4b	no_show_guest_fault	No-Show (Guest Fault)	#64748B	✅	Khách không đến, không thông báo trước
5	checked_out	Checked-Out (D)	#10B981	No	Khách đã hoàn tất trả phòng
5b	cancel_report_commission	Cancel Report Commission	#B91C1C	No	NEW — Hủy báo cáo hoa hồng
5c	keep_part_payment	Keep Part Payment	#EA580C	No	NEW — Giữ lại 1 phần thanh toán
6	review_order	Review Order	#6B7280	✅	NEW — Đơn hàng đã hoàn tất review

Track 2: Payment Status (booking_payment)

Managed by Finance/Treasury. Tracks money flow from guest/OTA to company. No changes from v1.

Step	Key	Label	Color	Terminal	Description
1	fully_paid	Fully Paid	#22C55E	✅	Đã thanh toán đầy đủ
2	cancelled_fully_paid	Cancelled + Fully Paid	#F59E0B	✅	Hủy nhưng đã thu toàn bộ tiền
3	cancelled_auto_refund	Cancelled + Auto Refund	#EF4444	✅	Hủy, nền tảng tự hoàn tiền
4	cancelled_manual_refund	Cancelled + Manual Refund	#DC2626	No	Hủy, kế toán phải hoàn tiền thủ công
5	manual_fully_paid	Fully Paid (Manual)	#16A34A	✅	Thủ quỹ xác nhận thu đủ tiền
6	not_paid	Not Paid (Manual)	#F97316	No	Chưa thu được tiền
7	cancelled_not_paid	Cancelled + Not Paid	#9CA3AF	✅	Hủy khi chưa thanh toán

Track 3: Source Status (booking_source) — NEW

Managed by Source Department / PO. Tracks supplier confirmation status. New track per workflow_ptx.md §5.2.

Step	Key	Label	Color	Terminal	Description
1	src_confirmed	Source Confirmed	#22C55E	No	NCC xác nhận có phòng, booking OK
2	src_relocate	Source Relocate	#F59E0B	No	Cần relocate — NCC đổi phòng/căn hộ
3	src_no_room	Source No Room	#EF4444	✅	NCC báo hết phòng — cần cancel hoặc relocate
4	src_cancelled	Source Cancelled	#9CA3AF	✅	Booking bị hủy phía source

Track 4: Accounting Status (booking_accounting) — REPLACES booking_purchasing

Managed by PO + Finance/Treasury. Tracks supplier purchasing and payment lifecycle. Replaces old booking_purchasing track.

Step	Key	Label	Color	Terminal	Description
1	acc_not_required	Not Required	#94A3B8	No	Chưa cần xử lý thanh toán NCC
2	acc_deposit_pending	Deposit Pending	#F97316	No	Cần đặt cọc cho NCC, đang chờ
3	acc_deposit_paid	Deposit Paid	#3B82F6	No	Đã đặt cọc cho NCC
3b	acc_deposit_failed	Deposit Failed	#EF4444	No	Đặt cọc thất bại (chuyển tiền lỗi)
4	acc_hold_confirmed	Hold Confirmed	#8B5CF6	No	NCC xác nhận giữ phòng sau khi nhận cọc
5	acc_payment_pending	Payment Pending	#F59E0B	No	Cần thanh toán còn lại cho NCC
6	acc_payment_paid	Payment Paid	#22C55E	✅	Đã thanh toán đầy đủ cho NCC
6b	acc_partial_payment	Partial Payment	#10B981	No	Thanh toán 1 phần cho NCC
7	acc_payment_adjusted	Payment Adjusted	#06B6D4	✅	Điều chỉnh thanh toán (bù trừ, chênh lệch)
8a	acc_cancelled_no_payment	Cancelled No Payment	#9CA3AF	✅	Hủy, không cần thanh toán
8b	acc_deposit_lost	Deposit Lost	#DC2626	✅	Mất cọc do hủy/no-show
8c	acc_deposit_refunded	Deposit Refunded	#16A34A	✅	NCC đã hoàn lại tiền cọc

Cross-Axis Validation Rules (FR-50)

Per workflow_ptx.md §5.6:

Rule	Type	Logic
R1	Hard Block	Check-in (booking_order → checkin_already) requires SOURCE = src_confirmed
R2	Alert	Check-in alert if ACCOUNTING = acc_deposit_pending and check-in < 6h
R3	Hard Block	Host payment (booking_accounting → acc_payment_paid) requires CS = checked_out
R4	Hard Block	Close order (booking_order → review_order) requires Payment + Accounting terminal
R5	Auto	Auto-risk flag generation on any ProcessInstance transition

Role-Based Transition Permissions

Track	Allowed Roles	Est. Transitions
Order (CS)	cs, admin, manager	~15
Payment	fin, admin, manager	9 (unchanged)
Source	po, cs, admin, manager	~5
Accounting	po, fin, admin, manager	~14

Technical Implementation

Database Models Used

• process_types — 4 entries: booking_order, booking_payment, booking_source (NEW), booking_accounting (replaces booking_purchasing)
• booking_status_def — ~37 statuses (was 21) with processTypeKey linking to process type
• booking_status_transition — ~43 transitions (was 27) with allowedRoles + hooks JSON

Migration from v1

1. Rename booking_purchasing ProcessType key → booking_accounting
2. Update existing ProcessInstance records: processTypeKey = 'booking_purchasing' → 'booking_accounting'
3. Map old purchasing statuses to new accounting statuses where possible
4. Create booking_source ProcessType + seed new statuses
5. Add 6 new statuses to booking_order track

Seed File

• File: packages/database/prisma/seed-booking-workflow.ts
• Called from main seed.ts via seedBookingWorkflow(prisma)
• Uses upsert pattern — safe to re-run

Backward Compatibility

Original 3 statuses (confirmed, cancelled, no_show) under booking process type are untouched. Existing Booking.status FK still references these. Workflow statuses are tracked via ProcessInstance records per axis.