Easy-Vibe 实战：基于 Go 构建交通数据分析平台——数据接入、窗口聚合、告警与可视化全链路

Easy-Vibe 实战：基于 Go 构建交通数据分析平台——数据接入、窗口聚合、告警与可视化全链路

【免费下载链接】easy-vibe💻 vibe coding 101｜The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe

导读

本文以 Easy-Vibe 课程 Stage 2 综合实战《Go Traffic Data Analysis Platform》为主线，讲解如何围绕一份真实的 PRD，用 Go（Gin 或 Fiber）+ PostgreSQL 从零搭建一条「数据接入 → 聚合 → 告警 → 可视化」的完整数据链路。与普通增删改查系统不同，这类数据产品在 IoT、监控、运营分析场景中非常普遍。读完本文，你将掌握：如何从 PRD 提取数据产品开发任务清单、如何搭建 Go API 服务骨架、如何设计窗口聚合与告警规则，以及如何完成端到端联调并交付一个可演示的数据产品原型。

实战背景与定位

这是 Easy-Vibe Stage 2（Junior Developer 阶段）的扩展实战项目，定位是数据产品而非业务管理系统。项目在 Stage 2 学习地图中的位置见 docs/en/stage-2/index.md，官方描述为"Build a complete data product with ingestion, windowed aggregation, trend dashboards, and alerting"。

本实战是学习者第一次接触 Go。课程明确强调：不必担心语言门槛——基于 JavaScript / TypeScript 基础学习 Go 并不难，核心在于理解数据链路的设计思路，而不是单纯堆砌 CRUD 接口。

实战的四个模块与职责如下（摘自关联文档）：

学习目标

完成本实战后，你将能够：

1. 阅读 PRD 并提取数据产品的开发任务清单；
2. 使用 Go（Gin 或 Fiber）搭建后端 API 服务；
3. 设计数据接入、窗口聚合和告警的完整链路；
4. 保持后端数据与前端看板的一致性；
5. 完成端到端联调，交付可演示的数据产品原型。

前置知识

开始前应掌握以下课程内容（对应 Stage 2 已学章节）：

• 前端页面设计与组件库使用：UI Design、Modern Component Libraries；
• 后端接口设计与开发：API Code with LLM Assistance；
• 数据库基础与 Supabase：Database to Supabase；
• Git 工作流与部署：Git & GitHub Workflow、Web App Deployment。

需求文档（PRD）是项目的灵魂

关联文档明确指出，本项目的需求文档（PRD）是开发的绝对依据。PRD 全文已收录在仓库中：PRD：Go 交通数据分析与可视化平台（状态为 Draft v0.1）。PRD 的一句话定义是：做一个支持事件接入、窗口聚合、异常检测和大屏展示的 Go 数据分析平台。

PRD 中还给出了关键的产品借鉴点（源自真实交通分析产品 TomTom Traffic Index 的指标表达方式）：

• 趋势、拥堵程度、城市/路口排行应直观可读；
• 看板首页应优先展示关键指标和异常信息，而不是堆很多图；
• 趋势页、排行页、告警页要有清晰分工；
• 管理端应强调数据导入、任务状态和告警处理，而不是只看静态图表；
• 整体设计要更像数据产品和运营看板，而不是普通后台列表。

这一环节传达的核心方法论是：先明确数据产品的口径、模块和接口，再进入实现——先读需求，后写代码。

第一部分：需求分析

1.1 阅读 PRD，回答关键问题

打开 PRD 文档（docs/zh-cn/stage-2/assignments/traffic-data-visualization-go/PRD.md），重点回答以下问题：

• 数据来源是什么？字段有哪些？
• 核心指标的定义是什么？（例如"拥堵"的具体标准）
• 告警规则是什么？第一版是否先收敛到简单规则？
• 看板包含哪些页面和图表？

