# HDSD — HLQT: Huấn luyện QUY TRÌNH cho CSDL A

> App web để **đào tạo & cập nhật CSDL A** (quy trình sơn gỗ nội thất). Cùng họ với CALIB (CSDL B) và Agent-Lab (đề nghị 2 phương án).
> Cập nhật: 09/10/2026.

## 1. Địa chỉ & mật khẩu

| | |
|---|---|
| Trong máy | `http://127.0.0.1:8100` |
| Qua Tailscale | `https://desktop-9gsdkd2.tail0ffe94.ts.net/hlqt/` — **nhớ dấu `/` cuối** |
| Mật khẩu dùng app | trong `HLQT-app\mat_khau.txt` (đổi được — sửa file rồi vào lại) |
| Mật khẩu xác nhận GHI CSDL A | trong `HLQT-app\pass_hlqt.txt` (mặc định **19842026**) |
| Khởi động | chạy `Chay_HLQT.bat` (mở 2 cửa sổ: `HLQT-server` + `HLQT-worker`; đóng 2 cửa sổ là tắt app) |

Funnel Tailscale là **công khai internet** ⇒ bắt buộc có mật khẩu (đã bật). Phiên đăng nhập 12 giờ.

## 2. Luồng làm việc (4 bước)

1. **Nạp một bản màu** (trang chính): chọn ảnh bản màu (bắt buộc) + ảnh phụ (tuỳ chọn) + mã màu, hệ sơn, loại nền/gỗ, yêu cầu chất lượng, ghi chú. Bấm *Gửi*.
2. **Agent đề nghị ĐÚNG 1 quy trình**: app gửi ảnh + gói kiến thức CSDL A (34 bước chuẩn · 118 quy trình · 29 luật) cho AGY (`gemini-3.1-pro-high`). AGY đọc bản màu, chọn **một** quy trình khả dĩ & sát nhất (nêu id + tên + lý do), trả về chuỗi bước theo bộ 34 bước chuẩn, điểm khớp và các điểm cần xác nhận. Trang ca tự cập nhật mỗi 10 giây.
3. **Anh nhập QUY TRÌNH THỰC TẾ** của bản màu đó (dán nguyên văn: các bước, loại sơn/bóng, tỉ lệ, dung môi, thời gian khô, cách thi công, số lần lót/bóng…). Càng chi tiết càng rút ra được nhiều. Bấm *Gửi cho agent phân tích*.
4. **Agent đối chiếu & đề xuất bổ sung**: bảng khác biệt (giống / thêm bước / thiếu bước / khác thứ tự / khác chi tiết), đọc lại ảnh để xác nhận, rút **luật mới**, đề xuất **1 quy trình mới** (kèm các bước map vào bộ 34 bước chuẩn) và **danh sách luật mới**, cảnh báo xung đột với luật cũ.
   → Nhập **mật khẩu xác nhận** rồi bấm *Xác nhận & ghi vào CSDL A*.

Chưa nhập mật khẩu thì CSDL A **giữ nguyên** — agent chỉ đề xuất. SAI mật khẩu ⇒ không đổi gì (trang hiện băng cảnh báo *“Sai mật khẩu xác nhận — CSDL A CHƯA thay đổi”*).

### Báo cho người dùng (email) — tự động ở 3 mốc
Hệ thống **tự gửi email** cho người dùng ngay khi agent xử lý xong, không cần ngồi canh trang:

| Mốc | Tiêu đề | Nội dung chính | Đính kèm |
|---|---|---|---|
| Xong **đề nghị** | `[HLQT] Đã có QUY TRÌNH ĐỀ NGHỊ — ca #N · <mã màu>` | quy trình được chọn (id + tên), độ khớp, chuỗi bước, điểm cần xác nhận, link ca | `DE_NGHI.md` |
| Xong **phân tích & đối chiếu** | `[HLQT] Đã PHÂN TÍCH & ĐỐI CHIẾU xong — ca #N … (n khác biệt, m luật mới)` | bảng khác biệt, luật mới, xung đột luật cũ, link để nhập mật khẩu ghi | `PHAN_TICH.md` |
| **Đã ghi CSDL A** | `[HLQT] ĐÃ GHI VÀO CSDL A — ca #N … (quy trình id …, m luật mới)` | id quy trình mới, số bước, số luật, thời điểm ghi | `PHAN_TICH.md` |

- Email nhận: ô **“Email nhận thông báo”** khi tạo ca; để trống thì dùng `HLQT-app\email_bao.txt`.
- Trên trang ca có khối **“Thông báo cho người dùng qua email”** hiện tình trạng từng mốc (`✔ đã gửi tới … (id …)` hoặc lỗi) và nút **“Gửi lại thông báo qua email”** (gửi lại theo mốc xa nhất đã có).
- Log từng lần gửi: `viec\C####_ddmm\_log_mail_p|c|ghi.txt`; nhật ký ở `nhat_ky_hlqt`.

