Bỏ qua để đến nội dung

Kiến trúc

Xem markdown

BeaChoice là một monorepo gồm các ứng dụng triển khai độc lập, dùng chung một API NestJS, một cơ sở dữ liệu Postgres và một dịch vụ xác thực. Trang này tóm tắt bức tranh chung; chi tiết từng phần nằm ở docs/system-architecture.md trong repo.

flowchart TB
subgraph Clients
W["apps/web<br/>Next.js · khách"]
S["apps/salon<br/>Next.js · chủ salon"]
A["apps/admin<br/>Next.js · quản trị"]
M["apps/mobile<br/>Flutter · khách và salon"]
end
AU["apps/auth<br/>Better Auth"]
API["apps/api<br/>NestJS · /api/v2"]
DB[("Postgres 17<br/>+ pg-boss")]
R2[("Object storage<br/>ảnh, video")]
SP["SePay<br/>thanh toán"]
W --> API
S --> API
A --> API
M --> API
W --> AU
S --> AU
A --> AU
M --> AU
API --> DB
API --> R2
SP -- webhook --> API
Thành phần Vai trò
apps/api Logic nghiệp vụ, lưu trữ, tác vụ nền (pg-boss), tích hợp ngoài
apps/auth Đăng nhập, tổ chức (salon), 2FA, cấp JWT ngắn hạn
apps/web Trang công khai và luồng đặt lịch của khách
apps/salon Ứng dụng web cho chủ salon và quản lý
apps/admin Console quản trị nền tảng, sau lớp truy cập riêng
apps/mobile Ứng dụng Flutter cho khách và salon
apps/docs Trang tài liệu này
packages/contracts Schema zod, danh mục lỗi, sự kiện, đặc tả OpenAPI
  • Hợp đồng trước, mã sau. Schema zod trong packages/contracts là nguồn duy nhất cho DTO, lỗi và OpenAPI. Xem OpenAPI.
  • Tenant là salon. Mã tổ chức bằng mã salon. Các đường dẫn /v2/salon/* lấy salon từ claim của JWT, không từ đường dẫn.
  • JWT ngắn hạn. Ứng dụng web giữ phiên bằng cookie ở máy chủ của chính nó; JWT sống năm phút và chỉ được đổi ở phía máy chủ, không xuống trình duyệt.
  • Tiền là số nguyên đồng. Mọi số tiền lưu bằng số nguyên, đơn vị đồng.
  • Hai luồng thanh toán tách bạch. Phí gói đi vào tài khoản của nền tảng, cọc đi vào tài khoản của từng salon. Nền tảng không giữ tiền cọc.
  • Lỗi theo RFC 9457. Phản hồi lỗi là application/problem+json với trường code ổn định để xử lý bằng chương trình.
  • Trang HTML nhận CSP theo từng yêu cầu. Trang web dùng nonce, vì vậy không có trang HTML tĩnh dùng chung cho mọi người.