阶段 2：资产合同 —— 旧 NPZ 导入、坐标/单位、绑定、包容器与工具 - What: shared/scene3d 新增四个模块与两个工具的真实现。digest.py：规范化内容摘要（C 连续小端字节 + 排序 JSON；DIGEST_SCHEMA 版本化），geometry_id（只看 part 角色/顶点/三角形，故意不含法线材质与 LOD 名——改颜色不得让标定失效）、binding_id、field_domain_id（形状、flip_v、source_scale、原点/索引约定、映射内容）、asset_hash（条目摘要 + 去自引用字段的 manifest）。legacy.py：LegacyFingerImporter 按"先单位、后刚体"两步转换（meters_per_source_unit 必填且不得猜、validate_rigid_transform 拒绝含缩放/镜像/非仿射的 4x4）；split_at_uv_seams 按 (源顶点, 量化 UV) 拆点，接缝处不平均 UV；vertex_normals 面积加权并给无面顶点有限回退；uv_to_pixel 采用实测约定 x=u*(W-1)、y=(1-v)*(H-1)（flip_v 时）；build_binding 生成四点双线性采样表（域内裁剪、零权 tap 丢弃并重分配、未用项 -1/0）；uv_correspondence_residual 用 Procrustes 残差把"UV 是否对得上 world_xyz"变成可断言的事实；estimate_meters_per_source_unit 只报告不应用。glb.py：glTF 2.0 子集读取（GLB 头/chunk 校验、accessor/bufferView/stride、节点 TRS 与矩阵烘焙进顶点、法线用逆转置再归一化、缺法线则计算），明确拒绝 Draco/meshopt/量化扩展、稀疏 accessor、外部 buffer、骨骼、形态目标、非 TRIANGLES、越界索引、非有限坐标与超预算三角形；with_housing 把外壳作为独立 part 加入且不动感知几何 id。package.py：.oryscene（zip：envelope.json + manifest.json + sensing/housing *.npy，无 pickle 无代码执行），写入原子（先写 .partial 再替换）、读取逐一校验 magic/envelope 版本/payload 状态/条目路径/manifest 自哈希/逐条目 sha256/dtype/shape/**从包内数组重算 geometry_id 与 binding_id**，加密封套明确报"本版本只开明文包"。tools/scene_assets/validate_scene.py 与 compile_scene.py 真实现（含 --json 报告与退出码：0 通过、2 检查失败、1 参数/文件问题；未给单位时停在 needs_units 并打印实测候选尺度）。测试：shared/tests/test_scene3d_assets.py 33 项（真实 1032 导出与 1005 对比资产的输入样例、接缝/法线/绑定/单位/变换/摘要的失败样例、GLB 往返与拒绝样例）、test_scene3d_package.py 24 项（往返、外壳条目、以及篡改条目/篡改 manifest 哈希/自洽但错误的几何/非有限坐标/多余条目/缺条目/路径穿越/dtype 与 shape 不符/未来版本/加密封套/key provider 的拒绝）。docs/architecture/studio-3d-stages.md 阶段 2 记为完成并附验收结果。 - Why: 阶段 2 要回答的是"这份几何到底是什么、单位是什么、它和哪套 UV 域配套、以及这份包有没有被动过"，这些一旦错了会以"三维看起来有点怪"的形式出现且事后无法追溯。因此把 UV 约定做成可测量的事实（真实资产残差 0.0064 vs 错误翻转 0.59）、把单位做成必填参数而不是默认值、把 identity 做成内容摘要并**在读取时重算**，同时用真实资产当输入样例、用篡改后的包当失败样例。 - Verification: 真实资产导入：1032 顶点/1974 三角形/域 300×280/尺寸 15.81×15.0×7.5 mm，validate_assets 通过；UV 残差 0.0064（错翻转 0.59）；两套资产混用被拒（geometry_mismatch）；缩放/镜像/非仿射变换被拒；compile→validate 端到端 ok（包内条目哈希与 manifest 自哈希全部通过）；shared 全量 244 passed；studio 118 passed；ui_check 554 项 0 失败；.repro/verify_assets.py 22 项 0 失败。过程中修掉 5 个真实缺陷：np.load 需要真实文件对象（手写内存 stub 抛空消息异常）、包可以"自洽却错误"（改数组+改哈希后无人重算几何 id，现已重算并比对）、binding 行数不匹配被误报为域错误、np.ptp 平铺比较无意义（换算/不变性断言改为按轴）、以及合成 PoC 场景自己用字符串当 geometry_id（所有人都会抄它，等于绕过检查）。 - Not in this change: 签名与 AES-GCM（阶段 5）；LOD 简化；calibration.py 侧的资产哈希登记；三维视图仍未被应用导入（阶段 4 接线）。

2026-09-14 15:08:29 +08:00
parent cad795c890
commit d0dcac743f
11 changed files with 3065 additions and 58 deletions
@@ -0,0 +1,369 @@
+"""Stage 2 acceptance for the ``.oryscene`` container.
+
+The interesting half is the refusals: a package that is *nearly* right is the case a
+loader has to catch, because the failure mode it prevents (a scene that renders with
+someone else's geometry) is silent. Every test below mutates one thing about a
+package that was just written correctly, and asserts that the loader says no — with
+the code the design document assigns to that failure.
+"""
+
+from __future__ import annotations
+
+import json
+import zipfile
+from dataclasses import replace
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from orisys_app_shared.scene3d import synthetic
+from orisys_app_shared.scene3d.contracts import ExpectedGeometry, ThreeDError
+from orisys_app_shared.scene3d.digest import asset_hash, content_digest
+from orisys_app_shared.scene3d.glb import with_housing
+from orisys_app_shared.scene3d.package import (
+    MAGIC,
+    describe_package,
+    read_package,
+    scene_from_contents,
+    write_package,
+)
+from orisys_app_shared.scene3d.package import PackagedAssetLoader
+
+
+@pytest.fixture
+def scene():
+    """A complete little scene: one sensing plate and one housing box."""
+    return synthetic.poc_scene()
+
+
+@pytest.fixture
+def package(tmp_path, scene):
+    path = tmp_path / "poc.oryscene"
+    report = write_package(scene, path)
+    assert report.output == path
+    return path
+
+
+def _rewrite(source: Path, destination: Path, mutate) -> Path:
+    """Copy a package, letting ``mutate`` change the members on the way through."""
+    with zipfile.ZipFile(source) as archive:
+        members = {info.filename: archive.read(info.filename) for info in archive.infolist()}
+    members = mutate(members)
+    with zipfile.ZipFile(destination, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+        for name in sorted(members):
+            archive.writestr(name, members[name])
+    return destination
+
+
+def _manifest(members) -> dict:
+    return json.loads(members["manifest.json"])
+
+
+def _store_manifest(members, manifest: dict) -> None:
+    members["manifest.json"] = json.dumps(manifest, indent=2, sort_keys=True).encode("utf-8")
+
+
+def _rehash(members, manifest: dict) -> None:
+    """Recompute the asset hash after a deliberate edit: the *content* is what lies."""
+    stripped = {k: v for k, v in manifest.items() if k not in ("asset_hash", "entry_digest")}
+    digest = asset_hash(
+        {name: str(record["sha256"]) for name, record in stripped["entries"].items()},
+        stripped,
+    )
+    manifest["asset_hash"] = digest
+    manifest["entry_digest"] = {
+        name: record["sha256"] for name, record in stripped["entries"].items()
+    }
+    _store_manifest(members, manifest)
+
+
+# ------------------------------------------------------------------ round trip
+def test_a_package_round_trips_into_the_same_scene(package, scene):
+    contents = read_package(package)
+    rebuilt = scene_from_contents(contents)
+    assert rebuilt.geometry_id == scene.geometry_id
+    assert rebuilt.field_domain_id == scene.field_domain_id
+    assert rebuilt.asset_id == scene.asset_id
+    assert rebuilt.shape_hw == scene.shape_hw
+    assert len(rebuilt.parts) == len(scene.parts)
+    for original in scene.parts:
+        copy = rebuilt.part(original.part_id)
+        assert copy is not None
+        assert np.array_equal(copy.positions_sensor_m, original.positions_sensor_m)
+        assert np.array_equal(copy.triangles, original.triangles)
+    assert np.array_equal(
+        np.asarray(rebuilt.binding.sample_indices),
+        np.asarray(scene.binding.sample_indices),
+    )
+    assert not np.asarray(rebuilt.binding.sample_weights).flags["WRITEABLE"]
+    assert [preset.name for preset in rebuilt.camera_presets] == [
+        preset.name for preset in scene.camera_presets
+    ]
+
+
+def test_the_loader_accepts_its_own_package_and_checks_the_device(package, scene):
+    loader = PackagedAssetLoader()
+    expected = ExpectedGeometry(
+        "finger", "rev-a", scene.geometry_id, scene.field_domain_id, scene.shape_hw
+    )
+    loaded = loader.load(package, expected)
+    assert loaded.geometry_id == scene.geometry_id
+    assert loader.validate(loaded, expected) == ()
+    wrong = ExpectedGeometry("finger", "rev-a", "other-geometry", scene.field_domain_id, scene.shape_hw)
+    with pytest.raises(ThreeDError) as excinfo:
+        loader.load(package, wrong)
+    assert excinfo.value.diagnostic.code == "geometry_mismatch"
+
+
+def test_the_package_report_describes_the_package(package):
+    report = describe_package(package)
+    assert report["asset_id"] == "poc-scene"
+    assert report["parts"] == {"sensing_surface": "sensing", "housing": "housing"}
+    assert report["shape_hw"] == [3, 3]
+    assert "sensing/positions.npy" in report["entries"]
+    assert report["vertices"]["sensing"] == 9
+
+
+def test_a_housing_part_survives_packaging(tmp_path):
+    """The housing has its own entries and keeps its role through the round trip."""
+    sensing_only = replace(synthetic.poc_scene(), parts=(synthetic.poc_scene().sensing_part(),))
+    housing = synthetic.poc_scene().part("housing")
+    scene = with_housing(sensing_only, housing)
+    path = tmp_path / "with-housing.oryscene"
+    write_package(scene, path)
+    rebuilt = scene_from_contents(read_package(path))
+    assert {part.role for part in rebuilt.parts} == {"sensing", "housing"}
+    assert np.array_equal(
+        rebuilt.part("housing").positions_sensor_m, housing.positions_sensor_m
+    )
+    assert rebuilt.part("housing").material.shading == "diffuse"
+
+
+# --------------------------------------------------------------- refusals
+def test_a_tampered_entry_is_refused(package, tmp_path):
+    def mutate(members):
+        members["sensing/positions.npy"] = b"not an array any more"
+        return members
+
+    broken = _rewrite(package, tmp_path / "tampered.oryscene", mutate)
+    with pytest.raises(ThreeDError) as excinfo:
+        read_package(broken)
+    assert excinfo.value.diagnostic.code == "asset_auth_failed"
+
+
+def test_a_tampered_manifest_hash_is_refused(package, tmp_path):
+    def mutate(members):
+        manifest = _manifest(members)
+        manifest["geometry_id"] = "somebody-elses-geometry"
+        _store_manifest(members, manifest)  # hash deliberately *not* recomputed
+        return members
+
+    broken = _rewrite(package, tmp_path / "manifest.oryscene", mutate)
+    with pytest.raises(ThreeDError) as excinfo:
+        read_package(broken)
+    assert "manifest hash does not match" in excinfo.value.diagnostic.message
+
+
+def test_geometry_that_is_swapped_in_with_a_matching_hash_is_still_refused(package, tmp_path):
+    """Consistency is not correctness: the binding must belong to the mesh."""
+    def mutate(members):
+        manifest = _manifest(members)
+        # Drop the sensing mesh to nine *different* positions but keep the binding,
+        # then fix every hash: the package is internally consistent and still wrong.
+        positions = np.zeros((9, 3), dtype=np.float32)
+        positions[:, 0] = np.arange(9, dtype=np.float32) * 0.01
+        import io
+
+        buffer = io.BytesIO()
+        np.save(buffer, positions, allow_pickle=False)
+        members["sensing/positions.npy"] = buffer.getvalue()
+        manifest["entries"]["sensing/positions.npy"]["sha256"] = content_digest(
+            {"data": positions}
+        )
+        _rehash(members, manifest)
+        return members
+
+    swapped = _rewrite(package, tmp_path / "swapped.oryscene", mutate)
+    contents = read_package(swapped)  # hash-wise it is a valid package
+    with pytest.raises(ThreeDError) as excinfo:
+        scene_from_contents(contents)
+    assert excinfo.value.diagnostic.code == "geometry_mismatch"
+    assert "geometry" in excinfo.value.diagnostic.message.lower()
+
+
+def test_non_finite_positions_are_refused(package, tmp_path):
+    def mutate(members):
+        import io
+
+        manifest = _manifest(members)
+        positions = np.zeros((9, 3), dtype=np.float32)
+        positions[0, 0] = np.nan
+        buffer = io.BytesIO()
+        np.save(buffer, positions, allow_pickle=False)
+        members["sensing/positions.npy"] = buffer.getvalue()
+        manifest["entries"]["sensing/positions.npy"]["sha256"] = content_digest(
+            {"data": positions}
+        )
+        _rehash(members, manifest)
+        return members
+
+    broken = _rewrite(package, tmp_path / "nan.oryscene", mutate)
+    with pytest.raises(ThreeDError) as excinfo:
+        scene_from_contents(read_package(broken))
+    assert "non-finite" in excinfo.value.diagnostic.message
+
+
+def test_an_undeclared_entry_is_refused(package, tmp_path):
+    def mutate(members):
+        members["sensing/extra.npy"] = b"\x00"
+        return members
+
+    broken = _rewrite(package, tmp_path / "extra.oryscene", mutate)
+    with pytest.raises(ThreeDError) as excinfo:
+        read_package(broken)
+    assert "undeclared entries" in excinfo.value.diagnostic.message
+
+
+def test_a_promised_entry_that_is_absent_is_refused(package, tmp_path):
+    def mutate(members):
+        members.pop("sensing/normals.npy")
+        return members
+
+    broken = _rewrite(package, tmp_path / "absent.oryscene", mutate)
+    with pytest.raises(ThreeDError) as excinfo:
+        read_package(broken)
+    assert "which is absent" in excinfo.value.diagnostic.message
+
+
+def test_a_path_that_escapes_the_package_is_refused(package, tmp_path):
+    def mutate(members):
+        manifest = _manifest(members)
+        record = manifest["entries"].pop("sensing/normals.npy")
+        manifest["entries"]["../normals.npy"] = record
+        _rehash(members, manifest)
+        return members
+
+    broken = _rewrite(package, tmp_path / "traversal.oryscene", mutate)
+    with pytest.raises(ThreeDError) as excinfo:
+        read_package(broken)
+    assert "escapes the package" in excinfo.value.diagnostic.message
+
+
+def test_a_dtype_or_shape_that_disagrees_with_the_manifest_is_refused(package, tmp_path):
+    for field, value, expected in (
+        ("dtype", "i4", "field_domain_mismatch"),
+        ("shape", [8, 3], "field_domain_mismatch"),
+    ):
+        def mutate(members, field=field, value=value):
+            manifest = _manifest(members)
+            manifest["entries"]["sensing/positions.npy"][field] = value
+            _rehash(members, manifest)
+            return members
+
+        broken = _rewrite(package, tmp_path / f"bad-{field}.oryscene", mutate)
+        with pytest.raises(ThreeDError) as excinfo:
+            read_package(broken)
+        assert excinfo.value.diagnostic.code == expected, field
+
+
+def test_an_envelope_from_the_future_or_another_tool_is_refused(package, tmp_path):
+    def wrong_magic(members):
+        envelope = json.loads(members["envelope.json"])
+        envelope["magic"] = "not-our-magic"
+        members["envelope.json"] = json.dumps(envelope).encode()
+        return members
+
+    broken = _rewrite(package, tmp_path / "magic.oryscene", wrong_magic)
+    with pytest.raises(ThreeDError) as excinfo:
+        read_package(broken)
+    assert excinfo.value.diagnostic.code == "asset_auth_failed"
+
+    def wrong_version(members):
+        envelope = json.loads(members["envelope.json"])
+        envelope["envelope_version"] = 99
+        members["envelope.json"] = json.dumps(envelope).encode()
+        return members
+
+    broken = _rewrite(package, tmp_path / "version.oryscene", wrong_version)
+    with pytest.raises(ThreeDError) as excinfo:
+        read_package(broken)
+    assert "envelope version" in excinfo.value.diagnostic.message
+
+
+def test_an_encrypted_envelope_says_so_instead_of_failing_obscurely(package, tmp_path):
+    """Stage 5 will open these; until then the message has to be honest."""
+    def encrypt(members):
+        envelope = json.loads(members["envelope.json"])
+        envelope["payload"] = "aead"
+        envelope["key_id"] = "customer-1"
+        members["envelope.json"] = json.dumps(envelope).encode()
+        return members
+
+    broken = _rewrite(package, tmp_path / "encrypted.oryscene", encrypt)
+    with pytest.raises(ThreeDError) as excinfo:
+        read_package(broken)
+    item = excinfo.value.diagnostic
+    assert item.code == "asset_auth_failed"
+    assert "plain packages only" in item.message
+
+
+def test_a_key_provider_is_refused_while_packages_are_plain(package, scene):
+    class Keys:
+        def get_content_key(self, key_id: str) -> bytes:  # pragma: no cover - not used
+            return b"secret"
+
+    expected = ExpectedGeometry(
+        "finger", "rev-a", scene.geometry_id, scene.field_domain_id, scene.shape_hw
+    )
+    with pytest.raises(ThreeDError) as excinfo:
+        PackagedAssetLoader().load(package, expected, Keys())
+    assert "key provider" in excinfo.value.diagnostic.message
+
+
+def test_the_manifest_carries_what_a_release_needs(package):
+    manifest = read_package(package).manifest
+    assert manifest["schema_version"] == "1.0"
+    assert manifest["coordinate_frame"] == "sensor"
+    assert manifest["length_unit"] == "m"
+    assert manifest["compatible"]["sensor_model"] == "finger"
+    assert manifest["field_domain"]["index_order"] == "row-major"
+    assert manifest["field_domain"]["origin"] == "top-left"
+    assert manifest["asset_hash"] and len(manifest["asset_hash"]) == 64
+    assert all(len(record["sha256"]) == 64 for record in manifest["entries"].values())
+
+
+def test_the_same_scene_compiles_to_the_same_hash(tmp_path, scene):
+    first = write_package(scene, tmp_path / "a.oryscene")
+    second = write_package(scene, tmp_path / "b.oryscene")
+    assert first.asset_hash == second.asset_hash
+    assert write_package(scene, tmp_path / "a.oryscene", sensor_model="box").asset_hash != (
+        first.asset_hash
+    ), "a different target device is a different package"
+
+
+def test_writing_is_atomic_so_a_failed_build_leaves_nothing(tmp_path, scene, monkeypatch):
+    """A half-written package must never be picked up by a later run."""
+    import orisys_app_shared.scene3d.package as package_module
+
+    target = tmp_path / "broken.oryscene"
+
+    def explode(*args, **kwargs):
+        raise RuntimeError("disk full")
+
+    monkeypatch.setattr(package_module.zipfile, "ZipFile", explode)
+    with pytest.raises(RuntimeError):
+        write_package(scene, target)
+    assert not target.exists()
+    assert not (tmp_path / "broken.oryscene.partial").exists(), (
+        "the partial file was left behind"
+    )
+
+
+def test_the_envelope_names_the_magic_and_the_payload_state(package):
+    with zipfile.ZipFile(package) as archive:
+        envelope = json.loads(archive.read("envelope.json"))
+    assert envelope["magic"] == MAGIC
+    assert envelope["envelope_version"] == 1
+    assert envelope["payload"] == "plain"
+    assert envelope["entry_count"] == len(read_package(package).arrays)