# HDSD — CALIB CSDL B: huấn luyện AGY & hiệu chỉnh thông số màu

**Dùng để:** chủ nhân đưa một **hỗn hợp màu** (các màu đã có trong CSDL B + tỉ lệ rõ ràng) → agent **dự đoán màu hỗn hợp** → chủ nhân tải **ảnh màu hỗn hợp thực tế** → agent **đối chiếu (ΔE)** và **đề xuất hiệu chỉnh hệ số cường độ** của từng màu ⇒ lần sau công thức pha màu chính xác hơn.

**Địa chỉ:** máy này `http://127.0.0.1:8099` · từ máy khác `https://desktop-9gsdkd2.tail0ffe94.ts.net/calib/` *(nên mở bằng dấu `/` cuối; liên kết trong app nay tự đúng ở mọi trang)*
**Mật khẩu vào app:** trong `mat_khau.txt` · **mật khẩu xác nhận ghi hiệu chỉnh: 19842026** (`pass_hieu_chinh.txt`) · **Khởi động:** bấm đúp `Chay_Calib.bat`
**Thư mục:** `C:\Claw 2\Nghien cuu\Du-an-B-He-mau-Stain-Glaze\calib-app`

---

## 1. Luồng làm việc (2 bước của AGY)

| Bước | Ai làm | Nội dung |
|---|---|---|
| **P — Dự đoán** | Chủ nhân nhập → AGY | Chọn màu + tỉ lệ % → agent đọc thông số các màu trong CSDL B rồi **dự đoán hỗn hợp**: hex, L\*a\*b\*, **phương pháp** (trung bình có trọng số / Kubelka-Munk), **độ tin cậy**, **ΔE dự kiến**, và các nguyên nhân có thể gây lệch |
| **C — Đối chiếu & hiệu chỉnh** | Chủ nhân tải ảnh → AGY | Agent **tự nhìn ảnh thực tế**, đọc màu thật (hex, L\*a\*b\*, độ tin cậy, mô tả bề mặt), tính **ΔE** so với dự đoán, giải thích lệch do đâu, rồi **đề xuất hệ số cường độ mới + màu sau hiệu chỉnh cho từng màu**. Hệ thống **chỉ ghi ĐỀ XUẤT** (trạng thái *cho_xac_nhan*); muốn ghi vào CSDL B phải **nhập mật khẩu 19842026** ở trang chi tiết |

## 2. Quy ước bắt buộc (chủ nhân chốt 08/10/2026)

- **Chỉ nhập `%` màu pha TRONG BASE** cho từng màu — **không cần cộng = 100%** (ví dụ *Black 27 = 4* nghĩa là 4% màu đó trong base).
- **Điều kiện chuẩn (cố định, không đổi giữa các lần):** kéo màu bằng **CÙNG thước kéo** với màu mẫu · pha trong **CÙNG loại base** với mẫu · trên **GIẤY TRẮNG cùng loại**. Nhờ vậy hệ số hiệu chỉnh mới so sánh được giữa các lần.
- **Trước khi GHI hiệu chỉnh vào CSDL B phải nhập mật khẩu xác nhận: `19842026`** (đổi trong `pass_hieu_chinh.txt`). Nhập sai ⇒ CSDL B **không đổi**; AGY chỉ dừng ở mức **đề xuất**.

## 3. Cách nhập một hỗn hợp

1. Vào Web UI → **Người nhập** (VD: *Lab – Hùng*) · **Ghi chú** (thước kéo nào, base gì, giấy gì — nếu khác điều kiện chuẩn thì ghi rõ).
2. **Thành phần**: mỗi dòng chọn **một màu trong CSDL B** + ghi **% màu pha trong base**; bấm **+ Thêm màu** nếu cần. Không thêm cùng một màu 2 lần (nên gộp).
3. Bấm **Gửi cho AGY dự đoán** → mở **trang chi tiết** (dự đoán hiện sau ~1–2 phút; trang tự cập nhật mỗi 10 giây, có dòng *Agent đang xử lý…*).
4. Ở trang chi tiết, mục **Ảnh màu hỗn hợp THỰC TẾ**: tải ảnh lên → agent tự chạy bước đối chiếu (~1–2 phút) → xem **ΔE** + **bảng ĐỀ XUẤT HIỆU CHỈNH** → nhập mật khẩu `19842026` → **Xác nhận & ghi vào CSDL B**.

**Ảnh nên chụp thế nào:** vuông góc, đủ sáng (không đèn vàng), **có ô giấy trắng/đen trong cùng khung** làm mốc, tránh lóe sáng và bóng đổ; nếu màng màu có nhiều vệt thì chụp đủ để thấy vệt đại diện.

## 4. Hệ số cường độ (`he_so_cuong_do`) — cách hiểu

