From 00f714d4923afe24724e58ea40f75ab0fb4396d7 Mon Sep 17 00:00:00 2001 From: Ho Ngoc Hai Date: Sun, 18 Jan 2026 23:06:44 +0700 Subject: [PATCH] feat: Add Vietnamese file naming guidelines and comprehensive documentation standards including automation tools and OpenAPI specifications. --- .agent/skills/documentation/SKILL.md | 855 ++++++++++++++++++++++++++- .agent/workflows/docs-edit-vi-en.md | 74 ++- 2 files changed, 926 insertions(+), 3 deletions(-) diff --git a/.agent/skills/documentation/SKILL.md b/.agent/skills/documentation/SKILL.md index 4b2c61a8..9677da7e 100644 --- a/.agent/skills/documentation/SKILL.md +++ b/.agent/skills/documentation/SKILL.md @@ -441,6 +441,839 @@ Health checks, metrics, logging. ``` +## Real-World Examples / Ví Dụ Thực Tế + +### Excellent Documentation Examples + +These services demonstrate best practices for microservices documentation: + +- **mkt-facebook-service-net** - Complete bilingual docs with EN/VI separation, Mermaid diagrams, API reference +- **mkt-x-service-net** - Clean language separation, comprehensive architecture docs +- **mkt-zalo-service-net** - Full integration guides, setup instructions +- **order-service-net** - Multi-vertical architecture documentation +- **catalog-service-net** - Standard CQRS/Clean Architecture patterns + +### Common Documentation Patterns in GoodGo + +**Architecture Documentation:** +- High-level system diagram with Traefik gateway +- Clean Architecture 4-layer diagram (API → Application → Domain → Infrastructure) +- Request flow sequence diagrams +- Database schema with relationships + +**API Documentation:** +- Endpoint tables with bilingual descriptions +- Request/response examples +- Error code reference +- Authentication requirements + +**Setup Guides:** +- Prerequisites section +- Step-by-step configuration +- Environment variable tables +- Troubleshooting sections + +### What Makes Good Documentation? + +1. **Complete Language Separation**: EN and VI in separate directories +2. **Consistent Dark Mermaid Palette**: Following mermaid-diagrams skill +3. **Practical Examples**: Real code snippets, not placeholders +4. **Troubleshooting Sections**: Common issues and solutions +5. **Quick Start Guides**: Get running in < 5 minutes + +--- + +## Automation & Tools / Công Cụ Tự Động + +### Link Checking + +Validate all markdown links to prevent broken references: + +```bash +# Install markdown-link-check +npm install -g markdown-link-check + +# Check single file +markdown-link-check docs/en/README.md + +# Check all markdown files in docs/ +find docs -name "*.md" | xargs markdown-link-check + +# With config file +markdown-link-check -c .markdown-link-check.json docs/en/README.md +``` + +**Config example** (`.markdown-link-check.json`): +```json +{ + "ignorePatterns": [ + { "pattern": "^http://localhost" }, + { "pattern": "^https://api.goodgo.vn" } + ], + "timeout": "20s", + "retryOn429": true, + "aliveStatusCodes": [200, 206] +} +``` + +### Markdown Linting + +Enforce consistent markdown style: + +```bash +# Install markdownlint-cli +npm install -g markdownlint-cli + +# Lint all docs +markdownlint docs/**/*.md + +# Fix auto-fixable issues +markdownlint --fix docs/**/*.md + +# With config +markdownlint -c .markdownlint.json docs/**/*.md +``` + +**Config example** (`.markdownlint.json`): +```json +{ + "default": true, + "MD013": { "line_length": 120 }, + "MD033": false, + "MD041": false +} +``` + +### Documentation Generation + +**OpenAPI to Markdown:** +```bash +# Using redoc-cli +npx @redocly/cli build-docs docs/en/api/openapi/service.yaml \ + -o docs/en/api/reference.html + +# Using swagger-markdown +npx swagger-markdown -i docs/en/api/openapi/service.yaml \ + -o docs/en/api/REFERENCE.md +``` + +**C# XML Comments to Markdown:** +```bash +# Using xmldoc2md (for .NET projects) +dotnet tool install -g xmldoc2md +xmldoc2md src/MyService.API/bin/Debug/net8.0/MyService.API.xml \ + docs/en/api/ +``` + +### CI/CD Integration + +```yaml +# .github/workflows/docs-validation.yml +name: Validate Documentation + +on: [pull_request] + +jobs: + validate-docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Check links + run: | + npm install -g markdown-link-check + find docs -name "*.md" | xargs markdown-link-check + - name: Lint markdown + run: | + npm install -g markdownlint-cli + markdownlint docs/**/*.md +``` + +--- + +## OpenAPI Specification Standards + +### File Structure + +``` +docs/en/api/openapi/ +├── service-name.yaml # Main OpenAPI spec +├── schemas/ # Reusable schemas +│ ├── common.yaml # Common types (PaginationRequest, etc.) +│ ├── errors.yaml # Error responses +│ └── entities.yaml # Domain entities +└── examples/ # Request/response examples + ├── requests/ + └── responses/ +``` + +### OpenAPI Template + +```yaml +openapi: 3.0.3 +info: + title: Service Name API + version: 1.0.0 + description: | + **English**: Brief description of the service and its capabilities. + + **Vietnamese**: Mô tả ngắn gọn về dịch vụ và khả năng của nó. + contact: + name: GoodGo Platform Team + email: dev@goodgo.vn + license: + name: Proprietary + +servers: + - url: https://api.goodgo.vn/v1 + description: Production + - url: https://staging-api.goodgo.vn/v1 + description: Staging + - url: http://localhost:5000 + description: Local development + +tags: + - name: Resources + description: | + **EN**: Resource management endpoints. + **VI**: Các endpoint quản lý tài nguyên. + - name: Admin + description: | + **EN**: Administrative operations (requires admin role). + **VI**: Các thao tác quản trị (yêu cầu quyền admin). + +paths: + /resources: + get: + summary: List resources + description: | + **EN**: Retrieve a paginated list of resources with optional filtering. + **VI**: Lấy danh sách tài nguyên có phân trang với bộ lọc tùy chọn. + tags: + - Resources + parameters: + - name: page + in: query + description: Page number (1-indexed) / Số trang (bắt đầu từ 1) + schema: + type: integer + minimum: 1 + default: 1 + - name: pageSize + in: query + description: Items per page / Số item mỗi trang + schema: + type: integer + minimum: 1 + maximum: 100 + default: 10 + - name: search + in: query + description: Search keyword / Từ khóa tìm kiếm + schema: + type: string + responses: + '200': + description: Success / Thành công + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceListResponse' + examples: + success: + $ref: '#/components/examples/ResourceListSuccess' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + security: + - bearerAuth: [] + +components: + schemas: + ResourceListResponse: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Resource' + pagination: + $ref: '#/components/schemas/PaginationMetadata' + + Resource: + type: object + required: + - id + - name + properties: + id: + type: string + format: uuid + name: + type: string + createdAt: + type: string + format: date-time + + PaginationMetadata: + type: object + properties: + page: + type: integer + pageSize: + type: integer + totalPages: + type: integer + totalItems: + type: integer + + responses: + BadRequest: + description: Bad request / Yêu cầu không hợp lệ + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + Unauthorized: + description: Unauthorized / Chưa xác thực + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + + examples: + ResourceListSuccess: + value: + data: + - id: "123e4567-e89b-12d3-a456-426614174000" + name: "Example Resource" + createdAt: "2024-01-18T10:00:00Z" + pagination: + page: 1 + pageSize: 10 + totalPages: 5 + totalItems: 42 + + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + description: | + **EN**: JWT token obtained from /auth/login endpoint. + **VI**: JWT token lấy từ endpoint /auth/login. +``` + +### Best Practices for OpenAPI + +1. **Use `$ref` for reusability**: Define schemas once, reference everywhere +2. **Include examples**: Provide realistic request/response examples +3. **Bilingual descriptions**: Add both EN and VI in description fields +4. **Security schemes**: Document all authentication methods +5. **Error responses**: Define standard error response schemas +6. **Validation rules**: Include min/max, patterns, enums where applicable + +--- + +## Versioning Documentation / Quản Lý Phiên Bản + +### API Documentation Versioning + +**Strategy**: Use semantic versioning and separate folders for major versions. + +``` +docs/en/api/ +├── v1/ +│ ├── openapi.yaml +│ └── CHANGELOG.md +├── v2/ +│ ├── openapi.yaml +│ └── CHANGELOG.md +└── README.md # Version comparison and migration guides +``` + +**When to create new version:** +- **Major (v2.0)**: Breaking changes (removed endpoints, changed response structure) +- **Minor (v1.1)**: New features, backward-compatible additions +- **Patch (v1.0.1)**: Bug fixes, documentation updates + +### Changelog Format + +Follow [Keep a Changelog](https://keepachangelog.com/) format: + +```markdown +# Changelog + +All notable changes to this service will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [1.2.0] - 2024-01-18 + +### Added / Đã Thêm +- **EN**: New endpoint `POST /api/v1/resources/bulk` for batch operations +- **VI**: Endpoint mới `POST /api/v1/resources/bulk` cho thao tác hàng loạt +- **EN**: Support for filtering by date range in list endpoints +- **VI**: Hỗ trợ lọc theo khoảng thời gian trong các endpoint danh sách + +### Changed / Đã Thay Đổi +- **EN**: Improved authentication flow to use refresh tokens +- **VI**: Cải thiện luồng xác thực sử dụng refresh token +- **EN**: Updated pagination default from 20 to 10 items per page +- **VI**: Cập nhật phân trang mặc định từ 20 xuống 10 items mỗi trang + +### Deprecated / Đã Lỗi Thời +- **EN**: `GET /api/v1/legacy-endpoint` - Use `GET /api/v1/resources` instead. Will be removed in v2.0 +- **VI**: `GET /api/v1/legacy-endpoint` - Dùng `GET /api/v1/resources` thay thế. Sẽ xóa ở v2.0 + +### Removed / Đã Xóa +- **EN**: OAuth1 authentication support (replaced by OAuth2) +- **VI**: Hỗ trợ xác thực OAuth1 (thay bằng OAuth2) + +### Fixed / Đã Sửa +- **EN**: Fixed pagination bug where last page returned empty results +- **VI**: Sửa lỗi phân trang khi trang cuối trả về kết quả rỗng +- **EN**: Resolved race condition in concurrent resource updates +- **VI**: Giải quyết race condition khi cập nhật tài nguyên đồng thời + +### Security / Bảo Mật +- **EN**: Added rate limiting to prevent brute force attacks +- **VI**: Thêm giới hạn tần suất để ngăn chặn tấn công brute force + +## [1.1.0] - 2024-01-10 + +### Added / Đã Thêm +- Initial release with core CRUD operations +- Phát hành đầu tiên với các thao tác CRUD cơ bản + +[Unreleased]: https://github.com/org/repo/compare/v1.2.0...HEAD +[1.2.0]: https://github.com/org/repo/compare/v1.1.0...v1.2.0 +[1.1.0]: https://github.com/org/repo/releases/tag/v1.1.0 +``` + +### Migration Guide Template + +```markdown +# Migration Guide: v1 to v2 + +## Breaking Changes / Thay Đổi Không Tương Thích + +### 1. Authentication Changes / Thay Đổi Xác Thực + +**Before (v1):** +```json +POST /auth/login +{ + "username": "user@example.com", + "password": "password123" +} +``` + +**After (v2):** +```json +POST /v2/auth/login +{ + "email": "user@example.com", + "password": "password123", + "deviceId": "optional-device-id" +} +``` + +**Migration Steps:** +1. Update client to use `email` field instead of `username` +2. Optionally include `deviceId` for better security tracking + +### 2. Response Format Changes / Thay Đổi Format Response + +**Before (v1):** +```json +{ + "items": [...], + "total": 100 +} +``` + +**After (v2):** +```json +{ + "data": [...], + "pagination": { + "page": 1, + "pageSize": 10, + "totalPages": 10, + "totalItems": 100 + } +} +``` + +## Deprecated Features / Tính Năng Lỗi Thời + +| Feature | Replacement | Removal Date | +|---------|-------------|-------------| +| `/api/v1/users` | `/api/v2/users` | 2024-06-01 | + +## Timeline / Lộ Trình + +- **2024-01-18**: v2.0 released, v1 deprecated +- **2024-03-01**: v1 enters maintenance mode (no new features) +- **2024-06-01**: v1 removed, v2 becomes stable +``` + +--- + +## Diagrams & Visuals / Sơ Đồ & Hình Ảnh + +### When to Use Diagrams + +| Diagram Type | Use Case | Mermaid Type | +|--------------|----------|-------------| +| **Architecture** | High-level system overview, service dependencies | `graph TB` | +| **Sequence** | Request/response flows, async processes, integrations | `sequenceDiagram` | +| **ER Diagram** | Database schema, table relationships | `erDiagram` | +| **State** | Status transitions (Order, Campaign, Payment) | `stateDiagram-v2` | +| **Class** | Domain model, entity relationships | `classDiagram` | +| **Flowchart** | Decision trees, business logic flows | `flowchart TD` | + +### Mermaid Dark Palette (MANDATORY) + +**CRITICAL**: Always use the dark color palette from [Mermaid Diagrams Skill](../mermaid-diagrams/SKILL.md). + +**Standard Colors:** +- **Primary (Blue)**: `#3498DB` - Main components, API layer +- **Secondary (Purple)**: `#8E44AD` - Application layer, handlers +- **Accent (Orange)**: `#E67E22` - Domain layer, business logic +- **Neutral (Dark Gray)**: `#34495E` - Databases, infrastructure +- **Success (Green)**: `#27AE60` - Success states +- **Warning (Yellow)**: `#F39C12` - Warning states +- **Danger (Red)**: `#E74C3C` - Error states + +**Example:** +```mermaid +graph TB + API[API Layer] + APP[Application] + DOMAIN[Domain] + DB[(Database)] + + API --> APP + APP --> DOMAIN + APP --> DB + + style API fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98 + style APP fill:#3498DB,color:#ECF0F1,stroke:#2980B9 + style DOMAIN fill:#E67E22,color:#ECF0F1,stroke:#D35400 + style DB fill:#34495E,color:#ECF0F1,stroke:#2C3E50 +``` + +### Screenshot Guidelines + +**File Naming:** +- ✅ Descriptive: `auth-flow-login-screen.png` +- ❌ Generic: `screenshot1.png`, `image.png` + +**File Organization:** +``` +docs/ +├── en/ +│ ├── images/ +│ │ ├── architecture/ +│ │ ├── screenshots/ +│ │ └── diagrams/ +│ └── README.md +└── vi/ + ├── images/ # Mirror EN structure + └── README.md +``` + +**File Format:** +- **PNG**: UI screenshots, diagrams with transparency +- **JPG**: Photos, images without transparency +- **SVG**: Vector graphics, logos (when possible) +- **WebP**: Modern format for smaller file sizes + +**Optimization:** +```bash +# Optimize PNG files +pngquant --quality 65-80 docs/en/images/*.png + +# Optimize JPG files +jpegoptim --max=85 docs/en/images/*.jpg + +# Convert to WebP +cwebp -q 80 input.png -o output.webp +``` + +**Embedding in Markdown:** +```markdown +# ✅ GOOD: With descriptive caption and alt text +![Login flow showing email input, password field, and social login options](images/auth-flow-login.png) + +# ❌ BAD: No context +![Screenshot](screenshot.png) +``` + +**Responsive Images:** +```markdown +System Architecture +``` + +--- + +## API Endpoint Tables / Bảng Danh Sách API + +### Standard Endpoint Table Format + +```markdown +## API Endpoints + +### Resource Management / Quản Lý Tài Nguyên + +| Method | Endpoint | Description / Mô Tả | Auth | +|--------|----------|---------------------|------| +| GET | `/api/v1/resources` | List all resources / Liệt kê tài nguyên | ✓ | +| POST | `/api/v1/resources` | Create new resource / Tạo mới tài nguyên | ✓ | +| GET | `/api/v1/resources/{id}` | Get resource details / Lấy chi tiết tài nguyên | ✓ | +| PUT | `/api/v1/resources/{id}` | Update resource / Cập nhật tài nguyên | ✓ | +| DELETE | `/api/v1/resources/{id}` | Delete resource / Xóa tài nguyên | ✓ | + +### Admin Endpoints / Endpoint Quản Trị + +| Method | Endpoint | Description / Mô Tả | Roles | +|--------|----------|---------------------|-------| +| GET | `/api/v1/admin/users` | List all users / Liệt kê người dùng | Admin | +| POST | `/api/v1/admin/users/{id}/suspend` | Suspend user / Tạm dừng người dùng | Admin | +``` + +### Query Parameters Table + +```markdown +### Query Parameters for `GET /api/v1/resources` + +| Parameter | Type | Required | Description / Mô Tả | Default | Example | +|-----------|------|----------|---------------------|---------|----------| +| `page` | integer | No | Page number (1-indexed) / Số trang | 1 | `?page=2` | +| `pageSize` | integer | No | Items per page / Số item mỗi trang | 10 | `?pageSize=20` | +| `search` | string | No | Search keyword / Từ khóa tìm kiếm | - | `?search=product` | +| `sortBy` | string | No | Sort field / Trường sắp xếp | `createdAt` | `?sortBy=name` | +| `sortOrder` | enum | No | Sort direction: `asc`, `desc` / Thứ tự | `desc` | `?sortOrder=asc` | +| `status` | enum | No | Filter by status / Lọc theo trạng thái | - | `?status=active` | +``` + +### Request Body Table + +```markdown +### Request Body for `POST /api/v1/resources` + +| Field | Type | Required | Description / Mô Tả | Validation | +|-------|------|----------|---------------------|------------| +| `name` | string | Yes | Resource name / Tên tài nguyên | Min: 3, Max: 100 chars | +| `description` | string | No | Resource description / Mô tả | Max: 500 chars | +| `type` | enum | Yes | Resource type: `product`, `service` | Must be valid enum | +| `price` | decimal | No | Price in VND / Giá (VNĐ) | Min: 0, Max: 1000000000 | +| `tags` | array | No | Tags for categorization / Thẻ phân loại | Max: 10 items | +``` + +### Response Codes Table + +```markdown +### Response Codes + +| Code | Status | Description / Mô Tả | +|------|--------|---------------------| +| 200 | OK | Request successful / Yêu cầu thành công | +| 201 | Created | Resource created / Tài nguyên đã tạo | +| 400 | Bad Request | Invalid input / Dữ liệu không hợp lệ | +| 401 | Unauthorized | Authentication required / Cần xác thực | +| 403 | Forbidden | Insufficient permissions / Không đủ quyền | +| 404 | Not Found | Resource not found / Không tìm thấy tài nguyên | +| 409 | Conflict | Resource already exists / Tài nguyên đã tồn tại | +| 422 | Unprocessable Entity | Validation failed / Xác thực thất bại | +| 500 | Internal Server Error | Server error / Lỗi server | +``` + +### Error Response Format + +```markdown +### Error Response Structure + +```json +{ + "type": "validation_error", + "title": "Validation Failed", + "status": 422, + "errors": { + "name": ["Name is required", "Name must be at least 3 characters"], + "email": ["Email format is invalid"] + }, + "traceId": "00-abc123-def456-00" +} +``` + +**Error Types:** +- `validation_error` - Input validation failures +- `authentication_error` - Authentication issues +- `authorization_error` - Permission denied +- `not_found_error` - Resource not found +- `conflict_error` - Duplicate or conflicting resource +- `internal_error` - Unexpected server error +``` + +--- + +## Configuration Documentation / Tài Liệu Cấu Hình + +### Environment Variables Table + +```markdown +## Environment Variables / Biến Môi Trường + +### Required Variables / Biến Bắt Buộc + +| Variable | Type | Description / Mô Tả | Example | +|----------|------|---------------------|----------| +| `DATABASE_URL` | string | PostgreSQL connection string / Chuỗi kết nối PostgreSQL | `postgresql://user:pass@localhost:5432/db` | +| `REDIS_URL` | string | Redis connection string / Chuỗi kết nối Redis | `redis://localhost:6379` | +| `JWT_SECRET` | string | Secret key for JWT signing / Khóa bí mật ký JWT | `your-256-bit-secret` | +| `RABBITMQ_URL` | string | RabbitMQ connection / Kết nối RabbitMQ | `amqp://user:pass@localhost:5672` | + +### Optional Variables / Biến Tùy Chọn + +| Variable | Type | Description / Mô Tả | Default | +|----------|------|---------------------|----------| +| `PORT` | integer | Server port / Cổng server | `5000` | +| `LOG_LEVEL` | enum | Logging level: `debug`, `info`, `warn`, `error` | `info` | +| `CORS_ORIGINS` | string | Allowed CORS origins (comma-separated) | `*` | +| `RATE_LIMIT_MAX` | integer | Max requests per window / Số request tối đa | `100` | +| `RATE_LIMIT_WINDOW_MS` | integer | Rate limit window in ms / Cửa sổ giới hạn (ms) | `60000` | +| `CACHE_TTL_SECONDS` | integer | Default cache TTL / TTL cache mặc định | `300` | +``` + +### Configuration File Example + +```markdown +## Configuration File: `appsettings.json` + +```json +{ + "Server": { + "Port": 5000, + "Environment": "Development", + "EnableSwagger": true + }, + "Database": { + "Host": "localhost", + "Port": 5432, + "Name": "goodgo_dev", + "Username": "postgres", + "Password": "password", + "MaxPoolSize": 20, + "CommandTimeout": 30 + }, + "Redis": { + "Host": "localhost", + "Port": 6379, + "Database": 0, + "Password": null, + "ConnectTimeout": 5000, + "SyncTimeout": 5000 + }, + "Jwt": { + "Secret": "your-secret-key-min-32-chars", + "Issuer": "goodgo-platform", + "Audience": "goodgo-clients", + "ExpirationMinutes": 60, + "RefreshTokenExpirationDays": 7 + }, + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + }, + "Console": { + "FormatterName": "json" + } + }, + "RateLimiting": { + "PermitLimit": 100, + "Window": "00:01:00", + "QueueLimit": 10 + }, + "Cors": { + "AllowedOrigins": [ + "http://localhost:3000", + "https://app.goodgo.vn" + ], + "AllowCredentials": true, + "AllowedHeaders": ["*"], + "AllowedMethods": ["GET", "POST", "PUT", "DELETE"] + } +} +``` + +**Notes:** +- **EN**: Never commit secrets to version control. Use environment variables or secret management tools. +- **VI**: Không bao giờ commit secrets vào version control. Dùng biến môi trường hoặc công cụ quản lý secrets. +``` + +### Docker Compose Configuration + +```markdown +## Docker Compose Configuration + +```yaml +version: '3.8' + +services: + app: + build: . + ports: + - "5000:5000" + environment: + - DATABASE_URL=postgresql://postgres:password@db:5432/goodgo + - REDIS_URL=redis://redis:6379 + - JWT_SECRET=${JWT_SECRET} + - LOG_LEVEL=info + depends_on: + - db + - redis + + db: + image: postgres:15 + environment: + - POSTGRES_DB=goodgo + - POSTGRES_USER=postgres + - POSTGRES_PASSWORD=password + volumes: + - postgres_data:/var/lib/postgresql/data + ports: + - "5432:5432" + + redis: + image: redis:7-alpine + ports: + - "6379:6379" + volumes: + - redis_data:/data + +volumes: + postgres_data: + redis_data: +``` + +**Environment File** (`.env`): +```bash +JWT_SECRET=your-production-secret-key-min-32-characters +DATABASE_PASSWORD=your-secure-db-password +``` +``` + +--- + ## Best Practices / Thực Hành Tốt ### Writing Style / Phong Cách Viết @@ -587,11 +1420,31 @@ markdownlint docs/**/*.md ## Resources / Tài Nguyên +### Related Skills - [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 +- [Mermaid Diagrams](../mermaid-diagrams/SKILL.md) - Diagram patterns with dark color palette (MANDATORY for docs) - [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 + +### External Resources +- [Keep a Changelog](https://keepachangelog.com/) - Changelog format standard +- [Semantic Versioning](https://semver.org/) - Version numbering scheme +- [OpenAPI Specification](https://swagger.io/specification/) - API documentation standard +- [Markdown Guide](https://www.markdownguide.org/) - Markdown syntax reference +- [GitHub Flavored Markdown](https://github.github.com/gfm/) - GitHub markdown extensions + +### Tools +- [markdown-link-check](https://github.com/tcort/markdown-link-check) - Validate markdown links +- [markdownlint](https://github.com/DavidAnson/markdownlint) - Markdown linter +- [Redocly CLI](https://redocly.com/docs/cli/) - OpenAPI tools +- [Mermaid Live Editor](https://mermaid.live/) - Test Mermaid diagrams + +### Example Documentation +Refer to these services for best practices: +- `services/mkt-facebook-service-net/docs/` - Complete bilingual setup +- `services/order-service-net/docs/` - Multi-vertical architecture +- `services/catalog-service-net/docs/` - Clean Architecture patterns diff --git a/.agent/workflows/docs-edit-vi-en.md b/.agent/workflows/docs-edit-vi-en.md index 0183166e..ccdcb3ac 100644 --- a/.agent/workflows/docs-edit-vi-en.md +++ b/.agent/workflows/docs-edit-vi-en.md @@ -56,6 +56,51 @@ README.md (service root) mkdir -p docs/en docs/vi ``` +### Bước 2.1: Đổi Tên Files Tiếng Việt / Rename Vietnamese Files + +**IMPORTANT**: Files trong `docs/vi/` PHẢI dùng tên tiếng Việt (kebab-case), KHÔNG dùng tên tiếng Anh. + +**Mapping Table (EN → VI):** + +| English (docs/en/) | Vietnamese (docs/vi/) | +|-------------------|----------------------| +| `README.md` | `gioi-thieu.md` | +| `ARCHITECTURE.md` | `kien-truc.md` | +| `API.md` | `api.md` | +| `DEPLOYMENT.md` | `trien-khai.md` | +| `CONFIGURATION.md` | `cau-hinh.md` | +| `TESTING.md` | `kiem-thu.md` | +| `WHATSAPP_SETUP.md` | `cai-dat-whatsapp.md` | +| `AI_CHATBOT_GUIDE.md` | `huong-dan-chatbot-ai.md` | +| `AUTOMATION_GUIDE.md` | `huong-dan-tu-dong-hoa.md` | +| `FACEBOOK_SETUP.md` | `cai-dat-facebook.md` | +| `TWITTER_SETUP.md` | `cai-dat-twitter.md` | +| `ZALO_SETUP.md` | `cai-dat-zalo.md` | + +**Vietnamese Filename Rules:** +1. ✅ **Kebab-case**: lowercase, hyphens only (`kien-truc.md`) +2. ✅ **No diacritics**: `kien-truc` not `kiến-trúc` +3. ✅ **No underscores**: `cai-dat-whatsapp` not `cai_dat_whatsapp` +4. ✅ **Technical terms lowercase**: `api.md`, `webhook.md`, `oauth.md` + +**Example Renaming:** +```bash +# ❌ WRONG (using English names in VI folder) +docs/vi/ARCHITECTURE.md +docs/vi/WHATSAPP_SETUP.md + +# ✅ CORRECT (using Vietnamese kebab-case names) +docs/vi/kien-truc.md +docs/vi/cai-dat-whatsapp.md +``` + +**Checklist:** +- [ ] All files in `docs/vi/` use lowercase Vietnamese names +- [ ] No uppercase letters in VI filenames +- [ ] No underscores (`_`), only hyphens (`-`) +- [ ] Technical terms kept in English (lowercase) + + --- ## Bước 3: Tách Nội Dung EN/VI / Separate EN/VI Content @@ -264,6 +309,7 @@ See detailed documentation in [docs/en/](docs/en/) or [docs/vi/](docs/vi/). - [ ] All Mermaid diagrams have dark color palette - [ ] No syntax errors in Mermaid - [ ] Links work correctly +- [ ] **Filename is UPPERCASE** (e.g., `ARCHITECTURE.md`, `README.md`) **For each VI file:** - [ ] No English text (except technical terms) @@ -271,13 +317,37 @@ See detailed documentation in [docs/en/](docs/en/) or [docs/vi/](docs/vi/). - [ ] All Mermaid diagrams have dark color palette - [ ] Mermaid structure matches EN version - [ ] Links work correctly +- [ ] **Filename is kebab-case Vietnamese** (e.g., `kien-truc.md`, `gioi-thieu.md`) +- [ ] **No diacritics in filename** (e.g., `kien-truc` not `kiến-trúc`) +- [ ] **No underscores**, only hyphens ### 7.2 Structure Checklist - [ ] `docs/en/` exists with all required files -- [ ] `docs/vi/` exists with mirror files +- [ ] `docs/vi/` exists with mirror files (same count) - [ ] Service root `README.md` links to both EN/VI -- [ ] File names match between EN/VI (e.g., `ARCHITECTURE.md`) +- [ ] **EN filenames are UPPERCASE** (e.g., `ARCHITECTURE.md`, `API.md`) +- [ ] **VI filenames are lowercase kebab-case** (e.g., `kien-truc.md`, `api.md`) +- [ ] Files match mapping table (e.g., `ARCHITECTURE.md` ↔ `kien-truc.md`) + +### 7.3 Filename Mapping Validation + +**Verify EN/VI pairs:** +```bash +# Example pairs that should exist +docs/en/README.md ↔ docs/vi/gioi-thieu.md +docs/en/ARCHITECTURE.md ↔ docs/vi/kien-truc.md +docs/en/API.md ↔ docs/vi/api.md +docs/en/WHATSAPP_SETUP.md ↔ docs/vi/cai-dat-whatsapp.md +``` + +**Common mistakes:** +- ❌ `docs/vi/ARCHITECTURE.md` (English name in VI folder) +- ❌ `docs/vi/KIEN-TRUC.md` (uppercase in VI folder) +- ❌ `docs/vi/kien_truc.md` (underscore instead of hyphen) +- ❌ `docs/vi/kiến-trúc.md` (using diacritics) +- ✅ `docs/vi/kien-truc.md` (correct!) + ### 7.3 Mermaid Validation