operations/onboarding.md

Developer Onboarding Guide

Quick start guide để setup local development environment.

Prerequisites

  • Node.js 22.x LTS (dùng nvm)
  • Yarn 1.x (Classic)
  • Docker Desktop (PostgreSQL, Redis, MinIO)
  • Git
  • IDE: VS Code hoặc JetBrains (recommended)

1. Clone Repos

# Tạo workspace folder
mkdir booking-system && cd booking-system

# Clone tất cả repos
git clone git@github.com:novagoo/booking-docs.git .
git clone git@github.com:novagoo/booking-api.git
git clone git@github.com:novagoo/booking-web.git
git clone git@github.com:novagoo/booking-mobile.git

Sau khi clone, cấu trúc folder:

booking-system/
├── booking-api/          ← NestJS backend
├── booking-web/          ← Next.js web app
├── booking-mobile/       ← React Native Expo mobile app
├── docs/                 ← Shared documentation
├── docker-compose.yml    ← Local infra
├── .nvmrc                ← Node version
└── CLAUDE.md             ← AI context

2. Switch Node Version

# Tại root booking-system/
nvm use
# Output: Now using node v22.22.2

Nếu chưa có Node 22:

nvm install 22

3. Start Infrastructure

# Tại root booking-system/
docker compose up -d

Services sẽ chạy tại:

Service URL Credentials
PostgreSQL localhost:5442 booking / booking_secret
Redis localhost:6389 —
MinIO API localhost:9010 booking_minio / minio_secret_key
MinIO Console http://localhost:9011 booking_minio / minio_secret_key

Verify:

docker compose ps
# Tất cả services phải ở trạng thái "running (healthy)"

4. Setup booking-api

cd booking-api

# Install dependencies
yarn install

# Setup environment
cp .env.example .env
# Edit .env nếu cần thay đổi ports/credentials

# Generate Prisma client
yarn prisma generate

# Run database migrations
yarn prisma migrate dev

# Seed sample data (1 tenant, 2 staff, 4 services)
yarn seed

# Verify build
yarn build

# Start development server
yarn start:dev

API chạy tại: http://localhost:3010/api Swagger docs: http://localhost:3010/api/docs

Prisma v7 Notes

  • Generator: prisma-client-js (CJS compatible cho NestJS)
  • Import: from '@prisma/client' (cách truyền thống)
  • Adapter: @prisma/adapter-pg bắt buộc ở v7 — PrismaService inject via constructor
  • Datasource URL: config trong prisma.config.ts, không trong schema.prisma
  • Sau khi sửa schema: yarn prisma migrate dev → yarn prisma generate

Useful Commands

yarn build              # Build TypeScript
yarn start:dev          # Watch mode (tự restart khi sửa code)
yarn test               # Unit tests
yarn test:e2e           # E2E tests
yarn prisma studio      # Database GUI (browser)
yarn prisma migrate dev # Create/apply migration
yarn prisma generate    # Regenerate client after schema change

5. Setup booking-web

(Sẽ cập nhật khi init project)

cd booking-web
yarn install
cp .env.example .env
yarn codegen            # Generate API client from OpenAPI
yarn dev                # Start dev server

6. Setup booking-mobile

(Sẽ cập nhật khi init project)

cd booking-mobile
yarn install
cp .env.example .env
yarn codegen            # Generate API client from OpenAPI
npx expo start          # Start Expo dev server

7. Key Documentation

Doc Đọc khi
CLAUDE.md Bắt đầu — overview toàn bộ project
Product Brief Hiểu business context, target users, MVP scope
Architecture Tech stack, system design, module structure
PRD Feature requirements, user stories, acceptance criteria
API Design BẮT BUỘC — API conventions phải tuân thủ
Tech Versions Pinned versions, breaking change notes

8. Development Workflow

Branch Convention

feat/US-4.1-customer-online-booking
fix/booking-conflict-timezone
refactor/tenant-middleware

Commit Convention

feat: add availability endpoint
fix: booking conflict detection timezone issue
refactor: extract tenant middleware from controllers
docs: update API design with rate limiting
test: add booking service unit tests
chore: upgrade Prisma to 7.7

PR Flow

  1. Create branch từ main
  2. Implement với TDD (test first)
  3. Verify build: yarn build
  4. Verify tests: yarn test
  5. Create PR → review → merge

Coding Standards

  • Immutability — Không mutate objects, spread để tạo mới
  • Small files — 200-400 lines, max 800
  • Error handling — Mọi error phải handle, không swallow
  • API conventions — Xem API Design
  • Resource abstraction — Core code KHÔNG hardcode "staff"

9. Troubleshooting

Docker không start

# Check Docker Desktop đang chạy
docker ps

# Check logs
docker compose logs postgres
docker compose logs redis

# Reset volumes (WARNING: mất data)
docker compose down -v
docker compose up -d

Prisma migrate lỗi

# Reset database (WARNING: mất data)
yarn prisma migrate reset

# Nếu schema conflict
yarn prisma migrate dev --name fix_schema

Port conflict

Xem ports đang dùng:

lsof -i -P -n | grep LISTEN | grep -E '5442|6389|9010|9011|3010'

Thay đổi ports trong .env và docker-compose.yml nếu cần.

Node version mismatch

nvm use          # Đọc .nvmrc
node --version   # Verify 22.x