pos-system/docs/vi/templates/guide.md

[Guide Title] / [Tiêu đề Hướng dẫn]

EN: Brief English description of what this guide covers VI: Mô tả ngắn gọn bằng tiếng Việt về nội dung hướng dẫn này

Workflow Diagram / Sơ đồ Quy trình

flowchart LR
    Start([Start]) --> Check{Prerequisites<br/>Met?}
    Check -->|No| Install[Install Prerequisites]
    Check -->|Yes| Step1[Step 1: Action]
    Install --> Step1
    Step1 --> Step2[Step 2: Action]
    Step2 --> Step3[Step 3: Action]
    Step3 --> Verify{Verify<br/>Success?}
    Verify -->|No| Troubleshoot[Check Troubleshooting]
    Verify -->|Yes| End([Complete])
    Troubleshoot --> Step1
    
    style Start fill:#e1f5ff
    style End fill:#d4edda
    style Check fill:#fff3cd
    style Verify fill:#fff3cd

Prerequisites / Yêu cầu

EN: Requirements

Before starting this guide, ensure you have:

• Requirement 1 with specific version (e.g., Node.js 20+)
• Requirement 2
• Requirement 3

VI: Yêu cầu

Trước khi bắt đầu hướng dẫn này, hãy đảm bảo bạn có:

• Yêu cầu 1 với phiên bản cụ thể (ví dụ: Node.js 20+)
• Yêu cầu 2
• Yêu cầu 3

Quick Check / Kiểm tra nhanh:

# EN: Verify prerequisites / VI: Xác minh yêu cầu
node --version   # Should be 20 or higher / Phải là 20 hoặc cao hơn
docker --version # Should be installed / Phải được cài đặt
dotnet --version # Should be 10.0+ for .NET services / Phải là 10.0+ cho .NET services

Example: Local Development Setup for Storage Service

# Clone repository
cd /Users/velikho/Desktop/WORKING/Base

# Install dependencies (.NET)
cd services/storage-service-net
dotnet restore

# Setup infrastructure
cd ../../deployments/local
docker-compose up -d postgres redis minio

# Run migrations
cd ../../services/storage-service-net
dotnet ef database update --project src/StorageService.Infrastructure --startup-project src/StorageService.API

Overview / Tổng quan

EN: What You'll Learn

By the end of this guide, you will be able to:

1. Outcome 1
2. Outcome 2
3. Outcome 3

Estimated Time / Thời gian ước tính: X minutes

VI: Bạn Sẽ Học Được Gì

Khi hoàn thành hướng dẫn này, bạn sẽ có thể:

1. Kết quả 1
2. Kết quả 2
3. Kết quả 3

Estimated Time / Thời gian ước tính: X phút

Step-by-Step Guide / Hướng dẫn Từng bước

Step 1 / Bước 1: [Action Title]

EN: English explanation of what this step accomplishes and why it's necessary.

VI: Giải thích tiếng Việt về những gì bước này đạt được và tại sao nó cần thiết.

# EN: Command description / VI: Mô tả lệnh
command-here --flag value

# EN: Expected output / VI: Kết quả mong đợi
Success message or output

Important Notes / Ghi chú quan trọng:

• Note 1 / Ghi chú 1
• Note 2 / Ghi chú 2

File to Create / File cần tạo:

# EN: Create configuration file / VI: Tạo file cấu hình
touch .env.local

Example Content / Nội dung ví dụ:

# EN: Environment variables / VI: Biến môi trường
ASPNETCORE_ENVIRONMENT=Development
DATABASE_URL=postgresql://localhost:5432/mydb
REDIS_URL=redis://localhost:6379
Storage__Provider=minio
Storage__MinIO__Endpoint=localhost:9000
Storage__MinIO__AccessKey=minioadmin
Storage__MinIO__SecretKey=minioadmin

Real-World Example / Ví dụ Thực tế: Traefik Routing Setup

EN: How to configure Traefik routing for a new service.

VI: Cách cấu hình Traefik routing cho service mới.

# docker-compose.yml
services:
  your-service-net:
    build:
      context: ../..
      dockerfile: services/your-service-net/Dockerfile
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - DATABASE_URL=${DATABASE_URL}
    labels:
      # Enable Traefik
      - "traefik.enable=true"
      # Define routing rule
      - "traefik.http.routers.your-service.rule=PathPrefix(`/api/v1/your-service`)"
      # Specify service port
      - "traefik.http.services.your-service.loadbalancer.server.port=8080"
      # Strip prefix middleware
      - "traefik.http.routers.your-service.middlewares=strip-prefix@docker"
    networks:
      - goodgo-network

networks:
  goodgo-network:
    external: true

Expected Result / Kết quả mong đợi:

• ✅ Service accessible at http://localhost/api/v1/your-service
• ✅ Traefik dashboard shows the service at http://localhost:8080
• ✅ Health check endpoint works: http://localhost/api/v1/your-service/health

Step 2 / Bước 2: [Action Title]

EN: Continue with next step explanation...

VI: Tiếp tục với giải thích bước tiếp theo...

// EN: Code example for this step
// VI: Ví dụ code cho bước này
import { Example } from './example';

