Migu2.0/PLATFORM_V3_CHANGES.md

平台 v3 重构 — 阶段 0~6 实际改动

范围：把 Simple3 WebTerminal 由"全功能浮动 Panel"模式收敛到"纯 3D Canvas"，所有 UI 改由 Vue 平台前端 (frontends/apps/simple-platform-vue) 接管；同时补齐反射 / 编辑 / 监控 / 编排 4 大业务面板与撤销栈、AI 生图、报警 SSE 等关键能力。

基线：上一份方案见 ARCHITECTURE.md v2/v3 章节；后续以本文件为准。

编译验证

• dotnet build Simple3/Simple3.csproj —— 0 警告 0 错误
• dotnet build MiGu.Server/MiGu.Server.csproj —— 0 警告 0 错误
• build-platform-frontend.bat —— vite build 46.5s，无 vue-tsc / ts 错误，robocopy /MIR 已同步 MiGu.Server/wwwroot
• 旧 SimpleComposer (WinForms) 在 v3 之外，不在本次构建目标里
• 旧 HttpClientHelper 提升 LangVersion=latest 修通

阶段 0：后端 Simple3 平台化（已完成）

新增文件

文件	作用
Simple3/Web/MapEditApiController.cs	写操作 8 路 API：create/delete/batch/copy-to/pick/dashboard/upload/ai-generate；阶段 6 又补：project/save、project/load、project/current、sample-sites-along-track
Simple3/Web/ReflectionApiController.cs	只读 + execute API；listKinds / listObjects / methods-by-type / setField / getBundle / selection 等
Simple3/Web/ReflectionApiDtos.cs	反射 API DTO + 统一信封 ReflectionEnvelope<T>
Simple3/Web/AiCompletionService.cs	OpenAI Function Calling 调用 + map-generate 工具桥（真实 LLM，不再桩）
Simple3/Web/AiConfigController.cs	AI 服务配置（endpoint/apiKey/model/system prompt/temperature/maxTokens/timeout）读写
Simple3/Web/AlarmStreamService.cs	1s 周期 diff car.status.enums.AlarmInfo（语义与 E:\Work\FRLD\StandardScene\Forklift.cs 的 Commons.GetCarStatus(this, "AlarmInfo") 等价），变化时通过 SSE alarm 事件推送 raise/update/clear
Simple3/Web/ProjectionStreamModule.cs	平台 SSE 总线，对外广播 object-created / object-deleted / object-patched / object-batch-changed / alarm / pick-result / project-saved / project-loaded
Simple3/Web/PluginAssemblyScan.cs	反射扫描 plugins/*.dll，把 MethodMember 标注的方法 + Car/Mission/CarProgram/Site/Track 子类型暴露给反射 API

修改文件

文件	关键改动
Simple3/Startup.cs	EntryPoint 第一步 EnsureImguiIniFromEmbedded()；启动 AlarmStreamService、ProjectionStreamModule、AiConfig 加载
Simple3/UI/SimpleUI.cs	CreateRemotePanelSetForTerminal 检测 CanvasOnly 旗标：不创建 Workbench / Toolbar / BottomBar / CAD / Welcome；保留 SelectionAction、SceneInput、SceneDrawable、2DMapView
Simple3/Workspace/WorkspaceWebUiContext.cs	增加 IsCanvasOnly(terminal) 旗标 + /declareCanvasOnly 注册器（与 /declareEmbedUi 互斥）
Simple3/Web/ProjectionWebHost.cs	/declareCanvasOnly 路由注册
Simple3/Web/ProjectionWebApiController.cs	现有 projection API 上挂 selection-detail SSE hook
Simple3/UI/ComposerDockPanel.cs	CanvasOnly 时 PrepareWelcomePanel 返回空
Simple3/Props/UIHelpers.cs	增加 UI_Image / UI_Text / UI_Model PropType。UI_Model 用于 CycleGUI 装饰物挂模型（obj/glb/gltf/cyclemodel）

关键 API 路径

POST  /projection/map-edit/objects/{kind}          # site|track|bezier|arc|nurbs|image|text|model
DELETE /projection/map-edit/objects/{kind}/{id}
POST  /projection/map-edit/objects/batch           # create/delete/patch 混合
POST  /projection/map-edit/objects/{kind}/{id}/fields/copy-to
POST  /projection/map-edit/pick                    # 拾取会话
GET   /projection/map-edit/dashboard/summary       # KPI 聚合
POST  /projection/map-edit/assets/upload           # 图片/模型 base64
POST  /projection/map-edit/ai/map-generate         # 真实 LLM 生图

# 阶段 6 新增（本会话）
POST  /projection/map-edit/project/save            # body: { path?: string }
POST  /projection/map-edit/project/load            # body: { path: string }
GET   /projection/map-edit/project/current
POST  /projection/map-edit/objects/track/{id}/sample-sites
                                                   # body: { spacingMm, includeEndpoints?, layer? }

GET   /projection/ai-config                        # 读 AI 服务配置
POST  /projection/ai-config                        # 写 AI 服务配置

GET   /projection/reflection/kinds | objects/{kind} | methods/{kind}/{id} | ...
SSE   /projection/stream                            # 所有 SSE 事件

阶段 1：MapEditorView 四栏壳（已完成）

frontends/apps/simple-platform-vue/src/views/admin/MapEditorView.vue 完整重写为：

┌─────────────────────────────────────────────────────┐
│ EditTopBar：项目 / 文件 / 编辑 / 视图 / 图层 / 对齐吸附 │
│             + 撤销/重做 + AI 生图 + 保存            │
├──────┬─────────────────────────┬───────────────────┤
│ Edit │   Workspace3D           │ EditPropertyPanel │
│ Tool │  (canvas-only iframe)   │ 对象/类型默认/图层 │
│ Rail │                         │                   │
├──────┴─────────────────────────┴───────────────────┤
│ EditStatusBar：选中 / 鼠标坐标 / 工具 / 吸附 / undo │
└─────────────────────────────────────────────────────┘

新增组件

• components/map-editor/EditTopBar.vue —— 6 个 dropdown 菜单（项目/文件/编辑/视图/图层/对齐吸附）+ 撤销重做按钮 + AI 生图入口 + 保存
• components/map-editor/EditToolRail.vue —— 6 组 CAD 工具按钮 + 吸附组（网格/对象/端点/中点 + 网格步长）
• components/map-editor/EditPropertyPanel.vue —— 3 Tab（对象 / 类型默认 / 图层），自动反射出 getFields，每行可改可保存；多选时统一字段写入；不一致字段显示「-」；执行 reflectionApi.execute 调任何 MethodMember
• components/map-editor/EditStatusBar.vue —— 状态栏
• components/map-editor/AiGenerateDialog.vue —— AI 生图对话框

反射 API 接入

• api/mapEdit.ts —— MapEditApiController 全 8+4 路 API 胶水（本会话补的 4 个：projectSave / projectLoad / projectCurrent / sampleSitesAlongTrack）
• api/reflection.ts —— ReflectionApiController 全套胶水（含 MOCK 离线 fallback）

阶段 2：对齐 / 批量生成 / 复制字段 / 类型默认 / 图层（已完成）

• composables/useAlignment.ts —— 11 种对齐模式：left/right/top/bottom/centerH/centerV/center/distributeH/distributeV/toFirst/toLast
• composables/useBatchGenerate.ts —— 横向/纵向/矩阵/环形 4 种批量生成器，输出 BatchOp[]
• composables/useClipboard.ts —— 对象/字段剪贴板
• transform.copyFields 工具：MapEditorView runCopyFields 读取多选（第 1 个为源，其余目标），prompt 字段名列表，调 mapEditApi.copyFieldsTo；撤销时用前置 patch 回滚
• 类型默认 Tab：站点/路径默认 layer/前缀/颜色/线宽，存 localStorage mapEditor.defaults
• 图层 Tab：图层名列表 + 可见 / 可选 / 颜色，本地状态

阶段 3：AI 生图 + 状态栏 + 项目保存/加载（已完成）

• AiGenerateDialog 通过 mapEditApi.aiMapGenerate 真实调用 LLM，后端走 AiCompletionService.GenerateMapAsync：用 OpenAI Function Calling 让 LLM 直接调 create_site / create_track / batch_create 等"工具"，落地到 SimpleLib
• 入口：EditTopBar 「AI 生图」按钮 → 弹对话框，参数：prompt / mode (sites/tracks/sites+tracks/full) / bounds / referenceImageBase64 / layer / constraints
• 项目保存/加载：EditTopBar「保存」/「另存为」/「加载项目」→ prompt 输入路径 → 调 mapEditApi.projectSave/Load → 服务端走 SimpleProject.ToFile / FromFile；最近路径缓存到 localStorage mapEditor.lastProjectPath

阶段 4：MapMonitor 浮动报警卡 + KPI + 实时列表（已完成）

frontends/apps/simple-platform-vue/src/views/admin/MapMonitorView.vue 改动：

• 删除原 AlarmTicker.vue 底部滚动条
• 新增 components/map-monitor/FloatingAlarmStack.vue + FloatingAlarmCard.vue，可拖动 / 可吸边 / 可堆叠
• 报警来源走 useMapEditStream.onAlarm（订阅 SSE 的 alarm 事件，由 AlarmStreamService 1s diff 推送）
• KPI 3 卡：在线车辆 / 运行中任务 / 排队任务
• 实时列表：左侧 Workspace3D + 右侧 VehicleMonitorPanel + SelectionDetailPanel
• 「定位」按钮通过 reflectionApi.setSelection('car', id) 让 Simple3 3D 高亮该车（视觉上等效 flyTo）

阶段 5：OrchestrationView 设计与编排（已完成）

views/admin/OrchestrationView.vue 5-Tab 壳：

Tab	来源
车辆	复用现有 CarPanelView
进程	复用现有 MissionEditorView
脚本	components/orchestration/ReflectionKindTable.vue（kind=script）：动态列表 + 反射 method 执行
任务流	ReflectionKindTable（kind=mission, extraFilter='taskflow'）
触发器	ReflectionKindTable（kind=mission, extraFilter='trigger'）

Tab 状态缓存到 sessionStorage。

阶段 6：联调 / 撤销栈做实 / 文档（已完成）

撤销栈做实

composables/useHistory.ts 提供 run/undo/redo/composite，每个命令 apply/revert 双向。本次把 MapEditorView 里所有占位 revert 改成真实回滚：

命令	原 revert	现 revert
runCreateSite	delete 创建的 id	（未变）
handleTrackPick 创建路径	delete 创建的 id	（未变）
deleteSelection	⚠️ 仅本地撤销	getBundle 抓快照 → batch.create 重建（id 重排）
onSetField 字段修改	⚠️ 不回滚	getBundle 抓原值 → setField 回去
applyAlignment	（已用 patch 反向恢复）	（未变）
applyBatchAsCommand	（已用 delete 反向移除）	（未变）
runAlongPathSampling（新增）	——	delete 所有采样产生的 site id
runCopyFields（新增）	——	patch 反向把 targets 字段值恢复

沿路径采样

• 后端：POST /projection/map-edit/objects/track/{id}/sample-sites { spacingMm, includeEndpoints?, layer? } —— 当前在 siteA → siteB 之间欧式直线均分（贝塞尔/弧的真实参数化采样留待后续 Track 子类 PR）
• 前端：选中 1+ 条 track，工具栏「沿路径」→ prompt 间距和端点开关 → 调后端，撤销可回退

编译相关清理

• Simple3/Recording/（之前的录制/回放实验目录）误用 Simple3.Rendering namespace、Car 找不到、Start(string, out) 默认参数顺序等 3 个错误 → 修
• Simple3/Props/UISite.cs 在 Simple3.Props namespace 下 Workspace.AddProp 被解析成 Simple3.Workspace.AddProp → 改为全限定 CycleGUI.Workspace.AddProp
• Simple3/Workspace/WorkspaceBottomBar.cs 缺 using Simple3.Workspace; → 补
• HttpClientHelper.csproj LangVersion 7.3 → latest

已知 TODO（不阻塞 v3 上线）

1. 贝塞尔/弧/Nurbs 路径的真实参数化采样（当前直线均分）
2. 撤销栈跨 Tab / 跨 session 共享（当前仅 MapEditor 视图局部）
3. Workspace3D 真正的 postMessage 'workspace.flyTo' 双向桥（当前用 setSelection 代替）
4. 复制字段 UI 支持类型化字段挑选器（当前 prompt 输入字段名）
5. AI 生图 OAuth/键持久化加密（当前明文存 config）
6. Recording 录制/回放模块未完工（PlaybackController 已修通编译，UI 已挂底栏，但实际录制/回放业务逻辑需要后续单独 PR 完成）

启动方式

# 1. 后端 build（Simple3 + MiGu.Server）
dotnet build Simple3\Simple3.csproj
dotnet build MiGu.Server\MiGu.Server.csproj

# 2. 前端打包并同步到 wwwroot
.\build-platform-frontend.bat

# 3. 启动平台 + Simple3
dotnet run --project MiGu.Server  # 监听 0.0.0.0:8080
# Simple3 端口 8222/8223 由 Simple3 自己启动

# 4. 访问
http://127.0.0.1:8080/admin/map-editor      # 地图编辑（v3 四栏壳）
http://127.0.0.1:8080/admin/map-monitor     # 地图监控（驾驶舱 + 浮动报警）
http://127.0.0.1:8080/admin/orchestration   # 设计与编排（5 Tab）