空气质量数据分析与预测系统技术文档

1. 项目概述

本项目是一个以 Flask + Vue2 + MySQL 为主的空气质量数据分析与预测系统，包含：

• 后台管理端：维护空气质量数据、气候数据、城市信息、用户信息、通知公告和系统日志。
• 前台展示端：面向普通访问者展示空气质量、气候数据、趋势预测、地图分析和资讯内容。
• 预测分析能力：基于历史气候数据和空气质量数据做短期趋势预测。
• 数据导入能力：支持历史 Excel、CSV 和远程空气质量数据补录。

当前数据库默认名称已统一为 design_361_air。

2. 当前整理结论

2.1 已清理内容

• 根目录历史大导出文件已迁移到 db/archive/design_air_test_legacy_full.sql
• .idea、__pycache__、前端缓存等明显生成物已清理
• 前后台 node_modules 已删除，目录体积显著下降；后续如需重新构建，执行 npm install
• 后台前端中未挂路由的旧页面源码已删除：
  • api/templates/front/admin/src/views/modules/climate_forecast/
  • api/templates/front/admin/src/views/modules/config/
  • api/templates/front/admin/src/views/modules/storeup/
  • api/templates/front/admin/src/views/modules/systemintro/
  • api/templates/front/admin/src/views/modules/users/
• 后台前端备份文件 api/templates/front/admin/src/main.js.bak 已删除

2.2 仍需保留的内容

• api/templates/front/admin/dist 和 api/templates/front/front/dist 不能删
  • Flask 当前直接托管这两个构建目录，删除后 /admin/ 和 /front/ 会直接失效
• utils 下的 Spark / HDFS / Hive / MapReduce / 百度 AI 等代码不能直接判定为废代码
  • 这些能力虽然不是当前核心展示链路，但后端通用 CRUD、上传、人脸识别、统计接口中仍存在实际引用
• /python0745x1xa/ 仍然是当前统一 API 前缀
  • 它不是数据库名，也不是无用字符串；前后端请求都在用

2.3 当前残留说明

• tmp/air_quality_sync 目录目前为空，但本机文件系统对该目录删除返回 Access denied
• 该目录不影响运行，只是一个运行时临时目录残留

结论：现在不能严肃地说“所有历史代码都删完了”，但已经完成了“明显无用生成物 + 无路由死页面”的清理；剩余保留项都是当前运行链路或兼容链路的一部分。

3. 技术栈

3.1 后端

• Python 3.7+
• Flask 1.1.2
• Flask-SQLAlchemy 2.4.4
• SQLAlchemy 1.3.20
• PyMySQL 1.0.2
• Click 8.1.2

3.2 数据分析与扩展能力

• NumPy
• SciPy
• openpyxl
• requests
• Scrapy
• hdfs
• mrjob
• pyspark
• pyhive

3.3 前台与后台前端

• Vue 2.6.14
• Vue Router 3.x
• Vuex 3.x
• Element UI 2.x
• ECharts 5.4.1
• vue-echarts
• vue-amap
• vue-baidu-map
• swiper
• vue-resource
• axios

4. 系统架构

4.1 运行结构

• Flask 作为单体后端服务，对外监听 8080
• 后端同时托管前台和后台构建后的静态资源
• 管理端入口：/admin/
• 前台入口：/front/
• API 统一前缀：/python0745x1xa/

4.2 架构特点

• 后端是“通用生成 CRUD + 少量人工增强接口”的混合结构
• 前端分为两个 Vue2 工程：
  • api/templates/front/admin
  • api/templates/front/front
• 预测逻辑、空气质量同步逻辑和通用工具逻辑集中在 utils/

5. 目录结构

E:\temp\weather
├─ api/                          Flask 应用主体
│  ├─ main/                      路由与接口
│  ├─ models/                    SQLAlchemy 模型
│  ├─ templates/front/           前后台静态资源、源码与上传文件
│  │  ├─ admin/                  后台 Vue2 工程
│  │  └─ front/                  前台 Vue2 工程
│  └─ bin/                       JDBC 驱动等扩展资源
├─ db/                           数据库脚本、结构文件、归档
├─ scripts/                      数据导入与资源生成脚本
├─ utils/                        鉴权、日志、预测、同步、Hadoop 扩展等
├─ config.ini                    数据库与 Redis 配置
├─ configs.py                    Flask 配置
├─ manage.py                     初始化和运维命令
├─ run.py                        直接启动入口
├─ 启动说明.md                   启动说明
└─ 项目技术文档.md               本文档

6. 核心数据模型

6.1 管理员与用户

• users
  • 后台管理员表
  • 字段核心：username、password、role、image
