pos-system/docs/vi/skills/microservices-development-process.md

# Quy Trình Phát Triển Microservices (Microservices Development Process)

Standard development process for creating and maintaining microservices in GoodGo platform. Use when creating new services, migrating services, refactoring services, or planning service implementations.
> Quy trình phát triển chuẩn để tạo và duy trì microservices trong nền tảng GoodGo. Sử dụng khi tạo services mới, migrate services, refactor services, hoặc lập kế hoạch implement services.

## Tổng Quan

The microservices development process provides a structured 8-phase approach to building services, ensuring comprehensive coverage from planning to deployment.

Quy trình phát triển microservices cung cấp cách tiếp cận có cấu trúc 8 giai đoạn để xây dựng services, đảm bảo bao phủ toàn diện từ lập kế hoạch đến triển khai.

## Khi Nào Sử Dụng

Use this skill when:
- Creating a new microservice from scratch
- Migrating or refactoring an existing service
- Planning service implementation with multiple phases
- Ensuring comprehensive coverage of all development aspects

Sử dụng skill này khi:
- Tạo microservice mới từ đầu
- Migrate hoặc refactor service hiện có
- Lập kế hoạch implement service với nhiều giai đoạn
- Đảm bảo bao phủ toàn diện tất cả các khía cạnh phát triển

## Quy Trình 8 Giai Đoạn

The microservices development process follows these phases:
Quy trình phát triển microservices theo các giai đoạn sau:

1. **Planning & Impact Analysis** - Define scope, impact, dependencies / Định nghĩa scope, impact, dependencies
2. **Foundation Setup** - Service structure, configs, infrastructure / Cấu trúc service, configs, infrastructure
3. **Core Implementation** - Business logic, APIs, data layer / Business logic, APIs, data layer
4. **Integration** - Routes, middleware, external services / Routes, middleware, external services
5. **Testing** - Unit, integration, E2E tests / Unit, integration, E2E tests
6. **Documentation** - API docs, README, guides / API docs, README, guides
7. **Cleanup & Verification** - Remove temporary files, verify completeness / Xóa file tạm, xác minh hoàn chỉnh
8. **Deployment** - Staging deployment, production deployment / Staging deployment, production deployment

### Biểu Đồ Luồng Quy Trình / Process Flow Diagram

This diagram shows the complete 8-phase development process with decision points and feedback loops.
Biểu đồ này hiển thị quy trình phát triển 8 giai đoạn đầy đủ với các điểm quyết định và vòng lặp phản hồi.

```mermaid
graph TD
    Start([Start: New Service Requirements]) --> Phase1[Phase 1: Planning & Impact Analysis]
    Phase1 --> ImpactCheck{Impact Analysis<br/>Complete?}
    ImpactCheck -->|No| Phase1
    ImpactCheck -->|Yes| Phase2[Phase 2: Foundation Setup]
    
    Phase2 --> FoundationCheck{Service Starts<br/>& Health Check Passes?}
    FoundationCheck -->|No| Phase2
    FoundationCheck -->|Yes| Phase3[Phase 3: Core Implementation]
    
    Phase3 --> ImplementationCheck{Business Logic<br/>Implemented?}
    ImplementationCheck -->|No| Phase3
    ImplementationCheck -->|Yes| Phase4[Phase 4: Integration]
    
    Phase4 --> IntegrationCheck{Routes & Middleware<br/>Working?}
    IntegrationCheck -->|No| Phase4
    IntegrationCheck -->|Yes| Phase5[Phase 5: Testing]
    
    Phase5 --> TestCheck{Tests Pass<br/>& Coverage Met?}
    TestCheck -->|No| Phase5
    TestCheck -->|Yes| Phase6[Phase 6: Documentation]
    
    Phase6 --> DocCheck{Docs<br/>Complete?}
    DocCheck -->|No| Phase6
    DocCheck -->|Yes| Phase7[Phase 7: Cleanup & Verification]
    
    Phase7 --> VerificationCheck{All Checks<br/>Pass?}
    VerificationCheck -->|No| Phase7
    VerificationCheck -->|Yes| Phase8[Phase 8: Deployment]
    
    Phase8 --> DeployCheck{Staging<br/>Deployed?}
    DeployCheck -->|No| Phase8
    DeployCheck -->|Yes| Production{Deploy to<br/>Production?}
    Production -->|Yes| ProdDeploy[Production Deployment]
    Production -->|No| Complete([Complete])
    ProdDeploy --> Complete
    
    style Phase1 fill:#e1f5ff
    style Phase2 fill:#fff4e1
    style Phase3 fill:#f0e1ff
    style Phase4 fill:#e1ffe1
    style Phase5 fill:#ffe1e1
    style Phase6 fill:#e1ffff
    style Phase7 fill:#fff0e1
    style Phase8 fill:#ffe1f5
    style Complete fill:#d4edda
```

