Đề 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:
- 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. - Đẩ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.
- Đố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,Orderhiệ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ệc | Chạy ở | Tần suất gọi Core |
|---|---|---|
| Hiển thị UI, tìm trạm, xem giờ trống | Edge | 0 (đọc snapshot giờ trống đã cache) |
| Giữ chỗ khi bấm "Đặt" | Core | 1 lệnh nhẹ / lượt đặt (vài ms) |
| Thanh toán, OTP, SMS/Zalo, hoá đơn | Edge | 0 |
| Xuất snapshot giờ trống | Core | 1 job / 30–60 giây, Edge tải theo ETag |
| Nhận sự kiện | Core | 1 request / lô (hàng trăm sự kiện) |
| Check-in tại trạm | Core | Như hiện tại, đọc bảng tham chiếu |
| Dashboard | Core | Đọc bảng tổng hợp, không gọi đối tác |
| Đối soát | Core | 1 lần / kênh / ngày |
7. Dashboard giám sát lấy gì
- Số lịch theo kênh / trạm / ngày, tỷ lệ huỷ, tỷ lệ check-in: từ
ChannelScheduleRef. - Doanh thu, phí kênh, trạng thái thanh toán: từ
ChannelOrderRef+Order. - Sức khoẻ kênh: độ trễ đồng bộ = now −
lastHeartbeatAt, khoảng hở seq, số lô bị từ chối chữ ký. - Tỷ lệ lấp đầy slot theo trạm và kênh, số lượt giữ chỗ hết hạn, số lần trả về FULL (nhu cầu bị từ chối).
- Kết quả đối soát: số ngày MATCHED / MISMATCH theo kênh.
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.
- 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ữ.
- 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)?
- 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.
- Độ 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ô.
- Đơn hàng không gắn lịch (bảo hiểm, sản phẩm khác): dùng chung
ChannelOrderRefvớischeduleCoderỗng.