Migu2.0/Doc/PROJECT_MODULES_AND_RELATIONSHIPS.md

迷毂 2.0 项目模块与关系说明

本文基于当前仓库代码、README 与架构文档整理。结论以本仓库实际实现为主；ARCHITECTURE.md 中包含较多中长期蓝图，若与代码存在差异，本文会单独标注。

1. 项目定位

MIGU2.0 是“迷毂 · 智能调度平台”的平台仓库，主要包含两部分：

• 平台后端：MiGu.Server，ASP.NET Core 8 WebAPI，监听默认 8080，负责登录、权限、配置中心、静态前端托管、YARP 反向代理和 SimpleLite 子进程拉起。
• 平台前端：frontends/apps/simple-platform-vue，Vue 3 + Vite + Pinia + Element Plus 单页应用，单工程承载管理员端 /admin/* 与运营端 /monitor/*。

调度内核 SimpleLite 不在本仓库内，按 README 描述位于相邻仓库 ../Simple/SimpleLite。当前仓库通过进程拉起、HTTP 代理、webVRender iframe 和本地文件读取等方式与 SimpleLite 协作。

2. 技术栈总览

后端

• 运行时：.NET 8 / ASP.NET Core Web API。
• API 文档：Swagger，仅开发环境启用。
• 鉴权：JWT Bearer + httpOnly Cookie 双轨。
• 授权：ASP.NET Core Authorization Policy + 自研 RBAC。
• 代理：YARP Reverse Proxy。
• 持久化：当前为 JSON 文件持久化，主要落在 MiGu.Server/data/；长期蓝图中计划接入 EF Core 多数据库 Provider。
• 进程编排：SimpleLiteLauncher 拉起或复用 SimpleLite.exe。

前端

• 框架：Vue 3.5、Vite 5、TypeScript。
• 状态：Pinia。
• UI：Element Plus、@element-plus/icons-vue。
• 图表/编排：ECharts、Vue Flow。
• HTTP：Axios，统一通过 /api baseURL 调用平台后端。
• 开发 Mock：VITE_USE_MOCK=true 时部分 API 使用前端 mock 数据。

外部/相邻系统

• SimpleLite.exe：调度内核、地图/任务/车辆领域能力、Projection API、webVRender。
• webVRender：默认 8223，由前端 Workspace3D.vue 以 iframe 方式嵌入。
• SimpleLite Projection/Web API：默认 8222，通过 /api/sl/* 由 YARP 转发。

3. 顶层目录职责

MIGU2.0/
├── MiGu.Server/                         平台后端工程
├── MiGu.Server.sln                      后端解决方案
├── frontends/                           前端 pnpm workspace
│   └── apps/simple-platform-vue/        单 SPA：管理员端 + 运营端
├── Doc/                                 代码审查、问题清单与本文档
├── ARCHITECTURE.md                      总体架构蓝图，含大量规划内容
├── PLATFORM_V3_CHANGES.md               v3 平台化实际改动记录
├── README.md                            仓库定位与启动说明
└── build-platform-frontend.bat          前端构建并同步到 MiGu.Server/wwwroot

4. 当前实现的总体运行关系

当前代码中的主入口是 MiGu.Server：

flowchart LR
    User["浏览器用户"] --> Vue["simple-platform-vue<br/>/login /admin /monitor"]
    Vue -->|/api/*| Server["MiGu.Server :8080"]
    Server --> Auth["Auth/RBAC/JWT"]
    Server --> Config["ConfigStore<br/>data/config-*.json"]
    Server --> Wizard["部署向导<br/>deployment profile"]
    Server --> Launcher["SimpleLiteLauncher"]
    Launcher -->|登录后按 launchMode 拉起/复用| SL["SimpleLite.exe<br/>相邻仓库"]
    Server -->|YARP /api/sl/*| SLApi["SimpleLite :8222"]
    Server -->|YARP /vr/*| VR["webVRender :8223"]
    Vue -->|iframe 或 /vr 代理| VR

关键说明：

• MiGu.Server 负责托管 SPA、处理登录与配置、代理 /api/sl/* 到 SimpleLite。
• 用户登录时可选择 DesktopAndWeb 或 WebOnly，后端转换为 SimpleLite 命令行 --display-mode=web+local 或 --display-mode=web。
• SimpleLiteLauncher 默认 FollowParent=false，即 MiGu.Server 退出不会杀掉已启动的 SimpleLite。
• 如果 8222 已经有 SimpleLite 在运行，后端会做 TCP + HTTP 探测并复用既有实例，避免重复拉起。
• 前端的 3D/地图画布主要通过 Workspace3D.vue 加载 http://localhost:8223 或经 /vr 同源代理。

5. 文档蓝图与当前代码的差异

仓库中存在两类叙述：

• README.md 和 MiGu.Server/README.md 已经描述“用户先启动 MiGu.Server，登录后拉起 SimpleLite”这一当前实现。
• ARCHITECTURE.md 仍保留较多早期蓝图，例如“SimpleLite 通过 SystemMission 拉起 MiGu.Server”“双 SPA 独立托管”“SimpleShared.* 多工程”“EF Core 多 Provider”等。

当前代码落地状态：

• 已落地：MiGu.Server 主入口、登录拉起 SimpleLite、YARP 代理、JWT/Cookie 鉴权、RBAC、配置中心 JSON 持久化、部署向导、日志管理、地图 JSON 预览、单 Vue SPA 管理/运营双域。
• 部分落地：配置中心模型、运维白名单、SimpleLite 反射下发、webVRender 嵌入、地图编辑/监控前端能力。
• 尚未在本仓库落地：SimpleShared.* 工程、EF Core 多数据库持久层、SystemMission 由 SimpleLite 反向守护平台、独立 platform-vue/rcsmonitor-vue 双工程、packages/sl-controls 共享组件库。

6. 后端模块

6.1 启动与基础设施：MiGu.Server/Program.cs

职责：

• 修正 ContentRootPath：直接运行 bin/Debug/net8.0/MiGu.Server.exe 时向上寻找 MiGu.Server.csproj，确保配置、data、wwwroot 路径一致。
• 默认监听：未配置 urls 时使用 http://0.0.0.0:8080。
• WebRoot 自动探测：优先使用 frontends/apps/simple-platform-vue/dist/index.html，其次 MiGu.Server/wwwroot/index.html。
• 注册 Controller、Swagger、CORS、JWT Bearer、Authorization Policy、YARP、ConfigStore、OpsAuditStore、HttpClient、SimpleLiteLauncher。
• 设置 Forwarded Headers，兼容反向代理后的 HTTPS Cookie。
• 托管静态资源和 SPA fallback。

核心关系：

• 调用 JwtIssuer 颁发/验签 JWT。
• 调用 InternalTokenStore 管理转发给 SimpleLite 的 X-Platform-Internal-Token。
• YARP sl-route 会自动注入内部 token。
• app.MapControllers() 处理平台自身 API，app.MapReverseProxy() 处理 /api/sl/* 与 /vr/*。

6.2 鉴权与会话：AuthController

职责：

• POST /api/auth/login：校验用户名密码与 scope，按登录请求 launchMode 拉起 SimpleLite，签发 JWT 和 Cookie。
• POST /api/auth/logout：清理 Cookie。
• GET /api/auth/me：让前端对本地 token 进行服务端实校。
• POST /api/auth/switch-scope：同一用户在 Platform 与 RCSMonitor 之间切换 scope，并由服务端重新计算权限。

依赖：

• RbacStore：用户密码校验、scope 判断、有效权限计算。
• JwtIssuer：签发 JWT。
• SimpleLiteLauncher：登录后拉起或复用 SimpleLite。
• ConfigStore：读取部署画像，决定是否需要进入配置向导。

6.3 RBAC 权限模块：Auth/

主要文件：

• RbacStore.cs：RBAC 核心存储与计算。
• RbacModels.cs：用户、角色、DTO。
• PageCatalog.cs：页面权限目录。
• JwtIssuer.cs：JWT 颁发和验签参数。
• InternalTokenStore.cs：平台与 SimpleLite 内部通信 token。

职责：

• 首次启动生成默认账号 admin 和 ops，并写入 data/rbac.json。
• 密码使用 PBKDF2-SHA256，带 salt，固定时间比较。
• 角色模型包含 scope、页面、操作码、控件可见性。
• 有效权限 = 当前 scope 下适用角色的页面、操作码、控件授权并集。
• 防止删除/停用最后一个具备管理权限的账号。

对外 API：

• RbacController 挂载 /api/rbac。
• 通过 RbacAdmin 策略保护，JWT 的 ops claim 需包含 * 或 auth.manage。
• 支持角色与用户 CRUD、密码修改、权限目录查询。

6.4 配置中心：Configs/ + ConfigController

ConfigStore 当前是“内存 + JSON 文件”的配置中心，覆盖以下 section：

• system：系统级配置。
• integrations：外部系统对接。
• routing：路径规划策略。
• vehicle：车辆维护策略。
• charge：充电策略。
• task：任务分配机制。
• traffic：交通管制规则。
• auth：权限与角色配置模型。
• device：设备管理。
• fleet：车队生命周期。
• scenario：场景模板。
• location：库位管理。
• ops：运营维护配置。
• widget：自定义控件。
• deployment：部署画像/配置向导结果。

ConfigController：

• GET /api/config：列出所有 section 的版本与更新时间。
• GET /api/config/{section}：读取某个配置。
• PUT /api/config/{section}：保存配置并增加版本。

关系：

• 前端 useConfigStore 统一读写这些 section。
• 许多配置页只是不同 section 的编辑视图。
• deployment section 还会参与菜单裁剪与 SimpleLite 插件选择。

注意：

• 控制器类加了 [Authorize]，但当前 PUT 也是普通 [Authorize]，注释中曾提到 PlatformScope，实际代码没有强制仅平台 scope 可写。
• 当前 JSON 文件属于占位持久层；长期架构文档计划迁移到 EF Core。

6.5 SimpleLite 拉起与诊断：Launcher/

主要文件：

• SimpleLiteLauncher.cs：拉起、复用、重启、诊断、插件选择联动。
• SimpleLiteOptions.cs：绑定 appsettings.json:SimpleLite。
• SimpleLiteBuildSync.cs：辅助同步/探测 SimpleLite 构建与 API。

职责：

• 将业务启动模式翻译为 SimpleLite 内部 display mode：
  • WebOnly -> --display-mode=web
  • DesktopAndWeb -> --display-mode=web+local
• 拉起前检查 8222 是否已有 SimpleLite，并用 /projection/cars 确认不是其他进程占用端口。
• 查找 SimpleLite.exe：优先配置路径，再尝试相邻仓库、发布包同目录等候选路径。
• 默认 Windows 下通过 cmd /c start 脱离父进程，避免关闭平台后端时带走 SimpleLite。
• FollowParent=true 时使用 Windows JobObject 绑定父子进程。
• 写入 plugins/active-scenes.json，把部署向导选出的导航场景传给 SimpleLite。
• GET /api/health/simplelite 返回配置、路径解析、端口、版本 API 可用性等诊断信息。

6.6 运维白名单与审计：OpsController + OpsAuditStore

职责：

• 对运营端发起的运维动作做白名单校验。
• 二次校验 JWT 的 ops claim。
• 支持 IdempotencyKey，避免重复点击/重试重复下发。
• monitor.note.write 仅写审计。
• 其他运维动作需要在 appsettings.json:Ops:Dispatch 显式配置 opCode -> "kind:Method" 后，才会转发到 SimpleLite 反射 API。
• 审计记录由 OpsAuditStore 落盘，重启后不丢。

默认白名单：

• 车辆：暂停、恢复、回库、重置会话、手动充电。
• 任务：暂停、取消、重派、提升优先级。
• 运营备注：写备注。

重要设计：

• 未配置映射时不会“假成功”，而是返回 ok=false 并说明“已记录审计但未下发”。
• 真实下发路径为 SimpleLite 反射执行接口：/projection/reflection/execute/{kind}/{id}/{method}。

6.7 投影与 SimpleLite 代理

模块组成：

• ProjectionController：平台本地 mock 投影接口，提供 sites/tracks/cars/missions 示例数据。
• YARP /api/sl/{**catch-all}：真实链路转发到 http://127.0.0.1:8222/。
• 前端 api/projection.ts：优先调用 /api/sl/projection/*，车辆和任务在失败或空列表时回退到反射对象列表。

关系：

• 管理端和运营端的地图监控、车辆面板、任务列表都依赖投影数据。
• /api/projection/* 更偏本地开发 mock；真实联调主要走 /api/sl/projection/*。

6.8 健康检查：HealthController

职责：

• GET /api/health：平台后端健康检查，返回启动时间、运行时长、端口规划。
• GET /api/health/simplelite：SimpleLite 路径和端口诊断。
• POST /api/health/simplelite/restart-for-update：授权用户可触发关闭 SimpleLite、同步最新 DLL 并重新拉起。

6.9 部署配置向导：WizardController + DeploymentCatalog

职责：

• 首次部署时收集导航方式、功能模块、业务场景。
• 保存后写入 deployment 配置 section。
• 将导航方式映射为 SimpleLite 场景插件 ID，并调用 SimpleLiteLauncher.WriteActiveScenes() 写入 plugins/active-scenes.json。
• 按部署画像裁剪页面，例如当前 wms 模块会点亮 admin-config-location。

对外 API：

• GET /api/wizard/options：选项目录。
• GET /api/wizard/profile：当前部署画像。
• GET /api/wizard/effective-pages：菜单裁剪结果。
• PUT /api/wizard/profile：保存画像。
• POST /api/wizard/reset：重新进入向导。

6.10 日志管理：LogsController

职责：

• 读取 SimpleLite 工作目录下的 log/ 文件。
• 支持概览、文件列表、目录浏览、日志条目分页、合订本、日志分析、原文查看、下载。
• 日志行按 Diagnosis.Log 的格式解析，支持标签聚合和数值字段识别。

安全：

• 仅 PlatformScope 可访问，因为日志可能包含路径、状态和内部运行信息。
• 对文件路径做安全解析，防止 ../ 目录穿越。

前端关系：

• 由 LogManagementView 挂在“运维与回放”配置聚合页下。

6.11 地图 JSON 预览：MapsContentController

职责：

• 先调用 SimpleLite /projection/map-edit/maps 获取地图目录。
• 再在本机读取对应地图 JSON 原文，供平台地图管理右侧预览。
• 对地图名做非法字符检查，并校验最终路径必须落在地图目录下。

关系：

• 依赖 SimpleLite 与 MiGu.Server 同机部署。
• 依赖 SimpleLiteOptions.ProjectionPort 和 InternalTokenStore。

7. 前端模块

7.1 应用入口与路由

主要文件：

• src/main.ts：创建 Vue 应用、Pinia、Element Plus，恢复主题。
• src/router/index.ts：定义 /login、/status、/wizard、/admin/*、/monitor/*。
• src/layouts/AppShell.vue：登录后的管理/运营统一壳层。
• src/layouts/BlankLayout.vue：登录、状态、向导等空白布局。

路由守卫做四件事：

• 未登录跳转 /login。
• 进入受保护路由前调用 auth.validate()，用 /api/auth/me 实校 token。
• 若 needsWizard=true，强制进入 /wizard。
• 根据路径自动切换 scope，并按 allowedPages 做页面级权限控制。

7.2 登录与会话状态

主要文件：

• views/LoginView.vue
• stores/auth.ts
• api/auth.ts
• types/auth.ts

职责：

• 登录页采集用户名、密码、scope 和 SimpleLite 启动模式。
• 登录成功后保存 token、用户、scope、runMode、effectivePermissions 到 Pinia 与 localStorage。
• auth.validate() 通过 /api/auth/me 处理服务端重启、JWT secret 重生导致的旧 token 失效问题。
• switchScope() 不在客户端伪造权限，而是请求后端重新签发 token 和权限。

注意：

• 登录页提示“任意非空用户名 + 任意密码即可登录”来自历史 Mock 文案；真实 API 模式下后端已校验 data/rbac.json 中的密码。

7.3 统一 HTTP 与 API 层

主要文件：

• api/http.ts：Axios 实例、baseURL、Cookie 与 Bearer 双轨、错误翻译、401 清理。
• api/auth.ts：登录、登出、me、scope 切换。
• api/config.ts：配置中心读写。
• api/projection.ts：站点、路径、车辆、任务投影。
• api/ops.ts：运维白名单执行和审计。
• api/reflection.ts：SimpleLite 反射对象、字段、方法执行。
• api/mapEdit.ts：地图编辑相关 API。
• api/wizard.ts：部署向导。
• api/logs.ts：日志管理。

关系：

• 所有平台 API 都以 /api 为 baseURL。
• /api/sl/* 由 MiGu.Server 反代给 SimpleLite。
• 开发环境可通过 VITE_USE_MOCK=true 使用前端 mock，但反射、工作台等部分 API 仍要求真实后端。

7.4 Shell、主题和权限控制组件

主要文件：

• layouts/AppShell.vue：侧边栏、顶栏、菜单、用户区、runMode 标签、scope 切换。
• components/ScopeSwitcher.vue：scope 切换入口。
• components/PermissionGuard.vue：按操作码或控件授权控制视图。
• components/ThemeSwitcher.vue：主题下拉。
• components/ThemeCustomizer.vue：主题自定义。
• stores/ui.ts、styles/themes.ts、styles/theme.css：主题、侧边栏折叠和样式变量。

关系：

• AppShell 中菜单的 key 与后端 PageCatalog、前端路由 route.name 对齐。
• auth.hasPage() 决定菜单项是否显示。
• auth.hasOp() 和 auth.widgetOf() 决定按钮、控件、面板的可见性与可交互程度。

7.5 3D 工作区：Workspace3D.vue

职责：

• 构造 webVRender iframe URL：http://{host}/?scope=...&token=...&ro=...。
• 支持 embedUi 和 canvasOnly 两种嵌入模式。
• 在纯画布/嵌入模式下尽力调用 /declareCanvasOnly 或 /declareEmbedUi。
• 监听 iframe postMessage，向 Vue 页面转发 pick、select、shortcut 事件。
• 提供重载和全屏能力。

关系：

• MapEditorView 使用 canvasOnly=true，所有编辑 UI 由 Vue 接管。
• MapMonitorView 使用 canvasOnly=true，叠加报警卡和车辆/任务工作台。
• 运营端 MonitorMapView 复用 MapMonitorView read-only。

7.6 管理端页面：/admin/*

主要页面：

• DashboardView.vue：管理员总览。
• MapMonitorView.vue：地图监控、车辆/任务工作台、浮动报警、选中信息。
• MapManagementView.vue：地图管理与地图 JSON 预览。
• MapEditorView.vue：地图编辑器。
• TrackTableView.vue：场景/路径管理。
• CarPanelView.vue：车辆管理。
• ProcessPanelView.vue：进程管理。
• ScriptPanelView.vue：脚本管理。
• TaskTemplateView.vue：任务编排。
• ProjectPropertiesView.vue：项目属性。

地图编辑器

MapEditorView.vue 是前端较重的模块，组合了：

• EditTopBar：项目/文件/编辑/视图/图层/对齐吸附等命令。
• EditToolRail：CAD/地图编辑工具按钮。
• EditPropertyPanel：对象字段、类型默认、图层、视口样式。
• EditStatusBar：选中数、鼠标坐标、工具、撤销栈状态。
• AiGenerateDialog 和 AiAssistantPanel：AI 生图/助手。
• Workspace3D：纯画布 iframe。
• useHistory：撤销/重做命令栈。
• useSelection：对象选择状态。
• useAlignment、useBatchGenerate、useClipboard：编辑辅助能力。
• mapEditApi、reflectionApi：与 SimpleLite 的地图编辑和反射 API 通信。

地图监控

MapMonitorView.vue 组合：

• KPI 统计：在线车辆、运行中任务、排队任务。
• Workspace3D：地图画布。
• FloatingAlarmStack：报警浮层。
• WorkspaceCanvasToolbar：画布工具条。
• VehicleMonitorPanel：车辆监控台。
• MissionListPanel：任务列表。
• MonitorSelectionPanel：选中对象详情和动作。
• useProjectionStream：订阅 SimpleLite/平台 SSE 事件。

7.7 运营端页面：/monitor/*

主要页面：

• MonitorDashboardView.vue：运营总览。
• VehicleHubView.vue：车辆运维，管理端和运营端共用。
• MonitorMapView.vue：只读地图监控，复用 MapMonitorView read-only。
• OpsActionPanelView.vue：运维白名单操作。
• AnnotationView.vue：运营备注。

设计关系：

• 运营端不是独立后端，仍使用 MiGu.Server。
• 运营端 scope 为 RCSMonitor，由后端 RBAC 返回受限页面和操作码。
• 前端只隐藏无权限按钮；真正的安全边界在后端 OpsController 和 YARP/Controller 授权。

7.8 配置中心聚合页

当前前端将十多个配置页面收敛为 6 个聚合入口：

• StrategyConfigView.vue：路径规划、任务分配、交通管制、充电策略。
• VehicleHubView.vue：运维总览、维护策略、车队生命周期。
• FacilityConfigView.vue：设备接入、库位管理。
• BusinessConfigView.vue：外部系统对接、场景模板、自定义控件。
• OpsCenterView.vue：调度回放、运营维护、日志管理、地图监控配置。
• SystemCenterView.vue：系统级配置、权限与角色。

旧路径通过路由 redirect 到这些聚合页的对应 tab，降低深链接迁移成本。

7.9 部署配置向导

WizardView.vue 用于首次登录后的部署选型：

• 选择导航方式：磁导航、二维码导航、激光导航。
• 选择功能模块：当前包含 WMS、PTL。
• 选择业务场景模板。
• 预览将激活的 SimpleLite 场景插件，如 scene.magnetic、scene.qrcode、scene.laser。

保存后：

• 调用 PUT /api/wizard/profile。
• 后端写入 deployment section。
• 后端写入 SimpleLite plugins/active-scenes.json。
• 前端调用 auth.markWizardDone()，跳转到对应首页。

8. 数据与持久化

后端持久化文件

当前主要文件都在 MiGu.Server/data/：

• rbac.json：用户、角色、密码哈希、页面/操作/控件权限。
• config-{section}.json：配置中心各 section。
• 运维审计文件：由 OpsAuditStore 管理。
• .internal-token：内部 token 可能由 InternalTokenStore 生成或读取。

这些文件采用 JSON 持久化，部分写入走 AtomicFile，损坏时会备份后回退默认值。

SimpleLite 侧文件

MiGu.Server 会直接或间接使用 SimpleLite 工作目录：

• plugins/active-scenes.json：部署向导写入，控制内核场景插件选择。
• log/**/*.log：日志管理模块读取并分析。
• 地图目录中的 *.json：地图管理预览读取。

