TravelQ Hotel Admin — Kiến trúc microservice

Đề xuất self-host Holitech Linux · thiết kế only · 07/11/2026 (Asia/Saigon)

1. Mục tiêu điều hành và phạm vi

1.1 Mục tiêu

• Tách miền nghiệp vụ thành dịch vụ có chủ sở hữu dữ liệu riêng (database-per-service), giảm điểm nghẽn monolith hiện tại (một Worker + D1 dùng chung).
• Giữ hợp đồng nghiệp vụ đã biết (HV/TA, một tài khoản nhận tiền KS, bộ phận, hiển thị TQID, xuất pháp lý kiểm soát) khi đổi kiến trúc.
• Chạy trên máy chủ Linux Holitech tự quản; TLS Nginx/Caddy; bí mật qua Docker/K8s secrets — không phụ thuộc Cloudflare.

1.2 Trong / ngoài phạm vi

2. Hiện trạng đã xác minh vs đề xuất

Sự thật kỹ thuật từ audit 07/11/2026 (chỉ đọc). Đề xuất audit cũ Node + SQLite một máy phục vụ port monolith tối thiểu — bị thay bởi quyết định viết lại microservice; stack dưới chọn PostgreSQL per-service.

3. Sơ đồ kiến trúc đề xuất

Hình 1. Lớp UI riêng · Gateway/BFF · 16 miền dịch vụ · RabbitMQ outbox/inbox · Postgres per-service · ranh giới ngoài (TQID, cổng TT, thiết bị). SVG vector nhúng — không phụ thuộc Mermaid ngoài.

4. Catalog miền (~16) và sở hữu dữ liệu

Nguyên tắc: mỗi dịch vụ sở hữu schema, credential, backup riêng. Ban đầu có thể một cluster Postgres trên một máy nhưng cấm bảng dùng chung và cấm SQL join xuyên database. Giao tiếp liên miền bằng API phiên bản hóa + sự kiện.

5. Stack đề xuất (self-host)

Outbox ghi cùng transaction miền; consumer Inbox theo idempotency key — chống double-pay / double-allocate. Tên biến môi trường (names-only, không giá trị): ví dụ AUTH_DATABASE_URL, PAY_DATABASE_URL, RABBITMQ_URL, MINIO_ENDPOINT — Holitech chọn sau khi chốt runtime. Docker/Compose chưa cài trên máy audit hiện tại — cần môi trường riêng khi triển khai sau này.

6. Luồng nghiệp vụ bắt buộc (sơ đồ)

Hình 2. Luồng A (mua phòng) và Luồng B (đơn prepaid → ledger paid → attestation hoàn tất). HV tuyệt đối không hoàn/huỷ.

6.1 Mua phòng — không user-hold

1. Khởi tạo thanh toán → mã động TTL 60 giây, không hold quỹ theo phiên user.
2. Hết hạn → intent expired; provider đến muộn → quarantine + reconcile; không tự coi đã bán.
3. Chỉ PaymentVerified (chữ ký webhook, đúng merchant KS, đúng amount/order, chống replay) → Inventory Allocate nguyên tử.
4. Verified-paid mới đếm quỹ đã bán. Paid nhưng hết phòng → quarantine; xử lý theo policy TA/dịch vụ nếu được phép — tuyệt đối không hoàn/huỷ HV. Đây là design question mở, không “lặng hoàn”.

HV: không hoàn, không huỷ. TA: ngoại lệ chỉ highest TravelQ admin (không manager/LT). Quy tắc hoàn dịch vụ không áp blanket lên HV.

6.2 Đơn → tiền (ledger) → LT → bộ phận → attestation hoàn tất → báo cáo

1. Tạo đơn (snapshot giá server).
2. Prepaid (Bếp đồ ăn/uống; Spa): paid_verified trước LT dispatch. HK: đồ dùng miễn phí; giặt là trả phí theo rule.
3. LT dispatch → Dept Advance + expectedStep; non-terminal. LT không đánh dấu hoàn tất bộ phận. Nhắc sau 15 phút.
4. Đề xuất: Attestation QL là cổng hoàn tất dịch vụ — không xoá / không thay sổ cái đã paid_verified. Hiện chưa có contract → fail-closed cho bước hoàn tất.
5. Dịch vụ đã trả bị từ chối: RefundRequested → gọi provider → RefundSettled chỉ khi verified; retry idempotent; không mark sớm; không double-count.
6. Báo cáo / đối soát tách: paid · completed · refund_pending · settled. Ghi nhận kế toán doanh thu cần xác nhận tài chính.