::: warning 如果以上问题没有明确答案，不要开始写代码。需求理解不清楚是导致返工的最常见原因。 :::

PRD 中对上述问题的回答非常具体，开发时应严格对齐：

MVP 范围（第一版必须包含）：数据接入接口、原始数据落库、定时聚合任务、异常检测规则、趋势图 + Top 路口 + 告警面板、管理端数据导入或模拟数据入口。

第一版明确不做：Kafka/Flink 级流处理、复杂 GIS 地图引擎、机器学习预测模型、多租户平台权限。

角色与权限：

1.2 确认数据链路

在动手前，先用一张链路图确认整体数据流（关联文档原文）：

1.3 确认技术选型（来自 PRD）

站点入口约定：分析看板app.xxx.com，后台管理台admin.xxx.com。

第二部分：搭建项目骨架

2.1 用 AI 生成 Go API 服务骨架

由于这是 AI 辅助开发（vibe coding）课程，骨架阶段直接借助大模型生成。关联文档给出了可直接复用的提示词：

Based on the current PRD, help me generate a Go traffic data analysis platform scaffold. Requirements: 1. Use Gin or Fiber 2. Provide data ingestion API 3. Provide aggregation task skeleton 4. Provide dashboard and alerts API skeleton 5. Don't implement real complex analysis yet, just runnable structure

注意第 5 条的关键约束：先不做真实复杂分析，只做可运行结构。这与增量式开发理念一致——先保证链路能跑通，再逐步填充算法细节。

2.2 验证项目结构

生成骨架后逐项检查：

• Go 服务可以正常启动
• 数据接入接口可接收并存储数据
• 聚合任务框架已搭好
• 前端看板页面可展示基本图表

第三部分：迭代开发

3.1 按模块推进

1. 数据接入 API：接收原始交通事件，写入数据库；
2. 数据聚合：按时间窗口聚合，计算趋势和拥堵指标；
3. 告警规则：基于阈值生成告警记录；
4. 看板接口：提供趋势数据、排行数据、告警列表；
5. 前端看板：趋势图、排行榜、告警列表页面。

PRD 给出的开发顺序建议与之一致：Go API 骨架与数据表 → 事件接入接口 → 聚合任务 → 告警规则 → Dashboard 查询接口 → 前端图表页。

3.2 数据表设计（来自 PRD，可直接建表）

PRD 为 MVP 提供了完整的数据表草案，这是实现层的核心依据：

raw_traffic_events ( id bigserial primary key, intersection_id text, event_time timestamptz, vehicle_count int, avg_speed numeric, source text, created_at timestamptz ) traffic_agg_1m ( id bigserial primary key, intersection_id text, window_start timestamptz, total_vehicles int, avg_speed numeric, congestion_index numeric ) traffic_agg_5m ( id bigserial primary key, intersection_id text, window_start timestamptz, total_vehicles int, avg_speed numeric, congestion_index numeric ) alerts ( id bigserial primary key, intersection_id text, level text, rule_code text, status text, message text, created_at timestamptz, resolved_at timestamptz ) import_jobs ( id bigserial primary key, filename text, status text, total_rows int, success_rows int, failed_rows int, created_at timestamptz )

设计要点解析：

• raw_traffic_events是原始明细表，保留每一次接入的事件；
• traffic_agg_1m/traffic_agg_5m是预聚合表，分别承载 1 分钟和 5 分钟窗口的指标（总车流量、平均车速、拥堵指数），这是「窗口聚合」的核心存储；
• alerts记录告警，包含等级、规则编码、处理状态与处理时间；
• import_jobs记录 CSV 批量导入任务的状态与成功/失败行数，便于定位导入失败原因。

3.3 指标与告警规则（第一版口径）

第一版指标：每分钟车流量、每 5 分钟聚合车流量、平均车速、拥堵指数、Top10 拥堵路口。

第一版告警规则（PRD 明确建议第一版先收敛到简单规则）：

