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

- Không thay thế hệ thống kế toán; sổ tài chính ở đây là **sổ theo dõi dự án**, không hạch toán.
- Không có cổng đăng nhập cho người ngoài (đúng yêu cầu "chỉ 2 tài khoản").
- Chưa có ký số, chưa có workflow phê duyệt nhiều cấp (đề xuất ở mục 10).

---

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

### 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ộ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` |

### 3.2 Bảng bổ trợ

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

### 3.3 Quy ước dữ liệu

- Thời gian lưu `DATETIME` theo `+07:00` (PDO `SET time_zone`), hiển thị `d/m/Y H:i`.
- Tiền tệ `DECIMAL(15,2)` + `currency`; hiển thị rút gọn (`tr`, `tỷ`).
- Mọi khoá ngoại `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.

---

### 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ồ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.

## 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.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
```

- Lớp 1 (danh sách trắng trong file cấu hình) chặn cả trường hợp ai đó `INSERT` thêm user vào DB.
- Lớp 2 (bảng `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 (...)`.

### 4.2 Phiên đăng nhập

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

### 4.3 Phân quyền

- `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).
- Trang tải tệp `/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.

### 4.4 Bảo vệ tầng HTTP

- Security header tự động: `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">`.
- Apache vhost `dv.badt.vn` vẫn bật ModSecurity/CRS như các app khác.
- Upload: whitelist phần mở rộng **và** MIME thật (finfo), giới hạn 25 MB, tên tệp sinh ngẫu nhiên,
  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
```

- Token gốc **không lưu** trong CSDL; chỉ hiển thị một lần khi cấp (UI hoặc `bin/token.php`).
- So khớp bằng `hash_equals` (tra cứu theo hash, không so chuỗi thô).
- Thu hồi: `UPDATE vietal_agent_tokens SET revoked_at=NOW()`; hết hạn theo `expires_at`.
- Rate limit đếm bằng file + `flock` trong `storage/ratelimit/` (không cần Redis).

---

## 5. Giao diện quản trị

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

### 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ớ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.

## 6. Cổng API cho AI Agents

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?}` |

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

```json
{ "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

```bash
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ể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).

---

## 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`](AGENT_WORKSPACE.md) · đặc tả máy đọc [`docs/openapi.yaml`](openapi.yaml) ·
worker mẫu [`tools/vietal_agent.py`](../tools/vietal_agent.py).

### 7.1 Cơ chế chính

| 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` |

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

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

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

### 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ự | 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ừ.

### 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ố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) |

## 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ó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ếp
- `GET /api/v1/tasks/{id}` — thuộc tính + tổ tiên + việc con + tài chính + minh chứng
- `POST /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).

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

- Controller: `controllers/ClaudeController.php` (`GET /claude`, `POST /claude/token`), view `views/claude.php`.
- MCP server: `tools/vietal_mcp.py` v2.0 (28 công cụ) phục vụ tải tại `/docs/tool/vietal_mcp.py`.
- API bổ sung cho agent: `POST /tasks/{id}/cost`, `POST /events`, `POST /requests/{id}/answer`,
  `POST /intake/{id}/apply`, `POST /intake/{id}/revert`.
- Tài liệu chi tiết: `docs/AGENT_CLAUDE.md` (sổ tay 17 mục).
- Trang FR: mọi đoạn văn/mô tả công cụ dịch động qua `dtr()` (cache `storage/tr`), nhãn tĩnh ở `lang/fr.php`.

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

| # | 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 |

---

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

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

```bash
# 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 |

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

```bash
# Đổ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):

```cron
*/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

```bash
# 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 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 |

---

## 10. Kiểm thử

| # | 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 |

---

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

| 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ỳ |

---

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

| 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` |
