feat(studio-3d): 设备几何身份接入 —— 同尺寸不同映射/不同表面被拒绝，资产加载只采用最新请求

- What: 1. **设备侧自己说几何**（新增 `shared/.../acquisition/geometry.py`）：`describe_sensor_geometry()` 从运行时真正加载的文件推导——`manifest.json` 的 `assets_dir`、`sensor.json` 的 `camera.resolution_stitch`/`source_scale`、以及据此命名的 unroll map（`unroll_map_uv_s0.4.npz`）。产出 `DeviceGeometry(expected, verified, detail)`：`field_domain_id` + `shape_hw`（映射身份，含 flip/scale/映射内容摘要）与 **无单位** 的 `source_geometry_id`（地图里 `world_xyz` 的内容摘要）。米制 `geometry_id` 需要"1 源单位 = N 米"这句只有人能做的声明，设备侧**故意留空**。两类失败区分对待：定位不到 bundle / 没写 `assets_dir` → `verified=False`（可显示，但不声明已校验）；bundle 变了（map 缺失、与 `resolution_stitch` 不符）→ 直接拒绝并指名两个形状/文件。 2. **契约**：`ExpectedGeometry += source_geometry_id`；`SceneAssets += source_geometry_id, compatible_sensor_model, compatible_hardware_revisions`；诊断码 `geometry_unverified`（info）； `digest.source_geometry_digest(world_xyz)`；`legacy.convert()` 写入 `source_geometry_id`； `package.py` 的 manifest 增 `source_geometry` 块（数组名与单位写明），读取时把 `compatible` 与 `source_geometry` 一并还原（旧包读到空串）。`validate_assets()` 的 expected 段重写：**只比较已声明的字段**，`source_geometry_id` 不符即拒绝，包内未记录该身份 → 返回 `geometry_unverified` 警告而不是静默通过；顺带修掉 `expected.sensor_model != assets.parts[0].role` 这行毫无意义的比较，改成真正的型号/硬件版本比对（`*` = 任意版本）。 3. **接线**：`app_window._sync_3d_source()` 传 `expected_provider=`（一个闭包，指向当前传感器配置）； `SceneAssetLoader` 在**工作线程**上解析它（`_resolve_and_load`）；`view.use_scene(assets, source_id, expected)` 改为 `validate_assets(assets, expected)` 并把警告送到面板，同时记录 `device_verified`； `_make_snapshot()` 用**设备**的身份构造 adapter（设备没声明的字段才回退资产），使 "帧与场景匹配" 第一次成为独立检查而不是自证；`describe()` 记录 `scene.device_verified` 与设备身份。 4. **资产加载请求身份（R7-a）**：`SceneAssetLoader` 增请求号与 pending 槽——忙时不再丢弃新请求，而是保留最新一个并在前一个结束后启动；完成信号带请求号（`loaded(assets, 描述, id, device)` / `failed(diag, id)`），`Mesh3dPanel` 丢弃过期完成（否则旧文件的场景会落回新选择上）。失败后可重试。 5. **工具与包**：`compile_scene.py`/`validate_scene.py` 报告 `geometry_id`/`field_domain_id`/ `source_geometry_id`/兼容信息；README 写明无单位身份是什么、为什么设备侧用它；**重编发布包** `apps/studio/config/sensors/finger/scene/finger-display-1.0.0.oryscene`（geometry_id 仍为 `1a2e0e92…`、1032 顶点 / 1974 三角形，新增 `source_geometry_id=46a03a5f…`，因此 asset_hash 变为 `ea4beab6…`）。 - Why: 审查报告 P1/R3：主窗口只传 sensor_type 与 package_override，`Mesh3dPanel._expected` 永远是 None， `validate_assets(assets, None)` 跳过全部设备比对，而 adapter 的 geometry_id/field_domain_id/shape_hw 全部来自**已选中的资产**——于是收到的数据被贴上"资产自己期望的身份"。结果：shape 相同但 UV 映射、 flip_v、source_scale 或相机配置不同时无法区分。P1/R7：`SceneAssetLoader.load()` 在忙时直接 return，既没保留最新请求也没有 generation，`_on_loaded` 又用当前 `_source` 标记已加载路径，快速切换配置时旧文件的任务会回到新选择上。 - Verification: · 证据探针 `.repro/probe_stage6_device.py` → `probe_stage6_device.json`（真实 bundle + 真实包）：设备描述 `verified=true`、domain `feb7f71e…`、source geometry `46a03a5f…`、shape 300x280、米制 id 未声明、map = `unroll_map_uv_s0.4.npz`；发布包通过该描述；**同尺寸不同映射**（只改 map 一个像素的坐标）→ domain 变化、shape 不变、包被 `field_domain_mismatch` 拒绝；设备什么都不声明 → 接受 + `geometry_unverified`。 · 新增 `shared/tests/test_scene3d_device_geometry.py` 9 项：描述来源、发布包通过、同尺寸不同映射拒绝、同 map 不同表面拒绝、定位不到 bundle → unverified、`resolution_stitch` 与 map 不符拒绝、map 缺失指名文件、无 `assets_dir` → unverified、map 命名规则。 · `test_scene3d_contracts.py` +4（未声明身份 → 警告而非匹配、source geometry 不符拒绝/缺记录 → 警告、型号与硬件版本、`source_geometry_digest` 的稳定性与形状校验）；`test_scene3d_package.py` +2 （`source_geometry` 往返、旧包读成"未声明"）；`test_scene3d_view.py` +6（adapter 身份来自设备、设备 domain 不符 → 拒绝且不上屏、无描述 → `geometry_unverified` 且 `device_verified=false`、 **最新请求才运行**、面板丢弃过期完成、失败后可重试）。 · 全量：apps/studio 0 失败（`--junitxml`：231→236 项）；shared 0 失败（含 device_geometry 9 项）； `validate_scene.py` 对重编包全项 ok。 - Not in this change: 生产侧仍不声明米制 `geometry_id`（那句单位声明只有人能写；要设备端复算它需要把 `meters_per_source_unit` 与刚体变换记进配置，属可选加强项，已在本提交的 `DeviceGeometry.detail` 里留位）； `ExpectedGeometry.mapping_digest` 未加——`field_domain_id` 本身就是由映射内容摘要派生的，再加一个字段只是同一个事实的第二个名字；`docs/architecture/studio-3d-contracts.pyi` 与本阶段新契约的同步放在阶段 6 的文档提交里；保护包密钥注入（R4）、限速与真实统计、二维后端统一均未动。
2026-09-14 21:10:53 +08:00
parent 7d1fca4c93
commit 3c0424b90c
17 changed files with 981 additions and 40 deletions
@@ -23,6 +23,7 @@ from __future__ import annotations
 import itertools
 import shutil
 import time
