Bản mẫu Tài liệu Module
Mọi module satellite trong nền tảng VENI-AI phải tuân theo sơ đồ (schema) tài liệu chuẩn hóa này. Điều này đảm bảo tính nhất quán cho các chủ sở hữu sản phẩm (product owners), lập trình viên và các bên liên quan.
📋 Sơ đồ Tài liệu
Một bản đặc tả module đầy đủ bao gồm bốn phần chính:
1. Tổng quan (index.md)
Ngữ cảnh nghiệp vụ cấp cao và giá trị mang lại.
- Vấn đề: Module này giải quyết sự phân mảnh nào?
- Giá trị Cốt lõi: Nó mang lại lợi ích gì cho tổ chức?
- Tích hợp Shell: Nó kế thừa những tính năng nào từ Shell?
2. Đặc tả (specification.md)
"Nguồn sự thật" cho các hành vi chức năng.
- Chân dung người dùng: Ai sử dụng module này và tại sao?
- Danh sách Tính năng: Danh sách các khả năng được phân loại kèm tiêu chí nghiệm thu (acceptance criteria).
- Quy tắc Nghiệp vụ: Các ràng buộc, giới hạn và các trường hợp biên.
3. Hình ảnh & Mockup
Được tích hợp vào phần Tổng quan hoặc Đặc tả.
- Hành trình người dùng: Cách người dùng điều hướng module.
- Mockup: Các khung hình CSS độ trung thực cao hiển thị UI bên trong Shell.
4. Tham chiếu Kỹ thuật
Chi tiết triển khai chuyên sâu cho kỹ sư.
- Schema Cơ sở dữ liệu: Sơ đồ ERD và định nghĩa cột sử dụng kiểu dữ liệu Drizzle.
- Đặc tả API: Định nghĩa các điểm cuối (endpoint) REST và gRPC với ví dụ yêu cầu/phản hồi.
- Ma trận RBAC: Bản đồ ánh xạ các vai trò với các quyền cụ thể.
🛠️ Bản mẫu Markdown
Bạn có thể sao chép bản mẫu này khi bắt đầu một module mới.
markdown
# [Tên Module]
## 1. Tổng quan
Mô tả mục đích của module. Đề cập đến vai trò của nó như một **SCS** (Hệ thống Tự trị).
## 2. Các Tính năng Chính
- **[Tính năng 1]**: Tiêu chí nghiệm thu và logic nghiệp vụ.
- **[Tính năng 2]**: Tiêu chí nghiệm thu và logic nghiệp vụ.
## 3. Mockup
<div class="spec-frame">
<!-- Mã CSS Mockup tại đây -->
</div>
## 4. Tham chiếu Kỹ thuật
### Schema Cơ sở dữ liệu
| Bảng | Cột | Mô tả |
|:---|:---|:---|
| `tên_bảng` | `id`, `org_id`, ... | Mục đích của bảng |
### Các điểm cuối API
<span class="method get">GET</span> `/api/[tài-nguyên]` — Danh sách mục.
<span class="method post">POST</span> `/api/[tài-nguyên]` — Tạo mục mới.
### Ma trận RBAC
| Quyền | Tài nguyên | Hành động | Vai trò mặc định |
|:---|:---|:---|:---|
| Xem mục | `items` | `read` | Tất cả người dùng |Áp dụng thực tế
Để xem sơ đồ này được áp dụng vào một module thực tế, hãy tham khảo tài liệu Module Drive.