np-dms/lcbp3

Fork 0

Files

T

admin 2e50bcaa58

CI / CD Pipeline / build (push) Successful in 5m27s

Details

CI / CD Pipeline / deploy (push) Successful in 5m18s

Details

690522:0839 227 #02

2026-05-22 08:39:26 +07:00

20 KiB

Raw Permalink Blame History

// File: docs/development-setup-guide.md // Change Log // - 2026-05-22: แก้ไข IP Address ของเซิร์ฟเวอร์ AI จาก 192.168.10.100 เป็น 192.168.10.8 เพื่อให้ตรงกับสภาพแวดล้อมจริง

คู่มือการตั้งค่าและเริ่มต้น Development (Development Setup Guide)

LCBP3-DMS — Document Management System เอกสารนี้ครอบคลุมขั้นตอนการตั้งค่า environment สำหรับการพัฒนาทั้ง Backend และ Frontend

อัปเดตล่าสุด: 2026-05-20

Prerequisites

ระบบที่รองรับ

Operating System: Windows 10/11, macOS, Linux
RAM: ขั้นต่ำ 8GB (แนะนำ 16GB)
Disk Space: ขั้นต่ำ 10GB

เครื่องมือที่ต้องการ

Tool	Minimum Version	Recommended	หมายเหตุ
Node.js	>=24.0.0	24.15.0 LTS	ใช้ LTS version
pnpm	>=10.33.0	10.33.0	Package manager
Docker Desktop	>=24.x	Latest	สำหรับ services stack
Git	>=2.x	Latest	Version control

การติดตั้งเครื่องมือพื้นฐาน

1. ติดตั้ง Node.js

ดาวน์โหลดจาก: https://nodejs.org/

# ตรวจสอบ version หลังติดตั้ง
node -v
# ควรได้: v24.15.0 หรือสูงกว่า

2. ติดตั้ง pnpm

# ติดตั้ง pnpm ผ่าน npm
npm install -g pnpm

# หรือใช้ standalone installer
# ดูที่: https://pnpm.io/installation

# ตรวจสอบ version
pnpm -v
# ควรได้: 10.33.0 หรือสูงกว่า

3. ติดตั้ง Docker Desktop

ดาวน์โหลดจาก: https://www.docker.com/products/docker-desktop/

เลือก Docker Desktop for Windows/Mac/Linux
ติดตั้งและรัน Docker Desktop
ตรวจสอบว่า Docker ทำงานได้:

docker -v
# ควรได้: Docker version 24.x.x

docker ps
# ควรแสดง container list (ว่างหรือมี container)

4. ติดตั้ง Git

ดาวน์โหลดจาก: https://git-scm.com/

git --version
# ควรได้: git version 2.x.x

การตั้งค่า Docker Services Stack

Services Stack ประกอบด้วย:

MariaDB - Database
Redis - Cache & Queue
Elasticsearch - Search engine
Qdrant - Vector store (AI)
ClamAV - Virus scanning
phpMyAdmin - Database management tool

1. Clone Repository

git clone https://git.np-dms.work/np-dms/lcbp3.git
cd lcbp3

2. รัน Docker Services

cd backend
docker compose up -d

ตรวจสอบสถานะ services:

docker compose ps

ควรเห็น services ทั้งหมดในสถานะ "Up" หรือ "healthy"

Service	Port	Credentials
MariaDB	3306	user: `admin` / pass: `Center2025` / DB: `lcbp3_dev`
Redis	16379	password: `Center2025`
Elasticsearch	9200	No auth (dev mode)
Qdrant	6333	No auth
ClamAV	3310	No auth
phpMyAdmin	8080	user: `admin` / pass: `Center2025`

3. ตรวจสอบ Services Health

# ตรวจสอบ MariaDB
docker compose exec mariadb mysql -u admin -pCenter2025 -e "SHOW DATABASES;"

# ตรวจสอบ Redis
docker compose exec redis redis-cli -a Center2025 ping
# ควรได้: PONG

# ตรวจสอบ Elasticsearch
curl http://localhost:9200/_cluster/health

