142 lines
8.4 KiB
Markdown
142 lines
8.4 KiB
Markdown
# 气象数据管理系统
|
||
|
||
基于 Spring Boot 3.5 与 Vue 3 的全栈气象数据管理与分析平台。
|
||
|
||
> 开发者文档：[CLAUDE.md](CLAUDE.md) | 模块文档：[system-admin](system-admin/CLAUDE.md) | [system-common](system-common/CLAUDE.md) | [system-dynamic-datasource](system-dynamic-datasource/CLAUDE.md) | [weather-data-ui](weather-data-ui/CLAUDE.md)
|
||
>
|
||
> English version: [README.md](README.md)
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
weather-data/
|
||
├── system-common/ 公共模块（基础类、Redis、校验、工具类）
|
||
├── system-dynamic-datasource/ 多数据源支持（AbstractRoutingDataSource）
|
||
├── system-admin/ 主应用（REST API、安全、定时任务、文件扫描）
|
||
└── weather-data-ui/ Vue 3 前端（Element Plus、ECharts、Pinia）
|
||
```
|
||
|
||
### 模块关系
|
||
|
||
```
|
||
system-common <-- 被所有后端模块依赖
|
||
system-dynamic-datasource <-- 被 system-admin 依赖
|
||
system-admin <-- 可运行的 Spring Boot 应用，依赖上述两个模块
|
||
weather-data-ui <-- 独立前端，通过 REST API 与 system-admin 通信
|
||
```
|
||
|
||
**[system-common](system-common/)** 提供基础类层次（[BaseEntity](system-common/src/main/java/com/weather/common/entity/BaseEntity.java)、[CrudService](system-common/src/main/java/com/weather/common/service/CrudService.java)、[CrudServiceImpl](system-common/src/main/java/com/weather/common/service/impl/CrudServiceImpl.java)）、[Redis 工具](system-common/src/main/java/com/weather/common/redis/RedisUtils.java)、校验框架、XSS 防护及通用工具类。所有后端模块均依赖此模块。
|
||
|
||
**[system-dynamic-datasource](system-dynamic-datasource/)** 提供 [@DataSource](system-dynamic-datasource/src/main/java/com/weather/commons/dynamic/datasource/annotation/DataSource.java) 注解与 [DynamicDataSource](system-dynamic-datasource/src/main/java/com/weather/commons/dynamic/datasource/config/DynamicDataSource.java)（继承 `AbstractRoutingDataSource`），用于运行时切换多数据源。当 system-admin 需要查询不同数据库时使用。
|
||
|
||
**[system-admin](system-admin/)** 是主应用入口（[AdminApplication.java](system-admin/src/main/java/com/weather/AdminApplication.java)），所有业务逻辑按 domain 组织在 `modules/` 下：
|
||
|
||
| 业务域 | 包路径 | 功能说明 |
|
||
|--------|--------|----------|
|
||
| 逐日气象数据 | [modules/weather/dailydata/](system-admin/src/main/java/com/weather/modules/weather/dailydata/) | Excel 批量导入、CRUD、Redis 缓存统计汇总 |
|
||
| 气象站点 | [modules/weather/station/](system-admin/src/main/java/com/weather/modules/weather/station/) | 站点注册，关联部门实现数据权限隔离 |
|
||
| 文件扫描 | [modules/weather/filescan/](system-admin/src/main/java/com/weather/modules/weather/filescan/) | WatchService 目录监控，气象资料自动入库 |
|
||
| 区域管理 | [modules/region/](system-admin/src/main/java/com/weather/modules/region/) | 行政区域树（省/市/县） |
|
||
| 系统管理 | [modules/sys/](system-admin/src/main/java/com/weather/modules/sys/) | 用户、角色、菜单、部门、字典、参数 |
|
||
| 通知消息 | [modules/sys/alert/](system-admin/src/main/java/com/weather/modules/sys/alert/) | SSE 实时推送，Spring 事件驱动广播 |
|
||
| 安全认证 | [modules/security/](system-admin/src/main/java/com/weather/modules/security/) | Shiro + Token 认证，OAuth2 过滤器，密码加密 |
|
||
| 定时任务 | [modules/job/](system-admin/src/main/java/com/weather/modules/job/) | Quartz 动态任务管理，在线启停 |
|
||
| 审计日志 | [modules/log/](system-admin/src/main/java/com/weather/modules/log/) | 操作日志、登录日志、异常日志 |
|
||
| 云存储 | [modules/oss/](system-admin/src/main/java/com/weather/modules/oss/) | 阿里云 OSS / 七牛云 / 腾讯云 COS 文件存储 |
|
||
|
||
**[weather-data-ui](weather-data-ui/)** 是 Vue 3 单页应用，通过 REST API 与 system-admin 通信。特性包括：动态路由（登录时从服务端菜单加载）、标签页导航、ECharts 图表可视化、SSE 实时通知滚动。
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| 后端框架 | Spring Boot 3.5.11, MyBatis-Plus 3.5.8, Apache Shiro 1.12 |
|
||
| 数据库 | MySQL 8.0（同时支持 Oracle、SQL Server、PostgreSQL、达梦） |
|
||
| 连接池 | Druid 1.2 |
|
||
| 缓存 | Redis 7（Lettuce 客户端，通过 `project-options.redis.open` 控制开关） |
|
||
| 定时任务 | Quartz 2.3 |
|
||
| 接口文档 | Knife4j 4.5 (Swagger) |
|
||
| Excel 处理 | EasyExcel 3.2 |
|
||
| 前端 | Vue 3.5, TypeScript 5.7, Vite 5.4, Element Plus 2.10, Pinia 2.3, ECharts 5 |
|
||
|
||
**环境要求**：JDK 17+、Maven 3.6+、Node.js 18+、MySQL 8.0+
|
||
|
||
## 快速启动（本地开发）
|
||
|
||
### 1. 初始化数据库
|
||
|
||
```bash
|
||
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS weather_data_system DEFAULT CHARSET utf8mb4"
|
||
mysql -u root -p weather_data_system < system-admin/db/weather_data_system.sql
|
||
```
|
||
|
||
数据库脚本：[system-admin/db/weather_data_system.sql](system-admin/db/weather_data_system.sql)
|
||
|
||
### 2. 配置数据源
|
||
|
||
编辑 [system-admin/src/main/resources/application-dev.yml](system-admin/src/main/resources/application-dev.yml)，修改 MySQL 和 Redis 连接信息：
|
||
|
||
```yaml
|
||
spring:
|
||
datasource:
|
||
druid:
|
||
url: jdbc:mysql://localhost:3306/weather_data_system?...
|
||
username: root
|
||
password: 你的密码
|
||
data:
|
||
redis:
|
||
host: 127.0.0.1
|
||
port: 6379
|
||
password:
|
||
```
|
||
|
||
### 3. 启动后端
|
||
|
||
```bash
|
||
# 完整构建
|
||
mvn clean install -DskipTests
|
||
|
||
# 在 IDE 中运行 AdminApplication.java
|
||
# 或命令行启动：
|
||
cd system-admin && mvn spring-boot:run -Dspring-boot.run.profiles=dev
|
||
```
|
||
|
||
管理后台：<http://localhost:8080/system-admin>
|
||
接口文档：<http://localhost:8080/system-admin/doc.html>
|
||
默认账号：`admin` / `admin`
|
||
|
||
### 4. 启动前端
|
||
|
||
```bash
|
||
cd weather-data-ui
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
前端开发服务器：<http://localhost:8001>
|
||
|
||
如需修改后端地址，编辑 [weather-data-ui/.env.development](weather-data-ui/.env.development) 中的 `VITE_APP_API`。
|
||
|
||
## 部署
|
||
|
||
1. 构建后端：`mvn clean package -DskipTests -f system-admin`
|
||
2. 构建前端：`cd weather-data-ui && npm run build`
|
||
3. 将 `system-admin/target/system-admin.jar` 和 `weather-data-ui/dist/` 部署到服务器
|
||
4. 配置 `application-prod.yml` 中的生产环境数据库和 Redis 连接信息
|
||
5. 启动后端：`java -jar system-admin.jar --spring.profiles.active=prod`
|
||
|
||
### Windows Server
|
||
|
||
参见 `deploy/` 目录下的一键部署脚本（[deploy.bat](deploy/deploy.bat) / [deploy.ps1](deploy/deploy.ps1)）。要求 Windows 10 1803+ 或 Windows Server 2019+，需预装 JDK 17+。以管理员身份运行。
|
||
|
||
## 核心功能
|
||
|
||
- **气象数据导入**：Excel 异步双遍扫描批量导入，进度可查，多行 INSERT 优化。入口：[WeatherDataImportManager](system-admin/src/main/java/com/weather/modules/weather/dailydata/WeatherDataImportManager.java)
|
||
- **统计汇总**：历年同月同日数据汇总，Redis 缓存加速查询，缓存命中自动降级至数据库。缓存任务：[WeatherSummarizeCacheTask](system-admin/src/main/java/com/weather/modules/weather/dailydata/task/WeatherSummarizeCacheTask.java)
|
||
- **文件监控**：基于 WatchService 自动监控资料目录，MD5 去重，文件生命周期管理（接收 -> 展示 -> 归档）。服务：[FileWatchServiceManager](system-admin/src/main/java/com/weather/modules/weather/filescan/FileWatchServiceManager.java)
|
||
- **实时通知**：基于 SSE 的服务端推送，Spring 事件驱动广播。服务：[SseAlertService](system-admin/src/main/java/com/weather/modules/sys/alert/SseAlertService.java)
|
||
- **数据权限**：基于 MyBatis-Plus 拦截器的部门级行级安全，通过 `@DataFilter` 注解启用。拦截器：[DataFilterInterceptor](system-admin/src/main/java/com/weather/common/interceptor/DataFilterInterceptor.java)
|
||
- **动态数据源**：运行时通过 `@DataSource` 注解切换数据源，ThreadLocal 上下文传递。实现：[DynamicDataSource](system-dynamic-datasource/src/main/java/com/weather/commons/dynamic/datasource/config/DynamicDataSource.java)
|
||
- **定时任务**：Quartz 动态任务管理，支持在线创建、启停、修改 Cron 表达式。配置：[ScheduleConfig](system-admin/src/main/java/com/weather/modules/job/config/ScheduleConfig.java)
|
||
- **云存储**：支持阿里云 OSS、七牛云、腾讯云 COS 文件上传与管理。工厂：[OSSFactory](system-admin/src/main/java/com/weather/modules/oss/cloud/OSSFactory.java)
|