# traffic_status_display_backend

**Repository Path**: zhang-junah/traffic_status_display_backend

## Basic Information

- **Project Name**: traffic_status_display_backend
- **Description**: 本后端服务是高德交通态势数据大屏展示系统的核心数据处理引擎。系统专注于“天源路”及其周边路段（广汕立交桥至京珠高速出入口）的实时交通状况监测与分析。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-17
- **Last Updated**: 2026-05-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: ollama, FastAPI, 数据大屏, MySQL, 自动生成报告

## README

# 高德交通态势数据大屏后端服务

[![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green.svg)](https://fastapi.tiangolo.com/)
[![MySQL](https://img.shields.io/badge/MySQL-8.0.4-orange.svg)](https://www.mysql.com/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

![image-20260317180253699](./assets/image-20260317180253699.png)

## 📖 项目简介

> 请注意，本项目开团的文件中还缺失定时任务开发模块和封装的所有高德开放平台API模块文件，因为涉及到我自己的key在里面，所以如果你有需要，可以自行实现。

> 如果你有其他定制化需求或者去密后的API模块，请联系微信20元获取， 微信号：**traffic_zhang**。


本后端服务是**高德交通态势数据大屏展示系统**的核心数据处理引擎。系统专注于“天源路”及其周边路段（广汕立交桥至京珠高速出入口）的实时交通状况监测与分析。

主要功能包括：
- **实时数据采集**：定时同步高德开放平台路况数据。
- **核心指标计算**：提供畅通、缓行、拥堵等关键指标的实时与历史查询接口。
- **智能分析报告**：基于本地部署的大模型（Qwen3-vl）自动生成每日交通态势分析 Word 报告。
- **数据持久化**：使用 MySQL 存储历史交通数据及报告元数据，支持趋势分析。

## 🛠️ 技术栈

- **开发语言**: Python 3.9+
- **Web 框架**: FastAPI (异步高性能)
- **数据库**: MySQL 8.0.4
- **AI 推理引擎**: Ollama + Qwen3-vl:4b (本地部署)
- **文档处理**: `python-docx` (生成分析报告)
- **定时任务**: `schedule` 库
- **依赖管理**: Pip / Requirements.txt

## 🏗️ 系统架构

系统采用前后端分离架构，后端主要承担以下职责：

1.  **数据采集服务 (Data Collector)**: 负责调用高德 API，清洗并持久化交通数据。
2.  **核心指标接口服务 (Core Metrics API)**: 为前端大屏提供 RESTful 数据接口。
3.  **智能分析报告服务 (AI Report Service)**: 聚合当日数据，调用本地大模型生成分析文本并导出 Word 文档。

## 🚀 快速开始

### 前置要求

- Python 3.9 或更高版本
- MySQL 8.0.4 数据库实例
- 本地部署 Ollama 并拉取模型：`ollama pull qwen3-vl:4b`
- 高德开放平台 API Key（如何申请请百度）

### 安装步骤

1. **安装依赖**
    ```bash
    # 为了确保程序可以正常运行，我推荐是使用python3.9环境进行安装。
    pip install -r requirements.txt
    ```

2. **配置数据库连接**
    在mysql_config.py中修改配置数据库连接信息
    ```cmd
    ASYNC_DATABASE_URL = "mysql+aiomysql://用户名:密码@数据库地址:端口/traffic_demo"
    ```

3. **数据库初始化**
    确保 MySQL 中已创建 `traffic_demo` 数据库。

4. **启动服务**
    ```bash
   # 你也可以在安装好依赖后直接启动main文件，默认9999端口，也可以运行下列命令启动。
    uvicorn main:app --host 0.0.0.0 --port 9999 --reload
   ```

## 📡 API 接口文档

启动服务后，访问 `http://localhost:8000/docs` 查看完整的 Swagger UI 交互式文档。

### 核心接口概览

| 方法 | 路径 | 描述 |
| :--- | :--- | :--- |
| `GET` | `/api/metrics/realtime` | 获取最新实时路况指标（畅通/缓行/拥堵比例） |
| `GET` | `/api/metrics/trend` | 获取指定时间段内的指标变化趋势 |
| `GET` | `/api/roads/detail` | 获取特定路段（如京珠高速出入口）的详细速度与状态 |
| `POST` | `/api/reports/generate` | 手动触发当日交通分析报告生成任务 |
| `GET` | `/api/reports/list` | 获取历史生成的报告列表及下载链接 |

## 💾 数据库设计

数据库名称：`traffic_demo`

### 1. 线路综合交通态势数据表 (`traffic_info`)
*每 30 分钟采集一次*

| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `id` | int | 主键 |
| `road_name` | varchar | 线路名称 |
| `expedite` | float | 畅通百分比 |
| `congested` | float | 缓行百分比 |
| `blocked` | float | 拥堵百分比 |
| `status` | smallint | 整体路况 (0:未知, 1:畅通, 2:缓行, 3:拥堵) |
| `create_time` | datetime | 创建时间 |

### 2. 道路信息表 (`roads`)
*关联线路 ID，存储细分道路数据*

| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `line_id` | int | 外键，关联 `traffic_info.id` |
| `name` | varchar | 道路名称 |
| `speed` | float | 平均速度 |
| `polyline` | text | 道路经纬度坐标 (用于地图绘制) |
| `direction` | varchar | 方向描述 |

## 🤖 智能报告生成流程

1.  **触发**: 每日定时任务或手动 API 调用。
2.  **聚合**: 从 `traffic_info` 和 `roads` 表提取当日全量数据。
3.  **推理**: 构建 Prompt 发送至本地 Ollama (Qwen3-vl:4b)。
4.  **生成**: 接收 AI 分析文本，利用 `python-docx` 格式化生成 Word 文档。
5.  **存储**: 文件保存至服务器磁盘，路径记录于数据库供前端下载。

## 📦 部署建议

- **生产环境**: 建议使用 Gunicorn 配合 Uvicorn Worker 启动 FastAPI。
  ```bash
  gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker
  ```
- **定时任务**: 建议使用系统级 Cron 或 Supervisor 管理后台数据采集与报告生成脚本，确保进程守护。
- **网络**: 服务器需确保能访问高德 API 及本地 Ollama 服务端口 (默认 11434)。

## 📄 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

---
*注：本后端服务需配合前端 Vue3 大屏项目共同运行，以实现完整的交通态势可视化效果。*