# its-frontend

**Repository Path**: yimeng812/its-frontend

## Basic Information

- **Project Name**: its-frontend
- **Description**: 基于 Vue 3 + CesiumJS 的 3D 智能交通仿真前端，搭配 后端服务 使用。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-22
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ITS Frontend — 3D 智能交通仿真系统（前端）

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)

基于 Vue 3 + CesiumJS 的 3D 智能交通仿真前端，搭配 [后端服务](https://gitee.com/yimeng812/its-backend) 使用。

## 技术栈

| 类别 | 技术 |
|------|------|
| 框架 | Vue 3（组合式 API） |
| 状态管理 | Pinia |
| 3D 地球 | CesiumJS 1.143 |
| 3D 模型 | Three.js 0.185 |
| 构建 | Vite 6 |
| 语言 | TypeScript 5.7 |
| 测试 | Vitest 4 + Vue Test Utils |
| MVT 解析 | @mapbox/vector-tile + pbf |

## 目录结构

```
src/
├── api/              # 后端 API 调用
│   ├── config.ts       # 后端配置（天地图 Token 等）
│   ├── valhalla.ts     # Valhalla 路线/等时线/路网匹配
│   ├── vehicle.ts      # 车辆 WebSocket 通信
│   └── cheluyunting.ts # 车路云听事件上报
├── cesium/           # CesiumJS 地图层
│   ├── viewer.ts       # Viewer 初始化与配置
│   ├── imagery.ts      # 天地图底图（矢量/影像切换）
│   ├── tile-network.ts # Valhalla MVT 路网瓦片渲染
│   ├── valhalla-mvt-layer.ts # 自定义 MVT ImageryProvider
│   └── coord.ts        # 坐标转换工具
├── three/            # Three.js 3D 叠加层
│   ├── vehicle-model.ts # 车辆 GLB 模型加载与渲染
│   └── overlay-bind.ts  # Three↔Cesium 坐标同步绑定
├── components/       # UI 组件
│   ├── map/            # 地图画布
│   ├── layout/         # 顶栏、状态栏
│   ├── panels/         # 侧面板（车辆创建/目的地/控制/事故/在线车辆等）
│   ├── CoordLocator.vue   # 坐标定位工具
│   └── EventReportModal.vue # 事件上报弹窗
├── composables/      # 组合式函数
│   ├── useVehicleMove.ts # 车辆沿路径行驶动画
│   ├── useVehicleWs.ts   # 车辆 WebSocket 连接管理
│   ├── useMapPick.ts     # 地图点击拾取
│   └── useFps.ts         # 帧率监控
├── stores/           # Pinia 状态
│   ├── vehicle.ts      # 车辆注册表、activeId、路径
│   ├── simulation.ts   # 仿真全局状态（速度、运行控制）
│   └── ui.ts           # UI 状态（面板开关、主题）
├── config/           # 常量配置
├── data/             # 静态数据（车辆模型列表）
├── types/            # TypeScript 类型声明
└── styles/           # CSS 主题与布局
```

## 核心功能

- **3D 地图** — 天地图底图（矢量/影像切换）+ Valhalla MVT 路网叠加
- **多车仿真** — 车辆注册表 + activeId 切换，单 RAF 循环驱动多车动画
- **路径规划** — 调用 Valhalla /route，3D 渲染路线 + 起点/终点标记
- **实时通信** — WebSocket 上报定位 + MQTT 下行事件转发
- **事故检测** — 距离阈值检测，半径圆/等时线覆盖范围可切换
- **车辆控制** — 开始/暂停/停止，全局速度档位调节
- **坐标定位** — 经纬度→行政区划查询
- **事件上报** — 交通事件上报至车路云听平台

## 运行

```bash
# 安装依赖
npm install

# 开发（默认 http://localhost:5173，局域网可访问）
npm run dev

# 构建
npm run build

# 测试
npm run test
```

### 环境变量

复制 `.env.example` 为 `.env`，按需修改：

```bash
# 后端基地址（天地图 Token、Valhalla 路由均经后端代理）
VITE_API_BASE=http://localhost:8080

# 局域网访问时改为后端机器 IP
# VITE_API_BASE=http://192.168.1.5:8080
```

### 外部依赖

- **后端服务** — 默认 `http://localhost:8080`，需先启动 [its-backend](https://gitee.com/yimeng812/its-backend)
- **Valhalla** — 路网引擎，经后端代理访问，无需前端直连
- **天地图** — Token 由后端下发，无需前端配置

## 与后端的关系

```
前端 (npm run dev :5173)
  │
  ├─ HTTP ─▶ 后端 /api/v1/map/token        → 天地图 Token
  ├─ HTTP ─▶ 后端 /api/v1/valhalla/*       → Valhalla 路网代理
  ├─ HTTP ─▶ 后端 /api/v1/event/*          → 车路云听事件上报
  ├─ HTTP ─▶ 后端 /api/v1/map/location     → 行政区划查询
  └─ WS   ─▶ 后端 /websocket/client/{id}   → 车辆实时双向通道
```
## 许可证

本项目基于 [GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl-3.0) 开源。详见 [LICENSE](LICENSE) 文件。

本项目采用双重许可模式：AGPL-3.0（开源）+ 商业许可。贡献者需签署 [贡献者许可协议（CLA）](CLA.md)，授权项目维护者将其贡献同时用于商业许可版本。