การตั้งค่า Environment Variables

Backend Environment Variables

สร้างไฟล์ .env ใน backend/:

cd backend
cp .env.example .env

แก้ไขค่าสำคัญใน backend/.env:

# Database
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=admin
DB_PASSWORD=Center2025
DB_DATABASE=lcbp3_dev

# Redis
REDIS_HOST=localhost
REDIS_PORT=16379
REDIS_PASSWORD=Center2025

# JWT - สร้างด้วยคำสั่ง: openssl rand -base64 32
JWT_SECRET=<ใส่ค่าที่สร้างจาก openssl>

# File Storage
UPLOAD_DEST=./uploads
MAX_FILE_SIZE=52428800

# ClamAV
CLAMAV_HOST=localhost
CLAMAV_PORT=3310

# AI Services (ถ้ามี AI Host)
AI_HOST_URL=http://192.168.10.8:11434
AI_QDRANT_URL=http://192.168.10.8:6333
OLLAMA_URL=http://192.168.10.8:11434
OLLAMA_MODEL_MAIN=gemma4:e4b
OLLAMA_MODEL_EMBED=nomic-embed-text

สร้าง JWT_SECRET:

openssl rand -base64 32

Frontend Environment Variables

สร้างไฟล์ .env.local ใน frontend/:

cd frontend
cp .env.example .env.local

แก้ไขค่าใน frontend/.env.local:

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:3001/api

# NextAuth Configuration - สร้างด้วย: openssl rand -base64 32
AUTH_SECRET=<ใส่ค่าที่สร้างจาก openssl>

สร้าง AUTH_SECRET:

openssl rand -base64 32

⚠️ สำคัญ: JWT_SECRET และ AUTH_SECRET ต้องเป็นค่าที่ต่างกัน

การติดตั้ง Dependencies

ติดตั้ง Dependencies ทั้งหมด (Monorepo)

จาก root directory ของ project:

cd lcbp3
pnpm install

คำสั่งนี้จะติดตั้ง dependencies สำหรับ:

Root workspace
Backend
Frontend

ติดตั้งเฉพาะ Backend

cd backend
pnpm install

ติดตั้งเฉพาะ Frontend

cd frontend
pnpm install

การตั้งค่า Database

1. Import Schema (ครั้งแรกเท่านั้น)

ถ้า database ว่างหรือเพิ่งสร้างใหม่:

# จาก root directory
mysql -u admin -pCenter2025 lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-01-drop.sql
mysql -u admin -pCenter2025 lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql
mysql -u admin -pCenter2025 lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-03-views-indexes.sql

2. Import Seed Data

mysql -u admin -pCenter2025 lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.8.0-seed-basic.sql
mysql -u admin -pCenter2025 lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.8.0-seed-permissions.sql

3. หรือใช้คำสั่ง Seed จาก Backend

cd backend
pnpm seed

4. ตรวจสอบ Database

ผ่าน phpMyAdmin: http://localhost:8080

หรือผ่าน command line:

mysql -u admin -pCenter2025 lcbp3_dev
mysql> SHOW TABLES;
mysql> SELECT COUNT(*) FROM users;
mysql> SELECT COUNT(*) FROM organizations;

การเริ่มต้น Backend Development

1. รัน Development Server

cd backend
pnpm run start:dev

หรือจาก root directory:

pnpm dev:backend

Backend จะรันที่: http://localhost:3001

2. เข้าถึง API Documentation

Swagger UI: http://localhost:3001/api/docs
API Root: http://localhost:3001/api

3. คำสั่งที่มีประโยชน์

# รันใน watch mode (auto-reload)
pnpm run start:dev

# Build สำหรับ production
pnpm run build

# รัน production build
pnpm run start:prod

# Run unit tests
pnpm run test

# Run e2e tests
pnpm run test:e2e

# Run test coverage
pnpm run test:cov

# Lint code
pnpm run lint

# Format code
pnpm run format

4. โครงสร้าง Backend

