Giao diện
Chạy hệ thống tại máy
Không dùng Docker ở bất cứ đâu. Đây là quyết định của dự án, không phải sở thích: Edge Function là server Deno thường nên chạy trực tiếp được, và PostgreSQL chạy native nhanh hơn nhiều so với qua Docker trên máy phát triển.
Phiên bản công cụ
Đặt đúng thứ tự trong PATH, nếu không sẽ gặp lỗi giả:
| Công cụ | Phiên bản |
|---|---|
| Node | 20 |
| pnpm | 9.15.4 |
| Deno | 2.x |
| Flutter | 3.47.8 qua FVM (chạy fvm use trong code/ một lần) |
| PostgreSQL | 17, native, cổng 5433 |
Node mới hơn hoặc Flutter global cũ hơn sẽ làm test đỏ mà không phải do code.
Backend
bash
cd code/apps/api
deno task dev # graphql -> http://localhost:8000/graphql
deno task dev:auth # auth -> http://localhost:8001deno run, không phải deno serve: entrypoint dùng Deno.serve() giống mọi Edge Function của Supabase, còn deno serve đòi export default { fetch }.
Không có gateway /functions/v1/* ở local — mỗi function phục vụ trên cổng riêng. Đó là đánh đổi đã chấp nhận.
Cần env/.env.local với PI_API_DB_URL (login pi_api), PI_AUTH_DB_URL (login pi_auth) và một cặp khoá ES256 sinh tại máy:
bash
deno run scripts/operator/generate-signing-key.ts \
--kid local-<yyyy-mm> --issuer http://127.0.0.1:8001Từ 2026-10-10 toàn bộ luồng chạy local, kể cả đăng nhập — không gọi project cloud nào. Mã OTP lấy từ provider giả.
Database
bash
cd code/apps/api
./scripts/db-reset.sh # drop -> create -> stubs -> migration -> seedTest không bao giờ chạy trên pideal_dev: mỗi bộ test tạo scratch DB riêng, copy từ một template DB đã áp đủ migration. Template được dựng một lần rồi dùng lại, nên scratch DB mới mất khoảng một giây thay vì chạy lại 820 file.
Nếu máy dùng chung với checkout khác, đặt PI_SCRATCH_TEMPLATE=0 để không xoá template mà checkout kia đang dùng.
Web
bash
# từ code/
pnpm install
pnpm exec nx serve web-admin # http://localhost:8080
pnpm exec nx serve web-storybook # http://localhost:6006
pnpm exec nx serve web-document # tài liệu nàyHoặc từ gốc repo: pnpm admin:local, pnpm dev:local (api + web-admin).
Mobile
bash
# từ code/
flutter pub get # cả workspace, một lockfile
pnpm exec nx run app-user:run # local
pnpm exec nx run app-user:run --configuration=mock # không cần backend, không cần file envChế độ mock là đường thoát khi backend chưa sẵn sàng: mọi operation GraphQL và mọi function JSON đều trả lời từ fixture, nhưng toàn bộ đường parse dữ liệu thật vẫn chạy.
Kiểm tra trước khi mở pull request
bash
# từ code/apps/api
deno task check # typecheck
deno task test # unit test
deno task schema:export # sau khi đổi SDL
# từ code/
pnpm exec nx typecheck <project>
pnpm exec nx test <project> # vitest; không có jest, không có playwright
pnpm exec nx check-coverage web-storybook
pnpm exec nx run-many -t analyze test -p tag:scope:mobile
pnpm exec nx check-coverage app-widgetbook
node scripts/auth-gates/run-all.mjs
pnpm exec nx run web-document:docgen-checkĐừng tự nghĩ ra lệnh test. Danh sách trên là đủ; lệnh không có trong đây thì không tồn tại trong repo này.
Nguồn: CLAUDE.md, docs/technical/02-environment.md §6, docs/db/README.md. Trang viết tay — xem mức độ tin cậy.