# Tài liệu kỹ thuật VIETAL — dành cho AI Agent và quản trị viên

Thư mục này là **nguồn tài liệu duy nhất** cho agent làm việc trên hệ thống quản trị dự án VIETAL.
Đọc công khai tại **https://dv.badt.vn/project/docs** hoặc tải raw markdown tại `/project/docs/{slug}.md`
(agent có token có thể đọc qua `GET /api/v1/docs` và `GET /api/v1/docs/{slug}`).

| Slug | Tệp | Nội dung | Ai đọc |
|---|---|---|---|
| `index` | `README.md` | Danh mục này | tất cả |
| `agent-workspace` | `AGENT_WORKSPACE.md` | Phân vai, kiến trúc truy cập, 27 endpoint, lease, quy ước nộp bài, phối hợp nhiều agent, bảo mật | agent + quản trị |
| `agent-claude` | `AGENT_CLAUDE.md` | **Sổ tay kết nối Claude**: chuẩn bị token, 3 cách kết nối (MCP/Desktop/Code), 28 công cụ, 5 quy trình mẫu, mã lỗi, bảo mật | người vận hành + Claude |
| `de-an` | `TOM_TAT_DE_AN.md` | Toàn bộ đề án: 13 mốc, 20 đầu việc, 32 chỉ số, 29 dòng ngân sách | agent cần ngữ cảnh |
| `thiet-ke` | `THIET_KE_HE_THONG.md` | Thiết kế hệ thống: CSDL, xác thực, giao diện, API, i18n, vận hành | kỹ thuật |
| `openapi` | `openapi.yaml` | Đặc tả OpenAPI 3.0 của Agent API | agent tự cấu hình |
| `mcp-benh-nhan` | `MCP_BENH_NHAN.md` | **MCP bệnh nhân ảo** (`vp_mcp.py`): 19 công cụ cho kho ca JSON và bộ giả lập, cách lấy cookie, cách dùng dòng lệnh | agent làm nội dung ca bệnh |
| `trao-doi` | `QUY_UOC_TRAO_DOI.md` | Quy ước trao đổi Ban điều hành ⇄ trợ lý: kênh nào dùng cho việc gì, tiền tố, nhịp, mẫu câu, điều cấm | cả hai phía |

## Trang cấp token cho Claude

Mở **https://dv.badt.vn/project/claude** (cần đăng nhập) để cấp token, xem cấu hình MCP sẵn để dán
(Claude Desktop / `.mcp.json`), danh sách 28 công cụ và câu lệnh giao việc mẫu.

## Tải công cụ

- MCP server cho Claude (28 công cụ): https://dv.badt.vn/project/docs/tool/vietal_mcp.py
- Worker mẫu (không cần MCP): https://dv.badt.vn/project/docs/tool/vietal_agent.py
- MCP bệnh nhân ảo (19 công cụ): https://dv.badt.vn/project/docs/tool/vp_mcp.py
- CLI bệnh nhân ảo (dùng trong terminal): https://dv.badt.vn/project/docs/tool/vp_cli.py
- Kiểm thử khói MCP: https://dv.badt.vn/project/docs/tool/mcp_smoke.py
- Báo cáo tổng quát dự án (10/2026): https://dv.badt.vn/project/docs/bao-cao

## Thứ tự đọc gợi ý cho agent mới

1. `agent-workspace` mục 1–4 (phân vai, truy cập, bắt đầu, vòng đời việc).
2. `agent-claude` (cách kết nối đúng với Claude + danh sách tool).
3. `de-an` khi cần hiểu nội dung/chỉ số/ngân sách của dự án.
4. `openapi.yaml` khi cần sinh client hoặc kiểm tra schema.

## Quy tắc chung

- Mọi con số phải lấy từ API hoặc tài liệu nguồn; **không suy đoán**.
- Tài liệu dự án nằm trong mục **Minh chứng** — tìm bằng `GET /api/v1/documents?q=…`,
  đọc nội dung đã bóc bằng `GET /api/v1/documents/{id}`.
- Ghi dấu vết công việc bằng `POST /api/v1/logs`; hỏi khi thiếu dữ liệu bằng `POST /api/v1/requests`.
- Không có endpoint xoá dữ liệu; việc duyệt cuối cùng thuộc về quản trị viên.