backend/
├── src/
│   ├── common/          # Shared utilities, guards, decorators
│   ├── config/          # Configuration module
│   ├── database/        # Database entities
│   ├── modules/         # Feature modules
│   │   ├── auth/
│   │   ├── user/
│   │   ├── project/
│   │   ├── correspondence/
│   │   ├── rfa/
│   │   ├── drawing/
│   │   ├── workflow-engine/
│   │   ├── ai/
│   │   └── ...
│   └── main.ts
├── test/                # Unit & E2E tests
├── uploads/             # File upload storage
└── package.json

5. การสร้าง Module ใหม่

ใช้ NestJS CLI:

cd backend
npx nest g module modules/<module-name>
npx nest g controller modules/<module-name>
npx nest g service modules/<module-name>

การเริ่มต้น Frontend Development

1. รัน Development Server

cd frontend
pnpm run dev

หรือจาก root directory:

pnpm dev:frontend

Frontend จะรันที่: http://localhost:3000

2. เข้าถึง Application

Frontend: http://localhost:3000
Login: ใช้ credentials จาก seed data

3. คำสั่งที่มีประโยชน์

# รัน development server
pnpm run dev

# Build สำหรับ production
pnpm run build

# Start production server
pnpm run start

# Run unit tests (Vitest)
pnpm run test

# Run E2E tests (Playwright)
pnpm run test:e2e

# Lint code
pnpm run lint

# Type check
pnpm run type-check

4. โครงสร้าง Frontend

frontend/
├── app/                 # Next.js App Router
│   ├── (admin)/         # Admin panel routes
│   ├── (auth)/          # Authentication pages
│   ├── (dashboard)/     # Main dashboard routes
│   └── api/             # API routes
├── components/          # React Components
├── lib/                 # Utilities & API clients
├── hooks/               # Custom React hooks
├── types/               # TypeScript definitions
├── public/              # Static assets
└── package.json

5. การสร้าง Page ใหม่

ใช้ Next.js App Router:

cd frontend/app/(dashboard)/<feature>
mkdir <feature>

สร้าง page.tsx และ layout.tsx ตามโครงสร้างที่มีอยู่

การทดสอบระบบ

1. ทดสอบ Backend API

# ทดสอบ health check
curl http://localhost:3001/api

# ทดสอบ login
curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@np-dms.work","password":"<password>"}'

2. ทดสอบ Frontend

เปิด browser ไปที่: http://localhost:3000

ลอง login ด้วย credentials จาก seed data
เข้าไปดูหน้า dashboard
ทดสอบสร้าง/แก้ไขข้อมูล

3. รัน Tests

Backend:

cd backend
pnpm run test           # Unit tests
pnpm run test:e2e       # E2E tests

Frontend:

cd frontend
pnpm run test           # Vitest unit tests
pnpm run test:e2e       # Playwright E2E tests

การ Debug และ Troubleshooting

ปัญหาที่พบบ่อย

1. Docker Services ไม่รัน

# ตรวจสอบ logs
docker compose logs

# รันใหม่
docker compose down
docker compose up -d

# ตรวจสอบ port conflicts
netstat -ano | findstr :3306

2. Database Connection Error

ตรวจสอบ:

Docker services รันอยู่หรือไม่
Credentials ใน .env ตรงกับ services หรือไม่
Database ถูกสร้างแล้วหรือยัง

# ทดสอบ connection
docker compose exec mariadb mysql -u admin -pCenter2025 lcbp3_dev

3. Backend ไม่รัน

ตรวจสอบ:

Dependencies ติดตั้งครบหรือไม่
Environment variables ตั้งค่าถูกต้องหรือไม่
Port 3001 ไม่ถูกใช้โดย process อื่น

# ตรวจสอบ port
netstat -ano | findstr :3001

# ลบ process ถ้าจำเป็น
taskkill /PID <PID> /F

4. Frontend ไม่รัน

ตรวจสอบ:

Dependencies ติดตั้งครบหรือไม่
NEXT_PUBLIC_API_URL ชี้ไปที่ backend ที่ถูกต้อง
Port 3000 ไม่ถูกใช้โดย process อื่น

5. TypeScript Errors

