Skip to content

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

Query238
Mutation175
Kiểu dữ liệu1.349
— type756
— enum361
— input229
— scalar3
Operation có description398/413 (96%)
Operation ghi rõ quyền trong SDL258/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.

DomainQueryMutation
payment171734
pipoint15924
spin111324
tier-admin14822
identity101121
campaign13821
catalog9918
order13518
product10717
cms10717
product-attribute41115
sale-admin7815
fulfillment8715
customer8614
campaign-public12214
mission7411
attribution5611
privacy2810
sale-profile549
media437
tier707
report707
shortage426
sale-view606
profile235
sale-application325
finance-policy235
report-export235
product-file224
cms-public404
notification314
audit404
campaign-import303
sale-transition123
recurring-skip123
order-return202
mfa022
affiliate-reward101

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.

Sinh từ ad83b0aea · 820 migration · PostgreSQL 17