Cổng gửi vé VeXeRe cho nhà xe

0. Tóm tắt điều hành

Hệ thống cần xây là một cổng tập trung của nhà xe để nhiều đại lý bán vé gửi vé về, nhà xe xếp chỗ (tự động qua API VeXeRe hoặc thủ công), rồi xuất vé cho từng khách và gửi qua SMS (SIM thường), email, Zalo OA, Zalo cá nhân, kèm thống kê và đối soát riêng từng đại lý. Đại lý được đẩy lên, thêm, sửa, xoá vé của mình trong giới hạn quyền theo trạng thái vé.

Năm kết luận chính sau khi đọc tài liệu:

1. Tài liệu VeXeRe cung cấp là góc nhìn ĐẠI LÝ (AMS + API đối tác), không phải góc nhìn nhà xe (BMS). Gửi vé "lên VeXeRe" bằng API này nghĩa là đặt chỗ như một đại lý: có hạn mức, có chiết khấu, có chính sách huỷ của VeXeRe. Cần xác nhận với VeXeRe tài khoản API cấp cho nhà xe (mục 11, câu 1).
2. API đủ để tự động hoá vòng đời vé: tìm chuyến → sơ đồ ghế → giữ chỗ → thanh toán → tra cứu → huỷ → sửa điểm đón/trả, và webhook báo ngược khi vé bị đổi giờ/huỷ/cập nhật giá cọc. Thiếu hai thứ: API đổi ngày/giờ (chỉ làm tay trên AMS) và API tra hạn mức.
3. Giữ chỗ chưa thanh toán sẽ tự huỷ đến expired_time; chuyến bị tắt bán trực tuyến trước giờ khởi hành N giờ. Hệ thống phải có đồng hồ theo dõi hai mốc này, không được phó mặc cho người trực.
4. Xây mới hoàn toàn trên VPS Linux riêng: mã, CSDL, tiến trình mới; Vé247/OSZalo/web chỉ là tài liệu nghiệp vụ và mã mẫu. Bộ công nghệ đề xuất (mục 4.7, phân tích sâu ở tài liệu 01): Node.js + TypeScript (NestJS), PostgreSQL, Redis + BullMQ, React + Vite (PWA); chạy trên aaPanel như các Node project gắn domain riêng (nginx + SSL của aaPanel), PostgreSQL/Redis/Google Drive cài từ App Store, sao lưu bằng Cron aaPanel lên Google Drive; Zalo cá nhân chạy trong worker riêng bằng zca-js; SMS qua máy Android + SIM chạy ứng dụng gateway.
5. Đối soát phải khoá kỳ: mỗi vé mang ba con số (giá bán, tiền VeXeRe ghi nhận, hoa hồng đại lý) và một trạng thái cuối; chốt kỳ thì vé không sửa được nữa; biên bản xuất Excel theo đại lý.
6. Lõi quản lý vé + mô-đun cắm/rút: lõi chỉ giữ thực thể vé, vòng đời, sự kiện, quyền, vết, cấu hình; mọi thứ khác (VeXeRe, từng kênh gửi, đẩy danh sách, đối soát, nguồn liên thông) là mô-đun có hợp đồng và phiên bản riêng, bật/tắt bằng cấu hình, nâng cấp không đụng lõi và không đụng nhau (mục 4.9). Tài liệu đi cùng mã: thiết kế, hướng dẫn sử dụng, bàn giao, kinh nghiệm nằm trong kho mã, cập nhật trong cùng một lần thay đổi và được CI kiểm tra (mục 4.10).

1. Bối cảnh và những gì tài liệu cho biết

1.1 Rút ra từ HDSD AMS (bản 7/2022)

AMS là phần mềm web cho đại lý đặt vé trên mọi nhà xe có bán trên VeXeRe. Các quy tắc nghiệp vụ ảnh hưởng trực tiếp đến thiết kế:

1.2 Rút ra từ tài liệu API đối tác (vdoc.vexere.net, đọc ngày 02/9/2026)

Môi trường: UAT (uat-api.vexere.net, uat-vroute.vexere.net, uat-account-service.vexere.net) và PRO (api.vexere.com, vroute.vexere.com, account-service.vexere.com). UAT có sẵn client_id/secret thử nghiệm trong tài liệu.

Xác thực: POST {account}/v3/token với grant_type=client_credentials; token sống 1 giờ; mọi API khác dùng Authorization: Bearer.

Mã lỗi cần xử lý riêng: 3403 SEAT_IS_NOT_AVAILABLE (chọn lại ghế, thử tối đa 3 lần), 3308 TRIP_IS_NOT_BOOKABLE (chuyển thủ công), 3317 BOOKING_EXPIRED, 3301 BOOKING_PAID, 3302 BOOKING_CANCELLED, 3101/3115/3118/3120 tham số sai (lỗi dữ liệu, không thử lại).

Điểm mâu thuẫn trong tài liệu cần hỏi VeXeRe: mục Update ticket info ghi "booking status = 2 (booked)" trong khi Get booking ghi "1-Reserve". Thiết kế coi giá trị trả về của GET /v3/booking là chuẩn.

1.3 Hệ thống hiện có: chỉ là tài liệu tham khảo và mã mẫu

Cổng gửi vé được xây mới hoàn toàn trên một VPS Linux riêng: mã nguồn mới, CSDL mới, tiến trình mới; không dùng chung máy chủ, CSDL hay thư viện lúc chạy với Vé247/OSZalo. Ba hệ thống cũ chỉ đóng vai trò tài liệu nghiệp vụ và mã mẫu để rút ngắn thiết kế chi tiết:

Sau khi cổng ổn định, các hệ thống cũ có thể đẩy vé vào cổng qua API liên thông (mục 4.6) với tư cách một "nguồn". Đó là tích hợp tuỳ chọn, không phải điều kiện để cổng chạy.

2. Mục tiêu, phạm vi, tác nhân

2.1 Mục tiêu đo được

