/project)Tài liệu thiết kế + đặc tả triển khai cho module quản trị dự án VIETAL tại
https://dv.badt.vn/project (máy chủ biên 245), do hai quản trị viên vận hành và
mở API cho các AI Agent trong cụm (local LLM 250, DeepSeek, Claude).
| Hạng mục | Giá trị |
|---|---|
| Điểm vào | https://dv.badt.vn/project |
| Web server | Apache 2.4 trên máy 245, PHP-FPM 8.3 pool riêng (php8.3-fpm-dv.badt.vn.sock) |
| Mã nguồn | /var/www/html/dv.badt.vn/vietal_project/ — ngoài webroot |
| Webroot của module | /var/www/html/dv.badt.vn/public_html/project/ (chỉ index.php, .htaccess, assets/) |
| CSDL | MySQL 8 — vietal_project @ 192.168.1.244, user vietal_app (chỉ quyền trên DB này), 17 bảng |
| Tệp tải lên | /var/www/html/dv.badt.vn/private_vietal_uploads/ — ngoài webroot, chỉ phục vụ qua PHP có xác thực |
| Ngôn ngữ | PHP 8.3 thuần (không framework, không Composer) — đồng bộ với các app sẵn có trên 245 |
| Đăng nhập | Chỉ 2 tài khoản (liemvt@pnt.edu.vn, saber.aloui@chu-angers.fr) — mỗi tài khoản nhận thêm 1 alias Gmail; mật khẩu bcrypt cost 12 |
---
1. Tiến độ & hoạt động: Kanban 6 cột + timeline theo mốc (milestone), có người phụ trách,
hạn chót, % hoàn thành, lịch sử thay đổi.
2. Tài chính & ngân sách: ghi nhận thu / chi / cam kết, phân loại hạng mục, nguồn tài trợ,
số chứng từ; tổng hợp theo hạng mục và theo tháng; đối chiếu với ngân sách được duyệt.
3. Sản phẩm & sự kiện: lịch sử cuộc họp – tập huấn – báo cáo, kèm biên bản và tài liệu đầu ra.
4. Minh chứng & hình ảnh: tải lên ảnh/tài liệu/biên bản, lưu metadata (thời điểm ghi nhận,
người tải, MIME, dung lượng, SHA-256), phục vụ kiểm tra/kiểm định về sau.
5. Cổng AI Agents: token API để agent đẩy log, cập nhật tiến độ, nộp báo cáo, tải minh chứng,
nhận việc được giao; giao diện chat đa nhiệm với agent ngay trong trang quản trị.
---
┌──────────────────────────────────────────────────────────────────────────────┐
│ Người dùng (2 quản trị viên) AI Agents (250 / cloud) │
│ Trình duyệt ──HTTPS──┐ DeepSeek · Claude · Qwen │ │
└───────────────────────┼──────────────────────────────────────────────┼────────┘
│ │ Bearer token
▼ ▼
┌───────────────────────────────────────────────────────────────────────┐
│ Apache 2.4 — máy 245 · vhost dv.badt.vn (:443, ModSecurity On) │
│ /project/* → public_html/project/index.php (+ .htaccess rewrite) │
│ PHP qua socket riêng php8.3-fpm-dv.badt.vn.sock │
└───────────────────────────────┬───────────────────────────────────────┘
▼
┌───────────────────────────────────────────────────────────────────────┐
│ vietal_project/ (NGOÀI webroot) │
│ bootstrap.php → Router → Controller → View │
│ lib/: db · auth · api · crypto · llm · repo · view · router │
│ storage/: app.key · logs/ · ratelimit/ │
└───────┬───────────────────────────────┬───────────────────────────────┘
│ PDO (utf8mb4) │ cURL (OpenAI-compatible)
▼ ▼
┌────────────────────────────┐ ┌──────────────────────────────────────────┐
│ MySQL 8 @ 192.168.1.244 │ │ LLM: 192.168.1.250:8091 (qwen2.5-7b) │
│ DB vietal_project │ │ api.deepseek.com / api.anthropic.com│
│ 13 bảng, InnoDB, utf8mb4 │ │ (api key mã hoá AES-256-GCM) │
└────────────────────────────┘ └──────────────────────────────────────────┘
| Tiêu chí | PHP thuần (đã chọn) | Laravel | FastAPI |
|---|---|---|---|
| Khớp hạ tầng 245 | Có sẵn Apache + PHP 8.3 pool riêng cho dv.badt.vn | Cần composer + storage symlink + cấu hình thêm | Cần thêm service Python + reverse proxy |
| Thời gian dựng & bảo trì | 0 dependency, deploy bằng rsync | Nặng, nhiều tầng cache | Phải quản lý process (systemd/uvicorn) |
| Đồng bộ với app khác trên 245 | Giống /ai/*, cùng kiểu auth/DB config | Khác biệt | Khác biệt |
| Kiểm soát bảo mật | Toàn bộ luồng nằm trong ~2.000 dòng dễ audit | Nhiều magic | Tốt nhưng thêm bề mặt vận hành |
Kết luận: PHP 8.3 thuần, tự viết router/PDO — phù hợp cụm máy hiện tại, không thêm runtime.
Kiến trúc vẫn tách lớp (router → controller → repo/view) để có thể chuyển sang Laravel sau này.
vietal_project/ # NGOÀI webroot
├── bootstrap.php # nạp cấu hình, thư viện, đăng ký route, dispatch
├── bootstrap_cli.php # dùng cho bin/*.php
├── routes.php # bảng định tuyến (web + api/v1)
├── config/config.php # DB, bảo mật, upload, LLM (quyền 640)
├── lib/
│ ├── helpers.php # cfg/e/url/flash/money/json_out/app_log…
│ ├── db.php # PDO singleton + q/row/rows/val/ins/upd
│ ├── auth.php # session, CSRF, đăng nhập, throttle, ACL
│ ├── api.php # Bearer token, scope, rate limit, JSON errors
│ ├── crypto.php # AES-256-GCM cho API key agent, token hash
│ ├── llm.php # gọi LLM (OpenAI-style / Anthropic), context dự án
│ ├── repo.php # truy vấn nghiệp vụ dùng chung
│ ├── view.php # render view + layout
│ └── router.php # router + security headers
├── controllers/ # Auth/Dashboard/Board/Finance/Evidence/Event/Agent/Chat/Account/Api
├── views/ # layout, login, dashboard, board, finance, evidence, events, agents, chat, account
├── public_assets/ # app.css, app.js (copy sang webroot/assets khi deploy)
├── public/ # index.php + .htaccess (copy sang webroot)
├── sql/schema.sql # 13 bảng
├── bin/
│ ├── install.php # tạo bảng + seed + cấp token mẫu
│ ├── check.php # kiểm tra sức khoẻ (DB, bảng, quyền, LLM)
│ ├── user_set.php # đổi mật khẩu / thêm tài khoản trong danh sách trắng
│ └── token.php # cấp / thu hồi token agent
├── storage/ # app.key, logs/, ratelimit/ (ngoài webroot)
├── docs/THIET_KE_HE_THONG.md # tài liệu này
└── deploy.sh # rsync + cấp quyền + reload FPM
---
17 bảng InnoDB/utf8mb4. Khoá ngoại bật đầy đủ; xoá dự án sẽ cascade công việc/tài chính/minh chứng,
xoá agent sẽ cascade token/job.
vietal_users ─┐ ┌──────────────┐ ┌────────────────────┐
├──owner─►│vietal_projects│◄──────│vietal_ai_agents │
│ └──────┬───────┘ └─────┬──────────────┘
│ │ │
│ ┌─────────┼──────────┬───────────┼─────────────┐
│ ▼ ▼ ▼ ▼ ▼
│ vietal_tasks vietal_budget vietal_events vietal_agent_tokens
│ │ _entries │ │
│ │ │ │ ▼
│ ▼ │ │ vietal_agent_jobs
│ vietal_evidence ◄┴──────────┘ │
│ ▲ │
│ │ │
│ vietal_logs ◄───────────────────────────────┘
│
vietal_chat_threads ── vietal_chat_messages
vietal_login_attempts (chống dò mật khẩu)
vietal_projects — dự án| Cột | Kiểu | Ghi chú |
|---|---|---|
| id | INT UNSIGNED PK | |
| code | VARCHAR(40) UNIQUE | dùng trong API (project=VIETAL-2026) |
| name, description | VARCHAR(190), TEXT | |
| status | ENUM planning/active/paused/completed/archived | |
| start_date, end_date | DATE | |
| budget_planned | DECIMAL(15,2) | ngân sách được duyệt |
| currency | CHAR(3) | mặc định VND |
| progress | TINYINT | tính lại tự động = AVG(tiến độ công việc ≠ backlog) |
| owner_id | FK users |
vietal_tasks — công việc & mốc (Kanban + Timeline)| Cột | Kiểu | Ghi chú |
|---|---|---|
| id, project_id (FK), parent_id (FK self) | cho phép chia việc con | |
| type | ENUM task,milestone | milestone hiển thị ở tab Timeline |
| title, description | ||
| status | ENUM backlog/todo/doing/review/done/blocked | 6 cột Kanban |
| priority | ENUM low/normal/high/critical | |
| assignee_id (FK users), agent_id (FK agents) | việc do người hay agent làm | |
| start_date, due_date, completed_at | ||
| progress | TINYINT 0–100 | kéo sang done ⇒ 100 |
| sort_order | INT | thứ tự trong cột |
Chỉ mục: (project_id, status, sort_order), due_date, agent_id.
vietal_logs — nhật ký hoạt động| Cột | Kiểu | Ghi chú |
|---|---|---|
| actor_type | ENUM user/agent/system | phân biệt thao tác người và máy |
| actor_id, actor_label | ||
| action | VARCHAR(60) | task.move, finance.create, agent.report… |
| message | VARCHAR(500) | hiển thị ở feed |
| payload | JSON | dữ liệu thay đổi (audit) |
| project_id (FK), task_id, evidence_id, ip |
Ghi mọi thao tác ghi dữ liệu (tạo/sửa công việc, giao dịch, upload, cấp token, đăng nhập).
vietal_evidence — minh chứng, sản phẩm| Cột | Kiểu | Ghi chú |
|---|---|---|
| project_id (FK), task_id (FK), event_id (FK) | liên kết ngữ cảnh | |
| kind | ENUM image/document/minutes/artifact/report/other | biên bản họp = minutes |
| title, description | ||
| original_name, stored_name | stored_name = 2026/04/<random>.<ext> | |
| mime, size_bytes, sha256 | kiểm tra toàn vẹn | |
| meta | JSON | nguồn (web/api), agent, IP |
| captured_at | DATETIME | thời điểm chụp/ghi nhận (khác thời điểm upload) |
| uploaded_by_type, uploaded_by, uploader_label, uploaded_at | người upload |
vietal_ai_agents — agent đăng ký| Cột | Kiểu | Ghi chú |
|---|---|---|
| code UNIQUE, name | tro-ly-vietal, deepseek-planner | |
| vendor | ENUM local/deepseek/claude/openai/custom | quyết định cách gọi |
| model, endpoint | ghi đè mặc định trong config | |
| api_key_enc | VARCHAR(512) | AES-256-GCM, khoá ở storage/app.key (0600) |
| system_prompt | TEXT | vai trò agent |
| capabilities, status, last_seen_at | heartbeat cập nhật last_seen_at |
| Bảng | Vai trò |
|---|---|
vietal_users | 2 tài khoản quản trị: email UNIQUE, password_hash bcrypt, must_change_pw, failed_attempts, locked_until, last_login_* |
vietal_budget_entries | sổ thu/chi/cam kết: kind, category, amount, funder, ref_no, entry_date |
vietal_events | cuộc họp/tập huấn/báo cáo: starts_at, ends_at, location, participants, notes |
vietal_agent_tokens | token_hash (sha256), scopes, expires_at, revoked_at, last_used_at |
vietal_agent_jobs | việc giao cho agent: status queued/running/done/failed, result, token/cost |
vietal_chat_threads / vietal_chat_messages | hội thoại đa nhiệm; tin nhắn có role user/agent/system, meta (model, latency, usage) |
vietal_login_attempts | đếm lần đăng nhập sai theo email + IP |
vietal_indicators | 32 chỉ số của khung logic: mã (1.1, 2.1.1…), gốc, đích M6/M12/M20, cách tính, tần suất, nguồn kiểm chứng, phân tách, giá trị hiện tại |
vietal_budget_lines | 29 dòng kế hoạch ngân sách theo Annexe B (mã 1.1.1.1 … 8), đơn vị, số lượng, đơn giá, tổng, năm 1 |
vietal_requests | yêu cầu/hỏi đáp giữa quản trị viên và agent: hướng (to_agent/from_agent), loại (request/question/blocker/review), trạng thái, câu trả lời |
vietal_resources | danh mục nguồn lực AI (LLM/OCR/ASR/TTS): endpoint, model, scope public/lan, token mã hoá, health gần nhất |
DATETIME theo +07:00 (PDO SET time_zone), hiển thị d/m/Y H:i.DECIMAL(15,2) + currency; hiển thị rút gọn (tr, tỷ).ON DELETE CASCADE (dữ liệu con) hoặc SET NULL (người phụ trách) — không xoá mất lịch sử tài chính khi xoá user.vietal_logs là append-only; không có API sửa/xoá log.---
data/plan.php là bản tách có cấu trúc từ thư mục /home/liem/vietal (4 tệp gốc):
| Tệp nguồn | Nội dung đã tách | Đích trong CSDL |
|---|---|---|
Cadre_Logique_VIETAL_VF.xlsx | Mục tiêu chung, 4 mục tiêu cụ thể (OS1–OS4), 6 kết quả (R1–R6), 32 chỉ số với gốc/đích M6–M12–M20, 21 hoạt động A0.1–A6.4, 5 mốc báo cáo | vietal_indicators (32), vietal_tasks (13 mốc + 20 đầu việc) |
Annexe_B_Budget_VIETAL_VF_CHU_chef_de_file.xlsx | 6 nhóm + 23 dòng ngân sách, đơn vị/số lượng/đơn giá, tổng 250.000 EUR (trực tiếp 233.645 + 16.355 quản lý 7%) | vietal_budget_lines (29 dòng) |
Guide_indicateurs_VIETAL_V1.docx | Công thức tính, tần suất thu thập, nguồn kiểm chứng, phân tách, điểm cảnh báo từng chỉ số | cột method, frequency, source, disaggregation của vietal_indicators |
DAJ_F030 … .docx | Bản kê khai pháp lý (không thuộc phạm vi quản trị tiến độ) | không nạp |
Thời gian: M1 = 07/2026 → M20 = 02/2028; dự án bắt đầu 2026-07-01, kết thúc 2028-02-29,
ngân sách 250.000 EUR. Trạng thái khởi tạo phản ánh thời điểm 10/2026 (giai đoạn M4):
A0.1/A0.2 hoàn thành, A1.1–A1.3, A4.1, A5.1, A6.1 đang thực hiện, phần còn lại ở trạng thái “cần làm”.
Liên kết công việc ↔ chỉ số: cột vietal_tasks.indicator_codes (ví dụ A1.3 → 1.2.1,1.2.2,1.2.3),
hiển thị trong trang Chỉ số ở mục “Công việc liên quan”. Nhờ đó khi cập nhật một chỉ số có thể truy
ngược ngay hoạt động nào chịu trách nhiệm và ngược lại.
Hai tài khoản, bốn địa chỉ đăng nhập (alias quy về cùng tài khoản, cùng mật khẩu):
| Tài khoản (email chính) | Alias được chấp nhận |
|---|---|
liemvt@pnt.edu.vn | thanhliem.vo@gmail.com |
saber.aloui@chu-angers.fr | saber.aloui@gmail.com |
POST /project/login (email + password + CSRF)
│
├─(1) email ∈ config.security.allowed_emails ? ── không → từ chối, ghi log
├─(2) đếm login_attempts sai trong 15' theo email+IP ── ≥5 → khoá 15'
├─(3) user tồn tại, is_active=1, chưa bị khoá
├─(4) password_verify(bcrypt cost 12)
└─(5) session_regenerate_id(true) → ghi session + log auth.login
INSERT thêm user vào DB.vietal_users) giữ mật khẩu bcrypt và trạng thái khoá.bin/install.php còn chủ động UPDATE vietal_users SET is_active=0 WHERE email NOT IN (...).| Thuộc tính | Giá trị | Lý do |
|---|---|---|
| Tên cookie | VIETALSESS | tách khỏi phiên Chamilo/BSGD trên cùng máy chủ |
| Path | /project/ | không gửi cookie sang /ai, /ba |
| HttpOnly / SameSite=Strict / Secure | bật | chống đọc bằng JS, chống CSRF cross-site, chỉ HTTPS |
session.use_strict_mode | 1 | không nhận session id do client tự đặt |
| Save path | /var/lib/php/sessions_vietal (700, www-data) | tách khỏi session PHP mặc định |
| Idle timeout | 2 giờ | |
| Absolute timeout | 12 giờ | |
| Fingerprint | sha256(User-Agent + uid) so mỗi request | phát hiện cookie bị dùng ở máy khác |
| CSRF | token 32 byte/phiên; mọi POST + header X-CSRF-Token cho fetch |
role = admin (2 tài khoản) — toàn quyền; role = viewer để dành cho nhu cầu sau (chỉ đọc).require_login() cho mọi trang quản trị; require_admin() cho hành động nhạy cảm (đang áp dụng cho toàn bộ controller quản trị qua require_login() + kiểm tra role khi mở rộng).
/evidence/{id}/file bắt buộc đăng nhập, kiểm tra realpath nằm trong thư mục upload (chống path traversal), trả Content-Disposition: inline cho ảnh/PDF, attachment cho phần còn lại.
X-Content-Type-Options, X-Frame-Options: SAMEORIGIN, Referrer-Policy, Permissions-Policy, COOP, HSTS khi HTTPS,
CSP default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; frame-ancestors 'none'.
<meta name="robots" content="noindex, nofollow">.dv.badt.vn vẫn bật ModSecurity/CRS như các app khác. thư mục ngoài webroot, chmod 0640, lưu SHA-256. Không cho .php, .svg, .html.
Authorization: Bearer vtk_<48 hex> (hỗ trợ thêm header X-Api-Token)
server: sha256(token) → tra vietal_agent_tokens → kiểm tra
revoked_at IS NULL · expires_at · agent.status='active' · scope
→ rate limit 120 req/phút/token → cập nhật last_used_at + agents.last_seen_at
bin/token.php).hash_equals (tra cứu theo hash, không so chuỗi thô).UPDATE vietal_agent_tokens SET revoked_at=NOW(); hết hạn theo expires_at.flock trong storage/ratelimit/ (không cần Redis).---
| Trang | Route | Nội dung chính |
|---|---|---|
| Tổng quan | / | 6 thẻ KPI (tiến độ, việc đang làm, ngân sách đã dùng, số dư, minh chứng, agent), mini-Kanban, mốc sắp tới, cơ cấu chi phí, feed hoạt động, minh chứng mới, sự kiện, trạng thái agent |
| Đăng nhập | /login | form 2 trường, thông báo lỗi chung (không tiết lộ email tồn tại) |
| Tiến độ | /board | Kanban 6 cột kéo–thả, lọc nhanh, hộp thoại thêm/sửa, tab Timeline theo tháng |
| Chỉ số | /indicators | 32 chỉ số đề án nhóm theo OS1–OS4 và R1–R6: gốc, đích M6/M12/M20, thanh tiến độ, ô cập nhật giá trị, chi tiết cách đo/nguồn kiểm chứng |
| Tài chính | /finance | 4 thẻ tổng, biểu mẫu ghi sổ (thu/chi/cam kết), cơ cấu hạng mục, dòng tiền theo tháng (CSS bar), kế hoạch ngân sách Annexe B (29 dòng), sổ giao dịch 200 dòng |
| Minh chứng | /evidence | form upload + lọc theo loại, lưới thẻ có ảnh xem trước / nhãn định dạng, metadata (thời điểm, người tải, MIME, SHA-256) |
| Sự kiện | /events | form thêm, timeline sự kiện sắp tới/đã qua, liên kết biên bản |
| Agents | /agents | danh sách agent + trạng thái kết nối, cấp token (hiện một lần), bảng token, bảng job, form giao việc, snippet curl |
| Trao đổi | /chat | danh sách hội thoại, khung chat, gọi LLM theo agent, poll 7 giây để nhận tin agent đẩy vào qua API |
| Tài khoản | /account | thông tin, đổi mật khẩu (≥10 ký tự), 10 lần đăng nhập gần nhất |
Thiết kế giao diện: sidebar tối cố định, nội dung sáng, thẻ bo 14px, responsive:
≤900px sidebar thành thanh cuộn ngang trên đầu, Kanban cuộn ngang từng cột, form về 1 cột.
Không dùng thư viện JS/CSS ngoài (đúng CSP script-src 'self'), biểu đồ vẽ bằng CSS.
dragstart (data-task=id) → drop vào [data-drop=status]
→ DOM di chuyển ngay (lạc quan)
→ POST /project/tasks/{id}/move {status}
+ X-CSRF-Token
← {ok:true,status,progress} → cập nhật số đếm cột + thanh tiến độ
← lỗi → hoàn nguyên DOM + thông báo
→ server ghi vietal_logs `task.move`, tính lại progress dự án
Mỗi lần gửi, server dựng system prompt:
<system_prompt của agent> + DỮ LIỆU DỰ ÁN HIỆN TẠI (tên/trạng thái/tiến độ, số việc theo trạng thái,
thu–chi–cam kết, 8 mốc gần nhất) + 16 tin nhắn gần nhất. Nhờ vậy agent trả lời theo số liệu thật,
không bịa. Kết quả gọi LLM được lưu kèm meta (model, latency, usage) và ghi vietal_logs.
---
Giao diện có hai ngôn ngữ, đổi bằng cặp nút VI · FR ở chân thanh bên (và ở trang đăng nhập).
Lựa chọn lưu trong phiên + cookie VIETALLANG (180 ngày, path /project/).
| Lớp | Cơ chế | Tệp |
|---|---|---|
| Nhãn giao diện | Danh mục dịch VI→FR, áp dụng lên HTML ở cuối request | lang/fr.php, lib/i18n.php |
| Nội dung đề án | Cột JSON fr trên vietal_projects / tasks / indicators / events, chọn bằng tf() | data/plan_fr.php + bin/install.php |
| Số & ngày | num() đổi dấu phân cách (vi 1.500.000 ↔ fr 1 500 000), ngày giữ dd/mm/yyyy | lib/i18n.php |
| Nội dung động (nhật ký, yêu cầu, minh chứng, hội thoại, đầu việc thiếu bản dịch) | Dịch bằng LLM qwen2.5-7b theo lô, cache tệp storage/tr/, glossary sửa calque khi đọc; dịch sẵn bằng bin/translate_fr.php | lib/tr.php,
bin/translate_fr.php |
| Chat với agent | Khi giao diện FR, system prompt thêm chỉ dẫn “Réponds en français” | controllers/ChatController.php |
|---|---|---|
| Ngữ cảnh agent | Tên mốc/trạng thái trong llm_project_context() cũng lấy theo ngôn ngữ | lib/llm.php |
Vì sao dùng bộ lọc theo text-node: bộ lọc chỉ thay khi toàn bộ nút văn bản khớp chính xác
(hoặc khớp tiền tố/hậu tố đã khai báo), nên nhật ký hoạt động, nội dung biên bản, câu trả lời của
agent… không bị dịch lẫn (tránh “Franglais”). Các câu dài (>20 ký tự) được phép thay trong
chuỗi ghép để xử lý tiêu đề <title> và các đoạn văn có thẻ inline.
Thêm chuỗi mới: thêm một dòng 'chuỗi tiếng Việt' => 'Chaîne française' vào lang/fr.php
(chuỗi ngắn nên khai báo kèm tiền tố/hậu tố, ví dụ 'Mã: ' hoặc ' việc khác').
Thêm nội dung song ngữ: bổ sung khoá tương ứng trong data/plan_fr.php rồi chạy lại
php bin/install.php (idempotent) để ghi cột fr.
Kiểm chứng tự động: đăng nhập với ?lang=fr, tải 9 trang, tách text node và tìm ký tự riêng
tiếng Việt (ă đ ơ ư ạ ả ã …). Sau khi hoàn thiện, chỉ còn lại nhật ký cũ, tiêu đề hội thoại cũ,
tên riêng (Việt Nam) và ảnh minh chứng thử nghiệm — đúng như mong đợi vì đó là dữ liệu, không phải nhãn.
Tiền tố: https://dv.badt.vn/project/api/v1 · Auth: Authorization: Bearer vtk_…
| Method | Endpoint | Scope | Mô tả | Body chính |
|---|---|---|---|---|
| GET | /ping | read | kiểm tra token + danh sách endpoint | — |
| GET | /projects | read | danh sách dự án | — |
| GET | /projects/{code}/summary | read | KPI + mốc của một dự án | — |
| GET | /tasks?project=CODE&status=doing&type=task&limit=100 | read | danh sách công việc | — |
| GET | /indicators?project=CODE | read | 32 chỉ số + giá trị hiện tại + % đạt đích | — |
| POST | /indicators/{code} | write | agent ghi giá trị chỉ số | {value, note} |
| POST | /tasks/{id}/progress | write | cập nhật tiến độ/trạng thái | {status, progress, message} |
| POST | /logs | write | đẩy nhật ký xử lý | {project, action, message, task_id?, payload?} |
| POST | /reports | write | nộp báo cáo (lưu thành minh chứng .md) | {project, title, content, kind?, task_id?} |
| POST | /evidence | write | tải minh chứng | multipart file hoặc JSON {filename, content_base64} + project,kind,title |
| GET | /chat/messages?thread_id=&after_id= | read | đọc tin nhắn; không có thread_id ⇒ liệt kê hội thoại của agent | — |
| POST | /chat/messages | write | agent gửi tin vào hội thoại (tự tạo nếu chưa có) | {thread_id?‖project+thread_title, content} |
| GET | /jobs?status=queued | read | nhận việc được giao | — |
| POST | /jobs | write | agent tự đề xuất việc | {title, instruction, project?} |
| POST | /jobs/{id} | write | báo trạng thái/kết quả | {status, result, tokens_in, tokens_out} |
| POST | /heartbeat | read | duy trì trạng thái agent | {status, note?} |
{ "ok": true, "task": { "id": 12, "status": "doing", "progress": 60 } }
{ "ok": false, "error": "invalid_status", "message": "status phải là: backlog, todo, …" }
Mã lỗi: 401 missing_token|invalid_token|expired|revoked, 403 scope|agent_inactive,
404 project_not_found|task_not_found|thread_not_found, 405 method_not_allowed,
422 …, 429 rate_limited (kèm Retry-After).
export VIETAL_TOKEN='vtk_…'
BASE=https://dv.badt.vn/project/api/v1
curl -s -H "Authorization: Bearer $VIETAL_TOKEN" $BASE/ping
curl -s -X POST $BASE/logs -H "Authorization: Bearer $VIETAL_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"project":"VIETAL-2026","action":"analysis.done","message":"Đã rà soát 42 hồ sơ"}'
curl -s -X POST $BASE/tasks/12/progress -H "Authorization: Bearer $VIETAL_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"status":"doing","progress":60,"message":"Đang tổng hợp số liệu quý 1"}'
curl -s -X POST $BASE/reports -H "Authorization: Bearer $VIETAL_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"project":"VIETAL-2026","title":"Báo cáo tuần 12","content":"# Kết quả\n- …"}'
| Kiểu | vendor | Cần API key | Gọi tới |
|---|---|---|---|
| Local LLM trong cụm | local | không | http://192.168.1.250:8091/v1/chat/completions (vLLM, bắt buộc field model) |
| DeepSeek | deepseek | có | https://api.deepseek.com/v1/chat/completions |
| Claude | claude | có | https://api.anthropic.com/v1/messages (x-api-key, anthropic-version) |
| Agent tự viết | custom | tuỳ | agent gọi vào API của VIETAL; không cần endpoint LLM |
API key nhập ở trang Agents được mã hoá AES-256-GCM trước khi ghi vietal_ai_agents.api_key_enc;
khoá chính ở storage/app.key (0600, ngoài webroot, không commit).
---
Hệ thống được thiết kế để agent làm việc, người chỉ huy. Chi tiết đầy đủ cho agent:
docs/AGENT_WORKSPACE.md · đặc tả máy đọc docs/openapi.yaml ·
worker mẫu tools/vietal_agent.py.
| Cơ chế | Bảng/cột | Ý nghĩa |
|---|---|---|
| Token theo agent | vietal_agent_tokens | mỗi agent một (hoặc nhiều) token vtk_…, scope read/write, có hạn/thu hồi |
| Lease giữ việc | vietal_tasks.claimed_by_agent / claim_token / claim_expires_at | chống 2 agent làm trùng một việc; hết hạn tự nhả, gia hạn bằng claim lại |
| Yêu cầu / hỏi đáp | vietal_requests | người giao việc (to_agent) hoặc agent hỏi/vướng mắc (from_agent), có trả lời của quản trị viên |
| Nguồn lực | vietal_resources | agent tự khám phá LLM/OCR/ASR/TTS nội bộ & công khai, kèm health và cách xác thực |
| Gói khởi động | GET /api/v1/workspace | một lời gọi trả về: việc nên làm, yêu cầu mở, job, nguồn lực, quy trình 6 bước |
| Nhật ký | vietal_logs | mọi thao tác của agent có actor_type=agent, actor_label, ip |
workspace → chọn việc → claim (lease 120') → context (chỉ số + minh chứng + sự kiện)
→ dùng nguồn lực (LLM/OCR/ASR/TTS) → progress → deliverable (review) → release
↘ thiếu dữ liệu → POST /requests ← quản trị viên trả lời trên web
| Nhóm | Ví dụ | Ai gọi được |
|---|---|---|
scope=public | pnt.badt.vn/gemma4, /medgemma, /deepseek_ocr, /medical_transcribe, /text2speech | agent ngoài Internet (HTTPS) |
scope=lan | 192.168.1.250:8091 (qwen2.5-7b), :8092 (gemma4) | agent chạy trong LAN 192.168.1.0/24 |
Trang quản trị /resources hiển thị endpoint, model, token (nếu có), nút Kiểm tra (gọi health_url)
và nút Kiểm tra tất cả. Agent đọc cùng danh mục qua GET /api/v1/resources (token write nhận thêm
auth_header/auth_value).
| Hạng mục | Đường dẫn | Ghi chú |
|---|---|---|
| Trang tài liệu công khai | /project/docs (HTML) và /project/docs/{slug}.md (raw text/markdown) | Claude web fetch được, không cần token |
| Tài liệu kỹ thuật | docs/README.md, AGENT_WORKSPACE.md, AGENT_CLAUDE.md, openapi.yaml, TOM_TAT_DE_AN.md, THIET_KE_HE_THONG.md | phục vụ trực tiếp từ repo (ngoài webroot), whitelist slug |
| API tài liệu | GET /api/v1/docs, GET /api/v1/docs/{slug} | cho agent có token |
| Bóc nội dung minh chứng | GET /api/v1/documents/{id} (cache trong vietal_evidence.text_extract) | PDF → pdftotext; scan → OCR; DOCX/XLSX/PPTX → đọc XML; ảnh → OCR |
| Bóc lại | POST /api/v1/documents/{id}/extract | khi cache rỗng/sai |
| Tìm tài liệu | GET /api/v1/documents?q=… | tìm trong tiêu đề, mô tả và text đã bóc |
Nhờ đó Claude đọc được nội dung tài liệu (không cần tải tệp nhị phân), và nếu bản scan mờ thì
tải bản gốc (GET /api/v1/evidence/{id}/file) để đọc trực tiếp bằng vision.
32 endpoint dưới /api/v1 (16 endpoint dữ liệu + 11 endpoint môi trường làm việc + 5 endpoint tài liệu/bóc text), xem bảng đầy đủ
trong AGENT_WORKSPACE.md mục 5 hoặc openapi.yaml.
/intake)Mục đích: người quản trị dán văn bản (biên bản họp, báo cáo tiến độ, email, tin nhắn, yêu cầu) — hệ thống
phân tích bằng mô hình nội bộ rồi ghi thẳng cập nhật vào dự án. Con người chỉ đọc báo cáo, agent làm việc.
Chuỗi mô hình (config/config.php → ingest.chain), tự dự phòng theo thứ tự:
| Thứ tự | Endpoint | Ghi chú |
|---|---|---|
| 1 | http://192.168.1.250:8094/v1 · qwen3-14b | máy 250, phân tích chính |
| 2 | http://192.168.1.250:8091/v1 · qwen2.5-7b | dự phòng khi 14B bận/chết |
| 3 | http://192.168.1.250:8092/v1 · google/gemma-4-e2b-it | dự phòng cuối |
ingest_chat() thử /models từng endpoint (2 giây) rồi gọi /chat/completions; endpoint lỗi bị bỏ qua và
ghi lại trong tried. Cột vietal_intake.model cho biết mô hình nào thực sự đã xử lý.
Luồng dữ liệu
1. POST /intake/analyze (hoặc POST /intake/queue nếu mô hình bận) → lưu vietal_intake (raw_text, status).
2. Prompt hệ thống gồm bối cảnh dự án (mã + tên công việc, chỉ số) và schema JSON bắt buộc.
3. ingest_analyze() → JSON {summary, items[]}; sai định dạng thì nhắc lại 1 lần.
4. ingest_apply() ghi từng mục: task_update, task_new, log, request, indicator, budget;
mục không hợp lệ bị bỏ qua và ghi lý do, không làm hỏng cả lô. Sau đó recalc_project_progress().
5. ingest_dispatch() (nút «Chuyển ra agent ngoài») tạo vietal_requests hướng to_agent; nếu có
storage/deepseek.key thì gọi DeepSeek soạn kế hoạch thực hiện và lưu vào answer (status answered).
API: POST /api/v1/intake {text, project, apply} · GET /api/v1/intake?status= · GET /api/v1/intake/{id}.
Worker: bin/intake_worker.php [n] xử lý tối đa n bản ghi queued; cron 5 phút trên máy 245
(/var/www/html/cron/vietal_intake_worker.sh, log /var/log/vietal_intake.log).
Khoá bí mật: storage/deepseek.key (0600, www-data), không nằm trong git và bị deploy.sh loại trừ.
Mọi đường vào (trang /intake, API POST /api/v1/intake, chat «Ghi vào dự án», worker cron) đều dùng chung
một bộ máy lib/ingest_plan.php:
1. Phân tích → ingest_analyze_all() (tự chia khối ~6.000 ký tự khi văn bản dài, gộp mục trùng).
2. Xem trước → ingest_plan(..., commit=false): trả đúng danh sách thay đổi (thêm/cập nhật/bỏ qua + lý do),
không ghi gì vào dự án; lưu vào vietal_intake.preview + warnings.
3. Duyệt → ingest_commit() (web POST /intake/{id}/apply, API POST /api/v1/intake/{id}/apply)
ghi thật, lưu snapshot (giá trị cũ của đúng các cột đã đổi) và applied_at.
4. Hoàn tác → ingest_revert() (web POST /intake/{id}/revert, API tương ứng): khôi phục cột cũ,
xoá bản ghi vừa tạo (giữ lại việc đã có việc con/minh chứng), trạng thái reverted.
Chống lỗi dữ liệu:
| Tình huống | Cách chặn |
|---|---|
| Dán trùng văn bản | raw_hash (sha256 sau chuẩn hoá) + kiểm tra theo dự án, trạng thái analyzed/applied → trả về bản ghi cũ |
| Việc/sự kiện/khoản chi trùng | so khớp mã + ngày + số tiền + nội dung trước khi ghi |
| Ghi 2 lần do cron + web | giữ chỗ nguyên tử processing + trạng thái chỉ cho ghi từ analyzed/error |
| Số tiền sai đơn vị | giữ currency từ văn bản (EUR/VND/USD), khoản chi gắn được task_id |
| Ngày vô lý (1970/2999) | ingest_date_ok() chỉ nhận 2000–2100; thiếu ngày thì dùng hôm nay kèm cảnh báo |
| Mô hình bịa | mỗi mục phải có evidence khớp nguyên văn; không khớp → loại và ghi lý do |
| Chỗ mơ hồ | item question → hiện ở khối «Cảnh báo và câu hỏi cần làm rõ», không ghi |
| Cần tra lại | storage/intake/{id}.json giữ nguyên phản hồi của mô hình (0600) |
Mô hình: danh sách kề parent_id + cột path (/12/45/78/) và depth. Không giới hạn số thế hệ.
Mỗi node có mã tự sinh theo cha: A1.1 → A1.1.1 → A1.1.1.1 → …
Thuộc tính một công việc (bảng vietal_tasks):
| Nhóm | Cột |
|---|---|
| Định danh | code, parent_id, path, depth, type (task/milestone), work_type (task/meeting/document/training/travel/procurement/clinical/finance/other) |
| Nội dung | title, description, deliverables (sản phẩm/đầu ra), tags, location (địa điểm) |
| Thời gian | start_date, due_date, completed_at, progress |
| Tài chính | est_cost, currency; các khoản thực tế nằm ở vietal_budget_entries.task_id |
| Minh chứng | vietal_evidence.task_id (ảnh, biên bản, sản phẩm — tải qua /tasks/{id}/evidence) |
| Thực thi | assignee_id, agent_id, lease (claimed_by_agent, claim_token, claim_expires_at) |
Quy tắc cộng dồn: việc có con thì progress = trung bình tiến độ việc con (tự hiệu chỉnh khi thêm/sửa/xoá con);
khi tất cả việc con done thì việc cha tự chuyển done. Việc lá giữ tiến độ nhập tay.
Giao diện: /tasks (cây đầy đủ, có số thế hệ), /tasks/{id} (thuộc tính, việc con, ảnh minh chứng,
tài chính của cả nhánh, nhật ký). Kanban /board vẫn dùng để kéo trạng thái.
API cho agent:
GET /api/v1/tasks?project=…&tree=1 — cả cây lồng nhau; &parent=<id> lọc con trực tiếpGET /api/v1/tasks/{id} — thuộc tính + tổ tiên + việc con + tài chính + minh chứngPOST /api/v1/tasks — tạo việc/việc con: {title, parent:"A1.1", work_type, deliverables, location, est_cost, start_date, due_date, status, progress}POST /api/v1/tasks/{id} — cập nhật thuộc tính (agent có scope write)Bộ phân tích văn bản (lib/ingest.php) sinh được task_new có parent → tự thành việc con đúng thế hệ,
kèm deliverables, location, est_cost, status (done nếu văn bản nói đã hoàn thành).
/claude)Trang dành cho người vận hành, gồm: cấp token riêng cho agent claude (hiện một lần, 1–365 ngày),
cấu hình MCP sẵn để dán (Claude Desktop claude_desktop_config.json, Claude Code claude mcp add,
.mcp.json), bảng 28 công cụ, câu lệnh giao việc mẫu, nguyên tắc an toàn và bảng xử lý lỗi.
controllers/ClaudeController.php (GET /claude, POST /claude/token), view views/claude.php.tools/vietal_mcp.py v2.0 (28 công cụ) phục vụ tải tại /docs/tool/vietal_mcp.py.POST /tasks/{id}/cost, POST /events, POST /requests/{id}/answer, POST /intake/{id}/apply, POST /intake/{id}/revert.
docs/AGENT_CLAUDE.md (sổ tay 17 mục).dtr() (cache storage/tr), nhãn tĩnh ở lang/fr.php.| # | Kiểm soát | Cách làm trong mã |
|---|---|---|
| 1 | Mã nguồn ngoài webroot | public_html/project/index.php chỉ require file ngoài |
| 2 | Chỉ 2 danh tính | whitelist config + vietal_users + tự vô hiệu user lạ |
| 3 | Mật khẩu mạnh | bcrypt cost 12, tối thiểu 10 ký tự, ép đổi lần đầu (must_change_pw) |
| 4 | Chống dò mật khẩu | vietal_login_attempts theo email và IP, khoá 15 phút sau 5 lần |
| 5 | Chống chiếm phiên | regenerate id, fingerprint UA, idle/absolute timeout, cookie Strict |
| 6 | CSRF | token/phiên, kiểm tra mọi POST (form + fetch header) |
| 7 | XSS | mọi output qua e() (htmlspecialchars ENT_QUOTES), CSP không cho script ngoài |
| 8 | SQL injection | 100% prepared statement, không nối chuỗi từ input |
| 9 | Path traversal | realpath + kiểm tra tiền tố thư mục upload khi trả tệp |
| 10 | Upload độc hại | whitelist ext + MIME, đổi tên ngẫu nhiên, ngoài webroot, chmod 640 |
| 11 | Lộ token | chỉ lưu sha256, hiện một lần, có hạn/thu hồi/rate limit |
| 12 | Lộ API key agent | mã hoá AES-256-GCM, khoá tách riêng 0600 |
| 13 | Dấu vết kiểm toán | vietal_logs append-only cho mọi thao tác ghi |
| 14 | Thông báo lỗi | production ẩn chi tiết, ghi storage/logs/*.log |
| 15 | Header bảo mật | CSP, HSTS, nosniff, frame-ancestors, referrer |
---
# 1) CSDL (đã tạo sẵn): database vietal_project + user vietal_app @192.168.1.%
# 2) Đồng bộ mã + assets + cấp quyền + reload FPM
./deploy.sh
# 3) Khởi tạo bảng + dữ liệu mẫu + tài khoản + token agent
ssh may245 "cd /var/www/html/dv.badt.vn/vietal_project && sudo -u www-data php bin/install.php"
# 4) Kiểm tra sức khoẻ
ssh may245 "cd /var/www/html/dv.badt.vn/vietal_project && php bin/check.php"
Quyền chuẩn trên máy chủ:
| Đường dẫn | Quyền |
|---|---|
vietal_project/ (mã) | liem:www-data, thư mục 750, tệp 640 |
vietal_project/config/config.php | 640 (chứa mật khẩu CSDL) |
vietal_project/storage/ | www-data, 775 (app.key 600) |
private_vietal_uploads/ | www-data:www-data, 750 |
public_html/project/ | liem:www-data, 755/644 |
/var/lib/php/sessions_vietal | www-data, 700 |
# Đổi mật khẩu / thêm tài khoản (phải nằm trong allowed_emails)
php bin/user_set.php --email=liem@pnt.edu.vn --password='…'
php bin/user_set.php --list
# Cấp / thu hồi token agent
php bin/token.php --agent=tro-ly-vietal --label="Máy 250" --days=90
php bin/token.php --revoke=3
# Kiểm tra sức khoẻ
php bin/check.php
# Sau mỗi lần sửa code trên 245
sudo systemctl reload php8.3-fpm # OPcache giữ bytecode cũ nếu không reload
Cron trên máy 245 (crontab -l của root):
*/30 * * * * /var/www/html/cron/vietal_translate_fr.sh # dịch sẵn nội dung động sang tiếng Pháp
*/5 * * * * /var/www/html/cron/vietal_intake_worker.sh # xử lý hàng đợi tiếp nhận văn bản thô
Log: /var/log/vietal_translate.log (tự cắt khi > 5 MB). Dọn dữ liệu thử:
sudo -u www-data php bin/cleanup_testdata.php — sao lưu JSON vào storage/ trước khi xoá.
# CSDL + tệp minh chứng (chạy trên 244/245, đưa về NAS 239)
mysqldump -h 192.168.1.244 -u vietal_app -p vietal_project --single-transaction \
| gzip -1 > vietal_$(date +%F).sql.gz
tar czf vietal_uploads_$(date +%F).tgz -C /var/www/html/dv.badt.vn private_vietal_uploads
Khuyến nghị đưa vào /var/www/autosys/backup_may245_to_239.sh (lịch 245 hiện có).
| Nơi xem | Nội dung |
|---|---|
storage/logs/app-YYYY-MM.log | exception, lỗi hệ thống |
storage/logs/llm-YYYY-MM.log | lỗi gọi LLM (HTTP code, body 400 ký tự đầu) |
storage/logs/security-YYYY-MM.log | đăng nhập sai, token sai, fingerprint mismatch |
vietal_logs (trong app) | toàn bộ thao tác nghiệp vụ |
/var/log/apache2/dv.badt.vn-error.log | lỗi PHP-FPM/Apache |
---
| # | Kịch bản | Kỳ vọng |
|---|---|---|
| 1 | GET /project/login | 200, form hiển thị, có cookie VIETALSESS |
| 2 | POST login sai email ngoài whitelist | quay lại form, không tạo phiên, vietal_login_attempts +1 |
| 3 | POST login đúng | 302 → /project/, dashboard có dữ liệu |
| 4 | GET /project/ không cookie | 302 → /login |
| 5 | POST form thiếu CSRF | 419 |
| 6 | 6 lần sai liên tiếp | lần 6 bị khoá 15 phút |
| 7 | Kéo thẻ Kanban sang cột khác | cột đếm đổi, CSDL status đổi, log task.move |
| 8 | Ghi giao dịch 100.000.000 | số dư giảm, cơ cấu hạng mục cập nhật |
| 9 | Upload ảnh 2 MB | lưu ngoài webroot, hiện thumbnail, có SHA-256 |
| 10 | Upload .php | bị từ chối 422/thông báo |
| 11 | Tải /evidence/1/file khi chưa đăng nhập | 302 → login |
| 12 | GET /api/v1/ping không token | 401 missing_token |
| 13 | GET /api/v1/ping token sai | 401 invalid_token |
| 14 | POST /api/v1/logs token đúng | 200, log actor_type=agent |
| 15 | 121 request/phút | request 121 → 429 |
| 16 | Chat gửi câu hỏi | có trả lời từ qwen2.5-7b:8091, lưu 2 tin nhắn |
| 17 | Agent đẩy tin qua POST /api/v1/chat/messages | tin hiện trong UI sau ≤7 giây |
| 18 | Đổi mật khẩu rồi đăng nhập lại | mật khẩu cũ bị từ chối |
| 19 | Đăng nhập bằng alias thanhliem.vo@gmail.com | vào đúng tài khoản liemvt@pnt.edu.vn |
| 20 | /indicators | 32 chỉ số, 13 mốc, thanh tiến độ theo đích M20 |
| 21 | Cập nhật chỉ số 6.1.2 = 2 | lưu giá trị, ghi log indicator.update |
| 22 | GET /api/v1/indicators?project=VIETAL-2026 | 200, 32 phần tử, có percent_of_target |
| 23 | POST /api/v1/indicators/1.1.1 value=1 | 200, chỉ số đạt đích, log actor=agent |
---
| Giai đoạn | Nội dung | Ghi chú kỹ thuật |
|---|---|---|
| 2 | Xuất báo cáo PDF/Excel tháng, in Kanban | dùng dompdf/PhpSpreadsheet đặt trong vendor/ ngoài webroot |
| 2 | Đính kèm nhiều tệp cho một minh chứng, xoá mềm | bảng vietal_evidence_files |
| 3 | Việc lặp lại, thông báo hạn chót qua email/Zalo | cron bin/remind.php + SMTP nội bộ |
| 3 | WebSocket/SSE thay poll 7 giây | endpoint /chat/stream |
| 3 | Agent tự chạy job nền (worker Python trên 250) | đọc GET /jobs?status=queued, POST /jobs/{id} |
| 4 | SSO dùng chung api_ai_main (nếu mở rộng >2 người) | đổi attempt_login() sang gọi validate.php của 253 |
| 4 | Ký số minh chứng, chống sửa tệp | đã có SHA-256; thêm chữ ký + niêm phong định kỳ |
---
| Yêu cầu ban đầu | Thành phần đáp ứng |
|---|---|
| Chỉ 2 tài khoản quản trị, mật khẩu bcrypt | vietal_users + config.security.allowed_emails + attempt_login() |
| Chặn request trái phép, kiểm tra session chặt | require_login(), fingerprint, timeout, CSRF, 401/419/403 |
| Kanban/timeline mốc công việc | vietal_tasks (type=milestone), /board (2 tab) |
| Tài chính, dòng tiền, nguồn lực | vietal_budget_entries, /finance, budget_summary() |
| Sản phẩm, biên bản, lịch sử sự kiện | vietal_evidence (kind=artifact/minutes) + vietal_events |
| Upload minh chứng kèm metadata thời gian/người upload | vietal_evidence.captured_at, uploader_label, sha256 + evidence_save_upload() |
| API token cho agent đẩy log/báo cáo/tiến độ | lib/api.php + /api/v1/* (32 endpoint) |
| Giao diện chat với agent trong trang quản trị | /chat + lib/llm.php + vietal_chat_* + vietal_agent_jobs |