WeatherServer/weather-service/docs/技术实现文档.md

# Weather Service 技术实现文档

## 1. Weather Service 项目结构

```
src/main/java/com/htfp/weather/
├── WeatherServiceApplication.java  # 应用程序入口
├── config/                        # 配置类
├── download/                      # 数据下载模块
├── griddata/                      # 网格数据处理
├── info/                         # 信息处理模块
├── schedule/                     # 定时任务模块
├── utils/                        # 工具类
└── web/                         # Web接口模块
```

## 2. 核心模块分析

### 2.1 应用程序入口
文件：`WeatherServiceApplication.java`

```java
@EnableRetry // 开启重试机制
@EnableScheduling // 开启定时任务
@SpringBootApplication
public class WeatherServiceApplication {
    public static void main(String[] args) {
        TimeZone.setDefault(TimeZone.getTimeZone("Asia/Shanghai"));
        SpringApplication.run(WeatherServiceApplication.class, args);
    }
}
```

主要特性：
1. 启用Spring Boot自动配置
2. 启用重试机制，支持失败操作重试
3. 启用定时任务调度功能
4. 设置默认时区为亚洲/上海

### 2.2 数据下载模块
目录：`download/`

#### 2.2.1 基础下载器（BaseDataDownloader）
文件：`BaseDataDownloader.java`

```java
@Data
@ToString
public abstract class BaseDataDownloader {
    private String startTimeStr;        // 起始时间（北京时UTC+8）
    private LocalDateTime startTime;    // 起始时间对象
    private String refTimeStr;          // 参考时间字符串
    private OffsetDateTime refTime;     // 数据实际起报UTC时间

    // 获取所有下载文件信息
    public abstract List<DownLoadFileInfo> getFilesInfo();
    
    // 单个文件下载
    public abstract DownLoadFileInfo download(DownLoadFileInfo downLoadFileInfo) throws IOException;
    
    // 批量下载所有文件
    public abstract List<DownLoadFileInfo> downloadAll(List<DownLoadFileInfo> downLoadFileInfoList);
}
```

#### 2.2.2 下载文件信息（DownLoadFileInfo）
文件：`DownLoadFileInfo.java`

```java
@Data
@ToString
public class DownLoadFileInfo {
    private String fileName;            // 保存文件名
    private String refTimeStr;          // 数据起报时间
    private Integer forecastHour;       // 预报时效
    private String forecastBJTimeStr;   // 预报时效对应的北京时间
    private String forecastUTCTimeStr;  // 预报时效对应的UTC时间
    private String url;                 // 下载链接
    private String savePath;            // 保存路径
    private boolean isDownloadSuccess;  // 下载是否成功
    private String errorMsg;            // 错误信息
}
```

#### 2.2.3 GFS数据下载
目录：`download/gfs/`

该模块实现了GFS（全球预报系统）气象数据的下载功能：
1. 支持配置下载起始时间
2. 提供单文件和批量下载能力
3. 包含下载状态跟踪和错误处理
4. 支持UTC和北京时间的转换

### 2.3 网格数据处理模块
目录：`griddata/`

#### 2.3.1 数据表配置（TableConfig）
文件：`griddata/common/TableConfig.java`

```java
@Data @Component @Slf4j
public class TableConfig {
    private String dataTableName;      // 数据表名
    private String metaTableName;      // 元数据表名
    private String dataIndexName;      // 数据索引名
    private String metaIndexName;      // 元数据索引名
    private String dataDir;            // 数据目录
    private List<String> variableList; // 变量列表
    private int lonSize;               // 经度网格数
    private int latSize;               // 纬度网格数
    private int levSize;               // 层次数
    private int timeToLive;            // 数据生存时间
    
    // 网格参数
    private double[] lonList;          // 经度列表
    private double[] latList;          // 纬度列表
    private int[] pressureList;        // 气压层次
    private int[] heightList;          // 高度层次
}
```

#### 2.3.2 数据导入（GfsDataImport）
文件：`griddata/operation/GfsDataImport.java`

主要功能：
1. 网格数据导入到阿里云表格存储
2. 支持多维度数据处理：
   - 时间维度
   - 空间维度（经纬度）
   - 垂直维度（气压层/高度层）
3. 数据处理流程：
   - 初始化元数据
   - 读取NC文件
   - 数据单位转换
   - 网格数据写入
   - 更新元数据状态

关键特性：
1. 支持并发导入
2. 错误处理和状态跟踪
3. 支持断点续传
4. 数据完整性验证

