# AimBot Web

基于 Vue 3 的机器人远程控制前端，提供自动监控、手动遥控和 PID 调参三个功能页面。

## 技术栈

| 层 | 技术 |
|----|------|
| 框架 | Vue 3.5 (Composition API, `<script setup>`) |
| 构建 | Vite 5 + pnpm |
| 路由 | Vue Router 4 (Hash 模式) |
| ROS 通信 | roslibjs → rosbridge WebSocket |
| HTTP | 原生 fetch |

## 项目结构

```
src/
├── main.js                     # 入口，挂载 App + Router
├── App.vue                     # 根布局：顶部导航 + router-view
├── config.js                   # 集中配置（地址、话题、控制参数）
├── router/index.js             # Hash 路由表
├── composables/
│   └── useRosbridge.js         # roslibjs 封装 Hook
└── views/
    ├── AutoMode.vue            # 自动模式页
    ├── ManualMode.vue          # 手动遥控页
    └── DebugMode.vue           # 调试模式页
```

## 架构分层

```
┌─────────────────────────────────────────────────────────┐
│  View 层 (views/*.vue)                                  │
│  - 页面 UI 与用户交互                                    │
│  - 调用 composable + config                             │
├─────────────────────────────────────────────────────────┤
│  Composable 层 (composables/useRosbridge.js)             │
│  - 封装 roslibjs 连接 / 发布 / 生命周期                  │
│  - 暴露响应式 connected 状态                             │
├─────────────────────────────────────────────────────────┤
│  Config 层 (config.js)                                  │
│  - 所有可配置常量集中管理                                 │
│  - 部署时只需修改此文件                                   │
├─────────────────────────────────────────────────────────┤
│  Router 层 (router/index.js)                            │
│  - Hash 路由，/auto → /manual → /debug                  │
│  - 默认重定向到 /auto                                    │
└─────────────────────────────────────────────────────────┘
```

## 路由设计

| 路径 | 页面 | 说明 |
|------|------|------|
| `#/auto` | AutoMode | 默认页，MJPEG 视频流 |
| `#/manual` | ManualMode | 键盘遥控 + 视频流 |
| `#/debug` | DebugMode | PID 参数配置 + 激光开关 |
| `#/` | → 重定向到 `#/auto` | |

选用 Hash 路由 (`createWebHashHistory`) 是为了避免部署到 Nginx 后直接访问子路径出现 404。

## 页面详解

### 1. AutoMode（自动模式）

**功能：** 显示自动运行过程的实时画面。

**数据流：**

```
web_video_server ──MJPEG──► <img src> ──► 浏览器渲染
```

**交互：**
- 「切换到当前模式」按钮 → `POST /api/mode/switch { mode: "auto" }` → ROS2 后端切换工作模式

**MJPEG 连接管理：**
- 组件挂载时 `<img>` 加载 MJPEG 流
- `onBeforeRouteLeave` 钩子中清空 `img.src`，确保离开页面时立即释放 TCP 连接
- 路由跳转顺序：旧页面断连 → 新页面建连，避免单连接服务端的冲突

### 2. ManualMode（手动模式）

**功能：** 键盘遥控机器人底盘和云台，J 键控制激光，同时观看实时画面。

**数据流：**

```
键盘事件 (keydown/keyup)
    │
    ├─► pressed Set (WASD/方向键 多键集合)
    │       │
    │       ▼
    │   computeVelocities()  ◄── config.js
    │       │
    │       ├─► { left, right } ──► /cmd_wheel    (值变化时发送)
    │       └─► { pitch, yaw  } ──► /cmd_gimbal   (值变化时发送)
    │                                      │
    │                                      ▼
    │                                 rosbridge ──► ROS2 节点
    │
    └─► J 键 (!e.repeat)
            │
            ▼
        POST /api/laser { action: "on"|"off" } ──► ROS2 HTTP 服务
```

**键盘映射策略：**

```
         W (+线速度)               ↑ (+pitch 度/秒)
    A (+角速度)  D (-角速度)   ← (+yaw 度/秒) → (-yaw 度/秒)
         S (-线速度)               ↓ (-pitch 度/秒)

        底盘 (差速驱动)              云台 (角度速率)
         J 激光 开/关
```

- **多键同时按下**：W+A 同时按 = 前进 + 左转，自动合成左右轮速
- **同轴冲突**：W+S 同时按 → 相互抵消，线速度为 0
- **值变化才发布**：比较当前速度与上次发布值，无变化则跳过，避免无效 rosbridge 消息
- **自动启停**：首个按键按下启动 `requestAnimationFrame` 循环，所有按键松开启自动停止（publish 值不变的帧直接跳过）
- **J 键防重复**：`e.repeat` 过滤，长按 J 不会反复切换激光