+from concurrent.futures import Future
 from dataclasses import replace
 from pathlib import Path

@@ -305,6 +306,8 @@ class _RecordingView(QWidget):
        self.packets: list = []
        self.coordinator = None
        self.assets = None
+        self.scenes_used: list = []
+        self.accept_scene = True
        self.available = True
        self.reason = ""
        self.source_kind = "live"
@@ -321,6 +324,14 @@ class _RecordingView(QWidget):
        float(np.asarray(frame, dtype=np.float64).sum())

    # the container's contract
+    def use_scene(self, assets, source_id: str, expected=None) -> bool:
+        """The seam ``Mesh3dPanel._on_loaded`` adopts a scene through."""
+        self.scenes_used.append((assets, source_id, expected))
+        if not self.accept_scene:
+            return False
+        self.assets = assets
+        return True
+
    def set_enabled(self, enabled: bool) -> None:
        self.enabled_flag = bool(enabled)

@@ -554,16 +565,108 @@ def test_a_package_is_loaded_off_the_gui_thread(qt_app, write_poc):
    assets, description = loaded[0]
    assert assets.geometry_id == synthetic.poc_scene().geometry_id
    assert str(path) in description
-    # A second load while one is in flight is the same request, not a queue.
+    # A second request while one is in flight is not dropped: it is the one the
+    # operator asked for *last*, so it waits for the first to finish and then runs.
    loader2 = SceneAssetLoader()
    try:
        loader2._inflight = True
