Đặt lịch đa kênh phân tán
Đề xuất kiến trúc · Station Server · 15/11/2026

Đặt lịch & đơn hàng đa kênh, dữ liệu phân tán

Frontend + backend chạy trên hạ tầng của từng ngân hàng / ví điện tử (gọi là Edge node). Server hiện tại (Core) chỉ giữ bộ đếm slot dùng chung, bảng tham chiếu mỏng và sổ sự kiện có ký số. Đối tác gánh phần lớn tải; Core vẫn là nơi quyết định dữ liệu cuối cùng và cấp số liệu cho dashboard.

1. Ý tưởng cốt lõi

Không đồng bộ từng bản ghi giữa các nơi. Thay vào đó dùng ba cơ chế rẻ hơn nhiều:

  1. Một bộ đếm slot chung ở Core, không chia quota. Mọi kênh, kể cả app và trạm nội bộ, cùng giữ chỗ trên một bộ đếm cho mỗi trạm/ngày/khung giờ. Ai đặt trước được trước, nên không có nơi thừa nơi thiếu. Mỗi lượt đặt chỉ tốn 1 lệnh gọi rất nhẹ: UPDATE ... SET reserved = reserved + 1 WHERE reserved < capacity. Phần nặng (xem giờ trống, thanh toán, thông báo) vẫn ở Edge. Danh sách giờ trống lấy từ ảnh chụp (snapshot) do Core xuất sẵn mỗi 30–60 giây, Edge tự cache.
  2. Đẩy sự kiện một chiều (outbox → ingest). Mỗi thay đổi ở Edge ghi vào bảng outbox, gom lô rồi đẩy về Core. Mỗi sự kiện có số thứ tự liên tục và chuỗi hash, ký bằng khoá của đối tác. Core phát hiện được thiếu, trùng hoặc bị sửa mà không cần đọc DB của đối tác.
  3. Đối soát cuối ngày. Edge gửi tổng (số lượng, tổng tiền, hash cuối chuỗi). Core so với dữ liệu đã nhận. Lệch thì yêu cầu gửi lại đoạn thiếu. Tương thích với hướng đặc tả đối soát OpenAPI V2 hiện có trong repo.
Core · server hiện tại

Giữ ít, nhưng là bản quyết định

  • CustomerSchedule, Order hiện tại giữ nguyên cho kênh nội bộ (app, web, trạm).
  • Bảng mới ChannelScheduleRef, ChannelOrderRef: chỉ cột cần cho trạm check-in, báo cáo và đối soát.
  • SlotCapacity: bộ đếm sức chứa dùng chung cho mọi kênh. SlotHold: từng lượt giữ chỗ của các kênh.
  • ChannelEventLog: sổ sự kiện chỉ ghi thêm, có ký số.
  • Dashboard đọc từ bảng tham chiếu và bảng tổng hợp, không gọi sang đối tác.
Edge · tại ngân hàng / ví

Gánh tải người dùng

  • Toàn bộ UI, tìm trạm, chọn giờ, thanh toán, OTP, thông báo.
  • DB riêng: hồ sơ khách hàng đầy đủ, dữ liệu riêng của đối tác (Core không cần biết).
  • Cache snapshot giờ trống, chỉ gọi Core 1 lần khi khách bấm "Đặt".
  • Outbox + worker đẩy lô sự kiện, thử lại khi lỗi.
  • API tra cứu chi tiết (tuỳ chọn) để trạm xem thêm khi cần.

2. Tổng quan triển khai

