Local Development

วิธีรันระบบ WMS บนเครื่องของคุณ — ตั้งแต่ clone จนเปิด browser ดูได้

Prerequisites

Tool	Version	หมายเหตุ
Node.js	≥ 20.0.0	LTS แนะนำ; ใช้ nvm / volta จัดการ version
pnpm	≥ 9.0.0	npm install -g pnpm
Git	any recent	clone repo
PostgreSQL	16 (option A)	local install หรือ Docker
Supabase project	— (option B)	ฟรี tier ใช้ดี — free 500MB DB
Docker Desktop	optional	สำหรับ docker compose up

1. Clone + Install

git clone <repo-url> WMS
cd WMS
pnpm install                    # resolve + install ทุก workspace

pnpm install จะ symlink dependency เข้า node_modules/.pnpm/ (content-addressable) — เร็วและประหยัดพื้นที่

2. Environment Setup

Copy template:

cp .env.example .env.development

แก้ค่าใน .env.development:

# Database — เลือก 1 ใน 2 option

# Option A: local Docker postgres
DATABASE_URL="postgresql://wms_user:wms_dev_password@localhost:5432/wms"
DIRECT_URL="postgresql://wms_user:wms_dev_password@localhost:5432/wms"

# Option B: Supabase (แนะนำเพื่อ match production env)
DATABASE_URL="postgresql://postgres.[PROJECT_REF]:[PASSWORD]@aws-1-ap-northeast-2.pooler.supabase.com:6543/postgres?pgbouncer=true"
DIRECT_URL="postgresql://postgres.[PROJECT_REF]:[PASSWORD]@aws-1-ap-northeast-2.pooler.supabase.com:5432/postgres"

# Auth — REQUIRED
JWT_SECRET="<random-string-at-least-32-chars>"
JWT_ACCESS_TTL=900
JWT_REFRESH_TTL=604800

# App
APP_PORT=3000
APP_TIER=S
NODE_ENV=development

# CORS — frontend dev ports
CORS_ORIGIN="http://localhost:5173,http://localhost:5174"

# Cloudflare R2 (optional — ทิ้งว่างได้สำหรับ dev)
R2_ENDPOINT=""
R2_ACCESS_KEY_ID=""
R2_SECRET_ACCESS_KEY=""
R2_BUCKET_NAME="wms-files"

JWT_SECRET

ต้องอย่างน้อย 16 chars (Joi enforce) — app จะ refuse to start ถ้าไม่ตั้ง สร้างได้ด้วย: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

ฝั่ง frontend (apps/web/.env.development):

VITE_API_URL=http://localhost:3000

apps/admin/.env.development:

VITE_API_URL=http://localhost:3000

3. Database Setup

Option A — Local PostgreSQL (Docker)

docker compose up -d postgres      # start เฉพาะ postgres

Option B — Supabase

สร้าง project ใหม่ที่ https://supabase.com → copy connection string ลง .env.development

Apply schema + seed

pnpm db:generate                   # generate Prisma Client
pnpm db:push                       # apply schema.prisma → database
pnpm --filter @wms/api prisma:seed # seed default tenant + admin user

Seed credentials

หลัง seed → admin user จะมี email + password ตามที่กำหนดใน apps/api/prisma/seed.ts (เปลี่ยนใน production!) ใช้ <your-admin-email> / <your-admin-password> (อ่านจากไฟล์ seed)

4. Run Individual Apps

แต่ละ command รันจาก repo root (อย่า cd เข้าไป):

pnpm --filter @wms/api dev          # backend on port 3000
pnpm --filter @wms/web dev          # main app on port 5173
pnpm --filter @wms/admin dev        # admin portal on port 5174
pnpm --filter @wms/docs dev         # docs site on port 5175

หรือใช้ shortcuts จาก root package.json:

pnpm dev:api                        # = pnpm --filter @wms/api dev
pnpm dev:web                        # = pnpm --filter @wms/web dev
pnpm dev:admin
pnpm dev:docs
pnpm dev                            # parallel: api + web

5. Verify

URL	คาด
http://localhost:3000/api/v1/health/live	{"status":"ok"}
http://localhost:3000/api/v1/docs	Swagger UI
http://localhost:5173	Main WMS — login screen
http://localhost:5174	Admin Portal — login screen
http://localhost:5175	Docs site

Login ทั้ง 2 frontend ด้วย seed admin credentials

Common Workflow

เพิ่ม field ใหม่ใน schema

# 1. แก้ apps/api/prisma/schema.prisma
# 2. apply + regen
pnpm db:push                        # update DB
pnpm db:generate                    # update PrismaClient types

# 3. backend: เพิ่ม field ใน DTO + service
# 4. frontend: เพิ่ม column ใน form/table
# 5. test

เพิ่ม endpoint ใหม่

# 1. apps/api/src/modules/<feature>/
#    - แก้ controller.ts ใส่ @Get/@Post + DTO
#    - แก้ service.ts ใส่ logic + Prisma query
# 2. (frontend) เพิ่ม hook ใน useApi.ts หรือเรียก api.ts ตรง
# 3. (docs) update apps/docs/reference/integration-api.md ถ้าเป็น public API

Test

pnpm --filter @wms/api test         # Jest unit (auth.service.spec.ts, ...)
pnpm --filter @wms/api test:e2e     # Jest e2e
pnpm lint                            # recursive ESLint

Build production

pnpm --filter @wms/api build        # → apps/api/dist/
pnpm --filter @wms/web build        # → apps/web/dist/
pnpm --filter @wms/admin build      # → apps/admin/dist/
pnpm --filter @wms/docs build       # → apps/docs/.vitepress/dist/

ฝั่ง backend test build local:

cd apps/api
node dist/main                      # ลอง start production build

Docker Compose (all-in-one)

ถ้าไม่อยาก setup ทีละตัว:

docker compose up -d                # postgres + redis + api

จาก docker-compose.yml:

• postgres — port 5432, db wms, user wms_user/wms_dev_password
• redis — port 6379 (cache + queue — optional ใน tier S)
• api — port 3000, build from apps/api/Dockerfile

จากนั้นรัน frontend แยก:

pnpm --filter @wms/web dev
pnpm --filter @wms/admin dev

Useful Tools

# Prisma Studio — visual DB browser
pnpm --filter @wms/api prisma:studio        # → http://localhost:5555

# Check what changed in schema vs DB
cd apps/api && npx prisma migrate diff \
  --from-url "$DATABASE_URL" --to-schema-datamodel prisma/schema.prisma

Troubleshooting

ปัญหา	แก้
JWT_SECRET is REQUIRED	ตั้ง JWT_SECRET ใน .env.development
prisma generate fail	check DATABASE_URL + DIRECT_URL format
Port 3000/5173 ใช้แล้ว	lsof -i:3000 (mac/linux) หรือ `netstat -ano
CORS error ใน browser	เพิ่ม origin ลงใน CORS_ORIGIN env แล้ว restart api
bcrypt build fail บน Apple Silicon	pnpm rebuild bcrypt หรือ npm install bcrypt --build-from-source

ดู troubleshooting รวม: Troubleshooting Section