admin/pos-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs): Update getting started and local development guides with new prerequisites and improved flow

Browse Source 
- Enhanced Node.js and PNPM version recommendations in the getting started guide.
- Added a color palette section with Mermaid diagrams for better visual representation.
- Improved the workflow steps in the local development guide for clarity and consistency.
- Updated Vietnamese documentation to reflect changes in the English version.
- Refactored database migration and seeding scripts for better error handling and user feedback.
This commit is contained in:
Ho Ngoc Hai
2026-01-08 15:37:25 +07:00
parent 489adbd314
commit 510e2306cd
7 changed files with 310 additions and 160 deletions
Download Patch File Download Diff File Expand all files Collapse all files

97
docs/en/guides/getting-started.md
View File

@@ -16,20 +16,20 @@
Before starting, ensure you have the following installed:
* **Node.js**: v20.0.0 or higher
* **Node.js**: v20.0.0 or higher (recommended v22+ or v25+)
```bash
node -v
# v20.10.0
# v25.2.1
```
* **PNPM**: v8.0.0 or higher (we use pnpm workspaces)
* **PNPM**: v8.15.0 or higher (we use pnpm workspaces)
```bash
pnpm -v
# 8.12.0
# 8.15.0
```
* **Docker & Docker Compose**: For local infrastructure
* **Docker & Docker Compose**: v24.0.0 or higher for local infrastructure
```bash
docker -v
# Docker version 24.0.0
# Docker version 29.1.3, build f52814d
```
* **Git**: For version control
* **Neon Account**: Serverless PostgreSQL (https://neon.tech)
@@ -49,9 +49,35 @@ graph TD
IAM --> Redis[(Redis Cache)]
IAM --> Kafka[Kafka Events]
style Traefik fill:#e1f5ff
style DB fill:#f0e1ff
style Redis fill:#fff4e1
style Client fill:#7F8C8D,color:#fff
style Traefik fill:#2980B9,color:#fff
style IAM fill:#27AE60,color:#fff
style Template fill:#E67E22,color:#fff
style DB fill:#8E44AD,color:#fff
style Redis fill:#F39C12,color:#fff
style Kafka fill:#3498DB,color:#fff
```
### Color Palette
```mermaid
graph LR
A["Primary<br/>#2980B9"] --> B["Data/Cache<br/>#F39C12"]
B --> C["Success<br/>#27AE60"]
C --> D["Warning<br/>#E67E22"]
D --> E["Error<br/>#C0392B"]
E --> F["Processing<br/>#8E44AD"]
F --> G["Info<br/>#3498DB"]
G --> H["Neutral<br/>#7F8C8D"]
style A fill:#2980B9,color:#fff
style B fill:#F39C12,color:#fff
style C fill:#27AE60,color:#fff
style D fill:#E67E22,color:#fff
style E fill:#C0392B,color:#fff
style F fill:#8E44AD,color:#fff
style G fill:#3498DB,color:#fff
style H fill:#7F8C8D,color:#fff
```
## Project Structure
@@ -60,23 +86,42 @@ The repository follows a monorepo structure:
```
Base/
├── apps/ # Frontend applications
│ ├── web-client/ # Next.js web application
│ └── mobile-client/ # Flutter mobile application
├── services/ # Backend microservices
│ ├── iam-service/ # Authentication & Authorization
│ └── _template/ # Template for new services
├── packages/ # Shared libraries
│ ├── logger/ # Structured logging
│ ├── types/ # Shared TypeScript types
│ └── http-client/ # Internal HTTP client
├── infra/ # Infrastructure configuration
│ ├── traefik/ # API Gateway config
│ └── databases/ # Database setup scripts
├── deployments/ # Deployment configurations
│ ├── local/ # Docker Compose for dev
│ └── k8s/ # Kubernetes manifests
└── docs/ # Documentation
├── apps/ # Frontend applications
│ ├── app-admin/ # Admin dashboard application
│ ├── app-client/ # Client mobile application (Flutter)
│ ├── web-client/ # Next.js web application
│ └── web-docs/ # Documentation website (Next.js)
├── services/ # Backend microservices
│ ├── iam-service/ # Authentication & Authorization service
│ └── _template/ # Template for new services
├── packages/ # Shared libraries
│ ├── auth-sdk/ # Authentication SDK
│ ├── config/ # Shared configuration utilities
│ ├── http-client/ # Internal HTTP client
│ ├── logger/ # Structured logging (@goodgo/logger)
│ ├── tracing/ # OpenTelemetry tracing
│ └── types/ # Shared TypeScript types
├── infra/ # Infrastructure configuration
│ ├── databases/ # Database setup scripts
│ ├── docker/ # Docker configurations
│ ├── observability/ # Prometheus, Grafana, Loki configs
│ ├── secrets/ # Secrets management templates
│ └── traefik/ # API Gateway configuration
├── deployments/ # Deployment configurations
│ ├── local/ # Docker Compose for development
│ ├── staging/ # Staging environment configs
│ └── production/ # Production Kubernetes manifests
├── scripts/ # Automation scripts
│ ├── build/ # Build scripts
│ ├── db/ # Database utilities
│ ├── deploy/ # Deployment scripts
│ ├── dev/ # Development helpers
│ ├── observability/ # Monitoring setup scripts
│ ├── setup/ # Initial setup scripts
│ └── utils/ # Utility scripts
└── docs/ # Documentation
├── en/ # English documentation
└── vi/ # Vietnamese documentation
```
## Installation & Setup

35
docs/en/guides/local-development.md
View File

@@ -13,25 +13,32 @@
```mermaid
graph TD
Start([Start]) --> Prerequisites[1. System Prerequisites]
Prerequisites --> Clone[2. Clone & Install]
Clone --> Env[3. Configure Environment<br/>(Shared & Service-Specific)]
Env --> DB[4. Setup Database<br/>(Migrate & Seed)]
DB --> Run[5. Run Project<br/>(Native/Docker/Hybrid)]
Run --> Dev[6. Development Loop<br/>(Watch Mode)]
Dev --> Test[7. Testing & Verify]
Prerequisites --> Clone["2. Clone and Install"]
Clone --> Env["3. Configure Environment - Shared and Service-Specific"]
Env --> DB["4. Setup Database - Migrate and Seed"]
DB --> Run["5. Run Project - Native/Docker/Hybrid"]
Run --> Dev["6. Development Loop - Watch Mode"]
Dev --> Test["7. Testing and Verify"]
Test --> End([Complete])
subgraph "Run Modes"
Run --> Mode1[Mode 1: Native (Fastest)]
Run --> Mode2[Mode 2: Hybrid (Flexible)]
Run --> Mode3[Mode 3: Full Docker (Production-like)]
Run --> Mode1[Mode 1: Native - Fastest]
Run --> Mode2[Mode 2: Hybrid - Flexible]
Run --> Mode3[Mode 3: Full Docker - Production-like]
end
style Start fill:#d4edda,stroke:#28a745,stroke-width:2px
style End fill:#d4edda,stroke:#28a745,stroke-width:2px
style Env fill:#fff3cd,stroke:#ffc107
style DB fill:#fff3cd,stroke:#ffc107
style Run fill:#cce5ff,stroke:#007bff
style Start fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
style End fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
style Prerequisites fill:#7F8C8D,color:#fff
style Clone fill:#7F8C8D,color:#fff
style Env fill:#E67E22,color:#fff
style DB fill:#E67E22,color:#fff
style Run fill:#2980B9,color:#fff
style Dev fill:#2980B9,color:#fff
style Test fill:#3498DB,color:#fff
style Mode1 fill:#8E44AD,color:#fff
style Mode2 fill:#8E44AD,color:#fff
style Mode3 fill:#8E44AD,color:#fff
```
## Overview

14
docs/vi/guides/getting-started.md
View File

@@ -62,13 +62,13 @@ graph TD
```mermaid
graph LR
A["Primary<br/>#2980B9"] --> B["Data/Cache<br/>#F39C12"]
B --> C["Success<br/>#27AE60"]
C --> D["Warning<br/>#E67E22"]
D --> E["Error<br/>#C0392B"]
E --> F["Processing<br/>#8E44AD"]
F --> G["Info<br/>#3498DB"]
G --> H["Neutral<br/>#7F8C8D"]
A["Primary #2980B9"] --> B["Data/Cache #F39C12"]
B --> C["Success #27AE60"]
C --> D["Warning #E67E22"]
D --> E["Error #C0392B"]
E --> F["Processing #8E44AD"]
F --> G["Info #3498DB"]
G --> H["Neutral #7F8C8D"]
style A fill:#2980B9,color:#fff
style B fill:#F39C12,color:#fff

60
docs/vi/guides/local-development.md
View File

@@ -1,37 +1,40 @@
# Hướng Dẫn Phát Triển Local (Local Development)
> **EN**: Local Development Guide
>
> **VI**: Hướng dẫn phát triển cục bộ
>Hướng dẫn phát triển cục bộ
**Cập nhật**: 2026-01-05
**Độ khó**: Trung bình (Intermediate)
**Thời gian thiết lập**: 15-30 phút
## Workflow / Quy Trình
```mermaid
graph TD
Start([Bắt đầu / Start]) --> Prerequisites[1. Yêu cầu Hệ thống<br/>Prerequisites]
Prerequisites --> Clone[2. Clone & Install]
Clone --> Env[3. Cấu hình Environment<br/>(Shared & Service-Specific)]
Env --> DB[4. Setup Database<br/>(Migrate & Seed)]
DB --> Run[5. Chạy Dự án<br/>(Native/Docker/Hybrid)]
Run --> Dev[6. Development Loop<br/>(Watch Mode)]
Dev --> Test[7. Testing & Verify]
Start([Bắt đầu / Start]) --> Prerequisites["1. Yêu cầu Hệ thống - Prerequisites"]
Prerequisites --> Clone["2. Clone và Install"]
Clone --> Env["3. Cấu hình Environment - Shared và Service-Specific"]
Env --> DB["4. Setup Database - Migrate và Seed"]
DB --> Run["5. Chạy Dự án - Native/Docker/Hybrid"]
Run --> Dev["6. Development Loop - Watch Mode"]
Dev --> Test["7. Testing và Verify"]
Test --> End([Hoàn tất / Complete])
subgraph "Các Chế độ Chạy / Run Modes"
Run --> Mode1[Cách 1: Native (Nhanh nhất)]
Run --> Mode2[Cách 2: Hybrid (Linh hoạt)]
Run --> Mode3[Cách 3: Full Docker (Production-like)]
Run --> Mode1["Cách 1: Native - Nhanh nhất"]
Run --> Mode2["Cách 2: Hybrid - Linh hoạt"]
Run --> Mode3["Cách 3: Full Docker - Production-like"]
end
style Start fill:#d4edda,stroke:#28a745,stroke-width:2px
style End fill:#d4edda,stroke:#28a745,stroke-width:2px
style Env fill:#fff3cd,stroke:#ffc107
style DB fill:#fff3cd,stroke:#ffc107
style Run fill:#cce5ff,stroke:#007bff
style Start fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
style End fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
style Prerequisites fill:#7F8C8D,color:#fff
style Clone fill:#7F8C8D,color:#fff
style Env fill:#E67E22,color:#fff
style DB fill:#E67E22,color:#fff
style Run fill:#2980B9,color:#fff
style Dev fill:#2980B9,color:#fff
style Test fill:#3498DB,color:#fff
style Mode1 fill:#8E44AD,color:#fff
style Mode2 fill:#8E44AD,color:#fff
style Mode3 fill:#8E44AD,color:#fff
```
## Tổng Quan / Overview
@@ -53,12 +56,10 @@ Trước khi bắt đầu, đảm bảo máy của bạn đã cài đặt các c
### 2.1 Clone và Cài Đặt Dependencies
```bash
# EN: Clone the repository
# VI: Clone repository về máy
git clone <repository-url>
cd Base
# EN: Install dependencies using pnpm
# VI: Cài đặt các thư viện phụ thuộc bằng pnpm
pnpm install
```
@@ -68,7 +69,6 @@ pnpm install
Dự án có script tự động hóa các bước khởi tạo cơ bản:
```bash
# EN: Run initialization script
# VI: Chạy script khởi tạo
./scripts/setup/init-project.sh
```
@@ -88,7 +88,6 @@ File: `deployments/local/.env.local`
Chứa các biến dùng chung cho toàn bộ hệ thống (JWT, Redis, Logging).
```bash
# EN: Create shared env file from example
# VI: Tạo file môi trường chung từ file mẫu
cp deployments/local/env.local.example deployments/local/.env.local
```
@@ -98,7 +97,6 @@ cp deployments/local/env.local.example deployments/local/.env.local
Mỗi service (ví dụ `iam-service`) cần file `.env.local` riêng chứa thông tin đặc thù như Database URL và Port.
```bash
# EN: Create service-specific env file
# VI: Tạo file môi trường riêng cho service
cp services/iam-service/env.local.example services/iam-service/.env.local
```
@@ -124,11 +122,9 @@ REDIS_HOST=localhost
Sau khi cấu hình `DATABASE_URL`, bạn cần đồng bộ schema và tạo dữ liệu mẫu.
```bash
# EN: Run migrations for iam-service
# VI: Chạy migration cho iam-service
./scripts/db/migrate.sh iam-service dev
# EN: Seed initial data (optional)
# VI: Tạo dữ liệu mẫu (tùy chọn)
./scripts/db/seed.sh iam-service
```
@@ -143,7 +139,6 @@ Chạy trực tiếp trên máy host. Tốc độ cao nhất, hot-reload nhanh n
1. **Khởi động Hạ tầng (Infrastructure)**:
```bash
# EN: Start Redis and Traefik in Docker background
# VI: Khởi động Redis và Traefik chạy ngầm bằng Docker
cd deployments/local
docker-compose up -d redis traefik
@@ -152,7 +147,6 @@ Chạy trực tiếp trên máy host. Tốc độ cao nhất, hot-reload nhanh n
2. **Chạy Service**:
```bash
# EN: Start iam-service in watch mode
# VI: Chạy iam-service ở chế độ watch
pnpm --filter @goodgo/iam-service dev
```
@@ -162,11 +156,9 @@ Chạy trực tiếp trên máy host. Tốc độ cao nhất, hot-reload nhanh n
Dùng khi bạn cần chạy nhiều service phụ trợ trong Docker, nhưng muốn dev trực tiếp 1 service chính.
```bash
# EN: Start dependent services in Docker
# VI: Chạy các service phụ thuộc trong Docker
docker-compose -f deployments/local/docker-compose.yml up -d user-service payment-service
# EN: Run the service you are working on natively
# VI: Chạy service bạn đang làm việc trực tiếp trên máy
pnpm --filter @goodgo/iam-service dev
```
@@ -176,7 +168,6 @@ pnpm --filter @goodgo/iam-service dev
Chạy toàn bộ hệ thống trong Docker. Tốt cho việc kiểm tra tích hợp (Integration Test) nhưng không có hot-reload.
```bash
# EN: Start everything with Docker Compose
# VI: Chạy tất cả bằng Docker Compose
cd deployments/local
docker-compose up -d
@@ -197,11 +188,9 @@ Sau khi khởi động, bạn có thể truy cập các điểm cuối sau:
### Kiểm tra Health Check
```bash
# EN: Check liveness
# VI: Kiểm tra liveness
curl http://localhost:5001/health/live
# EN: Check readiness
# VI: Kiểm tra readiness
curl http://localhost:5001/health/ready
```
@@ -214,11 +203,9 @@ curl http://localhost:5001/health/ready
**Giải pháp**:
```bash
# EN: Find process using port 5001
# VI: Tìm process đang chiếm port 5001
lsof -i :5001
# EN: Kill the process
# VI: Tắt process đó
kill -9 <PID>
```
@@ -238,7 +225,6 @@ kill -9 <PID>
**Giải pháp**:
```bash
# EN: Re-install dependencies and build packages
# VI: Cài lại dependencies và build lại packages
pnpm install
pnpm build