yangzhe
/
gunshi-project-ss
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
gunshi-project-ss/CLAUDE.md

6.8 KiB
Raw Blame History

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: 与气象、水文和水库监测系统集成

开发命令

构建和运行

# 编译项目
mvn clean compile

# 打包应用程序
mvn clean package

# 本地运行（开发环境）
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# 运行测试
mvn test

# 构建时跳过测试
mvn clean package -DskipTests

Docker 部署

# 开发环境部署
./deploy_dev.ps1

# 使用 docker-compose 生产环境部署
docker-compose up -d

# 重启服务
docker-compose restart

数据库操作

# 应用程序使用 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集成需要适当的认证和错误处理
  • 预警系统具有实时要求 - 优化性能以确保及时告警
  • 数据库性能对于大规模监测数据处理至关重要
  • 遵循定时任务和数据同步的现有模式