Chuyển tới nội dung chính

Môi trường phát triển local

Tài liệu này giải thích cách thiết lập và chạy backend khi phát triển. Nếu chỉ cần chạy thử nhanh, xem quick-start.md.

Các thành phần cần có​

Backend cần MongoDB và Redis đang chạy. Có hai cách:

CáchLệnhBackend chạy ở đâu
Chỉ chạy dịch vụ nền (khuyến nghị)npm run docker:devTrên máy, bằng npm run dev
Chạy cả backend trong Dockernpm run docker:fullTrong container, có hot reload

docker-compose.yml chỉ mở cổng của MongoDB và Redis trên 127.0.0.1, nên không truy cập được từ mạng ngoài. Dữ liệu lưu trong các volume Docker mongodb_data và redis_data.

Dịch vụImageCổng localKiểm tra sức khỏe
MongoDBmongo:7.0127.0.0.1:27017db.adminCommand('ping')
Redisredis:7-alpine127.0.0.1:6379redis-cli ping
Backend (profile full)build từ Dockerfile, target development127.0.0.1:${PORT:-8081}

Nguồn: docker-compose.yml.

Cấu hình môi trường​

Sao chép .env.example thành .env rồi điền giá trị. Danh sách biến bắt buộc nằm ở quick-start.md. Nhóm biến theo chức năng:

NhómVí dụ biếnGhi chú
Ứng dụngPORT, NODE_ENV, FE_URL, CORS_ORIGINS, TRUST_PROXY, SWAGGER_ENABLEDFE_URL được dùng làm danh sách CORS khi CORS_ORIGINS trống
MongoDBMONGO_URL, MONGO_INITDB_*MONGO_INITDB_* chỉ dùng cho container
RedisREDIS_HOST, REDIS_PORT, REDIS_PASSWORD, REDIS_QUEUE_DB, REDIS_CACHE_DB, REDIS_TTLHàng đợi dùng DB 0, cache và rate limit dùng DB 1 theo mặc định trong code
Xác thựcJWT_*, OTP_SECRET, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
EmailSMTP_HOST, SMTP_EMAIL, SMTP_PASSWORD
AIGEMINI_API_KEY, GROQ_API_KEY, GROQ_*_MODEL, AI_GROQ_*
Giám sátLOG_LEVEL, SENTRY_DSN, SENTRY_TRACES_SAMPLE_RATEKhông có SENTRY_DSN thì Sentry tắt
Dữ liệu mẫuEMAIL_ADMIN, INIT_PASSWORDTài khoản quản trị tạo bởi npm run seed

Các lệnh trong package.json​

LệnhTác dụngTrạng thái
npm run devChạy backend ở chế độ watch (nest start --watch)
npm run buildBiên dịch vào dist/
npm run start:prodChạy bản đã build (node dist/main)
npm run lintESLint, tự sửa lỗi (--fix)
npm testChạy toàn bộ unit test (Jest)
npm run test:covUnit test kèm coverage
npm run test:e2eChạy e2e với test/jest-e2e.json
npm run docker:dev, docker:full, docker:down, docker:logsQuản lý container
npm run seedNạp dữ liệu mẫu bằng src/databases/seeds/run-seed.tsGhi vào database
npm run dev:services, npm run dev:stopGọi ./scripts/dev-start.sh, ./scripts/dev-stop.shHỏng, xem bên dưới
npm run migrate:locationsGọi src/databases/migrations/run-location-standardization.tsHỏng, xem bên dưới

npm run lint có cờ --fix nên sẽ sửa file ngay trong working tree. Hãy commit hoặc stash thay đổi trước khi chạy nếu muốn xem riêng thay đổi do ESLint tạo ra.

Known Limitation: script dev bị thiếu​

Ba script trong package.json trỏ tới file không tồn tại trong repository:

ScriptFile được gọiTình trạng
dev:services./scripts/dev-start.shThư mục scripts/ không tồn tại. .gitignore có dòng /scripts nên thư mục này không được commit
dev:stop./scripts/dev-stop.shNhư trên
migrate:locationssrc/databases/migrations/run-location-standardization.tsThư mục src/databases/migrations/ rỗng

Hãy dùng npm run docker:dev và npm run docker:down thay cho dev:services và dev:stop. Việc sửa các script này nằm ngoài phạm vi dự án tài liệu và chưa được thực hiện.

Swagger​

Swagger UI ở http://localhost:8081/api. Swagger bật khi NODE_ENV khác production, hoặc khi đặt SWAGGER_ENABLED=true (main.ts). Xem thêm quy ước API ở 05-api (sẽ bổ sung ở Phase 3).

Kiểm thử​

  • Unit test nằm cạnh file nguồn, tên *.spec.ts. Chạy bằng npm test.
  • E2E cấu hình ở test/jest-e2e.json và dùng configureApp từ app.setup.ts để chạy cùng pipeline với production. Thư mục test/ hiện chưa được commit.

Chi tiết sẽ nằm ở 10-testing (Phase 4).

Quy ước khi phát triển​

Quy ước code, đặt tên và kiến trúc service nằm trong các tài liệu tham khảo của thư mục agent_docs/:

Trạng thái xác minh​

Hạng mụcTrạng thái
Danh sách script, cổng, image DockerĐã đối chiếu với package.json và docker-compose.yml
Ba script bị thiếu fileĐã xác minh bằng ls và git check-ignore
npx tsc --noEmitĐã chạy, không có lỗi (2026-11-05)
Chạy thực tế cùng MongoDB và RedisChưa xác minh: Docker daemon không chạy trên máy tạo tài liệu