# Backend type check
cd backend
pnpm run build

# Frontend type check
cd frontend
pnpm run type-check

การ Debug ด้วย VS Code

Backend:

เปิด folder backend/ ใน VS Code
กด F5 หรือไปที่ Run and Debug
เลือก "Launch NestJS"

Frontend:

เปิด folder frontend/ ใน VS Code
กด F5 หรือไปที่ Run and Debug
เลือก "Launch Next.js"

Checklist ก่อนเริ่มทำงาน

Prerequisites

Node.js >=24.0.0 ติดตั้งแล้ว
pnpm >=10.33.0 ติดตั้งแล้ว
Docker Desktop ติดตั้งและรันอยู่
Git ติดตั้งแล้ว
Repository clone เรียบร้อย

Docker Services

docker compose up -d รันใน backend/ แล้ว
ทุก services อยู่ในสถานะ "Up" หรือ "healthy"
MariaDB สามารถเชื่อมต่อได้
Redis สามารถเชื่อมต่อได้
Elasticsearch สามารถเชื่อมต่อได้

Environment Variables

backend/.env สร้างแล้ว
JWT_SECRET ตั้งค่าแล้ว (ใช้ค่าที่ generate)
frontend/.env.local สร้างแล้ว
AUTH_SECRET ตั้งค่าแล้ว (ใช้ค่าที่ generate)
JWT_SECRET และ AUTH_SECRET เป็นค่าที่ต่างกัน
Database credentials ตรงกับ Docker services

Database

Schema import เรียบร้อย (ครั้งแรก)
Seed data import เรียบร้อย (ครั้งแรก)
ตรวจสอบว่า tables ถูกสร้างแล้ว
ตรวจสอบว่า seed data มีอยู่

Dependencies

pnpm install ที่ root สำเร็จ
Backend dependencies ติดตั้งครบ
Frontend dependencies ติดตั้งครบ

Development Servers

Backend รันที่ http://localhost:3001
Frontend รันที่ http://localhost:3000
Swagger UI เข้าถึงได้ที่ http://localhost:3001/api/docs
ไม่มี error ใน console logs

Testing

ทดสอบ login ผ่าน frontend ได้
ทดสอบ API endpoints ผ่าน Swagger ได้
Unit tests รันผ่าน (backend)
Unit tests รันผ่าน (frontend)

ทรัพยากรเพิ่มเติม

เอกสารประกอบ

Project README: README.md
Backend Guidelines: specs/05-Engineering-Guidelines/05-02-backend-guidelines.md
Frontend Guidelines: specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md
ADR-019 UUID Strategy: specs/06-Decision-Records/ADR-019-hybrid-identifier-strategy.md
ADR-007 Error Handling: specs/06-Decision-Records/ADR-007-error-handling-strategy.md

Tools & Documentation

NestJS Docs: https://docs.nestjs.com/
Next.js Docs: https://nextjs.org/docs
TypeORM Docs: https://typeorm.io/
React Hook Form: https://react-hook-form.com/
TanStack Query: https://tanstack.com/query/latest

Dev URLs

Service	URL
Frontend	http://localhost:3000
Backend API	http://localhost:3001/api
Swagger UI	http://localhost:3001/api/docs
phpMyAdmin	http://localhost:8080
Elasticsearch	http://localhost:9200
Qdrant Dashboard	http://localhost:6333/dashboard

การปิดระบบ Development

# หยุด backend และ frontend (Ctrl+C)

# หยุด Docker services
cd backend
docker compose down

# หรือหยุดและลบ volumes (ข้อมูล DB จะหาย)
docker compose down -v

คำถามที่พบบ่อย (FAQ)

Q: ต้องรัน Docker services ทุกครั้งหรือไม่?

A: ใช่ ต้องรัน docker compose up -d ใน backend/ ก่อนเริ่ม development ทุกครั้ง

Q: สามารถรันเฉพาะ backend หรือ frontend ได้ไหม?

A: ได้ ใช้คำสั่ง pnpm dev:backend หรือ pnpm dev:frontend จาก root directory