const instance = new Example();
await instance.initialize();

Expected Result / Kết quả mong đợi:

• ✅ Result 1 / Kết quả 1
• ✅ Result 2 / Kết quả 2

Step 3 / Bước 3: [Action Title]

(Continue pattern for each step)

Verification / Xác minh

EN: How to verify that everything is working correctly.

VI: Cách xác minh mọi thứ đang hoạt động chính xác.

Quick Test / Kiểm tra nhanh

# EN: Run verification command / VI: Chạy lệnh xác minh
curl http://localhost:5000/health

# EN: Expected response / VI: Phản hồi mong đợi
{"status":"ok","timestamp":"2024-01-01T00:00:00.000Z"}

Verification Checklist / Danh sách kiểm tra

For .NET Services:

• Check 1: Service builds successfully / Service build thành công

  dotnet build
  

• Check 2: Database migrations applied / Migrations đã apply

  dotnet ef database update --project src/{ServiceName}.Infrastructure --startup-project src/{ServiceName}.API
  

• Check 3: Service responds to health checks / Service phản hồi health checks

  curl http://localhost:8080/health
  # Expected: {"status":"Healthy"}
  

• Check 4: Swagger UI accessible / Swagger UI truy cập được

  open http://localhost:8080/swagger
  

For Traefik Integration:

• Check 5: Service registered in Traefik / Service đăng ký trong Traefik

  curl http://localhost:8080/api/http/routers
  # Should see your-service router
  

• Check 6: API accessible via gateway / API truy cập được qua gateway

  curl http://localhost/api/v1/your-service/health
  

Common Issues / Vấn đề Thường gặp

Issue 1: [Problem Description]

EN Symptoms: What you see when this problem occurs

VI Triệu chứng: Những gì bạn thấy khi vấn đề này xảy ra

EN Solution:

# Steps to fix
step-1
step-2

VI Giải pháp:

# Các bước để sửa
step-1
step-2

Issue 2: [Problem Description]

(Repeat pattern for common issues)

Troubleshooting Decision Tree / Cây Quyết định Khắc phục

flowchart TD
    Problem[Service not accessible] --> Check1{Traefik<br/>running?}
    Check1 -->|No| Solution1[Start Traefik:<br/>docker-compose up traefik]
    Check1 -->|Yes| Check2{Service<br/>container running?}
    Check2 -->|No| Solution2[Start service:<br/>docker-compose up your-service]
    Check2 -->|Yes| Check3{Database<br/>connection OK?}
    Check3 -->|No| Solution3[Check DATABASE_URL<br/>Run migrations]
    Check3 -->|Yes| Logs[Check service logs:<br/>docker-compose logs -f]
    
    Solution1 --> Resolved{Resolved?}
    Solution2 --> Resolved
    Solution3 --> Resolved
    Logs --> Resolved
    Resolved -->|No| Support[Check documentation:<br/>docs/vi/guides/troubleshooting.md]
    Resolved -->|Yes| Success([Success])
    
    style Problem fill:#f8d7da,stroke:#721c24,stroke-width:2px
    style Success fill:#d4edda,stroke:#155724,stroke-width:2px
    style Check1 fill:#fff3cd,stroke:#856404,stroke-width:2px
    style Check2 fill:#fff3cd,stroke:#856404,stroke-width:2px
    style Check3 fill:#fff3cd,stroke:#856404,stroke-width:2px

Advanced Options / Tùy chọn Nâng cao

EN: Optional advanced configurations or alternative approaches.

VI: Cấu hình nâng cao tùy chọn hoặc cách tiếp cận thay thế.

Option 1 / Tùy chọn 1: [Title]

EN: When to use this option and how to implement it.

VI: Khi nào sử dụng tùy chọn này và cách triển khai.

# Example command
advanced-command --option

Next Steps / Bước Tiếp theo

EN: What to do after completing this guide.

VI: Làm gì sau khi hoàn thành hướng dẫn này.

For .NET Services:

• Next step 1: Implement CQRS Commands
• Next step 2: Add Repository Pattern
• Next step 3: Setup Redis Caching
• Next step 4: Configure Observability

For Deployment:

• Next step 1: Kubernetes Deployment
• Next step 2: Configure CI/CD Pipeline
• Next step 3: Setup Monitoring

Additional Resources / Tài nguyên Bổ sung

Related Documentation / Tài liệu Liên quan

• Related Guide 1 - EN: Description / VI: Mô tả
• Related Architecture - EN: Description / VI: Mô tả
• Related Skill - EN: Description / VI: Mô tả

External Resources / Tài nguyên Bên ngoài

• Official Documentation - EN: What it covers
• Tutorial - EN: Video or article description

FAQ / Câu hỏi Thường gặp

EN: Question 1?

Answer 1 in English.

VI: Câu hỏi 1?

Câu trả lời 1 bằng tiếng Việt.

EN: Question 2?

Answer 2 in English.

VI: Câu hỏi 2?

Câu trả lời 2 bằng tiếng Việt.

---

Difficulty / Độ khó: Beginner/Intermediate/Advanced
Estimated Time / Thời gian ước tính: X minutes
Authors / Tác giả: VelikHo (hongochai10@icloud.com)