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

feat: Add documentation reference guides for diagrams, OpenAPI, versioning, and API tables, and update the main documentation skill and editing workflow.

Browse Source
This commit is contained in:
Ho Ngoc Hai
2026-01-18 23:11:19 +07:00
parent 8d4ec77b27
commit 941ace8c80
6 changed files with 613 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

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

105
.agent/skills/documentation/references/API_TABLES.md Normal file
View File

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

109
.agent/skills/documentation/references/DIAGRAMS.md Normal file
View File

@@ -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
<img src="images/large-diagram.png" alt="System Architecture" width="800">
```
## 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)

191
.agent/skills/documentation/references/OPENAPI.md Normal file
View File

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

154
.agent/skills/documentation/references/VERSIONING.md Normal file
View File

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

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

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