Skip to content

Sơ đồ hệ thống ​

Toàn cảnh ​

HTTPS · token ES256 · x-pi-appSQL qua poolerUser AppFlutter · khách hàngSale AppFlutter · nhân viên bán hàngWeb AdminReact + Vite · nội bộgraphqltoàn bộ APIauthdanh tính, phiênjobsjob định kỳpayment-webhookcallback MoMopipoint-eventsevent PiPointPostgreSQL 17bảng · ràng buộc · RLS · hàm SECURITY DEFINERPiPointStorageMoMoSupabase Edge Functions — toàn bộ API của hệ thốngNét đứt = hệ thống ngoài PIDEAL

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 FunctionViệcAi gọi
graphqlToàn bộ API nghiệp vụ của ba ứng dụngBa client
authĐăng ký, đăng nhập, phiên, refresh, MFA, đổi token PiPoint lấy phiên PIDEALBa client
jobsJob định kỳSupabase Cron, mỗi phút
payment-webhookCallback của nhà cung cấp thanh toánMoMo
pipoint-eventsSự kiện tài khoản PiPoint đẩy sangPiPoint, 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ủ ý ​

Client3 ứng dụng/rest/v1Data API tự động/graphql/v1GraphQL tự độngbảng PostgreSQLtruy cập trực tiếpEdge Functionlối vào duy nhấtBa đường gạch chéo đều TẮT trên mọi project

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ì ​

POST /functions/v1/graphqlbearer · body · parse · giới hạn tài liệux-pi-app hợp lệxác thực token ES256 (cục bộ)phiên còn sốngwithAuditguard quyềnsanitize input + Zodservice → repositoryprojector outputmask lỗitrước resolvermỗi root fieldsanitize SAU guardkhông gọi HTTP

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 ​

accountsCUSTOMERkhách hàngSTAFFnhân viên Web AdminAPP_USERAPP_SALEWEB_ADMINrole: userrole: salerole: …app_membershipsrole_assignmentsKhoá duy nhất là (số điện thoại, loại tài khoản) — một người có thể có cả hai

Đ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 ​

resolverđiều phối, đổi tên trườngrequirePermission()quyền · scope · MFAparseArgs()sanitize + Zod, đúng một lầnservicequy tắc nghiệp vụrepositorySQL, postgres.jsPostgreSQLràng buộc · transaction · RLS · hàm definertừ chối ở đâykhông gọi safeParse thẳngSQL chỉ ở tầng nàybất biến tiền/trạng thái

Thứ tự này là bất biến của dự án. Hai lỗi hay gặp trong review:

  • Gọi safeParse của Zod thẳng thay vì parseArgs() — như vậy là bỏ qua bước sanitize, vì parseArgs mớ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.

Sinh từ ad83b0aea · 820 migration · PostgreSQL 17