Hệ Sinh Thái Mở Rộng & Lộ Trình
Lộ Trình • Future Services
5.2 Hướng Dẫn & Mẫu Chuẩn Viết Document Dịch Vụ Mới
Khi Pango AI Team phát triển thêm một dịch vụ mới (ví dụ Voicebot Service, OCR Service, Knowledge Service), kỹ sư chỉ cần tạo thư mục mới trong docs/ theo cấu trúc chuẩn bên dưới.
📁 1. Cấu Trúc Thư Mục Khuyến Nghị
docs/
└── <service-name>/ # Ví dụ: voicebot-service
├── _category_.json # Khai báo menu sidebar
├── overview.md # Giới thiệu mục đích & tính năng
├── architecture.md # Sơ đồ kiến trúc & giao thức (WebSocket/gRPC/GraphQL)
├── api-reference/ # Danh sách các API chi tiết
│ ├── _category_.json
│ ├── api-1.md
│ └── api-2.md
├── sdk-integration.md # Hướng dẫn tích hợp SDK
└── best-practices.md # Khuyến nghị kỹ thuật📄 2. Mẫu Khai Báo _category_.json
{
"label": "Tên Dịch Vụ Mới (Ví dụ: Voicebot Service)",
"position": 4,
"link": {
"type": "generated-index",
"description": "Mô tả ngắn gọn về vai trò của dịch vụ mới này đối với đối tác tích hợp."
}
}📑 3. Tiêu Chuẩn Trình Bày API (Enterprise Quality Checklist)
Mỗi trang API trong tài liệu dịch vụ mới cần đảm bảo đầy đủ các thành phần:
- Badge phân loại: Method (Query/Mutation/POST/WebSocket), Yêu cầu xác thực.
- Mô tả nghiệp vụ: Giải thích API dùng khi nào, ngữ cảnh gọi trong luồng app.
- Interactive Tabs: Tab 1 hiển thị Payload / Schema thô; Tab 2 hiển thị code mẫu TypeScript / Dart / Swift.
- Bảng Schema Parameters: Liệt kê tên thuộc tính, kiểu dữ liệu, bắt buộc hay tùy chọn, và ý nghĩa.
- Bảng Mã Lỗi & Xử Lý: Liệt kê các lỗi đặc thù của API và hướng khắc phục.