Skip to content

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
Node20
pnpm9.15.4
Deno2.x
Flutter3.47.8 qua FVM (chạy fvm use trong code/ một lần)
PostgreSQL17, 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:8001

deno 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:8001

Từ 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 -> seed

Test 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ày

Hoặ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 env

Chế độ 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.

Sinh từ ad83b0aea · 820 migration · PostgreSQL 17