lingniu-vehicle-ingest/vehicle-data-platform/docs/oneos-business-impact-matrix.md

OneOS 车辆业务影响矩阵

更新时间：2026-07-14

1. 结论

车辆数据中台接入 OneOS 不能等同于“把所有里程和位置字段同步回资产库”。OneOS 同时存在实时遥测、人工单据、合同聚合和结算证据；它们含义不同，必须按数据域迁移。

• 实时位置、在线状态、SOC、速度、当日里程、最新总里程：以车辆数据中台为权威来源。
• 交车里程、还车里程、异动起止里程和结算里程：保留 OneOS 单据事实，不允许遥测自动覆盖。
• 客户、合同、项目、当前租赁归属、车型和运营状态：以 OneOS 为权威来源。
• 车辆中台只消费最小业务投影，不复制合同金额、联系人、银行账号等敏感字段。

2. 当前遥测链路

链路	当前用途	已发现问题	建议
LocationUtil → 47.99.166.38:20000	交车、还车、迷你交车按 VIN 取坐标和总里程	地址硬编码；每次新建 HTTP Client；失败返回固定坐标而非“无数据”；会把故障伪装成真实位置	P0 禁止固定坐标降级；后续改为调用车辆中台单车快照 API
TruckSyncService → HASP	每 10 分钟拉位置、在线、SOC、氢耗、里程	全车辆串行请求；依赖车牌/VIN 双接口；状态可能滞后；同时写 vehicle_status.online_status	数据中台稳定后停用拉取任务，改为受控兼容投影或 OneOS 只读调用
tab_truck_remote_sync_realtime_info	OneOS 地图、车辆列表位置和里程	老表字段多为字符串；总里程单位是米、日里程按 km；坐标已转 GCJ-02；客户名可能来自 HASP 而非 OneOS	迁移期只作兼容缓存，不作为客户归属或历史权威来源
vehicle_realtime_location	CRUD 型实时位置表	当前更像普通业务表，没有持续同步和客户范围	不新增依赖；确认无调用方后归档或明确用途
vehicle_status	运营/车辆/证照/保险/在线/里程混合状态	前四项是业务状态，后两项是遥测状态，来源混杂	保留业务状态；在线和遥测里程逐步改为中台只读展示，不反向覆盖业务状态

3. 业务域影响

业务域	主要模块/表	与客户车辆范围关系	中台接入策略	风险级别
客户与账号	customer_info、sys_user	决定客户主体和启停	OneOS 认证，向中台传递签名客户身份	P0
合同	vehicle_lease_contract_info	主客户/丙方客户决定有效客户	OneOS 输出有效客户，不由中台推断合同	P0
当前租赁	vehicle_lease_order_record	决定当前可见车辆	修复聚合一致性后输出版本化 Scope	P0
交车	delivery_vehicle、交车任务	形成 Scope 开始时间；保存签署里程和地点	Scope 只使用已确认交车事实；人工里程不覆盖	P0
还车	return_vehicle_task	形成 Scope 结束；从客户范围移除	完成还车后发布新 Scope；异常时失败关闭	P0
换车/转三方	VehicleReplaceRecordService、合同变更	同时改变旧车、新车和有效客户	必须做原子或同版本范围切换	P0
地图	MapTruckController、旧 realtime 表	当前返回全量车辆	客户门户使用中台地图；OneOS 内部地图后续再迁移	P0
车辆列表/详情	VehicleInfoMapper	混入客户、合同、位置、总里程	业务档案继续 OneOS；遥测展示改为批量调用，禁止逐 VIN N+1	P1
事故、违章	AccidentInfo、TrafficViolation	通过车辆或历史租赁记录关联客户	若未来开放客户查看，必须按“事件发生时的客户”而非当前客户授权	P1
保险、年检、年审、证照	对应 vehicle 业务模块	当前以 vehicleId 关联	默认仍为内部业务；若开放客户须额外产品授权，不自动随实时车辆 Scope 开放	P1
加氢台账	HydrogenFuelLedger	使用客户、车辆和里程字段	台账里程是业务记录；中台遥测只用于对账，不自动改账	P1
结算	ReturnSettlement	使用交还车里程计算费用	中台可提供差异证据，不能成为自动覆盖结算的来源	P0
异动、调拨、故障	多个车辆业务模块	保存计划/起止/故障时里程	保留业务单据值；按需要显示中台采集值作为旁证	P1
运维和接入质量	车辆数据中台	不属于外部客户默认权限	仅内部运维/管理员开放	P0

