feat: align surgery API with schemas and extend client tooling

- Refactor app API and schemas; adjust surgery pipeline, repository, and session manager.

- Improve consumption TSV logging and consumable vision integration; trim voice resolution.

- Add Baidu Face 1:N search script, .env.example entries, and client API integration doc.

- Update demo client, staging checklist, surgery interface doc, and related tests; add sample face image.

Made-with: Cursor

tests/test_consumption_tsv_log.py

@@ -6,11 +6,14 @@ from app.config import settings
 from app.services.consumable_vision_algorithm import ClsTop3
 from app.services.consumption_tsv_log import (
     HEADER,
+    SUMMARY_HEADER,
     _RANGE_SEP,
+    append_consumption_log_summary,
     append_consumption_tsv_line,
     build_consumption_markdown,
     build_tsv_line,
     init_consumption_log_file,
+    resolve_consumption_item_id,
     short_camera_label,
 )
 
@@ -44,25 +47,27 @@ def test_build_tsv_line_matches_sample_shape(monkeypatch: pytest.MonkeyPatch) ->
         wall_end_epoch=w0 + 45.0,
     )
     parts = line.rstrip("\n").split("\t")
-    assert len(parts) == 7
+    assert len(parts) == 5
     assert parts[0] == "2237844"
-    assert parts[1] == "一次性医用灭菌棉签 0.9997"
-    assert parts[2] == "cls2"
-    assert parts[3] == "cls3"
-    assert parts[4] == "1"
-    assert parts[5] == "DOCTOR_PLACEHOLDER"
+    assert parts[1] == "一次性医用灭菌棉签"
+    assert parts[2] == "1"
+    assert parts[3] == "DOCTOR_PLACEHOLDER"
     assert (
-        parts[6]
+        parts[4]
         == "cam01@2024-01-01T00:00:00.000+00:00"
         + _RANGE_SEP
         + "2024-01-01T00:00:45.000+00:00"
     )
 
 
+def test_resolve_consumption_item_id_uses_normalized_catalog_key() -> None:
+    name_to_code = {"一次性使用手术单（一次性医用垫单）": "PID-900"}
+    assert resolve_consumption_item_id("一次性医用垫单", "", name_to_code) == "PID-900"
+
+
 def test_header_columns() -> None:
     cols = HEADER.strip().split("\t")
-    assert cols[0] == "物品id"
-    assert cols[-1] == "时间戳"
+    assert cols == ["item_id", "item_name", "qty", "doctor_id", "timestamp"]
 
 
 def test_per_surgery_file_init_and_append(
@@ -84,6 +89,31 @@ def test_per_surgery_file_init_and_append(
     assert p.read_text(encoding="utf-8") == HEADER
 
 
+def test_append_consumption_log_summary_appends_three_column_block(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(settings, "consumption_tsv_log_enabled", True)
+    monkeypatch.setattr(
+        settings,
+        "consumption_tsv_log_path",
+        str(tmp_path / "{surgery_id}.txt"),
+    )
+    init_consumption_log_file("s1")
+    append_consumption_tsv_line("s1", "x\n")
+    append_consumption_log_summary(
+        "s1",
+        {"A": ("nA", 2), "B": ("nB", 1)},
+    )
+    text = (tmp_path / "s1.txt").read_text(encoding="utf-8")
+    assert text.endswith(
+        "\n"
+        + SUMMARY_HEADER
+        + "A\tnA\t2\n"
+        + "B\tnB\t1\n"
+    )
+
+
 def test_build_consumption_markdown_top123_columns(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(settings, "consumption_log_timezone", "UTC")
     best = ClsTop3(
@@ -106,15 +136,9 @@ def test_build_consumption_markdown_top123_columns(monkeypatch: pytest.MonkeyPat
         wall_start_epoch=w0,
         wall_end_epoch=w0 + 45.0,
     )
-    assert "Top1 物品id" in md and "Top1 物品名称" in md and "Top1 置信度" in md
-    assert "Top2 物品名称" in md and "Top3 物品名称" in md
-    assert "Top2 物品id" not in md
+    assert "| item_id |" in md and "| item_name |" in md and "| qty |" in md
     assert "2237844" in md
     assert "一次性医用灭菌棉签" in md
-    assert "0.9997" in md
-    assert "cls2" in md and "cls3" in md
-    assert "11765-1-101" not in md and "21504-1-1" not in md
-    assert "0.0003" not in md and "0.0002" not in md
     assert "DOCTOR_PLACEHOLDER" in md
     assert "| 1 |" in md
     # 终端为可读时间戳，非落盘用 ISO@cam