refactor(web-platform): release V0.7.2 项目常规优化

2026-09-01 16:39:04 +08:00
parent 89d1c8cb57
commit 8ba83a8d0a
28 changed files with 993 additions and 932 deletions
@@ -0,0 +1,41 @@
+# 前端架构
+
+`src/` 采用“应用壳 + 业务域 + 共享基础设施”的组织方式。
+
+## 目录职责
+
+```text
+src/
+├── app/            应用入口、跨域编排、工作区壳和全局反馈
+├── components/ui/  无业务依赖的共享 UI 基础组件
+├── controller/     Python 控制器运行时、类型和面板
+├── map/            地图加载、生成、编辑和面板
+├── project/        工程导入、转换、文件树和工作区
+├── rl/             ONNX 策略运行时、任务绑定、类型和面板
+├── simulation/     MuJoCo 会话、物理适配器和仿真控制组件
+├── telemetry/      数据源抽象、记录器、导出和数据面板
+├── training/       本地训练客户端、类型和面板
+├── viewer/         Three.js 场景、渲染和交互
+├── stores/         跨域应用状态
+└── test/           全局测试初始化
+```
+
+## 依赖规则
+
+1. `components/ui` 不依赖任何业务域。
+2. 业务组件、类型和测试与所属业务域共置。
+3. `app` 负责组合业务域，不承载可复用的业务算法或运行时。
+4. `simulation` 不依赖 React 应用状态；遥测通过 `TelemetrySource` 接口读取仿真数据。
+5. 业务域之间通过显式类型和门面交互，避免从其他域读取内部状态。
+6. 新文件优先放入已有业务域；只有跨域复用且不含业务语义的组件才进入 `components/ui`。
+
+## 主要运行链路
+
+```text
+项目文件 → project → PhysicsAdapter → SimulationSession → MuJoCo WASM
+                                    ├→ controller / rl
+                                    └→ telemetry
+SimulationSession snapshot → app → viewer / 各业务面板
+```
+
+测试文件使用 `*.test.ts(x)` 与被测模块共置；端到端测试统一保存在 `e2e/`。