9. 关键接口关系

浏览器到平台后端

• /api/auth/*：登录、退出、身份实校、scope 切换。
• /api/config/*：配置中心。
• /api/rbac/*：权限与角色管理。
• /api/wizard/*：部署向导。
• /api/logs/*：日志管理。
• /api/maps/{name}/content：地图 JSON 预览。
• /api/health/*：健康检查。

平台后端到 SimpleLite

• /api/sl/* -> YARP -> http://127.0.0.1:8222/*。
• /vr/* -> YARP -> http://127.0.0.1:8223/*。
• OpsController 直接调用 http://127.0.0.1:{ProjectionPort}/projection/reflection/execute/...。
• MapsContentController 直接调用 http://127.0.0.1:{ProjectionPort}/projection/map-edit/maps。

前端到 webVRender

• 默认 iframe 直连：http://localhost:8223/?scope=...&token=...&ro=...。
• 可选同源代理：http://localhost:8080/vr/?scope=...。

10. 模块间依赖关系

flowchart TB
    subgraph Backend["MiGu.Server"]
        Program["Program.cs"]
        Auth["AuthController"]
        RBAC["RbacStore / JwtIssuer"]
        Config["ConfigStore"]
        Wizard["WizardController"]
        Launcher["SimpleLiteLauncher"]
        Ops["OpsController"]
        Logs["LogsController"]
        Maps["MapsContentController"]
        YARP["YARP ReverseProxy"]
    end

    subgraph Frontend["simple-platform-vue"]
        Router["router/index.ts"]
        AuthStore["stores/auth.ts"]
        ConfigStoreVue["stores/config.ts"]
        Shell["AppShell.vue"]
        Workspace["Workspace3D.vue"]
        Admin["admin views"]
        Monitor["monitor views"]
        WizardVue["WizardView.vue"]
    end

    subgraph SimpleLite["SimpleLite 相邻仓库"]
        SLExe["SimpleLite.exe"]
        Projection["Projection API :8222"]
        VRender["webVRender :8223"]
        LogsFile["log/**/*.log"]
        Plugins["plugins/active-scenes.json"]
        MapsDir["maps/*.json"]
    end

    Router --> AuthStore
    AuthStore --> Auth
    ConfigStoreVue --> Config
    Shell --> AuthStore
    Admin --> Workspace
    Monitor --> Workspace
    Workspace --> VRender
    WizardVue --> Wizard

    Program --> Auth
    Program --> RBAC
    Program --> Config
    Program --> Launcher
    Program --> YARP
    Auth --> RBAC
    Auth --> Launcher
    Auth --> Config
    Wizard --> Config
    Wizard --> Launcher
    Launcher --> SLExe
    Launcher --> Plugins
    Ops --> Projection
    Maps --> Projection
    Maps --> MapsDir
    Logs --> LogsFile
    YARP --> Projection
    YARP --> VRender

