Update consumable pipeline, client API docs, and deployment config

- Refine effective candidate consumables and classifier labels
- Adjust vision algorithm, TSV logging, and video session wiring
- Refresh client surgery HTTP contract doc and staging/video docs
- Update settings, docker-compose prod, tests, and uv.lock

Made-with: Cursor

tests/test_effective_candidate_consumables.py

@@ -1,4 +1,4 @@
-"""effective_candidate_consumables：空请求时回退到目录或模型类名。"""
+"""effective_candidate_consumables / build_name_mapping：YAML 与分类模型，无 Excel。"""
 
 from __future__ import annotations
 
@@ -6,7 +6,6 @@ from pathlib import Path
 from unittest.mock import MagicMock
 
 import pytest
-from openpyxl import Workbook
 
 from app.config import Settings
 from app.services.consumable_vision_algorithm import ConsumableVisionAlgorithmService
@@ -18,34 +17,64 @@ def test_effective_preserves_non_empty_request() -> None:
     assert got == ["纱布", "缝线"]
 
 
-def test_effective_empty_uses_model_class_names(monkeypatch: pytest.MonkeyPatch) -> None:
-    svc = ConsumableVisionAlgorithmService(Settings())
+def test_effective_empty_uses_model_when_yaml_has_no_names(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    yml = tmp_path / "empty.yaml"
+    yml.write_text("names: {}\nlabel_id: {}\n", encoding="utf-8")
+    s = Settings(consumable_classifier_labels_yaml_path=str(yml))
+    svc = ConsumableVisionAlgorithmService(s)
     mock_cls = MagicMock()
     mock_cls.names = {0: "ban", 1: "apple"}
     monkeypatch.setattr(svc, "_get_cls", lambda: mock_cls)
     assert svc.effective_candidate_consumables([]) == ["apple", "ban"]
 
 
-def test_effective_empty_prefers_catalog_xlsx(tmp_path: Path) -> None:
-    xlsx = tmp_path / "cat.xlsx"
-    wb = Workbook()
-    ws = wb.active
-    ws.append(["产品编码", "商品名称"])
-    ws.append(["C1", "商品乙"])
-    ws.append(["C2", "商品甲"])
-    wb.save(xlsx)
-
-    settings = Settings(consumable_catalog_xlsx_path=str(xlsx))
-    svc = ConsumableVisionAlgorithmService(settings)
-    got = svc.effective_candidate_consumables([])
-    assert got == ["商品乙", "商品甲"]
+def test_effective_empty_prefers_yaml_class_names(tmp_path: Path) -> None:
+    yml = tmp_path / "lab.yaml"
+    yml.write_text(
+        "names:\n  0: 商品甲\n  1: 商品乙\nlabel_id:\n  0: a\n  1: b\n",
+        encoding="utf-8",
+    )
+    s = Settings(consumable_classifier_labels_yaml_path=str(yml))
+    svc = ConsumableVisionAlgorithmService(s)
+    assert svc.effective_candidate_consumables([]) == ["商品甲", "商品乙"]
 
 
 def test_effective_whitespace_only_treated_as_empty(
-    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    svc = ConsumableVisionAlgorithmService(Settings())
+    yml = tmp_path / "empty.yaml"
+    yml.write_text("names: {}\nlabel_id: {}\n", encoding="utf-8")
+    s = Settings(consumable_classifier_labels_yaml_path=str(yml))
+    svc = ConsumableVisionAlgorithmService(s)
     mock_cls = MagicMock()
     mock_cls.names = {0: "x"}
     monkeypatch.setattr(svc, "_get_cls", lambda: mock_cls)
     assert svc.effective_candidate_consumables(["", "  "]) == ["x"]
+
+
+def test_build_name_mapping_from_label_id(tmp_path: Path) -> None:
+    yml = tmp_path / "lab.yaml"
+    yml.write_text(
+        "names:\n  0: 商品A\nlabel_id:\n  0: y1/y2\n",
+        encoding="utf-8",
+    )
+    s = Settings(consumable_classifier_labels_yaml_path=str(yml))
+    svc = ConsumableVisionAlgorithmService(s)
+    m = svc.build_name_mapping(["商品A"])
+    assert m["商品A"] == "y1/y2"
+
+
+def test_build_name_mapping_uses_name_when_no_id_in_yaml(
+    tmp_path: Path,
+) -> None:
+    yml = tmp_path / "lab.yaml"
+    yml.write_text(
+        "names:\n  0: 仅表内有的\nlabel_id: {}\n",
+        encoding="utf-8",
+    )
+    s = Settings(consumable_classifier_labels_yaml_path=str(yml))
+    svc = ConsumableVisionAlgorithmService(s)
+    m = svc.build_name_mapping(["仅表内有的"])
+    assert m["仅表内有的"] == "仅表内有的"