• yonghu
  • 前台用户表
  • 字段核心：yonghuzhanghao、mima、yonghuxingming、touxiang、xingbie、shoujihaoma

6.2 基础数据

• city
  • 城市基础信息
  • 字段核心：code、name、province、city_type、longitude、latitude、is_active
• climate_data
  • 气候历史数据
  • 字段核心：date、temp_high、temp_low、temp_avg、precipitation、wind_speed、humidity、aqi、city_id
• kongqizhiliang
  • 空气质量历史数据
  • 字段核心：city_code、city_name、province、record_date、aqi_index、quality_level、pm25_avg、pm10_avg、so2_avg、no2_avg、co_avg、o3_avg
  • 约束：city_code + record_date 唯一

6.3 内容与运营

• news
  • 通知公告
  • 支持点击量、点赞、点踩、收藏数
• newstype
  • 公告分类
• storeup
  • 收藏与推荐行为表
• systemintro
  • 系统简介/图文介绍
• syslog
  • 系统操作日志

6.4 参数配置

• config
  • 系统参数配置表
  • 用于百度地图 AK、百度 AI Key 等配置读取

7. 后端模块说明

7.1 应用启动

• run.py
  • 创建 Flask 应用并启动服务
  • 默认会尝试打开浏览器到 /front/
• manage.py
  • 提供 run、create_all、initsql 等命令

7.2 Flask 应用初始化

api/__init__.py 负责：

• 注册数据库
• 注册主蓝图 main_bp
• 注入自定义 JSON 序列化
• 初始化线程池 ThreadPoolExecutor(20)
• 根据 config.ini 条件性启用 Spark / HDFS
• 在 after_request 中统一写入 syslog

7.3 路由自动装载

api/main/__init__.py 会扫描 api/main/ 目录，并自动导入所有合法的 *_v.py 模块。
这意味着：

• 新增接口文件只要符合当前命名和语法规则，就会被自动挂载
• 误删接口文件会直接影响启动与路由可达性

8. 核心接口分组

8.1 登录与会话

• users_v.py
  • 管理员登录、分页、会话、增删改
• Yonghu_v.py
  • 前台用户注册、登录、资料维护、分页与统计
• 当前会话读取已做过修正
  • 优先按用户 id 回查数据库
  • 避免用户名或密码变更后出现“找不到当前会话用户”

8.2 气候数据

• Climate_data_v.py
  • 标准 CRUD
  • 统计接口：count、group、value、valueMul
  • 导入接口：importExcel

8.3 空气质量

• Kongqizhiliang_v.py
  • 标准 CRUD
  • 城市列表：cities
  • 数据总览：summary
  • 趋势分析：trend
  • 排行分析：rankings
  • 等级分布：levelStats
  • 省份聚合：provinceStats
  • 城市聚合：cityStats
  • 污染物聚合：pollutantStats
  • 最新同步：syncLatest

8.4 趋势预测

• Climate_forecast_v.py
  • 数据集选项：datasets
  • 城市列表：cities
  • 变量列表：variables
  • 方法列表：methods
  • 历史数据：history/<city_id>
  • 主预测接口：predict

8.5 资讯与运营

• News_v.py
  • 公告 CRUD
  • 点赞/点踩/收藏
  • 排序、分组、统计
• Newstype_v.py
  • 公告分类 CRUD
• Storeup_v.py
  • 收藏数据 CRUD 和统计
• Syslog_v.py
  • 系统日志查询和删除

8.6 公共接口

schema_v.py 提供一批通用能力：

• 文件上传/下载
• 动态下拉选项
• 计算接口
• 提醒接口
• 地理位置解析
• 人脸相似度匹配

9. 前端功能说明

9.1 后台管理端

当前后台主导航聚焦在以下模块：

• 用户管理
• 气候数据
• 空气质量
• 城市管理
• 系统日志
• 通知公告
• 通知公告分类

后台首页和驾驶舱页面主要展示：

• 城市数量
• 气候记录数量
• 空气质量记录数量
• 最新气候日期
• 最新空气日期
• 最新 AQI 排行

9.2 前台展示端

前台主导航当前包含：

• 气候数据
• 趋势预测
• 空气质量
• 数据分析
• 城市信息
• 通知公告

前台核心页面包括：

• 首页 home
  • 数据概览、最新空气排行、资讯入口
• 空气质量列表 kongqizhiliang
  • 支持按省市、日期、质量等级筛选
• 数据分析 air_analysis
  • 全国 / 省级地图、趋势图、排行图、污染物图表
• 趋势预测 climate_forecast
  • 支持 climate 和 air 两类数据集
• 气候数据 climate_data
  • 历史气候记录查询
• 城市信息 city
  • 城市基础信息查询
