Đặc Tả Quản Lý Quy Trình Nghiệp Vụ (BPM_SPEC)
Dự án: PTX Channel Manager (ptx-cm)
Phiên bản: 1.0.0
Ngày: 2026-03-02
Tiêu chuẩn: ISO 19510:2013 (BPMN 2.0) — Mô hình hóa thực tế
Liên quan: SRD.md | UI_SPEC.md | system-architecture.md
1. Phạm Vi & Tham Chiếu ISO 19510
1.1 Mục đích
Tài liệu này mô hình hóa tất cả quy trình vận hành PTX-CM sử dụng khái niệm Business Process Model and Notation (BPMN 2.0) theo định nghĩa ISO 19510:2013. Các quy trình được trực quan hóa dưới dạng sơ đồ Mermaid để render trực tiếp.
1.2 Mức Độ Tuân Thủ
Mô hình hóa thực tế — không tuân thủ XML nghiêm ngặt. Chúng tôi sử dụng các khái niệm BPMN (tasks, gateways, events, lanes) cho mục đích tài liệu và trực quan hóa. Engine runtime là state machine TypeScript tùy chỉnh (NestJS), không phải bộ thực thi BPMN XML.
1.3 Quy Ước Ký Hiệu Sơ Đồ
| Hình dạng | Cú pháp Mermaid | Phần tử BPMN | Mô tả |
|---|---|---|---|
| Hình chữ nhật bo tròn | ([text]) | User Task | Hành động thủ công cần người nhập liệu |
| Hình chữ nhật | [text] | Service Task | Hành động tự động của hệ thống |
| Hình thoi | {text} | Exclusive Gateway (XOR) | Điểm quyết định, chọn một đường |
| Hình tròn | ((text)) | Start/End Event | Ranh giới quy trình |
| Subgraph | subgraph Name | Pool/Lane | Nhóm tác nhân hoặc hệ thống |
| Mũi tên nét đứt | -.-> | Message/Signal | Kích hoạt liên quy trình |
| Mũi tên đậm | ==> | Critical path | Đường chính (happy path) |
2. Ánh Xạ Khái Niệm ISO 19510
| Phần tử BPMN | Loại ISO 19510 | Triển khai PTX-CM | Thành phần |
|---|---|---|---|
| Pool | Participant | Ranh giới hệ thống (PTX-CM) | Ứng dụng NestJS |
| Lane | Participant | Vai trò tác nhân (U-01–U-07) | RBAC PermissionsGuard |
| User Task | Activity | Hành động UI: click nút, gửi form | React component + API call |
| Service Task | Activity | BullMQ job hoặc thực thi hook | BookingHooksService, SyncEngine |
| Script Task | Activity | Tính toán nội bộ | AvailabilityCalc, DeduplicationLogic |
| Exclusive Gateway | Gateway | Kiểm tra transition + kiểm tra vai trò | BookingStatusTransition.allowedRoles |
| Parallel Gateway | Gateway | Thực thi hook đồng thời | Promise.all(hooks) trong BookingHooksService |
| Timer Start Event | Event | Lịch BullMQ repeatable job | PollingScheduler (mỗi 2-3 phút) |
| Error Boundary Event | Event | Try/catch → Tạo Alert | SyncJob.status=failed → E-11 Alert |
| Message Intermediate Event | Event | Gửi thông báo | send_notification hook (email/LINE) |
| Signal Event | Event | Phát broadcast toàn hệ thống | Phát hiện overbooking → Alert + Dashboard |
| Start Event | Event | Trigger quy trình | API request, BullMQ job trigger, hành động người dùng |
| End Event (terminate) | Event | Trạng thái kết thúc | BookingStatusDef.isTerminal=true |
| Data Object | Data | Thực thể (E-xx) | Prisma model |
| Data Store | Data | PostgreSQL table / Redis cache | Tầng cơ sở dữ liệu |
3. Danh Mục Quy Trình
| ID | Quy trình | Độ phức tạp | Trigger | Tác nhân | FR liên quan |
|---|---|---|---|---|---|
| P-01 | Vòng đời Booking | Cao | OTA sync / thao tác thủ công | Hệ thống, U-04, U-05, U-01/02 | FR-03, FR-25–FR-30, FR-41 |
| P-02 | Pipeline Đồng Bộ OTA | Trung bình | Timer (BullMQ) | Hệ thống | FR-03, FR-04 |
| P-03 | Xử Lý Alert | Thấp | Hệ thống tạo alert | U-04, U-05, U-01/02 | FR-07 |
| P-04 | Quản Lý Khách Hàng | Thấp | Thao tác CS thủ công | U-05, U-01/02 | FR-36–FR-38 |
| P-05 | Onboarding OTA | Trung bình | Hành động Admin | U-01/02 | FR-01, FR-02 |
| P-06 | Thiết Lập Property | Trung bình | Hành động Admin/import | U-01/02, U-04 | FR-05, FR-31–FR-32 |
4. Định Nghĩa Quy Trình
P-01: Vòng Đời Booking
Trigger: Phát hiện booking mới qua OTA sync HOẶC thay đổi trạng thái thủ công
Thực thể: E-08 (Booking), E-07 (Availability), E-12 (AuditLog), E-15 (Transition), E-20 (OtaStatusDef)
Các bước:
| # | Loại BPMN | Tác nhân | Bước | Thành phần |
|---|---|---|---|---|
| 1 | Start Event | Hệ thống | OTA sync phát hiện booking mới/cập nhật | SyncEngine.pullBookings |
| 2 | Service Task | Hệ thống | Upsert booking với dedup (ota_booking_id) | BookingsService.upsertFromOta |
| 3 | Service Task | Hệ thống | Lưu raw OTA status string (chỉ xem) | Booking.otaStatus field |
| 4 | User Task | U-04/05 | Yêu cầu chuyển đổi trạng thái qua UI | PATCH /bookings/:id/status |
| 5 | XOR Gateway | Hệ thống | Kiểm tra transition hợp lệ + vai trò được phép | BookingStatusTransition check |
| 6 | Parallel Gateway | Hệ thống | Thực thi hooks đồng thời | Promise.all([audit, avail, notify]) |
| 7 | End Event | — | Đạt trạng thái terminal | BookingStatusDef.isTerminal |
Ngoại lệ: Transition không hợp lệ → 400. Vai trò bị từ chối → 403. Hook lỗi → ghi log, không chặn transition.
P-02: Pipeline Đồng Bộ OTA
Trigger: BullMQ timer mỗi 2-3 phút
Thực thể: E-04 (OtaAccount), E-05 (OtaConnection), E-08 (Booking), E-07 (Availability), E-09 (SyncJob)
Các bước:
| # | Loại BPMN | Tác nhân | Bước | Thành phần |
|---|---|---|---|---|
| 1 | Timer Start | Hệ thống | BullMQ repeatable job kích hoạt | PollingScheduler |
| 2 | Service Task | Hệ thống | Tạo bản ghi SyncJob (pending) | SyncJobsService |
| 3 | Service Task | Hệ thống | Lấy OtaConnections đang hoạt động | OtaConnectionsService |
| 4 | XOR Gateway | Hệ thống | Kiểm tra tính hợp lệ session OtaAccount | OtaAccount.status check |
| 5 | Service Task | Hệ thống | Pull bookings qua OTA adapter | OtaAdapter.fetchBookings |
| 6 | Service Task | Hệ thống | Upsert + dedup bookings | BookingsService.upsertFromOta |
| 7 | Script Task | Hệ thống | Tính lại availability phòng | AvailabilityCalc |
| 8 | XOR Gateway | Hệ thống | Kiểm tra nếu đã đặt > tổng phòng | Phát hiện overbooking |
| 9 | Service Task | Hệ thống | Đẩy availability tới các OTA khác | OtaAdapter.pushAvailability |
| 10 | End Event | Hệ thống | Đánh dấu SyncJob completed/failed | SyncJob.status update |
Ngoại lệ: Session hết hạn → Alert + bỏ qua. Lỗi fetch → SyncJob failed + retry (3x backoff). Lỗi push → partial sync được ghi log.
P-03: Xử Lý Alert
Trigger: Hệ thống tạo alert (overbooking, lỗi đồng bộ, session hết hạn)
Thực thể: E-11 (Alert)
Các bước:
| # | Loại BPMN | Tác nhân | Bước |
|---|---|---|---|
| 1 | Signal Start | Hệ thống | Alert được tạo (E-11) bởi sync engine hoặc kiểm tra availability |
| 2 | Service Task | Hệ thống | Gửi thông báo (email/LINE) |
| 3 | User Task | U-04/05 | Xem xét alert trên dashboard |
| 4 | XOR Gateway | U-04/05 | Quyết định: xử lý hoặc chuyển tiếp |
| 5 | User Task | U-04/05 | Thêm ghi chú xử lý |
| 6 | End Event | — | Alert đánh dấu đã xử lý |
P-04: Quản Lý Khách Hàng
Trigger: CS tạo hồ sơ khách hàng hoặc liên kết booking
Thực thể: E-19 (Customer), E-08 (Booking)
Các bước:
| # | Loại BPMN | Tác nhân | Bước |
|---|---|---|---|
| 1 | User Task | U-05 | Tạo hồ sơ khách hàng |
| 2 | User Task | U-05 | Tìm kiếm/chọn bookings chưa liên kết |
| 3 | Service Task | Hệ thống | Gợi ý (fuzzy match tên/email) |
| 4 | User Task | U-05 | Liên kết bookings đã chọn |
| 5 | XOR Gateway | U-05 | Phát hiện khách hàng trùng lặp |
| 6 | User Task | U-05 | Xác nhận gộp |
| 7 | Service Task | Hệ thống | Transaction gộp nguyên tử |
P-05: Onboarding OTA
Trigger: Admin kết nối tài khoản OTA mới
Thực thể: E-04 (OtaAccount), E-02 (Property), E-03 (RoomType), E-05 (OtaConnection), E-06 (OtaRoomMapping)
Các bước:
| # | Loại BPMN | Tác nhân | Bước |
|---|---|---|---|
| 1 | User Task | U-01/02 | Chọn OTA, nhập thông tin đăng nhập |
| 2 | XOR Gateway | U-01/02 | Chọn phương thức 2FA |
| 3 | Service Task | Hệ thống | Kiểm tra kết nối qua Playwright |
| 4 | XOR Gateway | Hệ thống | Kết nối thành công/thất bại |
| 5 | Service Task | Hệ thống | Khám phá properties từ OTA |
| 6 | Script Task | Hệ thống | Đối chiếu property cross-OTA |
| 7 | User Task | U-01/02 | Chọn properties để import |
| 8 | Service Task | Hệ thống | Tạo hàng loạt thực thể |
P-06: Thiết Lập Property
Trigger: Admin tạo property thủ công hoặc import từ OTA
Thực thể: E-02 (Property), E-03 (RoomType), E-05 (OtaConnection), E-17 (SupplierRoomAllocation)
Các bước:
| # | Loại BPMN | Tác nhân | Bước |
|---|---|---|---|
| 1 | User Task | U-01/02 | Nhập thông tin property |
| 2 | User Task | U-01/02 | Thêm loại phòng |
| 3 | XOR Gateway | U-01/02 | Kết nối tới OTA? |
| 4 | User Task | U-04 | Ánh xạ loại phòng tới OTA |
| 5 | XOR Gateway | U-01/02 | Phân bổ nhà cung cấp? |
| 6 | User Task | U-01/02 | Đặt phân bổ nhà cung cấp |
| 7 | XOR Gateway | Hệ thống | Kiểm tra tổng phân bổ (cảnh báo nhẹ) |
5. Ma Trận Tương Tác Quy Trình
| Nguồn | Đích | Cơ chế Trigger | Luồng Dữ Liệu |
|---|---|---|---|
| P-05 → P-06 | Onboarding OTA → Thiết Lập Property | Import property tạo thực thể | E-02, E-03, E-05, E-06 |
| P-05 → P-02 | Onboarding OTA → Đồng Bộ OTA | OtaConnection mới kích hoạt polling | E-05 isActive=true |
| P-02 → P-01 | Đồng Bộ OTA → Vòng Đời Booking | Upsert booking tạo/cập nhật E-08 | E-08 với status=confirmed |
| P-02 → P-03 | Đồng Bộ OTA → Xử Lý Alert | Phát hiện lỗi sync hoặc overbooking | E-11 Alert được tạo |
| P-01 → P-04 | Vòng Đời Booking → QL Khách Hàng | CS liên kết booking với hồ sơ khách | E-08.customerId được gán |
6. Mức Độ Trưởng Thành & Tự Động Hóa
| Quy trình | Trạng thái hiện tại | Mức tự động hóa | Engine |
|---|---|---|---|
| P-01 Vòng Đời Booking | ✅ Đã triển khai | State machine + hooks | BookingStatusTransition table |
| P-02 Pipeline Đồng Bộ OTA | ⚠️ Một phần (adapters stubbed) | BullMQ job queue | PollingScheduler + SyncEngine |
| P-03 Xử Lý Alert | ✅ Đã triển khai | Thủ công (UI-driven) | AlertsService.resolve |
| P-04 Quản Lý Khách Hàng | ✅ Đã triển khai | Thủ công (UI-driven) | CustomersService CRUD |
| P-05 Onboarding OTA | ⚠️ Một phần (connection stubbed) | Wizard-guided | OtaAccountsService + S-06 |
| P-06 Thiết Lập Property | ✅ Đã triển khai | Thủ công (UI-driven) | PropertiesService CRUD |
7. Phase B: Workflow Engine Tổng Quát — ĐÃ TRIỂN KHAI
Phase B tổng quát hóa state machine booking để hỗ trợ nhiều loại quy trình:
7.1 Thực Thể Thêm Mới (Phase B)
| Thực thể | Mã | Mục đích |
|---|---|---|
| ProcessType | E-21 | Đăng ký định nghĩa quy trình (6 loại seed: booking, ota_sync, alert_resolution, customer_mgmt, ota_onboarding, property_setup) |
| ProcessInstance | E-22 | Theo dõi thực thi quy trình (đa hình: bất kỳ entity_type) |
7.2 Thực Thể Nâng Cấp (Phase B)
- BookingStatusDef — thêm FK
processTypeKey, mặc định='booking' để tương thích ngược - BookingStatusTransition — thêm FK
processTypeKey, mặc định='booking' để tương thích ngược
7.3 Trạng Thái Hoàn Thành Phase B
| Thành phần | Trạng thái |
|---|---|
| Database schema (E-21, E-22) | ✅ Đã triển khai |
| API endpoints (/process-types, /process-status, /process-transitions, /process-instances) | ✅ Đã triển khai |
| Tab Workflow trong Settings (S-16) | ✅ Đã triển khai |
| Tab Process Management (S-28) | ✅ Đã triển khai |
| Trang Process Instances (S-29) | ✅ Đã triển khai |
| Đăng ký NestJS modules | ✅ Đã triển khai |
| BookingHooksService tổng quát hóa với hỗ trợ entityType | ✅ Đã triển khai |
7.4 Tương Thích Ngược
Workflow booking hiện tại được bảo toàn qua processTypeKey = 'booking' mặc định trên tất cả bản ghi status/transition. Không có breaking changes cho quy trình P-01 Vòng Đời Booking.
Xem SRD.md FR-44 đến FR-47 để biết chi tiết yêu cầu.