**差速运动学转换：**

```
left_speed  = linear - angular × (wheel_separation / 2)
right_speed = linear + angular × (wheel_separation / 2)
```

### 3. DebugMode（调试模式）

**功能：** PID 参数在线调参，激光开关，模式切换。

**交互：**
- 顶部三个按钮可切换任意模式
- **激光开关按钮**：「激光: ON/OFF」点击切换，`POST /api/laser { action: "on"|"off" }`
- 12 个数字输入框分 4 组：
  - 视觉环 Yaw 电机：Kp / Ki / Kd
  - 视觉环 Pitch 电机：Kp / Ki / Kd
  - 角度环 Yaw 电机：Kp / Ki / Kd
  - 角度环 Pitch 电机：Kp / Ki / Kd
- 「发布参数」按钮 → rosbridge 发布 JSON 到 `/pid_config` 话题

**发布数据格式：**

```json
{
  "visual_yaw":   { "kp": 1.0, "ki": 0.1, "kd": 0.01 },
  "visual_pitch": { "kp": 1.0, "ki": 0.1, "kd": 0.01 },
  "angle_yaw":    { "kp": 2.0, "ki": 0.2, "kd": 0.02 },
  "angle_pitch":  { "kp": 2.0, "ki": 0.2, "kd": 0.02 }
}
```

## useRosbridge — 核心 Composable

```
useRosbridge()
│
├─ connect(url)      → 建立 WebSocket，绑定 connection/close/error 事件
├─ disconnect()      → 手动断开
├─ publish(topic, type, data) → 发布消息（自动缓存 Topic 对象）
├─ connected (ref)   → 响应式连接状态
│
└─ onUnmounted()     → 组件销毁时自动断开
```

- 每次调用 `useRosbridge()` 创建独立的 ros 实例
- Topic 对象按 `"topic:messageType"` 缓存，避免重复创建
- 组件卸载 (`onUnmounted`) 自动关闭 WebSocket，无需手动清理

## config.js — 配置项说明

```js
HTTP_API_BASE        // HTTP API 基础地址
ROSBRIDGE_URL        // rosbridge WebSocket，格式 ws://host:9090
MJPEG_AUTO_URL       // 自动模式 MJPEG 流地址
MJPEG_MANUAL_URL     // 手动模式 MJPEG 流地址
CMD_WHEEL_TOPIC      // 底盘轮速话题名
CMD_GIMBAL_TOPIC     // 云台角速度话题名
PID_CONFIG_TOPIC     // PID 参数话题名
MAX_LINEAR           // 最大线速度 (m/s)
MAX_ANGULAR          // 最大角速度 (rad/s)
WHEEL_SEPARATION     // 底盘轮距 (m)
GIMBAL_PITCH_DEG_S   // 云台 pitch 角度速率 (度/秒)
GIMBAL_YAW_DEG_S     // 云台 yaw 角度速率 (度/秒)
```

## HTTP API 接口一览

| 接口 | 方法 | 请求体 | 说明 | 触发位置 |
|------|------|--------|------|----------|
| `/api/mode/switch` | POST | `{"mode": "auto"\|"manual"\|"debug"}` | 切换工作模式 | Auto/Manual/Debug 页面按钮 |
| `/api/laser` | POST | `{"action": "on"\|"off"}` | 激光开关 | Manual J 键, Debug 按钮 |

## 通信架构总览

```
┌─────────────────────────────────────────────────────────┐
│                  Vue3 前端                               │
│                                                          │
│  AutoMode.vue ────► fetch POST /api/mode/switch          │
│               ────► <img src="/stream?topic=...">         │
│  ManualMode.vue ─► roslibjs ws://host:9090               │
│                ──► <img src="/stream?topic=...">          │
│                ──► fetch POST /api/laser (J 键)           │
│  DebugMode.vue ──► roslibjs ws://host:9090               │
│               ───► fetch POST /api/mode/switch            │
│               ───► fetch POST /api/laser (按钮)           │
└──────────┬──────────────┬───────────────────────────────┘
           │ HTTP         │ WebSocket + MJPEG
           ▼              ▼
      ┌─────────┐   ┌──────────────┐
      │  Nginx  │   │  rosbridge   │
      │  反代    │   │  web_video   │
      └────┬────┘   │  _server     │
           │        └──────┬───────┘
           ▼               ▼
      ROS2 HTTP        ROS2 话题
      模式切换          底盘 / 云台 / PID
      激光开关
```

## 开发命令

```bash
pnpm install      # 安装依赖
pnpm dev          # 开发服务器 → http://localhost:5173
pnpm build        # 生产构建 → dist/
pnpm preview      # 预览构建产物
```