• 通知公告 news
  • 公告浏览、详情、收藏

10. 预测引擎设计

预测相关代码位于 utils/forecast/。

10.1 当前方法

• ExponentialSmoothing
• ARMAModel
• CombinedForecast

10.2 支持数据集

• climate
  • 预测温度、降水、风速、湿度、AQI、气压等
• air
  • 预测 AQI、PM2.5、PM10、SO2、NO2、CO、O3

10.3 预测接口特性

• 返回变量单位与中文标签
• 自动区分数据集类型
• 为非负值变量做合理约束
• 附带样本时效性元数据
  • recent
  • delayed
  • historical

这部分设计的核心价值是：即使样本不是当天实时数据，系统也会明确告诉前端“这是近端趋势推演还是历史样本推演”，避免把模型结果误读为实时监测值。

11. 数据导入与运维脚本

11.1 空气质量导入

scripts/ 目录下已有多种导入脚本：

• import_kongqizhiliang_excel.py
  • 导入 Excel 历史空气质量数据
• import_kongqizhiliang_csv.py
  • 导入按城市组织的 CSV 空气质量数据
• import_kongqizhiliang_city_daily_csv.py
  • 另一类城市日级 CSV 导入

11.2 资讯导入

• import_air_quality_news.py
  • 从生态环境部等来源抓取空气质量相关资讯
  • 自动生成分类、公告内容和封面图

11.3 地图资源脚本

• download_province_geojson.py
  • 下载省级地图 GeoJSON
  • 供前台地图分析页面使用

11.4 在线补数

• utils/air_quality_sync.py
  • 从远程 CSV 源分段下载最新城市空气质量数据
  • 自动补齐 kongqizhiliang
  • 用于后台“同步最新数据”能力

12. 配置说明

12.1 数据库配置

配置文件：config.ini

关键项：

• type=mysql
• host=localhost
• port=3306
• user=root
• passwd=123456
• db=design_361_air
• hasHadoop=none

12.2 Flask 配置

配置文件：configs.py

关键项：

• 默认端口：8080
• 默认 Host：0.0.0.0
• SQLAlchemy 连接串从 config.ini 读取
• 默认使用开发配置 DevelopmentConfig

12.3 前端配置

• 前端 API 基础前缀：/python0745x1xa/
• 前台系统名：空气质量数据分析与预测系统

13. 运行与构建

13.1 后端启动

cd E:\temp\weather
pip install -r requirements.txt
python manage.py initsql --ini config.ini
python manage.py create_all
python run.py

13.2 前端依赖安装

后台：

cd E:\temp\weather\api\templates\front\admin
npm install

前台：

cd E:\temp\weather\api\templates\front\front
npm install

13.3 前端构建

后台：

cd E:\temp\weather\api\templates\front\admin
npm run build

前台：

cd E:\temp\weather\api\templates\front\front
npm run build

14. 目前的工程特征与风险

14.1 优点

• 核心业务已经切换到空气质量主题，页面和数据结构较统一
• 后台与前台都能直接围绕空气质量、气候数据和城市信息运转
• 预测接口支持双数据集和多模型
• 运维脚本和导入脚本比较齐全

14.2 技术债

• 后端仍保留较多“代码生成式 CRUD”结构，重复度高
• 接口命名存在历史遗留，风格不够统一
• 仍保留 Hadoop / Hive / Spark 等兼容逻辑，增加理解成本
• 前端仍是 Vue2 + Element UI 旧栈，长期维护性一般
• 一部分表和接口已经不在主导航，但仍保留在后端，用于兼容或潜在扩展

14.3 后续建议

• 统一 API 前缀，逐步替换 /python0745x1xa/
• 对 api/main/*_v.py 做二次拆分，区分通用 CRUD 与手写业务逻辑
• 对 utils 目录按主题重组，减少“历史兼容 + 当前业务”混放
• 为空气质量同步、预测和公告导入补上显式运维命令入口
• 若确认不再需要，可继续下线后端中未被前台或后台入口使用的业务表与接口

15. 本次整理后的建议使用方式

• 平时运行项目，直接用现有 dist 即可，不需要 npm install
• 只有在你继续改前端页面时，才重新安装依赖并构建
• 做下一轮“彻底删旧代码”前，建议先以“路由是否可达、接口是否被前端调用、脚本是否被运维使用”三条为准，不要只凭文件名判断

---

如需继续深挖，我下一步可以直接做两件事中的任意一个：

• 输出一份“接口清单版文档”，把每个主要接口的入参和返回结构单独列出来
• 继续做“第二轮瘦身”，把后端中已经没有前端入口、也没有运维脚本依赖的接口模块再缩减一遍