城市交通流量预测与拥堵成因分析系统

本文档说明 code/ 目录内的工程组成、功能边界与文件结构，不包含任何运行或部署步骤。

---

1. 项目定位

code/ 是一个面向城市交通拥堵分析的 monorepo，覆盖计算机设计课题中的主要能力链路：

课题要求	工程落点
处理时空交通数据（出租车、地铁、天气、事件等）	data-pipeline/
短期交通流量 / 拥堵预测	model/stgnn/ + backend/stgnn_store.py
拥堵关键因素 / 归因分析	model/attribution/ + model/congestion_rules/
交互式地理信息可视化	frontend/ + 地图相关 API
统一业务服务与数据出口	backend/

业务预测与地图展示以 离线训练产物 为准：API 不做在线模型推理，启动时加载 CSV/JSON 等结果文件。

---

2. 总体架构

┌─────────────────────────────────────────────────────────────────┐
│                        frontend/                               │
│   Web 仪表盘 · Leaflet 地图 · ECharts 图表 · 多页业务视图        │
└────────────────────────────┬────────────────────────────────────┘
                             │ HTTP  /api/v1/*
┌────────────────────────────▼────────────────────────────────────┐
│                        backend/                                  │
│   FastAPI · 鉴权/缓存 · DataRepository · 坐标系转换(GCJ-02)      │
└─────┬──────────────────────┬──────────────────────┬─────────────┘
      │                      │                      │
      ▼                      ▼                      ▼
 data-pipeline/          model/                 alignment/config/
 特征表与清洗对齐          训练脚本与离线产出        路段几何·路网·注册表

数据主链路（逻辑顺序）：

ingest → governance → alignment → features → feature_table.csv
                                              ↓
                         model（stgnn / attribution / baseline / deep）
                                              ↓
                         backend 读取产物 → frontend 展示

---

3. 功能说明

3.1 数据流水线（data-pipeline/）

• 接入（ingest）：多源 CSV（出租车分区、地铁站点客流、天气、活动事件）接入与 schema 校验。
• 治理（governance）：缺失、异常、重复等规则处理，输出清洗表与 reject 明细。
• 对齐（alignment）：Zone/Station 映射到统一路段 SEG-* 与网格 GRID-*；支持路段几何配置。
• 特征（features）：按时间窗聚合，生成模型使用的 feature_table.csv。
• 质量（quality）：数据质量评分与看板产出。
• schema：跨源字段与口径相关脚本与产出。

3.2 模型与算法（model/）

子目录	作用
stgnn/	主业务预测：时空邻域特征 + Ridge 回归（README 称 STGNN Proxy），产出 predictions.csv、forecast.csv、metrics.json
attribution/	拥堵成因分析：线性模型系数导出为 shap_like_values.csv，供后端按路段排序展示
congestion_rules/	拥堵识别规则标定与评估配置
baseline/	基线模型（ARIMA / 树模型等）对比实验
deep/	LSTM/GRU 等深度模型对比实验
registry/	模型注册与回滚相关元数据

说明：目录名 STGNN 表示时空预测模块；当前实现为代理模型（表格特征 + 邻域统计），非 PyTorch 图卷积网络在线训练服务。

3.3 后端服务（backend/）

• REST API：概览、路段趋势、预测、归因、热力图层、拥堵事件、路段几何等。
• 数据仓库：data.py 中 DataRepository 统一读取特征表、STGNN 预测、归因、路段几何。
• 离线存储适配：stgnn_store.py、attribution_store.py 加载 model/*/output 下文件。
• 坐标转换：coord_transform.py 将 OSM 路段几何由 WGS84 转为 GCJ-02，与高德等国内底图对齐。
• 认证与运维向能力：JWT/RBAC（auth.py）、Redis 缓存（cache.py）、审计与错误码（audit.py、error_codes.py）、异步任务占位（tasks.py）、OpenAPI 导出（export_openapi.py、openapi.json）。
• 测试：tests/ 下接口自动化、性能、调度、审计等 runner 及结果 JSON。

3.4 前端应用（frontend/）

单页应用（index.html + assets/app.js + assets/styles.css），主要视图包括：

• 路况总览：地图路段着色、流量对比、时间趋势。
• 拥堵归因：成因贡献与排序（对接归因 API）。
• 流量预测：历史与未来窗口、误差指标、地图时间回放。
• 数据说明：口径与交互说明。

地图：Leaflet + 国内底图（高德 / GeoQ）；路段线来自 /api/v1/map/segments/geometry。

3.5 路网与空间数据（data-pipeline/alignment/config/）

黄浦区真实路网相关材料（OpenStreetMap）：

文件	说明
segment_geometry.json	101 条业务路段 SEG-1001～SEG-1101 的折线坐标（源文件为 WGS84，后端对外转为 GCJ-02）
segment_registry.csv	路段 ↔ OSM way ↔ 路名 ↔ 匹配质量
road_segments.geojson	黄浦区 OSM 道路全集
osm_raw/huangpu_roads_overpass.json	Overpass 原始下载
黄浦区路网数据说明.md	数据来源、许可与核对说明
segment_route_verification.csv / segment_route_verification_report.md	101 条路段自动核对结果

相关脚本：alignment/scripts/build_huangpu_road_materials.py、verify_segment_routes.py、segment_geometry_builder.py。

3.6 运维与工程化（ops/、scripts/、.github/）

