# 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
```