feat: Add Vietnamese file naming guidelines and comprehensive documentation standards including automation tools and OpenAPI specifications.
This commit is contained in:
Ho Ngoc Hai
@@ -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
|
||||
|
||||
|
||||
# ❌ BAD: No context
|
||||
|
||||
```
|
||||
|
||||
**Responsive Images:**
|
||||
```markdown
|
||||
<img src="images/large-diagram.png" alt="System Architecture" width="800">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user