From 1794640f9d59e14de2bc9b3b89dcfc42e398d5aa Mon Sep 17 00:00:00 2001
From: kiyo9w <ngokapikapi@gmail.com>
Date: Mon, 28 Sep 2026 12:38:27 +0900
Subject: [PATCH] docs: describe live protocol and evaluation limits

---
 recognization/README.md   | 19 +++++++++----------
 recognization/docs/API.md | 11 ++++-------
 2 files changed, 13 insertions(+), 17 deletions(-)

diff --git a/recognization/README.md b/recognization/README.md
index 6dbf1ab..dff70a2 100644
--- a/recognization/README.md
+++ b/recognization/README.md
@@ -101,19 +101,17 @@ Bất kỳ client nào gửi được ảnh JPEG đều dùng được: điện
 
 ## 🛠️ Kiểm tra hệ thống (Tests)
 
+From `recognization/`, after `pip install -r requirements.lock` (or `pip install -r requirements-dev.txt`):
+
 ```bash
-cd code
-YOLO_OFFLINE=1 ../.venv/bin/python -m unittest test_observe test_engine test_tracking test_live test_api -v
-
-# Test với model thật (tải trọng số, chạy ~15s)
-DORAYAKI_REAL_MODEL=1 YOLO_OFFLINE=1 ../.venv/bin/python -m unittest test_real_model -v
-
-cd ..
-YOLO_OFFLINE=1 .venv/bin/python code/test_suite.py        # bộ test gốc
-.venv/bin/python code/bench_engine.py                     # đo tốc độ detect/classify
+YOLO_OFFLINE=1 YOLO_AUTOINSTALL=false python -m unittest discover -s code -p 'test_*.py' -v
 ```
 
-Lưu ý: chạy test bằng danh sách module cụ thể, **không dùng** `unittest discover` vì sẽ import `test.py`/`fast_test.py` (script scratch với đường dẫn máy khác và cửa sổ OpenCV chặn).
+That discovers every `code/test_*.py` module. `test_real_model` is included and skipped unless `DORAYAKI_REAL_MODEL=1` (it loads the YOLO weights). CI runs the same command from `.github/workflows/test.yml`.
+
+```bash
+YOLO_OFFLINE=1 python code/bench_engine.py   # speed measurement, not part of the suite
+```
 
 ---
 
@@ -145,6 +143,7 @@ code/
   empty_shelf_detector.py, inventory.py, pipeline.py, observe.py
   stream_client.py   # client mẫu (camera / video / pan ảnh tĩnh)
   bench_engine.py    # đo tốc độ
+  test_*.py          # unittest modules (discover -s code -p 'test_*.py')
   web/               # web client (index.html, styles.css, app.js)
 docs/API.md          # tài liệu API đầy đủ
 docs/design-price-tags-and-compliance.md   # thiết kế OCR giá, đối chiếu, compliance, mobile
diff --git a/recognization/docs/API.md b/recognization/docs/API.md
index d25fd88..989c2c0 100644
--- a/recognization/docs/API.md
+++ b/recognization/docs/API.md
@@ -377,12 +377,9 @@ The protocol is capture-source agnostic; an iPad/phone client needs no server ch
 ## Tests
 
 ```bash
-cd recognization/code
-YOLO_OFFLINE=1 ../.venv/bin/python -m unittest test_observe test_engine test_tracking test_live test_api -v
-DORAYAKI_REAL_MODEL=1 YOLO_OFFLINE=1 ../.venv/bin/python -m unittest test_real_model -v
-cd .. && YOLO_OFFLINE=1 .venv/bin/python code/test_suite.py     # the original CLI suite
+cd recognization
+YOLO_OFFLINE=1 YOLO_AUTOINSTALL=false python -m unittest discover -s code -p 'test_*.py' -v
 ```
 
-Run tests with an explicit module list: `unittest discover` would import
-`test.py`/`fast_test.py`, which are scratch scripts with hardcoded paths from another
-machine and a blocking OpenCV window.
+`test_real_model` is discovered and skipped unless `DORAYAKI_REAL_MODEL=1`.
+CI installs `requirements.lock` and runs the same command.