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 + pinned versions, system design, module structure, breaking change notes
PRD Feature requirements, user stories, acceptance criteria
API Design BẮT BUỘC — API conventions phải tuân thủ

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