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

feat(docs): Enhance deployment and development guides with improved clarity and structure

Browse Source 
- Updated Mermaid diagrams in the deployment and development guides for better visual representation and consistency.
- Improved formatting and clarity in the Kubernetes local deployment and IAM migration guides, including detailed workflows and troubleshooting sections.
- Enhanced the Vietnamese documentation to align with the English version, ensuring consistency across guides.
- Added quick tips and common issues sections to facilitate user navigation and understanding.
This commit is contained in:
Ho Ngoc Hai
2026-01-08 17:10:06 +07:00
parent 70d90d36e0
commit 9ba4a478ee
22 changed files with 3030 additions and 3030 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/en/guides/development.md
View File

@@ -20,22 +20,22 @@ We follow a strict monorepo structure managed by PNPM Workspaces.
```
Base/
├── apps/ # Frontend applications
│ ├── web-client/ # Next.js 14+ (App Router)
│ └── mobile-client/ # Flutter
├── services/ # Backend microservices
│ ├── _template/ # Template for new services
│ ├── iam-service/ # Identity & Access Management
│ └── ...
├── packages/ # Shared libraries
│ ├── logger/ # Structured logging (Winston)
│ ├── types/ # Shared DTOs & Interfaces
│ ├── http-client/ # Internal Service Client
│ └── tracing/ # OpenTelemetry configuration
├── infra/ # Infrastructure-as-Code
│ ├── traefik/ # API Gateway
│ └── databases/ # Database setup scripts
└── docs/ # Documentation (EN & VI)
apps/ # Frontend applications
web-client/ # Next.js 14+ (App Router)
mobile-client/ # Flutter
services/ # Backend microservices
_template/ # Template for new services
iam-service/ # Identity & Access Management
...
packages/ # Shared libraries
logger/ # Structured logging (Winston)
types/ # Shared DTOs & Interfaces
http-client/ # Internal Service Client
tracing/ # OpenTelemetry configuration
infra/ # Infrastructure-as-Code
traefik/ # API Gateway
databases/ # Database setup scripts
docs/ # Documentation (EN & VI)
```
---

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

@@ -62,13 +62,13 @@ graph TD
```mermaid
graph LR
A["🔵 Primary<br/>#1A5490"] --> B["🟠 Data/Cache<br/>#CA6F1E"]
B --> C["🟢 Success<br/>#1E8449"]
C --> D["🟡 Warning<br/>#BA6610"]
D --> E["🔴 Error<br/>#922B21"]
E --> F["🟣 Processing<br/>#6C3483"]
F --> G["🔷 Info<br/>#21618C"]
G --> H["⚫ Neutral<br/>#34495E"]
A[" Primary<br/>#1A5490"] --> B[" Data/Cache<br/>#CA6F1E"]
B --> C[" Success<br/>#1E8449"]
C --> D[" Warning<br/>#BA6610"]
D --> E[" Error<br/>#922B21"]
E --> F[" Processing<br/>#6C3483"]
F --> G[" Info<br/>#21618C"]
G --> H[" Neutral<br/>#34495E"]
style A fill:#1A5490,stroke:#154360,color:#ECF0F1
style B fill:#CA6F1E,stroke:#A04000,color:#ECF0F1
@@ -86,42 +86,42 @@ The repository follows a monorepo structure:
```
Base/
├── 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
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

52
docs/en/guides/iam-migration.md
View File