Mỗi màu trong CSDL B có một hệ số, mặc định **1.0**:
- **> 1** = màu này **mạnh hơn** giả định (màu lên đậm/rực hơn tính toán) ⇒ khi lập công thức nên **giảm tỉ lệ dùng**.
- **< 1** = màu **yếu hơn** giả định ⇒ nên **tăng tỉ lệ dùng**.
- Hệ số được ghi **có lịch sử** (bảng `hieu_chinh_mau`): ngày · màu · giá trị cũ → mới · ΔE của hỗn hợp · lý do · hỗn hợp số mấy. **Không ghi đè mất dấu vết.**

Trang **Lịch sử hiệu chỉnh** (`/hieu-chinh`) xem: hệ số hiện tại của từng màu + số lần hiệu chỉnh + toàn bộ lịch sử.

## 5. Nguyên tắc & giới hạn (đọc để dùng đúng)

- Kết quả AGY là **số đọc từ ảnh**, không phải số máy đo quang phổ ⇒ dùng để **hiệu chỉnh tương đối theo thời gian**, không dùng làm chứng nhận màu cho khách.
- **ΔE**: agent nêu rõ công thức (CIE76 / CIEDE2000). ΔE < 2 ⇒ agent sẽ nói **không cần hiệu chỉnh**.
- Mỗi hỗn hợp **chỉ nên đổi 1–2 màu một lần** để biết chính xác màu nào gây lệch; hiệu chỉnh dồn nhiều màu cùng lúc sẽ khó quy trách nhiệm.
- **Càng nhiều hỗn hợp được đối chiếu, hệ số càng sát.** Nên làm đều: hỗn hợp 2 màu (dễ hiểu) trước, rồi 3–4 màu.
- Dữ liệu gốc (ảnh, dự đoán, đối chiếu) lưu ở `viec\H####_ddmm\`: `DU_DOAN.md`, `DOI_CHIEU.md`, `anh\`, `_log_du_doan.txt`, `_log_doi_chieu.txt`.
- Lỗi xảy ra: xem cột `loi` trong DB hoặc log trong thư mục việc; nếu agent không tạo được tệp thì thử lại (bấm lại hoặc gửi lại hỗn hợp).

## 6. Bảng dữ liệu liên quan (trong CSDL B)

| Bảng | Nội dung |
|---|---|
| `mau` | 8 màu hệ METAL COMPLEX + cột hiệu chỉnh: `he_so_cuong_do`, `so_lan_hieu_chinh`, `ngay_hieu_chinh`, `lab_hieu_chinh` |
| `mau_bang_in` | 27 tấm mẫu đã đo (hex, L\*a\*b\*) dùng làm dữ liệu gốc cho việc dự đoán |
| `hon_hop` | mỗi lần thử: thành phần + **`dieu_kien`** (điều kiện chuẩn) + dự đoán + ảnh thực tế + màu thực + ΔE + kết luận |
| `hieu_chinh_mau` | lịch sử đề xuất/hiệu chỉnh từng màu (không ghi đè): `gia_tri_cu`→`gia_tri_moi`, `lab_moi`, `ly_do`, `delta_E_truoc`, **`da_ap_dung`** (0 = mới đề xuất, 1 = đã ghi vào CSDL B), `nguon_anh` |
| `nhat_ky` | nhật ký mọi lần nạp/sửa CSDL B |

## 7. 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 **dự đoán** | `[CALIB] Đã có DỰ ĐOÁN màu — hỗn hợp #N (<các màu + %>)` | hex/L\*a\*b\* dự đoán, phương pháp, độ tin cậy, sai số ΔE dự kiến + **nhắc chụp ảnh thực tế** | `DU_DOAN.md` |
| Xong **đối chiếu** | `[CALIB] Đã ĐỐI CHIẾU xong — hỗn hợp #N (ΔE … · đề xuất hiệu chỉnh m màu)` | dự đoán vs thực tế, ΔE, **bảng đề xuất hệ số từng màu** (chưa ghi), kết luận + link nhập mật khẩu | `DOI_CHIEU.md` |
| **Đã ghi CSDL B** | `[CALIB] ĐÃ GHI hệ số vào CSDL B — hỗn hợp #N (m màu)` | các màu đã cập nhật hệ số cũ→mới, thời điểm, nhắc điều kiện chuẩn | `DOI_CHIEU.md` |

- Email nhận: ô **“Email nhận thông báo”** khi tạo hỗn hợp; để trống thì dùng `calib-app\email_bao.txt`.
- Trang chi tiết có khối **“Thông báo cho người dùng qua email”** (tình trạng từng mốc: `✔ đã gửi tới … (id …)`) + nút **“Gửi lại thông báo qua email”**.
- Log từng lần gửi: `viec\H####_ddmm\_log_mail_p|c|ghi.txt`; nhật ký ở bảng `nhat_ky`.

## 8. Khi cần dừng / bật lại

- Tắt: đóng 2 cửa sổ *Calib server* và *Calib worker* (hoặc kết thúc tiến trình `server_calib.py` / `worker_calib.py`).
- Bật lại: chạy `Chay_Calib.bat` (tự tắt bản cũ trùng cổng 8099 rồi mở lại).
- Chỉ tắt phần công khai (giữ nội bộ): `tailscale funnel --set-path=/calib off`.