Giao diện
API GraphQL
Trang sinh tự động
Parse từ code/apps/api/supabase/functions/graphql/schema.graphql — file SDL do backend export bằng deno task schema:export, cũng là nguồn mà client web và mobile codegen từ đó. Không hand-edit ở cả hai phía.
Toàn bộ API của ba ứng dụng đi qua một endpoint: POST /functions/v1/graphql. Chi tiết tầng và xác thực: Kiến trúc back-end.
Quy mô
| Query | 238 |
| Mutation | 175 |
| Kiểu dữ liệu | 1.349 |
| — type | 756 |
| — enum | 361 |
| — input | 229 |
| — scalar | 3 |
| Operation có description | 398/413 (96%) |
| Operation ghi rõ quyền trong SDL | 258/413 (62%) |
Theo domain
Gán bằng cách tìm tên field trong khối extend type Query/Mutation của từng domain (domains/<domain>/*schema*.ts). 38 domain trong backend.
| Domain | Query | Mutation | |
|---|---|---|---|
| payment | 17 | 17 | 34 |
| pipoint | 15 | 9 | 24 |
| spin | 11 | 13 | 24 |
| tier-admin | 14 | 8 | 22 |
| identity | 10 | 11 | 21 |
| campaign | 13 | 8 | 21 |
| catalog | 9 | 9 | 18 |
| order | 13 | 5 | 18 |
| product | 10 | 7 | 17 |
| cms | 10 | 7 | 17 |
| product-attribute | 4 | 11 | 15 |
| sale-admin | 7 | 8 | 15 |
| fulfillment | 8 | 7 | 15 |
| customer | 8 | 6 | 14 |
| campaign-public | 12 | 2 | 14 |
| mission | 7 | 4 | 11 |
| attribution | 5 | 6 | 11 |
| privacy | 2 | 8 | 10 |
| sale-profile | 5 | 4 | 9 |
| media | 4 | 3 | 7 |
| tier | 7 | 0 | 7 |
| report | 7 | 0 | 7 |
| shortage | 4 | 2 | 6 |
| sale-view | 6 | 0 | 6 |
| profile | 2 | 3 | 5 |
| sale-application | 3 | 2 | 5 |
| finance-policy | 2 | 3 | 5 |
| report-export | 2 | 3 | 5 |
| product-file | 2 | 2 | 4 |
| cms-public | 4 | 0 | 4 |
| notification | 3 | 1 | 4 |
| audit | 4 | 0 | 4 |
| campaign-import | 3 | 0 | 3 |
| sale-transition | 1 | 2 | 3 |
| recurring-skip | 1 | 2 | 3 |
| order-return | 2 | 0 | 2 |
| mfa | 0 | 2 | 2 |
| affiliate-reward | 1 | 0 | 1 |
Quy ước chung
Những điều sau đúng cho mọi operation, nên các trang domain không nhắc lại.
Header. Authorization: Bearer <access token> và x-pi-app: APP_USER | APP_SALE | WEB_ADMIN là bắt buộc. x-correlation-id tuỳ chọn, được echo lại và đóng dấu lên mọi lỗi. Ngoại lệ duy nhất: User App khách chưa đăng nhập được gọi một số field công khai mà không cần token.
Phân trang. Một kiểu duy nhất: page (từ 1) + pageSize. Mọi danh sách trả về { items, page, pageSize, total }, cộng sourceStatus khi nguồn có thể thiếu dữ liệu. Không dùng cursor.
Mutation. Input mang requestId làm khoá idempotency; sửa bản ghi đã có thì phải gửi expectedVersion. Kết quả mang status: ACCEPTED | REPLAYED | UNKNOWN — client không suy ra thành công từ HTTP 200.
Lỗi. Mã nằm trong extensions.code, danh sách cố định: unauthorized, forbidden, not_found, validation_failed, conflict, stale_version, policy_undecided, provider_unknown, internal, otp_invalid, too_many_requests. Lỗi không mang mã nào trong số đó ra ngoài dưới dạng internal với message cố định.
Scalar. DateTime luôn UTC ISO-8601 với Z. VndAmount và PointAmount là số nguyên JSON. ID là chuỗi đục, client không parse.
Nguồn đầy đủ của các quy ước này: docs/contracts/api-conventions.md.