diff --git a/.agent/skills/documentation/SKILL.md b/.agent/skills/documentation/SKILL.md index 9677da7e..6fce8198 100644 --- a/.agent/skills/documentation/SKILL.md +++ b/.agent/skills/documentation/SKILL.md @@ -67,79 +67,61 @@ services/my-service-net/ **Key Rules:** - `docs/en/` and `docs/vi/` MUST mirror each other (same files, same structure) - Each language folder is MONOLINGUAL (no bilingual mixing) -- **Filenames**: EN uses English (UPPERCASE), VI uses Vietnamese (kebab-case) +- **Filenames**: Use same English filenames in both folders (e.g., `ARCHITECTURE.md`, `README.md`) - 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`/`kien-truc.md` is MANDATORY, `README.md`/`gioi-thieu.md` is MANDATORY, other files optional +- `ARCHITECTURE.md` is MANDATORY, `README.md` is MANDATORY, other files optional -### Vietnamese Filename Conventions / Quy Ước Đặt Tên Tiếng Việt +### Filename Conventions / Quy Ước Đặt Tên File -**Standard EN/VI Filename Mapping:** +**IMPORTANT**: Both `docs/en/` and `docs/vi/` use the **same English filenames** for consistency and ease of maintenance. -| English (docs/en/) | Vietnamese (docs/vi/) | Description | -|-------------------|----------------------|-------------| -| `README.md` | `gioi-thieu.md` | Service introduction, quick start | -| `ARCHITECTURE.md` | `kien-truc.md` | Architecture documentation | -| `API.md` | `api.md` | API reference (technical term) | -| `DEPLOYMENT.md` | `trien-khai.md` | Deployment guide | -| `CONFIGURATION.md` | `cau-hinh.md` | Configuration guide | -| `TESTING.md` | `kiem-thu.md` | Testing guide | -| `TROUBLESHOOTING.md` | `khac-phuc-su-co.md` | Troubleshooting | -| `MIGRATION.md` | `di-chuyen-du-lieu.md` | Migration guide | -| `PERFORMANCE.md` | `hieu-nang.md` | Performance optimization | -| `SECURITY.md` | `bao-mat.md` | Security guidelines | +**Standard Filenames (used in both EN and VI):** -**Service-Specific Examples:** +| Filename | Purpose / Mục đích | +|----------|-------------------| +| `README.md` | Service introduction, quick start / Giới thiệu dịch vụ | +| `ARCHITECTURE.md` | Architecture documentation / Tài liệu kiến trúc | +| `API.md` | API reference / Tài liệu API | +| `DEPLOYMENT.md` | Deployment guide / Hướng dẫn triển khai | +| `CONFIGURATION.md` | Configuration guide / Hướng dẫn cấu hình | +| `TESTING.md` | Testing guide / Hướng dẫn kiểm thử | +| `TROUBLESHOOTING.md` | Troubleshooting / Khắc phục sự cố | +| `WHATSAPP_SETUP.md` | WhatsApp setup / Cài đặt WhatsApp | +| `AI_CHATBOT_GUIDE.md` | AI chatbot guide / Hướng dẫn chatbot AI | +| `AUTOMATION_GUIDE.md` | Automation guide / Hướng dẫn tự động hóa | -| Service Type | EN Filename | VI Filename | -|-------------|------------|-------------| -| WhatsApp | `WHATSAPP_SETUP.md` | `cai-dat-whatsapp.md` | -| WhatsApp | `AI_CHATBOT_GUIDE.md` | `huong-dan-chatbot-ai.md` | -| WhatsApp | `AUTOMATION_GUIDE.md` | `huong-dan-tu-dong-hoa.md` | -| Facebook | `FACEBOOK_SETUP.md` | `cai-dat-facebook.md` | -| Twitter/X | `TWITTER_SETUP.md` | `cai-dat-twitter.md` | -| Zalo | `ZALO_SETUP.md` | `cai-dat-zalo.md` | +**Naming Rules:** -**Naming Rules for Vietnamese Files:** - -1. **Kebab-case**: All lowercase, words separated by hyphens (`-`) - - ✅ `kien-truc.md`, `huong-dan-chatbot-ai.md` - - ❌ `KIEN-TRUC.md`, `Kien_Truc.md`, `KienTruc.md` - -2. **Vietnamese without diacritics**: Use non-accented Vietnamese - - ✅ `kien-truc` (not `kiến-trúc`) - - ✅ `cau-hinh` (not `cấu-hình`) - - ✅ `trien-khai` (not `triển-khai`) - -3. **Descriptive and clear**: Use full words, avoid abbreviations - - ✅ `huong-dan-chatbot-ai.md` (clear) - - ❌ `hd-chatbot.md` (abbreviated) - -4. **Technical terms**: Keep English for technical/API terms - - ✅ `api.md` (lowercase) - - ✅ `webhook.md` - - ✅ `oauth.md` +1. **UPPERCASE for main docs**: `ARCHITECTURE.md`, `README.md`, `API.md` +2. **UPPERCASE_SNAKE_CASE for feature docs**: `WHATSAPP_SETUP.md`, `AI_CHATBOT_GUIDE.md` +3. **Same filename in both folders**: Makes linking and reference easier +4. **English only**: Avoid encoding issues, better tool compatibility **Directory Structure Example:** ``` services/mkt-whatsapp-service-net/docs/ ├── en/ -│ ├── README.md -│ ├── ARCHITECTURE.md -│ ├── API.md -│ ├── WHATSAPP_SETUP.md -│ ├── AI_CHATBOT_GUIDE.md -│ └── AUTOMATION_GUIDE.md +│ ├── README.md # English content +│ ├── ARCHITECTURE.md # English content +│ ├── API.md # English content +│ ├── WHATSAPP_SETUP.md # English content +│ └── AI_CHATBOT_GUIDE.md # English content └── vi/ - ├── gioi-thieu.md - ├── kien-truc.md - ├── api.md - ├── cai-dat-whatsapp.md - ├── huong-dan-chatbot-ai.md - └── huong-dan-tu-dong-hoa.md + ├── README.md # Vietnamese content (same filename) + ├── ARCHITECTURE.md # Vietnamese content (same filename) + ├── API.md # Vietnamese content (same filename) + ├── WHATSAPP_SETUP.md # Vietnamese content (same filename) + └── AI_CHATBOT_GUIDE.md # Vietnamese content (same filename) ``` +**Benefits:** +- ✅ Easy to find corresponding files (same name in both folders) +- ✅ Simple linking and references +- ✅ No encoding issues +- ✅ Better tool compatibility + ## Key Patterns / Mẫu Chính diff --git a/.agent/skills/documentation/references/API_TABLES.md b/.agent/skills/documentation/references/API_TABLES.md new file mode 100644 index 00000000..915dc252 --- /dev/null +++ b/.agent/skills/documentation/references/API_TABLES.md @@ -0,0 +1,105 @@ +# API Endpoint Tables / Bảng Danh Sách API + +This reference provides standard table formats for documenting API endpoints. + +## 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 +``` + +## Resources + +- [OpenAPI Reference](OPENAPI.md) - For OpenAPI spec documentation +- [Back to Documentation Skill](../SKILL.md) diff --git a/.agent/skills/documentation/references/DIAGRAMS.md b/.agent/skills/documentation/references/DIAGRAMS.md new file mode 100644 index 00000000..a71d9dac --- /dev/null +++ b/.agent/skills/documentation/references/DIAGRAMS.md @@ -0,0 +1,109 @@ +# Diagrams & Visuals / Sơ Đồ & Hình Ảnh + +This reference provides detailed guidelines for creating and managing visual content in documentation. + +## 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 +``` + +## Resources + +- [Mermaid Diagrams Skill](../mermaid-diagrams/SKILL.md) - MANDATORY for all diagrams +- [Mermaid Live Editor](https://mermaid.live/) - Test Mermaid diagrams +- [Back to Documentation Skill](../SKILL.md) diff --git a/.agent/skills/documentation/references/OPENAPI.md b/.agent/skills/documentation/references/OPENAPI.md new file mode 100644 index 00000000..c1fa137b --- /dev/null +++ b/.agent/skills/documentation/references/OPENAPI.md @@ -0,0 +1,191 @@ +# OpenAPI Specification Standards + +This reference provides detailed guidelines for creating OpenAPI documentation for GoodGo microservices. + +## 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 + +## Resources + +- [OpenAPI Specification](https://swagger.io/specification/) - Official spec +- [Redocly CLI](https://redocly.com/docs/cli/) - OpenAPI tools +- [Back to Documentation Skill](../SKILL.md) diff --git a/.agent/skills/documentation/references/VERSIONING.md b/.agent/skills/documentation/references/VERSIONING.md new file mode 100644 index 00000000..213d96db --- /dev/null +++ b/.agent/skills/documentation/references/VERSIONING.md @@ -0,0 +1,154 @@ +# Versioning Documentation / Quản Lý Phiên Bản + +This reference provides detailed guidelines for versioning API documentation and maintaining changelogs. + +## 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 +``` + +## Resources + +- [Keep a Changelog](https://keepachangelog.com/) - Changelog format standard +- [Semantic Versioning](https://semver.org/) - Version numbering scheme +- [Back to Documentation Skill](../SKILL.md) diff --git a/.agent/workflows/docs-edit-vi-en.md b/.agent/workflows/docs-edit-vi-en.md index a042c22f..53229de1 100644 --- a/.agent/workflows/docs-edit-vi-en.md +++ b/.agent/workflows/docs-edit-vi-en.md @@ -50,55 +50,30 @@ README.md (service root) 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 +4. **Sử dụng cùng tên file tiếng Anh cho cả EN và VI** **Commands:** ```bash mkdir -p docs/en docs/vi ``` -### Bước 2.1: Đổi Tên Files Tiếng Việt / Rename Vietnamese Files +**IMPORTANT - Filename Convention:** +- ✅ Cả `docs/en/` và `docs/vi/` dùng **CÙNG tên file tiếng Anh** +- ✅ Ví dụ: `ARCHITECTURE.md`, `README.md`, `API.md` trong cả 2 folders +- ✅ Lợi ích: Dễ tìm file tương ứng, không cần nhớ 2 bộ tên khác nhau -**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 +**Example Structure:** +``` +docs/ +├── en/ +│ ├── README.md # English content +│ ├── ARCHITECTURE.md # English content +│ └── API.md # English content +└── vi/ + ├── README.md # Vietnamese content (same filename!) + ├── ARCHITECTURE.md # Vietnamese content (same filename!) + └── API.md # Vietnamese content (same filename!) ``` - -**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) ---