lingniu-vehicle-ingest/docs/vehicle-data-platform-roadmap.md

车辆数据中台一期实施路线图

本路线图从分析完成后的下一阶段开始。任何阶段都以“契约、实现、测试、运行检查、文档”全部完成为退出条件，不并行铺开所有页面。

1. 阶段总览

阶段	目标	主要交付	退出条件
0 分析与决策	冻结一期边界和关键决策	本次四份文档、P0 决策记录	档案来源、认证、指标元数据、在线阈值、文件存储有负责人和结论
1 数据与 API 基座	建立统一模型和可演进契约	MySQL 向前迁移、指标目录、V2 OpenAPI、鉴权/审计、统一错误/分页	契约测试通过；旧链路不受影响；迁移可回滚
2 V2 前端基础	建立独立、无 mock 的前端壳	路由/菜单、权限、token、API client、AsyncState、地图/图表/表格基础组件	构建和组件测试通过；1440×900 基础布局可用；无 mock fallback
3 全局监控	先打通实时主路径	地图聚合、组合筛选、统计、车辆信息卡、详情跳转	1k/10k 数据基准达标；视口移动不卡顿；状态口径一致
4 单车数字档案	形成统一车辆入口	档案、实时状态、地图、动态遥测分组、来源证据	车牌/VIN/车辆编号均可解析；缺失字段不渲染空大表
5 轨迹回放	完成历史位置产品能力	分段/抽稀查询、过滤、停车点、播放控制、列表联动	长时段不会全量阻塞；抽稀/过滤可解释；播放状态正确
6 历史分析与导出	建立通用指标分析	指标目录、多车多指标列表/曲线、异步 CSV/XLSX	百万点查询经服务端聚合；导出有任务进度和受控下载
7 接入管理	产品化接入质量	动态在线阈值、延迟、最近消息/错误、协议/厂家统计	从未上报与离线可区分；事件/接收时间延迟口径明确
8 告警中心	建立可持久业务告警	规则 CRUD、评估 worker、事件、处理记录、站内通知	数值/Boolean 规则可验证；去重、恢复、确认、关闭链路完整
9 联调与生产发布	达到一期验收并部署当前 ECS	性能/异常/安全测试、运维文档、release、监控和回滚	验收清单通过，ECS 健康、无 lag、旧 release 可回滚

进度注记（2026-07-14）：阶段 7 的 V2 接入汇总、车辆状态、动态阈值、协议覆盖、版本审计及桌面/移动端页面已实现。网关 realtime snapshot 同一条原子 upsert 现维护独立于设备事件时间的首次/前次/最新接收时间、连续间隔、样本数和 event ID 去重；平台读取该投影并合并车型/企业，明确区分 live_writer 真首次观测和 snapshot_backfill 上线基线。platform-v2-20260714080619 又将缺少权威 VIN 的真实 JT808 终端纳入“身份待绑定”队列，只暴露哈希 ID、脱敏终端号和登记/上报证据；当前生产 1 条，页面与复制内容均未泄漏原始手机号，查询 p95 2.44ms。实际 phone→VIN 绑定仍必须由运维核验权威来源，不能猜测。

阶段 8 进度注记（2026-07-14）：durable 规则/审计、持续候选、事件/动作、站内通知、独立 evaluator、V2 API 与告警中心三个工作区已上线；确认、规则创建、通知已读和权限通过真实接口联调。platform-v2-20260714070507 将持续时间改为由不同 source event 的单调事件时间推进，重复快照和迟到观测不再制造持续异常，freshness_sec 作为明确的墙钟规则单独处理；后续 Kafka fields active evaluator 又补齐分区 checkpoint、迟到窗口和数据库权威重放抑制。真实规则灰度、规则编辑锁竞争及 31 分钟连续运行门禁均通过，阶段 8 一期退出项已关闭。

