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

feat: Define microservices documentation standards and update the bilingual documentation editing workflow.

Browse Source
This commit is contained in:
Ho Ngoc Hai
2026-01-18 22:52:20 +07:00
parent 2d0b6f3bce
commit 5c39c4aa93
2 changed files with 519 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

190
.agent/skills/documentation/SKILL.md
View File

@@ -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

373
.agent/workflows/docs-edit-vi-en.md
View File

@@ -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)
## 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