Giao diện
Thêm một API GraphQL
Trình tự này không phải gợi ý — bỏ một bước thì test đỏ hoặc review trả về.
1. Hợp đồng trước
Thêm SDL vào graphql/domains/<domain>/schema.ts. Tên operation phải theo đúng danh mục hợp đồng (docs/contracts/api-contract-catalog.md) — không đặt tên tự do, không tạo alias.
Description của field là nơi ghi quyền ("Requires order.read"), và chính description đó được tài liệu lấy làm nội dung — nên viết nó cho người đọc, không viết cho mình.
bash
cd code/apps/api && deno task schema:export # ghi lại graphql/schema.graphqlĐăng ký domain vào graphql/compose-types.ts (danh sách SDL) và graphql/compose.ts (danh sách resolver). Không sửa index.ts.
2. Resolver gọi đúng thứ tự
resolver
→ requirePermission() guard, đọc từ ma trận quyền
→ parseArgs() sanitize + Zod, đúng MỘT lần, SAU guard
→ service quy tắc nghiệp vụ
→ repository SQLHai lỗi hay gặp:
- Gọi
safeParsetrực tiếp thay vìparseArgs(). Sai:parseArgslà chỗ verdict của bước sanitize được lấy; gọi thẳng Zod là bỏ qua sanitize. - Đặt sanitize trước guard. Sai: người không có quyền phải nhận
unauthorized/forbidden, không được thấy chi tiết chính sách lọc nội dung.
3. Profile sanitize
Domain viết graphql/domains/<d>/sanitize-profile.ts:
incho mỗi operation và mỗi leaf của input;outcho mỗi output type, đúng kind khớp với field;refcho String mà bước này không quét.
Rồi thêm đúng một dòng vào _shared/sanitize/profiles/index.ts.
Thiếu profile thì sanitize-registry-audit_test.ts (duyệt cả đồ thị từ SDL) và sql-sink-gate_test.ts làm deno task 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.
4. Mutation thì thêm audit
Mọi mutation phải có một mục trong domains/audit/registry.ts, nếu không deno task test đỏ. Thao tác nhạy cảm gọi thêm auditNote() để ghi before/after (được mask trước khi insert).
5. Quyền
Thêm luật vào _shared/contracts/permission-matrix.json — đây là file Edge Function nạp lúc chạy, nên nó là nguồn thật của phân quyền. → Ma trận quyền
Mặc định là từ chối: root field không có spec thì luôn forbidden.
6. Sinh lại client
bash
# web
pnpm --filter @pi/web-services codegen
# mobile
pnpm exec nx gen app-servicesCả hai đọc cùng một file SDL đã export, không đọc server đang chạy. File sinh ra được commit.
7. Test đúng một lần, ở tầng thấp nhất
Một hành vi — một test, đặt ở tầng thấp nhất chứng minh được nó. Nếu đã có test cho hành vi gần giống thì mở rộng test đó, đừng thêm một test song song ở tầng khác.
8. Tài liệu tự theo
Không phải viết tay gì cho tài liệu API: chạy lại bộ sinh là có.
bash
pnpm exec nx run web-document:docgenOperation mới sẽ xuất hiện ở Tra cứu API và trên trang module tương ứng, kèm tham số, kiểu trả về và quyền lấy từ SDL.
Nếu operation không hiện ra, nghĩa là bộ sinh không gán được nó về domain nào — trang tổng quan API sẽ cảnh báo, và đó là dấu hiệu SDL khai ở chỗ bất thường.
Nguồn: docs/technical/21-add-new-api.md, docs/contracts/api-conventions.md, docs/technical/22-plans-evidence-tests.md, CLAUDE.md. Trang viết tay — xem mức độ tin cậy.