Kafka 告警流进度注记（2026-07-14）：platform-v2-20260714080619 当前生产仍运行 active event-time evaluator。动态规则锁、批次范围 candidate/Boolean/活跃事件/重复窗口、事件/动作/通知和 (group,topic,partition) checkpoint 在同一个 MySQL 事务内完成，随后才 commit Kafka；失败事务不会越过 offset。快照 evaluator 在 active 模式只保留 freshness_sec，空动态规则扫描由约 13ms 降至 0.5–1ms。迁移 010 已用真实 RAW 样本修正国标告警位和宇通速度/SOC 映射。受限 JT808 speed>=0、持续 20 秒、重复 1 小时灰度只打开 1 条事件；关闭后又有 2 批 candidate 推进但未重开，随后规则停用并清理状态。914 个带活跃规则的生产批次 p50 7.80ms、p95 12.07ms、最大 18.68ms，候选推进 11、重复观测 9、迟到观测 1、批次失败 0。迁移 011 进一步持久化最近非法原因/时间；当前已定位为单个未绑定 VIN 的 JT808 终端，保留 missing_vin_jt808 运维告警并在接入页生成脱敏处置队列。当前 9 分区 lag 0，跨窗口历史重算和代表性峰值长稳仍待阶段 9 门禁。

规则编辑锁竞争门禁（2026-07-14）：生产创建了不可能命中业务车辆的启用规则，在 active stream evaluator 持续消费时完成 60 次顺序版本化编辑，HTTP 200 为 60/60，冲突和 5xx 均为 0；编辑延迟 p50 3.991ms、p95 7.220ms、p99 8.584ms、最大 10.875ms。并发窗口 41 个活跃规则批次处理 303 条消息，失败、重放、误开和恢复均为 0；规则随后停用且事件总数为 0。锁竞争退出项已关闭，仍保留代表性峰值长稳与 RDS 峰值观测。

阶段 5 进度注记（2026-07-14）：生产真实轨迹基线显示活跃车辆总点数约 9,500–71,361，旧接口仅加工最新 5,000 点但摘要未充分表达覆盖边界。platform-v2-20260714060112 已在当前 ECS 上线默认今天、最长 7 天校验、完整/最新切片证据、同协议无效坐标/重复/疑似漂移过滤、多源主来源选择、GPS 推断停车、行驶/停车/数据间隔分段、质量摘要，以及保留事件和分段边界的抽稀映射。8 辆生产 canary 今天窗口为 5.7–34.22ms；正式切流抽样 2,254 个源点完整读取、1,200 个地图点、33 段和 5 次停车为 32.83ms。并行协议不会被拼成一条路线，停车也不冒充 ignition 状态；服务端持久 queryId/游标分段和长周期观测仍待后续数据合同。

轨迹与接入补齐注记（2026-07-14）：platform-v2-20260714083640 已在当前 ECS 上线。vehicle_locations 向前增加 SOC，轨迹返回 SOC 可用性、方向和告警并使用绝对时间戳；页面以 Asia/Shanghai 展示，同步卡片只为暂停点做一小时坐标缓存的地址解析。生产宇通 5 分钟 300 点全部有 SOC，JT808 5 分钟 10 点全部有方向/告警；修复了 TDengine 时间窗二次偏移及亚秒采样被截断成零秒后误判 gap 的问题，5,000 点页面分段从 3,203 降到 14，仅保留 1 个真实 28 分钟间隔，无横向溢出或控制台错误。接入页新增车型、接入厂家、首次接入和最新上报范围；生产 G7s + latestSeenFrom 深链筛选当前页 50/50 匹配。小窗位置导出 120/120 行完成，Kafka lag 0，MySQL/TDengine 可写。

全局监控性能闭环（2026-07-14）：platform-v2-20260714090040 已在当前 ECS 上线。此前页面虽有后端聚合接口，实际仍把 1,000 行普通车辆列表直接送入地图；现改为 200 行服务端筛选列表与独立地图查询，moveend/zoomend 300ms 防抖并由 React Query 去重缓存。低缩放返回聚合，高缩放按 bounds 返回轻量 MassMarks，超过 2,000 个点时自适应扩大网格，10,000 合成车辆不会退化成 10,000 个点或聚合标记。10k 纯聚合基准 30 次为 0.976ms/op；当前 ECS 727 辆真实数据 30 次低缩放聚合为 29 组，API p50 57.31ms、p95 63.44ms、最大 70.65ms，城市视口 168 点 p50 94.89ms、p95 108.56ms、最大 114.54ms。生产浏览器首屏为 15 个聚合/200 行，无横向溢出；行驶筛选所有加载行均匹配，唯一车牌查询自动从聚合切到 1 个点并聚焦到 2km 比例尺。