### Luồng Chi Tiết Các Giai Đoạn / Detailed Phase Flow

This diagram breaks down the tasks within each phase and shows the sequential flow between phases.
Biểu đồ này phân tích các nhiệm vụ trong từng giai đoạn và hiển thị luồng tuần tự giữa các giai đoạn.

```mermaid
graph LR
    subgraph Planning["Phase 1: Planning"]
        P1A[Define Scope] --> P1B[Impact Analysis]
        P1B --> P1C[Dependencies Map]
        P1C --> P1D[Acceptance Criteria]
    end
    
    subgraph Foundation["Phase 2: Foundation"]
        F2A[Copy Template] --> F2B[Configure Package]
        F2B --> F2C[Setup Database]
        F2C --> F2D[Configure Docker]
        F2D --> F2E[Setup Traefik]
    end
    
    subgraph Implementation["Phase 3: Implementation"]
        I3A[DTOs] --> I3B[Repository]
        I3B --> I3C[Service]
        I3C --> I3D[Controller]
        I3D --> I3E[Module]
    end
    
    subgraph Integration["Phase 4: Integration"]
        IN4A[Register Routes] --> IN4B[Setup Middleware]
        IN4B --> IN4C[External Services]
        IN4C --> IN4D[Health Checks]
    end
    
    subgraph Testing["Phase 5: Testing"]
        T5A[Unit Tests] --> T5B[Integration Tests]
        T5B --> T5C[E2E Tests]
        T5C --> T5D[Coverage Check]
    end
    
    subgraph Documentation["Phase 6: Documentation"]
        D6A[README] --> D6B[API Docs]
        D6B --> D6C[Architecture Docs]
    end
    
    subgraph Cleanup["Phase 7: Cleanup"]
        C7A[Remove Temp Files] --> C7B[Update References]
        C7B --> C7C[Verify Everything]
    end
    
    subgraph Deployment["Phase 8: Deployment"]
        DEP8A[Staging] --> DEP8B[Verification]
        DEP8B --> DEP8C[Production]
    end
    
    Planning --> Foundation
    Foundation --> Implementation
    Implementation --> Integration
    Integration --> Testing
    Testing --> Documentation
    Documentation --> Cleanup
    Cleanup --> Deployment
    
    style Planning fill:#e1f5ff
    style Foundation fill:#fff4e1
    style Implementation fill:#f0e1ff
    style Integration fill:#e1ffe1
    style Testing fill:#ffe1e1
    style Documentation fill:#e1ffff
    style Cleanup fill:#fff0e1
    style Deployment fill:#ffe1f5
```

## Các Giai Đoạn Chính

### Phase 1: Planning & Impact Analysis / Giai Đoạn 1: Lập Kế Hoạch & Phân Tích Tác Động

**Scope Definition / Định Nghĩa Scope:**
- Service Purpose: What business capability does it provide? / Mục đích service: Cung cấp khả năng kinh doanh gì?
- API Surface: What endpoints are needed? / API Surface: Cần endpoints nào?
- Data Models: What data structures are required? / Data Models: Cần cấu trúc dữ liệu nào?
- Dependencies: What services/packages does it depend on? / Dependencies: Phụ thuộc vào services/packages nào?

