CMVR-IOT/README.md

# CMVR IoT 物联网平台

CMVR IoT 是招商车研机器人及智能设备管理平台。本项目以 RuoYi-Vue 3.9.2 为基础升级到 Spring Boot 4，保留原有 REST、前端和 gRPC 对外接口，并将 QUIC Gateway 集成到主应用进程中。

Java 包名、Maven 坐标统一使用 `com.cmvr`。旧项目 `cmvr-iot` 仅作为迁移来源，不参与本项目构建。

## 主要功能

- 系统管理：用户、角色、部门、菜单、字典、参数、日志和通知。
- 机器人设备：以边缘端上报的永久 `robotId` 作为唯一业务身份，自动同步机器人地址、在线状态和设备清单。
- 测试业务：任务配置、任务编排、任务实例、检测项、语音唤醒、Flowise 和 AI 评估。
- 智能巡检：机器人、地图、点位、任务、执行实例、巡检结果和告警。
- 智能座舱：语音交互、触控交互、TTS、语料库和车机操作配置。
- 专项业务：爱玛电动车测试、评价指标库和大模型服务。
- 边缘控制：通过 gRPC 调用 AGV、相机、机械臂、灵巧手、机器人头部、麦克风和扬声器。
- QUIC 接入：节点注册、心跳、设备快照、媒体 DATAGRAM 和 gRPC 地址同步。
- 平台能力：Quartz 定时任务、代码生成、WebSocket、MinIO 文件服务和 Knife4j 接口文档。

## 技术栈

| 组件 | 版本或实现 |
| --- | --- |
| Java | 17 |
| Spring Boot | 4.0.6 |
| Spring Security | JWT 认证 |
| MyBatis | MyBatis-Plus 3.5.17、MPJ 1.5.9 |
| 数据库 | MySQL |
| 缓存 | Redis |
| RPC | gRPC 1.58.0、Protobuf 3.25.5 |
| QUIC | Netty QUIC 4.2.16.Final |
| API 文档 | Springdoc 3.0.3、Knife4j 4.5.0 |
| 前端 | Vue 3.4、Element Plus 2.9、Vite 5.3 |

## 工程结构

| 模块 | 说明 |
| --- | --- |
| `cmvr-iot-admin` | Spring Boot 启动入口、REST 控制器和运行配置 |
| `cmvr-iot-framework` | 安全、Web、MyBatis、WebSocket 等框架配置 |
| `cmvr-iot-common` | 公共模型、注解、异常和工具类 |
| `cmvr-iot-system` | 用户、角色、菜单、字典、参数和通用分组 |
| `cmvr-iot-quartz` | Quartz 任务调度和任务日志 |
| `cmvr-iot-generator` | 代码生成 |
| `cmvr-iot-device` | 设备协议模型、机器人配置和巡检告警监听 |
| `cmvr-iot-test` | 测试任务、流程、检测项和执行实例 |
| `cmvr-iot-vi` | 语音交互业务 |
| `cmvr-iot-ti` | 触控交互业务 |
| `cmvr-iot-evaluation` | 评价指标业务 |
| `cmvr-iot-inspection` | 智能巡检业务 |
| `cmvr-iot-aima` | 爱玛电动车专项业务 |
| `cmvr-iot-tts` | TTS 任务和车载语料 |
| `cmvr-iot-api` | 边缘服务和大模型 API 聚合模块 |
| `cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-lib` | 原有 gRPC 协议及生成代码 |
| `cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-client` | 原有机器人 gRPC 客户端 |
| `cmvr-iot-quic-contract` | QUIC 控制、节点事件和媒体数据协议 |
| `cmvr-iot-quic` | 与主应用同进程运行的 QUIC Gateway |
| `cmvr-iot-ui-lxl-dev-worktree` | Vue 3 管理控制台（同级独立前端仓库） |

## 环境准备

- JDK 17
- Maven 3.6.3 或更高版本
- MySQL 5.7/8.0
- Redis
- Node.js 18/20 LTS 和 pnpm 9
- MinIO，仅使用文件、语料或媒体存储功能时需要

默认激活 `test` profile，后端端口为 `13080`。运行前检查以下配置：