全局监控产品闭环（2026-07-14）：platform-v2-20260714093533 将活跃告警 VIN 与当前关键词/协议/状态筛选后的车辆集合在服务端求交，alertDataAvailable=true 后页面展示权威告警车辆数，不再使用占位。选中车辆卡片按需并发读取档案/日里程、当前业务告警和地址，并展示真实来源、接入供应商、今日里程、解析位置及当前告警；无权威供应商时明确“待补充”。生产 727 车显示告警车辆 0，抽样车辆今日里程 59.4 km、三协议来源、嘉兴解析地址和 0 条当前告警；1280×720 无页面溢出。

单车最新遥测闭环（2026-07-14）：platform-v2-20260714092531 已在当前 ECS 上线 GET /api/v2/vehicles/:vin/telemetry/latest。服务端复用权威指标目录统一 key/中文名/单位/类型/分类，同时保留真实源字段、厂家扩展、协议、端点、帧、设备/接收时间、freshness/delay 和 good|stale|warning 原因；前端不再从 RAW key 猜测标签或质量。身份只解析一次，三个协议表固定并行各取最多 5 帧且跳过分页计数，真实三源车辆扫描 10 帧返回 155 值/7 分组；生产 30 次 p50 174ms、p95 179ms、最大 179ms，本地 100 帧×50 字段纯归并基准 0.389ms/op。页面使用独立 10 秒缓存、20 秒刷新，一次遍历建立分组与来源索引；1280 桌面和 390×844 移动端均无横向溢出，行内时间为紧凑时分秒，控制台无错误或警告。

连续运行门禁（2026-07-14）：alert stream evaluator 自 08:31:50 起连续 active 运行超过 31 分钟且未重启；该窗口 16,226 批、216,118 条消息全部完成处理，valid 216,072、历史未绑定身份导致 invalid 46、replay skipped 0、失败日志 0，批次延迟 p50 6.511ms、p95 10.481ms、p99 12.806ms、最大 29.697ms。结合此前 929 个带活跃规则批次和 60 次并发版本编辑均无失败/误开，已覆盖正常流量长稳及规则锁竞争。窗口结束时 checkpoint 累计 processed 563,598、9 分区 lag 0、MySQL/TDengine 可写；最近非法身份时间已超过 20 分钟且脱敏处置队列仍保留。阶段 9 的代表性连续运行门禁关闭，云数据库 Performance Insights 仍作为容量扩容观察项，不再阻塞单 ECS 一期上线。

阶段 6 进度注记（2026-07-14）：platform-v2-20260714063725 已在当前 ECS 上线历史时间序列聚合与百万行受控导出。位置历史按车辆与协议在 TDengine 使用 PARTITION BY protocol INTERVAL(...) 服务端聚合，速度使用桶均值、总里程使用桶末值并保留 min/max/样本数；最长 31 天、每序列目标 60–600 点、空窗不 FILL，前端按单位拆成速度/总里程小多图并明确粒度、覆盖率、缺失桶、原始点数和查询耗时。真实 canary 单车双协议 1,392 个原始点聚合为 127 桶、254 浏览器点，20.67ms；5 台车 8,197 个原始点聚合为 376 桶、752 浏览器点，86.53ms。导出采用单并发队列、5,000 行 TDengine 复合游标、30 分钟超时、100 万行双重配额、流式 CSV、.part + fsync + 原子发布，并持久化总行数、已处理行数、文件大小和完成时间。预发布门禁发现并修复 8 小时时区偏移和移动端面板压缩；最终桌面与 390×844 验收无横向溢出。RAW 保持离散证据而不伪造连续趋势；日里程趋势、多实例数据库队列/对象存储与更多可聚合指标仍待后续数据合同。