**Impact Analysis Checklist / Checklist Phân Tích Tác Động:**
- [ ] Service directory: `services/service-name/`
- [ ] Prisma schema: `services/service-name/prisma/schema.prisma`
- [ ] Dockerfile: `services/service-name/Dockerfile`
- [ ] Update `deployments/local/docker-compose.yml`
- [ ] Update `infra/traefik/dynamic/routes.yml`

### Phase 2: Foundation Setup / Giai Đoạn 2: Thiết Lập Nền Tảng

**Service Structure / Cấu Trúc Service:**
```bash
# EN: Copy template
# VI: Copy template
cp -r services/_template services/new-service-name
cd services/new-service-name
```

**Acceptance Criteria / Tiêu Chí Chấp Nhận:**
- [ ] Service starts: `pnpm dev` (health check passes) / Service khởi động: `pnpm dev` (health check pass)
- [ ] Docker build succeeds / Docker build thành công
- [ ] Service accessible via Traefik / Service có thể truy cập qua Traefik

### Phase 3: Core Implementation / Giai Đoạn 3: Implementation Cốt Lõi

**Implementation Order / Thứ Tự Implementation:**
1. **DTOs** - Zod schemas for validation / Zod schemas cho validation
2. **Repository** - Prisma-based data access / Data access dựa trên Prisma
3. **Service** - Business logic / Business logic
4. **Controller** - HTTP request handling / Xử lý HTTP requests
5. **Module** - Wire up components / Kết nối các components

**Luồng Implementation / Implementation Flow:**

This diagram shows the step-by-step implementation order for each feature module within Phase 3.
Biểu đồ này hiển thị thứ tự implementation từng bước cho mỗi feature module trong Giai đoạn 3.

```mermaid
graph TD
    Start[Start Implementation] --> DTOs[1. Create DTOs<br/>Zod Validation Schemas]
    DTOs --> Repo[2. Create Repository<br/>Prisma Data Access]
    Repo --> Service[3. Create Service<br/>Business Logic]
    Service --> Controller[4. Create Controller<br/>HTTP Handlers]
    Controller --> Module[5. Create Module<br/>Wire Up Components]
    Module --> Test[Manual Testing]
    Test --> Pass{Tests Pass?}
    Pass -->|No| Repo
    Pass -->|Yes| Next[Next Feature Module]
    
    style DTOs fill:#e1f5ff
    style Repo fill:#fff4e1
    style Service fill:#f0e1ff
    style Controller fill:#e1ffe1
    style Module fill:#ffe1e1
```

### Phase 4: Integration / Giai Đoạn 4: Tích Hợp

**Required Middlewares / Middlewares Bắt Buộc:**
1. Correlation middleware
2. Logging middleware
3. Metrics middleware
4. CORS middleware
5. Rate limiting middleware
6. Authentication middleware (if needed) / (nếu cần)
7. Error middleware (always last) / (luôn cuối cùng)

### Phase 5: Testing / Giai Đoạn 5: Kiểm Thử

**Test Coverage Targets / Mục Tiêu Test Coverage:**
- Minimum: 70% coverage / Tối thiểu: 70% coverage
- Critical paths: 90%+ coverage / Đường dẫn quan trọng: 90%+ coverage
- Repositories: 80%+ coverage
- Services: 80%+ coverage

**Testing Checklist / Checklist Testing:**
- [ ] Unit tests pass / Unit tests pass
- [ ] Integration tests pass / Integration tests pass
- [ ] E2E tests pass / E2E tests pass
- [ ] Coverage meets thresholds / Coverage đạt ngưỡng

### Phase 6: Documentation / Giai Đoạn 6: Tài Liệu

**Required Documentation / Tài Liệu Bắt Buộc:**
- Service README (bilingual EN/VI) / README service (song ngữ EN/VI)
- Swagger/OpenAPI spec / Swagger/OpenAPI spec
- Architecture docs (if complex) / Tài liệu kiến trúc (nếu phức tạp)

### Phase 7: Cleanup & Verification / Giai Đoạn 7: Dọn Dẹp & Xác Minh

**Luồng Quy Trình Xác Minh / Verification Process Flow:**