11. 典型业务链路

11.1 登录并启动 SimpleLite

1. 用户打开 /login。
2. 前端提交用户名、密码、scope、launchMode 到 /api/auth/login。
3. AuthController 调 RbacStore.VerifyCredentials() 校验密码。
4. AuthController 检查用户是否可使用请求的 scope。
5. AuthController 调 SimpleLiteLauncher.MaybeStart()。
6. SimpleLiteLauncher 复用或拉起 SimpleLite.exe。
7. 后端计算有效权限，签发 JWT，写 httpOnly Cookie。
8. 前端保存登录态，并按 needsWizard 跳转 /wizard 或业务首页。

11.2 管理员打开地图编辑器

1. 路由进入 /admin/map-editor。
2. 守卫确保 scope 为 Platform，并检查 admin-map-editor 页面权限。
3. MapEditorView 加载 Workspace3D，以 canvasOnly=true 打开 8223 webVRender。
4. Vue 侧顶栏、工具栏、属性面板接管编辑 UI。
5. 创建、删除、批量生成、字段修改等操作通过 mapEditApi 或 reflectionApi 调用 SimpleLite。
6. useHistory 记录可回滚命令，部分操作会用快照恢复。

11.3 运营端执行运维动作

1. 运营用户进入 /monitor/ops 或只读地图监控页中的动作入口。
2. 前端通过 auth.hasOp() 隐藏无权限操作。
3. 用户确认后调用 /api/sl/ops/execute。
4. OpsController 校验白名单、JWT 操作码、幂等键。
5. 若是备注，则只写审计；若是内核动作，读取 Ops:Dispatch 映射。
6. 已配置映射时调用 SimpleLite 反射 execute；未配置映射时返回未下发。
7. 审计落盘，前端显示执行结果。