上线进度注记（2026-07-14）：platform-v2-20260714033929 已发布到当前 ECS 115.29.187.205:20300。API 与告警 evaluator 均为 active，数据模式强制 production，MySQL/TDengine/Redis/容量检查已接入，Kafka lag 为 0；viewer/operator/admin 鉴权、越权拒绝、核心真实查询、根页面与 hashed 静态资源均已冒烟。告警 evaluator 当前扫描 1159 条车辆来源快照约 8–9ms，规则为 0，未产生生产告警；10k 车辆 × 20 规则的本地合成判定与批次规划约 20ms，候选写入已改为每 500 条一次批处理、活跃事件不重复写、超过 5 分钟的动态遥测不继续累积。首轮发布发现 Web 归档遗漏并在 API 冒烟后修复，runbook 已增加根页和主资源门禁。仍需补齐 ECS 10k 真实数据库写入基准、长时间稳定性、真实规则灰度及导出文件生产存储后，阶段 8/9 才可完全退出。

一期最终发布注记（2026-07-14）：当前 release 为 platform-v2-20260714093533，前一 platform-v2-20260714092531 保留可回滚。全部 11 项迁移 journal 校验通过；平台 API、快照 evaluator、流 evaluator 均 active，MySQL/TDengine 可写，9 个 Kafka 分区 lag 0、replay skipped 0，三单元最近发布窗口 error 日志均为 0。未鉴权会话返回 401，管理员会话、monitor、单车、active 告警、最新遥测、根页面与 hashed 主资源均通过真实生产冒烟；Web 22 个测试文件 272 项、API go test ./... 和 go vet ./... 全部通过。阶段 9 的单 ECS 一期退出项关闭；云数据库峰值容量和多实例对象存储作为后续扩容观察项。

导出进度注记（2026-07-14）：CSV 异步导出位于 /opt/lingniu-vehicle-platform/data/exports 持久目录，任务索引使用原子 jobs.json；完成文件和任务在 API 重启后仍可列出、下载，中断任务会显式失败而非永久 running。platform-v2-20260714063725 将旧的 1,000 行内存聚合/OFFSET/2 分钟实现升级为 100 万行流式游标任务。本地真实写入 1,000,000 行为 0.45 秒；ECS 候选位置 1,451 行与 RAW 3,538 行在单并发队列中 0.41 秒完成。正式生产 1,457 行、162,533 字节文件在 API 重启前后 SHA-256 完全一致，桌面和 390×844 任务卡无溢出、控制台无错误。当前满足单 ECS 一期受控导出；多实例扩容前仍需迁移到数据库队列与 OSS/兼容对象存储。

高级告警与指标目录进度注记（2026-07-14）：数值区间/区间外、布尔状态变化、OEM 范围、重复间隔、状态表和索引迁移已上线；ECS 以不存在厂家范围的两条规则完成启用灰度，evaluator 扫描 1159 条快照约 9ms、未误开事件，随后停用并保留版本审计。规则编辑器已通过生产浏览器检查。统一 /api/v2/metrics 目录现提供协议字段映射及可检索/绘图/告警能力，编辑器和后端写入均按目录校验。事件 INSERT 占位符、状态批写和重复边界已有自动化契约测试；布尔真实翻转、重复抑制与活跃规则长稳仍需独立生产灰度。

事件时间告警灰度注记（2026-07-14）：当前 ECS 对单车 JT808 建立 speed_kmh >= 0、持续 20 秒、重复间隔 1 小时的受限规则。真实新观测形成 candidate 后只打开 1 条事件，事件证据时间 06:58:57.000、接收时间 06:58:57.934、平台触发时间 06:59:06.871；事件随后关闭、通知设为已读、规则停用并保留审计。再次启用时 evaluator 记录 candidates_advanced 与 duplicate_observations，重复窗口内 opened=0。该门禁同时发现 MySQL UNIX_TIMESTAMP(DATETIME(3)) 返回小数字符串导致候选及最近触发时间整数扫描失败，最终改为直接扫描 DATETIME(3) 并增加毫秒精度 SQL mock 契约。发布期间两次失败校验均由软链回滚陷阱恢复，最终 release 为 platform-v2-20260714070507。

指标配置持久化进度注记（2026-07-14）：005_metric_catalog.sql 已建立指标定义与协议源字段映射权威表；生产目录读取和告警规则校验共享该数据源，关闭或修改能力标记会立即约束后续规则写入。种子数据使用 INSERT IGNORE，发布不会回写覆盖运维配置；尚缺管理端 CRUD、版本审计以及把动态 RAW 指标纳入统一目录的受控发现流程。

