← Danh mục tài liệu · raw markdown

VIETAL — Thiết kế hệ thống module Quản trị dự án (/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ụcGiá trị
Điểm vàohttps://dv.badt.vn/project
Web serverApache 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/)
CSDLMySQL 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ậpChỉ 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. Mục tiêu và phạm vi

1.1 Yêu cầu nghiệp vụ

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ị.

1.2 Ngoài phạm vi (giai đoạn 1)

---

2. Kiến trúc tổng thể

┌──────────────────────────────────────────────────────────────────────────────┐
│ 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)        │
   └────────────────────────────┘   └──────────────────────────────────────────┘

2.1 Vì sao chọn PHP thuần (không Laravel/FastAPI)

Tiêu chíPHP thuần (đã chọn)LaravelFastAPI
Khớp hạ tầng 245Có sẵn Apache + PHP 8.3 pool riêng cho dv.badt.vnCần composer + storage symlink + cấu hình thêmCần thêm service Python + reverse proxy
Thời gian dựng & bảo trì0 dependency, deploy bằng rsyncNặng, nhiều tầng cachePhải quản lý process (systemd/uvicorn)
Đồng bộ với app khác trên 245Giống /ai/*, cùng kiểu auth/DB configKhác biệtKhác biệt
Kiểm soát bảo mậtToàn bộ luồng nằm trong ~2.000 dòng dễ auditNhiều magicTố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.

2.2 Cây thư mục

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

---

3. Mô hình dữ liệu

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)

3.1 Bảng lõi (theo yêu cầu)

vietal_projects — dự án

CộtKiểuGhi chú
idINT UNSIGNED PK
codeVARCHAR(40) UNIQUEdùng trong API (project=VIETAL-2026)
name, descriptionVARCHAR(190), TEXT
statusENUM planning/active/paused/completed/archived
start_date, end_dateDATE
budget_plannedDECIMAL(15,2)ngân sách được duyệt
currencyCHAR(3)mặc định VND
progressTINYINTtính lại tự động = AVG(tiến độ công việc ≠ backlog)
owner_idFK users

vietal_tasks — công việc & mốc (Kanban + Timeline)

CộtKiểuGhi chú
id, project_id (FK), parent_id (FK self)cho phép chia việc con
typeENUM task,milestonemilestone hiển thị ở tab Timeline
title, description
statusENUM backlog/todo/doing/review/done/blocked6 cột Kanban
priorityENUM 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
progressTINYINT 0–100kéo sang done ⇒ 100
sort_orderINTthứ 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ộtKiểuGhi chú
actor_typeENUM user/agent/systemphân biệt thao tác người và máy
actor_id, actor_label
actionVARCHAR(60)task.move, finance.create, agent.report…
messageVARCHAR(500)hiển thị ở feed
payloadJSONdữ 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ộtKiểuGhi chú
project_id (FK), task_id (FK), event_id (FK)liên kết ngữ cảnh
kindENUM image/document/minutes/artifact/report/otherbiên bản họp = minutes
title, description
original_name, stored_namestored_name = 2026/04/<random>.<ext>
mime, size_bytes, sha256kiểm tra toàn vẹn
metaJSONnguồn (web/api), agent, IP
captured_atDATETIMEthời điểm chụp/ghi nhận (khác thời điểm upload)
uploaded_by_type, uploaded_by, uploader_label, uploaded_atngười upload

vietal_ai_agents — agent đăng ký

CộtKiểuGhi chú
code UNIQUE, nametro-ly-vietal, deepseek-planner
vendorENUM local/deepseek/claude/openai/customquyết định cách gọi
model, endpointghi đè mặc định trong config
api_key_encVARCHAR(512)AES-256-GCM, khoá ở storage/app.key (0600)
system_promptTEXTvai trò agent
capabilities, status, last_seen_atheartbeat cập nhật last_seen_at

3.2 Bảng bổ trợ

BảngVai trò
vietal_users2 tài khoản quản trị: email UNIQUE, password_hash bcrypt, must_change_pw, failed_attempts, locked_until, last_login_*
vietal_budget_entriessổ thu/chi/cam kết: kind, category, amount, funder, ref_no, entry_date
vietal_eventscuộc họp/tập huấn/báo cáo: starts_at, ends_at, location, participants, notes
vietal_agent_tokenstoken_hash (sha256), scopes, expires_at, revoked_at, last_used_at
vietal_agent_jobsviệc giao cho agent: status queued/running/done/failed, result, token/cost
vietal_chat_threads / vietal_chat_messageshộ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_indicators32 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_lines29 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_requestsyê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_resourcesdanh mục nguồn lực AI (LLM/OCR/ASR/TTS): endpoint, model, scope public/lan, token mã hoá, health gần nhất

3.3 Quy ước dữ liệu

---

3.4 Dữ liệu đề án nạp sẵn (tách từ 4 tệp nguồn)

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ồnNội dung đã táchĐích trong CSDL
Cadre_Logique_VIETAL_VF.xlsxMụ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áovietal_indicators (32), vietal_tasks (13 mốc + 20 đầu việc)
Annexe_B_Budget_VIETAL_VF_CHU_chef_de_file.xlsx6 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.docxCô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 … .docxBả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.

4. Xác thực & kiểm soát truy cập (Authentication & ACL)

4.1 Hai lớp danh tính

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.vnthanhliem.vo@gmail.com
saber.aloui@chu-angers.frsaber.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

4.2 Phiên đăng nhập

Thuộc tínhGiá trịLý do
Tên cookieVIETALSESStá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 / Securebậtchống đọc bằng JS, chống CSRF cross-site, chỉ HTTPS
session.use_strict_mode1khô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 timeout2 giờ
Absolute timeout12 giờ
Fingerprintsha256(User-Agent + uid) so mỗi requestphát hiện cookie bị dùng ở máy khác
CSRFtoken 32 byte/phiên; mọi POST + header X-CSRF-Token cho fetch

4.3 Phân quyền

controller quản trị qua require_login() + kiểm tra role khi mở rộng).

(chống path traversal), trả Content-Disposition: inline cho ảnh/PDF, attachment cho phần còn lại.

4.4 Bảo vệ tầng HTTP

Referrer-Policy, Permissions-Policy, COOP, HSTS khi HTTPS,

CSP default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; frame-ancestors 'none'.

thư mục ngoài webroot, chmod 0640, lưu SHA-256. Không cho .php, .svg, .html.

4.5 Token cho AI Agent

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

---

5. Giao diện quản trị

TrangRouteNộ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/loginform 2 trường, thông báo lỗi chung (không tiết lộ email tồn tại)
Tiến độ/boardKanban 6 cột kéo–thả, lọc nhanh, hộp thoại thêm/sửa, tab Timeline theo tháng
Chỉ số/indicators32 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/finance4 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/evidenceform 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/eventsform thêm, timeline sự kiện sắp tới/đã qua, liên kết biên bản
Agents/agentsdanh 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/chatdanh 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/accountthô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.

5.1 Luồng kéo–thả Kanban

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

5.2 Ngữ cảnh cho chat

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.

---

5.3 Đa ngôn ngữ (Tiếng Việt / Français)

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ớpCơ chếTệp
Nhãn giao diệnDanh mục dịch VI→FR, áp dụng lên HTML ở cuối requestlang/fr.php, lib/i18n.php
Nội dung đề ánCột JSON fr trên vietal_projects / tasks / indicators / events, chọn bằng tf()data/plan_fr.php + bin/install.php
Số & ngàynum() đổi dấu phân cách (vi 1.500.000 ↔ fr 1 500 000), ngày giữ dd/mm/yyyylib/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 agentKhi giao diện FR, system prompt thêm chỉ dẫn “Réponds en français”controllers/ChatController.php
Ngữ cảnh agentTê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.

6. Cổng API cho AI Agents

Tiền tố: https://dv.badt.vn/project/api/v1 · Auth: Authorization: Bearer vtk_…

MethodEndpointScopeMô tảBody chính
GET/pingreadkiểm tra token + danh sách endpoint—
GET/projectsreaddanh sách dự án—
GET/projects/{code}/summaryreadKPI + mốc của một dự án—
GET/tasks?project=CODE&status=doing&type=task&limit=100readdanh sách công việc—
GET/indicators?project=CODEread32 chỉ số + giá trị hiện tại + % đạt đích—
POST/indicators/{code}writeagent ghi giá trị chỉ số{value, note}
POST/tasks/{id}/progresswritecập nhật tiến độ/trạng thái{status, progress, message}
POST/logswriteđẩy nhật ký xử lý{project, action, message, task_id?, payload?}
POST/reportswritenộp báo cáo (lưu thành minh chứng .md){project, title, content, kind?, task_id?}
POST/evidencewritetải minh chứngmultipart 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/messageswriteagent 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=queuedreadnhận việc được giao—
POST/jobswriteagent tự đề xuất việc{title, instruction, project?}
POST/jobs/{id}writebáo trạng thái/kết quả{status, result, tokens_in, tokens_out}
POST/heartbeatreadduy trì trạng thái agent{status, note?}

6.1 Định dạng phản hồi

{ "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).

6.2 Ví dụ tích hợp

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- …"}'

6.3 Ba kiểu agent và cách cấu hình

KiểuvendorCần API keyGọi tới
Local LLM trong cụmlocalkhônghttp://192.168.1.250:8091/v1/chat/completions (vLLM, bắt buộc field model)
DeepSeekdeepseekcóhttps://api.deepseek.com/v1/chat/completions
Claudeclaudecóhttps://api.anthropic.com/v1/messages (x-api-key, anthropic-version)
Agent tự viếtcustomtuỳ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).

---

7. Môi trường làm việc cho AI Agent từ xa

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.

7.1 Cơ chế chính

Cơ chếBảng/cộtÝ nghĩa
Token theo agentvietal_agent_tokensmỗi agent một (hoặc nhiều) token vtk_…, scope read/write, có hạn/thu hồi
Lease giữ việcvietal_tasks.claimed_by_agent / claim_token / claim_expires_atchố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 đápvietal_requestsngườ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ựcvietal_resourcesagent 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 độngGET /api/v1/workspacemộ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_logsmọi thao tác của agent có actor_type=agent, actor_label, ip

7.2 Vòng làm việc

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

7.3 Nguồn lực công khai vs nội bộ

NhómVí dụAi gọi được
scope=publicpnt.badt.vn/gemma4, /medgemma, /deepseek_ocr, /medical_transcribe, /text2speechagent ngoài Internet (HTTPS)
scope=lan192.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).

7.5 Tài liệu trong website và bóc nội dung cho agent

Hạng mụcĐường dẫnGhi 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ậtdocs/README.md, AGENT_WORKSPACE.md, AGENT_CLAUDE.md, openapi.yaml, TOM_TAT_DE_AN.md, THIET_KE_HE_THONG.mdphục vụ trực tiếp từ repo (ngoài webroot), whitelist slug
API tài liệuGET /api/v1/docs, GET /api/v1/docs/{slug}cho agent có token
Bóc nội dung minh chứngGET /api/v1/documents/{id} (cache trong vietal_evidence.text_extract)PDF → pdftotext; scan → OCR; DOCX/XLSX/PPTX → đọc XML; ảnh → OCR
Bóc lạiPOST /api/v1/documents/{id}/extractkhi cache rỗng/sai
Tìm tài liệuGET /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.

7.6 Tổng số endpoint

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.

7b. Tiếp nhận văn bản thô → cập nhật dự án (trang /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ựEndpointGhi chú
1http://192.168.1.250:8094/v1 · qwen3-14bmáy 250, phân tích chính
2http://192.168.1.250:8091/v1 · qwen2.5-7bdự phòng khi 14B bận/chết
3http://192.168.1.250:8092/v1 · google/gemma-4-e2b-itdự 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ừ.

7b-bis. Quy trình hai bước: xem trước → duyệt → hoàn tác

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ốngCách chặn
Dán trùng văn bảnraw_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ùngso khớp mã + ngày + số tiền + nội dung trước khi ghi
Ghi 2 lần do cron + webgiữ 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ịamỗ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ạistorage/intake/{id}.json giữ nguyên phản hồi của mô hình (0600)

7c. Cây công việc nhiều tầng (mỗi việc chẻ thành nhiều thế hệ việc con)

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ómCột
Định danhcode, parent_id, path, depth, type (task/milestone), work_type (task/meeting/document/training/travel/procurement/clinical/finance/other)
Nội dungtitle, description, deliverables (sản phẩm/đầu ra), tags, location (địa điểm)
Thời gianstart_date, due_date, completed_at, progress
Tài chínhest_cost, currency; các khoản thực tế nằm ở vietal_budget_entries.task_id
Minh chứngvietal_evidence.task_id (ảnh, biên bản, sản phẩm — tải qua /tasks/{id}/evidence)
Thực thiassignee_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:

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).

7d. Trang «Kết nối Claude» (/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.

POST /intake/{id}/apply, POST /intake/{id}/revert.

8. Bảo mật — danh sách kiểm soát

#Kiểm soátCách làm trong mã
1Mã nguồn ngoài webrootpublic_html/project/index.php chỉ require file ngoài
2Chỉ 2 danh tínhwhitelist config + vietal_users + tự vô hiệu user lạ
3Mật khẩu mạnhbcrypt cost 12, tối thiểu 10 ký tự, ép đổi lần đầu (must_change_pw)
4Chống dò mật khẩuvietal_login_attempts theo email và IP, khoá 15 phút sau 5 lần
5Chống chiếm phiênregenerate id, fingerprint UA, idle/absolute timeout, cookie Strict
6CSRFtoken/phiên, kiểm tra mọi POST (form + fetch header)
7XSSmọi output qua e() (htmlspecialchars ENT_QUOTES), CSP không cho script ngoài
8SQL injection100% prepared statement, không nối chuỗi từ input
9Path traversalrealpath + kiểm tra tiền tố thư mục upload khi trả tệp
10Upload độc hạiwhitelist ext + MIME, đổi tên ngẫu nhiên, ngoài webroot, chmod 640
11Lộ tokenchỉ lưu sha256, hiện một lần, có hạn/thu hồi/rate limit
12Lộ API key agentmã hoá AES-256-GCM, khoá tách riêng 0600
13Dấu vết kiểm toánvietal_logs append-only cho mọi thao tác ghi
14Thông báo lỗiproduction ẩn chi tiết, ghi storage/logs/*.log
15Header bảo mậtCSP, HSTS, nosniff, frame-ancestors, referrer

---

9. Triển khai & vận hành

8.1 Cài đặt (một lần)

# 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ẫnQuyền
vietal_project/ (mã)liem:www-data, thư mục 750, tệp 640
vietal_project/config/config.php640 (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_vietalwww-data, 700

8.2 Vận hành thường ngày

# Đổ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á.

8.3 Sao lưu

# 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ó).

8.4 Nhật ký & chẩn đoán

Nơi xemNội dung
storage/logs/app-YYYY-MM.logexception, lỗi hệ thống
storage/logs/llm-YYYY-MM.loglỗ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.loglỗi PHP-FPM/Apache

---

10. Kiểm thử

#Kịch bảnKỳ vọng
1GET /project/login200, form hiển thị, có cookie VIETALSESS
2POST login sai email ngoài whitelistquay lại form, không tạo phiên, vietal_login_attempts +1
3POST login đúng302 → /project/, dashboard có dữ liệu
4GET /project/ không cookie302 → /login
5POST form thiếu CSRF419
66 lần sai liên tiếplần 6 bị khoá 15 phút
7Kéo thẻ Kanban sang cột kháccột đếm đổi, CSDL status đổi, log task.move
8Ghi giao dịch 100.000.000số dư giảm, cơ cấu hạng mục cập nhật
9Upload ảnh 2 MBlưu ngoài webroot, hiện thumbnail, có SHA-256
10Upload .phpbị từ chối 422/thông báo
11Tải /evidence/1/file khi chưa đăng nhập302 → login
12GET /api/v1/ping không token401 missing_token
13GET /api/v1/ping token sai401 invalid_token
14POST /api/v1/logs token đúng200, log actor_type=agent
15121 request/phútrequest 121 → 429
16Chat gửi câu hỏicó trả lời từ qwen2.5-7b:8091, lưu 2 tin nhắn
17Agent đẩy tin qua POST /api/v1/chat/messagestin hiện trong UI sau ≤7 giây
18Đổi mật khẩu rồi đăng nhập lạimật khẩu cũ bị từ chối
19Đăng nhập bằng alias thanhliem.vo@gmail.comvào đúng tài khoản liemvt@pnt.edu.vn
20/indicators32 chỉ số, 13 mốc, thanh tiến độ theo đích M20
21Cập nhật chỉ số 6.1.2 = 2lưu giá trị, ghi log indicator.update
22GET /api/v1/indicators?project=VIETAL-2026200, 32 phần tử, có percent_of_target
23POST /api/v1/indicators/1.1.1 value=1200, chỉ số đạt đích, log actor=agent

---

11. Lộ trình mở rộng

Giai đoạnNội dungGhi chú kỹ thuật
2Xuất báo cáo PDF/Excel tháng, in Kanbandù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ềmbảng vietal_evidence_files
3Việc lặp lại, thông báo hạn chót qua email/Zalocron bin/remind.php + SMTP nội bộ
3WebSocket/SSE thay poll 7 giâyendpoint /chat/stream
3Agent tự chạy job nền (worker Python trên 250)đọc GET /jobs?status=queued, POST /jobs/{id}
4SSO 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
4Ký số minh chứng, chống sửa tệpđã có SHA-256; thêm chữ ký + niêm phong định kỳ

---

12. Phụ lục — bản đồ yêu cầu → thành phần

Yêu cầu ban đầuThành phần đáp ứng
Chỉ 2 tài khoản quản trị, mật khẩu bcryptvietal_users + config.security.allowed_emails + attempt_login()
Chặn request trái phép, kiểm tra session chặtrequire_login(), fingerprint, timeout, CSRF, 401/419/403
Kanban/timeline mốc công việcvietal_tasks (type=milestone), /board (2 tab)
Tài chính, dòng tiền, nguồn lựcvietal_budget_entries, /finance, budget_summary()
Sản phẩm, biên bản, lịch sử sự kiệnvietal_evidence (kind=artifact/minutes) + vietal_events
Upload minh chứng kèm metadata thời gian/người uploadvietal_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