gunshi-project-ss/CLAUDE.md

# CLAUDE.md

本文档为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。

## 重要说明
- @agent-technical-writer --think-hard 
  docs目录下是你之前结合代码库为我生成的详细设计文档的部分章节，以一个章节对应一个文件的形式存在，，现在需要你对比docs目录和template目
  录下的文档，template目录下的文档是作为参考的文档模板，包含4个章节的片段，结合代码库的实现调整docs目录下对应的4个文档片段的内容并进行
  扩充，需要留意docs目录下的todo.md的要求，并且在todo.md中记录工作步骤并保持追踪。你要先阅读todo.md再开始工作，例如先对比并修改第4章就
  更新todo.md并停止执行，等我下达命令再继续对比第5章，以此类推。由于文档内容比较多，你一个一个对比，不要全部加载到上下文再去对比
- 每次执行任务前要回顾docs/todo.md的内容
- 这个项目是黑石咀水库的，不是山洪灾害四预系统项目的，我让你参考山洪灾害四预系统项目的设计文档的行文风格和排版来编写
   黑石咀项目的详细设计文档
- 生成的文档内容要参考代码库已有的实现，但是不要把具体代码写入文档
- 你的任务很重要的一部分工作是扩充文档内容，切记这一点，但是不要写大量的与代码库内容无关的内容
- 只需要编写第4、5、6、7章
- 第6章不需要编写6.3数据库设计章节内容
- 保持与现有代码库的一致性
- 确保文档的技术准确性
- 不要写具体代码实现的内容，如果一定要写与代码相关的内容，使用自然语言来描述逻辑
- 保持小章节的序号，如4.1、4.2等
- 如果文档模板实在找不到与代码库对应的内容，留空，不要擅自填写不相干的内容
- 
## 项目概述

**黑石咀水库系统** - 湖北省山洪灾害防治综合洪水监测预警系统。这是一个基于 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连接