告警写入性能注记（2026-07-14）：alert-benchmark 默认使用连接级 MySQL 临时表，同时提供必须显式确认且带 advisory lock 的独立物理表持久模式，两者都复制候选表主键与持续时间索引且绝不写业务候选/事件。当前 ECS 到生产 RDS 的持久单事务基准：10,000 行/500 批次为 195ms（约 51,234 行/秒），100,000 行为 1,971ms（约 50,713 行/秒）；两档行数和物理表清理均独立校验。10 万行窗口观察到实例全局 redo 增量约 31MB，但全局计数包含并发业务流量，不能当作本事务精确归因。当前结果证明真实提交、网络和索引路径具备明显余量，最终容量退出仍需 evaluator 活跃规则长稳、锁竞争和 RDS Performance Insights 峰值窗口证据。

车辆主数据进度注记（2026-07-14）：采用“网关权威身份 + 平台补充主档”的混合边界。vehicle_profile 不覆盖 VIN/车牌/厂家，专门保存车型、车辆类型、所属企业、运营状态、接入服务商、首次接入和累计运行时长；vehicle_profile_audit、乐观版本和 admin-only 写入保证可追溯。单车详情已合并完整度与缺失字段，管理员可在档案卡原位维护，只读角色仅查看。外部主数据同步 API 与 CSV 管理入口已实现：单批 500 辆、dry-run、来源/版本幂等、同版本变更拒绝、人工及异源默认保护、显式接管、网关身份校验和逐 VIN 结果；写入持久化 source_system/source_version/synced_at 并生成不可变同步审计。具体车厂/GPS 厂商的定时连接器仍需按其认证和字段合同配置。

主数据同步上线注记（2026-07-14）：platform-v2-20260714051915 已部署当前 ECS，API 与 evaluator 均为 active。管理员 dry-run、operator 403、页面分包和外网根页均已验证；生产可查询身份集合的 410 个唯一 VIN 在同一事务预演中耗时 175.44ms，重复预演 170.08ms，缺失身份为 0，抽样档案前后完全一致。上线验证未向生产写入虚构车型/企业数据；正式写入需由权威车厂/GPS 数据文件或连接器触发。

主数据告警范围进度注记（2026-07-14）：规则新增 scopeModels/scopeCompanies，评估器以 VIN 主键左联 vehicle_profile，未维护对应维度的车辆不会误匹配；协议、VIN、厂家、车型、企业范围均执行去重和大小上限，避免配置膨胀拖慢 10 秒评估周期。规则编辑器、版本快照和数据库持久化共享同一字段合同。

2. 阶段 0：必须先确认的决策

1. 车辆档案采用两者结合：网关身份表维护 VIN/车牌/厂家，平台 vehicle_profile 承载补充业务属性并预留外部同步来源元数据。
2. 认证是否复用 ln-bi 的 jumpToken/JWT 交换流程；角色和操作权限的权威来源是什么。
3. 动态指标目录的首批范围、中文名、单位、类型、协议字段映射及负责人。
4. 在线阈值是否采用“全局默认 + 协议覆盖”，建议默认 5 分钟并同时展示实际延迟。
5. 导出文件使用 OSS/兼容对象存储还是 ECS 本地盘，保留天数和单任务配额。
6. 告警时间基准使用事件时间，迟到数据容忍窗口和重复告警间隔的产品定义。

决策记录写 ADR，不把未确认事项固化进页面常量。

3. 阶段 1：数据与 API 基座

3.1 MySQL 迁移

• 扩充或关联车辆档案：车型、车辆类型、运营公司、运营状态、接入厂家、首次接入时间。
• 新建 metric_definition、metric_protocol_mapping。
• 新建告警域：alert_rule、alert_rule_scope、alert_event、alert_event_action、notification。
• 新建导出域：export_job，文件本体放对象/文件存储。
• 为所有业务表增加必要的状态、时间和组合索引；迁移只向前新增，不改写接入 writer 的现有主键语义。

3.2 BFF 契约

• 建立 /api/v2，保留旧只读接口作为过渡。
• 统一游标/offset 分页规则、排序白名单、时间格式、错误码、traceId 和最大查询范围。
• 生成 OpenAPI 与前端类型，避免 Go/TypeScript 手工重复漂移。
• 接入鉴权、操作权限、审计日志、限流、请求超时和幂等键。

3.3 验证

