Giao diện
Sơ đồ hệ thống
Toàn cảnh
Ba ứng dụng, năm Edge Function, một database. Hai hệ thống bên ngoài: PiPoint (định danh dùng chung và ví điểm của tập đoàn) và MoMo (thanh toán).
| Edge Function | Việc | Ai gọi |
|---|---|---|
graphql | Toàn bộ API nghiệp vụ của ba ứng dụng | Ba client |
auth | Đăng ký, đăng nhập, phiên, refresh, MFA, đổi token PiPoint lấy phiên PIDEAL | Ba client |
jobs | Job định kỳ | Supabase Cron, mỗi phút |
payment-webhook | Callback của nhà cung cấp thanh toán | MoMo |
pipoint-events | Sự kiện tài khoản PiPoint đẩy sang | PiPoint, qua Pub/Sub |
Hai function cuối không bao giờ là mutation của client — chúng là cổng vào cho hệ thống bên ngoài, có kiểm chữ ký hoặc OIDC riêng.
Hai đường bị chặn có chủ ý
Supabase có thể tự sinh REST và GraphQL từ schema PostgreSQL. PIDEAL tắt cả hai trên mọi project.
Cái giá phải trả là mọi CRUD dù đơn giản cũng phải viết tay. Cái nhận lại:
- Mỗi API hiện trong Git và review được qua pull request.
- Xác thực và phân quyền tập trung một chỗ.
- Thay đổi schema không bao giờ vô tình mở ra API mới — đây là lý do chính.
- Client không phụ thuộc vào thiết kế vật lý của database.
Một request đi qua những gì
Bốn điểm đáng chú ý:
Xác thực làm cục bộ. Không có lệnh gọi HTTP nào sang dịch vụ auth cho mỗi request. Chữ ký kiểm bằng khoá công khai của issuer tin cậy; câu hỏi "phiên còn sống không" được trả lời ngay trong câu lệnh đầu tiên của transaction nạp actor — không tốn thêm một vòng đi về database.
app trong token phải trùng x-pi-app. Lệch thì forbidden. Một token cấp cho User App không dùng được để gọi API Web Admin, kể cả khi người đó có cả hai tài khoản.
Sanitize chạy sau guard. Người không có quyền luôn nhận unauthorized/forbidden — họ không bao giờ thấy chi tiết chính sách lọc nội dung. Lượt bị từ chối vẫn để lại một dòng audit.
Projector output chạy sau resolver. Dữ liệu cũ không an toàn được làm sạch trên đường ra, nhưng không bao giờ ghi đè vào database: không backfill, không migration dữ liệu.
Một tài khoản, ba ứng dụng
Điểm dễ hiểu sai: có phiên chỉ chứng minh danh tính, không chứng minh quyền truy cập. Một người vừa được tạo tài khoản STAFF đăng nhập được ngay, nhưng chưa có vai trò nên thấy màn hình "Chưa có quyền" cho tới khi người khác duyệt.
Cả web và mobile đều gác theo cùng một cách: đọc me.nextStep, và mọi giá trị khác READY đều bị đẩy sang màn hình chờ.
Thứ tự lớp trong backend
Thứ tự này là bất biến của dự án. Hai lỗi hay gặp trong review:
- Gọi
safeParsecủa Zod thẳng thay vìparseArgs()— như vậy là bỏ qua bước sanitize, vìparseArgsmới là chỗ lấy verdict của bước đó. - Đặt sanitize trước guard — như vậy người không có quyền lại thấy được chi tiết chính sách lọc nội dung.
Dữ liệu
accounts là trục của toàn bộ mô hình: phần lớn khoá ngoại của hệ thống trỏ về nó. Trục nghiệp vụ là chiến dịch → đơn hàng → thanh toán — ba domain này nối với nhau dày hơn hẳn mọi cặp khác.
Con số cụ thể của từng cạnh không ghi ở đây vì trang này viết tay. Chúng nằm ở Cơ sở dữ liệu, nơi mọi số liệu do bộ sinh đo từ schema thật và có sơ đồ tương tác ba cấp: bản đồ domain → ERD nhóm con có cột → chi tiết bảng.
Trang viết tay; sơ đồ vẽ bằng SVG trong ArchDiagram.vue. Số liệu lấy ở Cơ sở dữ liệu — xem mức độ tin cậy.