thecont1/traffic-oracle

# traffiCOracle

**traffiCOracle** 是一个面向班加罗尔的免费实时交通仪表盘。它会告诉你目前城市的车流速度有多快（或多慢）——以及今天的交通状况与过去几个月相比如何。 它**无需安装应用、无需登录，背后也没有运行任何服务器**。在任何浏览器中打开它，无论是在手机还是笔记本电脑上，它都能立即运行。所有数据处理都在你的浏览器中完成，并且数据会全天持续从一个公共数据集中实时拉取。 ## 它的用途是什么？ - **通勤者** 决定是现在出发还是等待 30 分钟 - **城市规划者** 和记者寻找历史交通趋势 - **好奇的居民** 想知道今天哪些路线异常拥堵 - **研究人员** 需要可分享的、带永久链接的交通视图 ## 目录 - [功能](#features) - [快速开始](#quick-start) - [数据](#data) - [工作原理](#how-it-works) - [提示与故障排除](#tips--troubleshooting) - [许可证](#license) ## 功能 - **TrafficNOW! — 实时概览** 一个不断更新的侧边栏，显示每条受监控路线的当前速度和状态。路线会根据百分位统计数据（而非简单的平均值）进行颜色编码，从*异常快*到*异常慢*。闪烁的绿点告诉你数据是实时的。 - **用自然语言提问** 选择一条路线、一天中的某个时间段（工作日早上、晚上、周末……）以及一个日期范围，然后选择一个问题：*“交通改善了吗？”*、*“交通变糟了吗？”*或*“典型情况是什么？”* 仪表盘会给出结论、emoji 摘要和迷你趋势图来回答你。 - **基准比较滑块** 拖动滑块来定义你自己的“正常”周。该时间窗口之后的所有数据都将与你自定义的基准进行比较，让你可以看出最近的交通状况是否真的比你认为的典型情况更好或更糟。 - **日历热力图** 一个 GitHub 风格的网格，根据每天的平均速度为每一天标记颜色。看一眼就能知道哪些天是红色的（慢），哪些天是绿色的（快）。 - **每张图表上都有不确定性区间带** 速度和耗时图表显示的不是单条线，而是一个阴影带，代表典型范围（15-85 百分位）和所有可能的范围（5-95 百分位）。这能告诉你某个平均值到底有多*可靠*。 - **三种视觉主题** *Colour me surprised!*（充满活力的深色）、*Scale me gray!*（简洁专业）和 *Clear as day!*（温暖明亮）。只需点击一下即可循环切换；系统会记住你的选择。 - **缩放控制** 顶部的一个胶囊状控件可让你缩放整个 UI（80 % → 115 %），让仪表盘在任何屏幕尺寸或视力偏好下都能提供舒适的体验。 - **移动端伴侣** 在手机上，仪表盘会变身为以路线为主导的滑动体验。选择路线，滑动浏览卡片并分享视图。 - **可分享的 URL** 每个筛选条件、主题、缩放级别和基准选择都会被编码到地址栏中。复制链接，其他人就能看到和你完全一样的视图。 - **天生易于访问** 图表使用图案和线条粗细（而不仅仅是颜色）来传达含义。所有文本和界面元素均符合 WCAG 对比度指南。 ## 快速开始 你**无需**在本地运行任何程序即可使用 traffiCOracle。公共实例可在浏览器中即时加载。 如果你想修改代码或离线运行： ### 前置条件 | 工具 | 用途 | 安装 | |------|---------|---------| | **Bun** | JavaScript runtime 与包管理器 | `curl -fsSL https://bun.sh/install \| bash` | ### 本地运行 ``` # Clone 仓库 git clone https://github.com/thecont1/traffic-oracle && cd traffic-oracle # 安装 dependencies bun install # 启动 development server bun run dev ``` 打开 **http://localhost:5173**。无需数据库，无需 API key，也无需 `.env` 文件——仪表盘会自动获取实时数据。 ### 实用命令 ``` bun run typecheck # Check TypeScript types bun test # Run the test suite bun run build # Build for production bun run deploy # Deploy to Cloudflare Workers ``` ## 数据 ### 数据来源 traffiCOracle 会读取两个 CSV 文件，这些文件由其姊妹项目 **[traffic-monitor-lizard](https://github.com/thecont1/traffic-monitor-lizard)** 发布。该项目使用一个小型自动化脚本每 30 分钟检查一次 Google Maps 的行程耗时，并将结果追加到 GitHub 上的公共 CSV 文件中。traffiCOracle 直接从 GitHub 的 raw-content CDN 获取这些文件。 - **路线文件** — 每条受监控道路的元数据 (`csv-routes-bangalore.csv`) - **交通文件** — 带有时间戳的速度和耗时读数 (`csv-traffic-bangalore.csv`) ### 交通数据列 | 列名 | 示例 | 含义 | |--------|---------|---------| | `date` | `2026-04-01` | 读数记录的日历日期 | | `time` | `08:30` | 一天中的时间（24 小时制） | | `route_code` | `R-100` | 内部路线标识符 | | `label_full` | `Hosur Road` | 易读的路线名称 | | `label_short` | `Hosur Road` | 简短的显示标签 | | `duration` | `35` | 行程耗时（分钟） | | `distance` | `18` | 路线距离（公里） | 根据 `duration` 和 `distance`，traffiCOracle 会为每一行计算**平均速度**（km/h）。 ### 数据质量 在任何数据出现在图表上之前，仪表盘都会静默丢弃未通过常规逻辑检查的行： - 耗时超过 5 小时的行程 (`duration > 300`) - 速度超过 150 km/h（在城市交通中是不可能的） - 无法读取或缺失的日期 - 缺失距离值（默认设为 10 km 以免程序崩溃） 验证通过后，数据行会按周和按天进行聚合，并根据你选择的路线和时间段进行过滤。 ### 更新频率 - **首次加载** 会下载完整的历史数据集（数万行）。 - **后台刷新** 每隔几分钟检查一次新数据。如果 GitHub 上的 CSV 发生变化，只会下载新行并合并到系统中。 - **当标签页处于隐藏状态时** 轮询会暂停以节省带宽和电池电量；当你返回时它会自动恢复。 ## 工作原理 traffiCOracle 是一个**无后端**（zero-backend）的 React 应用。这意味着没有私人服务器保存你的数据，没有登录门槛，也没有需要配置的 API key。 ``` Your Browser │ ├─► fetches CSV from GitHub (public raw URLs) │ ├─► parses the CSV inside the browser │ ├─► validates, cleans, and aggregates the numbers │ └─► draws charts, cards, and maps ``` 从下载原始 CSV 到渲染出最终的图表像素，一切都在你的设备上发生。唯一的外部依赖是存储原始交通读数的公共 GitHub repository。 ### 为什么百分位很重要 城市交通并不呈正态分布：大多数行程都集中在“典型”速度附近，但一次事故就能产生大量速度极慢的行程。简单的平均值会掩盖这一点。traffiCOracle 使用**百分位数**（percentiles）——这与 INRIX 和 TomTom 等专业交通服务所采用的方法相同——因此“典型”区间能真正代表大多数通勤者的体验。

标签：云安全态势管理, 交通监控, 仪表盘, 前端应用, 时间序列分析, 智慧出行, 程序员工具, 自动化攻击