#### 2.3.3 数据操作类
目录：`griddata/operation/`

1. BaseTableOperation：表操作基类
2. CreateTable：创建数据表
3. GfsDataFetcher：数据获取
4. QueryMeta：元数据查询
5. UpdateTable：表更新
6. DataDeleter：数据删除

### 2.4 定时任务模块
目录：`schedule/`

#### 2.4.1 网格数据处理器（GridDataProcessor）
文件：`schedule/GridDataProcessor.java`

```java
@Component
@Slf4j
@DependsOn({"gfsDataImport", "gfsDownloader"})
public class GridDataProcessor {
    // 定时任务：每日北京时0,8,12,18点30分执行
    @Scheduled(cron = "0 30 0,8,12,18 * * ?")
    public void dailyDataProcess() {
        if (download()) {           // 下载数据
            importToTableStore();    // 导入数据库
        }
        clearExpiredData();         // 清理过期数据
    }
}
```

主要功能：
1. 数据下载管理
   - 获取文件信息
   - 执行下载
   - 处理下载失败
2. 数据导入管理
   - 导入表格存储
   - 处理导入失败
3. 数据清理
   - 清理3天前的过期数据
   - 日志记录

#### 2.4.2 错误报告服务（ErrorReportService）
文件：`schedule/ErrorReportService.java`

```java
@Service
@Slf4j
public class ErrorReportService {
    // 邮件发送，支持重试
    @Retryable(maxAttempts = 4, backoff = @Backoff(delay = 2000, multiplier = 2))
    public void sendSimpleEmail(final Mail mail) {
        // 发送邮件逻辑
    }
    
    // 远程报告，支持重试
    @Retryable(maxAttempts = 4, backoff = @Backoff(delay = 2000, multiplier = 2))
    public void reportToRemote(final ErrorReport report) {
        // 发送远程报告逻辑
    }
}
```

特性：
1. 支持邮件通知
2. 支持远程报告
3. 失败重试机制
4. 多种通知方式

### 2.5 Web接口模块
目录：`web/`

#### 2.5.1 地面天气控制器（SurfaceWeatherController）
文件：`web/controller/SurfaceWeatherController.java`

```java
@RestController
@RequestMapping("/htfp/weather/v1/surface/")
public class SurfaceWeatherController {
    // 地面实时气象信息查询
    @PostMapping("/querySurfaceNowWeather")
    public Result queryNowWeather(@Validated @RequestBody Position2D position2D)
    
    // 地面24小时预报结果查询
    @PostMapping("/querySurfaceForecast")
    public Result querySurfaceForecast(@Validated @RequestBody Position2D position2D)
    
    // 地面气象预警信息查询
    @PostMapping("/queryWeatherWarning")
    public Result queryWeatherWarning(@Validated @RequestBody Position2D position2D)
    
    // 全国地面气象预警信息查询
    @PostMapping("/queryAllWeatherWarning")
    public Result queryWeatherWarning()
}
```

主要功能：
1. 地面实时天气查询
2. 24小时天气预报
3. 气象预警信息
4. 支持多数据源切换（和风天气、彩云天气等）

#### 2.5.2 高空天气控制器（UpperWeatherController）
文件：`web/controller/UpperWeatherController.java`

```java
@RestController
@RequestMapping("/htfp/weather/v1/upper/")
public class UpperWeatherController {
    // 高空实时气象信息查询
    @PostMapping("/queryUpperNowWeather")
    public Result queryUpperNowWeather(@Validated @RequestBody Position3D position3D)
    
    // 高空航点实时气象信息查询
    @PostMapping("/queryUpperNowWeatherInMultiPoints")
    public Result queryUpperNowWeatherInMultiPoints(@Validated @RequestBody MultiPointsRequest request)
    
    // 高空24小时预报结果查询
    @PostMapping("/queryUpperForecast")
    public Result queryUpperForecast(@Validated @RequestBody Position3D position3D)
    
    // 高度廓线查询
    @RequestMapping("/queryProfileByPressure")
    public Result queryProfileByAndPressure(@Validated @RequestBody ProfileRequest request)
    
    // 平面网格数据查询
    @PostMapping("/queryPlaneGrid")
    public Result queryPlaneGrid(@Validated @RequestBody PlaneRequest request)
}
```

主要功能：
1. 高空实时天气查询
   - 单点查询
   - 多点查询（航线）
