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 反向代理和 Simple3 子进程拉起。
- 平台前端：`frontends/apps/simple-platform-vue`，Vue 3 + Vite + Pinia + Element Plus 单页应用，单工程承载管理员端 `/admin/*` 与运营端 `/monitor/*`。

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

## 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。
- 进程编排：`Simple3Launcher` 拉起或复用 `Simple3.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 数据。

### 外部/相邻系统

- `Simple3.exe`：调度内核、地图/任务/车辆领域能力、Projection API、webVRender。
- webVRender：默认 `8223`，由前端 `Workspace3D.vue` 以 iframe 方式嵌入。
- Simple3 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<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["Simple3Launcher"]
    Launcher -->|登录后按 launchMode 拉起/复用| SL["Simple3.exe<br/>相邻仓库"]
    Server -->|YARP /api/sl/*| SLApi["Simple3 :8222"]
    Server -->|YARP /vr/*| VR["webVRender :8223"]
    Vue -->|iframe 或 /vr 代理| VR
```

关键说明：

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

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

仓库中存在两类叙述：

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

当前代码落地状态：

- 已落地：`MiGu.Server` 主入口、登录拉起 Simple3、YARP 代理、JWT/Cookie 鉴权、RBAC、配置中心 JSON 持久化、部署向导、日志管理、地图 JSON 预览、单 Vue SPA 管理/运营双域。
- 部分落地：配置中心模型、运维白名单、Simple3 反射下发、webVRender 嵌入、地图编辑/监控前端能力。
- 尚未在本仓库落地：`SimpleShared.*` 工程、EF Core 多数据库持久层、SystemMission 由 Simple3 反向守护平台、独立 `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、Simple3Launcher。
- 设置 Forwarded Headers，兼容反向代理后的 HTTPS Cookie。
- 托管静态资源和 SPA fallback。

核心关系：

- 调用 `JwtIssuer` 颁发/验签 JWT。
- 调用 `InternalTokenStore` 管理转发给 Simple3 的 `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` 拉起 Simple3，签发 JWT 和 Cookie。
- `POST /api/auth/logout`：清理 Cookie。
- `GET /api/auth/me`：让前端对本地 token 进行服务端实校。
- `POST /api/auth/switch-scope`：同一用户在 `Platform` 与 `RCSMonitor` 之间切换 scope，并由服务端重新计算权限。

依赖：

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

### 6.3 RBAC 权限模块：`Auth/`

主要文件：

- `RbacStore.cs`：RBAC 核心存储与计算。
- `RbacModels.cs`：用户、角色、DTO。
- `PageCatalog.cs`：页面权限目录。
- `JwtIssuer.cs`：JWT 颁发和验签参数。
- `InternalTokenStore.cs`：平台与 Simple3 内部通信 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 还会参与菜单裁剪与 Simple3 插件选择。

注意：

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

### 6.5 Simple3 拉起与诊断：`Launcher/`

主要文件：

- `Simple3Launcher.cs`：拉起、复用、重启、诊断、插件选择联动。
- `Simple3Options.cs`：绑定 `appsettings.json:Simple3`。
- `Simple3BuildSync.cs`：辅助同步/探测 Simple3 构建与 API。

职责：

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

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

职责：

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

默认白名单：

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

重要设计：

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

### 6.7 投影与 Simple3 代理

模块组成：

- `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/simple3`：Simple3 路径和端口诊断。
- `POST /api/health/simple3/restart-for-update`：授权用户可触发关闭 Simple3、同步最新 DLL 并重新拉起。

### 6.9 部署配置向导：`WizardController` + `DeploymentCatalog`

职责：

- 首次部署时收集导航方式、功能模块、业务场景。
- 保存后写入 `deployment` 配置 section。
- 将导航方式映射为 Simple3 场景插件 ID，并调用 `Simple3Launcher.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`

职责：

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

安全：

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

前端关系：

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

### 6.11 地图 JSON 预览：`MapsContentController`

职责：

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

关系：

- 依赖 Simple3 与 MiGu.Server 同机部署。
- 依赖 `Simple3Options.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 和 Simple3 启动模式。
- 登录成功后保存 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`：Simple3 反射对象、字段、方法执行。
- `api/mapEdit.ts`：地图编辑相关 API。
- `api/wizard.ts`：部署向导。
- `api/logs.ts`：日志管理。

关系：

- 所有平台 API 都以 `/api` 为 baseURL。
- `/api/sl/*` 由 MiGu.Server 反代给 Simple3。
- 开发环境可通过 `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`：与 Simple3 的地图编辑和反射 API 通信。

#### 地图监控

`MapMonitorView.vue` 组合：

- KPI 统计：在线车辆、运行中任务、排队任务。
- `Workspace3D`：地图画布。
- `FloatingAlarmStack`：报警浮层。
- `WorkspaceCanvasToolbar`：画布工具条。
- `VehicleMonitorPanel`：车辆监控台。
- `MissionListPanel`：任务列表。
- `MonitorSelectionPanel`：选中对象详情和动作。
- `useProjectionStream`：订阅 Simple3/平台 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。
- 选择业务场景模板。
- 预览将激活的 Simple3 场景插件，如 `scene.magnetic`、`scene.qrcode`、`scene.laser`。

保存后：

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

## 8. 数据与持久化

### 后端持久化文件

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

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

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

### Simple3 侧文件

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

- `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/*`：健康检查。

### 平台后端到 Simple3

- `/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["Simple3Launcher"]
        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 Simple3["Simple3 相邻仓库"]
        SLExe["Simple3.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 登录并启动 Simple3

1. 用户打开 `/login`。
2. 前端提交用户名、密码、scope、launchMode 到 `/api/auth/login`。
3. `AuthController` 调 `RbacStore.VerifyCredentials()` 校验密码。
4. `AuthController` 检查用户是否可使用请求的 scope。
5. `AuthController` 调 `Simple3Launcher.MaybeStart()`。
6. `Simple3Launcher` 复用或拉起 `Simple3.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` 调用 Simple3。
6. `useHistory` 记录可回滚命令，部分操作会用快照恢复。

### 11.3 运营端执行运维动作

1. 运营用户进入 `/monitor/ops` 或只读地图监控页中的动作入口。
2. 前端通过 `auth.hasOp()` 隐藏无权限操作。
3. 用户确认后调用 `/api/sl/ops/execute`。
4. `OpsController` 校验白名单、JWT 操作码、幂等键。
5. 若是备注，则只写审计；若是内核动作，读取 `Ops:Dispatch` 映射。
6. 已配置映射时调用 Simple3 反射 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，并写 Simple3 `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`
- Simple3 诊断：`http://localhost:8080/api/health/simple3`
- 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/simple3` 的真实数据。
- `ProjectionController` 是本地 Mock，占位意义大于生产意义，真实链路依赖 `/api/sl/*`。
- 运维白名单默认没有 `Ops:Dispatch` 映射，未配置前只会审计，不会真实下发内核动作。
- 多数据库、EF Core、SystemMission、独立前端包和共享组件库仍是蓝图，不应被外部交付文档表述为已完成。

## 14. 快速索引

- 后端启动：`MiGu.Server/Program.cs`
- 登录和启动 Simple3：`MiGu.Server/Controllers/AuthController.cs`
- Simple3 拉起器：`MiGu.Server/Launcher/Simple3Launcher.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`