Migu2.0/frontends/README.md

# 迷毂 · 前端 (frontends/)

> 产品代号 **迷毂**（Mí Gǔ），全称「迷毂 · 智能调度平台」。
> 单一 Vue 工程 `simple-platform-vue` 承载 admin（管理员 / Platform）与 monitor（运营 / RCSMonitor）双视图；
> 通过路由前缀 `/admin/*` 与 `/monitor/*` 切换，后续可按 ARCHITECTURE.md §13 拆分为独立工程。
>
> 落地范围与依据：本目录是 [ARCHITECTURE.md](../ARCHITECTURE.md) v1.7 §6/§9/§13/§17/§18 中前端形态的初版骨架；
> 真实业务接入由 `Platform.Server`（同仓库新增的 .NET 8 工程）反代 Simple3 完成。
>
> 品牌主色：默认 **工业紫** `#6a1b9a`（6 套主题可切换），详见 ARCHITECTURE.md §17.7。
> 工程包名 `simple-platform-vue` / 仓库目录 `frontends/apps/simple-platform-vue` 保持不动，避免破坏 pnpm/CI 脚本，仅用户可见文案统一为「迷毂」。

## 目录结构

```
frontends/
├── package.json               # workspace 根
├── pnpm-workspace.yaml        # pnpm monorepo 占位（当前只有一个 app）
└── apps/
    └── simple-platform-vue/
        ├── package.json
        ├── vite.config.ts     # base=/  ；dev 时 /api 代理到 http://127.0.0.1:8080
        ├── index.html
        ├── env.d.ts
        ├── .env.development
        ├── public/
        │   ├── favicon.svg                  # 紫色渐变方块 + 「迷」字
        │   └── login-bg.jpg                 # 登录页背景图 (1.8MB，来源 C:\Tool\wallpapper\wall_Beach.jpg)
        └── src/
            ├── main.ts                      # Pinia + applyCurrentTheme() + Element Plus
            ├── App.vue
            ├── styles/
            │   ├── theme.css                # --mg-* 玻璃令牌 + Element Plus 覆盖
            │   └── themes.ts                # 6 套主题预设 + applyThemeVars()
            ├── router/index.ts              # /login /status /admin/* /monitor/* (title base="迷毂")
            ├── stores/ {auth, config, ui}.ts
            ├── api/    {http, auth, config, projection, ops}.ts
            ├── layouts/{AppShell, BlankLayout}.vue   # 紫色渐变侧边栏 / 紫色三段渐变背景
            ├── components/
            │   ├── Workspace3D.vue         # ★ iframe 包 http://localhost:8223
            │   ├── ThemeSwitcher.vue       # 顶栏主题下拉（§17.7）
            │   ├── ScopeSwitcher.vue
            │   ├── PermissionGuard.vue
            │   ├── DataTablePro.vue
            │   └── ConfigPageBase.vue
            ├── views/
            │   ├── LoginView.vue
            │   ├── ServiceStatusView.vue   # 复刻 §3.4 状态窗
            │   ├── admin/
            │   │   ├── DashboardView.vue
            │   │   ├── MapMonitorView.vue  # ★ 地图监控页（iframe 8223 + 实时车辆侧栏）
            │   │   ├── MapEditorView.vue / TrackTableView.vue
            │   │   ├── CarPanelView.vue   / MissionEditorView.vue
            │   │   ├── CadToolbarView.vue / PlaybackView.vue
            │   │   └── config/             # 14 个配置中心页（§9）
            │   └── monitor/
            │       ├── MonitorDashboardView.vue
            │       ├── MonitorMapView.vue  # ★ 只读 iframe 8223 + 运维白名单
            │       ├── OpsActionPanelView.vue
            │       └── AnnotationView.vue
            ├── types/  {auth, map, car, mission, ops, config}.ts
            └── mock/   {server.ts, data/*.ts}
```

## 启动

```pwsh
# 1) 安装依赖（首次）
cd frontends
pnpm install

# 2) 启动 Vite 开发服务器（默认 :5173）
pnpm dev

# 3) 打开浏览器
#    http://localhost:5173/login
#    任意非空用户名 + 任意密码即可登录（鉴权全为 Mock）
#    scope=Platform → /admin/map-monitor （★ 地图监控页）
#    scope=RCSMonitor → /monitor/map      （★ 只读地图监控页）
```

## 地图监控页与 webVRender

地图监控页（`/admin/map-monitor` 与 `/monitor/map`）通过 `<Workspace3D>` 组件以 iframe 嵌入
Simple3 WebTerminal 提供的 webVRender，默认 URL：

```
http://localhost:8223/?scope=Platform&token=<jwt>&ro=0    # 管理员，可交互
http://localhost:8223/?scope=RCSMonitor&token=<jwt>&ro=1  # 运营，只读
```

可通过 `.env.development` 中的 `VITE_VRENDER_HOST` 覆盖默认主机，或直接给组件传 `host` 属性。

### iframe 嵌入注意事项（CORS / X-Frame-Options）

- 当前 Simple3 WebTerminal 暂未声明 `X-Frame-Options`/`Content-Security-Policy: frame-ancestors`，
  浏览器多数情况下会按默认策略放行同源 / 局域网嵌入。