4. 时间语义

必须区分两类车辆权限：

当前车辆权限

用于 /monitor、当前车辆列表、最新遥测和当前告警。依据当前有效交付关系，车辆还车后立即移除。

历史事件权限

轨迹、历史数据和事故/违章存在两种产品口径，不能默认选择：

1. 持有期口径（推荐）：客户只能查看 scopeStartAt <= eventAt < scopeEndAt 的数据。车辆还车后仍可查看租赁期间历史，但不能查看还车后的数据。
2. 仅当前口径：还车后所有历史立即不可见，实现简单但不利于客户对账。

建议范围投影保留历史有效期，而不是只保存当前 VIN 集合：

customer_id, vin, valid_from, valid_to, contract_id, scope_version

任何历史查询都同时校验 VIN 和事件时间。当前快照接口用于实时查询，历史范围接口或增量事件用于回填 valid_to。

5. 坐标与单位

字段	OneOS 当前情况	数据中台约定	展示规则
原始坐标	上游多为 WGS-84	中台保存 WGS-84 原始值并标注坐标系	高德前端展示前统一转 GCJ-02，只转换一次
旧地图坐标	TruckSyncService 已转 GCJ-02	不回写为“原始坐标”	迁移时避免再次转换造成漂移
total_mileage	HASP 老表单位为 m、类型为字符串	中台规范为 km、数值类型	API 字段明确命名 totalMileageKm
day_mileage	OneOS 按 km 使用	中台按自然日、时区和来源生成	明确 Asia/Shanghai 日界线和统计版本
交还车里程	人工/单据 km	不覆盖	可增加 telemetryMileageKm 作对照证据

6. 推荐迁移顺序

1. 修复并审计客户账号、当前租赁聚合和 Scope 接口。
2. 车辆中台完成客户身份、当前/历史 Scope 投影和全 API 隔离。
3. 外部客户门户先只读上线，功能限定为当前监控、持有期轨迹、里程和授权告警。
4. 为 OneOS 提供批量最新遥测 API，影子对比 HASP 与旧接口，不改业务单据。
5. 对比位置、在线、SOC、总里程、日里程的覆盖率与延迟，达到验收标准后切换 OneOS 地图读取源。
6. 最后停用 TruckSyncService 和 LocationUtil 旧链路；保留可回滚开关，不删除历史表。

7. 遥测切换验收

• 连续 7 天 VIN 覆盖率不低于旧链路，关键车辆无遗漏。
• 最新位置 P95 延迟满足业务约定，离线判断与数据上报周期匹配。
• WGS-84 → GCJ-02 只执行一次，抽样点位无系统性漂移。
• 总里程单位和来源明确，无米/公里千倍错误，无异常倒退未告警。
• OneOS 地图使用批量接口，不出现逐车 N+1 调用。
• 数据中台不可用时显示“实时数据暂不可用”，不得展示固定默认坐标或过期数据为实时值。
• 交车、还车、结算、加氢台账等人工事实在切换前后完全不变。

8. 本轮不建议改动的业务

在客户车辆范围和遥测切换稳定前，不建议同时改造保险、年检、结算、违章、事故、加氢台账等业务流程。它们可以消费 Scope 或遥测证据，但不应与第一批权限修复绑在一次发布中。