# 迷毂 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. 顶层目录职责
```text
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`：
```mermaid
flowchart LR
User["浏览器用户"] --> Vue["simple-platform-vue
/login /admin /monitor"]
Vue -->|/api/*| Server["MiGu.Server :8080"]
Server --> Auth["Auth/RBAC/JWT"]
Server --> Config["ConfigStore
data/config-*.json"]
Server --> Wizard["部署向导
deployment profile"]
Server --> Launcher["SimpleLiteLauncher"]
Launcher -->|登录后按 launchMode 拉起/复用| SL["SimpleLite.exe
相邻仓库"]
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. 模块间依赖关系
```mermaid
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. 构建与运行
### 后端
```powershell
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`
### 前端开发
```powershell
cd frontends
pnpm install
pnpm dev
```
默认访问：
- `http://localhost:5173/login`
- Vite 将 `/api` 代理到 `http://127.0.0.1:8080`。
### 前端构建并同步后端静态资源
```powershell
.\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`