黄兆尉andCursor
3686abdc78
配置段/环境变量、Launcher、健康检查 API、OpenAPI 与前后端文案同步；兼容探测旧 SimpleLite 进程名。 Co-authored-by: Cursor <cursoragent@cursor.com>
158 lines
9.3 KiB
Markdown
158 lines
9.3 KiB
Markdown
# 迷毂 · 前端 (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) — 后端骨架启动说明
|