# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

WVP-PRO 是一个基于 GB28181-2016 标准的开箱即用网络视频平台。负责实现核心信令与设备管理后台，支持 NAT 穿透，支持海康、大华、宇视等品牌的 IPC、NVR 接入。集成 ZLMediaKit 流媒体服务器。

**生产部署信息：**
- **容器名称：** `vsp-wvp`（后端）、`vsp-frontend`（前端）、`vsp-zlmedia`（流媒体）
- **端口映射：**
  - 后端：18080:18080
  - SIP: 8116:8116 (TCP/UDP)
  - 前端：8088:80
- **部署位置：** 腾讯云服务器 `/opt/vsp-platform`
- **存储：** 腾讯云 MySQL + 腾讯云 Redis
- **访问地址：**
  - WVP 后端：http://服务器IP:18080
  - WVP 前端：http://服务器IP:8088
  - API 文档：http://服务器IP:18080/doc.html

## 常用命令

### 本地开发

```bash
# 编译后端（需要 Maven 3.3+ 和 Java 17）
mvn clean package -DskipTests

# 或使用 Windows 批处理脚本
编译.bat

# 运行后端
mvn spring-boot:run
启动.bat

# 编译前端（Vue 2）
cd web
npm install
npm run dev              # 开发服务器
npm run build:prod       # 生产构建
```

### Docker 部署（生产环境）

```bash
# 构建后端镜像
docker build -t vsp-wvp:latest .

# 运行后端容器
docker run -d \
  --name vsp-wvp \
  -p 18080:18080 \
  -p 8116:8116 \
  -p 8116:8116/udp \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e MYSQL_HOST=腾讯云MySQL地址 \
  -e REDIS_HOST=腾讯云Redis地址 \
  vsp-wvp:latest

# 构建前端镜像
cd web
docker build -t vsp-frontend:latest .

# 运行前端容器
docker run -d \
  --name vsp-frontend \
  -p 8088:80 \
  vsp-frontend:latest

# 查看日志
docker logs -f vsp-wvp
docker logs -f vsp-frontend

# 重启容器
docker restart vsp-wvp
docker restart vsp-frontend

# 进入容器调试
docker exec -it vsp-wvp /bin/bash
```

### 基础服务（本地开发）

```bash
cd docker
docker compose up -d polaris-redis polaris-mysql polaris-media
docker compose down
docker compose logs -f polaris-media
```

## 架构概览

### 核心模块（src/main/java/com/genersoft/iot/vmp/）

- **gb28181/** — GB28181 协议实现
  - `transmit/` — SIP 信令传输层
  - `service/` — 设备管理、播放服务、PTZ 控制
  - `bean/` — GB28181 实体类

- **jt1078/** — JT1078 协议支持（部标808/1078）

- **media/** — ZLMediaKit 集成
  - 流媒体代理、录像管理
  - RTSP/RTMP/HLS/FLV 输出

- **aiot/** — AIoT 功能模块
  - `controller/` — AI 配置、ROI 管理、告警接口
  - `service/` — 配置推送、截图服务
  - `dao/` — ai_camera、ai_roi、ai_roi_algo_bind 数据访问

- **vmanager/** — REST API 控制器
  - 设备管理、通道查询、云台控制等

- **web/** — Vue 2 前端（独立目录）

### 配置文件

- `src/main/resources/application.yml` — 主配置
- `src/main/resources/application-dev.yml` — 开发环境配置
  - server.port: 18080
  - MySQL: localhost:3306
  - Redis: localhost:6379
  - ZLM: localhost:6080

### AIoT 关键接口

**配置管理：**
- `POST /api/ai/config/push` — 推送配置到边缘端（Redis Stream）
- `GET /api/ai/config/export` — 导出摄像头完整配置
- `POST /api/ai/config/push-all` — 一次性推送全部配置（本地调试）

**ROI 管理：**
- `POST /api/ai/roi/create` — 创建 ROI 区域
- `PUT /api/ai/roi/update` — 更新 ROI 区域
- `DELETE /api/ai/roi/delete` — 删除 ROI 区域
- `GET /api/ai/roi/list` — 查询 ROI 列表

**截图服务：**
- `POST /api/ai/roi/snap` — 请求边缘端截图（Redis Stream）
- `POST /api/ai/roi/snap/callback` — 边缘端截图回调

**摄像头管理：**
- `GET /api/ai/camera/list` — 获取摄像头列表
- `POST /api/ai/camera/sync` — 同步摄像头配置

**视频播放：**
- `GET /api/play/{deviceId}/{channelId}` — 播放视频流
- `GET /api/play/{deviceId}/{channelId}/stop` — 停止播放

### 数据库表（MySQL）

**AIoT 核心表：**
- `ai_camera` — 摄像头配置（camera_id, camera_name, rtsp_url）
- `ai_roi` — ROI 区域配置（roi_id, camera_id, polygon, roi_name）
- `ai_roi_algo_bind` — 算法绑定（bind_id, roi_id, algorithm_code, threshold）
- `ai_edge_device` — 边缘设备管理
- `ai_config_snapshot` — 配置版本快照

**GB28181 核心表：**
- `device` — 国标设备表
- `device_channel` — 设备通道表
- `stream_proxy` — 流代理配置

## 开发工作流

### 修改后端代码
1. 修改 Java 代码
2. `mvn clean package -DskipTests`
3. `启动.bat` 或 `mvn spring-boot:run`
4. 访问 http://localhost:18080/doc.html 测试

### 修改前端代码
1. 修改 Vue 代码（web/src/）
2. `cd web && npm run build:prod`
3. 重新构建 Docker 镜像或直接运行 `npm run dev`

### 修改 AIoT 配置推送逻辑
- 配置推送服务：`aiot/service/impl/AiConfigServiceImpl.java`
- Redis Stream 写入：使用 RedisTemplate 的 `opsForStream().add()`
- 配置格式：JSON 包含 cameras、rois、bindings 数组

### GB28181 设备处理
- 设备注册处理：`gb28181/transmit/event/request/impl/RegisterRequestProcessor.java`
- 心跳处理：`gb28181/transmit/event/request/impl/MessageRequestProcessor.java`
- SIP 命令发送：`gb28181/transmit/cmd/impl/SIPCommander.java`

## 常见问题

### 启动失败：端口被占用
检查 18080 端口：`netstat -ano | findstr 18080`

### 数据库连接失败
检查 MySQL 状态（Docker 模式）：
```bash
docker ps | grep mysql
docker logs docker-polaris-mysql-1
```

### Redis 连接失败
检查 Redis（Docker 模式）：
```bash
docker exec -it docker-polaris-redis-1 redis-cli ping
```

### ZLMediaKit 流媒体服务异常
检查 ZLM 容器：
```bash
docker logs vsp-zlmedia
```

## Git 提交规范

在修改代码后，使用中文提交信息：

```bash
git add .
git commit -m "功能：添加XXX功能

详细说明...

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
```

**不要立即 push**，等待用户指示再推送到远程。