11.4 首次部署配置向导

1. 登录或 /api/auth/me 返回 needsWizard=true。
2. 路由守卫强制进入 /wizard。
3. 前端加载 /api/wizard/options 和 /api/wizard/profile。
4. 用户选择导航方式、模块、场景。
5. 保存后端写 deployment section。
6. 后端将导航方式转换为场景插件 ID，并写 SimpleLite plugins/active-scenes.json。
7. 后续登录时，AuthController.BuildSession() 会按部署画像裁剪可见页面。

12. 构建与运行

后端

cd MiGu.Server
dotnet build MiGu.Server.csproj -c Debug
dotnet run

默认访问：

• 平台：http://localhost:8080/login
• 健康检查：http://localhost:8080/api/health
• SimpleLite 诊断：http://localhost:8080/api/health/simplelite
• Swagger：开发环境 /swagger

前端开发

cd frontends
pnpm install
pnpm dev

默认访问：

• http://localhost:5173/login
• Vite 将 /api 代理到 http://127.0.0.1:8080。

前端构建并同步后端静态资源

.\build-platform-frontend.bat

脚本会：

1. 检查或安装依赖。
2. 执行 pnpm --filter simple-platform-vue build。
3. 用 robocopy /MIR 同步 dist 到 MiGu.Server/wwwroot。
4. 默认启动 MiGu.Server/build-and-run.bat，可加 --no-start 禁止启动。