- `cmvr-iot-admin/src/main/resources/application-test.yml`：MySQL、Redis、MinIO、gRPC 和第三方服务。
- `cmvr-iot-admin/src/main/resources/application.yml`：上传目录、JWT、MyBatis、Knife4j 和 QUIC。
- 不要把生产密码、访问密钥或 TLS 私钥提交到仓库。

## 数据库初始化

新数据库以 `sql/ry_20260417.sql` 为基础脚本。按实际启用模块检查并执行以下补充脚本：

- `sql/quartz.sql`：Quartz 表结构。
- `sql/aima_module.sql`：爱玛业务。
- `sql/inspection_module.sql`、`inspection_result.sql`、`inspection_detection_alert.sql`：巡检业务。
- `sql/tts_corpus_module.sql`：TTS 和语料业务。
- `sql/robot_quic_identity_migration.sql`：机器人 QUIC 身份、运行状态和设备快照表。
- `sql/robot_id_only_migration.sql`：移除巡检机器人和任务实例中的历史终端 ID 字段。

补充脚本可能面向不同历史库版本。已有数据库升级前应先备份，并确认字段或索引尚未存在。

## 后端运行

在项目根目录执行：

```bash
mvn clean package -DskipTests
java -jar cmvr-iot-admin/target/cmvr-iot-admin.jar
```

也可以在 IDEA 中直接运行：

```text
com.cmvr.CmvrIotApplication
```

DevTools 自动重启已关闭。修改代码后需要完整停止并重新启动应用，避免 MPJ 保留已经关闭的 Spring 上下文。

常用地址：

- 后端 API：`http://localhost:13080`
- Knife4j 文档：`http://localhost:13080/doc.html`
- OpenAPI JSON：`http://localhost:13080/v3/api-docs/00-all`

Knife4j 只展示带原有 `@ApiOperation` 注解的正式接口，并沿用中文 `@Api(tags=...)` 业务分类。

## 前端运行

```bash
cd ../cmvr-iot-ui-lxl-dev-worktree
pnpm install
pnpm dev
```

默认开发端口为 `80`。`.env.development` 中的 `VITE_API_URL` 必须与后端地址一致；本项目后端默认是 `http://localhost:13080`。更多说明见 [ruoyi-ui/README.md](ruoyi-ui/README.md)。

## gRPC 与 QUIC

原有机器人 gRPC 客户端与 proto 均保留，但业务调用只传永久 `robotId`。平台根据 `inspection_robot.robot_id` 查找 QUIC 最近同步的 `ip_address` 和 `port`，不再使用终端 ID 或终端配置解析 gRPC 地址。

边缘端通过 QUIC 上报设备快照后，平台按 `robotId + deviceId` 写入 `inspection_robot_device`。前端选择机器人后只展示该机器人当前在线且启用的设备；单一匹配设备会自动选中并锁定。

QUIC 不是独立服务，`cmvr-iot-quic` 已作为 `cmvr-iot-admin` 的运行时依赖。启用时主应用同时启动：

- QUIC：默认 `0.0.0.0:4433/udp`
- 节点和媒体事件：通过 Spring 单例 `NodeEventBroker` 在进程内直接分发，不占用内部端口

设置 `cmvr.quic.enabled=true` 前必须配置有效的 TLS 证书和私钥，否则应用会拒绝启动。详细配置见 [cmvr-iot-quic/README.md](cmvr-iot-quic/README.md)。

## 构建与验证

```bash
# 运行测试
mvn test

# 构建全部后端模块
mvn clean package -DskipTests

# 构建前端生产包
cd ../cmvr-iot-ui-lxl-dev-worktree
pnpm build:prod
```

Windows 下也可以使用 `bin/package.bat`、`bin/run.bat` 和 `bin/clean.bat`。

## 排查提示

- `ApplicationContext ... has been closed already`：彻底停止旧 Java 进程后重新启动，不要使用 DevTools 热重启。
- 找不到机器人或机器人离线：确认机器人表已登记相同的永久 `robotId`，并检查 QUIC 注册日志、`inspection_robot` 的地址和连接状态。
- QUIC 启动失败：检查证书、私钥、ALPN、UDP 端口占用和 native library 对应的操作系统架构。
- 数据库提示缺少字段：确认基础脚本版本及对应模块迁移脚本已经执行。