ykcheungab
bf643de93d
- What:
1. `docs/architecture/studio-3d-stages.md` 新增「阶段 6：运行正确性与失效状态（批次 A）—— 已完成」：
做（epoch/字段级来源/设备几何身份/加载请求号/工具与重编包）、验收表格（含两份探针的
before/after 与全量计数）、"这一阶段抓到的" 7 条、兼容说明 6 条；文首进度改成阶段 6 已完成、
7/8/9 未开始；依赖关系图扩展为 6→7/8→9。
2. `docs/architecture/studio-3d-contracts.pyi` 与本阶段的契约改动同步：`SceneState` 加 `'stale'`；
`SurfaceFieldFrame`/`RenderFrame` 加 `computed_frame_id`；`ExpectedGeometry` 加 `source_geometry_id`
并注明米制 id 何时为空；`SceneAssets` 加 `source_geometry_id`/`compatible_sensor_model`/
`compatible_hardware_revisions`；`ThreeDCoordinator.__init__` 加 `clock`/`stale_grace_s`，新增
`note_field_failure()`/`show_rest()`/`epoch`/`last_presented()`。
- Why: 规格 §13 要求每阶段同时交出实现、测试、输入样例、失败样例、兼容说明与平台诊断报告；阶段 6 的
契约改动（`SceneState`、两个 `computed_frame_id`、`ExpectedGeometry`/`SceneAssets` 的新身份字段、
协调器新参数）必须先落到接口骨架里，否则下一阶段会照着过期文档实现。审查报告本身不修改
（`_review_scene3d_20260914/` 保持原样），结论与反号证据写进本仓文档。
- Verification:
· 阶段末全量复核（与本提交同一工作树）：apps/studio 234 项 0 失败（14 跳过 = offscreen 下的真 GL 用例，
用 `QT_QPA_PLATFORM=windows` 单独跑为 14 项 0 失败 0 跳过）；shared 316 项 0 失败 1 跳过；
`ui_check` 587 项 0 失败；`locale_check` 0 缺失（zh/en 各 398 键，仅有键集合相同）；
`validate_scene.py` 对重编发布包 `source geometry recorded 46a03a5fbac1eace` 等全项 ok。
· 复现证据：`.repro/probe_stage6_r1.py`（R1/R7-b 反号）、`.repro/probe_stage6_device.py`
（R3：同尺寸不同映射被拒、表面不同被拒、设备不声明 → unverified），输出 JSON 与扫描件留在 `.repro/`。
- Not in this change: 不改代码（本提交只动文档与接口骨架）；阶段 7/8/9 的计划条目（二维后端统一、
回放入口收口、能力控件、限速与真实统计、保护包密钥注入、ARM 与 2 小时门禁）尚未开始；
真机上"算法链失败时 `VRAW` 是否也过期"这一条仍待实测（风险项已写进阶段 6 小节）。
orisys-app
Desktop applications that consume the Orisys SDK.
| App | Status |
|---|---|
apps/studio |
Scaffold shell (theme / locale / prefs / logging) |
apps/internal |
Stub for future calibration & automated testing |
Layout
shared/— common paths, prefs, theme, i18n, loggingapps/studio/config/— locales, default prefs, editablesensors/copiesapps/studio/outputs/— generated logs and calibration exports (gitignored)build/— Windows PyInstaller packaging (build/studio/build.ps1)
Run (studio shell)
cd D:\repo\orisys-app
python -m pip install -e .\shared -e .\apps\studio
python .\apps\studio\run.py
Or without install:
$env:PYTHONPATH = "D:\repo\orisys-app\shared\src;D:\repo\orisys-app\apps\studio\src"
python D:\repo\orisys-app\apps\studio\run.py
Local orisys SDK
orisys_app_shared.force imports orisys.calibration at module scope, so the
studio app cannot start against an SDK build that predates that module
(the published 0.5.2 wheel does not include it). When working from a repo
checkout, install the SDK from source instead of from an index:
python -m pip install .\..\orisys-sdk # same checkout that built this app
If a pip build is blocked by the environment, the equivalent manual install is
to copy orisys-sdk/src/orisys/**/*.py over site-packages/orisys/ and delete
the stale __init__.cp310-win_amd64.pyd (an extension module shadows the
package __init__.py, which hides sibling modules such as calibration.py).
Verifying UI changes
Both tools render the real main window with the offscreen Qt platform — no display, camera or sensor hardware required:
python .\apps\studio\tools\ui_check.py # layout/theme assertions
python .\apps\studio\tools\ui_snapshot.py --theme light --demo `
--sensor finger --panels cal,3d --size 1600x900 --out shot.png
ui_check.py needs only the runtime dependencies. The pytest suite in
shared/tests and apps/studio/tests covers the same ground plus locale and
preference-schema parity:
pip install pytest
python -m pytest
On Windows the offscreen platform finds no fonts unless QT_QPA_FONTDIR points
at C:\Windows\Fonts; both tools set it automatically.
ui_check.py also runs the palette rules (WCAG contrast, colour separation,
ramp monotonicity) that guard the brand tokens; see
apps/studio/docs/ui-palette.md for the
colour system, its relationship to the UI design spec, and every deliberate
deviation from it.
ui_check.py includes a record channel section as well; see
apps/studio/docs/record-channel.md for
why recording and calibration sampling no longer hang off the UI refresh timer,
and for the data-reliability fixes that came with it.
Branding
Window / EXE icon: shared/resources/branding/logo.png
Top bar / About: shared/resources/branding/logo_topbar.png
Dark mode is the default. Logos currently sit on a black tile; a transparent (or light) variant may be needed for polished light mode later.
Versioning
- Studio app version (
orisys_studio.__version__) — shown in Help → About and used for releases. - Shared package version (
orisys_app_shared.__version__) — internal library version. - Shared API (
orisys_app_shared.API_VERSION) — compatibility tag. Studio declaresREQUIRES_SHARED_API; startup logs a warning on mismatch.
Deferred
Run/Stop pipeline, arrow/force plots, units, calibration capture, Open3D finger mesh, sync-from-wheel for config/sensors, PyInstaller packaging, and the internal app.