2. 高空天气预报
   - 24小时预报
   - 多点预报
3. 高度廓线分析
   - 气压坐标
   - 近地面高度坐标
4. 平面网格数据查询

#### 2.5.3 接口特性
1. RESTful API设计
2. 跨域支持（@CrossOrigin）
3. 参数验证（@Validated）
4. 统一响应格式（Result）
5. 接口日志记录（@ControllerLog）
6. 异常处理（ControllerExceptionAdvice）

#### 2.5.4 数据模型
1. 请求参数：
   - Position2D：二维位置（经纬度）
   - Position3D：三维位置（经纬度+高度）
   - MultiPointsRequest：多点请求
   - ProfileRequest：廓线请求
   - PlaneRequest：平面网格请求

2. 响应数据：
   - NowWeatherStatus：实时天气状态
   - TimeSeriesDataset：时间序列数据
   - SurfaceWeatherWarning：天气预警信息
   - ProfileResponse：廓线响应
   - PlaneResponse：平面网格响应

### 2.6 工具类模块
目录：`utils/`

#### 2.6.1 HTTP客户端工具（HttpClientUtils）
文件：`utils/HttpClientUtils.java`

提供HTTP请求相关功能：
1. GET请求
2. POST请求
3. SSL证书处理
4. 请求头管理
5. 响应处理

#### 2.6.2 JSON工具（JSONUtils）
文件：`utils/JSONUtils.java`

JSON数据处理工具：
1. 对象序列化
2. JSON解析
3. 文件读写
4. 类型转换

#### 2.6.3 气象工具（MeteoUtils）
文件：`utils/MeteoUtils.java`

气象数据处理工具：
1. 气压高度转换
2. 温度单位转换
3. 风向风速计算
4. 气象要素计算

#### 2.6.4 时间工具（DateTimeUtils）
文件：`utils/DateTimeUtils.java`

时间处理工具：
1. 时区转换
2. 格式化处理
3. 时间计算
4. UTC时间处理

#### 2.6.5 数组工具（NdArrayUtils）
文件：`utils/NdArrayUtils.java`

多维数组处理工具：
1. 数组维度转换
2. 数据提取
3. 数组操作

#### 2.6.6 Spring工具（SpringUtil）
文件：`utils/SpringUtil.java`

Spring相关工具：
1. Bean管理
2. 上下文处理
3. 配置加载

## 3. 系统功能概述

### 3.1 核心功能
1. GFS气象数据处理
   - 数据下载
   - 数据解析
   - 数据存储
   - 数据查询

2. 天气信息服务
   - 地面天气查询
   - 高空天气查询
   - 天气预警
   - 天气预报

3. 数据分析能力
   - 高度廓线分析
   - 多点数据分析
   - 网格数据分析
   - 时序数据分析

### 3.2 技术特点
1. 数据处理
   - 支持多维度数据
   - 高效数据存储
   - 实时数据更新
   - 数据质量控制

2. 系统架构
   - 模块化设计
   - 可扩展性好
   - 高可用性
   - 易维护性

3. 接口设计
   - RESTful规范
   - 参数验证
   - 异常处理
   - 日志记录

4. 运维特性
   - 监控告警
   - 错误追踪
   - 性能优化
   - 安全保障

## 4. 后续开发建议

### 4.1 功能增强
1. 数据源扩展
   - 增加更多气象数据源
   - 支持数据源动态切换
   - 实现数据源备份

2. 分析能力提升
   - 增加更多气象要素分析
   - 提供数据可视化能力
   - 支持自定义分析模型

3. 接口优化
   - 增加批量处理接口
   - 优化接口响应时间
   - 提供WebSocket接口

### 4.2 性能优化
1. 数据处理
   - 优化数据存储结构
   - 实现数据缓存
   - 提高并发处理能力

2. 系统架构
   - 引入微服务架构
   - 实现服务集群
   - 优化负载均衡

3. 运维能力
   - 完善监控系统
   - 优化告警机制
   - 提升系统可用性

### 4.3 安全加强
1. 访问控制
   - 实现用户认证
   - 细化权限管理
   - 加强接口安全

2. 数据安全
   - 加密敏感数据
   - 实现数据备份
   - 审计日志完善

### 4.4 文档完善
1. 接口文档
   - 详细API说明
   - 示例代码
   - 错误码说明

2. 运维文档
   - 部署说明
   - 配置说明
   - 故障处理

3. 开发文档
   - 架构说明
   - 开发规范
   - 测试用例