Skip to content

Kiến trúc back-end ​

Backend chạy trên Supabase nhưng không theo mô hình BaaS. Supabase ở đây là hạ tầng được quản lý — PostgreSQL, Storage, runtime cho Edge Function, connection pooler — còn API thì do dự án tự viết.

Phần chung cho cả ba phía ở Kiến trúc chung.

Luật gốc ​

Mọi API của ứng dụng phải được viết tường minh trong Edge Function và nằm trong Git — kể cả CRUD đơn giản nhất.

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

Cái giá: mọi CRUD phải viết tay. Cái nhận lại: mỗi API review được qua pull request, xác thực và phân quyền tập trung, và thay đổi schema không bao giờ vô tình mở ra API mới.

Năm Edge Function ​

FunctionViệcAi gọiĐặc điểm
graphqlToàn bộ API nghiệp vụBa clientMột endpoint, domain compose bên trong
authDanh tính, phiên, MFA, đổi token PiPointBa clientFunction duy nhất giữ khoá ký riêng
jobsJob định kỳSupabase Cron mỗi phútDùng role pi_worker riêng
payment-webhookCallback nhà cung cấp thanh toánMoMoKiểm chữ ký trên byte nhận được
pipoint-eventsSự kiện tài khoản PiPointPiPoint qua Pub/SubChỉ ghi biên nhận, không gọi ngược

Chỉ một endpoint GraphQL, không phải một function cho mỗi endpoint — nếu không sẽ có hàng trăm function. Nhóm theo domain nghiệp vụ, compose trong một function.

Thứ tự lớp ​

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, không phải khuyến nghị:

  • Resolver chỉ điều phối và đổi snake_case → camelCase. Không có quy tắc nghiệp vụ nào ở đây.
  • Repository giữ SQL. Không có SQL nào nằm trong service hay resolver.
  • Sanitize chạy sau guard, nên người không có quyền luôn nhận unauthorized/forbidden chứ không bao giờ thấy chi tiết chính sách.

Một domain gồm những gì ​

Mỗi domain nghiệp vụ là một thư mục dưới functions/graphql/domains/<domain>/:

domains/catalog/
├── schema.ts              SDL — template literal TypeScript
├── resolvers.ts           điểm vào, nối guard → validate → service
├── validators.ts          Zod cho từng operation
├── *-service.ts           quy tắc nghiệp vụ
├── *-repository.ts        SQL
├── sanitize-profile.ts    profile cho từng field vào và ra
├── guards.ts              luật quyền của domain
└── *_test.ts              test đặt cạnh code

Domain lớn chia thêm thư mục con (ví dụ pipoint/wallet/). Helper dùng chung cho nhiều domain nằm ở functions/_shared/.

Chỉ chủ hợp đồng được compose. Chỉ graphql/compose-types.ts (danh sách SDL) và graphql/compose.ts (danh sách resolver) biết tên domain; index.ts import hai file đó và không import gì khác. Pull request của một domain thêm module của mình vào hai danh sách, không sửa index.ts.

→ Tra cứu API theo domain

Xác thực caller ​

Bearer là access token do auth phát: JWT ES256, hạn ngắn, mang kid, iss, aud = pideal-api, sub = id tài khoản, sid = phiên, và app.

Hàm graphql xác thực cục bộ, không gọi HTTP sang đâu:

  1. Kiểm chữ ký bằng khoá công khai của các issuer tin cậy (AUTH_TRUSTED_ISSUERS).
  2. app trong token phải trùng header x-pi-app, nếu không thì forbidden.
  3. Phiên phải còn sống — hỏi ngay trong câu lệnh đầu tiên của transaction nạp actor, nên không tốn thêm một vòng đi về database.

Token không chứa vai trò hay quyền. Quyền là các grant (permission, scope) còn hiệu lực, đọc lại ở mỗi request, nên thu hồi quyền có tác dụng ngay.

Khoá ký riêng chỉ nằm trong auth. Supabase cấp secret theo project, nên điều này do code và một gate CI bảo đảm, không phải do nền tảng.

→ Route của function auth · Danh mục kiểm soát

Mutation: một đường duy nhất ​

Mọi mutation đi qua runCommand, làm đúng một trình tự trong một transaction:

một transactionmutationinput mang requestIdguard quyềnZodclaim khoá idempotency (actor, operation, requestId)kiểm expectedVersionthay đổi trạng tháighi event vào outboxlưu kết quả cho lần replaycùng khoá, cùng payload→ REPLAYEDlệch version→ stale_versioncùng
Tình huốngKết quả
Cùng khoá, cùng payloadTrả kết quả đã lưu, status: REPLAYED — không chạy lần hai
Cùng khoá, payload khácconflict / idempotency_key_reuse
Khoá đang chạyconflict / request_in_progress
Thực thi ném lỗiKhoá được giải phóng — cho phép thử lại
Nhà cung cấp không trả lời dứt khoátKết quả status: UNKNOWN, khoá vẫn giữ

Điểm cuối quan trọng với thanh toán: UNKNOWN không phải thất bại. Client phải hỏi lại trạng thái hoặc thử lại với cùng requestId, tuyệt đối không tạo giao dịch mới.

Lưu không đổi gì thì không ghi gì: không tăng version, không đổi updated_at, không ghi dòng audit thành công — trả changed: false.

Hai thứ chạy tự động trên mọi mutation ​

Audit. withAudit bọc toàn bộ Mutation lúc compose schema. Một lệnh từ Web Admin để lại đúng một dòng chỉ-ghi-thêm: ai làm, làm gì, input đã mask, kết quả SUCCESS · FAILED · DENIED, IP. Trigger trên bảng audit từ chối UPDATE và DELETE. Mutation mới không khai trong registry thì test đỏ. PII được mask trước khi insert.