flowchart LR
  subgraph BankA["Ngân hàng A (hạ tầng đối tác)"]
    UA[Người dùng app NH A] --> FEA[Frontend]
    FEA --> BEA[Backend Edge]
    BEA --> DBA[(DB riêng NH A
booking + PII + outbox)] end subgraph WalletB["Ví điện tử B (hạ tầng đối tác)"] UB[Người dùng ví B] --> FEB[Frontend] FEB --> BEB[Backend Edge] BEB --> DBB[(DB riêng ví B)] end subgraph Core["Core · Station Server"] QS[Slot Service
bộ đếm chung + snapshot] IG[Event Ingest
verify chữ ký + hash chain] RC[Reconciliation] REF[(ChannelScheduleRef
ChannelOrderRef
ChannelEventLog)] CS[(CustomerSchedule
Order hiện tại)] DASH[Dashboard giám sát] ST[App trạm đăng kiểm] end BEA -- "1. giữ chỗ (1 lệnh / lượt đặt)" --> QS BEB -- "1. giữ chỗ" --> QS BEA -- "2. đẩy lô sự kiện (async)" --> IG BEB -- "2. đẩy lô sự kiện" --> IG BEA -- "3. tổng cuối ngày" --> RC BEB -- "3. tổng cuối ngày" --> RC IG --> REF RC --> REF QS --> CS QS -. "snapshot giờ trống 30-60s" .-> BEA QS -. "snapshot" .-> BEB REF --> DASH CS --> DASH ST -- "check-in theo biển số / mã" --> REF ST -. "xem chi tiết (tuỳ chọn)" .-> BEA

3. Sequence: đặt lịch qua kênh đối tác

Xem giờ trống, thanh toán, thông báo đều ở Edge. Core chỉ nhận đúng 1 lệnh đồng bộ là giữ chỗ, mọi thứ khác về Core theo lô bất đồng bộ.

sequenceDiagram
  autonumber
  actor U as Người dùng (app NH/ví)
  participant E as Edge Backend
  participant EDB as Edge DB (+outbox)
  participant Q as Core · Slot Service
  participant I as Core · Event Ingest
  participant R as Core · Ref tables

  rect rgba(11,110,110,0.08)
  Note over E,Q: Nền: Core xuất snapshot giờ trống mỗi 30-60s
  E->>Q: GET snapshot (ETag, chỉ tải khi có thay đổi)
  Q-->>E: số chỗ còn theo trạm / ngày / khung giờ
  end

  U->>E: Xem trạm, ngày, giờ trống
  E-->>U: Trả từ cache Edge (không gọi Core)
  U->>E: Bấm Đặt (biển số, giờ)
  E->>EDB: INSERT EdgeBooking (PENDING)
  E->>Q: reserve(slotKey, channelBookingId, HOLD hoặc CONFIRM) - lệnh đồng bộ duy nhất
  Q->>Q: UPDATE SlotCapacity SET reserved+1 WHERE reserved < capacity
  alt Còn chỗ
    Q->>Q: INSERT SlotHold(holdId, hết hạn sau 15 phút)
    Q-->>E: OK, holdId
    E->>EDB: thanh toán nếu có, CONFIRMED + OutboxEvent(BOOKING_CONFIRMED, holdId)
    E-->>U: Xác nhận, mã lịch hẹn CH-NHA-xxxx
  else Hết chỗ
    Q-->>E: FULL + 3 khung giờ gần nhất còn chỗ
    E-->>U: Gợi ý khung giờ khác
  end

  loop Outbox worker (mỗi vài giây, gom tối đa 500 sự kiện)
    E->>EDB: lấy sự kiện chưa gửi theo seq
    E->>I: POST /channel/events (lô, chữ ký Ed25519)
    I->>I: verify chữ ký, seq liên tục, hash chain, idempotent theo eventId
    I->>R: upsert ChannelScheduleRef, append ChannelEventLog
    I->>Q: SlotHold chuyển CONFIRMED
    I-->>E: ack lastSeq
    E->>EDB: đánh dấu đã gửi đến lastSeq
  end
  

4. Sequence: check-in tại trạm, huỷ lịch và đối soát