• 在生产结构副本/测试库运行 migration up/down 或等价回滚演练。
• 契约测试覆盖空值、未知协议、时区、分页边界和非法指标。
• 回归现有 Gateway、writers、realtime API 的写入与查询。

4. 阶段 2：V2 前端基础

建议新建独立入口/目录，而不是在 PrototypeApp.tsx 内渐进堆叠：

src-v2/
├── app/                 # router、providers、权限和菜单
├── shared/              # ui、api、map、chart、table、utils
├── entities/vehicle/    # 车辆领域类型、状态、展示组件
├── features/            # 筛选、车辆选择、时间范围、指标选择
├── pages/               # 路由页面
└── widgets/             # 地图工作区、详情面板、事件时间线

基础能力包括：正式路由、URL 查询恢复、认证门禁、统一 API client、查询缓存、错误边界、加载/空/错误状态、车辆状态 token、远程搜索选择器、服务端表格、ECharts 时序封装、AMap SDK。V2 默认禁止导入 prototype/mockData.ts。

5. 阶段 3 至 8：业务模块次序

每个模块遵循相同步骤：

1. 冻结页面信息架构和 DTO。
2. 先实现/验证后端接口和样本响应。
3. 实现页面及深链跳转。
4. 增加单元、契约和交互测试。
5. 用真实接口实际运行，检查加载、空、错误、权限和不同屏幕。
6. 更新已完成/未完成、接口和运维文档后再进入下一模块。

告警中心虽然菜单重要，但排在数据查询能力之后：规则依赖统一指标目录、车辆范围和时间语义。可在阶段 1 先建表/契约，阶段 8 再启用评估与通知。

6. 性能验收门槛

以下是建议基线，开发前应在目标 ECS/浏览器上校准：

场景	门槛
全局监控首屏	1,000 车 P95 API < 1s；10,000 车聚合结果而非 10,000 DOM Marker；主要交互保持流畅
地图拖动/缩放	只在 moveend/zoomend 防抖查询；旧请求可取消；无请求风暴
实时刷新	差量或低频批量刷新，不按车轮询；页面隐藏时降频/暂停
轨迹	单次返回受控；长时间段自动抽稀/分段；保留起终点、停车和告警关键点
历史曲线	浏览器展示点数设上限；TDengine 服务端聚合/抽稀；缩放后按窗口补查
表格	全部服务端分页/排序/筛选；长列表虚拟化
导出	异步任务；并发、行数、时间范围和文件大小有限额；不占用同步 API worker
告警	消费失败不丢 offset；事件按规则+车辆+窗口幂等；可观测积压和评估延迟

7. 阶段 9：当前 ECS 发布计划

现有运维说明表明接入链路和平台都使用 systemd 裸机 release + current 软链。最终发布应继续该模式，但平台、告警 worker、导出 worker使用独立 unit 和健康检查。

发布顺序：

1. 备份并执行 MySQL 向前兼容迁移，确认现有服务继续健康。
2. 上传新 release，先启动告警/导出 worker 的 disabled 或 idle 模式。
3. 启动/切换平台 BFF，验证 /readyz、/api/ops/health、核心查询和运行时配置。
4. 切换 V2 静态 Web，进行全局监控、单车、轨迹、历史、接入、告警 smoke。
5. 开启 worker，小范围规则验证后再开放全部规则。
6. 检查 Kafka lag、Redis 在线 key、TDengine/MySQL 可写性、CPU/内存/磁盘和错误日志。
7. 保留前一 release 与数据库兼容窗口；失败时先回切软链并停新 worker，不做破坏性数据库回滚。

密钥放 /opt/lingniu-vehicle-platform/env 或对应 worker 环境文件，禁止写入 git、静态 JS 或部署日志。具体命令以实施时更新后的 runbook 为准，不能直接复制过时 release 名。

8. 一期完成清单

• 六大业务模块和导出任务满足目标文件的功能验收。
• 页面在 1440×900 正常，常用操作三次点击内，真实数据无 mock 残留。
• 1k/10k 地图、百万点历史、异步导出、告警积压均有测试记录。
• OpenAPI、数据字典、环境变量、启动、部署、回滚、监控与未完成事项完整。
• ECS 上全部新旧服务健康，Kafka lag 回零，运行版本可从健康接口确认。