Dòng audit ghi trong transaction của lệnh, nên rollback thì không còn dòng nào; replay cũng không ghi thêm.

Sanitize. Mọi chuỗi vào và ra đi qua policy: phát hiện câu lệnh SQL, ký tự điều khiển và bidi, allow-list cho rich text. Mỗi domain khai profile cho từng field; thiếu profile thì test đỏ. Auth, webhook, import và export không có default theo type — mọi khoá, mọi ô, mọi cột đều phải khai.

Trên đường ra có một bước nữa: projector làm sạch dữ liệu cũ không an toàn, nhưng không bao giờ ghi đè vào database — không backfill, không migration dữ liệu. Giá trị không làm sạch được thì để trống (null, hoặc '' với String!), và client phải render được cả hai.

Logic nghiệp vụ nằm ở đâu ​

Phần lớn bất biến về tiền và trạng thái không nằm trong TypeScript mà trong hàm SQL SECURITY DEFINER. Một transaction trong database là nơi duy nhất giữ được bất biến khi nhiều request chạy đồng thời.

Ví dụ thật: thứ tự khoá dòng khi đặt cọc là order → nghĩa vụ thanh toán → intent, giống nhau ở cả năm chỗ ghi. Trước khi thống nhất, callback khoá theo thứ tự ngược với lệnh huỷ của khách và hai bên deadlock.

TypeScript điều phối; SQL giữ sự thật.

→ Hàm SQL theo schema

Job định kỳ ​

Không có process chạy nền. pg_cron + pg_net post {"mode":"tick"} tới POST /functions/v1/jobs mỗi phút, kèm một secret so sánh theo thời gian hằng số. Mỗi tick chạy các job đến hạn, qua role pi_worker riêng.

Lịch kiểu EVERY_N_MINUTES không bù lại các lần lỡ — một việc đến hạn chờ tối đa N phút. Job nào chưa cấu hình giới hạn thì bị bỏ qua và được nêu tên trong log của tick, không chạy lặng lẽ.

Cron được CI đăng ký lại mỗi lần deploy, không có công tắc bật/tắt.

Event ​

Thay đổi trạng thái ghi event vào outbox trong cùng transaction với thay đổi đó — nên không có chuyện ghi dữ liệu thành công mà mất event. Bên nhận đọc qua inbox nên xử lý lại không trùng lặp.

Vòng chuyển tiếp outbox mặc định tắt, vì một event đã chuyển tiếp sẽ ở trạng thái đã gửi cho mọi consumer, kể cả consumer chưa đăng ký.

PiPoint, server tới server ​

_shared/pipoint/ giữ client dùng service account: khoá SA → Google ID token → gọi walletPlatform-ledger và ekycPlatform-review. Nó cũng giữ bộ kiểm PiPoint ID token và bộ kiểm OIDC của Pub/Sub.

Hai ràng buộc được gate CI canh:

  • Chỉ _shared/env.ts đọc khoá service account, và function auth không bao giờ giữ nó.
  • Chỉ auth đọc khoá ký riêng.

Điểm chờ (pending) là của PIDEAL; chỉ khi phát hành mới ghi có vào ví PiPoint. Ví không bao giờ âm.

Giới hạn chống lạm dụng ​

Giới hạn tài liệu GraphQL (body, độ sâu, số selection, số root field) chạy trước mọi resolver, không có trạng thái. Introspection tắt ở mọi môi trường trừ khi bật cờ, và production bỏ qua cờ đó.

Giá trị cụ thể: Danh mục kiểm soát.

Ràng buộc triển khai ​

Function graphql vượt giới hạn 5 MB của Supabase. CI dựng một bản copy đã bỏ type, comment và khoảng trắng bằng esbuild — không rename, không bundle, giữ nguyên cấu trúc file và import — rồi deploy bản đó. Repo không bị đổi.

Kèm theo: unit test chạy trên bản đã strip, một gate kích thước, và một phép thử nạp function trước khi db push. Source map lưu làm artifact của CI.

Kiểm thử ​

TầngCông cụGhi chú
Unitdeno task testFile *-db_test.ts bị bỏ qua khi không có DB
Typecheckdeno task checkToàn bộ source
DBnode --test scripts/...Trên scratch DB, không bao giờ pideal_dev
Đầu cuối qua graphrunner riêngToken ES256 thật, kiểm phiên thật
Gate authnode scripts/auth-gates/run-all.mjsPhạm vi khoá, không còn tham chiếu GoTrue

Scratch DB là bản copy của một template đã áp đủ migration, nên tạo mất khoảng một giây thay vì chạy lại toàn bộ migration.

Một hành vi — một test, ở tầng thấp nhất chứng minh được nó. Đã có test cho hành vi gần giống thì mở rộng test đó, không thêm test song song ở tầng khác.

Chạy local ​

Không Docker. Edge Function là server Deno thường nên chạy trực tiếp: graphql ở cổng 8000, auth ở 8001, PostgreSQL 17 native ở 5433. Từ 2026-10-10 toàn bộ luồng kể cả đăng nhập chạy local; không gọi project cloud nào.

Đánh đổi đã chấp nhận: local không có gateway /functions/v1/*, mỗi function phục vụ trên cổng riêng.

→ Chạy local


Nguồn: docs/technical/01-back-end-supabase.md, docs/contracts/api-conventions.md, docs/technical/03-authentication.md §9, docs/technical/23-function-deploy-bundle.md, docs/technical/02-environment.md (nhật ký quyết định), và code trong code/apps/api/supabase/functions/. Trang viết tay — xem mức độ tin cậy.

Sinh từ ad83b0aea · 820 migration · PostgreSQL 17