-        loader2.load(SceneSource(path=path, kind="package", directory=path.parent))
-        assert loader2._executor is None
+        first = loader2.load(SceneSource(path=path, kind="package", directory=path.parent))
+        second = loader2.load(SceneSource(path=path, kind="package", directory=path.parent))
+        assert second > first
+        assert loader2._executor is None, "a queued request must not open a second worker"
+        assert loader2._pending is not None, "the newer request was dropped"
+        assert loader2._pending[-1] == second
    finally:
        loader2.close()


+class _ManualExecutor:
+    """Futures that only run when the test says so, like a loaded thread pool."""
+
+    def __init__(self) -> None:
+        self.pending: list = []
+
+    def submit(self, function, *args, **kwargs):
+        future: Future = Future()
+        self.pending.append((future, function, args, kwargs))
+        return future
+
+    def run_next(self) -> None:
+        future, function, args, kwargs = self.pending.pop(0)
+        if future.set_running_or_notify_cancel():
+            try:
+                future.set_result(function(*args, **kwargs))
+            except BaseException as exc:  # noqa: BLE001 - mirrored into the future
+                future.set_exception(exc)
+
+    def shutdown(self, wait: bool = True) -> None:  # noqa: ARG002 - executor contract
+        self.pending.clear()
+
+
+def test_the_newest_load_is_the_one_that_runs(qt_app, write_poc):
+    """R7: requests carry an id, and a queue keeps the newest rather than the first."""
+    from orisys_studio.scene3d.asset_source import SceneAssetLoader
+
+    path = write_poc()
+    loader = SceneAssetLoader()
+    loader._executor = _ManualExecutor()
+    answers: list = []
+    loader.loaded.connect(
+        lambda assets, description, request_id, device: answers.append(request_id)
+    )
+    loader.failed.connect(lambda item, request_id: answers.append(("failed", request_id)))
+    try:
+        first = loader.load(SceneSource(path=path, kind="package", directory=path.parent))
+        second = loader.load(SceneSource(path=path, kind="package", directory=path.parent))
+        assert answers == [], "a request was answered before its worker ran"
+        loader._executor.run_next()
+        assert answers == [first], "the pending request did not start after the first"
+        assert loader._pending is None
+        loader._executor.run_next()
+        assert answers == [first, second]
+    finally:
+        loader.close()
+
+
+def test_the_pane_ignores_a_completion_for_a_superseded_load(qt_app):
+    """The other half: an old answer must not mark the *new* selection as loaded."""
+    from orisys_studio.ui.mesh3d_panel import Mesh3dPanel
+
+    panel = Mesh3dPanel()
+    view = _RecordingView()
+    panel.attach_view(view)
+    assets = synthetic.poc_scene()
+    panel._load_request = 2
+    panel._on_loaded(assets, "old.oryscene", 1, None)
+    assert view.assets is None, "a completion for an older request was adopted"
+    panel._on_loaded(assets, "new.oryscene", 2, None)
+    assert view.assets is assets
+    assert view.scenes_used[-1][1] == "new.oryscene"
+
+
+def test_a_failed_load_can_be_retried(qt_app, tmp_path, write_poc):
+    """A rejection is not a dead end: the next request still runs."""
+    from orisys_studio.scene3d.asset_source import SceneAssetLoader
+
+    broken = tmp_path / f"broken{PACKAGE_SUFFIX}"
+    broken.write_bytes(b"not a zip archive at all")
+    good = write_poc()
+    loader = SceneAssetLoader()
+    loader._executor = _ManualExecutor()
+    answers: list = []
+    loader.loaded.connect(lambda assets, description, request_id, device: answers.append(request_id))
+    loader.failed.connect(lambda item, request_id: answers.append(("failed", request_id)))
+    try:
+        bad = loader.load(SceneSource(path=broken, kind="package", directory=tmp_path))
+        loader._executor.run_next()
+        assert answers == [("failed", bad)]
+        again = loader.load(SceneSource(path=good, kind="package", directory=good.parent))
+        loader._executor.run_next()
+        assert answers[-1] == again
+    finally:
+        loader.close()
+
+
 def test_a_corrupt_package_is_reported_not_raised(qt_app, tmp_path):
    from orisys_studio.scene3d.asset_source import SceneAssetLoader

