企业官网建设流程全解析

• 教程
• 文档

这是一篇面向 datawhalechina/easy-vibe 项目 Stage 2 学习者的综合实战指南。你将围绕一份真实的 PRD（需求文档），用 Go 语言构建一条「数据接入 → 聚合 → 告警 → 可视化」的完整数据链路，交付一个可演示、可部署的交通数据分析平台。读完本文，你将掌握如何从 PRD 提取开发任务、用 Gin/Fiber 搭建 Go API 服务、设计窗口聚合与告警规则、打通后端与前端看板，并完成端到端联调与上线演示。

项目定位：为什么是「数据产品」而不是又一个 CRUD

本项目要求你围绕真实 PRD，使用 Go 完成一个交通数据分析平台。它与此前增删改查（CRUD）类项目最大的区别在于：重点是把原始交通数据转换成可读的分析结果和告警，构建一条「数据接入 → 聚合 → 告警 → 可视化」的完整数据链路。这类数据产品在 IoT、监控、运营分析等场景中非常常见。

产品由四个核心模块组成：

这是 Stage 2 的综合实战环节（在 Stage 2 目录 中被列为可选进阶项目），也是你第一次接触 Go 语言。不必担心——有了之前 JavaScript / TypeScript 的基础，学习 Go 并不难，重点是理解数据链路的设计思路。

前置知识

在开始本项目之前，你应该已经掌握以下内容：

• 前端页面设计与组件库使用（UI 设计、现代组件库）
• 后端接口设计与开发（接口代码编写）
• 数据库基础与 Supabase（从数据库到 Supabase）
• Git 工作流与部署（Git 和 GitHub、部署 Web 应用）

学习目标

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

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

项目整体按四个阶段推进：需求分析（阅读 PRD，明确数据来源、指标口径和告警规则）→搭建骨架（用 AI 生成 Go API 服务和前端看板骨架）→迭代开发（补充聚合逻辑、告警规则和看板接口）→联调上线（端到端跑通，部署并准备演示）。

第一部分：需求分析

1.1 阅读 PRD

本项目的需求文档（PRD）位于仓库内：交通数据分析与可视化平台 PRD。打开它，重点回答以下四个问题：

• 数据来源是什么？字段有哪些？PRD 给出的数据表核心字段包括intersection_id（路口 ID）、event_time（事件时间）、vehicle_count（车流量）、avg_speed（平均车速）、source（数据来源）等。
• 核心指标的定义是什么？例如「拥堵」的具体标准：第一版指标包括每分钟车流量、每 5 分钟聚合车流量、平均车速、拥堵指数、Top10 拥堵路口。
• 告警规则是什么？第一版建议先收敛到简单规则：当前流量高于近 5 分钟均值阈值、当前速度连续低于阈值。
• 看板包含哪些页面和图表？包括总览页、趋势页、路口排行页、告警页，以及管理端的数据导入页和任务管理页。

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

1.2 确认技术选型

PRD 给出了明确的技术选型建议，这是本项目的默认技术栈：

• 后端框架：Go + Gin/Fiber
• 数据库：PostgreSQL
• 聚合任务调度：robfig/cron
• 前端：React / Next.js
• 图表库：ECharts或AntV

站点入口约定：分析看板为app.xxx.com，后台管理台为admin.xxx.com。同时 PRD 明确了 MVP 边界——第一版必须包含数据接入接口、原始数据落库、定时聚合任务、异常检测规则、趋势图/Top 路口/告警面板、管理端数据导入或模拟数据入口；第一版不做Kafka/Flink 级流处理、复杂 GIS 地图引擎、机器学习预测模型和多租户平台权限，避免范围蔓延。

1.3 确认数据链路

在写代码之前，先在纸上确认整条数据链路：

关键状态流（来自 PRD）：数据事件有「接收成功 / 校验失败」两种状态；聚合任务经历「待执行 → 执行中 → 成功 / 失败」；告警则按「新建 → 已确认 → 已处理」流转。这条状态机贯穿整个产品设计，也是后续接口和页面分工的依据。

第二部分：搭建项目骨架

2.1 用 AI 生成 Go API 服务

本项目鼓励用 AI 辅助生成代码骨架。参考提示词如下：

