Giao diện
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.
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
| Function | Việc | Ai gọi | Đặc điểm |
|---|---|---|---|
graphql | Toàn bộ API nghiệp vụ | Ba client | Một endpoint, domain compose bên trong |
auth | Danh tính, phiên, MFA, đổi token PiPoint | Ba client | Function duy nhất giữ khoá ký riêng |
jobs | Job định kỳ | Supabase Cron mỗi phút | Dùng role pi_worker riêng |
payment-webhook | Callback nhà cung cấp thanh toán | MoMo | Kiểm chữ ký trên byte nhận được |
pipoint-events | Sự kiện tài khoản PiPoint | PiPoint qua Pub/Sub | Chỉ 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
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/forbiddenchứ 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 codeDomain 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.
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:
- Kiểm chữ ký bằng khoá công khai của các issuer tin cậy (
AUTH_TRUSTED_ISSUERS). apptrong token phải trùng headerx-pi-app, nếu không thìforbidden.- 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:
| Tình huống | Kết quả |
|---|---|
| Cùng khoá, cùng payload | Trả kết quả đã lưu, status: REPLAYED — không chạy lần hai |
| Cùng khoá, payload khác | conflict / idempotency_key_reuse |
| Khoá đang chạy | conflict / request_in_progress |
| Thực thi ném lỗi | Khoá được giải phóng — cho phép thử lại |
| Nhà cung cấp không trả lời dứt khoát | Kế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.
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à functionauthkhô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ầng | Công cụ | Ghi chú |
|---|---|---|
| Unit | deno task test | File *-db_test.ts bị bỏ qua khi không có DB |
| Typecheck | deno task check | Toàn bộ source |
| DB | node --test scripts/... | Trên scratch DB, không bao giờ pideal_dev |
| Đầu cuối qua graph | runner riêng | Token ES256 thật, kiểm phiên thật |
| Gate auth | node scripts/auth-gates/run-all.mjs | Phạ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.
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.