98 lines
7.7 KiB
Markdown
98 lines
7.7 KiB
Markdown
# 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 集合：
|
||
|
||
```text
|
||
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 或遥测证据，但不应与第一批权限修复绑在一次发布中。
|