## 3. Ghi vào CSDL A gồm những gì

Sau khi xác nhận đúng mật khẩu, hệ thống (backup CSDL A trước):

1. Thêm **1 dòng `quy_trinh`**: `loai = 'thực tế (HLQT)'`, nguồn ghi rõ *“HLQT ca #N — ảnh bản màu + quy trình thực tế do chủ nhân nhập”*, ngày, hệ sơn, mã màu, loại nền, yêu cầu.
2. Thêm các dòng **`buoc_quy_trinh`** (thứ tự · nội dung · số bước chuẩn 1–34 · ghi chú).
3. Thêm các dòng **`huan_luyen`** (luật mới: nhóm · quy tắc · phạm vi · nguyên văn), `trang_thai = 'ĐANG ÁP DỤNG'`, nguồn = *HLQT ca #N*.
4. Ghi **nhật ký** `nhat_ky_hlqt` + đánh dấu ca đã bổ sung (`da_bo_sung = 1`, `qt_moi_id`, `so_luat_them`).
5. **Dựng lại gói kiến thức** cho HLQT và cho Agent-Lab ⇒ lần đề nghị sau đã có quy trình/luật mới.

**Ẩn danh:** mọi văn bản ghi vào CSDL A được lọc bỏ tên khách hàng đã biết (thay bằng `「khách hàng」`); prompt cũng cấm AGY ghi tên khách/kỹ thuật viên.

## 4. Các trang

- `/` — nạp bản màu mới + 8 ca gần đây.
- `/ca?id=N` — chi tiết ca: ảnh · đề nghị · ô nhập quy trình thực tế · phân tích & đề xuất · ô mật khẩu xác nhận · trạng thái agent (đang xử lý / rảnh).
- `/danh-sach` — toàn bộ ca và trạng thái.
- `/luat` — **toàn bộ luật huấn luyện trong CSDL A** (29 luật cũ + luật mới do HLQT thêm) — xem nhanh CSDL A đã học được gì.

## 5. Trạng thái ca

`chờ đề nghị` → `đã có đề nghị` → `chờ phân tích` → **`CHỜ XÁC NHẬN`** → `đã bổ sung CSDL A` (hoặc `LỖI`).

## 6. Sự cố thường gặp

| Hiện tượng | Xử lý |
|---|---|
| Trang ca không tự cập nhật | Bấm F5; kiểm cửa sổ `HLQT-worker` còn chạy không. |
| Ca báo `LỖI` | Xem `HLQT-app\viec\C####_ddmm\_log_agy_de_nghi.txt` (hoặc `_log_agy_phan_tich.txt`), rồi đổi trạng thái ca về `cho_de_nghi`/`cho_phan_tich` để chạy lại. |
| AGY chạy lâu (>5 phút) | Bình thường với gói kiến thức lớn (đề nghị ~1–3 phút, phân tích ~2–5 phút). |
| Muốn xem agent đang làm gì | Khối nhỏ trên trang ca: *“Agent đang xử lý: ca #N · bước P/C · từ HH:MM”*. |
| Sửa mật khẩu app | Sửa `HLQT-app\mat_khau.txt`. |
| Đổi mật khẩu xác nhận ghi | Sửa `HLQT-app\pass_hlqt.txt`. |

## 7. Tệp & thư mục

```
Du-an-A-Quy-trinh-son\HLQT-app\
├─ server_hlqt.py        web app (cổng 8100)
├─ worker_hlqt.py        worker: bước P, bước C, hàm ghi_vao_csdla()
├─ goi_kien_thuc_hlqt.py dựng kien_thuc\CSDLA_GOI_CHO_AGY.md cho AGY
├─ kien_thuc\            gói kiến thức (tự dựng lại sau mỗi lần ghi)
├─ viec\C####_ddmm\      mỗi ca: ảnh, YEU_CAU_*.txt, DE_NGHI.md, QUY_TRINH_THUC_TE.txt, PHAN_TICH.md, _log_agy_*.txt
├─ _tools\gui_ca.py      gửi ca / nộp quy trình thực tế / xác nhận ghi từ dòng lệnh (để kiểm thử)
├─ mat_khau.txt · pass_hlqt.txt · bi_mat.txt
└─ _nhip.json            nhịp worker (app đọc để hiện “đang xử lý…”)
CSDLA.db (bảng riêng của app: huan_luyen_ca, nhat_ky_hlqt) · _backup\CSDLA_bak_*_truoc_*.db
```

Ghi từ dòng lệnh (khi cần):
```
python _tools\gui_ca.py tao --anh "…\anh_05.jpg" --ma-mau "PT-002 H" --he-son "nước" --nen "trám bắn cát"
python _tools\gui_ca.py thuc-te --ca 2 --file "…\quy_trinh_thuc_te.txt"
python _tools\gui_ca.py ghi --ca 2
```