13. 风险与待完善点

• 架构文档与当前实现存在历史差异，后续应更新 ARCHITECTURE.md 中关于启动归属、双 SPA 拆分、共享组件库和持久层状态的描述。
• ConfigController.Put 当前只要求登录，未按注释限制 PlatformScope，如果运营 scope 可调用配置写入，需要确认是否符合预期。
• 前端登录页仍有 Mock 文案，真实 API 模式下会误导用户。
• ServiceStatusView.vue 目前展示大量 Mock 状态，尚未接入 /api/health 与 /api/health/simplelite 的真实数据。
• ProjectionController 是本地 Mock，占位意义大于生产意义，真实链路依赖 /api/sl/*。
• 运维白名单默认没有 Ops:Dispatch 映射，未配置前只会审计，不会真实下发内核动作。
• 多数据库、EF Core、SystemMission、独立前端包和共享组件库仍是蓝图，不应被外部交付文档表述为已完成。

14. 快速索引

• 后端启动：MiGu.Server/Program.cs
• 登录和启动 SimpleLite：MiGu.Server/Controllers/AuthController.cs
• SimpleLite 拉起器：MiGu.Server/Launcher/SimpleLiteLauncher.cs
• 配置中心：MiGu.Server/Configs/ConfigStore.cs
• 权限中心：MiGu.Server/Auth/RbacStore.cs
• 权限 API：MiGu.Server/Controllers/RbacController.cs
• 运维 API：MiGu.Server/Controllers/OpsController.cs
• 部署向导 API：MiGu.Server/Controllers/WizardController.cs
• 日志 API：MiGu.Server/Controllers/LogsController.cs
• 前端路由：frontends/apps/simple-platform-vue/src/router/index.ts
• 前端会话状态：frontends/apps/simple-platform-vue/src/stores/auth.ts
• 前端配置状态：frontends/apps/simple-platform-vue/src/stores/config.ts
• 前端 3D iframe：frontends/apps/simple-platform-vue/src/components/Workspace3D.vue
• 管理端地图编辑：frontends/apps/simple-platform-vue/src/views/admin/MapEditorView.vue
• 管理端地图监控：frontends/apps/simple-platform-vue/src/views/admin/MapMonitorView.vue
• 运营端地图监控：frontends/apps/simple-platform-vue/src/views/monitor/MonitorMapView.vue
• 配置向导：frontends/apps/simple-platform-vue/src/views/WizardView.vue