@@ -694,6 +797,79 @@ def test_a_fresh_field_reaches_the_screen_and_clears_the_stale_state(qt_app):
        view.close()


+# ---------------------------------- stage 6: the adapter speaks for the *device* (R3)
+def test_the_adapter_identity_comes_from_the_device_not_the_asset(qt_app):
+    """R3: built from the asset, "the frame matches the scene" is self-certified."""
+    from orisys_app_shared.scene3d.contracts import ExpectedGeometry
+    from orisys_studio.scene3d.view import Scene3DView
+
+    view = Scene3DView()
+    try:
+        if not view.available:
+            pytest.skip("no GL binding here")
+        assets = replace(synthetic.poc_scene(), source_geometry_id="device-src")
+        device = ExpectedGeometry(
+            "finger",
+            "rev",
+            "",
+            assets.field_domain_id,
+            assets.shape_hw,
+            source_geometry_id="device-src",
+        )
+        assert view.use_scene(assets, source_id="poc", expected=device)
+        described = view.describe()["scene"]
+        assert described["device_verified"] is True, described
+        assert described["device"]["source_geometry_id"] == "device-src"
+        assert described["source_geometry_id"] == "device-src"
+
+        adapter = view._adapter
+        assert adapter is not None
+        # The device stated no metre-scaled id, so the asset's is used *and* the pane
+        # is only verified on the identities the device did state.
+        assert adapter.geometry_id == assets.geometry_id
+        assert adapter.field_domain_id == assets.field_domain_id
+        assert adapter.shape_hw == tuple(assets.shape_hw)
+    finally:
+        view.close()
+
+
+def test_a_device_whose_domain_disagrees_refuses_the_scene(qt_app):
+    from orisys_app_shared.scene3d.contracts import ExpectedGeometry
+    from orisys_studio.scene3d.view import Scene3DView
+
+    view = Scene3DView()
+    try:
+        if not view.available:
+            pytest.skip("no GL binding here")
+        assets = synthetic.poc_scene()
+        device = ExpectedGeometry(
+            "finger", "", "", "somebody-elses-domain", assets.shape_hw
+        )
+        assert view.use_scene(assets, source_id="poc", expected=device) is False
+        assert view.assets is None
+        assert view.last_diagnostic is not None
+        assert view.last_diagnostic.code == "field_domain_mismatch"
+    finally:
+        view.close()
+
+
+def test_a_scene_without_a_device_description_is_shown_as_unverified(qt_app):
+    """Expected unknown: show the surface, but never claim it was checked."""
+    from orisys_studio.scene3d.view import Scene3DView
+
+    view = Scene3DView()
+    try:
+        if not view.available:
+            pytest.skip("no GL binding here")
+        assert view.use_scene(synthetic.poc_scene(), source_id="poc")
+        described = view.describe()["scene"]
+        assert described["device_verified"] is False
+        assert view.last_diagnostic is not None
+        assert view.last_diagnostic.code == "geometry_unverified"
+    finally:
+        view.close()
+
+
 # ------------------------------------------------------- stage 5: the record block
 def test_a_recording_says_what_the_3d_pane_was(
    make_window, next_record_root, write_poc, qt_app, monkeypatch