223 lines
6.8 KiB
Markdown
223 lines
6.8 KiB
Markdown
# CLAUDE.md
|
||
|
||
本文档为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。
|
||
|
||
## 项目概述
|
||
|
||
**黑石咀水库系统** - 湖北省山洪灾害防治综合洪水监测预警系统。这是一个基于 Spring Boot 3.x 的 Java 应用程序，实现了山洪灾害监测管理的"四预"系统（预报/预警/预演/预案）。
|
||
|
||
## 技术栈
|
||
|
||
- **框架**: Spring Boot 3.x with Java 21
|
||
- **数据库**: PostgreSQL with MyBatis-Plus 3.5.7 ORM
|
||
- **缓存**: Redis 用于缓存和会话管理
|
||
- **构建工具**: Maven 3.x
|
||
- **部署**: Docker 容器配合 docker-compose
|
||
- **架构**: 微服务分层架构
|
||
- **消息队列**: Spring Boot Quartz 调度器用于定时任务
|
||
- **文件存储**: MinIO/S3 兼容的对象存储
|
||
- **空间数据**: JTS (LocationTech) 用于地理处理
|
||
- **外部 API**: 与气象、水文和水库监测系统集成
|
||
|
||
## 开发命令
|
||
|
||
### 构建和运行
|
||
```bash
|
||
# 编译项目
|
||
mvn clean compile
|
||
|
||
# 打包应用程序
|
||
mvn clean package
|
||
|
||
# 本地运行（开发环境）
|
||
mvn spring-boot:run -Dspring-boot.run.profiles=dev
|
||
|
||
# 运行测试
|
||
mvn test
|
||
|
||
# 构建时跳过测试
|
||
mvn clean package -DskipTests
|
||
```
|
||
|
||
### Docker 部署
|
||
```bash
|
||
# 开发环境部署
|
||
./deploy_dev.ps1
|
||
|
||
# 使用 docker-compose 生产环境部署
|
||
docker-compose up -d
|
||
|
||
# 重启服务
|
||
docker-compose restart
|
||
```
|
||
|
||
### 数据库操作
|
||
```bash
|
||
# 应用程序使用 PostgreSQL，通过 MyBatis-Plus 进行自动模式管理
|
||
# 数据库迁移通过应用程序的实体模型处理
|
||
# 不需要单独的迁移工具
|
||
```
|
||
|
||
## 架构概述
|
||
|
||
### 分层架构
|
||
```
|
||
控制器层 (REST API) → 服务层 (业务逻辑) → 映射器层 (数据访问) → 数据库
|
||
```
|
||
|
||
### 核心组件
|
||
|
||
#### 1. **数据采集与同步**
|
||
- **位置**: `src/main/java/com/gunshi/project/hsz/timetask/DataTaskHsz.java`
|
||
- **功能**: 5分钟间隔从外部API同步数据
|
||
- **数据源**:
|
||
- 水文监测站（降雨量、水位）
|
||
- 气象站（气象数据）
|
||
- 水库监测系统
|
||
|
||
#### 2. **预报系统**
|
||
- **位置**: `src/main/java/com/gunshi/project/hsz/service/ForecastService.java`
|
||
- **功能**: 天气预报处理和洪水预测
|
||
- **特性**: GRIB2文件处理，网格降雨量计算
|
||
- **集成**: 外部气象API和洪水算法库
|
||
|
||
#### 3. **预警系统**
|
||
- **位置**: `src/main/java/com/gunshi/project/hsz/service/MessageCenterService.java`
|
||
- **功能**: 水位和渗压多级预警系统
|
||
- **特性**: 短信通知，广播预警，阈值告警
|
||
|
||
#### 4. **评估管理**
|
||
- **位置**: `src/main/java/com/gunshi/project/hsz/service/AssessTaskService.java`
|
||
- **功能**: 县级评估任务管理和工作流
|
||
- **特性**: 任务分配，审批流程，结果统计
|
||
|
||
### 包结构
|
||
|
||
```
|
||
src/main/java/com/gunshi/project/hsz/
|
||
├── controller/ # REST API 控制器 (132个控制器)
|
||
├── service/ # 业务逻辑服务
|
||
├── mapper/ # 数据访问层 (MyBatis-Plus)
|
||
├── model/ # 实体模型
|
||
├── entity/ # DTO 和 VO
|
||
├── timetask/ # 定时任务
|
||
├── config/ # 配置类
|
||
├── util/ # 工具类
|
||
├── grb/ # GRIB2 气象数据处理
|
||
└── system/ # 系统管理 (日志、用户)
|
||
```
|
||
|
||
## 数据库设计
|
||
|
||
### 关键数据模型
|
||
- **StPptnR**: 降雨监测站数据
|
||
- **StRsvrR**: 水库水位数据
|
||
- **StRiverR**: 河流水位数据
|
||
- **MessageCenter**: 预警消息管理
|
||
- **AssessTask**: 评估任务管理
|
||
- **OsmoticWarnRule**: 渗压预警规则
|
||
|
||
### 数据库配置
|
||
- **主数据库**: PostgreSQL (主从设置)
|
||
- **缓存**: Redis 用于会话和查询缓存
|
||
- **连接池**: HikariCP 优化设置
|
||
- **模式管理**: 通过 MyBatis-Plus 实体注解自动管理
|
||
|
||
## 外部集成
|
||
|
||
### API 端点
|
||
- **水文数据**: `jcskPath` (荆楚水库API)
|
||
- **气象数据**: `shqxjsCloudowrCnPath` (气象服务API)
|
||
- **水库数据**: `owrsvrPath` (水库监测API)
|
||
- **预警系统**: `shqxjsWarnPath` (气象预警API)
|
||
|
||
### 认证
|
||
- **基于令牌**: 外部服务认证的API令牌
|
||
- **IP白名单**: 动态IP白名单管理
|
||
- **安全**: 通过Jackson反序列化器进行XSS防护
|
||
|
||
## 配置管理
|
||
|
||
### 环境配置
|
||
- **dev**: 开发环境（本地测试）
|
||
- **prod**: 生产环境（Docker部署）
|
||
- **local**: 具有特定设置的本地开发
|
||
- **ruoyi**: RuoYi框架集成
|
||
|
||
### 关键配置文件
|
||
- `config-common.yml`: 通用配置（服务器端口、上下文路径）
|
||
- `config-prod.yml`: 生产数据库和外部API设置
|
||
- `config-dev.yml`: 开发环境设置
|
||
|
||
## 安全特性
|
||
|
||
### 应用安全
|
||
- **XSS防护**: 自定义Jackson反序列化器进行输入清理
|
||
- **SQL注入防护**: 通过MyBatis-Plus进行参数化查询
|
||
- **身份认证**: 与RuoYi权限框架集成
|
||
- **输入验证**: JSR-303验证注解
|
||
|
||
### 数据安全
|
||
- **数据库**: SSL连接，加密凭据
|
||
- **API**: 外部服务的基于令牌的认证
|
||
- **文件存储**: 具有访问控制的加密对象存储
|
||
|
||
## 监控和日志记录
|
||
|
||
### 应用监控
|
||
- **健康检查**: Spring Boot执行器端点
|
||
- **性能**: MyBatis-Plus SQL日志记录和性能分析
|
||
- **错误跟踪**: 具有详细日志记录的自定义异常解析器
|
||
|
||
### 数据同步
|
||
- **定时任务**: Quartz调度器用于5分钟数据同步
|
||
- **重试机制**: 失败API调用的自动重试
|
||
- **数据验证**: 自动数据清理和验证
|
||
|
||
## 开发指南
|
||
|
||
### 代码组织
|
||
- 遵循现有的包结构和命名约定
|
||
- 使用MyBatis-Plus进行数据库操作和lambda查询
|
||
- 使用`@Transactional`实现适当的事务管理
|
||
- 对业务逻辑使用现有的服务模式
|
||
|
||
### 数据库操作
|
||
- 始终使用MyBatis-Plus lambda查询确保类型安全
|
||
- 使用`@Cacheable`注解实现适当的缓存策略
|
||
- 为数据库表使用现有的实体模型模式
|
||
- 遵循主从数据库配置
|
||
|
||
### 外部API集成
|
||
- 使用现有的`OkHttpUtil`进行HTTP请求
|
||
- 实现适当的错误处理和重试机制
|
||
- 遵循现有的基于令牌的认证模式
|
||
- 使用配置属性设置API端点
|
||
|
||
### 测试
|
||
- 为服务层业务逻辑编写单元测试
|
||
- 测试数据同步和外部API集成
|
||
- 验证数据库操作和数据完整性
|
||
- 测试预警系统阈值逻辑
|
||
|
||
## 部署说明
|
||
|
||
### 生产部署
|
||
- 使用提供的`docker-compose.yml`进行容器化部署
|
||
- 为数据库凭据配置适当的环境变量
|
||
- 确保Redis和PostgreSQL服务正在运行
|
||
- 监控数据同步任务和API健康状态
|
||
|
||
### 开发设置
|
||
- 使用`dev`配置文件进行本地开发
|
||
- 在`config-dev.yml`中配置本地数据库连接
|
||
- 使用`mvn spring-boot:run`运行应用程序
|
||
- 使用适当的凭据测试外部API连接
|
||
|
||
## 重要说明
|
||
|
||
- 本系统处理关键的洪水监测数据 - 确保数据完整性和可靠性
|
||
- 外部API集成需要适当的认证和错误处理
|
||
- 预警系统具有实时要求 - 优化性能以确保及时告警
|
||
- 数据库性能对于大规模监测数据处理至关重要
|
||
- 遵循定时任务和数据同步的现有模式 |