• ops/：多环境配置（dev/test/prod）、Docker Compose、部署/冒烟 PowerShell 脚本、监控与应急预案文档、运行日志与制品清单。
• scripts/（根目录）：路段检查、合成数据生成、前端几何同步等辅助脚本；scripts/ci/ 为 CI 冒烟。
• .github/workflows/：发布与文档类自动化（如打包说明文档与任务 CSV）。

3.7 过程文档与协作资产（不参与运行时）

路径	说明
execution/	按里程碑 M1～M5、改版 S1～S5 存放实施说明、评审记录、验收 JSON、工作日志
jira_import_tasks.csv	Jira 看板导入用任务清单（项目管理）
trello_import_tasks.csv	Trello 看板导入用任务清单
模型训练.md	数据流水线与模型训练的专题说明（含路径索引）
mac_run.sh	本地一键启动脚本（运维便利，非业务逻辑）
requirements.txt	Python 依赖清单（Web 服务为主）
.venv/	本地虚拟环境（依赖安装目录，非业务源码）
.playwright-cli/	前端 E2E / 截图调试残留
报告/	若存在，为项目报告类附件目录

---

4. 目录结构一览

code/
├── 项目说明.md                 # 本文件
├── 模型训练.md                 # 训练与数据路径专题说明
├── requirements.txt
├── mac_run.sh
├── jira_import_tasks.csv       # 项目管理导入（非运行时）
├── trello_import_tasks.csv     # 项目管理导入（非运行时）
│
├── data-pipeline/              # 数据流水线
│   ├── ingest/                 # 接入：samples、staging、schemas、config
│   ├── governance/             # 治理：清洗结果、reject
│   ├── alignment/              # 对齐：spatial_mapping、几何、aligned_records
│   ├── features/               # 特征：feature_table.csv
│   ├── quality/                # 质量评分
│   └── schema/                 # 字段/schema 相关
│
├── model/                      # 离线模型训练与产物
│   ├── stgnn/                  # 主预测（scripts + output）
│   ├── attribution/            # 归因（scripts + output）
│   ├── congestion_rules/       # 拥堵规则
│   ├── baseline/               # 基线对比
│   ├── deep/                   # 深度模型对比
│   └── registry/               # 模型注册信息
│
├── backend/                    # FastAPI 后端
│   ├── app.py                  # 应用入口与路由
│   ├── data.py                 # 业务数据聚合
│   ├── stgnn_store.py          # STGNN 离线结果加载
│   ├── attribution_store.py    # 归因结果加载
│   ├── coord_transform.py      # WGS84 ↔ GCJ-02
│   ├── auth.py / cache.py / audit.py / …
│   ├── openapi.json
│   ├── tests/                  # 接口与质量门禁脚本
│   └── logs/                   # 审计日志等
│
├── frontend/                   # 静态 Web 前端
│   ├── index.html
│   ├── assets/
│   │   ├── app.js              # 主逻辑（地图、图表、API）
│   │   └── styles.css
│   ├── README.md
│   └── tests/                  # 前端检查 / E2E runner
│
├── ops/                        # 环境、部署、监控、预案
├── scripts/                    # 根级辅助脚本
├── execution/                  # 里程碑与改版过程文档
├── .github/workflows/          # CI/CD 工作流
└── 报告/                       # 报告附件（若有）

---

5. 核心数据与产物文件

文件	用途
data-pipeline/features/output/feature_table.csv	特征主表，模型训练与分析的输入
data-pipeline/alignment/output/aligned/aligned_records.csv	时空对齐后的记录
data-pipeline/governance/output/clean/*.csv	清洗后的各数据源
model/stgnn/output/predictions.csv	路段历史/当前预测序列
model/stgnn/output/forecast.csv	未来时间窗预测
model/stgnn/output/metrics.json	STGNN 模块评估指标
model/attribution/output/shap_like_values.csv	路段特征贡献（归因）
data-pipeline/alignment/config/segment_geometry.json	地图路段折线
data-pipeline/alignment/config/segment_registry.csv	路段与真实道路对照

---

6. 业务标识约定

• 路段 SEG-1001～SEG-1101：101 个统一空间分析单元，贯穿特征表、预测结果与地图。
• 网格 GRID-*：出租车 / 地铁 / 天气 / 事件在配置中的空间别名（见 alignment/config/spatial_mapping.json）。
• 预测服务：读取 SEG-* 级离线 CSV，按时间窗展示拥堵等级、流量指数等派生指标。

---

7. 与课题的对应关系（摘要）

• 已实现且可演示：多源数据处理链路、短期预测展示、归因与规则模块、交互地图与图表、黄浦区 OSM 真实路网叠图、后端统一 API。
• 需在文章中说明边界之处：
  • 样本数据可为演示 CSV，可替换为真实开放数据；
  • STGNN 为时空代理回归模型，图结构基于路段编号邻域而非完整路网图神经网络；
  • 出租车等为分区/站点级聚合，非原始 GPS 轨迹级存储。

---

8. 文档索引

文档	位置
后端 API 说明	backend/README.md
前端页面与接口依赖	frontend/README.md
对齐与路网导入	data-pipeline/alignment/README.md
STGNN 模块	model/stgnn/README.md
归因模块	model/attribution/README.md
拥堵规则	model/congestion_rules/README.md
运维总览	ops/README.md
黄浦区路网说明	data-pipeline/alignment/config/黄浦区路网数据说明.md
多 Agent 执行手册	execution/00_多Agent执行总控手册.md

---

文档描述范围仅限 code/ 目录内工程内容；仓库根目录及其他目录不在本文件范围内。