Cổng gửi vé VeXeRe

0. Kết luận nhanh

Ghi chú về "gs" trong yêu cầu: hiểu là Go. Nếu ý là Google Apps Script thì không phù hợp: không chạy trên VPS riêng, không giữ tiến trình dài (Zalo, hàng đợi), giới hạn thời gian chạy và số lần gọi.

1. Ràng buộc từ hạ tầng thật và tải dự kiến

1.1 VPS Ubuntu + aaPanel

aaPanel cung cấp sẵn: nginx (site, reverse proxy, SSL Let's Encrypt tự gia hạn), tường lửa, cron, giám sát cơ bản, và qua App Store: PM2 Manager, Node.js version manager, Python manager, Docker manager, Redis, Supervisor. Kinh nghiệm từ Vé247 trên cùng loại VPS: aaPanel chỉ nên làm nginx + SSL, còn Node chạy bằng PM2 do script cài, không để aaPanel quản phiên bản Node (tránh lệch bản khi aaPanel cập nhật).

Hệ quả cho thiết kế:

• Mọi tiến trình ứng dụng lắng nghe 127.0.0.1 ở cổng nội bộ; chỉ nginx của aaPanel ra Internet.
• PostgreSQL 16 và Redis 7 cài từ apt của Ubuntu 24.04 (không phụ thuộc plugin), chỉ nghe localhost/socket.
• Cập nhật bằng git pull + di trú + pm2 reload như Vé247, có nút Cập nhật trên trang quản trị.

1.2 Tải dự kiến (giả định, cần xác nhận)

Kết luận: hệ thống I/O-bound, chờ dịch vụ ngoài là chính. Ngôn ngữ nhanh hơn 3 lần về CPU không đổi trải nghiệm; kiến trúc bất đồng bộ, hàng đợi, cách ly lỗi mới quyết định tốc độ và độ bền.

2. So sánh ngôn ngữ theo từng chức năng của hệ thống

Thang 1–5 (5 tốt nhất). Trọng số theo mức ảnh hưởng đến dự án này.

2.1 Vì sao không chọn "lai" (Go hoặc PHP lõi + Node cho Zalo)

Kênh Zalo cá nhân bản web bắt buộc một tiến trình Node. Nếu lõi viết bằng Go/PHP/Python thì hệ thống có hai ngôn ngữ, hai bộ công cụ, hai cách gỡ lỗi cho một người bảo trì; mọi lợi ích hiệu năng của Go không đổi được trải nghiệm vì nút thắt nằm ở SIM, Zalo và API VeXeRe (mục 1.2). Node đủ nhanh: một tiến trình Fastify trên 1 vCPU phục vụ hàng nghìn yêu cầu/giây với route đơn giản, gấp nhiều chục lần nhu cầu.

2.2 Khi nào cân nhắc lại

• Tải vượt ~50.000 vé/ngày hoặc cần xử lý ảnh/AI tại chỗ nặng → tách dịch vụ đó sang Go/Python, giao tiếp qua Redis/HTTP; lõi + mô-đun không đổi nhờ hợp đồng (tài liệu 00, mục 4.9).
• Zalo đổi cơ chế khiến zca-js chết hẳn → mô-đun zalo-ca-nhan thay bằng Zalo OA/ZNS hoặc điều khiển trình duyệt (Playwright), vẫn là mô-đun KenhGui.

2.3 Zalo cá nhân bản web: hiểu đúng rủi ro

• zca-js mô phỏng Zalo Web: đăng nhập bằng QR (hoặc cookie + IMEI + user-agent đã lưu), nhận sự kiện qua websocket, gửi tin/ảnh, tìm người theo số điện thoại. Không phải API chính thức; Zalo có thể đổi giao thức hoặc khoá tài khoản gửi hàng loạt.
• Thiết kế giảm rủi ro: tài khoản Zalo riêng cho nhà xe (không dùng số cá nhân chủ), gửi tin chỉ tới khách đã nhắn/kết bạn, nhịp gửi tự đặt (20/phút, 150/giờ, 600/ngày; chưa có con số chính thức), nội dung cá nhân hoá (mã vé, tên), không gửi liên kết lạ, giữ phiên (persist session) để không phải quét QR lại, giám sát "sống/chết" và đăng nhập lại bằng QR trên trang quản trị, luôn có SMS dự phòng.
• Khi khách chưa từng nhắn: tin rơi vào "Tin nhắn chờ" → coi là đã gửi nhưng chưa chắc đọc; nếu 10 phút không thấy đã xem thì gửi SMS.

3. Hiệu năng và tốc độ

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

3.2 Kỹ thuật tối ưu từng lớp

• Máy chủ: NestJS trên Fastify; pool kết nối Prisma (10–20); chỉ mục CSDL theo tài liệu 00 mục 5; phân trang con trỏ; tránh N+1 (Prisma include có chọn lọc); nén brotli/gzip và HTTP/2 tại nginx; cache Redis cho danh mục (tuyến, điểm đón) và token VeXeRe.
• Việc nặng ra khỏi API: dựng PNG/PDF, gọi VeXeRe, gửi tin đều là job ở worker; API chỉ ghi CSDL và đẩy job.
• Thời gian thực bằng SSE thay vì long-poll: một kết nối/người, nginx proxy_buffering off cho đường /api/sse.
• Giao diện: Vite + SWC, tách gói theo trang (lazy route), Ant Design nhập theo thành phần, service worker cache tài nguyên tĩnh, TanStack Query cache dữ liệu và làm mới theo SSE, ảnh vé tạo ở máy chủ (không dựng ở điện thoại yếu).
• Máy chủ Node: --max-old-space-size phù hợp (api 512 MB, worker 768 MB), PM2 cluster 2 instance cho api trên 2 vCPU.

4. Chống lỗi và chống chết hệ thống

Nguyên tắc: một thứ hỏng không kéo thứ khác; mọi thứ tự dậy; dữ liệu không mất, không trùng.

4.1 Cách ly tiến trình

4.2 Trong mã

• Bắt unhandledRejection/uncaughtException → ghi nhật ký, thoát có kiểm soát để PM2 dựng lại (không "nuốt" lỗi rồi chạy tiếp sai).
• Tắt mềm: nhận SIGTERM → ngừng nhận yêu cầu/job mới, chờ job đang chạy ≤ 30 giây, đóng kết nối → pm2 reload không rớt yêu cầu.
• Idempotency ở mọi biên: nguon + ma_nguon cho vé nguồn, transaction_id cho lệnh VeXeRe, event_type + booking_code + event_timestamp cho webhook, ve_id + kenh + loai_tin cho tin gửi.
• Giao dịch CSDL và khoá hàng khi chuyển trạng thái vé (SELECT … FOR UPDATE), không bao giờ hai điều hành xếp cùng một vé.
• Cầu dao (opossum) cho VeXeRe, SMS gateway, Zalo OA: lỗi liên tiếp → mở cầu dao 60 giây, job vào hàng chờ, không dồn dập gọi dịch vụ đang hỏng.
• Thử lại có lùi và hàng đợi chết (dead-letter) trong BullMQ: sau N lần thất bại, job chuyển sang "cần người xem", hiện ở bàn xếp vé.
• Kiểm tra đầu vào bằng zod ở API, webhook, tệp đẩy lên; giới hạn kích thước tệp; giới hạn tốc độ theo IP/tài khoản (@nestjs/throttler + nginx limit_req).
• Cờ mô-đun: mô-đun lỗi bị vô hiệu tự động, lõi chạy tiếp (tài liệu 00 mục 4.9).

4.3 Vận hành

• Giám sát: /health (CSDL, Redis, phiên Zalo, SIM lần liên hệ cuối, token VeXeRe, sao lưu cuối); aaPanel hiển thị CPU/RAM/PID từng Node project và có cảnh báo (Monitor/alarm) qua Telegram/Email; bot Zalo/Telegram của hệ thống báo sự cố nghiệp vụ; Uptime Kuma là tuỳ chọn nếu muốn theo dõi từ ngoài VPS.
• Tự dậy: Node project của aaPanel (PM2 bên trong) khởi động lại tiến trình chết, giới hạn bộ nhớ, boot cùng máy; Cron Access URL gọi /health mỗi 5 phút để ghi nhận sống/chết trong log.
• Sao lưu: hoàn toàn bằng Cron aaPanel + plugin Google Drive (mục 5.3); Redis không cần sao lưu; kiểm tra khôi phục tự động hằng tuần.
• Nhật ký: pino JSON ra log của Node project; Cron Cut Log của aaPanel cắt và giữ 30 tệp; che SĐT.
• Bảo mật máy chủ: chỉ mở 22/80/443 (aaPanel Security), SSH bằng khoá, fail2ban, cập nhật bảo mật tự động (unattended-upgrades), PostgreSQL/Redis chỉ localhost, bí mật trong .env quyền 600.
• Phát hành theo bậc: UAT VeXeRe → nhánh main → VPS; có thể thêm Node project cgv-api-thu trên cổng khác để thử bản mới trước khi chuyển domain.

5. Triển khai trên aaPanel như một ứng dụng web có domain riêng

Mục tiêu người dùng đặt ra: cài lên aaPanel như một ứng dụng web có domain riêng, chạy qua proxy, đơn giản, ít thao tác tay, dựa vào tính năng aaPanel có sẵn. Kết luận sau khi tra tài liệu chính thức (02/9/2026): aaPanel đã có đủ, không cần Docker, không cần cài PM2/nginx/PostgreSQL thủ công.

5.1 Tính năng aaPanel được dùng

5.2 Các bước cài một lần (khoảng 30 phút, chi tiết trong deploy/HUONG-DAN-AAPANEL.md)

1. App Store: cài Node.js version manager (chọn 22), PgSQL manager, Redis, Google Drive (xác thực tài khoản Drive).
2. PgSQL manager: tạo database cong_gui_ve và user; ghi mật khẩu vào .env.
3. Terminal: git clone https://<PAT chỉ đọc>@github.com/biencuong/CongGuiVe.git /www/wwwroot/cong-gui-ve; sao chép deploy/.env.example thành .env, điền bí mật, chmod 600.
4. Website → Node project → Add ba dự án, đều bật Boot on startup, Node 22, user www: - cgv-api — kiểu PM2 Project, tệp khởi động deploy/khoi-dong.cjs (tham số api), cổng 3000, giới hạn bộ nhớ 512 MB, 1 instance (2 khi ≥ 4 vCPU); Domain ve.xekhachhagiang.vn → bật Mapping → cài SSL, bắt buộc HTTPS. - cgv-worker — tệp khởi động deploy/khoi-dong.cjs (tham số worker), cổng 3001 (chỉ /health), không domain. - cgv-zalo — tham số worker-zalo, cổng 3002, giới hạn 384 MB, không domain. khoi-dong.cjs (GĐ0) tự kiểm tra node_modules → pnpm install --frozen-lockfile; chạy prisma migrate deploy; dựng apps/web/dist nếu thiếu; rồi chạy tiến trình tương ứng. Nhờ vậy cập nhật = git pull + bấm Restart trong panel, hoặc nút Cập nhật trong app gọi deploy/cap-nhat.sh rồi tự khởi động lại.
5. Site do Mapping tạo → Config: dán khối deploy/nginx-them.conf vào trong server {}: / phục vụ apps/web/dist (SPA fallback), /api/ → 127.0.0.1:3000, /api/sse tắt proxy_buffering, giới hạn tốc độ /api/vexere/webhook và /api/sms/webhook, nén. Không muốn chạm nginx thì để api tự phục vụ SPA (chậm hơn một chút, chấp nhận được ở GĐ1).
6. Cron: bốn tác vụ ở mục 5.3.
7. Security: chỉ mở 22 (đổi cổng, SSH bằng khoá), 80, 443; các cổng 3000–3002, 5432, 6379 không mở ra ngoài.

Bố cục trên VPS:

/www/wwwroot/cong-gui-ve/        git clone; .env (600) không trong git
  deploy/khoi-dong.cjs            tệp khởi động cho Node project (cài phụ thuộc, di trú, dựng web, chạy)
  deploy/cap-nhat.sh              pull → khởi động lại 3 dự án qua API aaPanel → kiểm tra /health
  deploy/nginx-them.conf          khối dán vào site aaPanel
  deploy/sao-luu.sh               Cron A (mục 5.3)
  deploy/khoi-phuc.sh             khôi phục từ bản sao lưu
  deploy/kiem-tra-khoi-phuc.sh    Cron C
  data/                           phiên Zalo, tệp tải lên (được sao lưu, không trong git)
/www/backup/cong-gui-ve/          bản sao lưu cục bộ 7 ngày, aaPanel đẩy lên Google Drive

Cấu hình VPS tối thiểu: 2 vCPU, 4 GB RAM, 40 GB SSD. Nếu dùng chung VPS với Vé247 (STT faster-whisper tốn RAM), cần ≥ 8 GB hoặc tách VPS.

5.3 Sao lưu tự động và đẩy lên Google Drive bằng Cron của aaPanel

Vì Cron Backup Database chỉ hỗ trợ MySQL, PostgreSQL đi đường Shell Script rồi Backup Directory đẩy lên Google Drive. Nguyên tắc: CSDL + cấu hình + phiên Zalo là những gì không dựng lại được từ git; bí mật lên Drive phải ở dạng mã hoá; sao lưu chưa kiểm tra khôi phục thì chưa tính là sao lưu.

Khôi phục: tải hai tệp từ Drive về, chạy bash deploy/khoi-phuc.sh <tệp.dump> [<tệp.tar.gz.enc>] (giải mã, pg_restore --clean --if-exists, in nhắc khởi động lại ba dự án). Mục tiêu: khôi phục xong ≤ 30 phút; mất dữ liệu tối đa 24 giờ. Muốn hạ xuống 1 giờ: thêm Cron A′ chu kỳ "N giờ = 1" chỉ chạy pg_dump (bản .dump vài MB).

Các tệp deploy/sao-luu.sh, deploy/khoi-phuc.sh, deploy/kiem-tra-khoi-phuc.sh, deploy/.env.example, deploy/HUONG-DAN-AAPANEL.md đã có trong repo; khoi-dong.cjs, cap-nhat.sh, nginx-them.conf viết ở GĐ0 khi có mã.

6. Tích hợp AI (mô-đun ai-tro-ly)

6.1 Nguyên tắc

AI không ghi thẳng vào lõi. Mọi kết quả AI là đề xuất có điểm tin cậy; người (đại lý/điều hành) xác nhận trên bảng xem trước; lệnh vào lõi vẫn là lệnh chuẩn (taoVe, suaVe). Không có AI thì hệ thống vẫn chạy đủ (mô-đun tắt được).

6.2 Các ứng dụng xếp theo giá trị

6.3 Kỹ thuật

• SDK chính thức @anthropic-ai/sdk (TypeScript); mô hình mặc định claude-opus-4-8 (5 USD/1M token vào, 25 USD/1M token ra); suy nghĩ thích ứng thinking: {type: "adaptive"}; structured outputs (client.messages.parse() với zod schema của vé) để không phải tự phân tích JSON. Nếu muốn giảm chi phí cho việc 1 và 6 ở khối lượng lớn, người dùng có thể chọn claude-haiku-4-5 (1 USD/5 USD) hoặc claude-sonnet-5 (3 USD/15 USD) — đó là quyết định của người dùng, không tự hạ.
• Prompt caching: hướng dẫn hệ thống + danh mục tuyến/điểm đón cố định đặt trước, nội dung biến đặt sau; kiểm tra cache_read_input_tokens > 0.
• Batch API (giảm 50 %) cho việc 3 và 6 chạy đêm.
• Ước chi phí việc 1: một ảnh danh sách ~1.500 token vào + 500 token ra ≈ 0,02 USD với Opus 4.8; 100 ảnh/ngày ≈ 2 USD/ngày.
• Bảo vệ dữ liệu: gửi tối thiểu (không gửi email/ghi chú nhạy cảm nếu không cần), che SĐT khi chỉ cần suy luận cấu trúc, ghi nhật ký prompt/kết quả để kiểm tra, không dùng dữ liệu khách để huấn luyện (mặc định API không dùng).
• Chống lỗi: thời gian chờ 60 giây, cầu dao, khi AI lỗi thì rơi về luật chuẩn hoá (đại lý vẫn nhập tay được); ngưỡng tin cậy < 0,7 thì bắt buộc xem lại.

7. Tự động hoá

8. Ứng dụng người dùng: PC và mobile

8.1 So sánh cách làm ứng dụng mobile

8.2 Thiết kế PWA cho đại lý (điện thoại) và điều hành (PC)

• Một ứng dụng, hai bố cục: mobile bố cục một cột, thanh điều hướng dưới (Vé mới · Vé của tôi · Đẩy danh sách · Thống kê · Tôi); PC bố cục hai cột cho bàn xếp vé và bảng quản trị.
• Nhập ít gõ: chọn tuyến/giờ gần đây, ô SĐT type="tel", ngày bằng chip "hôm nay / mai / kia", điểm đón theo danh sách; dán tin Zalo → hệ thống tách thành vé (luật + AI); chụp ảnh danh sách (camera) → AI đọc.
• Ngoại tuyến có kiểm soát: form vé lưu IndexedDB khi mất mạng, tự gửi khi có mạng (Android: Background Sync; iOS: gửi khi mở lại app); danh sách vé gần đây đọc được ngoại tuyến; dải "đang ngoại tuyến" rõ ràng.
• Thông báo đẩy: vé đã xếp, vé bị từ chối, yêu cầu được duyệt, giữ chỗ sắp hết hạn; Web Push (VAPID) qua web-push; iOS chỉ khi đã thêm vào màn hình chính → hướng dẫn cài ngay lần đầu đăng nhập.
• Chạm một tay: nút ≥ 44 px, thao tác chính ở vùng ngón cái, chip trạng thái màu thống nhất (tài liệu 00), chữ 16 px trở lên, tối/sáng theo máy.
• Máy yếu, mạng yếu: gói ban đầu < 300 KB nén, ảnh vé do máy chủ dựng, danh sách ảo hoá, tránh hoạt ảnh nặng; kiểm tra bằng Lighthouse mobile với Moto G (mô phỏng).
• Cập nhật: service worker báo "có bản mới" → tải lại; phiên bản hiện trong mục Tôi.
• Bảo mật: phiên cookie HttpOnly + SameSite; khoá màn hình ứng dụng (mã PIN tuỳ chọn) cho đại lý dùng máy chung; đăng xuất từ xa.

8.3 Ứng dụng trên máy gửi SMS

Máy Android + SIM đặt cố định chạy ứng dụng SMS Gateway (mã nguồn mở), kết nối máy chủ gateway tự host; trang quản trị hiển thị máy nào đang sống, số tin hôm nay, lỗi. Nếu app không đáp ứng (ví dụ cần nhiều SIM trên một máy, hoặc nhận SMS khách trả lời để ghi vào vé), viết app Kotlin riêng theo cùng giao thức REST + webhook.

9. Cơ chế phiên bản và đồng bộ git (đã cài trong repo)

9.1 Quy ước

• Nguồn phiên bản duy nhất: trường version trong package.json gốc (semver X.Y.Z). Khi có monorepo, lõi và từng mô-đun có version riêng trong package.json/manifest.ts của chúng; phiên bản gốc là "bản phát hành toàn hệ thống".
• Thẻ git vX.Y.Z gắn vào commit phát hành; docs/CHANGELOG.md theo Keep a Changelog: mọi thay đổi ghi vào mục [Chưa phát hành], khi nâng phiên bản script chuyển thành [X.Y.Z] - ngày.
• Thông điệp commit kiểu Conventional Commits, mô tả tiếng Việt: feat(vexere): giữ chỗ tự động, fix(gui-tin): thử lại SMS, docs: cập nhật hướng dẫn đại lý. Quy tắc nâng: feat → minor, fix → patch, BREAKING CHANGE → major.
• Nhánh: main là bản chạy trên VPS; việc lớn làm trên nhánh tinh-nang/<ten> và gộp bằng PR để CI kiểm tra.

9.2 Công cụ trong repo

9.3 Dùng hằng ngày

# Máy dev (Windows) — cuối buổi làm việc
powershell -ExecutionPolicy Bypass -File scripts\dong-bo-git.ps1 -ThongDiep "docs: bổ sung phân tích công nghệ"
# Phát hành bản mới (nâng minor, gắn thẻ, đẩy)
powershell -ExecutionPolicy Bypass -File scripts\dong-bo-git.ps1 -Nang minor -ThongDiep "feat: giai đoạn 1"

Đồng bộ tự động theo lịch (tuỳ chọn, chưa bật — chờ chốt ở mục 10): Task Scheduler chạy dong-bo-git.ps1 -ThongDiep "tự động" mỗi 30 phút; chỉ commit khi có thay đổi. Nhược điểm: lịch sử commit vụn; thích hợp cho giai đoạn tài liệu, không nên dùng cho mã.

9.4 Trên VPS

deploy/cap-nhat.sh (GĐ0) kéo main rồi khởi động lại ba Node project (qua API của aaPanel hoặc lệnh PM2 mà panel dùng), khoi-dong.cjs tự cài phụ thuộc, di trú, dựng web; script kiểm tra /health và ghi số bản (git describe --tags) để trang quản trị hiển thị; nút Cập nhật gọi script này; GitHub webhook có thể kích hoạt tự động khi có thẻ mới.

10. Điểm chưa rõ cần chốt

1. 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 CPU/RAM/đĩa.
2. Domain và tài khoản Google Drive cho sao lưu: tên miền phụ nào (đề xuất ve.xekhachhagiang.vn); Drive của nhà xe riêng hay tài khoản đang dùng? Khoá mã hoá sao lưu sẽ giữ ở đâu ngoài VPS?
3. Zalo cá nhân: dùng bao nhiêu tài khoản, có số SIM riêng cho nhà xe không, chấp nhận thỉnh thoảng quét lại QR trên trang quản trị?
4. Mobile — đã chốt 02/9/2026: PWA cài từ trình duyệt ở bản 1. Còn lại: tỉ lệ đại lý dùng iPhone (ảnh hưởng thông báo đẩy, chia sẻ tin).
5. AI — đã chốt 02/9/2026: bản 1 bật "đọc danh sách vé từ văn bản dán và ảnh chụp", mô hình mặc định claude-opus-4-8. Còn lại: ngân sách tháng; có đổi sang mô hình rẻ hơn cho khối lượng lớn không.
6. Đồng bộ git — đã chốt 02/9/2026: Claude tự chạy scripts/dong-bo-git.ps1 cuối mỗi lượt làm việc có thay đổi; không đặt lịch tự động.
7. Tên repo CongGuiVe (riêng tư, tài khoản biencuong) có cần đổi không?
8. Máy gửi SMS: chấp nhận ứng dụng SMS Gateway mã nguồn mở, hay muốn app riêng ngay từ đầu?