@@ -10,18 +10,18 @@ IAM Service is an extended version of Auth Service with additional features for
```mermaid
graph LR
Start([Start Migration]) --> Backup[📦 Backup]
Backup --> DBMigrate[🗄️ Database Migration]
DBMigrate --> UpdateDeps[📚 Update Dependencies]
UpdateDeps --> Deploy[🚀 Deploy]
Deploy --> Verify[✅ Verify]
Start([Start Migration]) --> Backup[ Backup]
Backup --> DBMigrate[ Database Migration]
DBMigrate --> UpdateDeps[ Update Dependencies]
UpdateDeps --> Deploy[ Deploy]
Deploy --> Verify[ Verify]
Verify --> Decision{All Tests Pass?}
Decision -->|Yes| Rollout[📊 Gradual Rollout]
Decision -->|No| Rollback[⏮️ Rollback]
Rollback --> Debug[🔍 Debug Issues]
Decision -->|Yes| Rollout[ Gradual Rollout]
Decision -->|No| Rollback[⏮ Rollback]
Rollback --> Debug[ Debug Issues]
Debug --> DBMigrate
Rollout --> Monitor[📈 Monitor]
Monitor --> Complete([✨ Complete])
Rollout --> Monitor[ Monitor]
Monitor --> Complete([ Complete])
style Start fill:#2d4263,stroke:#c69b7b,stroke-width:2px,color:#f5f5f5
style Backup fill:#191e29,stroke:#76b6c4,stroke-width:2px,color:#f5f5f5
@@ -39,7 +39,7 @@ graph LR
## Backward Compatibility
✅ **All existing endpoints continue to work normally:**
**All existing endpoints continue to work normally:**
- `/api/v1/auth/*` - Authentication endpoints
- `/api/v1/rbac/*` - RBAC endpoints
@@ -367,25 +367,25 @@ If you encounter issues during migration:
## Quick Tips
**Migration Checklist:**
- ✅ Backup database and code
- ✅ Run database migrations
- ✅ Update deployment configuration
- ✅ Test backward compatibility
- ✅ Monitor gradual rollout
- ✅ Prepare rollback plan
- Backup database and code
- Run database migrations
- Update deployment configuration
- Test backward compatibility
- Monitor gradual rollout
- Prepare rollback plan
### Common Issues & Solutions
| Issue | Cause | Solution |
|-------|-------|----------|
| 🔴 Migration failed | Database connection | Check `DATABASE_URL` in `.env` |
| 🔴 Service won't start | Missing env vars | Verify all env vars are set |
| 🟡 Slow performance | Database indexes | Run Prisma migrations completely |
| 🟡 Connection timeout | Network issues | Check firewall & security groups |
| 🔵 New endpoints 404 | Routing config | Update Traefik/Ingress config |
| Migration failed | Database connection | Check `DATABASE_URL` in `.env` |
| Service won't start | Missing env vars | Verify all env vars are set |
| Slow performance | Database indexes | Run Prisma migrations completely |
| Connection timeout | Network issues | Check firewall & security groups |
| New endpoints 404 | Routing config | Update Traefik/Ingress config |
**Visual Indicators:**
- 🔵 Old Components (Unchanged)
- 🟢 New Components (Added)
- 🔴 Components to Deprecate
- ⚠️ Requires Attention
- Old Components (Unchanged)
- New Components (Added)
- Components to Deprecate
- Requires Attention

58
docs/en/guides/kubernetes-local.md
View File

@@ -10,16 +10,16 @@
```mermaid
graph TD
Start([🚀 Start]) --> EnvPrep[1️⃣ Environment Prep<br/>Enable K8s in Docker Desktop]
EnvPrep --> BuildImg[2️⃣ Build Docker Image<br/>docker build -t service:local]
BuildImg --> LoadImg[3️⃣ Load Image to Cluster<br/>kind load docker-image]
LoadImg --> Secrets[4️⃣ Configure Secrets<br/>kubectl create secret]
Secrets --> Deploy[5️⃣ Deploy Service<br/>kubectl apply -f manifests]
Deploy --> Verify[6️⃣ Verify Deployment<br/>kubectl get pods]
Verify --> Test[7️⃣ Test Service<br/>Port Forward & Curl]
Test --> End([✅ Complete])
Start([ Start]) --> EnvPrep[1⃣ Environment Prep<br/>Enable K8s in Docker Desktop]
EnvPrep --> BuildImg[2⃣ Build Docker Image<br/>docker build -t service:local]
BuildImg --> LoadImg[3⃣ Load Image to Cluster<br/>kind load docker-image]
LoadImg --> Secrets[4⃣ Configure Secrets<br/>kubectl create secret]
Secrets --> Deploy[5⃣ Deploy Service<br/>kubectl apply -f manifests]
Deploy --> Verify[6⃣ Verify Deployment<br/>kubectl get pods]
Verify --> Test[7⃣ Test Service<br/>Port Forward & Curl]
Test --> End([ Complete])
subgraph Deployment["📦 Deployment Resources"]
subgraph Deployment[" Deployment Resources"]
Deploy --> |Apply| ConfigMap[ConfigMap<br/>Environment Config]
Deploy --> |Apply| K8sDeployment[Deployment<br/>Pod Template]
Deploy --> |Apply| Service[Service<br/>LoadBalancer/NodePort]
@@ -79,7 +79,7 @@ This guide details how to deploy the IAM Service (or any microservice in the Goo
### 2.1 Enable Kubernetes in Docker Desktop
1. Open **Docker Desktop**.
2. Click the **Settings (⚙️)** icon.
2. Click the **Settings ()** icon.
3. Select the **Kubernetes** tab.
4. Check **Enable Kubernetes**.
5. Select **Show system containers (advanced)** for easier debugging (optional).
@@ -122,7 +122,7 @@ docker images | grep iam-service
## 4. Load Image into Cluster
**⚠️ IMPORTANT**: Docker Desktop can use different backends. If you are running Kubernetes inside Docker Desktop, sometimes it doesn't immediately see local images if using a `kind` node underneath.
** IMPORTANT**: Docker Desktop can use different backends. If you are running Kubernetes inside Docker Desktop, sometimes it doesn't immediately see local images if using a `kind` node underneath.
If you are using **Kind** (Kubernetes in Docker) separately or a specific Docker Desktop config, you need to load the image:
@@ -254,55 +254,55 @@ When done, delete resources to free up capacity.
kubectl delete namespace iam-local
```
## 📚 Quick Tips
## Quick Tips
### Common Issues & Solutions
| Issue | Symptoms | Solution |
|-------|----------|----------|
| 🔴 **ImagePullBackOff** | Pod stuck in `ImagePullBackOff` | Set `imagePullPolicy: Never` in deployment YAML<br/>Run `kind load docker-image` if using Kind |
| 🔴 **CrashLoopBackOff** | Pod keeps restarting | Check logs with `kubectl logs`<br/>Verify `DATABASE_URL` in secrets<br/>Ensure DB is accessible via `host.docker.internal` |
| 🟡 **Pending LoadBalancer** | Service External-IP shows `<pending>` | Normal on local—use `kubectl port-forward` instead |
| 🟡 **Connection Refused** | Can't connect after port-forward | Check pod is `Running` (not `CrashLoopBackOff`)<br/>Verify correct port mapping |
| **ImagePullBackOff** | Pod stuck in `ImagePullBackOff` | Set `imagePullPolicy: Never` in deployment YAML<br/>Run `kind load docker-image` if using Kind |
| **CrashLoopBackOff** | Pod keeps restarting | Check logs with `kubectl logs`<br/>Verify `DATABASE_URL` in secrets<br/>Ensure DB is accessible via `host.docker.internal` |
| **Pending LoadBalancer** | Service External-IP shows `<pending>` | Normal on local—use `kubectl port-forward` instead |
| **Connection Refused** | Can't connect after port-forward | Check pod is `Running` (not `CrashLoopBackOff`)<br/>Verify correct port mapping |
### Essential Commands Reference
```bash
# 🔍 Debugging
# Debugging
kubectl get pods -n iam-local -w # Watch pods in real-time
kubectl describe pod <POD_NAME> -n iam-local # Detailed pod info + events
kubectl logs -f <POD_NAME> -n iam-local # Stream logs
kubectl exec -it <POD_NAME> -n iam-local -- /bin/sh # Shell into container
# 🔄 Image Management
# Image Management
docker build -t service:local -f Dockerfile . # Build image
kind load docker-image service:local --name desktop # Load to Kind cluster
docker images | grep service # List local images
# 🚀 Quick Deployment
# Quick Deployment
kubectl apply -f deployment.yaml -n iam-local # Deploy single manifest
kubectl apply -f . -n iam-local # Deploy all files in directory
kubectl rollout restart deployment/iam-service -n iam-local # Force pod restart
# 🧹 Cleanup
# Cleanup
kubectl delete pod <POD_NAME> -n iam-local --force # Force delete stuck pod
kubectl delete namespace iam-local --force --grace-period=0 # Force delete namespace
```
### Visual Status Indicators
- 🟢 **Running** - Service is healthy
- 🟡 **Pending** - Waiting for resources
- 🔴 **CrashLoopBackOff** - Service keeps failing (check logs!)
- 🔵 **ContainerCreating** - Pod starting up
- ⚫ **Terminating** - Pod shutting down
- **Running** - Service is healthy
- **Pending** - Waiting for resources
- **CrashLoopBackOff** - Service keeps failing (check logs!)
- **ContainerCreating** - Pod starting up
- **Terminating** - Pod shutting down
### Pro Tips
1. **⚡ Fast Rebuild**: For quick iteration, use `kubectl rollout restart deployment/iam-service -n iam-local` after rebuilding image
2. **🔍 Watch Mode**: Use `-w` flag to watch resources update in real-time
3. **📝 YAML Validation**: Run `kubectl apply --dry-run=client -f file.yaml` to validate before applying
4. **🎯 Label Filtering**: Use `-l app=iam-service` to filter resources by label instead of typing pod names
1. ** Fast Rebuild**: For quick iteration, use `kubectl rollout restart deployment/iam-service -n iam-local` after rebuilding image
2. ** Watch Mode**: Use `-w` flag to watch resources update in real-time
3. ** YAML Validation**: Run `kubectl apply --dry-run=client -f file.yaml` to validate before applying
4. ** Label Filtering**: Use `-l app=iam-service` to filter resources by label instead of typing pod names
## References

40
docs/en/guides/local-deployment.md
View File

@@ -229,16 +229,16 @@ docker-compose logs traefik
```mermaid
graph TB
Client[👤 Client<br/>Browser] --> Traefik
Client[ Client<br/>Browser] --> Traefik
Traefik[🌐 Traefik<br/>API Gateway<br/>:80, :8080]
Traefik[ Traefik<br/>API Gateway<br/>:80, :8080]
Traefik --> IAM[🔐 IAM Service<br/>Authentication<br/>:5001]
Traefik --> Admin[⚙️ Web Admin<br/>Dashboard<br/>:3000]
Traefik --> WebClient[🌍 Web Client<br/>Application<br/>:3001]
Traefik --> IAM[ IAM Service<br/>Authentication<br/>:5001]
Traefik --> Admin[ Web Admin<br/>Dashboard<br/>:3000]
Traefik --> WebClient[ Web Client<br/>Application<br/>:3001]
IAM --> Redis[(💾 Redis<br/>Cache<br/>:6379)]
IAM --> DB[(🗄️ PostgreSQL<br/>Neon Database)]
IAM --> Redis[( Redis<br/>Cache<br/>:6379)]
IAM --> DB[( PostgreSQL<br/>Neon Database)]
classDef client fill:#1a1a2e,stroke:#16213e,stroke-width:2px,color:#eee
classDef gateway fill:#0f3460,stroke:#16213e,stroke-width:3px,color:#eee
@@ -254,15 +254,15 @@ graph TB
```
**Legend:**
- 👤 **Client**: External users via browser
- 🌐 **Gateway**: Traefik API Gateway (auto-routing)
- 🔐 **Backend**: IAM Service (authentication)
- ⚙️ **Frontend**: Web Admin & Client applications
- 💾 **Storage**: Redis cache & PostgreSQL database
- **Client**: External users via browser
- **Gateway**: Traefik API Gateway (auto-routing)
- **Backend**: IAM Service (authentication)
- **Frontend**: Web Admin & Client applications
- **Storage**: Redis cache & PostgreSQL database
## Quick Tips
### 🚨 Common Issues
### Common Issues
| Problem | Solution |
|---------|----------|
@@ -272,7 +272,7 @@ graph TB
| **Redis connection** | Ensure Redis is healthy: `docker-compose exec redis redis-cli ping` |
| **Traefik routing** | Check dashboard at http://localhost:8080 for route status |
### 🎯 Development Workflow
### Development Workflow
```bash
# Quick restart (code changes)
@@ -285,14 +285,14 @@ docker-compose up -d --build iam-service
docker-compose down -v && docker-compose up -d
```
### 🔐 Security Checklist
### Security Checklist
- ✅ Change default `JWT_SECRET` (min 32 characters)
- ✅ Use environment-specific `.env.local` (never commit)
- ✅ Verify CORS origins match your frontend URLs
- ✅ Enable HTTPS in production (not needed for local)
- Change default `JWT_SECRET` (min 32 characters)
- Use environment-specific `.env.local` (never commit)
- Verify CORS origins match your frontend URLs
- Enable HTTPS in production (not needed for local)
### 📊 Monitoring
### Monitoring
- **Traefik Dashboard**: http://localhost:8080 - View all routes and services
- **Service Health**: http://localhost/api/v1/auth/health - Check service status

102
docs/en/guides/mermaid.md
View File

@@ -8,13 +8,13 @@ This guide helps you choose the right Mermaid diagram type for your documentatio
| Diagram Type | Use For | Complexity |
|----------------------|------------------------|---------------------------|
| **Flowchart** | Workflows, decision trees | ⭐⭐ |
| **Sequence Diagram** | API interactions, request flows | ⭐⭐⭐ |
| **Class Diagram** | Code structure, patterns | ⭐⭐⭐ |
| **Graph** | System architecture, dependencies | ⭐⭐ |
| **ER Diagram** | Database schema | ⭐⭐⭐ |
| **Gantt** | Timeline, project schedule | ⭐⭐ |
| **C4 Diagram** | System context, containers | ⭐⭐⭐⭐ |
| **Flowchart** | Workflows, decision trees | |
| **Sequence Diagram** | API interactions, request flows | |
| **Class Diagram** | Code structure, patterns | |
| **Graph** | System architecture, dependencies | |
| **ER Diagram** | Database schema | |
| **Gantt** | Timeline, project schedule | |
| **C4 Diagram** | System context, containers | |
---
@@ -415,19 +415,19 @@ Our diagrams use a consistent dark color palette based on professional design pr
```mermaid
graph LR
subgraph Primary["🎨 Primary Colors"]
subgraph Primary[" Primary Colors"]
A1["Dark Blue<br/>#2980B9"]
A2["Purple<br/>#8E44AD"]
A3["Green<br/>#27AE60"]
end
subgraph Secondary["🎨 Secondary Colors"]
subgraph Secondary[" Secondary Colors"]
B1["Orange<br/>#E67E22"]
B2["Yellow<br/>#F39C12"]
B3["Red<br/>#C0392B"]
end
subgraph Neutrals["🎨 Neutral Colors"]
subgraph Neutrals[" Neutral Colors"]
C1["Dark Gray<br/>#2C3E50"]
C2["Medium Gray<br/>#34495E"]
C3["Light Text<br/>#ECF0F1"]
@@ -450,15 +450,15 @@ graph LR
| Color | Hex Code | Use For | Example |
|-------|----------|---------|---------|
| **Dark Blue** | `#2980B9` | ✅ Services, Processing, APIs | User Service, API Gateway |
| **Purple** | `#8E44AD` | ✅ Core Components, ORM | Prisma, IAM Service |
| **Green** | `#27AE60` | ✅ Success, Validation, End States | Success Flow, Validated Data |
| **Orange** | `#E67E22` | ⚠️ Cache, Warning States | Redis Cache, Warnings |
| **Yellow** | `#F39C12` | ⚠️ Database, Important Decisions | PostgreSQL, Decision Nodes |
| **Red** | `#C0392B` | ❌ Errors, Failures, Alerts | Error States, Failed Operations |
| **Dark Gray** | `#2C3E50` | 🔘 Start/End, Neutral Elements | Start Node, End Node |
| **Medium Gray** | `#34495E` | 🔘 Subgraphs, Background | Processing Groups, Containers |
| **Light Text** | `#ECF0F1` | 📝 Text Color (always use) | All node text |
| **Dark Blue** | `#2980B9` | Services, Processing, APIs | User Service, API Gateway |
| **Purple** | `#8E44AD` | Core Components, ORM | Prisma, IAM Service |
| **Green** | `#27AE60` | Success, Validation, End States | Success Flow, Validated Data |
| **Orange** | `#E67E22` | Cache, Warning States | Redis Cache, Warnings |
| **Yellow** | `#F39C12` | Database, Important Decisions | PostgreSQL, Decision Nodes |
| **Red** | `#C0392B` | Errors, Failures, Alerts | Error States, Failed Operations |
| **Dark Gray** | `#2C3E50` | Start/End, Neutral Elements | Start Node, End Node |
| **Medium Gray** | `#34495E` | Subgraphs, Background | Processing Groups, Containers |
| **Light Text** | `#ECF0F1` | Text Color (always use) | All node text |
### Standard Style Pattern
@@ -493,14 +493,14 @@ style NodeName fill:#HexColor,stroke:#DarkerShade,stroke-width:2px,color:#ECF0F1
**Choose colors based on node function:**
🔵 **Blue (`#2980B9`)** → Services, APIs, Controllers
🟣 **Purple (`#8E44AD`)** → Core Systems, ORM, Frameworks
🟢 **Green (`#27AE60`)** → Success, Validation, Completion
🟠 **Orange (`#E67E22`)** → Cache, Memory, Storage
🟡 **Yellow (`#F39C12`)** → Databases, Decisions, Important Actions
🔴 **Red (`#C0392B`)** → Errors, Failures, Critical Issues
⚫ **Dark Gray (`#2C3E50`)** → Start/End, Neutral States
⚫ **Medium Gray (`#34495E`)** → Containers, Subgraphs, Groups
**Blue (`#2980B9`)** → Services, APIs, Controllers
**Purple (`#8E44AD`)** → Core Systems, ORM, Frameworks
**Green (`#27AE60`)** → Success, Validation, Completion
**Orange (`#E67E22`)** → Cache, Memory, Storage
**Yellow (`#F39C12`)** → Databases, Decisions, Important Actions
**Red (`#C0392B`)** → Errors, Failures, Critical Issues
**Dark Gray (`#2C3E50`)** → Start/End, Neutral States
**Medium Gray (`#34495E`)** → Containers, Subgraphs, Groups
---
@@ -520,7 +520,7 @@ style NodeName fill:#HexColor,stroke:#DarkerShade,stroke-width:2px,color:#ECF0F1
## Common Pitfalls
### ❌ Too Complex
### Too Complex
```mermaid
graph TD
@@ -538,7 +538,7 @@ graph TD
I --> J
```
### ✅ Simplified with Subgraphs
### Simplified with Subgraphs
```mermaid
graph TD
@@ -592,24 +592,24 @@ mmdc -i your-doc.md
## Quick Tips
### 🔧 Mermaid Common Issues
### Mermaid Common Issues
**Issue**: Diagram not rendering
- ✅ Check for syntax errors (missing arrows, brackets)
- ✅ Ensure proper indentation in subgraphs
- ✅ Validate special characters are escaped
- Check for syntax errors (missing arrows, brackets)
- Ensure proper indentation in subgraphs
- Validate special characters are escaped
**Issue**: Colors not applying
- ✅ Place style commands after all node definitions
- ✅ Use exact node IDs in style statements
- ✅ Ensure hex colors include `#` prefix
- Place style commands after all node definitions
- Use exact node IDs in style statements
- Ensure hex colors include `#` prefix
**Issue**: Text overlapping
- ✅ Use shorter labels or `<br/>` for line breaks
- ✅ Adjust diagram direction (TD, LR, RL, BT)
- ✅ Increase spacing between nodes
- Use shorter labels or `<br/>` for line breaks
- Adjust diagram direction (TD, LR, RL, BT)
- Increase spacing between nodes
### 🎨 Color Pattern Quick Reference
### Color Pattern Quick Reference
```markdown
// Services & APIs
@@ -634,19 +634,19 @@ style Node fill:#F39C12,stroke:#D68910,stroke-width:2px,color:#ECF0F1
style Node fill:#2C3E50,stroke:#1C2833,stroke-width:2px,color:#ECF0F1
```
### 📊 Visual Indicators
### Visual Indicators
Use emojis to enhance diagram readability:
- 🔵 Services & APIs
- 🟣 Core Systems
- 🟢 Success Paths
- 🟡 Databases
- 🟠 Cache/Storage
- 🔴 Errors
- ⚫ Neutral/Start/End
- ⚠️ Warnings
- ✅ Validated
- ❌ Failed
- Services & APIs
- Core Systems
- Success Paths
- Databases
- Cache/Storage
- Errors
- Neutral/Start/End
- Warnings
- Validated
- Failed
---

100
docs/en/guides/neon-database.md
View File

@@ -4,26 +4,26 @@ This project uses [Neon PostgreSQL](https://neon.tech) for all environments.
## Why Neon?
- ✅ **Serverless**: No infrastructure management
- ✅ **Branching**: Separate databases for dev/staging/prod
- ✅ **Auto-scaling**: Handles traffic spikes automatically
- ✅ **Point-in-time restore**: Easy recovery from mistakes
- ✅ **Free tier**: Perfect for development
- ✅ **Connection pooling**: Built-in PgBouncer support
- **Serverless**: No infrastructure management
- **Branching**: Separate databases for dev/staging/prod
- **Auto-scaling**: Handles traffic spikes automatically
- **Point-in-time restore**: Easy recovery from mistakes
- **Free tier**: Perfect for development
- **Connection pooling**: Built-in PgBouncer support
## Architecture Overview
```mermaid
graph TD
Project["📦 Neon Project<br/>goodgo-platform"]
Project[" Neon Project<br/>goodgo-platform"]
Dev["🔧 Development Branch<br/>main"]
Staging["🧪 Staging Branch<br/>staging"]
Prod["🚀 Production Branch<br/>production"]
Dev[" Development Branch<br/>main"]
Staging[" Staging Branch<br/>staging"]
Prod[" Production Branch<br/>production"]
LocalDev["💻 Local Dev<br/>.env.local"]
K8sStaging["☸️ Kubernetes<br/>staging namespace"]
K8sProd["☸️ Kubernetes<br/>production namespace"]
LocalDev[" Local Dev<br/>.env.local"]
K8sStaging[" Kubernetes<br/>staging namespace"]
K8sProd[" Kubernetes<br/>production namespace"]
Project --> Dev
Project --> Staging
@@ -126,27 +126,27 @@ kubectl create secret generic iam-service-secrets \
```mermaid
graph LR
subgraph Local["💻 Local Development"]
Schema["📝 Update Schema<br/>prisma/schema.prisma"]
CreateMig["🔧 Create Migration<br/>migrate dev"]
TestLocal["✅ Test Locally"]
subgraph Local[" Local Development"]
Schema[" Update Schema<br/>prisma/schema.prisma"]
CreateMig[" Create Migration<br/>migrate dev"]
TestLocal[" Test Locally"]
end
subgraph CI["⚙️ CI/CD Pipeline"]
Push["📤 Git Push"]
Build["🔨 Build"]
TestCI["🧪 Run Tests"]
subgraph CI[" CI/CD Pipeline"]
Push[" Git Push"]
Build[" Build"]
TestCI[" Run Tests"]
end
subgraph Staging["🧪 Staging"]
MigStaging["📊 Run Migrations<br/>migrate deploy"]
TestStaging["✅ Verify Schema"]
subgraph Staging[" Staging"]
MigStaging[" Run Migrations<br/>migrate deploy"]
TestStaging[" Verify Schema"]
end
subgraph Prod["🚀 Production"]
Approval["👤 Manual Approval"]
MigProd["📊 Run Migrations<br/>migrate deploy"]
Rollback["🔄 Rollback Plan"]
subgraph Prod[" Production"]
Approval[" Manual Approval"]
MigProd[" Run Migrations<br/>migrate deploy"]
Rollback[" Rollback Plan"]
end
Schema --> CreateMig
@@ -300,7 +300,7 @@ Monitor your databases via Neon Console:
## Quick Tips
### 🎨 Mermaid Diagram Color Palette
### Mermaid Diagram Color Palette
| Element | Color | Usage |
|---------|-------|-------|
@@ -311,38 +311,38 @@ Monitor your databases via Neon Console:
| **Infrastructure** | `#475569` + `#94a3b8` | K8s, CI/CD (gray) |
| **Error/Rollback** | `#7f1d1d` + `#ef4444` | Critical actions (dark red) |
### 🚨 Common Mermaid Issues
### Common Mermaid Issues
**Syntax Errors:**
- ✅ Use quotes for labels with special chars: `["Label<br/>text"]`
- ✅ Escape HTML entities: `&amp;` not `&`
- ✅ Use `<br/>` for line breaks inside labels
- ❌ Avoid `<br>` without closing slash
- Use quotes for labels with special chars: `["Label<br/>text"]`
- Escape HTML entities: `&amp;` not `&`
- Use `<br/>` for line breaks inside labels
- Avoid `<br>` without closing slash
**Rendering Issues:**
- If diagram doesn't render, check for matching brackets `[]` or `{}`
- Verify all style declarations use valid CSS colors
- Ensure subgraph names are unique
### 📊 Visual Indicators
### Visual Indicators
| Icon | Meaning |
|------|---------|
| 📦 | Project/Package |
| 🔧 | Development/Tools |
| 🧪 | Testing/Staging |
| 🚀 | Production/Deploy |
| 💻 | Local Environment |
| ☸️ | Kubernetes |
| ⚙️ | CI/CD Pipeline |
| 📝 | Configuration/Schema |
| 📊 | Database/Data |
| ✅ | Success/Validation |
| ❌ | Error/Failed |
| 🔄 | Rollback/Retry |
| 👤 | Manual Action |
| 📤 | Push/Upload |
| 🔨 | Build Process |
| | Project/Package |
| | Development/Tools |
| | Testing/Staging |
| | Production/Deploy |
| | Local Environment |
| | Kubernetes |
| | CI/CD Pipeline |
| | Configuration/Schema |
| | Database/Data |
| | Success/Validation |
| | Error/Failed |
| | Rollback/Retry |
| | Manual Action |
| | Push/Upload |
| | Build Process |
## Resources

32
docs/en/guides/observability.md
View File

@@ -222,11 +222,11 @@ Diagrams use a dark color palette for better readability:
| Component Type | Fill Color | Stroke Color | Purpose |
|----------------|------------|--------------|----------|
| 🚀 Services | `#e94560` | `#c81e3b` | Microservices (red) |
| 📊 Collectors | `#f39c12` | `#d68910` | Data collection (orange) |
| 💾 Storage | `#3498db` | `#2874a6` | Storage (blue) |
| 📊 Visualization | `#9b59b6` | `#7d3c98` | Visualization (purple) |
| 📦 Subgraphs | `#1a1a2e` - `#533483` | `#16213e` - `#0f3460` | Logical groups |
| Services | `#e94560` | `#c81e3b` | Microservices (red) |
| Collectors | `#f39c12` | `#d68910` | Data collection (orange) |
| Storage | `#3498db` | `#2874a6` | Storage (blue) |
| Visualization | `#9b59b6` | `#7d3c98` | Visualization (purple) |
| Subgraphs | `#1a1a2e` - `#533483` | `#16213e` - `#0f3460` | Logical groups |
**All text uses `color:#ffffff` (white) for readability on dark backgrounds**
@@ -234,13 +234,13 @@ Diagrams use a dark color palette for better readability:
### Mermaid Common Issues
✅ **DO:**
**DO:**
- Use `flowchart LR` for left-to-right flow
- Use `sequenceDiagram` for time-based interactions
- Apply dark colors for better contrast
- Use descriptive node IDs
❌ **DON'T:**
**DON'T:**
- Mix `graph` and `flowchart` syntax
- Use special characters in node IDs without quotes
- Forget closing brackets for subgraphs
@@ -265,11 +265,11 @@ sum(metric_name) by (label)
### Visual Indicators
- 📊 **Metrics**: Numerical time-series data
- 📝 **Logs**: Text-based event records
- 🎯 **Query**: Search/filter operations
- 🔍 **Explore**: Investigation interface
- 📈 **Dashboard**: Pre-configured visualizations
- **Metrics**: Numerical time-series data
- **Logs**: Text-based event records
- **Query**: Search/filter operations
- **Explore**: Investigation interface
- **Dashboard**: Pre-configured visualizations
## Troubleshooting
@@ -277,10 +277,10 @@ sum(metric_name) by (label)
| Issue | Symptoms | Solution |
|-------|----------|----------|
| ⚠️ No logs visible | Grafana Explore shows no logs | Check Promtail is running: `docker ps \| grep promtail` |
| 📊 Missing metrics | Services don't appear in Prometheus targets | Check service `/metrics` endpoint |
| 🔴 Container won't start | `docker ps` doesn't show container | View logs: `docker-compose logs <service-name>` |
| 🌐 Network issue | Services can't connect | Create network: `docker network create microservices-network` |
| No logs visible | Grafana Explore shows no logs | Check Promtail is running: `docker ps \| grep promtail` |
| Missing metrics | Services don't appear in Prometheus targets | Check service `/metrics` endpoint |
| Container won't start | `docker ps` doesn't show container | View logs: `docker-compose logs <service-name>` |
| Network issue | Services can't connect | Create network: `docker network create microservices-network` |
### Logs Not Appearing in Loki

66
docs/en/guides/troubleshooting.md
View File

@@ -46,42 +46,42 @@ When something goes wrong, follow this checklist:
```mermaid
flowchart TD
Start([🔍 Issue Detected]) --> CheckStatus{Check Service<br/>Status}
Start([ Issue Detected]) --> CheckStatus{Check Service<br/>Status}
CheckStatus -->|All Running| CheckLogs[📋 Check Logs]
CheckStatus -->|Some Down| IdentifyService[🎯 Identify Failed<br/>Service]
CheckStatus -->|All Running| CheckLogs[ Check Logs]
CheckStatus -->|Some Down| IdentifyService[ Identify Failed<br/>Service]
IdentifyService --> ServiceType{Service Type?}
ServiceType -->|Infrastructure| InfraCheck[🔧 Infrastructure<br/>Check]
ServiceType -->|Application| AppCheck[⚙️ Application<br/>Check]
ServiceType -->|Infrastructure| InfraCheck[ Infrastructure<br/>Check]
ServiceType -->|Application| AppCheck[ Application<br/>Check]
InfraCheck --> DBCheck{Database?}
InfraCheck --> RedisCheck{Redis?}
InfraCheck --> TraefikCheck{Traefik?}
DBCheck -->|Yes| DBSolution[✅ Check DATABASE_URL<br/>✅ Verify Neon connection<br/>✅ Check IP whitelist]
RedisCheck -->|Yes| RedisSolution[✅ Restart Redis<br/>✅ Check port mapping<br/>✅ Verify connection string]
TraefikCheck -->|Yes| TraefikSolution[✅ Check labels<br/>✅ Verify PathPrefix<br/>✅ Check health status]
DBCheck -->|Yes| DBSolution[ Check DATABASE_URL<br/> Verify Neon connection<br/> Check IP whitelist]
RedisCheck -->|Yes| RedisSolution[ Restart Redis<br/> Check port mapping<br/> Verify connection string]
TraefikCheck -->|Yes| TraefikSolution[ Check labels<br/> Verify PathPrefix<br/> Check health status]
AppCheck --> ErrorType{Error Type?}
ErrorType -->|Config| ConfigFix[✅ Check .env variables<br/>✅ Run init-project.sh]
ErrorType -->|Prisma| PrismaFix[✅ Check migrations<br/>✅ Regenerate client<br/>✅ Reset database]
ErrorType -->|Auth| AuthFix[✅ Check token expiry<br/>✅ Verify keys<br/>✅ Sync Docker time]
ErrorType -->|Config| ConfigFix[ Check .env variables<br/> Run init-project.sh]
ErrorType -->|Prisma| PrismaFix[ Check migrations<br/> Regenerate client<br/> Reset database]
ErrorType -->|Auth| AuthFix[ Check token expiry<br/> Verify keys<br/> Sync Docker time]
CheckLogs --> LogAnalysis{Log Shows<br/>Error?}
LogAnalysis -->|Yes| ErrorType
LogAnalysis -->|No| ConnCheck[🌐 Check Connectivity]
LogAnalysis -->|No| ConnCheck[ Check Connectivity]
ConnCheck --> GatewayTest{Gateway<br/>Reachable?}
GatewayTest -->|No| TraefikCheck
GatewayTest -->|Yes| ServiceTest{Service<br/>Reachable?}
ServiceTest -->|No| AppCheck
ServiceTest -->|Yes| Resolved([✨ Issue Resolved])
ServiceTest -->|Yes| Resolved([ Issue Resolved])
DBSolution --> Restart[🔄 Restart Services]
DBSolution --> Restart[ Restart Services]
RedisSolution --> Restart
TraefikSolution --> Restart
ConfigFix --> Restart
@@ -90,7 +90,7 @@ flowchart TD
Restart --> Verify{Issue<br/>Fixed?}
Verify -->|Yes| Resolved
Verify -->|No| DeepDebug[🛠️ Deep Debugging<br/>Required]
Verify -->|No| DeepDebug[ Deep Debugging<br/>Required]
DeepDebug --> ContainerShell[Access Container Shell]
DeepDebug --> PrismaStudio[Use Prisma Studio]
@@ -307,7 +307,7 @@ A: Docker consumes RAM.
## Quick Tips
### 🎯 Debugging Shortcuts
### Debugging Shortcuts
```bash
# Quick health check all services
@@ -329,7 +329,7 @@ docker stats --no-stream
docker system prune -a --volumes
```
### 🔍 Common Error Patterns
### Common Error Patterns
| Error Pattern | Likely Cause | Quick Fix |
|--------------|--------------|-----------|
@@ -341,13 +341,13 @@ docker system prune -a --volumes
| `502 Bad Gateway` | Service crashed | Check service logs |
| `Config validation error` | Missing env vars | Run `init-project.sh` |
### 📋 Log Analysis Tips
### Log Analysis Tips
**What to look for in logs:**
- ✅ `Server listening on port XXXX` = Service started successfully
- ⚠️ `Warning:` = Non-critical issues
- ❌ `Error:` = Critical issues requiring attention
- 🔍 `Trace:` = Detailed execution flow
- `Server listening on port XXXX` = Service started successfully
- `Warning:` = Non-critical issues
- `Error:` = Critical issues requiring attention
- `Trace:` = Detailed execution flow
**Useful grep patterns:**
```bash
@@ -364,7 +364,7 @@ docker-compose logs | grep -i "prisma\|database\|p1001\|p1003"
docker-compose logs | grep -i "unauthorized\|401\|jwt\|token"
```
### 💾 Resource Management
### Resource Management
**Recommended Docker Resources:**
- **RAM**: Minimum 4GB, Recommended 8GB
@@ -388,14 +388,14 @@ docker container prune
# Remove unused images
docker image prune -a
# Remove unused volumes (⚠️ deletes data!)
# Remove unused volumes ( deletes data!)
docker volume prune
# Nuclear option (⚠️ removes everything!)
# Nuclear option ( removes everything!)
docker system prune -a --volumes
```
### 🛡️ Best Practices
### Best Practices
1. **Always check logs first** before making changes
2. **Use Traefik Dashboard** (http://localhost:8080) to verify routing
@@ -406,16 +406,16 @@ docker system prune -a --volumes
7. **Keep services running** you're actively developing
8. **Stop services** you're not using to save resources
### 🎨 Visual Indicators
### Visual Indicators
When reading logs, look for these patterns:
- 🟢 `[INFO]` = Normal operation
- 🟡 `[WARN]` = Something to watch
- 🔴 `[ERROR]` = Needs immediate attention
- 🔵 `[DEBUG]` = Detailed information
- ⚡ `[TRACE]` = Very detailed execution flow
- `[INFO]` = Normal operation
- `[WARN]` = Something to watch
- `[ERROR]` = Needs immediate attention
- `[DEBUG]` = Detailed information
- `[TRACE]` = Very detailed execution flow
### 🔗 Related Resources
### Related Resources
- [Local Deployment Guide](./local-deployment.md) - Setup instructions
- [Development Guide](./development.md) - Development workflow

32
docs/vi/guides/development.md
View File

@@ -20,22 +20,22 @@ Chúng tôi tuân theo cấu trúc monorepo quản lý bởi PNPM Workspaces.
```
Base/
├── apps/ # Ứng dụng Frontend
│ ├── web-client/ # Next.js 14+ (App Router)
│ └── mobile-client/ # Flutter
├── services/ # Backend microservices
│ ├── _template/ # Template cho service mới
│ ├── iam-service/ # Identity & Access Management
│ └── ...
├── packages/ # Thư viện chia sẻ
│ ├── logger/ # Structured logging (Winston)
│ ├── types/ # DTOs & Interfaces chia sẻ
│ ├── http-client/ # Internal Service Client
│ └── tracing/ # Cấu hình OpenTelemetry
├── infra/ # Infrastructure-as-Code
│ ├── traefik/ # API Gateway
│ └── databases/ # Scripts thiết lập Database
└── docs/ # Tài liệu (EN & VI)
apps/ # Ứng dụng Frontend
web-client/ # Next.js 14+ (App Router)
mobile-client/ # Flutter
services/ # Backend microservices
_template/ # Template cho service mới
iam-service/ # Identity & Access Management
...
packages/ # Thư viện chia sẻ
logger/ # Structured logging (Winston)
types/ # DTOs & Interfaces chia sẻ
http-client/ # Internal Service Client
tracing/ # Cấu hình OpenTelemetry
infra/ # Infrastructure-as-Code
traefik/ # API Gateway
databases/ # Scripts thiết lập Database
docs/ # Tài liệu (EN & VI)
```
---

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

@@ -86,42 +86,42 @@ Repository tuân theo cấu trúc monorepo:
```
Base/
├── apps/ # Ứng dụng Frontend
│ ├── 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/ # Service xác thực & phân quyền
│ └── _template/ # Template cho service mới
├── packages/ # Thư viện chia sẻ (Shared libraries)
│ ├── auth-sdk/ # Authentication SDK
│ ├── config/ # Shared configuration utilities
│ ├── http-client/ # Client HTTP nội bộ
│ ├── logger/ # Structured logging (@goodgo/logger)
│ ├── tracing/ # OpenTelemetry tracing
│ └── types/ # TypeScript types chia sẻ
├── infra/ # Cấu hình Infrastructure
│ ├── databases/ # Scripts thiết lập Database
│ ├── docker/ # Docker configurations
│ ├── observability/ # Prometheus, Grafana, Loki configs
│ ├── secrets/ # Secrets management templates
│ └── traefik/ # Cấu hình API Gateway
├── deployments/ # Cấu hình Deploy
│ ├── local/ # Docker Compose cho dev
│ ├── 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/ # Tài liệu
├── en/ # English documentation
└── vi/ # Vietnamese documentation
apps/ # Ứng dụng Frontend
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/ # Service xác thực & phân quyền
_template/ # Template cho service mới
packages/ # Thư viện chia sẻ (Shared libraries)
auth-sdk/ # Authentication SDK
config/ # Shared configuration utilities
http-client/ # Client HTTP nội bộ
logger/ # Structured logging (@goodgo/logger)
tracing/ # OpenTelemetry tracing
types/ # TypeScript types chia sẻ
infra/ # Cấu hình Infrastructure
databases/ # Scripts thiết lập Database
docker/ # Docker configurations
observability/ # Prometheus, Grafana, Loki configs
secrets/ # Secrets management templates
traefik/ # Cấu hình API Gateway
deployments/ # Cấu hình Deploy
local/ # Docker Compose cho dev
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/ # Tài liệu
en/ # English documentation
vi/ # Vietnamese documentation
```
## Cài đặt & Thiết lập

118
docs/vi/guides/iam-migration.md
View File

@@ -6,34 +6,34 @@ Tài liệu này hướng dẫn cách migrate từ `auth-service` sang `iam-serv
IAM Service là phiên bản mở rộng của Auth Service với các tính năng bổ sung về Identity Management, Access Management, và Governance & Compliance. Tất cả các API endpoints của Auth Service vẫn được giữ nguyên để đảm bảo backward compatibility.
### 🔄 Migration Process Flow
### Migration Process Flow
```mermaid
graph TD
Start([🚀 Bắt đầu Migration]) --> Backup[📦 Step 1: Backup<br/>Database & Code]
Backup --> Update[🔧 Step 2: Update Codebase<br/>Package refs, Env vars]
Update --> Migrate[🗄️ Step 3: Run Prisma Migration<br/>Add IAM models]
Migrate --> Deploy{🚀 Deployment Strategy}
Start([ Bắt đầu Migration]) --> Backup[ Step 1: Backup<br/>Database & Code]
Backup --> Update[ Step 2: Update Codebase<br/>Package refs, Env vars]
Update --> Migrate[ Step 3: Run Prisma Migration<br/>Add IAM models]
Migrate --> Deploy{ Deployment Strategy}
Deploy -->|Khuyến nghị| BlueGreen[💚 Blue-Green Deployment]
Deploy -->|Dễ dàng hơn| InPlace[⚡ In-Place Migration]
Deploy -->|Khuyến nghị| BlueGreen[ Blue-Green Deployment]
Deploy -->|Dễ dàng hơn| InPlace[ In-Place Migration]
BlueGreen --> DeployNew[Deploy IAM Service mới]
DeployNew --> Verify1[✅ Verify hoạt động]
Verify1 --> Switch[🔀 Switch traffic]
Switch --> Monitor1[📊 Monitor]
DeployNew --> Verify1[ Verify hoạt động]
Verify1 --> Switch[ Switch traffic]
Switch --> Monitor1[ Monitor]
Monitor1 --> Success{Thành công?}
InPlace --> DeployBoth[Deploy cả 2 service]
DeployBoth --> GradualRoute[🔀 Gradually route traffic]
GradualRoute --> Monitor2[📊 Monitor]
DeployBoth --> GradualRoute[ Gradually route traffic]
GradualRoute --> Monitor2[ Monitor]
Monitor2 --> Success
Success -->|Yes| Cleanup[🧹 Decommission Auth Service]
Success -->|No| Rollback[⏮️ Rollback]
Success -->|Yes| Cleanup[ Decommission Auth Service]
Success -->|No| Rollback[⏮ Rollback]
Cleanup --> Complete([✨ Migration Hoàn Thành])
Rollback --> End([❌ Migration Failed])
Cleanup --> Complete([ Migration Hoàn Thành])
Rollback --> End([ Migration Failed])
style Start fill:#1a472a,stroke:#2d8659,stroke-width:3px,color:#fff
style Complete fill:#1a472a,stroke:#2d8659,stroke-width:3px,color:#fff
@@ -56,28 +56,28 @@ graph TD
style Rollback fill:#4a1a1a,stroke:#8b2e2e,color:#fff
```
### 🏗️ Architecture Evolution
### Architecture Evolution
```mermaid
graph TB
subgraph Before["Auth Service (Trước)"]
AuthAPI[🔐 Authentication APIs<br/>/api/v1/auth/*]
RBACAPI[👥 RBAC APIs<br/>/api/v1/rbac/*]
MFAAPI[🔒 MFA APIs<br/>/api/v1/mfa/*]
SessionAPI[🎫 Session APIs<br/>/api/v1/sessions/*]
OIDCAPI[🆔 OIDC APIs<br/>/api/v1/oidc/*]
AuthAPI[ Authentication APIs<br/>/api/v1/auth/*]
RBACAPI[ RBAC APIs<br/>/api/v1/rbac/*]
MFAAPI[ MFA APIs<br/>/api/v1/mfa/*]
SessionAPI[ Session APIs<br/>/api/v1/sessions/*]
OIDCAPI[ OIDC APIs<br/>/api/v1/oidc/*]
end
subgraph After["IAM Service (Sau)"]
AuthAPI2[🔐 Authentication APIs<br/>/api/v1/auth/*<br/>✅ Giữ nguyên]
RBACAPI2[👥 RBAC APIs<br/>/api/v1/rbac/*<br/>✅ Giữ nguyên]
MFAAPI2[🔒 MFA APIs<br/>/api/v1/mfa/*<br/>✅ Giữ nguyên]
SessionAPI2[🎫 Session APIs<br/>/api/v1/sessions/*<br/>✅ Giữ nguyên]
OIDCAPI2[🆔 OIDC APIs<br/>/api/v1/oidc/*<br/>✅ Giữ nguyên]
AuthAPI2[ Authentication APIs<br/>/api/v1/auth/*<br/> Giữ nguyên]
RBACAPI2[ RBAC APIs<br/>/api/v1/rbac/*<br/> Giữ nguyên]
MFAAPI2[ MFA APIs<br/>/api/v1/mfa/*<br/> Giữ nguyên]
SessionAPI2[ Session APIs<br/>/api/v1/sessions/*<br/> Giữ nguyên]
OIDCAPI2[ OIDC APIs<br/>/api/v1/oidc/*<br/> Giữ nguyên]
IdentityAPI[🆔 Identity Management<br/>/api/v1/identity/*<br/>⭐ MỚI]
AccessAPI[🔑 Access Management<br/>/api/v1/access/*<br/>⭐ MỚI]
GovernanceAPI[📋 Governance<br/>/api/v1/governance/*<br/>⭐ MỚI]
IdentityAPI[ Identity Management<br/>/api/v1/identity/*<br/> MỚI]
AccessAPI[ Access Management<br/>/api/v1/access/*<br/> MỚI]
GovernanceAPI[ Governance<br/>/api/v1/governance/*<br/> MỚI]
end
Before -.->|Backward Compatible<br/>Migration| After
@@ -101,7 +101,7 @@ graph TB
## Backward Compatibility
✅ **Tất cả các endpoints hiện tại vẫn hoạt động bình thường:**
**Tất cả các endpoints hiện tại vẫn hoạt động bình thường:**
- `/api/v1/auth/*` - Authentication endpoints
- `/api/v1/rbac/*` - RBAC endpoints
@@ -213,18 +213,18 @@ cp -r services/auth-service services/auth-service.backup
### Step 3: Deployment
#### 🎯 Deployment Strategy Comparison
#### Deployment Strategy Comparison
```mermaid
graph LR
subgraph BlueGreen["💚 Blue-Green Deployment (Khuyến nghị)"]
BG1[Ưu điểm:<br/>✅ Zero downtime<br/>✅ Easy rollback<br/>✅ Safe testing]
BG2[Nhược điểm:<br/>⚠️ Cần thêm resources<br/>⚠️ Phức tạp hơn]
subgraph BlueGreen[" Blue-Green Deployment (Khuyến nghị)"]
BG1[Ưu điểm:<br/> Zero downtime<br/> Easy rollback<br/> Safe testing]
BG2[Nhược điểm:<br/> Cần thêm resources<br/> Phức tạp hơn]
end
subgraph InPlace["⚡ In-Place Migration"]
IP1[Ưu điểm:<br/>✅ Simple setup<br/>✅ Less resources<br/>✅ Gradual migration]
IP2[Nhược điểm:<br/>⚠️ Potential downtime<br/>⚠️ Harder rollback<br/>⚠️ Higher risk]
subgraph InPlace[" In-Place Migration"]
IP1[Ưu điểm:<br/> Simple setup<br/> Less resources<br/> Gradual migration]
IP2[Nhược điểm:<br/> Potential downtime<br/> Harder rollback<br/> Higher risk]
end
Decision{Chọn Strategy} -->|Production| BlueGreen
@@ -318,11 +318,11 @@ Nếu gặp vấn đề trong quá trình migration, vui lòng:
2. Review migration guide này
3. Contact team lead hoặc DevOps team
## 💡 Quick Tips
## Quick Tips
### Migration Best Practices
✅ **DO:**
**DO:**
- Backup database trước khi migrate
- Test migration trên staging trước
- Monitor metrics trong quá trình migration
@@ -330,7 +330,7 @@ Nếu gặp vấn đề trong quá trình migration, vui lòng:
- Prepare rollback plan trước khi deploy
- Document tất cả các thay đổi
❌ **DON'T:**
**DON'T:**
- Skip backup step
- Migrate trực tiếp trên production
- Ignore error logs
@@ -342,11 +342,11 @@ Nếu gặp vấn đề trong quá trình migration, vui lòng:
| Vấn đề | Nguyên nhân | Giải pháp |
|--------|-------------|-----------|
| 🔴 Migration failed | Database connection | Check `DATABASE_URL` trong `.env` |
| 🔴 Service won't start | Missing env vars | Verify tất cả env vars được set |
| 🟡 Slow performance | Database indexes | Run Prisma migrations đầy đủ |
| 🟡 Connection timeout | Network issues | Check firewall & security groups |
| 🔵 New endpoints 404 | Routing config | Update Traefik/Ingress config |
| Migration failed | Database connection | Check `DATABASE_URL` trong `.env` |
| Service won't start | Missing env vars | Verify tất cả env vars được set |
| Slow performance | Database indexes | Run Prisma migrations đầy đủ |
| Connection timeout | Network issues | Check firewall & security groups |
| New endpoints 404 | Routing config | Update Traefik/Ingress config |
### Troubleshooting Quick Reference
@@ -370,24 +370,24 @@ pnpm prisma migrate reset # DEV ONLY
kubectl rollout undo deployment/iam-service
```
### 📊 Color Palette Reference
### Color Palette Reference
**Diagram Colors:**
- 🟢 **Success/Recommended**: `#1a472a` (Dark green)
- 🔵 **Process/Info**: `#1e3a5f` (Dark blue)
- 🟣 **Decision/Important**: `#4a2c5f` (Dark purple)
- 🟡 **Warning/Alternative**: `#5f4a1e` (Dark yellow)
- 🔴 **Error/Rollback**: `#4a1a1a` (Dark red)
- **Success/Recommended**: `#1a472a` (Dark green)
- **Process/Info**: `#1e3a5f` (Dark blue)
- **Decision/Important**: `#4a2c5f` (Dark purple)
- **Warning/Alternative**: `#5f4a1e` (Dark yellow)
- **Error/Rollback**: `#4a1a1a` (Dark red)
### ⚠️ Important Reminders
### Important Reminders
- 📦 **Always backup** trước khi migrate
- 🧪 **Test thoroughly** trên staging
- 📊 **Monitor closely** sau khi deploy
- 🔄 **Prepare rollback** plan
- 📝 **Document changes** cho team
- **Always backup** trước khi migrate
- **Test thoroughly** trên staging
- **Monitor closely** sau khi deploy
- **Prepare rollback** plan
- **Document changes** cho team
- ⏰ **Schedule wisely** - tránh giờ peak
- 🤝 **Communicate** với team và stakeholders
- **Communicate** với team và stakeholders
---

80
docs/vi/guides/kubernetes-local.md
View File

@@ -6,14 +6,14 @@
```mermaid
graph TD
Start([🚀 Bắt đầu]) --> EnvPrep[1. Chuẩn bị Môi trường]
Start([ Bắt đầu]) --> EnvPrep[1. Chuẩn bị Môi trường]
EnvPrep --> BuildImg[2. Build Docker Image]
BuildImg --> LoadImg[3. Load Image vào Cluster]
LoadImg --> Secrets[4. Cấu hình Secrets & Environment]
Secrets --> Deploy[5. Deploy Service]
Deploy --> Verify[6. Kiểm tra & Verify]
Verify --> Test[7. Test Service]
Test --> End([✅ Hoàn tất])
Test --> End([ Hoàn tất])
subgraph "Chi tiết Deploy"
Deploy --> |Apply| ConfigMap[ConfigMap]
@@ -69,7 +69,7 @@ Hướng dẫn này mô tả chi tiết cách deploy IAM Service (hoặc bất k
### 2.1 Enable Kubernetes trong Docker Desktop
1. Mở **Docker Desktop**.
2. Nhấn vào biểu tượng **Settings (⚙️)**.
2. Nhấn vào biểu tượng **Settings ()**.
3. Chọn tab **Kubernetes**.
4. Check vào ô **Enable Kubernetes**.
5. Chọn **Show system containers (advanced)** để dễ debug (tùy chọn).
@@ -112,7 +112,7 @@ docker images | grep iam-service
## 4. Load Image vào Cluster
**⚠️ QUAN TRỌNG**: Docker Desktop có thể sử dụng các backend khác nhau. Nếu bạn đang chạy Kubernetes trong Docker Desktop, đôi khi nó không nhìn thấy image local ngay lập tức nếu sử dụng `kind` node dưới nền.
** QUAN TRỌNG**: Docker Desktop có thể sử dụng các backend khác nhau. Nếu bạn đang chạy Kubernetes trong Docker Desktop, đôi khi nó không nhìn thấy image local ngay lập tức nếu sử dụng `kind` node dưới nền.
Nếu bạn dùng **Kind** (Kubernetes in Docker) riêng biệt hoặc cấu hình Docker Desktop đặc biệt, bạn cần load image:
@@ -249,54 +249,54 @@ kubectl delete namespace iam-local
## Quick Tips
### 🔍 Các Vấn Đề Thường Gặp & Giải Pháp
### Các Vấn Đề Thường Gặp & Giải Pháp
| Vấn đề | Triệu chứng | Giải pháp |
|--------|-------------|-----------|
| 🔴 **ImagePullBackOff** | Pod bị kẹt ở trạng thái `ImagePullBackOff` | Đặt `imagePullPolicy: Never` trong deployment YAML<br/>Chạy `kind load docker-image` nếu dùng Kind |
| 🔴 **CrashLoopBackOff** | Pod liên tục restart | Kiểm tra logs với `kubectl logs`<br/>Verify `DATABASE_URL` trong secrets<br/>Đảm bảo DB accessible qua `host.docker.internal` |
| 🟡 **Pending LoadBalancer** | Service External-IP hiển thị `<pending>` | Bình thường trên local—dùng `kubectl port-forward` thay thế |
| 🟡 **Connection Refused** | Không kết nối được sau port-forward | Kiểm tra pod đang `Running` (không phải `CrashLoopBackOff`)<br/>Verify port mapping chính xác |
| **ImagePullBackOff** | Pod bị kẹt ở trạng thái `ImagePullBackOff` | Đặt `imagePullPolicy: Never` trong deployment YAML<br/>Chạy `kind load docker-image` nếu dùng Kind |
| **CrashLoopBackOff** | Pod liên tục restart | Kiểm tra logs với `kubectl logs`<br/>Verify `DATABASE_URL` trong secrets<br/>Đảm bảo DB accessible qua `host.docker.internal` |
| **Pending LoadBalancer** | Service External-IP hiển thị `<pending>` | Bình thường trên local—dùng `kubectl port-forward` thay thế |
| **Connection Refused** | Không kết nối được sau port-forward | Kiểm tra pod đang `Running` (không phải `CrashLoopBackOff`)<br/>Verify port mapping chính xác |
### 📖 Tham Chiếu Lệnh Thiết Yếu
### Tham Chiếu Lệnh Thiết Yếu
```bash
# 🔍 Debugging
# Debugging
kubectl get pods -n iam-local -w # Theo dõi pods real-time
kubectl describe pod <POD_NAME> -n iam-local # Thông tin chi tiết pod + events
kubectl logs -f <POD_NAME> -n iam-local # Stream logs
kubectl exec -it <POD_NAME> -n iam-local -- /bin/sh # Shell vào container
# 🔄 Quản Lý Image
# Quản Lý Image
docker build -t service:local -f Dockerfile . # Build image
kind load docker-image service:local --name desktop # Load vào Kind cluster
docker images | grep service # Liệt kê local images
# 🚀 Deploy Nhanh
# Deploy Nhanh
kubectl apply -f deployment.yaml -n iam-local # Deploy single manifest
kubectl apply -f . -n iam-local # Deploy tất cả files trong thư mục
kubectl rollout restart deployment/iam-service -n iam-local # Force restart pods
# 🧹 Cleanup
# Cleanup
kubectl delete pod <POD_NAME> -n iam-local --force # Force delete pod bị kẹt
kubectl delete namespace iam-local --force --grace-period=0 # Force delete namespace
```
### 📋 Deployment Checklist
### Deployment Checklist
- [ ] ✅ Docker Desktop Kubernetes enabled
- [ ] ✅ kubectl context = `docker-desktop`
- [ ] ✅ Image built locally: `docker images | grep iam-service`
- [ ] ✅ Namespace created: `kubectl get ns iam-local`
- [ ] ✅ Secrets created: `kubectl get secrets -n iam-local`
- [ ] ✅ ConfigMap applied: `kubectl get cm -n iam-local`
- [ ] ✅ Deployment applied: `kubectl get deploy -n iam-local`
- [ ] ✅ Service created: `kubectl get svc -n iam-local`
- [ ] ✅ Pods running: `kubectl get pods -n iam-local`
- [ ] ✅ Port-forward works: `kubectl port-forward ...`
- [ ] ✅ Health check passes: `curl http://localhost:5002/health/live`
- [ ] Docker Desktop Kubernetes enabled
- [ ] kubectl context = `docker-desktop`
- [ ] Image built locally: `docker images | grep iam-service`
- [ ] Namespace created: `kubectl get ns iam-local`
- [ ] Secrets created: `kubectl get secrets -n iam-local`
- [ ] ConfigMap applied: `kubectl get cm -n iam-local`
- [ ] Deployment applied: `kubectl get deploy -n iam-local`
- [ ] Service created: `kubectl get svc -n iam-local`
- [ ] Pods running: `kubectl get pods -n iam-local`
- [ ] Port-forward works: `kubectl port-forward ...`
- [ ] Health check passes: `curl http://localhost:5002/health/live`
### 💾 Resource Management
### Resource Management
**Recommended Resources per Pod:**
```yaml
@@ -321,7 +321,7 @@ kubectl top pods -n iam-local
kubectl describe node docker-desktop
```
### 🛡️ Best Practices
### Best Practices
1. **Sử dụng namespaces** để tách biệt môi trường
2. **Set resource limits** cho mọi pod
@@ -332,22 +332,22 @@ kubectl describe node docker-desktop
7. **Enable logging** để dễ debug
8. **Regular cleanup** các resources không dùng
### 🎨 Trạng Thái Visual
### Trạng Thái Visual
- 🟢 **Running** - Service hoạt động bình thường
- 🟡 **Pending** - Đang chờ resources
- 🔴 **CrashLoopBackOff** - Service liên tục fail (kiểm tra logs!)
- 🔵 **ContainerCreating** - Pod đang khởi động
- ⚫ **Terminating** - Pod đang tắt
- **Running** - Service hoạt động bình thường
- **Pending** - Đang chờ resources
- **CrashLoopBackOff** - Service liên tục fail (kiểm tra logs!)
- **ContainerCreating** - Pod đang khởi động
- **Terminating** - Pod đang tắt
### 💡 Pro Tips
### Pro Tips
1. **⚡ Fast Rebuild**: Để iterate nhanh, dùng `kubectl rollout restart deployment/iam-service -n iam-local` sau khi rebuild image
2. **🔍 Watch Mode**: Dùng flag `-w` để theo dõi resources update real-time
3. **📝 YAML Validation**: Chạy `kubectl apply --dry-run=client -f file.yaml` để validate trước khi apply
4. **🎯 Label Filtering**: Dùng `-l app=iam-service` để filter resources theo label thay vì gõ pod names
1. ** Fast Rebuild**: Để iterate nhanh, dùng `kubectl rollout restart deployment/iam-service -n iam-local` sau khi rebuild image
2. ** Watch Mode**: Dùng flag `-w` để theo dõi resources update real-time
3. ** YAML Validation**: Chạy `kubectl apply --dry-run=client -f file.yaml` để validate trước khi apply
4. ** Label Filtering**: Dùng `-l app=iam-service` để filter resources theo label thay vì gõ pod names
### 🔗 Tài Liệu Tham Khảo
### Tài Liệu Tham Khảo
- [Kubernetes Documentation](https://kubernetes.io/docs/)
- [Docker Desktop for Mac](https://docs.docker.com/desktop/mac/networking/)

40
docs/vi/guides/local-deployment.md
View File

@@ -227,16 +227,16 @@ docker-compose logs traefik
```mermaid
graph TB
Client[👤 Client<br/>Browser] --> Traefik
Client[ Client<br/>Browser] --> Traefik
Traefik[🌐 Traefik<br/>API Gateway<br/>:80, :8080]
Traefik[ Traefik<br/>API Gateway<br/>:80, :8080]
Traefik --> IAM[🔐 IAM Service<br/>Authentication<br/>:5001]
Traefik --> Admin[⚙️ Web Admin<br/>Dashboard<br/>:3000]
Traefik --> WebClient[🌍 Web Client<br/>Application<br/>:3001]
Traefik --> IAM[ IAM Service<br/>Authentication<br/>:5001]
Traefik --> Admin[ Web Admin<br/>Dashboard<br/>:3000]
Traefik --> WebClient[ Web Client<br/>Application<br/>:3001]
IAM --> Redis[(💾 Redis<br/>Cache<br/>:6379)]
IAM --> DB[(🗄️ PostgreSQL<br/>Neon Database)]
IAM --> Redis[( Redis<br/>Cache<br/>:6379)]
IAM --> DB[( PostgreSQL<br/>Neon Database)]
classDef client fill:#1a1a2e,stroke:#16213e,stroke-width:2px,color:#eee
classDef gateway fill:#0f3460,stroke:#16213e,stroke-width:3px,color:#eee
@@ -252,15 +252,15 @@ graph TB
```
**Chú Giải:**
- 👤 **Client**: Người dùng truy cập qua trình duyệt
- 🌐 **Gateway**: Traefik API Gateway (định tuyến tự động)
- 🔐 **Backend**: IAM Service (xác thực)
- ⚙️ **Frontend**: Ứng dụng Web Admin & Client
- 💾 **Storage**: Redis cache & PostgreSQL database
- **Client**: Người dùng truy cập qua trình duyệt
- **Gateway**: Traefik API Gateway (định tuyến tự động)
- **Backend**: IAM Service (xác thực)
- **Frontend**: Ứng dụng Web Admin & Client
- **Storage**: Redis cache & PostgreSQL database
## Quick Tips
### 🚨 Các Vấn Đề Thường Gặp
### Các Vấn Đề Thường Gặp
| Vấn Đề | Giải Pháp |
|--------|-----------|
@@ -270,7 +270,7 @@ graph TB
| **Kết nối Redis** | Đảm bảo Redis healthy: `docker-compose exec redis redis-cli ping` |
| **Traefik routing** | Kiểm tra dashboard tại http://localhost:8080 để xem trạng thái routes |
### 🎯 Development Workflow
### Development Workflow
```bash
# Restart nhanh (thay đổi code)
@@ -283,14 +283,14 @@ docker-compose up -d --build iam-service
docker-compose down -v && docker-compose up -d
```
### 🔐 Security Checklist
### Security Checklist
- ✅ Thay đổi `JWT_SECRET` mặc định (tối thiểu 32 ký tự)
- ✅ Sử dụng `.env.local` riêng cho từng môi trường (không commit)
- ✅ Xác minh CORS origins khớp với frontend URLs
- ✅ Bật HTTPS trong production (không cần cho local)
- Thay đổi `JWT_SECRET` mặc định (tối thiểu 32 ký tự)
- Sử dụng `.env.local` riêng cho từng môi trường (không commit)
- Xác minh CORS origins khớp với frontend URLs
- Bật HTTPS trong production (không cần cho local)
### 📊 Monitoring
### Monitoring
- **Traefik Dashboard**: http://localhost:8080 - Xem tất cả routes và services
- **Service Health**: http://localhost/api/v1/auth/health - Kiểm tra trạng thái service

124
docs/vi/guides/mermaid.md
View File

@@ -8,13 +8,13 @@ Hướng dẫn này giúp bạn chọn loại sơ đồ Mermaid phù hợp cho t
| Loại Sơ đồ | Sử dụng cho | Độ phức tạp |
|-------------|-------------|-------------|
| **Flowchart** | Quy trình, cây quyết định | ⭐⭐ |
| **Sequence Diagram** | Tương tác API, luồng request | ⭐⭐⭐ |
| **Class Diagram** | Cấu trúc code, patterns | ⭐⭐⭐ |
| **Graph** | Kiến trúc hệ thống, dependencies | ⭐⭐ |
| **ER Diagram** | Schema database | ⭐⭐⭐ |
| **Gantt** | Timeline, lịch trình dự án | ⭐⭐ |
| **C4 Diagram** | Bối cảnh hệ thống, containers | ⭐⭐⭐⭐ |
| **Flowchart** | Quy trình, cây quyết định | |
| **Sequence Diagram** | Tương tác API, luồng request | |
| **Class Diagram** | Cấu trúc code, patterns | |
| **Graph** | Kiến trúc hệ thống, dependencies | |
| **ER Diagram** | Schema database | |
| **Gantt** | Timeline, lịch trình dự án | |
| **C4 Diagram** | Bối cảnh hệ thống, containers | |
---
@@ -439,13 +439,13 @@ Sử dụng bảng màu tối để tạo sơ đồ có độ tương phản cao
```mermaid
graph LR
A["🔵 Primary<br/>#2C3E50"] --> B["💾 Data/Cache<br/>#34495E"]
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<br/>#2C3E50"] --> B[" Data/Cache<br/>#34495E"]
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:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:2px
style B fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
@@ -461,24 +461,24 @@ graph LR
| Màu | Mã Hex | Sử dụng cho | Màu Viền | Màu Chữ |
|-----|--------|-------------|----------|---------|
| 🔵 **Primary** | `#2C3E50` | Node chính, bắt đầu, khối chính | `#34495E` | `#ECF0F1` |
| 💾 **Data/Cache** | `#34495E` | Database, Cache, Storage | `#2C3E50` | `#ECF0F1` |
| ✅ **Success** | `#27AE60` | Kết thúc thành công, xác nhận | `#229954` | `#ECF0F1` |
| ⚠️ **Warning** | `#E67E22` | Cảnh báo, điều kiện quan trọng | `#D35400` | `#ECF0F1` |
| ❌ **Error** | `#C0392B` | Lỗi, thất bại, hủy bỏ | `#A93226` | `#ECF0F1` |
| ⚙️ **Processing** | `#8E44AD` | Xử lý, quá trình chạy | `#7D3C98` | `#ECF0F1` |
| ℹ️ **Info** | `#3498DB` | Thông tin, ghi chú | `#2980B9` | `#ECF0F1` |
| ⚪ **Neutral** | `#7F8C8D` | Trung lập, không ưu tiên | `#5D6D7E` | `#ECF0F1` |
| **Primary** | `#2C3E50` | Node chính, bắt đầu, khối chính | `#34495E` | `#ECF0F1` |
| **Data/Cache** | `#34495E` | Database, Cache, Storage | `#2C3E50` | `#ECF0F1` |
| **Success** | `#27AE60` | Kết thúc thành công, xác nhận | `#229954` | `#ECF0F1` |
| **Warning** | `#E67E22` | Cảnh báo, điều kiện quan trọng | `#D35400` | `#ECF0F1` |
| **Error** | `#C0392B` | Lỗi, thất bại, hủy bỏ | `#A93226` | `#ECF0F1` |
| **Processing** | `#8E44AD` | Xử lý, quá trình chạy | `#7D3C98` | `#ECF0F1` |
| ℹ **Info** | `#3498DB` | Thông tin, ghi chú | `#2980B9` | `#ECF0F1` |
| **Neutral** | `#7F8C8D` | Trung lập, không ưu tiên | `#5D6D7E` | `#ECF0F1` |
### Checklist Áp dụng Màu
✅ **Nguyên tắc Cơ bản:**
**Nguyên tắc Cơ bản:**
- [ ] Sử dụng màu tối cho nền (dark background)
- [ ] Màu chữ sáng (`#ECF0F1` hoặc `#fff`) để tạo tương phản
- [ ] Viền tối hơn nền một chút để tạo chiều sâu
- [ ] Độ dày viền: `2px` hoặc `3px`
✅ **Pattern theo Loại Node:**
**Pattern theo Loại Node:**
**Start/End Nodes (Bắt đầu/Kết thúc):**
```markdown
@@ -560,7 +560,7 @@ style NodeName fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:2px
## Cạm bẫy Thường gặp
### ❌ Too Complex
### Too Complex
```mermaid
graph TD
@@ -589,7 +589,7 @@ graph TD
style J fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px
```
### ✅ Simplified with Subgraphs
### Simplified with Subgraphs
```mermaid
graph TD
@@ -641,16 +641,16 @@ mmdc -i your-doc.md
---
## 💡 Quick Tips
## Quick Tips
### ⚠️ Lỗi Mermaid Thường gặp
### Lỗi Mermaid Thường gặp
#### 1. Lỗi Cú pháp
**Vấn đề:** Sơ đồ không render
```markdown
❌ SAI: flowchart TD A -> B
✅ ĐÚNG: flowchart TD
SAI: flowchart TD A -> B
ĐÚNG: flowchart TD
A --> B
```
@@ -663,12 +663,12 @@ mmdc -i your-doc.md
**Vấn đề:** Node ID trùng lặp
```markdown
❌ SAI:
SAI:
graph TD
A[Start]
A[Process] <!-- Trùng ID -->
✅ ĐÚNG:
ĐÚNG:
graph TD
A[Start]
B[Process]
@@ -678,27 +678,27 @@ graph TD
**Vấn đề:** Style không áp dụng
```markdown
❌ SAI: style Node fill:#2C3E50 <!-- Thiếu dấu phẩy -->
SAI: style Node fill:#2C3E50 <!-- Thiếu dấu phẩy -->
✅ ĐÚNG: style Node fill:#2C3E50,color:#ECF0F1
ĐÚNG: style Node fill:#2C3E50,color:#ECF0F1
```
#### 4. Lỗi Subgraph
**Vấn đề:** Subgraph không hiển thị đúng
```markdown
❌ SAI:
SAI:
subgraph "My Group"
A --> B
end
✅ ĐÚNG:
ĐÚNG:
subgraph MyGroup["My Group"]
A --> B
end
```
### 🎨 Quick Color Pattern Reference
### Quick Color Pattern Reference
**Copy-paste Templates:**
@@ -725,32 +725,32 @@ style Process fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
style Info fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
```
### 🔍 Visual Indicators Guide
### Visual Indicators Guide
Sử dụng emoji để tăng khả năng đọc:
| Emoji | Ý nghĩa | Sử dụng trong |
|-------|---------|---------------|
| 🚀 | Start/Launch | Node bắt đầu |
| ✅ | Success | Node thành công |
| ❌ | Error/Failed | Node lỗi |
| ⚠️ | Warning | Decision nodes quan trọng |
| 🔐 | Security/Auth | Authentication steps |
| 💾 | Database/Storage | Data nodes |
| ⚙️ | Processing | Processing nodes |
| ℹ️ | Information | Info nodes |
| 🔄 | Sync/Update | Sync operations |
| 📡 | API/Network | External calls |
| | Start/Launch | Node bắt đầu |
| | Success | Node thành công |
| | Error/Failed | Node lỗi |
| | Warning | Decision nodes quan trọng |
| | Security/Auth | Authentication steps |
| | Database/Storage | Data nodes |
| | Processing | Processing nodes |
| ℹ | Information | Info nodes |
| | Sync/Update | Sync operations |
| | API/Network | External calls |
**Ví dụ sử dụng:**
```mermaid
flowchart TD
Start([🚀 Bắt đầu]) --> Auth{🔐 Xác thực?}
Auth -->|❌| Error[Lỗi]
Auth -->|✅| Process[⚙️ Xử lý]
Process --> DB[(💾 Database)]
DB --> Success[✅ Thành công]
Start([ Bắt đầu]) --> Auth{ Xác thực?}
Auth -->|| Error[Lỗi]
Auth -->|| Process[ Xử lý]
Process --> DB[( Database)]
DB --> Success[ Thành công]
style Start fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:3px
style Success fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
@@ -760,7 +760,7 @@ flowchart TD
style DB fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
```
### 🛠️ Troubleshooting Checklist
### Troubleshooting Checklist
Khi sơ đồ không render:
@@ -772,7 +772,7 @@ Khi sơ đồ không render:
- [ ] **Kiểm tra Color**: Hex code có dấu `#` phía trước?
- [ ] **Kiểm tra Special Characters**: Tránh ký tự đặc biệt trong label
### 📊 Diagram Selection Matrix
### Diagram Selection Matrix
**Chọn loại sơ đồ dựa trên mục đích:**
@@ -780,13 +780,13 @@ Khi sơ đồ không render:
flowchart TD
Start{Bạn cần<br/>visualize gì?}
Start -->|Quy trình| Flow[Flowchart ⭐⭐]
Start -->|API/Giao tiếp| Seq[Sequence ⭐⭐⭐]
Start -->|Code Structure| Class[Class Diagram ⭐⭐⭐]
Start -->|Kiến trúc| Graph[Graph ⭐⭐]
Start -->|Database| ER[ER Diagram ⭐⭐⭐]
Start -->|Timeline| Gantt[Gantt Chart ⭐⭐]
Start -->|System Context| C4[C4 Diagram ⭐⭐⭐⭐]
Start -->|Quy trình| Flow[Flowchart ]
Start -->|API/Giao tiếp| Seq[Sequence ]
Start -->|Code Structure| Class[Class Diagram ]
Start -->|Kiến trúc| Graph[Graph ]
Start -->|Database| ER[ER Diagram ]
Start -->|Timeline| Gantt[Gantt Chart ]
Start -->|System Context| C4[C4 Diagram ]
style Start fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
style Flow fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px

154
docs/vi/guides/neon-database.md
View File

@@ -4,28 +4,28 @@ Project này sử dụng [Neon PostgreSQL](https://neon.tech) cho tất cả mô
## Tại Sao Chọn Neon?
- ✅ **Serverless**: Không cần quản lý infrastructure
- ✅ **Branching**: Database riêng cho dev/staging/prod
- ✅ **Auto-scaling**: Tự động xử lý traffic spikes
- ✅ **Point-in-time restore**: Dễ dàng khôi phục từ lỗi
- ✅ **Free tier**: Hoàn hảo cho development
- ✅ **Connection pooling**: Hỗ trợ PgBouncer tích hợp
- **Serverless**: Không cần quản lý infrastructure
- **Branching**: Database riêng cho dev/staging/prod
- **Auto-scaling**: Tự động xử lý traffic spikes
- **Point-in-time restore**: Dễ dàng khôi phục từ lỗi
- **Free tier**: Hoàn hảo cho development
- **Connection pooling**: Hỗ trợ PgBouncer tích hợp
## Kiến Trúc Neon
```mermaid
graph TB
subgraph NeonProject["🌐 Neon Project: goodgo-platform"]
Main["<b>Branch: main</b><br/>🔧 Development<br/>Auto-scaling<br/>Point-in-time restore"]
Staging["<b>Branch: staging</b><br/>🧪 Staging<br/>Created from main<br/>Pre-production testing"]
Production["<b>Branch: production</b><br/>🚀 Production<br/>Created from main<br/>Live environment"]
subgraph NeonProject[" Neon Project: goodgo-platform"]
Main["<b>Branch: main</b><br/> Development<br/>Auto-scaling<br/>Point-in-time restore"]
Staging["<b>Branch: staging</b><br/> Staging<br/>Created from main<br/>Pre-production testing"]
Production["<b>Branch: production</b><br/> Production<br/>Created from main<br/>Live environment"]
end
subgraph Features["✨ Tính Năng Chính"]
F1["⚡ Serverless<br/>No infrastructure"]
F2["🔄 Auto-scaling<br/>Handle spikes"]
F3["💾 Backups<br/>Point-in-time"]
F4["🔌 Pooling<br/>PgBouncer"]
subgraph Features[" Tính Năng Chính"]
F1[" Serverless<br/>No infrastructure"]
F2[" Auto-scaling<br/>Handle spikes"]
F3[" Backups<br/>Point-in-time"]
F4[" Pooling<br/>PgBouncer"]
end
Main -->|Branch từ| Staging
@@ -153,28 +153,28 @@ Migration thủ công:
```mermaid
flowchart TD
Start([👨‍💻 Bắt đầu<br/>Schema thay đổi]) --> Dev[📝 Development<br/>Tạo migration mới<br/>migrate.sh dev]
Dev --> Test{✅ Test<br/>Migration<br/>OK?}
Start([ Bắt đầu<br/>Schema thay đổi]) --> Dev[ Development<br/>Tạo migration mới<br/>migrate.sh dev]
Dev --> Test{ Test<br/>Migration<br/>OK?}
Test -->|❌ Không| Fix[🔧 Sửa lỗi<br/>Cập nhật schema]
Test -->| Không| Fix[ Sửa lỗi<br/>Cập nhật schema]
Fix --> Dev
Test -->|✅ Có| Commit[📦 Commit<br/>Migration files<br/>+ schema.prisma]
Commit --> PR[🔀 Pull Request<br/>Code review]
Test -->| Có| Commit[ Commit<br/>Migration files<br/>+ schema.prisma]
Commit --> PR[ Pull Request<br/>Code review]
PR --> CICD[⚙️ CI/CD Pipeline<br/>Kiểm tra migration]
CICD --> Staging[🧪 Staging Branch<br/>Auto-apply migration]
PR --> CICD[ CI/CD Pipeline<br/>Kiểm tra migration]
CICD --> Staging[ Staging Branch<br/>Auto-apply migration]
Staging --> StagingTest{✅ Staging<br/>Test OK?}
StagingTest -->|❌ Không| Rollback1[↩️ Rollback staging]
Staging --> StagingTest{ Staging<br/>Test OK?}
StagingTest -->| Không| Rollback1[↩ Rollback staging]
Rollback1 --> Fix
StagingTest -->|✅ Có| Approval[👥 Approval<br/>Production deploy]
Approval --> Prod[🚀 Production Branch<br/>Apply migration]
StagingTest -->| Có| Approval[ Approval<br/>Production deploy]
Approval --> Prod[ Production Branch<br/>Apply migration]
Prod --> ProdTest{✅ Production<br/>OK?}
ProdTest -->|❌ Không| Rollback2[🚨 Emergency Rollback<br/>Restore point-in-time]
ProdTest -->|✅ Có| Complete([✨ Hoàn thành<br/>Migration thành công])
Prod --> ProdTest{ Production<br/>OK?}
ProdTest -->| Không| Rollback2[ Emergency Rollback<br/>Restore point-in-time]
ProdTest -->| Có| Complete([ Hoàn thành<br/>Migration thành công])
style Start fill:#1a1a2e,stroke:#16213e,stroke-width:2px,color:#fff
style Dev fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
@@ -232,37 +232,37 @@ Theo dõi databases qua Neon Console:
```mermaid
flowchart TD
Problem([🚨 Vấn Đề Neon<br/>Không kết nối được?]) --> Type{Loại<br/>Vấn Đề?}
Problem([ Vấn Đề Neon<br/>Không kết nối được?]) --> Type{Loại<br/>Vấn Đề?}
Type -->|🔌 Kết nối| ConnIssue[Vấn Đề Kết Nối]
Type -->|📊 Migration| MigIssue[Vấn Đề Migration]
Type -->|⚡ Hiệu suất| PerfIssue[Vấn Đề Hiệu Suất]
Type -->| Kết nối| ConnIssue[Vấn Đề Kết Nối]
Type -->| Migration| MigIssue[Vấn Đề Migration]
Type -->| Hiệu suất| PerfIssue[Vấn Đề Hiệu Suất]
ConnIssue --> CheckURL{Connection<br/>String OK?}
CheckURL -->|❌ Không| FixURL[✅ Kiểm tra:<br/>• sslmode=require<br/>• Credentials đúng<br/>• Endpoint active]
CheckURL -->|✅ Có| CheckIP{IP trong<br/>allowlist?}
CheckIP -->|❌ Không| AddIP[✅ Thêm IP vào<br/>Neon Console]
CheckIP -->|✅ Có| CheckBranch{Branch<br/>active?}
CheckBranch -->|❌ Không| ActivateBranch[✅ Kích hoạt branch<br/>hoặc tạo mới]
CheckBranch -->|✅ Có| ContactSupport[📞 Liên hệ<br/>Neon Support]
CheckURL -->| Không| FixURL[ Kiểm tra:<br/>• sslmode=require<br/>• Credentials đúng<br/>• Endpoint active]
CheckURL -->| Có| CheckIP{IP trong<br/>allowlist?}
CheckIP -->| Không| AddIP[ Thêm IP vào<br/>Neon Console]
CheckIP -->| Có| CheckBranch{Branch<br/>active?}
CheckBranch -->| Không| ActivateBranch[ Kích hoạt branch<br/>hoặc tạo mới]
CheckBranch -->| Có| ContactSupport[ Liên hệ<br/>Neon Support]
MigIssue --> CheckEnv{DATABASE_URL<br/>đã set?}
CheckEnv -->|❌ Không| SetEnv[✅ Export<br/>DATABASE_URL]
CheckEnv -->|✅ Có| CheckSchema{Schema<br/>đồng bộ?}
CheckSchema -->|❌ Không| ResetMig[✅ DEV ONLY:<br/>prisma migrate reset]
CheckSchema -->|✅ Có| CheckTimeout{Connection<br/>timeout?}
CheckTimeout -->|✅ Có| AddPooling[✅ Thêm<br/>?pgbouncer=true]
CheckTimeout -->|❌ Không| CheckLimits[✅ Kiểm tra<br/>Neon Console limits]
CheckEnv -->| Không| SetEnv[ Export<br/>DATABASE_URL]
CheckEnv -->| Có| CheckSchema{Schema<br/>đồng bộ?}
CheckSchema -->| Không| ResetMig[ DEV ONLY:<br/>prisma migrate reset]
CheckSchema -->| Có| CheckTimeout{Connection<br/>timeout?}
CheckTimeout -->| Có| AddPooling[ Thêm<br/>?pgbouncer=true]
CheckTimeout -->| Không| CheckLimits[ Kiểm tra<br/>Neon Console limits]
PerfIssue --> HasPooling{Connection<br/>Pooling ON?}
HasPooling -->|❌ Không| EnablePooling[✅ Thêm<br/>?pgbouncer=true]
HasPooling -->|✅ Có| CheckQueries{Slow<br/>queries?}
CheckQueries -->|✅ Có| AnalyzeQueries[✅ Neon Console<br/>Query Analyzer]
CheckQueries -->|❌ Không| CheckIndexes{Indexes<br/>tối ưu?}
CheckIndexes -->|❌ Không| AddIndexes[✅ Thêm indexes<br/>vào Prisma schema]
CheckIndexes -->|✅ Có| ScalePlan[✅ Nâng cấp<br/>Neon plan]
HasPooling -->| Không| EnablePooling[ Thêm<br/>?pgbouncer=true]
HasPooling -->| Có| CheckQueries{Slow<br/>queries?}
CheckQueries -->| Có| AnalyzeQueries[ Neon Console<br/>Query Analyzer]
CheckQueries -->| Không| CheckIndexes{Indexes<br/>tối ưu?}
CheckIndexes -->| Không| AddIndexes[ Thêm indexes<br/>vào Prisma schema]
CheckIndexes -->| Có| ScalePlan[ Nâng cấp<br/>Neon plan]
FixURL --> Solved([✨ Đã giải quyết])
FixURL --> Solved([ Đã giải quyết])
AddIP --> Solved
ActivateBranch --> Solved
ContactSupport --> Solved
@@ -367,7 +367,7 @@ flowchart TD
4. **Backup thường xuyên**: Sử dụng automatic backups của Neon
5. **Theo dõi usage**: Kiểm tra Neon Console thường xuyên
## 💡 Quick Tips
## Quick Tips
### Mermaid Diagram Colors
@@ -375,11 +375,11 @@ Tất cả Mermaid diagrams sử dụng **bảng màu tối (dark palette)** v
| Loại Node | Màu | Mục Đích |
|-----------|-----|----------|
| 🔵 **Primary** | `#0f3460` | Actions, Steps, Solutions |
| 🟣 **Purple** | `#533483` | Staging, Categories, Warnings |
| 🔴 **Red** | `#c72c41` | Production, Errors, Critical |
| 🔘 **Dark** | `#1a1a2e` | Backgrounds, Containers |
| ⚫ **Darker** | `#16213e` | Decision Points, Questions |
| **Primary** | `#0f3460` | Actions, Steps, Solutions |
| **Purple** | `#533483` | Staging, Categories, Warnings |
| **Red** | `#c72c41` | Production, Errors, Critical |
| **Dark** | `#1a1a2e` | Backgrounds, Containers |
| **Darker** | `#16213e` | Decision Points, Questions |
**Pattern:**
```css
@@ -390,28 +390,28 @@ style NodeName fill:#0f3460,stroke:#16213e,stroke-width:2px,color:#fff
| Vấn đề | Giải pháp nhanh | Emoji |
|--------|----------------|-------|
| Connection timeout | Thêm `?pgbouncer=true` | ⚡ |
| SSL error | Thêm `?sslmode=require` | 🔒 |
| IP bị chặn | Thêm IP vào Neon Console allowlist | 🚫 |
| Branch inactive | Kích hoạt lại trong Console | 💤 |
| Migration lỗi | Reset dev: `prisma migrate reset` | 🔄 |
| Slow queries | Bật Query Analyzer trong Console | 🐌 |
| Storage đầy | Nâng cấp plan hoặc cleanup data | 💾 |
| Connection timeout | Thêm `?pgbouncer=true` | |
| SSL error | Thêm `?sslmode=require` | |
| IP bị chặn | Thêm IP vào Neon Console allowlist | |
| Branch inactive | Kích hoạt lại trong Console | |
| Migration lỗi | Reset dev: `prisma migrate reset` | |
| Slow queries | Bật Query Analyzer trong Console | |
| Storage đầy | Nâng cấp plan hoặc cleanup data | |
### Visual Indicators
- 🌐 = Neon Project
- 🔧 = Development
- 🧪 = Staging
- 🚀 = Production
- ⚡ = Performance/Speed
- 🔌 = Connection
- 💾 = Storage/Backup
- 🔄 = Retry/Rollback
- ✅ = Success/OK
- ❌ = Error/Failed
- 🚨 = Critical/Emergency
- 📊 = Metrics/Analytics
- = Neon Project
- = Development
- = Staging
- = Production
- = Performance/Speed
- = Connection
- = Storage/Backup
- = Retry/Rollback
- = Success/OK
- = Error/Failed
- = Critical/Emergency
- = Metrics/Analytics
## Tài Nguyên

42
docs/vi/guides/observability.md
View File

@@ -6,23 +6,23 @@ Tài liệu này hướng dẫn cách sử dụng stack observability (Grafana,
```mermaid
graph TB
subgraph Services["🚀 Microservices"]
subgraph Services[" Microservices"]
IAM["IAM Service"]
User["User Service"]
Order["Order Service"]
end
subgraph Collectors["📊 Data Collectors"]
Prometheus["Prometheus<br/>📈 Metrics Collector"]
Promtail["Promtail<br/>📝 Log Collector"]
subgraph Collectors[" Data Collectors"]
Prometheus["Prometheus<br/> Metrics Collector"]
Promtail["Promtail<br/> Log Collector"]
end
subgraph Storage["💾 Storage"]
subgraph Storage[" Storage"]
PrometheusDB["Prometheus TSDB<br/>Metrics Storage"]
Loki["Loki<br/>Log Aggregation"]
end
subgraph Visualization["📊 Visualization"]
subgraph Visualization[" Visualization"]
Grafana["Grafana<br/>Dashboard & Analytics"]
end
@@ -142,16 +142,16 @@ Trong giao diện **Explore** với **Prometheus** đã chọn:
- **Promtail**: Rules để quét log được cấu hình tại `infra/observability/promtail/promtail-config.yml`.
- **Grafana**: Cấu hình datasources và dashboards provisioning nằm trong `infra/observability/grafana/`.
## 💡 Quick Tips
## Quick Tips
### Troubleshooting chung
| Vấn đề | Triệu chứng | Giải pháp |
|--------|-------------|-----------|
| ⚠️ Không thấy logs | Grafana Explore không hiển thị logs | Kiểm tra Promtail đang chạy: `docker ps \| grep promtail` |
| 📊 Metrics bị thiếu | Services không xuất hiện trong Prometheus targets | Kiểm tra `/metrics` endpoint của service |
| 🔴 Container không khởi động | `docker ps` không show container | Xem logs: `docker-compose logs <service-name>` |
| 🌐 Network issue | Services không kết nối được | Tạo network: `docker network create microservices-network` |
| Không thấy logs | Grafana Explore không hiển thị logs | Kiểm tra Promtail đang chạy: `docker ps \| grep promtail` |
| Metrics bị thiếu | Services không xuất hiện trong Prometheus targets | Kiểm tra `/metrics` endpoint của service |
| Container không khởi động | `docker ps` không show container | Xem logs: `docker-compose logs <service-name>` |
| Network issue | Services không kết nối được | Tạo network: `docker network create microservices-network` |
### LogQL Quick Reference
@@ -172,11 +172,11 @@ container_memory_usage_bytes{container="iam-service"} # Memory usage của IAM
### Best Practices
- ✅ **Naming Convention**: Đặt tên metrics theo pattern `<namespace>_<subsystem>_<name>_<unit>`
- ✅ **Labels**: Sử dụng labels để phân loại dữ liệu (environment, service, instance)
- ✅ **Retention**: Cấu hình retention phù hợp cho Prometheus và Loki
- ✅ **Alerting**: Thiết lập alerts cho các metrics quan trọng
- ⚠️ **Cardinality**: Tránh sử dụng quá nhiều unique labels (gây tăng cardinality)
- **Naming Convention**: Đặt tên metrics theo pattern `<namespace>_<subsystem>_<name>_<unit>`
- **Labels**: Sử dụng labels để phân loại dữ liệu (environment, service, instance)
- **Retention**: Cấu hình retention phù hợp cho Prometheus và Loki
- **Alerting**: Thiết lập alerts cho các metrics quan trọng
- **Cardinality**: Tránh sử dụng quá nhiều unique labels (gây tăng cardinality)
### Color Palette Reference
@@ -184,11 +184,11 @@ Diagram sử dụng bảng màu tối để dễ nhìn:
| Loại Component | Fill Color | Stroke Color | Mục đích |
|----------------|------------|--------------|----------|
| 🚀 Services | `#e94560` | `#c81e3b` | Microservices (đỏ) |
| 📊 Collectors | `#f39c12` | `#d68910` | Thu thập dữ liệu (cam) |
| 💾 Storage | `#3498db` | `#2874a6` | Lưu trữ (xanh dương) |
| 📊 Visualization | `#9b59b6` | `#7d3c98` | Trực quan hóa (tím) |
| 📦 Subgraphs | `#1a1a2e` - `#533483` | `#16213e` - `#0f3460` | Nhóm logic |
| Services | `#e94560` | `#c81e3b` | Microservices (đỏ) |
| Collectors | `#f39c12` | `#d68910` | Thu thập dữ liệu (cam) |
| Storage | `#3498db` | `#2874a6` | Lưu trữ (xanh dương) |
| Visualization | `#9b59b6` | `#7d3c98` | Trực quan hóa (tím) |
| Subgraphs | `#1a1a2e` - `#533483` | `#16213e` - `#0f3460` | Nhóm logic |
**Tất cả text sử dụng `color:#ffffff` (trắng) để dễ đọc trên nền tối**

66
docs/vi/guides/troubleshooting.md
View File

@@ -46,42 +46,42 @@ Khi có sự cố, hãy làm theo danh sách kiểm tra sau:
```mermaid
flowchart TD
Start([🔍 Phát Hiện Sự Cố]) --> CheckStatus{Kiểm tra<br/>Trạng thái Service}
Start([ Phát Hiện Sự Cố]) --> CheckStatus{Kiểm tra<br/>Trạng thái Service}
CheckStatus -->|Tất cả Running| CheckLogs[📋 Xem Logs]
CheckStatus -->|Một số Down| IdentifyService[🎯 Xác định Service<br/>Bị Lỗi]
CheckStatus -->|Tất cả Running| CheckLogs[ Xem Logs]
CheckStatus -->|Một số Down| IdentifyService[ Xác định Service<br/>Bị Lỗi]
IdentifyService --> ServiceType{Loại Service?}
ServiceType -->|Infrastructure| InfraCheck[🔧 Kiểm tra<br/>Infrastructure]
ServiceType -->|Application| AppCheck[⚙️ Kiểm tra<br/>Application]
ServiceType -->|Infrastructure| InfraCheck[ Kiểm tra<br/>Infrastructure]
ServiceType -->|Application| AppCheck[ Kiểm tra<br/>Application]
InfraCheck --> DBCheck{Database?}
InfraCheck --> RedisCheck{Redis?}
InfraCheck --> TraefikCheck{Traefik?}
DBCheck -->|Có| DBSolution[✅ Kiểm tra DATABASE_URL<br/>✅ Verify kết nối Neon<br/>✅ Kiểm tra IP whitelist]
RedisCheck -->|Có| RedisSolution[✅ Restart Redis<br/>✅ Kiểm tra port mapping<br/>✅ Verify connection string]
TraefikCheck -->|Có| TraefikSolution[✅ Kiểm tra labels<br/>✅ Verify PathPrefix<br/>✅ Kiểm tra health status]
DBCheck -->|Có| DBSolution[ Kiểm tra DATABASE_URL<br/> Verify kết nối Neon<br/> Kiểm tra IP whitelist]
RedisCheck -->|Có| RedisSolution[ Restart Redis<br/> Kiểm tra port mapping<br/> Verify connection string]
TraefikCheck -->|Có| TraefikSolution[ Kiểm tra labels<br/> Verify PathPrefix<br/> Kiểm tra health status]
AppCheck --> ErrorType{Loại Lỗi?}
ErrorType -->|Config| ConfigFix[✅ Kiểm tra .env variables<br/>✅ Chạy init-project.sh]
ErrorType -->|Prisma| PrismaFix[✅ Kiểm tra migrations<br/>✅ Regenerate client<br/>✅ Reset database]
ErrorType -->|Auth| AuthFix[✅ Kiểm tra token expiry<br/>✅ Verify keys<br/>✅ Sync thời gian Docker]
ErrorType -->|Config| ConfigFix[ Kiểm tra .env variables<br/> Chạy init-project.sh]
ErrorType -->|Prisma| PrismaFix[ Kiểm tra migrations<br/> Regenerate client<br/> Reset database]
ErrorType -->|Auth| AuthFix[ Kiểm tra token expiry<br/> Verify keys<br/> Sync thời gian Docker]
CheckLogs --> LogAnalysis{Log Hiện<br/>Lỗi?}
LogAnalysis -->|Có| ErrorType
LogAnalysis -->|Không| ConnCheck[🌐 Kiểm tra Kết nối]
LogAnalysis -->|Không| ConnCheck[ Kiểm tra Kết nối]
ConnCheck --> GatewayTest{Gateway<br/>Truy Cập Được?}
GatewayTest -->|Không| TraefikCheck
GatewayTest -->|Có| ServiceTest{Service<br/>Truy Cập Được?}
ServiceTest -->|Không| AppCheck
ServiceTest -->|Có| Resolved([✨ Đã Giải Quyết])
ServiceTest -->|Có| Resolved([ Đã Giải Quyết])
DBSolution --> Restart[🔄 Restart Services]
DBSolution --> Restart[ Restart Services]
RedisSolution --> Restart
TraefikSolution --> Restart
ConfigFix --> Restart
@@ -90,7 +90,7 @@ flowchart TD
Restart --> Verify{Đã Sửa<br/>Xong?}
Verify -->|Có| Resolved
Verify -->|Không| DeepDebug[🛠️ Debug Sâu<br/>Hơn]
Verify -->|Không| DeepDebug[ Debug Sâu<br/>Hơn]
DeepDebug --> ContainerShell[Truy cập Container Shell]
DeepDebug --> PrismaStudio[Dùng Prisma Studio]
@@ -307,7 +307,7 @@ docker-compose down -v
## Mẹo Nhanh (Quick Tips)
### 🎯 Lệnh Debug Nhanh
### Lệnh Debug Nhanh
```bash
# Kiểm tra nhanh các service bị lỗi
@@ -329,7 +329,7 @@ docker stats --no-stream
docker system prune -a --volumes
```
### 🔍 Các Pattern Lỗi Thường Gặp
### Các Pattern Lỗi Thường Gặp
| Pattern Lỗi | Nguyên nhân Có thể | Cách Sửa Nhanh |
|-------------|-------------------|----------------|
@@ -341,13 +341,13 @@ docker system prune -a --volumes
| `502 Bad Gateway` | Service bị crash | Xem logs service |
| `Config validation error` | Thiếu biến môi trường | Chạy `init-project.sh` |
### 📋 Mẹo Phân Tích Logs
### Mẹo Phân Tích Logs
**Những gì cần tìm trong logs:**
- ✅ `Server listening on port XXXX` = Service khởi động thành công
- ⚠️ `Warning:` = Vấn đề không nghiêm trọng
- ❌ `Error:` = Vấn đề nghiêm trọng cần xử lý
- 🔍 `Trace:` = Chi tiết luồng thực thi
- `Server listening on port XXXX` = Service khởi động thành công
- `Warning:` = Vấn đề không nghiêm trọng
- `Error:` = Vấn đề nghiêm trọng cần xử lý
- `Trace:` = Chi tiết luồng thực thi
**Các pattern grep hữu ích:**
```bash
@@ -364,7 +364,7 @@ docker-compose logs | grep -i "prisma\|database\|p1001\|p1003"
docker-compose logs | grep -i "unauthorized\|401\|jwt\|token"
```
### 💾 Quản Lý Tài Nguyên
### Quản Lý Tài Nguyên
**Docker Resources Khuyến nghị:**
- **RAM**: Tối thiểu 4GB, Khuyến nghị 8GB
@@ -388,14 +388,14 @@ docker container prune
# Xóa images không dùng
docker image prune -a
# Xóa volumes không dùng (⚠️ mất dữ liệu!)
# Xóa volumes không dùng ( mất dữ liệu!)
docker volume prune
# Tùy chọn hạt nhân (⚠️ xóa mọi thứ!)
# Tùy chọn hạt nhân ( xóa mọi thứ!)
docker system prune -a --volumes
```
### 🛡️ Best Practices
### Best Practices
1. **Luôn kiểm tra logs trước** khi thay đổi gì
2. **Dùng Traefik Dashboard** (http://localhost:8080) để verify routing
@@ -406,16 +406,16 @@ docker system prune -a --volumes
7. **Giữ services đang chạy** mà bạn đang develop
8. **Tắt services** không dùng để tiết kiệm tài nguyên
### 🎨 Visual Indicators
### Visual Indicators
Khi đọc logs, chú ý các pattern sau:
- 🟢 `[INFO]` = Hoạt động bình thường
- 🟡 `[WARN]` = Cần theo dõi
- 🔴 `[ERROR]` = Cần xử lý ngay
- 🔵 `[DEBUG]` = Thông tin chi tiết
- ⚡ `[TRACE]` = Luồng thực thi rất chi tiết
- `[INFO]` = Hoạt động bình thường
- `[WARN]` = Cần theo dõi
- `[ERROR]` = Cần xử lý ngay
- `[DEBUG]` = Thông tin chi tiết
- `[TRACE]` = Luồng thực thi rất chi tiết
### 🔗 Tài Liệu Liên Quan
### Tài Liệu Liên Quan
- [Hướng dẫn Local Deployment](./local-deployment.md) - Hướng dẫn setup
- [Hướng dẫn Development](./development.md) - Workflow phát triển