mywienerlinien

# 维也纳交通 - 双标准应用 <p align="center"> <a href="https://github.com/casey/just"><img src="https://img.shields.io/badge/just-ready_to_go-7c5cfc?style=flat-square&logo=just&logoColor=white" alt="Just"></a> <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a> <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.13+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a> <a href="https://github.com/PrefectHQ/fastmcp"><img src="https://img.shields.io/badge/FastMCP-3.2-7c5cfc?style=flat-square" alt="FastMCP"></a> </p> > 📖 **[安装指南](INSTALL.md)** — 快速启动，手动设置和故障排除 **最近更新：** 2025-12-27 **状态：** 生产就绪 | SOTA 合规 | 功能齐全 **版本：** 2.0.1（阶段 1-5 完成 + 模式迁移） 一个全面的维也纳公共交通应用程序，具有 **两个互补的接口**： - **网页应用**: 交互式实时地图，显示出发信息 - **MCP 服务器**: Claude Desktop 的 AI 助手集成（SOTA 合规） **重要注意：** 由于维也纳交通局 API 的限制，地图显示 **站点出发事件** 而不是实时 GPS 车辆位置。这是官方 API 提供的实时信息。 两个接口共享相同的后端逻辑和数据源，在网页和 AI 平台上提供统一的体验。 --- ## 快速启动 ```powershell git clone https://github.com/sandraschi/mywienerlinien cd mywienerlinien just ``` 这将打开一个交互式仪表板，显示所有可用的命令。运行 `just bootstrap` 安装依赖项，然后运行 `just serve` 或 `just dev` 启动。 ### 手动设置 如果您没有安装 `just`: ## 快速启动 ### Docker（推荐 - 带有热重载！） ```powershell # 启动所有服务 docker compose up -d # 前端：http://localhost:3079 # Grafana：http://localhost:3140 # 开发（即时代码更改）： # 编辑文件 更改自动重载，1 秒内！ # 参见 DOCKER_DEV_GUIDE.md 获取详细信息 ``` ### 原生开发（最快迭代） ```powershell # 在 Docker 外运行前端，带有热重载 .\run_dev.ps1 # 前端：http://localhost:3080（带有即时重载） # 连接到 Docker 数据库，端口 5433 ``` --- ## SOTA 功能 ### MCP 服务器（SOTA 满分 10/10） **FastMCP 3.1.0 合规** - **12 个生产就绪工具**：所有工具都已完全实现，具有实际功能 - **5 个 AI 提示**：为 Claude 提供全面的指导 - **5 个资源**：交通系统参考数据 - **超快启动**：3-5 秒（之前为 67 秒） - **多城市就绪**：第 6 阶段城市管理工具 - **实时 GTFS 路径规划**：带有多个换乘支持的 A* 路径查找 - **机器学习预测**：使用随机森林的延迟预测（第 3C 阶段） - **多城市支持**：多个城市的框架（第 4 阶段） 参见 `SOTA_CHECKLIST.md` 获取详细的合规报告。 --- ## 最近更新（2025 年 12 月） ### **数据库模式迁移完成** - **修复关键模式不匹配** 应用程序代码和数据库之间的不匹配 - **迁移城市表** 从旧模式（`name`、`country`）到新第 4 阶段模式（`city_code`、`city_name`、`map_center_lat` 等） - **应用维也纳城市配置** 具有正确的坐标（48.2082，16.3738）和元数据 - **增强健康检查** 具有改进的超时处理（30 秒超时，40 秒启动周期） ### **完整数据加载验证** - **4,684 个站点** - 完整的维也纳交通站网络 - **1,138 条线路** - 所有地铁、 трамвай 和公交线路 - **562,609 次行程** - 全面的调度数据 - **10,629,882 次站点时间** - 完整的时刻表数据库 - **实时车辆跟踪** - 51+ 辆活跃车辆正在监控 ### **系统状态：功能齐全** - **后端 API**：所有端点都响应实时数据 - **WebSocket 连接**：主动实时更新 - **MCP 服务器**：12 个工具，5 个提示，5 个资源 - 可用于 Claude Desktop - **数据库**：PostgreSQL/PostGIS，具有空间索引 - **监控**：http://localhost:3140 上的 Grafana 仪表板 **应用程序现已生产就绪，包含完整的维也纳交通数据和所有功能！** --- ## 架构概述 ### FastAPI 网页应用 - **目的**：用于实时交通可视化的人性化网页界面 - **传输**：HTTP/WebSocket - **位置**：`frontend/app.py` - **功能**： - 交互式地图，显示实时车辆位置（198 行） - 不同交通类型的颜色编码标记（U-Bahn，tram，bus） - 按类型或线路编号过滤车辆 - 每 15 秒自动刷新 - 桌面和移动设备的响应式设计 - 实时 WebSocket 更新 - PWA 支持（离线能力，可安装） - 收藏系统（基于 localStorage） - 高级过滤和排序 - 分析仪表板（Chart.js 可视化） ### FastMCP MCP 服务器（原生运行，非 Docker） - **目的**：用于自然语言交通查询的 AI 助手集成 - **传输**：stdio（用于 Claude Desktop） - **位置**：`frontend/mcp_server/` - **执行**：在主机上原生运行（连接到 Docker 数据库） - **为什么原生**：stdio 传输需要直接进程通信 - **功能**： - **9 个核心工具**：出发、搜索、行程规划、状态、帮助、警报、时刻表、附近、服务器状态 - **5 个提示**：用于维也纳交通的 AI 助手指导 - **5 个资源**：交通系统参考数据 - **FastMCP 3.1.0 合规**（SOTA） - **Google 风格的文档字符串** - **基于 GTFS 的实时路径规划**，使用 A* 路径查找 - **机器学习延迟预测**（第 3C 阶段） - **多城市架构**（第 4 阶段） - **生产错误处理** ### 共享后端 两个接口使用相同的核心模块： - `data_loader.py` - GTFS 数据加载和站点管理 - `database.py` - PostgreSQL/PostGIS 数据库层 - `vehicle_service.py` - 实时车辆数据收集 - `disruption_alerts.py` - 服务中断监控 - `routing_service.py` - 用于行程规划的 A* 路径查找 - `graph_service.py` - 交通图构建 - `realtime_service.py` - 实时延迟集成 - `prediction_service.py` - 基于机器学习的延迟预测（第 3C 阶段） - `city_manager.py` - 多城市支持（第 4 阶段） --- ## 阶段实施状态 ### 第一阶段：核心基础设施（完成） - GTFS 数据加载和处理 - 实时车辆跟踪 - 交互式地图，198 行 - PostgreSQL/PostGIS 数据库 - Docker 容器化 ### 第二阶段：PWA 和收藏（完成） - Progressive Web App 支持 - 服务工作线程，用于离线能力 - 应用清单，用于可安装性 - 使用 localStorage 的收藏系统 - 移动优化 - 地理位置集成 ### 第三阶段 A：高级路径规划（完成） - A* 路径查找算法 - 交通图构建 - 多次换乘支持 - 实时延迟集成 - 行程比较 ### 第三阶段 B：高级过滤（完成） - 线路类型过滤（地铁，tram，总线） - 方向过滤 - 区域过滤 - 无障碍过滤 - 基于时刻表的过滤 ### 第三阶段 C：机器学习和分析（完成） - 历史数据收集 - 机器学习延迟预测（随机森林/梯度提升） - 使用 Chart.js 的分析仪表板 - 智能通知 - 模型训练脚本 ### 第四阶段：多城市支持（完成） - 城市配置框架 - 城市表的数据库迁移 - 城市切换 API - 支持多个奥地利城市 - 具有速率限制的公共 API ### 第五阶段：集成功能（完成） - 天气集成（OpenWeatherMap） - 日历集成 - 社交功能（用户生成的内容） - 社区仪表板 --- ## 安装 ### 先决条件 - [uv](https://docs.astral.sh/uv/) 已安装（推荐） - Python 3.12+ ### 快速启动 立即通过 `uvx` 运行： ```bash uvx vienna-transit-mcp ``` ### Claude Desktop 集成 添加到您的 `claude_desktop_config.json`： ```json "mcpServers": { "vienna-transit-mcp": { "command": "uv", "args": ["--directory", "D:/Dev/repos/mywienerlinien", "run", "vienna-transit-mcp"] } } ``` ### 先决条件 - Python 3.9 或更高版本 - Docker 和 Docker Compose - 带有 PostGIS 的 PostgreSQL 16+（通过 Docker） ### 快速安装 ```powershell # 克隆仓库 git clone https://github.com/yourusername/mywienerlinien.git cd mywienerlinien # 使用 Docker 启动（推荐） docker compose up -d # 或安装用于原生开发 pip install -e . ``` --- ## 用法 ### 1. Docker（生产 + 开发） ```powershell # 启动所有服务 docker compose up -d # 查看日志 docker compose logs -f frontend # 代码更改后重启（快速重建 - 10 秒） docker compose restart frontend # 停止所有服务 docker compose down ``` **启用热重载！** 编辑 Python/HTML/CSS 文件 更改立即生效！ ### 2. 原生开发（最快） ```powershell # 直接运行前端（连接到 Docker 数据库） .\run_dev.ps1 # 前端运行在 http://localhost:3080 # 文件更改时立即重载！ ``` 参见 `DOCKER_DEV_GUIDE.md` 获取全面的开发工作流程。 ### 3. MCP 服务器（Claude Desktop / Cursor IDE - 原生执行） **重要：** - MCP 服务器原生运行（不在 Docker 中） - 入口点：`frontend.mcp_server.server`（模块执行） - 连接到 `localhost:5433` 上的 Docker 数据库 **为什么原生：** MCP 使用 stdio 传输，需要直接进程通信。Docker stdio 管道复杂且脆弱。原生执行更简单。 #### 对于 Cursor IDE **重要：** Cursor 使用系统 Python。 在 Cursor 使用的 Python 中安装依赖项： ```powershell # 查找系统 Python 路径（如果需要，请检查 Cursor 错误日志） # 示例：C:\Users\sandr\AppData\Local\Programs\Python\Python310\python.exe python -m pip install -e . ``` 参见 `CURSOR_SETUP.md` 获取详细的 Cursor 配置说明。 #### 对于 Claude Desktop 添加到 `claude_desktop_config.json`: ```json { "mcpServers": { "vienna-transit": { "command": "python", "args": ["-m", "frontend.mcp_server.server"], "env": { "PYTHONPATH": "D:/Dev/repos/mywienerlinien", "PYTHONUNBUFFERED": "1", "DATABASE_URL": "postgresql://wienerlinien:wienerlinien@localhost:5433/wienerlinien" } } } } ``` **注意：** 一些 JSON linter 对 `cwd` 参数提出异议。使用 `-m` 模块执行并使用 `PYTHONPATH` 避免此问题。 --- ## MCP 工具（共 12 个） ### 基础工具 1. **`help`** - 获取有关 MCP 工具和维也纳交通的帮助 2. **`server_status`** - 检查 MCP 服务器的健康状况和配置 ### 多城市管理（第 6 阶段） 3. **`list_cities`** - 列出所有可用的交通城市及其状态 4. **`switch_to_city`** - 切换用于交通查询的活跃城市 5. **`city_transit_stats`** - 获取城市交通系统的综合统计数据 ### 搜索和发现 6. **`station_search`** - 按名称查找站点（模糊匹配） 7. **`nearby_stops`** - 查找附近的站点（地理位置） ### 实时信息 8. **`next_departures`** - 获取任何站点的实时出发信息 9. **`traffic_alerts`** - 检查服务中断和警报 10. **`line_status`** - 获取特定交通线路的状态 ### 时刻表和规划 11. **`stop_timetable`** - 获取站点的完整时刻表 12. **`journey_planner`** - 使用 A* 路径查找规划最佳路线 --- ## 当前状态 ### 数据库 - **GTFS 导入**：25-50 倍更快（13 小时 -> 15-30 分钟） - **性能**：优化的触发器、索引和批量插入 - **第 4 阶段迁移**：城市表和多城市模式 ### 实时馈送 - **车辆跟踪**：功能齐全（198 行） - **RBL 映射**：使用监控 ID 增强 GTFS 站点 - **API 限流**：尊重维也纳交通局的速率限制 - **延迟集成**：路由中的实时延迟 ### 机器学习功能（第 3C 阶段） - **历史数据**：车辆快照和行程记录 - **预测模型**：随机森林/梯度提升 - **分析**：具有可视化的仪表板 - **训练**：CLI 工具用于模型训练 ### 端口（本地） - 前端：http://localhost:3079（Docker）或 :3080（原生） - Grafana：http://localhost:3140 - PostgreSQL：localhost:5433 - Loki：localhost:3193 --- ## Docker 开发提示 ### 热重载（零重建！） ```powershell # 编辑任何 .py/.html/.css 文件 # 更改立即生效！无需重建！ ``` ### 常规重建（10 秒） ```powershell # 对于 Python 代码更改 docker compose restart frontend # 快速！使用缓存！ ``` ### 完整重建（仅限依赖项更改！） ```powershell # 仅当 requirements.txt 更改时！ docker compose down docker compose build frontend docker compose up -d ``` **永远不要使用 `--no-cache` 进行代码更改！** （浪费 15+ 分钟） 参见 `DOCKER_DEV_GUIDE.md` 和 `DOCKER_GUIDE_COMPLETE.html` 获取详细信息。 --- ## 测试 ### MCP 服务器测试 ```powershell # 测试导入 python test_mcp.py # 运行数据库 $env:DATABASE_URL = "postgresql://wienerlinien:wienerlinien@localhost:5433/wienerlinien" python -m frontend.mcp_server.server` ``` 参见 `docs/MCP_TESTING_GUIDE.md` 获取全面的测试场景。 ### 网页应用测试 1. 打开 http://localhost:3079 2. 验证所有 198 条线路在地图上可见 3. 测试过滤器（地铁，tram，总线） 4. 测试实时更新 --- ## 文档 ### 核心文档 - `README.md` - 本文件（概述和设置） - `frontend/mcp_server/README.md` - MCP 服务器详细信息 - `SOTA_CHECKLIST.md` - SOTA 合规报告 - `docs/MCP_TESTING_GUIDE.md` - 测试指南 - `docs/RULEBOOK.md` - 开发指南 ### Docker 文档 - `DOCKER_DEV_GUIDE.md` - 本地开发指南 - `DOCKER_GUIDE_COMPLETE.html` - 交互式指南（带有 TOC） - `DOCKER_UI_GUIDE.md` - Docker Desktop UI 解决方法 ### 阶段文档 - `docs/gtfs-loader-fix.md` - GTFS 性能优化 - `docs/STATUS-2025-01-15.md` - 实现状态 - `todo.md` - 功能路线图 ### API 文档 - `docs/PUBLIC_API.md` - 公共 API 文档 - `docs/mcp-architecture.md` - MCP 架构详细信息 --- ## 维也纳交通局 API ### 端点 - `/monitor` - 实时出发信息和车辆位置 - `/trafficInfoList` - 服务中断 - `/newsList` - 新闻和公告 ### 公平使用政策 - 只查询必要的站点 - 最小 15 秒间隔 - 尊重速率限制（使用缓存实现） **2024 年无需 API 架构详细信息 --- ## 开发指南 ### 代码质量 ```powershell # 使用 Ruff 进行 linting ruff check . ruff check . --fix` # 格式化 ruff format . # 类型检查 mypy frontend/mcp_server/ --ignore-missing-imports` ``` ### Pre-commit Hooks ```powershell # 安装 pip install pre-commit pre-commit install` # 手动运行 pre-commit run --all-files` ``` 所有代码必须通过 ruff 检查且零警告。 ### 关键规则 - 全面的错误处理 - 关键操作的正确日志记录 - 尊重 API 速率限制 - 遵循 PEP 8 标准 - 包括新功能的测试 参见 `docs/RULEBOOK.md` 获取完整指南。 --- ## 部署 ### Docker 生产环境 ```powershell # 生产环境构建 docker compose -f docker-compose.prod.yml up -d` # 带有 Grafana 监控 docker compose -f docker-compose.yml up -d` ``` ### 环境变量 ```bash DATABASE_URL=postgresql://user:pass@host:5433/wienerlinien APP_ENV=production OPENWEATHER_API_KEY=your_key_here` ``` --- ## 贡献 1. 阅读 [规则手册](docs/RULEBOOK.md) 2. 遵循代码质量标准 3. 在提交前运行 `ruff check .` 4. 彻底测试 5. 更新文档 --- ## 🛡️ 工业质量堆栈 该项目遵循 **SOTA 14.1** 高保真代理编排的工业标准： - **Python（核心）**：使用 Ruff 进行 linting 和格式化。核心处理程序中禁止使用 `print` 语句（`T201`）。 - **Webapp（UI）**：使用 Biome 进行毫秒级 linting。严格执行 `noConsoleLog`。 - **协议合规性**：强化 `stdout/stderr` 隔离，以确保崩溃抗性 JSON-RPC 通信。 - **自动化**：使用 Justfile 的配方进行所有舰队操作（`just lint`、`just fix`、`just dev`）。 - **安全性**：使用 `bandit` 和 `safety` 进行自动审计。 ## 许可 安诺伊纳顿海狸项目收藏的一部分。 **数据源：** 维也纳交通局 - https://www.wienerlinien.at/open-data **许可：** 知识共享署名 4.0 国际 (CC BY 4.0) --- ## 致谢 - **维也纳交通局** 提供开放数据 API - **FastMCP** 提供 MCP 协议实现 - **Claude AI** 提供开发协助 - **GTFS 社区** 提供交通数据标准 --- **维也纳交通系统已符合 SOTA 标准且生产就绪！**