This diagram illustrates the cleanup and verification workflow for Phase 7, including the decision point for migrations and the comprehensive verification steps.
Biểu đồ này minh họa quy trình dọn dẹp và xác minh cho Giai đoạn 7, bao gồm điểm quyết định cho migrations và các bước xác minh toàn diện.

```mermaid
graph TD
    Start[Start Cleanup] --> Remove[Remove Temporary Files]
    Remove --> Update{Is Migration?}
    Update -->|Yes| RefUpdate[Update References<br/>grep & replace]
    Update -->|No| Verify[Run Verification]
    RefUpdate --> Verify
    
    Verify --> TypeCheck[TypeScript Check]
    TypeCheck --> LintCheck[Lint Check]
    LintCheck --> TestCheck[Test Check]
    TestCheck --> BuildCheck[Build Check]
    BuildCheck --> DockerCheck[Docker Build]
    DockerCheck --> HealthCheck[Health Check]
    HealthCheck --> TraefikCheck[Traefik Check]
    TraefikCheck --> AllPass{All Pass?}
    
    AllPass -->|No| Fix[Fix Issues]
    Fix --> Verify
    AllPass -->|Yes| Complete[Phase Complete]
    
    style Remove fill:#ffe1e1
    style RefUpdate fill:#fff4e1
    style Verify fill:#e1ffe1
    style Complete fill:#d4edda
```

**Verification Steps / Các Bước Xác Minh:**
- [ ] TypeScript check: `pnpm typecheck` / Kiểm tra TypeScript
- [ ] Lint check: `pnpm lint` / Kiểm tra lint
- [ ] Test check: `pnpm test` / Kiểm tra test
- [ ] Build check: `pnpm build` / Kiểm tra build
- [ ] Docker build succeeds / Docker build thành công

### Phase 8: Deployment / Giai Đoạn 8: Triển Khai

**Staging Deployment / Triển Khai Staging:**
```bash
# EN: Build and push Docker image
# VI: Build và push Docker image
docker build -t goodgo/service-name:latest .
docker push goodgo/service-name:latest

# EN: Apply Kubernetes configs
# VI: Áp dụng configs Kubernetes
kubectl apply -f deployments/staging/kubernetes/service-name.yaml
```

## Best Practices / Thực Hành Tốt

1. **Always Plan First**: Complete impact analysis before coding / Luôn lập kế hoạch trước: Hoàn thành phân tích tác động trước khi code
2. **Follow Phases**: Don't skip verification steps / Tuân theo các giai đoạn: Không bỏ qua các bước xác minh
3. **Test Early**: Write tests alongside implementation / Test sớm: Viết tests cùng với implementation
4. **Document as You Go**: Don't leave documentation for the end / Tài liệu khi làm: Không để tài liệu đến cuối
5. **Verify Comprehensively**: Use checklists to ensure nothing is missed / Xác minh toàn diện: Sử dụng checklists để đảm bảo không bỏ sót

## Common Pitfalls to Avoid / Các Lỗi Thường Gặp Cần Tránh

1. **Skipping Impact Analysis**: Leads to missing updates / Bỏ qua phân tích tác động: Dẫn đến thiếu cập nhật
2. **No Verification Steps**: Misses broken references / Không có bước xác minh: Bỏ sót references bị hỏng
3. **Incomplete Testing**: Missing edge cases / Testing không đầy đủ: Thiếu edge cases
4. **Poor Documentation**: Makes maintenance difficult / Tài liệu kém: Làm khó bảo trì

## Skills Liên Quan

- [Project Rules](./project-rules.md) - Architecture and conventions / Kiến trúc và conventions
- [API Design](./api-design.md) - API design patterns / Các patterns thiết kế API
- [Testing Patterns](./testing-patterns.md) - Testing best practices / Best practices về testing
- [Documentation](./documentation.md) - Documentation guidelines / Hướng dẫn tài liệu
- [Database Prisma](./database-prisma.md) - Prisma patterns / Các patterns Prisma

## Tài Nguyên

- Service Template: `services/_template/` - Template service
- Skill Source: `.cursor/skills/microservices-development-process/SKILL.md` - Source file đầy đủ