• 当前流量高于近 5 分钟均值阈值；
• 当前速度连续低于阈值。

PRD 还定义了关键状态流，实现时需在数据模型中体现：

• 数据事件：接收成功 / 校验失败；
• 聚合任务：待执行 → 执行中 → 成功 / 失败；
• 告警：新建 → 已确认 → 已处理。

3.4 接口草案（PRD 原文）

POST /api/traffic/events请求示例：

{ "intersectionId": "A-101", "timestamp": "2026-04-01T08:30:00+08:00", "vehicleCount": 42, "avgSpeed": 18.6, "source": "simulator" }

非功能要求（实现时需纳入验收）：聚合任务可重复执行且结果稳定；API 返回结构统一；导入失败要能定位原因；看板查询响应时间可接受。

3.5 页面架构（来自 PRD）

PRD 定义为「2 套入口，6 个大页面」：

A. 分析看板app.xxx.com（4 页）

B. 后台管理台admin.xxx.com（2 页）

前端关键组件：指标卡片、折线图/柱状图、排行榜表格、告警列表、时间范围筛选器。

3.6 模块自检

完成每个模块后，对照检查表逐项验证：

第四部分：联调与上线

4.1 端到端测试

至少验证以下两个场景：

• 接入一批测试数据 → 聚合任务执行 → 看板展示更新；
• 触发告警条件 → 告警记录生成 → 告警页面显示。

PRD 建议的后台监控指标可作为联调阶段的观察项：接入事件总数、聚合任务成功率、告警总数与处理率、热点路口排行、导入任务成功率；基础监控包括接入接口错误率、聚合任务耗时、数据库写入失败率、看板查询接口耗时。

交付物清单

完成本项目后，需要提交：

• 可访问的线上演示链接
• 源码仓库链接（含 README）
• PRD 文档
• 核心页面截图（数据接入演示、趋势看板、告警列表）
• 60 秒演示视频

评分标准

设计要点深度解析

为什么先「读 PRD」而不是「直接让 AI 写」

关联文档将「需求分析」设为第一部分，并给出强警告：需求不清晰时不要开始写代码。从数据产品特性看，指标口径（如"拥堵指数"的计算方式）和告警阈值直接影响数据库 schema 与聚合算法，返工成本远高于业务 CRUD。PRD 中专门列出「待确认项」（是否提供 CSV 导入作为主要演示入口、是否需要地图视图、告警阈值写死还是后台可配、图表库选 ECharts 还是 AntV），这些决策应在开发前与项目目标对齐。

聚合任务为何采用「预聚合表」

从 PRD 的数据表结构可以看出，本项目的聚合采用定时批处理 + 预聚合表方案：robfig/cron定时触发聚合任务，将raw_traffic_events按 1 分钟 / 5 分钟窗口计算后写入traffic_agg_1m/traffic_agg_5m。这样做的好处是看板查询只读预聚合表，响应快；同时聚合任务可重复执行（非功能要求），配合「待执行 → 执行中 → 成功/失败」的状态机保证结果稳定。进阶方向（评分标准的 Advanced 项）是支持增量更新，即只聚合上次执行后的新数据，而不是全量重算。

「两套入口」的产品分层

PRD 明确要求分析看板（app）与后台管理台（admin）分离：分析用户只关注趋势、排行、告警；管理员关注数据导入、任务健康与告警处置。这体现了数据产品"面向不同角色提供不同信息密度"的设计原则——看板首页优先展示关键指标和异常信息，管理端强调任务状态而非静态图表。

参考资料

本实战与 Stage 2 以下课程章节强关联，建议按需回看：

• UI Design
• Modern Component Libraries
• Database to Supabase
• API Code with LLM Assistance
• Git & GitHub Workflow
• Web App Deployment

核心文档入口：实战作业说明 与 PRD 需求文档。

【免费下载链接】easy-vibe💻 vibe coding 101｜The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe