快圈 — 技术文档
本页只保留业务后端集成摘要。完整且最新的外部接口规范以 docs/遥测数据分析API列表.docx 为准。
数据流转
- 前端上传 VBO，业务后端将原始文件写入对象存储并获得可下载的 file_url。
- 业务后端同步调用分析引擎 API 1，等待 metadata 与两圈 telemetry_data 返回。
- telemetry_data 整包转存为 JSON 文件放到对象存储（向后兼容，节次详情页使用）。
- 同时将 telemetry_data.laps 中每圈单独存为 JSON 文件，每圈的 OSS URL 写入 lap_summaries JSONB 的 telemetry_url 字段。
- metadata + lap_summaries（含 telemetry_url）写入关系型数据库。
- 详情页做圈层对比时调用 API 2，传入单圈 URL；生成 PDF 报告时调用 API 3.1 或 API 3.2。
高频遥测数组严禁直接塞入 PostgreSQL/MySQL。数据库只保存 telemetry 文件 URL（整包 URL 存 telemetry_data_url 列，单圈 URL 存 lap_summaries JSONB），否则会造成主库容量和查询性能问题。
API 接口
以下端点均由业务后端调用，前端不得直接请求外部分析引擎。供应商规范中 API 1 与 API 3 使用 v2，API 2 当前为 v1。
API 1 — 核心遥测与 AI 分析引擎
POST/api/v2/engine/analyze-vbo
| 字段 | 类型 | 必填 | 说明 |
|---|
| file_url | string | 是 | 对象存储中的原始 VBO 文件 URL |
| context.vehicle_type | string | 否 | 车辆型号，供 AI 评价参考 |
{
"file_url": "https://your-s3-bucket.com/raw-vbo/session_123.vbo",
"context": {
"vehicle_type": "Porsche 911 GT3 RS"
}
}
| 字段 | 类型 | 必填 | 说明 |
|---|
| status | string | 是 | 成功固定返回 "success" |
| data.metadata.session_info.session_time_utc | string | 是 | VBO GPS 提取的绝对 UTC 时间，用于后端查询天气 |
| data.metadata.session_info.track_id | string | 是 | 分析引擎识别出的赛道 ID |
| data.metadata.session_info.track_name | string | 是 | 分析引擎识别出的赛道名称 |
| data.metadata.ai_evaluation.summary_text | string | 是 | AI 驾驶评语 |
| data.metadata.ai_evaluation.radar_scores.driving_technology | object | 是 | 驾驶技术评分 key-value；当前按规范使用 Braking、Throttle |
| data.metadata.ai_evaluation.radar_scores.vehicle_performance | object | 是 | 车辆性能评分 key-value；当前按规范使用 Grip、Aero、Handling |
| data.metadata.lap_summaries | array | 是 | 固定返回 actual_best 与 theoretical_best 两圈摘要 |
| data.metadata.lap_summaries[].segmentation.indices | number[] | 是 | 赛道分段索引，用于 API 2 和前端地图联动 |
| data.telemetry_data.laps | array | 是 | 两圈高频遥测数据，业务后端需转存到对象存储 |
{
"status": "success",
"data": {
"metadata": {
"session_info": {
"session_time_utc": "2026-04-03T06:30:00Z",
"track_id": "TRK_SHANGHAI_GP_001",
"track_name": "Shanghai International Circuit"
},
"ai_evaluation": {
"summary_text": "入弯刹车点控制极佳...",
"radar_scores": {
"driving_technology": {
"Braking": 85.34,
"Throttle": 90.0
},
"vehicle_performance": {
"Grip": 88.5,
"Aero": 78.45,
"Handling": 85
}
}
},
"lap_summaries": [
{
"lap_id": "lap_actual_best",
"lap_type": "actual_best",
"lap_time_ms": 135340,
"max_speed_kph": 265.4,
"segmentation": { "indices": [0, 320, 580, 890, 1150, 1200] }
}
]
},
"telemetry_data": {
"laps": [
{
"lap_id": "lap_actual_best",
"channels": {
"time": [0.0, 0.1],
"lat": [31.3389, 31.3390],
"lon": [121.2197, 121.2198],
"speed": [82.1, 84.6]
}
}
]
}
}
}
引擎返回的评分维度 key 由引擎自行定义，当前规范：驾驶维度 car_control、line_precision、braking_technique、consistency；车辆维度 handling、agility、power、braking_power。数据库 score_dimensions 表需与之保持一致。
API 2 — 空间映射与圈层对比
POST/api/v1/engine/compare-laps
| 字段 | 类型 | 必填 | 说明 |
|---|
| reference_lap.telemetry_url | string | 是 | 参考圈遥测 JSON 文件 URL |
| reference_lap.segment_indices | number[] | 是 | 参考圈分段索引，来自 API 1 metadata |
| comparison_lap.telemetry_url | string | 是 | 对比圈遥测 JSON 文件 URL |
{
"reference_lap": {
"telemetry_url": "https://s3.example.com/lap_actual_best.json",
"segment_indices": [0, 320, 580, 890, 1150, 1200]
},
"comparison_lap": {
"telemetry_url": "https://s3.example.com/lap_12.json"
}
}
| 字段 | 类型 | 必填 | 说明 |
|---|
| data.reference_index_length | number | 是 | 参考圈数组长度，用作前端图表 X 轴总刻度 |
| data.segment_analysis | array | 是 | 分段时间差与速度差，用于地图分段染色和悬浮卡片 |
| data.continuous_data.delta_time | number[] | 是 | 秒差曲线，对比圈时间 - 参考圈时间 |
| data.continuous_data.mapped_comparison_telemetry | object | 是 | 按参考圈 index 重采样后的对比圈遥测数组 |
API 3.1 — 节次深度分析报告
POST/api/v2/engine/reports/session-summary
| 字段 | 类型 | 必填 | 说明 |
|---|
| file_url | string | 是 | 原始 VBO 文件 URL |
| context.driver_name | string | 否 | 用于 PDF 页眉或封面 |
| context.vehicle_name | string | 否 | 用于 PDF 封面 |
| context.track_name | string | 否 | 用于 PDF 封面 |
| context.report_language | string | 否 | 报告语言，如 zh-CN |
成功响应为 application/pdf 二进制流；失败响应为 application/json。
API 3.2 — 深度对比分析报告
POST/api/v2/engine/reports/lap-comparison
| 字段 | 类型 | 必填 | 说明 |
|---|
| reference_lap.telemetry_url | string | 是 | 参考圈遥测 JSON 文件 URL |
| reference_lap.lap_time_text | string | 是 | 参考圈圈速展示文本 |
| reference_lap.segment_indices | number[] | 是 | 参考圈分段索引，必须和 API 1 返回保持一致 |
| comparison_lap.telemetry_url | string | 是 | 对比圈遥测 JSON 文件 URL |
| comparison_lap.lap_time_text | string | 是 | 对比圈圈速展示文本 |
成功响应为 application/pdf 二进制流；业务后端负责计费、调用引擎、转存 PDF、再把下载 URL 返回给前端。
异常处理
| 字段 | 类型 | 必填 | 说明 |
|---|
| 400 / 422 | HTTP | — | 文件 URL 无法访问、下载失败或 VBO 格式非法 |
| 404 | HTTP | — | VBO GPS 坐标无法匹配到已知赛道 |
| 500 | HTTP | — | AI 评估、解析算法或 PDF 生成失败 |
{
"status": "failed",
"error": {
"code": "TRACK_UNRECOGNIZED",
"message": "The GPS coordinates in the VBO file do not match any known track."
}
}
基础设施采购清单（阿里云）
以下为在阿里云华东 2（上海）地域部署完整系统所需的云服务、选购时的具体配置项及参考价格（2026-04）。
运行 Next.js 业务后端 + Python VBO 分析引擎，两个服务同机部署。
| 字段 | 类型 | 必填 | 说明 |
|---|
| 付费模式 | 选择 | — | 包年包月（新用户年付最优惠） |
| 地域 / 可用区 | 选择 | — | 华东 2（上海），任选一个可用区 |
| 实例规格 | 选择 | — | 通用型 g7 或 u1，4 核 CPU / 8GB 内存 |
| 操作系统 | 选择 | — | Ubuntu 22.04 LTS 64 位（和 macOS 最接近的 Linux，包管理器 apt 与 Homebrew 类似） |
| 系统盘 | 选择 | — | ESSD Entry，80GB（够用，后续可在线扩容） |
| 公网带宽 | 选择 | — | 按固定带宽 5Mbps（小规模足够，大流量时走 CDN） |
| 安全组 | 选择 | — | 开放 22（SSH）、80（HTTP）、443（HTTPS）、3000（调试用，上线后关闭） |
| 登录凭证 | 选择 | — | 选「密钥对」而非密码，Mac 终端可直接 ssh -i 登录 |
参考价格：¥400–500/年（新用户首年）
存储用户、赛道、节次、成绩、积分等全部业务数据。
| 字段 | 类型 | 必填 | 说明 |
|---|
| 系列 | 选择 | — | 基础版（单节点，初期够用；上线后可一键升级高可用版） |
| 数据库引擎 | 选择 | — | PostgreSQL 16（和本地开发版本一致） |
| 实例规格 | 选择 | — | 2 核 CPU / 4GB 内存 |
| 存储空间 | 选择 | — | 100GB ESSD（按需扩容，无需停机） |
| 地域 / 可用区 | 选择 | — | 华东 2（上海），与 ECS 同可用区（内网互通，延迟最低） |
| 网络类型 | 选择 | — | 专有网络 VPC（和 ECS 放在同一个 VPC 下） |
| 白名单 | 配置 | — | 添加 ECS 内网 IP，禁止公网直连（用 SSH 隧道从 Mac 管理） |
参考价格：¥118/年（新用户首年）
迁移方式：Supabase 控制台导出 pg_dump → RDS 控制台导入，然后把 .env 里的 DATABASE_URL 换成 RDS 内网地址即可。
存储 VBO 原始文件、遥测 JSON（整包 + 单圈）、PDF 报告、用户头像等二进制资源。替代当前的 Supabase Storage。
| 字段 | 类型 | 必填 | 说明 |
|---|
| Bucket 地域 | 选择 | — | 华东 2（上海），与 ECS/RDS 同地域 |
| 存储类型 | 选择 | — | 标准存储（热数据，随时读取） |
| 读写权限 | 选择 | — | 私有（通过后端签名 URL 或 CDN 鉴权访问） |
| 资源包 | 选择 | — | 40GB 存储包（初期足够，超出按 ¥0.09/GB/月 计费） |
| Bucket 数量 | 建议 | — | 建 3 个：telemetry-vbo（原始文件）、telemetry-json（遥测 JSON）、reports-pdf（报告） |
参考价格：¥9/年（40GB 资源包），上传免费，下载流量走 CDN
迁移改动仅 1 个文件 src/lib/storage/supabase.ts，将 Supabase REST 调用替换为 OSS SDK（@ali-oss/client），接口返回格式不变，调用方无需修改。
加速 OSS 文件下载（遥测 JSON、PDF 报告），同时降低 OSS 直出流量费用。
| 字段 | 类型 | 必填 | 说明 |
|---|
| 加速域名 | 配置 | — | 如 cdn.kuaiquan.cn，CNAME 指向阿里云分配的域名 |
| 源站 | 配置 | — | 选择 OSS 域名作为源站（控制台有一键关联） |
| 资源包 | 选择 | — | 100GB / 半年流量包 |
参考价格：¥6/半年（100GB 流量包）
| 字段 | 类型 | 必填 | 说明 |
|---|
| 证书类型 | 选择 | — | 免费个人测试证书（DV 单域名），每账号每年 20 张 |
| 有效期 | 说明 | — | 90 天，到期前在控制台续签即可（免费） |
| 部署位置 | 配置 | — | 下载证书文件，配置到 ECS 上的 Nginx |
参考价格：¥0
费用汇总
| 服务 | 新用户首年 |
|---|
| ECS 4 核 8GB | ¥400–500 |
| RDS PostgreSQL | ¥118 |
| OSS 40GB 资源包 | ¥9 |
| CDN 100GB 流量包 | ¥12 |
| SSL 证书 | ¥0 |
| 合计 | ~¥540–640/年 |
价格为新用户首年优惠价，以阿里云官网实际结算为准。所有服务选同一地域（华东 2 上海）、同一 VPC，确保内网互通。续费价格会显著上涨。
快圈 Doc · Source: docs/遥测数据分析API列表.docx