- 若浏览器控制台报「Refused to display 'http://localhost:8223/' in a frame」，请在 Simple3 WebTerminal
  侧加上 `X-Frame-Options: ALLOWALL` 或 `Content-Security-Policy: frame-ancestors *`（本轮代码未改动 Simple3）。
- 若需通过 `Platform.Server` 走同源代理，可以让 iframe 指向 `http://localhost:8080/vr/`，由 YARP
  转发到 `http://127.0.0.1:8223/`（见 `Platform.Server/appsettings.json` 的 `vrender-route`）。

## 与后端联调

- Vite dev 模式下，所有 `/api/*` 请求经 Vite proxy 转到 `http://127.0.0.1:8080`，由 `Platform.Server` 处理：
  - `/api/auth/login` → `Platform.Server` `AuthController`（Mock JWT）
  - `/api/config/{section}` → `Platform.Server` `ConfigController`（14 维度占位）
  - `/api/health` → `Platform.Server` `HealthController`
  - `/api/projection/*` → `Platform.Server` `ProjectionController`（占位）
  - `/api/sl/*` → YARP 反代 Simple3 WebAPI `http://127.0.0.1:8222/`
  - `/api/sl/ops/execute` 与 `/api/sl/ops/audits` → `Platform.Server` `OpsController`（白名单网关占位）

### Mock 开关：`VITE_USE_MOCK`

`api/auth.ts`、`api/config.ts`、`api/ops.ts` 读取 `import.meta.env.VITE_USE_MOCK`：

| 环境          | 文件                | 默认值 | 行为                                              |
|---------------|---------------------|--------|---------------------------------------------------|
| dev (`pnpm dev`) | `.env.development` | `true`  | 走 `mock/server.ts`，**无后端也能跑通 UI**           |
| prod (`pnpm build`) | `.env.production` | `false` | 强制打到 Platform.Server，没启后端会失败（这是期望行为）|

要在 dev 环境联调真实后端，把 `.env.development` 里的 `VITE_USE_MOCK` 注释掉或改为 `false` 即可。
不要再像旧版那样改源码里的 `const MOCK = true` —— 那条常量已经下线，统一由 env 控制。

> 其他 `api/*.ts`（如 `reflection.ts`、`projection.ts`、`workbench.ts`）从一开始就直连真实 API，
> 不受 `VITE_USE_MOCK` 影响；它们后端必到位才能用。

## 生产构建

```pwsh
# 在 frontends 目录
pnpm --filter simple-platform-vue build   # 产出 apps/simple-platform-vue/dist/

# 部署到 Platform.Server (一次拷贝，单一合并工程)
# Windows / PowerShell
Remove-Item ..\Platform.Server\wwwroot\* -Recurse -Force -ErrorAction SilentlyContinue
Copy-Item apps\simple-platform-vue\dist\* ..\Platform.Server\wwwroot\ -Recurse
```

部署完成后访问 `http://localhost:8080/login`、`/admin/dashboard`、`/admin/map-monitor`、`/monitor/map`，所有非 API 路径都会回退到 `wwwroot/index.html`，由 vue-router 内部解析。

> 已通过冒烟验证：`pnpm build` 通过 vue-tsc 严格类型检查 + Vite 生产构建（2412 模块、44 chunk），`Platform.Server` 启动后 `/`、`/admin/map-monitor`、`/monitor/map`、`/api/health`、`/api/config/system` 与 `/assets/index-*.js` 均返回 200。

## 品牌与主题（v1.6.1 对齐 FRLD / ddms）

- 产品名「**迷毂**」全局可见文案：登录窗标题/副标题、`<title>`、侧边栏顶部、favicon。
- 母公司 logo：`public/FRLD-logo-white.png`（11.5 KB 展开态）+ `public/FRLD-logo-white-no_title.png`（3.5 KB 折叠态）。来源 `E:\ddms\frontend\public`，与法睿兰达 FAIRYLAND 运营管理引擎（FAME / ddms）共用同一品牌资产。
- 中英双标题：中文 `迷 毂 · 智能调度平台`、英文 `Mi Gu · Intelligent Dispatch Platform`（首字母加粗）。
- 品牌主色 `#7c3aed`（Tailwind violet-600）：通过 `src/styles/theme.css` 覆盖 Element Plus 的 `--el-color-primary` 与 `--el-color-primary-rgb`（双重 `:root` + `html !important` 兜底）。配套 `--mg-primary-{50..950}` 阶梯、`--mg-accent #a855f7`、`--mg-bg-aside-{1,2}` 侧栏深紫渐变。
- 登录卡：单列 460px，背景 `linear-gradient(135deg, #2d1b69 0%, #7c3aed 100%)`（ddms 同款），透明输入 + 白底紫字大按钮 + 双卡 scope 选择器。
- 侧边栏顶端 logo 块：FRLD logo 38px + 中英双标题居中（折叠时变 28px logo + 「迷毂」缩写）。
- 完整视觉规范与色卡见 [`../ARCHITECTURE.md` §17](../ARCHITECTURE.md#17-视觉规范v16-新增v161-对齐-frld)。

## 相关文档

- [../ARCHITECTURE.md](../ARCHITECTURE.md) — v1.6 总体架构（§3 启动登录、§5 三端职责、§6 共享内核、§9 配置中心、§10 关键交互、§17 视觉规范）
- [../Platform.Server/README.md](../Platform.Server/README.md) — 后端骨架启动说明