引入WMS仓储主数据与关系管理全流程能力

后端实现基于EF Core的库区/库位/容器/物料/关系/历史等模型、服务与RESTful接口，支持多数据库Provider。前端新增类型、API与聚合页面，支持主数据及容器位置/物料关系的增删改查、绑定/解绑、装料/卸料、历史追溯。完善权限、菜单与文档，平台具备完整WMS能力。
2026-06-22 09:15:42 +08:00
parent e9847f581c
commit f2ef32a22b
33 changed files with 2979 additions and 0 deletions
@@ -0,0 +1,705 @@
+# 迷毂 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<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. 模块间依赖关系
+
+```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`