From 5c39c4aa93178e495bca96915d070ddb593426f7 Mon Sep 17 00:00:00 2001 From: Ho Ngoc Hai Date: Sun, 18 Jan 2026 22:52:20 +0700 Subject: [PATCH] feat: Define microservices documentation standards and update the bilingual documentation editing workflow. --- .agent/skills/documentation/SKILL.md | 190 ++++++++++++-- .agent/workflows/docs-edit-vi-en.md | 373 +++++++++++++++++++++++++-- 2 files changed, 519 insertions(+), 44 deletions(-) diff --git a/.agent/skills/documentation/SKILL.md b/.agent/skills/documentation/SKILL.md index 6111db66..e13c4c60 100644 --- a/.agent/skills/documentation/SKILL.md +++ b/.agent/skills/documentation/SKILL.md @@ -44,6 +44,34 @@ docs/ | Infrastructure | `infra/[component]/README.md` | Side-by-side bilingual | | API Specs | `docs/en/api/openapi/` | OpenAPI YAML | +### Microservices Documentation Structure / Cấu Trúc Tài Liệu Microservices + +**REQUIRED structure for all microservices:** + +``` +services/my-service-net/ +├── README.md # Service overview with links to EN/VI docs +└── docs/ + ├── en/ # English documentation + │ ├── README.md # English intro, quick start, config + │ ├── ARCHITECTURE.md # Architecture, layers, patterns + │ ├── API.md # API reference (optional) + │ └── [OTHER].md # Service-specific docs + └── vi/ # Vietnamese documentation (mirror EN) + ├── README.md # Vietnamese intro, quick start, config + ├── ARCHITECTURE.md # Architecture, layers, patterns + ├── API.md # API reference (optional) + └── [OTHER].md # Service-specific docs +``` + +**Key Rules:** +- `docs/en/` and `docs/vi/` MUST mirror each other (same files, same structure) +- Each language folder is MONOLINGUAL (no bilingual mixing) +- Service root `README.md` links to both EN/VI documentation +- Mermaid diagrams MUST use dark color palette (see [Mermaid Diagrams Skill](../mermaid-diagrams/SKILL.md)) +- `ARCHITECTURE.md` is MANDATORY, `README.md` is MANDATORY, other files optional + + ## Key Patterns / Mẫu Chính ### Bilingual Format Options / Định Dạng Song Ngữ @@ -133,34 +161,148 @@ Description and commands... - [Related Doc](../path/to/doc.md) ``` -### Architecture Document Template +### Architecture Document Template (Microservices) + +For microservices in `services/[name]/docs/en/ARCHITECTURE.md` or `.../vi/ARCHITECTURE.md`: ```markdown -# Component Architecture +# Architecture Documentation -## Overview -High-level description. +**Service**: [service-name] +**Version**: 1.0 +**Last Updated**: [Date] -## Architecture Diagram -```mermaid -graph TD - A[Component A] --> B[Component B] +## System Overview + +Brief description of the service purpose and capabilities. + +### High-Level Architecture + +\`\`\`mermaid +graph TB + subgraph External + Client[Client/User] + ExtAPI[External API] + end + + subgraph "GoodGo Platform" + Gateway[Traefik Gateway] + + subgraph "[Service Name]" + API[API Layer] + APP[Application Layer] + DOMAIN[Domain Layer] + INFRA[Infrastructure Layer] + end + + PG[(PostgreSQL)] + REDIS[(Redis)] + RABBIT[RabbitMQ] + end + + Client --> Gateway + Gateway --> API + API --> APP + APP --> DOMAIN + APP --> INFRA + INFRA --> PG + INFRA --> REDIS + INFRA --> RABBIT + + style Gateway fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:3px + style API fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px + style DOMAIN fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px + style PG fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px + style REDIS fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px +\`\`\` + +## Clean Architecture Layers + +### 1. API Layer +**Responsibility**: HTTP interface, controllers, background jobs + +**Controllers:** +- `ExampleController` - Description +- `AnotherController` - Description + +### 2. Application Layer +**Responsibility**: Use cases, CQRS commands/queries, handlers + +**Commands (Writes):** +- `CreateEntityCommand` - Description +- `UpdateEntityCommand` - Description + +**Queries (Reads):** +- `GetEntityQuery` - Description +- `ListEntitiesQuery` - Description + +### 3. Domain Layer +**Responsibility**: Business logic, entities, aggregates, domain events + +**Aggregates:** +- `EntityAggregate` - Description of aggregate root and business rules + +### 4. Infrastructure Layer +**Responsibility**: Persistence, external services, integrations + +**Data Access:** +- `ServiceContext` - EF Core DbContext +- Repositories + +**External Services:** +- `ExternalApiClient` - HTTP client for external integration + +## Request Flow + +\`\`\`mermaid +sequenceDiagram + participant Client + participant API + participant Handler + participant Domain + participant DB + + Client->>API: POST /endpoint + API->>Handler: Command/Query + Handler->>Domain: Business Logic + Domain->>DB: Save/Retrieve + DB-->>Domain: Result + Domain-->>Handler: Result + Handler-->>API: Response + API-->>Client: 200 OK + + style API fill:#8E44AD,color:#ECF0F1 + style Handler fill:#3498DB,color:#ECF0F1 + style Domain fill:#E67E22,color:#ECF0F1 + style DB fill:#34495E,color:#ECF0F1 +\`\`\` + +## Database Schema + +Key tables and relationships. + +## Integration Events + +Events published/consumed by this service. + +## Security Considerations + +Authentication, authorization, data protection. + +## Performance Optimization + +Caching, query optimization, background processing. + +## Monitoring & Observability + +Health checks, metrics, logging. + +## References + +- [API Documentation](API.md) +- [Service README](README.md) ``` -## Components - -### Component Name -**Purpose**: What it does -**Technology**: Tech stack -**Dependencies**: What it depends on - -## Design Decisions - -### Decision 1 -**Context**: Why needed -**Decision**: What was decided -**Consequences**: Impact -``` ## Best Practices / Thực Hành Tốt @@ -311,4 +453,8 @@ markdownlint docs/**/*.md - [Project Rules](../project-rules/SKILL.md) - Project structure and standards - [Comment Code](../comment-code/SKILL.md) - Code commenting standards - [API Design](../api-design/SKILL.md) - API documentation +- [Mermaid Diagrams](../mermaid-diagrams/SKILL.md) - Diagram patterns with dark color palette - [Skill Authoring](../skill-authoring/SKILL.md) - How to write skills + +### Workflows +- [/docs-edit-vi-en](../../.agent/workflows/docs-edit-vi-en.md) - Workflow for updating microservices documentation diff --git a/.agent/workflows/docs-edit-vi-en.md b/.agent/workflows/docs-edit-vi-en.md index 3d847905..0183166e 100644 --- a/.agent/workflows/docs-edit-vi-en.md +++ b/.agent/workflows/docs-edit-vi-en.md @@ -1,31 +1,360 @@ --- -description: Workflows chỉnh sửa docs +description: Workflows chỉnh sửa và cập nhật docs của microservices theo chuẩn EN/VI --- -Bước 1 Xóa EN comments bên VI và xoá VI comments bên EN +# Workflow: Microservices Documentation Update -Bước 2 - Làm sạch Code Blocks -⚠️ Lưu ý: Bản VI xóa # EN:, bản EN xóa # VI +## Mục Đích / Purpose -Bước 3 - Chuẩn hóa Header (MỚI) -- Hướng dẫn xóa > **Lưu ý**: / > **Note**: -- Đơn giản hóa header +Workflow này giúp Agent cập nhật và duy trì documentation của microservices theo cấu trúc chuẩn: +``` +docs/ + en/ + ARCHITECTURE.md + README.md + API.md (optional) + ... (other docs) + vi/ + ARCHITECTURE.md + README.md + API.md (optional) + ... (other docs) +README.md (service root) +``` -Bước 4 - Mermaid -- Checklist lỗi cú pháp cụ thể -- Hướng dẫn tạo diagram mới nếu chưa có +## Khi Nào Sử Dụng / When to Use -Bước 5 - Color Palette (CHI TIẾT HƠN) -- Color Palette Reference đầy đủ -- Checklist áp dụng màu chi tiết -- Pattern cho từng loại node -⚠️ Lưu ý: Sử dụng bảng màu tối và text chữ trắng. +- Tạo mới hoặc cập nhật documentation cho microservices +- Tách bilingual docs thành separate EN/VI files +- Đảm bảo docs đồng bộ giữa EN và VI versions +- Chuẩn hóa Mermaid diagrams và color palettes -Bước 6 - Verification (MỚI) -- Checklist kiểm tra chất lượng -- Đảm bảo đồng bộ VI-EN +--- -Quick Tips Section (MỚI) -- Mermaid Common Issues -- Color Pattern quick reference -- Visual indicators (emojis) \ No newline at end of file +## Bước 1: Xác Định Cấu Trúc Hiện Tại / Identify Current Structure + +**Actions:** +1. Kiểm tra cấu trúc `docs/` folder của service +2. Xác định xem có bilingual files hay đã tách riêng EN/VI +3. List tất cả các files cần xử lý + +**Expected Output:** +- Danh sách files hiện tại +- Xác định files nào cần tách/cập nhật + +--- + +## Bước 2: Tạo Cấu Trúc Thư Mục Chuẩn / Create Standard Structure + +**Actions:** +1. Tạo `docs/en/` nếu chưa có +2. Tạo `docs/vi/` nếu chưa có +3. Đảm bảo có `README.md` tại service root + +**Commands:** +```bash +mkdir -p docs/en docs/vi +``` + +--- + +## Bước 3: Tách Nội Dung EN/VI / Separate EN/VI Content + +### 3.1 Xử Lý Bilingual Files (Nếu Có) + +**Pattern 1: Side-by-side format** +```markdown +# Title / Tiêu Đề +Description in English. +Mô tả bằng tiếng Việt. +``` +→ Split into separate files + +**Pattern 2: Sections format** +```markdown +# English Section +... +--- +# Phần Tiếng Việt +... +``` +→ Extract each section to corresponding file + +**Pattern 3: Comments** +```markdown +# EN: English comment +# VI: Vietnamese comment +``` +→ Remove VI comments from EN files, EN comments from VI files + +### 3.2 Làm Sạch Nội Dung / Clean Content + +**For EN files:** +- ✅ Keep: `# EN:` comments (optional) +- ❌ Remove: `# VI:` comments +- ❌ Remove: Vietnamese inline translations (after slashes) +- ❌ Remove: `> **Lưu ý**:` Vietnamese notes + +**For VI files:** +- ✅ Keep: `# VI:` comments (optional) +- ❌ Remove: `# EN:` comments +- ❌ Remove: English inline translations +- ❌ Remove: `> **Note**:` English notes + +**Example:** +```markdown +❌ BAD (in EN file): +## Configuration / Cấu Hình +> **Note**: This is important +> **Lưu ý**: Điều này rất quan trọng + +✅ GOOD (in EN file): +## Configuration +> **Note**: This is important + +✅ GOOD (in VI file): +## Cấu Hình +> **Lưu ý**: Điều này rất quan trọng +``` + +--- + +## Bước 4: Chuẩn Hóa Mermaid Diagrams / Standardize Mermaid Diagrams + +### 4.1 Syntax Check + +**Common Issues Checklist:** +- [ ] Có xuống dòng sau `flowchart TD` / `graph TD`? +- [ ] Arrow sử dụng `-->` không phải `->`? +- [ ] Không có Node ID trùng lặp? +- [ ] Labels có ký tự đặc biệt được quote? `["Label (with parens)"]` +- [ ] Subgraph format: `subgraph ID["Label"]`? + +### 4.2 Apply Dark Color Palette + +**LUÔN sử dụng bảng màu tối:** + +| Node Type | Fill Color | Border | Stroke Width | +|-----------|-----------|--------|--------------| +| **Start** | `#2C3E50` | `#34495E` | `3px` | +| **End/Success** | `#27AE60` | `#229954` | `3px` | +| **Decision** | `#E67E22` | `#D35400` | `2px` | +| **Error** | `#C0392B` | `#A93226` | `2px` | +| **Process** | `#8E44AD` | `#7D3C98` | `2px` | +| **Database/Cache** | `#34495E` | `#2C3E50` | `2px` | +| **Gateway/API** | `#3498DB` | `#2980B9` | `3px` | +| **Neutral** | `#7F8C8D` | `#5D6D7E` | `2px` | + +**Text Color:** `#ECF0F1` (light text cho contrast) + +**Style Template:** +```mermaid +style NodeName fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:3px +``` + +### 4.3 Example: Before/After + +**❌ BEFORE (no styling):** +```mermaid +graph TD + A[Start] --> B[Process] + B --> C{Decision} + C -->|Yes| D[Success] + C -->|No| E[Error] +``` + +**✅ AFTER (with dark palette):** +```mermaid +graph TD + A[Start] --> B[Process] + B --> C{Decision} + C -->|Yes| D[Success] + C -->|No| E[Error] + + style A fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:3px + style B fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px + style C fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px + style D fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:3px + style E fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px +``` + +### 4.4 Visual Indicators (Optional) + +Có thể thêm emoji cho clarity: +- 🚀 Start/Launch +- ✅ Success/Done +- ❌ Error/Failed +- ⚠️ Warning/Decision +- 🔐 Security/Auth +- 💾 Database +- ⚙️ Processing +- 🌐 API/Network + +--- + +## Bước 5: Đảm Bảo Đồng Bộ EN/VI / Ensure EN/VI Consistency + +**Checklist:** +- [ ] Cả EN và VI đều có cùng sections (headings) +- [ ] Mermaid diagrams có cùng structure (chỉ khác labels) +- [ ] Code examples giống nhau (chỉ khác comments) +- [ ] File names khớp: `en/ARCHITECTURE.md` ↔ `vi/ARCHITECTURE.md` + +**EN Diagram Example:** +```mermaid +graph TD + A[Request] --> B{Valid?} + B -->|Yes| C[Process] + B -->|No| D[Error] +``` + +**VI Diagram Example (same structure, Vietnamese labels):** +```mermaid +graph TD + A[Yêu cầu] --> B{Hợp lệ?} + B -->|Có| C[Xử lý] + B -->|Không| D[Lỗi] +``` + +--- + +## Bước 6: Cập Nhật Service Root README / Update Service README + +Service root `README.md` phải link đến EN/VI docs: + +**Template:** +```markdown +# Service Name + +> **EN**: [English Documentation](docs/en/README.md) +> **VI**: [Tài liệu Tiếng Việt](docs/vi/README.md) + +## Quick Links + +- 📖 [Architecture Documentation](docs/en/ARCHITECTURE.md) / [Tài liệu Kiến trúc](docs/vi/ARCHITECTURE.md) +- 🚀 [Quick Start](docs/en/README.md#quick-start) +- 🔧 [Configuration](docs/en/README.md#configuration) + +## Tech Stack + +- .NET 8 +- PostgreSQL +- Redis +- RabbitMQ + +## Development + +\`\`\`bash +dotnet build +dotnet run +\`\`\` + +See detailed documentation in [docs/en/](docs/en/) or [docs/vi/](docs/vi/). +``` + +--- + +## Bước 7: Validation / Kiểm Tra Chất Lượng + +### 7.1 Content Checklist + +**For each EN file:** +- [ ] No Vietnamese text (except code comments if needed) +- [ ] No bilingual patterns (`Text / Chữ`) +- [ ] All Mermaid diagrams have dark color palette +- [ ] No syntax errors in Mermaid +- [ ] Links work correctly + +**For each VI file:** +- [ ] No English text (except technical terms) +- [ ] No bilingual patterns +- [ ] All Mermaid diagrams have dark color palette +- [ ] Mermaid structure matches EN version +- [ ] Links work correctly + +### 7.2 Structure Checklist + +- [ ] `docs/en/` exists with all required files +- [ ] `docs/vi/` exists with mirror files +- [ ] Service root `README.md` links to both EN/VI +- [ ] File names match between EN/VI (e.g., `ARCHITECTURE.md`) + +### 7.3 Mermaid Validation + +```bash +# Optional: validate Mermaid syntax using mermaid-cli +mmdc -i docs/en/ARCHITECTURE.md -o /tmp/test.svg +``` + +--- + +## Resources / Tài Nguyên + +**Related Skills:** +- [Documentation Skill](../.agent/skills/documentation/SKILL.md) - Documentation guidelines +- [Mermaid Diagrams Skill](../.agent/skills/mermaid-diagrams/SKILL.md) - Diagram patterns +- [Skill Authoring](../.agent/skills/skill-authoring/SKILL.md) - How to write skills + +**Tools:** +- [Mermaid Live Editor](https://mermaid.live/) - Test diagrams +- [Mermaid Documentation](https://mermaid.js.org/) + +--- + +## Example: Complete Workflow Execution + +```bash +# 1. Create structure +mkdir -p services/my-service-net/docs/{en,vi} + +# 2. Split bilingual ARCHITECTURE.md into EN/VI +# (Agent processes content, removes cross-language text) + +# 3. Apply Mermaid formatting +# (Agent adds dark color palette to all diagrams) + +# 4. Update root README.md +# (Agent creates bilingual link structure) + +# 5. Validate +# Check all files exist, links work, diagrams render +``` + +**Result:** +``` +services/my-service-net/ +├── README.md (links to docs/en and docs/vi) +└── docs/ + ├── en/ + │ ├── ARCHITECTURE.md (English only, dark Mermaid) + │ └── README.md (English only) + └── vi/ + ├── ARCHITECTURE.md (Vietnamese only, dark Mermaid) + └── README.md (Vietnamese only) +``` + +--- + +## Quick Tips / Mẹo Nhanh + +### Mermaid Common Issues +- Missing line break after `flowchart TD` → Add newline +- Single dash in arrow `->` → Change to `-->` +- Duplicate node IDs → Rename nodes (A, B, C, etc.) +- Missing quotes on special chars → Wrap in `["label"]` + +### Color Pattern Quick Reference +```markdown +🟦 Start = #2C3E50 / #34495E +🟩 Success = #27AE60 / #229954 +🟧 Decision = #E67E22 / #D35400 +🟥 Error = #C0392B / #A93226 +🟪 Process = #8E44AD / #7D3C98 +⬛ Database = #34495E / #2C3E50 +🔷 API = #3498DB / #2980B9 +``` + +### Visual Indicators +- Use emojis consistently: 🚀 ✅ ❌ ⚠️ 🔐 💾 ⚙️ 🌐 +- Dark palette mandatory for all diagrams +- Light text color `#ECF0F1` for contrast \ No newline at end of file