Mọi khoản về một tài khoản nhận tiền đích KS. Không cash / nợ phòng / manual-paid. Mỗi giao dịch: mã động hotel / order / amount. KS bật/tắt nhóm đơn: chỉ đơn mới; giữ lịch sử. KS VIEW giá; TravelQ maker/checker = hai tài khoản cá nhân độc lập, không tự duyệt (mật khẩu dùng chung ≠ hai tài khoản độc lập).

6.3 Hiển thị danh tính & xuất pháp lý

• UI thường: holder = chữ cuối · TQID; Anh/Chị chỉ khi có giới tính hồ sơ. Người đi cùng / A4 / biên lai: chỉ TQID.
• Xuất khai báo cư trú: full info chỉ với ủy quyền + consent + audit; UI thường không full PII.

7. Bảo mật (đề xuất)

• RBAC + ABAC: mọi request gắn hotel / department / account-version đã ký phía server; role không do trình duyệt chọn.
• MFA cho admin và cặp 4-mắt giá.
• Service identity: mTLS (danh tính dịch vụ) và phân đoạn mạng giữa service — phân đoạn mạng không thay thế danh tính; webhook provider: chữ ký + timestamp + nonce chống replay.
• Truy vấn tham số hóa; PII hạn chế mã hóa at-rest; retention tách; audit pháp lý.
• Phiên khách in-room: gắn phòng, TTL ngắn, khóa khi checkout.
• CSRF: SameSite + Origin allowlist; cookie HttpOnly Secure; cấm wildcard origin.
• Không secret / hash verifier / token / số định danh cá nhân trong tài liệu hay ví dụ.

8. Vận hành · quan sát · sao lưu

• Compose: gateway, services, Postgres (logic tách), RabbitMQ, MinIO, (Redis), OTel collector, Prometheus, Grafana, Loki.
• Log: correlation-id bắt buộc; không PII; không body thanh toán.
• Backup: WAL PITR Postgres từng DB logic; object MinIO phiên bản + mã hóa; test restore định kỳ.
• Mục tiêu (chưa đạt): RPO ≤ 15 phút · RTO ≤ 4 giờ trên single-host. Failover HA là giai đoạn sau khi có nhu cầu thật đã đo.

9. Lộ trình · ước lượng · rủi ro

Giả định đội: 2–3 engineer full-stack + 0.5 ops quen Node/Postgres; song song với xác nhận nghiệp vụ từ anh Long. Đơn vị: person-week (pw). Không hứa ngày calendar / chi phí tiền. Không bịa số liệu test/CI hiện tại.

Tổng thô: ~22–37 pw (ước lượng lập kế hoạch). Với giả định đội 2–3 engineer, quy đổi thô ~8–19 tuần trước các trễ bên ngoài (gateway/TQID/pháp lý/onboarding) — không phải cam kết ngày giao.

10. Thuật ngữ

11. Kết luận

Đây là bản thiết kế đề xuất để Holitech self-host theo hướng microservice, kế thừa hợp đồng nghiệp vụ đã biết từ nguồn Hotel Admin hiện có, đồng thời không tuyên bố đã triển khai, đã nghiệm thu cổng thanh toán, khuôn mặt, encoder, attestation, hay chứng nhận danh tính TQID. Sự thật đã kiểm (monolith CF+D1, 4 API, 10 bảng core, không KV/R2 bắt buộc trong phạm vi rà, payment/face/encoder/attestation chưa xong) được tách rõ khỏi phần đề xuất.

Bước tiếp theo: anh Long và Holitech chốt các câu hỏi mục §9.2, rồi mới mở giai đoạn G0 / G1.

— Hết tài liệu đề xuất · không chứa secret · không dữ liệu cá nhân —