lixiaolong
6aaed4dacc
- 统一使用 VO 对象替代零散参数，提升接口一致性 - 新增多个 AGV 相关 VO 类，包括地图、导航、速度控制等场景 - 为所有 POST 接口添加 @RequestBody 注解明确请求体映射 - 优化 protobuf 对象到 Map 的转换逻辑，添加辅助方法 - 在所有查询接口中启用参数验证注解 @Validated - 为紧急停止和故障清除等操作改为 POST 方法增强安全性 - 更新 README.md 添加项目架构说明与开发约定 - 调整 ARM 控制器参数传递方式与验证机制
250 lines
6.8 KiB
Markdown
250 lines
6.8 KiB
Markdown
# cmvr-iot
|
||
|
||
cmvr-iot 是一个基于 Java 8 和 Spring Boot 2.5 的多模块后端工程，提供设备管理、边缘机器人控制、测试编排、巡检、TTS、AIMA、VI/TI 等业务能力。工程入口在 `cmvr-iot-admin`，其余模块按业务和基础能力拆分。
|
||
|
||
## 技术栈
|
||
|
||
- Java 8
|
||
- Spring Boot 2.5.15
|
||
- Spring Security
|
||
- MyBatis Plus / MyBatis Plus Join
|
||
- MySQL / Redis
|
||
- Druid
|
||
- Quartz
|
||
- Knife4j / Swagger
|
||
- gRPC Java 1.58.0
|
||
- Protobuf / protoc-maven-plugin
|
||
- MinIO
|
||
|
||
## 模块说明
|
||
|
||
| 模块 | 说明 |
|
||
| --- | --- |
|
||
| `cmvr-iot-admin` | Web 启动模块，包含 REST Controller、启动类和运行配置 |
|
||
| `cmvr-iot-framework` | Web、安全、配置、通用框架能力 |
|
||
| `cmvr-iot-common` | 公共工具、通用响应、基础常量和通用能力 |
|
||
| `cmvr-iot-system` | 系统管理、用户、角色、菜单、字典等基础业务 |
|
||
| `cmvr-iot-quartz` | 定时任务模块 |
|
||
| `cmvr-iot-generator` | 代码生成模块 |
|
||
| `cmvr-iot-device` | 设备领域模型与设备相关能力 |
|
||
| `cmvr-iot-test` | 测试任务、编排、执行实例等业务 |
|
||
| `cmvr-iot-vi` | VI 相关业务 |
|
||
| `cmvr-iot-ti` | TI 相关业务 |
|
||
| `cmvr-iot-evaluation` | 评测相关业务 |
|
||
| `cmvr-iot-inspection` | 巡检机器人、地图、任务、告警等业务 |
|
||
| `cmvr-iot-aima` | AIMA 相关业务 |
|
||
| `cmvr-iot-tts` | TTS 语音合成相关业务 |
|
||
| `cmvr-iot-api` | API 聚合模块 |
|
||
| `cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-lib` | gRPC proto 与生成代码模块 |
|
||
| `cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-client` | 边缘设备 gRPC 客户端、设备控制服务和请求 VO |
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
cmvr-iot
|
||
├── cmvr-iot-admin # Spring Boot 启动模块
|
||
├── cmvr-iot-common # 公共模块
|
||
├── cmvr-iot-framework # 框架模块
|
||
├── cmvr-iot-system # 系统管理模块
|
||
├── cmvr-iot-device # 设备模块
|
||
├── cmvr-iot-test # 测试业务模块
|
||
├── cmvr-iot-api
|
||
│ └── cmvr-iot-edge
|
||
│ ├── cmvr-iot-grpc-lib # proto 与 gRPC 生成代码
|
||
│ └── cmvr-iot-grpc-client # gRPC 客户端与边缘控制服务
|
||
├── sql # 增量 SQL
|
||
├── Dockerfile
|
||
├── Jenkinsfile
|
||
└── pom.xml # Maven 父工程
|
||
```
|
||
|
||
## 环境要求
|
||
|
||
- JDK 1.8
|
||
- Maven 3.6+
|
||
- MySQL 5.7+/8.x
|
||
- Redis
|
||
- 可访问的 gRPC 机器人/边缘终端服务
|
||
- 可选：MinIO、外部大模型/TTS/评测服务
|
||
|
||
注意：`application-*.yml` 中包含环境相关地址、账号和密钥配置。实际部署或本地开发时，应使用本机配置、环境变量或配置中心覆盖，不要直接复用生产/测试环境敏感配置。
|
||
|
||
## 配置文件
|
||
|
||
主配置文件位于：
|
||
|
||
```text
|
||
cmvr-iot-admin/src/main/resources/application.yml
|
||
```
|
||
|
||
环境配置文件位于：
|
||
|
||
```text
|
||
cmvr-iot-admin/src/main/resources/application-dev.yml
|
||
cmvr-iot-admin/src/main/resources/application-test.yml
|
||
cmvr-iot-admin/src/main/resources/application-prod.yml
|
||
```
|
||
|
||
当前 `application.yml` 默认激活：
|
||
|
||
```yaml
|
||
spring:
|
||
profiles:
|
||
active: test
|
||
```
|
||
|
||
如需切换环境，可以修改 `spring.profiles.active`，或启动时指定：
|
||
|
||
```bash
|
||
java -jar cmvr-iot-admin-dev.jar --spring.profiles.active=dev
|
||
```
|
||
|
||
## 构建
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
mvn clean package -DskipTests
|
||
```
|
||
|
||
只编译启动模块及其依赖：
|
||
|
||
```bash
|
||
mvn -pl cmvr-iot-admin -am compile -DskipTests
|
||
```
|
||
|
||
只重新生成并编译 gRPC 代码：
|
||
|
||
```bash
|
||
mvn -pl cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-lib -am compile -DskipTests
|
||
```
|
||
|
||
## 启动
|
||
|
||
启动类：
|
||
|
||
```text
|
||
cmvr-iot-admin/src/main/java/com/cmvr/CmvrIotApplication.java
|
||
```
|
||
|
||
IDE 中直接运行 `CmvrIotApplication` 即可。
|
||
|
||
打包后运行：
|
||
|
||
```bash
|
||
java -jar cmvr-iot-admin/target/cmvr-iot-admin-dev.jar --spring.profiles.active=dev
|
||
```
|
||
|
||
默认开发端口以当前 profile 配置为准，例如 `application-dev.yml` 中为：
|
||
|
||
```yaml
|
||
server:
|
||
port: 13080
|
||
```
|
||
|
||
## 接口文档
|
||
|
||
项目集成 Knife4j / Swagger。服务启动后可访问：
|
||
|
||
```text
|
||
http://localhost:13080/doc.html
|
||
```
|
||
|
||
如果端口或上下文路径被 profile 覆盖，请以实际配置为准。
|
||
|
||
## 数据库脚本
|
||
|
||
增量脚本位于：
|
||
|
||
```text
|
||
sql/
|
||
```
|
||
|
||
当前包含：
|
||
|
||
- `aima_module.sql`
|
||
- `inspection_module.sql`
|
||
- `tts_corpus_module.sql`
|
||
|
||
初始化数据库时，需要结合目标环境的基础库结构和增量脚本执行。
|
||
|
||
## gRPC 与边缘设备
|
||
|
||
边缘设备相关代码集中在：
|
||
|
||
```text
|
||
cmvr-iot-api/cmvr-iot-edge/
|
||
```
|
||
|
||
proto 文件位于：
|
||
|
||
```text
|
||
cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-lib/src/main/proto/
|
||
```
|
||
|
||
gRPC 客户端服务位于：
|
||
|
||
```text
|
||
cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-client/src/main/java/com/cmvr/edge/client/
|
||
```
|
||
|
||
边缘控制器位于：
|
||
|
||
```text
|
||
cmvr-iot-admin/src/main/java/com/cmvr/web/controller/api/
|
||
```
|
||
|
||
新增或修改 proto 后，执行 Maven compile 会触发 `protoc-maven-plugin` 生成 Java 和 gRPC Stub 代码。业务代码应复用现有 gRPC 客户端管理工具获取 Stub，避免在业务层重复创建底层 `ManagedChannel`。
|
||
|
||
## 实时语音对讲
|
||
|
||
当前实时语音对讲链路为：
|
||
|
||
```text
|
||
浏览器 WebSocket Binary PCM <-> Java 后端 <-> gRPC 双向流 <-> 机器人终端
|
||
```
|
||
|
||
约定音频格式：
|
||
|
||
- PCM_S16LE
|
||
- 48000 Hz
|
||
- 单声道
|
||
- 16 bit
|
||
- 10 ms 一帧
|
||
- 960 bytes/帧
|
||
|
||
相关文件：
|
||
|
||
- WebSocket 控制器：`cmvr-iot-admin/src/main/java/com/cmvr/web/controller/api/WebRtcSignalingController.java`
|
||
- 业务会话管理：`cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-client/src/main/java/com/cmvr/edge/client/service/AudioService.java`
|
||
- gRPC 音频适配：`cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-client/src/main/java/com/cmvr/edge/client/adapter/RobotAudioGrpcAdapter.java`
|
||
- proto：`cmvr-iot-api/cmvr-iot-edge/cmvr-iot-grpc-lib/src/main/proto/cmvr/api/robot_audio.proto`
|
||
|
||
说明：历史 WebRTC 相关类可能仍保留在源码中，但当前浏览器音频传输链路使用 WebSocket 二进制 PCM。
|
||
|
||
## 开发约定
|
||
|
||
- Controller 层只做参数接收、基础校验和响应封装。
|
||
- POST 控制类接口优先使用单个 `@RequestBody VO` 承载完整请求参数。
|
||
- GET 查询类接口可以使用 query 参数绑定 VO。
|
||
- 不建议在同一个接口中同时声明通用 VO 和零散业务参数。
|
||
- gRPC 调用统一通过现有客户端管理类获取 Stub。
|
||
- proto 修改后必须重新编译并确认生成代码已更新。
|
||
- 不要提交本地日志、崩溃 dump、临时音频文件和包含真实密钥的配置。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 编译全部模块
|
||
mvn clean compile -DskipTests
|
||
|
||
# 编译启动模块及依赖
|
||
mvn -pl cmvr-iot-admin -am compile -DskipTests
|
||
|
||
# 打包
|
||
mvn clean package -DskipTests
|
||
|
||
# 运行指定 profile
|
||
java -jar cmvr-iot-admin/target/cmvr-iot-admin-dev.jar --spring.profiles.active=dev
|
||
```
|