sequenceDiagram
  autonumber
  participant ST as App trạm
  participant R as Core · Ref tables
  participant I as Core · Event Ingest
  participant E as Edge Backend
  participant RC as Core · Reconciliation
  participant D as Dashboard

  Note over ST,R: Trạm chỉ cần bảng tham chiếu, không gọi đối tác
  ST->>R: Tìm lịch theo biển số + ngày (gộp nội bộ và mọi kênh)
  R-->>ST: scheduleCode, giờ, kênh, trạng thái
  ST->>R: Cập nhật CHECKED_IN / COMPLETED
  R->>I: tạo sự kiện chiều ngược (Core → kênh)
  I-->>E: webhook trạng thái (lô, có retry)

  Note over E: Người dùng huỷ trên app ngân hàng
  E->>E: Huỷ local, ghi outbox BOOKING_CANCELED
  E->>I: đẩy trong lô kế tiếp
  I->>R: status = CANCELED, reserved - 1 (slot trả lại cho mọi kênh)

  Note over E,RC: 00:30 hằng ngày
  E->>RC: daySummary(channel, date, count, tổng tiền, lastSeq, lastHash)
  RC->>R: tính lại từ ChannelEventLog
  alt Khớp
    RC-->>E: MATCHED
  else Lệch (thiếu seq / khác hash)
    RC-->>E: yêu cầu gửi lại seq từ a đến b
    E->>I: gửi lại đoạn thiếu
  end
  RC->>R: dọn SlotHold treo, khớp reserved với số lịch thực
  R->>D: số liệu tổng hợp theo kênh / trạm / ngày
  

5. Class diagram

Phần Core thêm 6 bảng nhỏ, không sửa cấu trúc CustomerSchedule hiện có (đã có sẵn partnerName, partnerTranID, scheduleHash có thể dùng cho kênh nội bộ). Phần Edge là gợi ý tối thiểu cho đối tác, họ được thêm bảng riêng tuỳ ý.

classDiagram
  direction LR

  class Channel {
    +int channelId
    +string channelCode  "NH_A, VI_B"
    +string channelType  "BANK | EWALLET"
    +string publicKey    "Ed25519, verify sự kiện"
    +string webhookUrl
    +int lastAckSeq
    +string lastHash
    +datetime lastHeartbeatAt
    +int status
  }

  class SlotCapacity {
    +bigint slotId
    +int stationsId
    +string dateSchedule
    +string timeSlot
    +int capacity
    +int reserved
    +int version
    +reserve() bool
    +release()
  }

  class SlotHold {
    +string holdId
    +bigint slotId
    +int channelId
    +string channelBookingId  "khoá idempotent"
    +int status  "HELD | CONFIRMED | RELEASED | EXPIRED"
    +datetime expiresAt
  }

  class ChannelScheduleRef {
    +bigint refId
    +int channelId
    +string channelBookingId  "id phía đối tác"
    +string scheduleCode
    +int stationsId
    +string licensePlates
    +string dateSchedule
    +string time
    +int vehicleType
    +string phoneHash  "không lưu số gốc"
    +int status
    +string holdId
    +bigint lastEventSeq
    +datetime updatedAt
    +findByPlate(plate, date)
  }

  class ChannelOrderRef {
    +bigint refId
    +int channelId
    +string channelOrderId
    +string scheduleCode
    +decimal totalAmount
    +decimal channelFee
    +string paymentRef
    +int paymentStatus
    +bigint lastEventSeq
  }

  class ChannelEventLog {
    +bigint id
    +int channelId
    +bigint seq
    +string eventId  "unique, chống trùng"
    +string eventType
    +json payload  "chỉ trường tham chiếu"
    +string prevHash
    +string hash
    +string signature
    +datetime receivedAt
    +verify()
  }

  class ReconciliationBatch {
    +int batchId
    +int channelId
    +string date
    +int partnerCount
    +int coreCount
    +decimal partnerAmount
    +decimal coreAmount
    +string partnerLastHash
    +int result  "MATCHED | MISMATCH | RESOLVED"
  }

  class CustomerSchedule {
    <>
    +int customerScheduleId
    +string scheduleCode
    +int stationsId
    +string partnerName
    +string partnerTranID
  }

  class Order {
    <>
    +int orderId
  }

  class EdgeBooking {
    <>
    +id
    +customer PII đầy đủ
    +dữ liệu riêng đối tác
    +status
  }

  class OutboxEvent {
    <>
    +seq
    +eventId
    +eventType
    +payload
    +prevHash
    +hash
    +sentAt
  }

  class AvailabilityCache {
    <>
    +snapshot
    +etag
    +fetchedAt
  }

  Channel "1" --> "*" SlotHold
  Channel "1" --> "*" ChannelScheduleRef
  Channel "1" --> "*" ChannelOrderRef
  Channel "1" --> "*" ChannelEventLog
  Channel "1" --> "*" ReconciliationBatch
  SlotCapacity "1" --> "*" SlotHold : giữ chỗ
  SlotHold "1" --> "0..1" ChannelScheduleRef
  ChannelScheduleRef "1" --> "0..1" ChannelOrderRef
  ChannelEventLog ..> ChannelScheduleRef : dựng lại trạng thái
  CustomerSchedule ..> SlotCapacity : kênh nội bộ trừ chung bộ đếm
  ChannelOrderRef ..> Order : gộp báo cáo doanh thu
  EdgeBooking "1" --> "*" OutboxEvent
  AvailabilityCache ..> SlotCapacity : snapshot chỉ đọc
  OutboxEvent ..> ChannelEventLog : đẩy lô, ký số
  