请基于当前 PRD，帮我生成一个 Go 交通数据分析平台骨架。 要求： 1. 使用 Gin 或 Fiber 2. 提供数据接入接口 3. 提供聚合任务骨架 4. 提供 dashboard 和 alerts 接口骨架 5. 先不做真实复杂分析，只做可运行结构

提示词的关键在于先做「可运行结构」，不做真实复杂分析——这符合迭代开发的节奏，也符合 接口代码编写 教程中「提供完整上下文（Schema + 约束）再让 AI 写代码」的实践建议。

2.2 设计数据表

结合 PRD 中给出的建表 SQL，数据表是数据链路的地基，建议按如下设计落地：

-- 原始交通事件表 raw_traffic_events ( id bigserial primary key, intersection_id text, event_time timestamptz, vehicle_count int, avg_speed numeric, source text, created_at timestamptz ) -- 1 分钟聚合表 traffic_agg_1m ( id bigserial primary key, intersection_id text, window_start timestamptz, total_vehicles int, avg_speed numeric, congestion_index numeric ) -- 5 分钟聚合表 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 )

注意traffic_agg_1m与traffic_agg_5m的窗口设计：1 分钟聚合服务于分钟级车流量指标，5 分钟聚合服务于稳定趋势与拥堵指数计算，两者在后续聚合任务中分层产出。

2.3 验证项目结构

骨架生成后，逐项检查：

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

第三部分：迭代开发

3.1 按模块推进

从 PRD 的开发顺序建议出发，推荐按以下顺序逐模块推进：

1. Go API 骨架与数据表：先跑通 Gin/Fiber 服务与 PostgreSQL 连接
2. 数据接入 API（ingest）：接收原始交通事件，校验后写入raw_traffic_events表
3. 数据聚合（aggregation）：按时间窗口（1 分钟、5 分钟）聚合，计算趋势和拥堵指标，写入聚合表
4. 告警规则（alerts）：基于阈值生成告警记录（当前流量高于近 5 分钟均值、速度连续低于阈值）
5. 看板接口（dashboard）：提供趋势数据、排行数据、告警列表
6. 前端看板：趋势图、排行榜、告警列表页面

3.2 接口草案

PRD 定义了清晰的接口清单，开发时可直接对照实现：

其中POST /api/traffic/events的请求体示例：

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

这个接口是整条链路的入口：模拟器或 CSV 导入产生的交通事件，都通过它进入系统。实现时注意 PRD 的非功能要求——API 返回结构统一、导入失败要能定位原因、看板查询响应时间可接受，这些正是工程完整度的加分项。

3.3 页面架构与关键组件

PRD 将前端定义为「2 套入口，6 个大页面」：分析看板（app.xxx.com）4 个大页面 + 后台管理台（admin.xxx.com）2 个大页面。

前端关键组件包括：指标卡片、折线图/柱状图、排行榜表格、告警列表、时间范围筛选器。PRD 特别强调：总览页应优先展示关键指标和异常信息，而不是堆很多图；整体设计要更像数据产品和运营看板，而不是普通后台列表。

3.4 模块自检

每完成一个模块，用下表自查：

此外，PRD 建议后台至少监控这些运营指标：接入事件总数、聚合任务成功率、告警总数与处理率、热点路口排行、导入任务成功率；基础监控包括接入接口错误率、聚合任务耗时、数据库写入失败率、看板查询接口耗时。

第四部分：联调与上线

4.1 端到端测试

至少验证以下两个核心场景：

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

建议用模拟器或 CSV 导入构造测试数据，跑通全链路后再进行部署（可参考 部署 Web 应用）。

4.2 交付物

完成本项目后，你需要提交以下内容：

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

评分标准

评分标准实际上指明了进阶方向：增量聚合更新、可配置指标、自定义告警规则、时间范围筛选、统一错误处理与日志——如果你有余力，这些都是让作品从「完成」走向「优秀」的着力点。

参考资料

• UI 设计
• 使用现代组件库更新你的界面
• 从数据库到 Supabase
• 大模型辅助编写接口代码与接口文档
• Git 和 GitHub 工作流
• 如何部署 Web 应用

• 教程
• 文档