• Đại lý nhập một vé dưới 30 giây trên điện thoại; đẩy danh sách 50 vé dưới 2 phút kể cả sửa lỗi.
• Vé hợp lệ được xếp tự động qua API và gửi khách trong vòng 2 phút (trường hợp ghế còn, chuyến còn bán online).
• Khách nhận vé qua ít nhất một kênh ≥ 99 % (SMS là kênh bảo đảm, các kênh khác là bổ sung).
• Mọi thay đổi vé đều có vết (ai, lúc nào, trước/sau).
• Chốt đối soát tháng cho một đại lý dưới 10 phút, có biên bản Excel.

2.2 Ngoài phạm vi (phiên bản 1)

• Không thay thế AMS/BMS của VeXeRe; không quản lý sơ đồ ghế của nhà xe.
• Không thu tiền online (dùng kênh thanh toán online của VeXeRe nếu cần).
• Không xây app di động gốc cho đại lý (web mobile-first/PWA là đủ).
• Không tích hợp cổng SMS thương hiệu (brandname) — chỉ SIM thường theo yêu cầu.

2.3 Tác nhân

3. Nghiệp vụ và quy trình

3.1 Vòng đời một vé

stateDiagram-v2
    [*] --> NHAP: đại lý tạo (form/danh sách/API)
    NHAP --> DA_DAY: đại lý bấm "Đẩy lên"
    DA_DAY --> DANG_XEP: điều hành nhận / máy tự xếp
    DANG_XEP --> DA_XEP: có ghế + mã VeXeRe (hoặc xếp tay)
    DANG_XEP --> TU_CHOI: hết chỗ / chuyến ẩn / dữ liệu sai
    TU_CHOI --> NHAP: đại lý sửa, đẩy lại
    DA_XEP --> DA_XUAT: bộ xuất vé dựng nội dung
    DA_XUAT --> DA_GUI: ≥ 1 kênh gửi thành công
    DA_GUI --> HOAN_THANH: qua giờ khởi hành + 1 ngày
    DA_XEP --> HUY: huỷ (đại lý yêu cầu → điều hành duyệt / webhook VeXeRe)
    DA_XUAT --> HUY
    DA_GUI --> HUY
    DA_DAY --> HUY: đại lý tự huỷ khi chưa xếp
    HUY --> [*]
    HOAN_THANH --> [*]

Quy tắc quyền theo trạng thái (chi tiết ở mục 7):

Trạng thái gửi theo từng kênh là lớp riêng trên vé: mỗi vé có N bản ghi gui_tin (kênh, người nhận, CHO_GUI → DANG_GUI → DA_GUI/LOI → DA_XEM nếu kênh báo được). Vé đạt DA_GUI khi có ít nhất một kênh DA_GUI.

3.2 Luồng 1 — Đại lý nhập thủ công

1. Đại lý mở cổng trên điện thoại → Vé mới. Form gồm: SĐT khách (bắt buộc, 10 số), tên khách, số khách, loại chỗ (ghế/giường/cabin/…), tuyến (chọn từ danh sách tuyến nhà xe), ngày đi, giờ đi (chọn trong lịch chuyến), điểm đón, điểm trả, ghi chú cho nhà xe, giá bán, tiền đã thu (đã thu tại đại lý / thu tại xe / chuyển khoản), kênh gửi cho khách (mặc định theo cấu hình đại lý), email (nếu chọn kênh email).
2. Hệ thống kiểm tra tức thì: trùng SĐT + ngày + giờ (cảnh báo, không chặn); giờ đi đã qua mốc tắt bán (cảnh báo "sẽ xếp thủ công"); điểm đón có trong danh sách của chuyến.
3. Bấm Lưu nháp (NHAP) hoặc Đẩy lên (DA_DAY). Đẩy lên tạo mã vé nội bộ dạng VX-YYMMDD-NNNN.
4. Đại lý thấy vé trong Vé của tôi với trạng thái thời gian thực (SSE).

3.3 Luồng 2 — Đẩy danh sách

Ba cách nhập, cùng một bộ kiểm tra:

Quy trình: tải lên → hệ thống dựng bảng xem trước có cột Kết quả kiểm tra (hợp lệ / cảnh báo / lỗi + lý do) → đại lý sửa tại chỗ trong bảng → bấm Đẩy các dòng hợp lệ → tạo một lô (lo_day) và N vé DA_DAY; dòng lỗi giữ lại trong lô để sửa tiếp. Toàn bộ hoặc không: không, vì thực tế một dòng sai không nên chặn 49 dòng đúng; nhưng lô ghi rõ số dòng thành công/lỗi.

Kiểm tra bắt buộc: SĐT hợp lệ; ngày ≥ hôm nay; giờ có trong lịch chuyến của tuyến; số khách 1–8 mỗi dòng (hơn thì tự tách); trùng lặp trong cùng lô (SĐT + ngày + giờ) hỏi gộp hay tách.

3.4 Luồng 3 — Xếp vé

Ba chế độ, cấu hình theo tuyến hoặc theo vé:

sequenceDiagram
    autonumber
    participant DL as Đại lý
    participant C as Cổng gửi vé
    participant DH as Điều hành
    participant VX as VeXeRe API
    DL->>C: Đẩy vé (DA_DAY)
    C->>C: Tìm tuyến → from_id/to_id, company_id
    C->>VX: GET /v2/route (ngày, from, to, online_ticket=1)
    VX-->>C: danh sách chuyến của nhà xe
    C->>C: Khớp giờ đi (± dung sai) → trip_code
    C->>VX: GET /v3/trip/seat_map?trip_code
    VX-->>C: ghế trống, giá, điểm đón/trả
    C->>C: Chọn ghế theo luật (loại chỗ, tầng, kề nhau)
    alt Tự động hoàn toàn
        C->>VX: POST /v3/booking/reserve
        VX-->>C: booking_code, ticket code, partner_code
        opt Đại lý đã thu tiền
            C->>VX: POST /v3/booking/pay (transaction_id = mã vé nội bộ)
        end
        C->>VX: GET /v3/booking?code (biển số, tài xế, giờ đón)
        C->>C: DA_XEP → xuất vé → gửi
    else Bán tự động (mặc định giai đoạn đầu)
        C->>DH: Đề xuất ghế + giá, chờ bấm "Xác nhận"
        DH->>C: Xác nhận / đổi ghế / từ chối
        C->>VX: reserve (+ pay) như trên
    else Thủ công (chuyến ẩn, hết ghế, lỗi API)
        DH->>DH: Xếp trên AMS/BMS hoặc gọi nhà xe
        DH->>C: Nhập mã vé/ghế/biển số → DA_XEP
    end
    C-->>DL: Trạng thái đổi thời gian thực

Luật chọn ghế (cấu hình được): đúng loại chỗ đại lý ghi; ưu tiên ghế kề nhau cho nhóm; ưu tiên tầng dưới cho người già/trẻ em nếu ghi chú; không lấy ghế có phụ thu khác giá bán trừ khi đại lý cho phép; nếu chuyến có nhiều mức giá thì hiện chênh lệch cho điều hành. Khi 3403 SEAT_IS_NOT_AVAILABLE → tải lại sơ đồ, chọn lại, tối đa 3 lần rồi chuyển bán tự động.

Đồng hồ theo dõi: vé đã reserve chưa pay có expired_time → nhắc điều hành trước 30 phút và 10 phút; đến hạn mà chưa quyết → tự chuyển TU_CHOI với lý do "hết hạn giữ chỗ" và báo đại lý. Vé đẩy lên sau mốc tắt bán của chuyến → vào hàng đợi thủ công ngay, không gọi API.

3.5 Luồng 4 — Xuất vé và gửi đa kênh

Nội dung vé (một nguồn dữ liệu, nhiều khuôn hiển thị): tên nhà xe, mã vé nội bộ + mã VeXeRe (ticket code, partner_code nếu có), tên khách, số khách, tuyến, ngày giờ khởi hành, giờ đón dự kiến + điểm đón + địa chỉ, số ghế (hoặc "nhà xe xếp chỗ khi lên xe"), biển số + SĐT xe (nếu VeXeRe trả), giá vé + đã thu/chưa thu, chính sách huỷ tóm tắt, số hotline, liên kết tra cứu ngắn.

Khuôn theo kênh:

Chính sách gửi: mỗi đại lý có thứ tự kênh mặc định (ví dụ Zalo cá nhân → SMS; hoặc SMS + Email). Bộ gửi chạy hàng đợi: thử kênh 1; nếu kênh 1 không thể gửi (không tìm thấy Zalo, email sai) thì tự chuyển kênh dự phòng; nếu kênh 1 đã gửi thì các kênh đánh dấu "song song" vẫn gửi. Giới hạn nhịp riêng từng kênh (mục 4.3). Mọi lần gửi lưu nội dung đã gửi để tra lại đúng chữ khách nhận.

Gửi lại: khi vé đổi (giờ, ghế, xe) → tự dựng bản "VÉ CẬP NHẬT" và gửi lại theo cùng kênh đã thành công trước đó; khi huỷ → "VÉ ĐÃ HUỶ" kèm phí/hoàn.

3.6 Luồng 5 — Sửa, huỷ, đổi chuyến

Điều hành có thể uỷ quyền cho một đại lý tin cậy tự duyệt yêu cầu của mình (cờ tu_duyet trên đại lý).

3.7 Luồng 6 — Đồng bộ ngược từ VeXeRe

• Webhook: nhận ticket_updated (nhà xe đổi giờ/giờ đón) → cập nhật vé, gửi "VÉ CẬP NHẬT"; ticket_cancelled → HUY, ghi cancel_fee/refund_amount, báo đại lý + khách; ticket_official_fare_updated (vé cọc) → đánh dấu chờ thu thêm/hoàn với hạn surcharge_time_deadline, báo đại lý. Xác thực x-signature, lưu sự kiện thô, idempotent theo (event_type, booking_code, event_timestamp), trả 200 {"code":"00"} ngay rồi xử lý nền.
• Quét định kỳ (dự phòng webhook lỗi): mỗi 15 phút với vé có ngày đi ≤ 2 ngày tới gọi GET /v3/booking?code=&checking_status_only=1; mỗi giờ với vé xa hơn. Khác trạng thái → xử lý như webhook.
• Làm giàu trước giờ chạy: 3 giờ trước khởi hành gọi GET /v3/booking lấy biển số/tài xế/SĐT xe; nếu mới có thì gửi khách tin "XE CỦA BẠN" (tuỳ chọn cấu hình).

3.8 Luồng 7 — Thống kê và đối soát theo đại lý

Số liệu trên mỗi vé (đóng băng khi chốt kỳ):

• gia_ban: giá đại lý bán cho khách (đại lý nhập).
• gia_ncc: giá nhà cung cấp chỗ ghi nhận (với VeXeRe là amount_booking, giá bán lẻ VeXeRe).
• gia_dai_ly (bảng mô-đun vexere): giá dành cho đại lý (sau chiết khấu) — lấy từ AMS/GET booking nếu API trả; nếu không thì tính theo % chiết khấu cấu hình.
• hoa_hong: hoa hồng nhà xe trả đại lý (theo % hoặc số cố định, cấu hình theo đại lý × tuyến × loại chỗ).
• phi_huy, hoan_tien khi huỷ.
• hinh_thuc_thu: đã thu tại đại lý / thu tại xe / chuyển khoản nhà xe.

Công thức mặc định (điều chỉnh được ở cấu hình): phai_nop = Σ(gia_ban − hoa_hong) cho vé đã thu tại đại lý và không huỷ; vé huỷ có phí thì phai_nop += phi_huy_dai_ly_chiu. Vé thu tại xe không tính vào phải nộp nhưng vẫn tính hoa hồng.

Kỳ đối soát: tuần hoặc tháng theo đại lý. Quy trình: quản trị tạo kỳ → hệ thống liệt kê vé theo ngày đi trong kỳ, ba cột đối chiếu (hệ thống, VeXeRe qua GET booking/nhập file Báo cáo chi tiết vé xuất từ AMS, đại lý xác nhận) → dòng lệch được tô và có ô ghi chú xử lý → chốt kỳ (khoá mọi vé trong kỳ) → xuất biên bản Excel (tổng hợp + chi tiết) → đại lý bấm Xác nhận trên cổng (ghi thời điểm, người). Mở lại kỳ chỉ quản trị làm, có lý do, ghi vết.

Bảng thống kê (đại lý thấy của mình, quản trị thấy tất cả, lọc ngày/tuần/tháng/khoảng): số vé, số ghế, doanh thu, hoa hồng, tỉ lệ huỷ, phí huỷ; theo tuyến, theo giờ, theo loại chỗ; tỉ lệ gửi thành công theo kênh và thời gian trung bình từ đẩy lên → đã gửi; xếp hạng đại lý; tồn đọng (vé DA_DAY quá 15 phút, vé giữ chỗ sắp hết hạn, tin gửi lỗi).

4. Kiến trúc hệ thống

4.1 Tổng thể

flowchart LR
    subgraph NguoiDung[Người dùng]
        DL[Đại lý
web mobile-first / PWA]
        DH[Điều hành
bàn xếp vé]
        QT[Quản trị]
        KH[Khách
trang tra cứu]
    end
    subgraph VPS[VPS Ubuntu + aaPanel]
        CADDY[nginx của aaPanel
HTTPS, reverse proxy từ Node project]
        API[api — NestJS
REST + SSE, RBAC, audit]
        WK[worker — NestJS
xếp vé, gửi tin, đồng bộ, đồng hồ hết hạn]
        WZ[worker-zalo
zca-js, phiên Zalo cá nhân]
        PG[(PostgreSQL 16)]
        RD[(Redis 7
BullMQ, phiên, cache token)]
        SMSG[sms-gateway server
tự host]
    end
    subgraph Kenh[Kênh gửi]
        SIM[Máy Android + SIM
app SMS Gateway]
        MAIL[SMTP]
        OA[Zalo OA / ZNS]
    end
    subgraph Ngoai[Ngoài]
        VX[VeXeRe API]
        NG[Nguồn tuỳ chọn:
Vé247 / OSZalo / web]
    end
    DL & DH & QT & KH --> CADDY --> API
    NG -->|API khoá riêng| CADDY
    VX -->|webhook HMAC| CADDY
    API <--> PG
    API <--> RD
    WK <--> PG
    WK <--> RD
    WZ <--> RD
    WK <--> VX
    WK --> SMSG --> SIM
    SIM -->|đã gửi / đã nhận / lỗi| SMSG
    WK --> MAIL & OA

Nguyên tắc: một kho mã (monorepo), ba tiến trình Node (api, worker, worker-zalo) dùng chung PostgreSQL và Redis; giao diện là SPA tĩnh do Caddy phục vụ; mọi việc nền (xếp vé, gửi tin, quét trạng thái, nhắc hết hạn) là job BullMQ có thử lại và có giới hạn nhịp theo hàng đợi. Tách worker-zalo để phiên Zalo cá nhân đứt không kéo API đứt. Mã viết bằng TypeScript; tên miền nghiệp vụ tiếng Việt không dấu (ve, daiLy, guiTin) để khớp tài liệu này. Quy mô vài trăm vé/ngày chạy thoải mái trên một VPS nhỏ; tách dịch vụ sau nếu lớn. Bên trong, mã tổ chức theo lõi quản lý vé + mô-đun cắm/rút (mục 4.9): api và worker chỉ là hai "vỏ" nạp lõi cùng các mô-đun đang bật.

4.2 Mô-đun

4.3 Thiết kế từng kênh gửi

Thiết kế kênh SMS (chi tiết): dùng ứng dụng SMS Gateway for Android (mã nguồn mở) trên một máy Android + SIM đặt cố định, cùng máy chủ gateway tự host trong Docker Compose (ứng dụng có chế độ máy chủ riêng); worker gọi REST gửi tin kèm mã tham chiếu, nhận webhook đã gửi/đã nhận/lỗi để cập nhật gui_tin; nhịp gửi do BullMQ giới hạn (mặc định 1 tin/5 giây, trần ngày cấu hình); tạm dừng hàng đợi khi 5 lỗi liên tiếp và báo quản trị; hỗ trợ nhiều máy SIM (mỗi máy một tài khoản gateway, cổng chia đều). Nếu ứng dụng gateway không đáp ứng, viết app Kotlin riêng theo cùng giao thức (kinh nghiệm từ app Vé247). Cần kiểm tra lại phiên bản ứng dụng gateway hiện hành trước khi chốt.

4.4 Bộ kết nối VeXeRe — quy ước

• Token cache 55 phút, làm mới sớm; nhận 401 thì làm mới một lần rồi thử lại.
• Mọi lệnh ghi (reserve, pay, refund, agent_api) là một giao dịch nội bộ có transaction_id = mã vé nội bộ + hậu tố hành động, để đối soát với vxr_transaction_id.
• Không bao giờ gọi pay mà chưa lưu booking_code; không gọi refund mà chưa lưu kết quả GET refund để hiện phí.
• Ghi đầy đủ yêu cầu/đáp (che SĐT một phần) vào mod_vexere_nhat_ky với thời gian phản hồi để theo dõi.
• Bảng ánh xạ mod_vexere_anh_xa: tuyến nội bộ → from_id/to_id (area), company_id nhà xe, danh sách giờ, dung sai khớp giờ (mặc định ±10 phút), danh sách điểm đón/trả nội bộ ↔ pickup_id/drop_off_point_id (đồng bộ từ seat_map, quản trị chỉnh tay).
• Kiểm thử: chạy trên UAT với client_id/secret thử nghiệm trong tài liệu; bộ ca kiểm thử theo mục Testcases của tài liệu; sang PRO khi có tài khoản thật.

4.5 Webhook nhận từ VeXeRe

POST /api/vexere/webhook → đọc thô body → dựng chuỗi theo thứ tự trường trong tài liệu → HMAC-SHA256(client_secret) → so với x-signature (so sánh thời gian hằng) → sai thì 401 và ghi nhật ký → đúng thì lưu mod_vexere_su_kien (chống trùng) → trả ngay 200 {"code":"00","message":"Webhook received"} → xử lý nền. URL webhook đăng ký với VeXeRe qua đầu mối kỹ thuật (tài liệu không có API tự đăng ký).

4.6 API liên thông cho nguồn tuỳ chọn (Vé247, OSZalo, web)

Tích hợp tuỳ chọn, bật khi cần; cổng không phụ thuộc các hệ thống này.

• POST /api/nguon/ve (khoá theo nguồn): nhận vé theo lược đồ tương thích tao-ve của Vé247 (maNguon, soDienThoai, soKhach, loaiGhe, tuyenTu, tuyenDen, ngayDi, gio, diemDon, diemTra, yeuCauKhac, nguon) → trả veId, maVe. Idempotent theo nguon + maNguon.
• POST /api/nguon/ve/{id}/huy, PUT /api/nguon/ve/{id}: như đại lý.
• Webhook ra POST {url nguồn} khi vé đổi trạng thái, để hệ thống nguồn cập nhật phía mình.

4.7 Công nghệ đề xuất

Tiêu chí chọn: một người bảo trì được; chạy trên một VPS Linux bằng Docker; kênh Zalo cá nhân chỉ có thư viện Node (zca-js) nên một ngôn ngữ cho toàn bộ tiết kiệm nhất; có sẵn hàng đợi có nhịp, lịch, RBAC, audit; phục vụ nhiều đại lý ghi đồng thời và đối soát bằng SQL.

Phương án đã cân nhắc và lý do không chọn:

• Node + Fastify + SQLite một tiến trình (khuôn Vé247): triển khai đơn giản nhất, nhưng yếu khi nhiều đại lý ghi đồng thời, không có hàng đợi có nhịp, khó tách worker Zalo. Vẫn là phương án dự phòng nếu muốn tối giản (mục 11, câu 12).
• Python Django: quản trị và ORM sẵn, nhưng Zalo cá nhân vẫn cần tiến trình Node; hai ngôn ngữ cho một người bảo trì.
• PHP Laravel (+ Filament): nhanh cho back-office, cùng vấn đề hai ngôn ngữ.
• Go: nhị phân gọn, nhưng làm giao diện/tích hợp chậm hơn, không có thư viện Zalo.

Cấu hình VPS tối thiểu: 2 vCPU, 4 GB RAM, 40 GB SSD, Ubuntu 24.04. Ước dùng: PostgreSQL ~300 MB, Redis ~50 MB, ba tiến trình Node ~450 MB, Caddy ~30 MB.

4.8 Cấu trúc mã nguồn (monorepo, pnpm workspaces)

cong-gui-ve/
  apps/
    api/              NestJS: nạp lõi + các mô-đun đang bật; REST + SSE
    worker/           NestJS không HTTP: chạy job BullMQ của lõi và mô-đun, cron
    worker-zalo/      tiến trình riêng của mô-đun zalo-ca-nhan (zca-js)
    web/              React + Vite + AntD: vỏ giao diện lõi + màn hình do mô-đun đóng góp
  packages/
    core/             thực thể, máy trạng thái, bus sự kiện, quyền, vết, cấu hình, registry mô-đun
    core-contracts/   interface điểm mở rộng, kiểu sự kiện, phiên bản hợp đồng (semver)
    modules/
      vexere/  sms-gateway/  email/  zalo-oa/  zalo-ca-nhan/  xuat-ve/
      day-danh-sach/  api-nguon/  thong-ke/  doi-soat/
        (mỗi mô-đun: manifest.ts, src/, prisma/ (bảng mod_*), test/,
         README.md, HUONG-DAN-SU-DUNG.md, CHANGELOG.md)
    shared/           zod schema, chuẩn hoá SĐT/giờ/ngày, tiện ích dùng chung
    db/               gom lược đồ lõi + mô-đun, di trú, Prisma client
    vexere-client/    bọc API VeXeRe (dùng bởi mô-đun vexere), có mock
  deploy/             khoi-dong.cjs, cap-nhat.sh, nginx-them.conf (GĐ0); sao-luu.sh, khoi-phuc.sh,
                      kiem-tra-khoi-phuc.sh, .env.example, HUONG-DAN-AAPANEL.md (đã có)
  scripts/            phien-ban.py, dong-bo-git.ps1 / .sh, kiem-tra-tai-lieu.py (đã có)
  .githooks/          pre-commit kiểm tra tài liệu;  .github/workflows/ CI kiểm tra tài liệu
  package.json        nguồn phiên bản toàn hệ thống (semver)
  docs/
    thiet-ke/         tài liệu này, 01-phan-tich-cong-nghe-nen-tang.md + mỗi mô-đun một tệp + ADR
    huong-dan/        theo vai trò: dai-ly.md, dieu-hanh.md, quan-tri.md (+ ảnh chụp)
    ban-giao/         HANDOVER-LOG.md
    kinh-nghiem/      LESSONS.md
    tham-khao/        bản trích tài liệu VeXeRe/AMS
    CHANGELOG.md
  CLAUDE.md           chỉ dẫn cho AI: đọc tài liệu nào đầu phiên, cập nhật tài liệu nào khi đổi mã

Khung docs/, CLAUDE.md đã tạo sẵn trong repo này; tài liệu thiết kế hiện nằm ở docs/00-…md và sẽ chuyển vào docs/thiet-ke/ khi khởi tạo monorepo.

4.9 Lõi quản lý vé và mô-đun cắm/rút

Ý tưởng: lõi là "hệ điều hành vé", mô-đun là "ứng dụng" cài lên. Lõi không biết VeXeRe, không biết SMS; nó chỉ biết vé, trạng thái, sự kiện, quyền, vết. Một mô-đun nâng cấp, thêm hay gỡ không làm lõi và mô-đun khác phải đổi mã.