6. Ai chịu tải gì

Công việcChạy ởTần suất gọi Core
Hiển thị UI, tìm trạm, xem giờ trốngEdge0 (đọc snapshot giờ trống đã cache)
Giữ chỗ khi bấm "Đặt"Core1 lệnh nhẹ / lượt đặt (vài ms)
Thanh toán, OTP, SMS/Zalo, hoá đơnEdge0
Xuất snapshot giờ trốngCore1 job / 30–60 giây, Edge tải theo ETag
Nhận sự kiệnCore1 request / lô (hàng trăm sự kiện)
Check-in tại trạmCoreNhư hiện tại, đọc bảng tham chiếu
DashboardCoreĐọc bảng tổng hợp, không gọi đối tác
Đối soátCore1 lần / kênh / ngày

7. Dashboard giám sát lấy gì

8. Những điểm cần quyết định

Điểm đồng bộ duy nhất là lệnh giữ chỗ. Nếu Core không phản hồi, Edge không xác nhận được lịch. Phương án dự phòng: Edge nhận yêu cầu ở trạng thái "chờ xác nhận", tự thử lại và báo khách khi có kết quả. Để Core không thành điểm nghẽn, tách lệnh giữ chỗ thành một service nhỏ riêng (Redis hoặc bảng riêng), không chạy chung tiến trình với các API nặng hiện tại.
  1. Thời gian giữ chỗ. Bao lâu là đủ cho bước thanh toán (gợi ý 15 phút)? Lịch miễn phí thì xác nhận luôn trong 1 lệnh, không cần giữ.
  2. Trường dữ liệu tối thiểu ở Core. Trạm cần biển số, giờ, loại xe để check-in. Số điện thoại và họ tên có cần không, hay chỉ lưu hash và gọi sang Edge khi cần (tác động tới Nghị định 13/2023 về bảo vệ dữ liệu cá nhân và hợp đồng với ngân hàng)?
  3. Ràng buộc với đối tác. Phiên bản Edge do mình phát hành (bắt buộc cập nhật), đối tác có được sửa code không? Nếu có, hash chain + chữ ký vẫn đảm bảo Core phát hiện gian lận dữ liệu đã gửi, nhưng không bắt được sự kiện bị giấu từ đầu; đối soát doanh thu với cổng thanh toán là lớp kiểm tra thứ hai.
  4. Độ trễ chấp nhận được. Dashboard trễ vài giây đến vài phút có ổn không? Nếu cần gần thời gian thực, giảm kích thước lô.
  5. Đơn hàng không gắn lịch (bảo hiểm, sản phẩm khác): dùng chung ChannelOrderRef với scheduleCode rỗng.