文档：创建 CLAUDE.md 开发指南

新增内容： - 项目概述和生产部署信息 - 本地开发和 Docker 部署命令 - 架构概览（核心模块、配置文件） - AIoT 关键接口说明（配置管理、ROI、截图、视频播放） - 数据库表结构说明 - 开发工作流指引 - 常见问题排查 - Git 提交规范 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-03-05 16:27:38 +08:00
parent f0466e84d4
commit 827daebcf4
1 changed files with 225 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,225 @@
+# 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**，等待用户指示再推送到远程。