flowchart TB
    subgraph LOI[Lõi quản lý vé — packages/core]
        TT[Thực thể & máy trạng thái vé]
        SK[Bus sự kiện ve.*]
        QQ[Quyền · phiên · vết · cấu hình]
        RG[Registry mô-đun
manifest · phiên bản · bật/tắt · cô lập lỗi]
        HD[Hợp đồng — core-contracts
NhaCungCapCho · KenhGui · NguonVe · KhuonVe · BaoCao · TrangQuanTri]
    end
    subgraph MOD[Mô-đun cắm/rút — packages/modules/*]
        M1[vexere
NhaCungCapCho · BaoCao · webhook]
        M2[sms-gateway · email · zalo-oa · zalo-ca-nhan
KenhGui]
        M3[day-danh-sach · api-nguon
NguonVe]
        M4[xuat-ve
KhuonVe]
        M5[thong-ke · doi-soat
BaoCao]
    end
    M1 & M2 & M3 & M4 & M5 -. thực thi hợp đồng .-> HD
    HD --> RG
    SK -- phát sự kiện --> M1 & M2 & M4 & M5
    M3 -- lệnh tạo/sửa vé --> TT
    M1 -- kết quả xếp chỗ --> TT
    M2 -- kết quả gửi --> TT

Lõi (packages/core) gồm:

• Thực thể chuẩn: ve, dai_ly, nguoi_dung, tuyen, diem_don_tra, ve_lich_su, yeu_cau_thay_doi, gui_tin, su_kien, mo_dun, cai_dat (mục 5).
• Máy trạng thái vé (mục 3.1) và các lệnh chuyển trạng thái có kiểm tra quyền: taoVe, dayVe, xepVe, tuChoi, xuatVe, ghiKetQuaGui, huyVe, suaVe, khoaVe, moKhoaVe.
• Bus sự kiện: ve.tao, ve.day, ve.xep, ve.tu_choi, ve.xuat, ve.gui, ve.sua, ve.huy, ve.het_han, ve.khoa; trong tiến trình qua event-emitter, liên tiến trình qua BullMQ; mọi sự kiện lưu bảng su_kien để phát lại cho mô-đun bật muộn hoặc xử lý lỗi.
• Nhà cung cấp chỗ mặc định thu-cong (điều hành nhập ghế/mã tay) nằm trong lõi, nên lõi tự chạy được khi không có mô-đun nào.
• Registry mô-đun: đọc manifest (tên, phiên bản, yeuCauLoi: ">=1.2 <2", điểm mở rộng cung cấp, quyền cần, bảng sở hữu, di trú, trang cấu hình), bật/tắt theo bảng mo_dun, kiểm tra tương thích khi khởi động, cô lập lỗi (mô-đun ném lỗi → ghi nhật ký, đánh dấu lỗi, lõi và mô-đun khác chạy tiếp).
• Dịch vụ chung mô-đun gọi qua interface: quyền, phiên, vết, cấu hình (có mã hoá bí mật), nhật ký, hàng đợi, SSE.

Sáu điểm mở rộng (interface TypeScript trong packages/core-contracts):

Quy tắc ràng buộc (kiểm tra bằng lint và CI):

1. Mô-đun chỉ phụ thuộc core-contracts và shared; không import mô-đun khác; mô-đun nói chuyện với nhau qua sự kiện lõi.
2. Mô-đun sở hữu bảng riêng tiền tố mod_<ten>_, chỉ tham chiếu lõi qua ve_id/dai_ly_id/tuyen_id; không thêm cột vào bảng lõi; cần lưu thêm thì dùng thuoc_tinh_mo_rong (JSONB, khoá theo tên mô-đun).
3. Phiên bản: lõi và từng mô-đun đánh semver riêng; lõi giữ tương thích ngược trong cùng phiên bản lớn; đổi hợp đồng = tăng phiên bản lớn kèm bảng chuyển đổi; mô-đun khai báo dải phiên bản lõi hỗ trợ; registry từ chối nạp mô-đun không tương thích và nêu rõ lý do.
4. Di trú CSDL của mô-đun nằm trong thư mục mô-đun, chạy theo thứ tự lõi → mô-đun; tắt mô-đun không xoá dữ liệu; xoá dữ liệu là thao tác riêng có xác nhận.
5. Kiểm thử hợp đồng: mỗi điểm mở rộng có bộ test chuẩn (ví dụ KenhGui: gửi thành công, thất bại, webhook trùng, quá nhịp); mô-đun mới phải qua bộ test đó trước khi được nạp.
6. Bật/tắt không cần dựng lại; giao diện tự ẩn/hiện menu, trang cấu hình, cột báo cáo theo mô-đun đang bật.
7. Mọi gọi từ lõi sang mô-đun có thời gian chờ và bắt lỗi; mô-đun chậm/hỏng không chặn máy trạng thái.

Ví dụ vận hành: nhà xe muốn thử kênh Telegram → viết mô-đun telegram thực thi KenhGui, chạy bộ test hợp đồng, bật trong quản trị; lõi, VeXeRe, SMS không đổi một dòng. Nâng lõi 1.x → 2.0 vì đổi hợp đồng NhaCungCapCho → chỉ mô-đun vexere phải cập nhật; các kênh gửi vẫn chạy.

4.10 Tài liệu đồng bộ với mã

Nguyên tắc: một thay đổi chưa xong nếu tài liệu chưa đổi theo. Bốn bộ tài liệu sống trong kho mã, cùng nhánh, cùng lần cập nhật với mã:

Cơ chế bảo đảm đồng bộ toàn hệ thống:

1. Định nghĩa hoàn thành cho mọi thay đổi: mã + test + di trú + cập nhật đúng bộ tài liệu bị ảnh hưởng + một dòng CHANGELOG.md (theo Keep a Changelog, ghi phiên bản lõi/mô-đun).
2. CI chặn: kịch bản kiểm tra khi thay đổi đụng packages/core, packages/modules/<x> hoặc apps/web mà không đụng docs/ hay README/HUONG-DAN-SU-DUNG của mô-đun tương ứng thì thất bại, trừ khi gắn nhãn khong-doi-tai-lieu kèm lý do. Mẫu PR có ô kiểm bốn bộ tài liệu.
3. Sinh tự động những gì sinh được, không viết tay hai lần: OpenAPI từ NestJS Swagger → docs/thiet-ke/api.md; ERD từ lược đồ Prisma; bảng mô-đun và phiên bản từ manifest; sơ đồ trạng thái từ hằng số máy trạng thái; ma trận quyền từ định nghĩa CASL. Chạy trong CI, tệp sinh ra commit kèm.
4. Phiên bản tài liệu = phiên bản phần mềm: đầu mỗi tài liệu ghi "áp dụng cho lõi x.y / mô-đun z"; trang Giới thiệu trong app hiện phiên bản và liên kết đúng bản hướng dẫn; nâng lõi lên phiên bản lớn mới thì CI bắt mọi mô-đun cập nhật dòng tương thích trong README.
5. Đồng bộ với bộ nhớ AI: CLAUDE.md trong kho chỉ dẫn đầu phiên đọc HANDOVER-LOG.md + LESSONS.md, cuối phiên cập nhật; khớp thói quen bàn giao đang dùng ở các dự án khác.
6. Rà soát định kỳ: mỗi lần phát hành chạy danh mục "tài liệu nào nhắc đến màn hình/API/bảng vừa đổi" (tìm theo tên) và duyệt; hằng quý đọc lại hướng dẫn cùng một đại lý thật.

5. Thiết kế dữ liệu

Dữ liệu chia hai lớp theo mục 4.9: bảng lõi (mô-đun chỉ đọc/ghi qua dịch vụ lõi) và bảng mô-đun (tiền tố mod_<ten>_, mô-đun toàn quyền, tham chiếu lõi qua ve_id/dai_ly_id/tuyen_id).

erDiagram
    DAI_LY ||--o{ NGUOI_DUNG : "có"
    DAI_LY ||--o{ VE : "sở hữu"
    TUYEN ||--o{ VE : "thuộc"
    TUYEN ||--o{ DIEM_DON_TRA : "có"
    VE ||--o{ VE_LICH_SU : "vết"
    VE ||--o{ YEU_CAU_THAY_DOI : "yêu cầu"
    VE ||--o{ GUI_TIN : "gửi"
    VE ||--o{ SU_KIEN : "phát"
    VE ||--o| MOD_VEXERE_DAT_CHO : "mô-đun vexere"
    VE ||--o{ MOD_VEXERE_GIAO_DICH : "mô-đun vexere"
    MOD_DAY_DANH_SACH_LO ||--o{ VE : "mô-đun đẩy danh sách"
    MOD_DOI_SOAT_KY ||--o{ MOD_DOI_SOAT_CT : "gồm"
    MOD_DOI_SOAT_CT }o--|| VE : "ghi nhận"

Bảng lõi

Bảng mô-đun

Chỉ mục: ve(dai_ly_id, trang_thai), ve(ngay_di, gio_di), ve(sdt), ve(nguon, ma_nguon) UNIQUE, gui_tin(trang_thai, kenh), mod_vexere_dat_cho(booking_code), mod_vexere_su_kien(booking_code).

6. Giao diện

Đại lý (điện thoại là chính): Vé mới (form một cột, chọn nhanh tuyến/giờ đã dùng gần đây), Đẩy danh sách (tải tệp/dán, bảng xem trước sửa tại chỗ), Vé của tôi (thẻ vé, màu theo trạng thái, lọc ngày đi, tìm SĐT, nút Sửa/Huỷ/Gửi lại tuỳ trạng thái), Thống kê của tôi, Đối soát (kỳ, biên bản, nút Xác nhận).

Điều hành (máy tính): Bàn xếp vé hai cột — trái là hàng đợi DA_DAY nhóm theo chuyến (ngày/giờ/tuyến), phải là chi tiết vé + sơ đồ ghế VeXeRe + nút Xác nhận/Đổi ghế/Từ chối/Xếp tay; Yêu cầu chờ duyệt; Tin gửi lỗi; Sắp hết hạn giữ chỗ (đếm ngược); Tra cứu mọi vé.

Quản trị: Tuyến & điểm (đồng bộ id VeXeRe), Đại lý & hoa hồng, Kênh gửi (trạng thái SIM, OSZalo, OA, SMTP; bộ đếm ngày), Khuôn tin (xem trước theo kênh), Người dùng & quyền, Nhật ký.

Khách: trang /v/{mã ngắn} hiện vé (không cần đăng nhập, mã ngắn khó đoán 8 ký tự), cập nhật theo trạng thái mới nhất, nút "Gọi nhà xe".

Điểm UX quan trọng: trạng thái đổi tức thời (SSE); thao tác trên điện thoại một tay; chữ to, nút to; màu trạng thái thống nhất toàn hệ thống.

7. Phân quyền và an toàn

An toàn:

• Mật khẩu băm (scrypt/argon2), phiên cookie HttpOnly, khoá API đại lý băm; giới hạn lần đăng nhập sai.
• Bí mật (client_secret VeXeRe, SMTP, OA token, khoá OSZalo, khoá SIM) trong .env, không commit; giá trị trong kenh_cau_hinh mã hoá bằng khoá máy chủ.
• Mọi hành động ghi vào ve_lich_su/nhật ký; xoá là xoá mềm.
• Dữ liệu cá nhân (SĐT, tên, email) theo Nghị định 13/2023/NĐ-CP: chỉ dùng cho việc đi xe; tự ẩn SĐT trong thống kê tổng hợp; lịch xoá/ẩn danh vé sau N tháng (mặc định 24) cấu hình được; thông báo xử lý dữ liệu trên trang tra cứu.
• Webhook: chữ ký HMAC, chống phát lại theo event_timestamp, giới hạn tốc độ theo IP.
• HTTPS bắt buộc (aaPanel + Let's Encrypt), CSDL sao lưu hằng ngày ra thư mục ngoài web root như Vé247, giữ 30 bản.

8. Vận hành

• Triển khai: VPS Ubuntu + aaPanel. Ba Node project (cgv-api gắn domain đề xuất ve.xekhachhagiang.vn với Mapping + SSL, cgv-worker, cgv-zalo), Node 22 / PostgreSQL / Redis / Google Drive cài từ App Store. Cập nhật: git pull + Restart trong panel (tệp khởi động tự cài phụ thuộc, di trú, dựng web) hoặc nút Cập nhật trong app. Tệp .env chỉ có trên VPS. Chi tiết: tài liệu 01 mục 5, deploy/HUONG-DAN-AAPANEL.md.
• Giám sát: /health (CSDL, Redis, token VeXeRe, hàng đợi, worker-zalo, SMS gateway lần liên hệ cuối, webhook nhận cuối, sao lưu cuối); aaPanel Monitor + Cron Access URL; bot Zalo/Telegram báo sự cố; Bull Board xem hàng đợi (chỉ quản trị). Cảnh báo khi: máy SIM im > 10 phút, tin lỗi > 5 liên tiếp, vé giữ chỗ sắp hết hạn, VeXeRe lỗi 5xx liên tục, pay lỗi (nghi hạn mức thấp), phiên Zalo đứt, sao lưu lỗi.
• Hạn mức VeXeRe: không có API tra, nên hệ thống tự ước tính (nạp − đã thanh toán + đã hoàn) và quản trị nhập lại số thực từ AMS khi lệch.
• Sao lưu/khôi phục: Cron aaPanel — Shell deploy/sao-luu.sh (02:00, pg_dump + gói cấu hình mã hoá) → Backup Directory lên Google Drive giữ 30 bản (02:40) → deploy/kiem-tra-khoi-phuc.sh hằng tuần; Redis không cần sao lưu; khôi phục bằng deploy/khoi-phuc.sh.
• Nhật ký: pino JSON ra log Node project, Cron Cut Log giữ 30 tệp; che SĐT một phần.
• Bảo mật máy chủ: chỉ mở 22 (khoá SSH, tắt mật khẩu), 80, 443; UFW + fail2ban; PostgreSQL/Redis chỉ trong mạng nội bộ Docker; cập nhật bảo mật hệ điều hành tự động.

9. Lộ trình và ước lượng

Ước lượng tính theo một người làm chính với Claude Code, thử nghiệm thật với 1–2 đại lý ngay cuối GĐ1.

10. Rủi ro và giảm thiểu

11. Câu hỏi cần chốt trước khi lập trình

1. Tài khoản VeXeRe: nhà xe đã có (hoặc xin được) client_id/secret API đối tác chưa? Chiết khấu và hạn mức thế nào? Hay mỗi đại lý dùng tài khoản AMS riêng (khi đó hệ thống chỉ xếp thủ công và ghi nhận)?
2. company_id của nhà xe trên VeXeRe và danh sách tuyến/giờ chính thức để dựng bảng ánh xạ.
3. Thanh toán: đại lý thu tiền rồi hệ thống pay ngay (trừ hạn mức), hay chỉ giữ chỗ và thu tại xe? Ai chịu phí huỷ theo giá đại lý?
4. Gửi SMS: mua một máy Android + SIM riêng đặt cố định (đề xuất) chạy ứng dụng SMS Gateway mã nguồn mở, hay tự viết app? Dự kiến bao nhiêu tin/ngày, mấy SIM?
5. Zalo OA đã có và đã xác thực chưa? Có ngân sách ZNS không, hay để giai đoạn sau?
6. Có để VeXeRe tự nhắn SMS/email cho khách song song không? Nếu không, customer_email gửi lên VeXeRe dùng hộp thư của nhà xe.
7. VPS — đã chốt 02/9/2026: VPS mới riêng, Ubuntu + aaPanel. Còn lại: nhà cung cấp, cấu hình (đề xuất 2 vCPU / 4 GB / 40 GB SSD, Ubuntu 24.04), tên miền (đề xuất ve.xekhachhagiang.vn), ai giữ quyền root?
8. Hoa hồng đại lý: % hay số cố định, theo tuyến/loại chỗ? Kỳ đối soát tuần hay tháng?
9. Nguồn tuỳ chọn: có cần Vé247/OSZalo/web đẩy vé vào cổng ngay GĐ1 không, hay để sau khi cổng ổn định?
10. Đại lý được xoá vé tới trạng thái nào: chỉ trước khi xếp (đề xuất) hay cả sau khi xếp nếu chưa gửi khách?
11. Có cần vé khứ hồi và vé cọc Lễ/Tết ở phiên bản 1 không?
12. Bộ công nghệ: chốt theo mục 4.7 (NestJS + PostgreSQL + Redis/BullMQ + React/Vite + Docker Compose) hay muốn tối giản hơn (Fastify + SQLite một tiến trình, chấp nhận hạn chế đã nêu)?
13. Mức "cắm/rút" mong muốn: mô-đun nằm trong cùng kho mã, bật/tắt bằng cấu hình không cần dựng lại (đề xuất, mục 4.9) hay cần cài/gỡ gói mô-đun lúc chạy như plugin thật (phức tạp và rủi ro hơn nhiều)?

Đã chốt ngày 02/9/2026 (trả lời trực tiếp): VPS mới riêng Ubuntu + aaPanel (câu 7); ứng dụng đại lý bản 1 là PWA cài từ trình duyệt; đồng bộ git: Claude tự chạy scripts/dong-bo-git.ps1 cuối mỗi lượt làm việc; AI bản 1: đọc danh sách vé từ văn bản dán và ảnh chụp (tài liệu 01, mục 6). Các câu còn lại vẫn mở.

Phụ lục A — Ánh xạ trạng thái VeXeRe ↔ hệ thống

Phụ lục B — Khuôn tin mẫu

SMS (không dấu, ≤ 160 ký tự) XKH: Ve 17h30 02/9 Ha Giang-Ha Noi, 2 giuong A5 A6, don BX Ha Giang 17h15. Ma ve NO97T9. Xe 24B-123.45 0912xxxxxx. Xem: xkh.vn/v/AB12CD34

Zalo cá nhân / OA (có dấu, kèm ảnh vé)

🎫 VÉ XE KHÁCH HÀ GIANG
Khách: Nguyễn Văn A (0912…)
Chuyến: 17h30 Thứ Tư 02/9/2026 · Hà Giang → Hà Nội
Chỗ: 2 giường A5, A6 (tầng dưới)
Đón: 17h15 tại Bến xe Hà Giang
Xe: 24B-123.45 · 0912 xxx xxx
Mã vé: NO97T9 · Đã thanh toán 400.000đ
Huỷ trước 12 giờ không mất phí. Tra cứu: xkh.vn/v/AB12CD34

Email: tiêu đề Vé xe 17h30 02/9 Hà Giang → Hà Nội — mã NO97T9; thân HTML bảng như trên, mã QR nội bộ, nút "Xem vé".

Phụ lục C — Mẫu cột tệp đẩy danh sách