Q: JWT_SECRET และ AUTH_SECRET ต้องเหมือนกันหรือไม่?

A: ไม่ ต้องเป็นค่าที่ต่างกันเพื่อความปลอดภัย

Q: ต้อง import schema ทุกครั้งหรือไม่?

A: ไม่ ต้อง import เฉพาะครั้งแรกเท่านั้น หรือเมื่อมีการเปลี่ยนแปลง schema

Q: ถ้าต้องการ reset database ทั้งหมด?

A: รัน docker compose down -v แล้ว import schema ใหม่

ข้อควรระวัง

⚠️ Security:

ห้าม commit .env หรือ .env.local ไฟล์
ห้ามใช้ค่า secrets จริงใน production
เปลี่ยน password สำหรับ production environment

⚠️ Data Integrity:

อย่าแก้ไข database schema โดยตรงโดยไม่ทำตาม ADR-009
ใช้ seed data สำหรับ development เท่านั้น

⚠️ Performance:

ปิด Docker services เมื่อไม่ใช้งานเพื่อประหยัด resources
ใช้ watch mode สำหรับ development เท่านั้น (ไม่ใช่ production)

สำหรับคำถามเพิ่มเติม หรือปัญหาที่พบ กรุณาติดต่อทีม Development หรือสร้าง Issue ใน Gitea

20 KiB Raw Permalink Blame History

คู่มือการตั้งค่าและเริ่มต้น Development (Development Setup Guide)

📋 Table of Contents

Prerequisites

ระบบที่รองรับ

เครื่องมือที่ต้องการ

การติดตั้งเครื่องมือพื้นฐาน

1. ติดตั้ง Node.js

2. ติดตั้ง pnpm

3. ติดตั้ง Docker Desktop

4. ติดตั้ง Git

การตั้งค่า Docker Services Stack

1. Clone Repository

2. รัน Docker Services

3. ตรวจสอบ Services Health

การตั้งค่า Environment Variables

Backend Environment Variables

Frontend Environment Variables

การติดตั้ง Dependencies

ติดตั้ง Dependencies ทั้งหมด (Monorepo)

ติดตั้งเฉพาะ Backend

ติดตั้งเฉพาะ Frontend

การตั้งค่า Database

1. Import Schema (ครั้งแรกเท่านั้น)

2. Import Seed Data

3. หรือใช้คำสั่ง Seed จาก Backend

4. ตรวจสอบ Database

การเริ่มต้น Backend Development

1. รัน Development Server

2. เข้าถึง API Documentation

3. คำสั่งที่มีประโยชน์

4. โครงสร้าง Backend

5. การสร้าง Module ใหม่

การเริ่มต้น Frontend Development

1. รัน Development Server

2. เข้าถึง Application

3. คำสั่งที่มีประโยชน์

4. โครงสร้าง Frontend

5. การสร้าง Page ใหม่

การทดสอบระบบ

1. ทดสอบ Backend API

2. ทดสอบ Frontend

3. รัน Tests

การ Debug และ Troubleshooting

ปัญหาที่พบบ่อย

1. Docker Services ไม่รัน

2. Database Connection Error

3. Backend ไม่รัน

4. Frontend ไม่รัน

5. TypeScript Errors

การ Debug ด้วย VS Code

Checklist ก่อนเริ่มทำงาน

Prerequisites

Docker Services

Environment Variables

Database

Dependencies

Development Servers

Testing

ทรัพยากรเพิ่มเติม

เอกสารประกอบ

Tools & Documentation

Dev URLs

การปิดระบบ Development

คำถามที่พบบ่อย (FAQ)

Q: ต้องรัน Docker services ทุกครั้งหรือไม่?

Q: สามารถรันเฉพาะ backend หรือ frontend ได้ไหม?

Q: JWT_SECRET และ AUTH_SECRET ต้องเหมือนกันหรือไม่?

Q: ต้อง import schema ทุกครั้งหรือไม่?

Q: ถ้าต้องการ reset database ทั้งหมด?

ข้อควรระวัง

20 KiB

Raw Permalink Blame History