# OneOS 车辆业务与车辆数据中台集成分析

完整系统、模块、接口、安全、数据库和运维分析见 `docs/oneos-ln-asset-management-system-analysis.md`。本文件聚焦车辆数据中台集成边界。

更新时间：2026-07-14

生产数据库聚合审计结果见 `oneos-production-audit-report.md`。
涉及 OneOS 的精确修改文件、批次、测试和回滚边界见 `oneos-change-approval-proposal.md`；该提案尚未执行。
车辆数据中台全部 API 的客户 Scope、IDOR、导出和地图服务覆盖矩阵见 `customer-scope-api-enforcement-matrix.md`。

## 1. 分析范围与约束

- OneOS 根目录：`/Users/lingniu/project/ai-coding/oneos`
- 核心业务服务：`ln-asset-management`，分支 `dev`
- 相关身份服务：`ln-cloud/ruoyi-auth`、`ln-cloud/ruoyi-system`
- 本轮仅进行只读分析，没有修改 OneOS 文件、数据库或运行配置。
- 车辆锁车、控车不在本方案范围内。

## 2. 系统职责边界

详细业务影响与遥测迁移边界见 `oneos-business-impact-matrix.md`。

### OneOS 应作为权威来源

- 客户档案：`customer_info`
- 客户账号及启停：`ry-cloud.sys_user`
- 车辆基础信息：`vehicle_info`、`vehicle_model`、`vehicle_status`
- 合同客户：`vehicle_lease_contract_info`
- 当前车辆交付/归还状态：`vehicle_lease_order_record`，必要时结合交还车任务表复核
- 业务筛选维度：运营状态、车型、品牌、运营公司、业务部门、合同和项目

### 车辆数据中台应作为权威来源

- 多协议接入状态及最后上报时间
- 实时位置、车速、SOC 和车辆告警
- 历史轨迹和原始数据证据
- 按 VIN 归并后的每日里程、统计期里程和最新总里程
- 协议数据质量与异常诊断

OneOS 当前仍通过 HASP/旧车联网接口拉取位置和总里程，其中 `/vehicle-info/page?withTotalMileage=true` 会按 VIN 逐车调用外部 HTTP 接口，存在 N+1 请求。新集成不应让车辆中台反向依赖这条旧链路。

## 3. 已确认的数据关系

### 权威表与用途

| 数据域 | 表 | 主键/关联 | 集成用途 | 注意事项 |
| --- | --- | --- | --- | --- |
| 客户档案 | `customer_info` | `id` | 客户名称、编码、合作状态 | 含联系人、银行等敏感字段，范围接口只取最小必要字段 |
| 客户账号 | `ry-cloud.sys_user` | `user_id = customer_info.id` | 登录、启停、用户类型 | 账号可能缺失；当前 `user_type=customer` 未被权限枚举支持 |
| 账号角色 | `ry-cloud.sys_user_role`、`sys_role` | `user_id`、`role_id` | 客户门户功能权限 | 新客户当前不自动分配角色 |
| 车辆档案 | `vehicle_info` | `id`、`vin` | VIN、车牌、车型、运营组织 | 实体已不再保存客户归属；VIN 必须核验空值和重复值 |
| 车辆状态 | `vehicle_status` | `vehicle_id` | 运营、车辆、证照、保险状态 | `online_status`、里程仍混有旧链路数据，不作为中台遥测权威值 |
| 合同 | `vehicle_lease_contract_info` | `id`、`order_id` | 主客户、丙方客户、合同和项目 | 有效客户为 `COALESCE(other_customer_id, customer_id)` |
| 当前租赁聚合 | `vehicle_lease_order_record` | 设计上一车一行 | 当前客户、合同、最近交还车事实 | Mapper 不完整、写入有清空风险，必须审计后使用 |
| 租赁历史 | `vehicle_lease_order_record_log` | `contract_id + vehicle_id` | 归属和交还车复核 | 是可追溯证据之一，但当前按组合更新，并非不可变事件日志 |
| 交车事实 | `delivery_vehicle` | `vehicle_id`、`order_detail_id` | 核验交车时间、里程和单据 | 完成状态枚举需与生产字典确认 |
| 还车事实 | `return_vehicle_task` | `vehicle_id`、`contract_id` | 核验还车时间、里程和完成状态 | 多条完成路径会更新聚合表，部分异常不中断主流程 |

车辆数据中台不应复制 `contact_mobile`、身份证/信用代码、银行账号、密码等字段。客户投影只需要客户 ID、展示名称、账号状态、业务版本和同步时间。

### 客户与账号

新增客户时，`customer_info.id` 使用雪花 ID，并尝试以同一个 ID 创建 `sys_user.user_id`：

```text
customer_info.id = sys_user.user_id
sys_user.user_type = customer
```

但账号创建失败只记录日志，不阻断客户保存，因此该关系不是天然完整的，必须进行覆盖率核验和补偿。

### 车辆与客户

2026-03-27 的 `9a8e2a5f` 提交将以下业务归属字段从 `VehicleInfo` 实体中移除：

- `customerId`
- `contractCode`
- `businessId`
- `businessDeptId`
- `contractType`

代码注释明确这些字段改由 `vehicle_lease_order_record` 提供。因此不能再把 `vehicle_info.customer_id` 当作唯一权威口径，即使旧数据库或旧文档仍保留该列。

合同存在甲方客户和丙方客户，现有业务代码的有效客户规则为：

```text
effectiveCustomerId = other_customer_id != null ? other_customer_id : customer_id
```

客户车辆范围还必须考虑交还车边界：只有已经交车且尚未还车的车辆，才能视为客户当前可见车辆。仅按 `vehicle_lease_order_record.customer_id` 查询会把已经归还的车辆继续授权给客户。

建议的当前客户车辆口径已调整为事务事实优先：

```text
vehicle_info.del_flag = 0
AND vehicle_lease_order_record.del_flag = 0
AND effective_customer_id = 当前客户
AND 最新有效 delivery_vehicle.delivery_status IN (2,3)
AND 不存在该交车单对应的 return_vehicle_task.status IN (2,3,5)
```

`vehicle_lease_order_record` 只用于客户归属交叉校验，不使用 `last_return_time` 判断生命周期，因为还车草稿会提前写入该字段。生产影子查询已验证该条件，仍需由业务抽样确认换车、合同变更、丙方客户、重复交还车和历史补录场景。

### 订单记录的可信度限制

`vehicle_lease_order_record` 的设计目标是“每辆车一条当前记录”，但当前实现还不能未经校验就作为唯一授权依据：

- `VehicleLeaseOrderRecordMapper.xml` 的 `BaseResultMap` 和 `Base_Column_List` 没有 `customer_id`、`project_name`、交还车单 ID、交还车人等实体字段。调用 `selectByVehicleId`、`selectByVehicleIds` 等自定义查询时，这些字段会丢失。
- `saveOrUpdateForContract()` 在 `deliveryVehicleId == null` 时会清空已有交车和还车字段。合同提交、重新提交、审批通过等多条路径都会调用该方法，若车辆此前已经交付，可能暂时或永久破坏当前租赁状态。
- 还车提交路径先写入还车时间，完成路径又可能清空当前合同和客户字段；不同查询不能仅以 `customer_id IS NOT NULL` 或仅以时间字段判断。
- 交还车更新失败只记录日志、不中断主流程，业务任务成功不代表聚合记录一定成功同步。

因此阶段 A 需要同时以当前聚合表、历史表、交车单、还车任务和合同表交叉核对。正式的范围快照接口应在一个受测试的查询服务中封装口径，并对异常记录失败关闭，不能让各调用方直接读取聚合表自行解释。

## 4. 已发现的高风险缺口

### P0：现有客户车辆远程接口会返回全量车辆

`RemoteVehicleService.listByCustomerId(customerId)` 的客户过滤已被注释，当前实现实际查询全部未删除车辆；`RemoteVehicleVo.customerId` 和 `contractCode` 的回填也被注释。

该接口在修复前不得用于任何外部客户权限，否则存在严重跨客户数据泄露风险。

### P0：客户账号体系尚不能直接用于车辆数据中台

- `customer_info` 创建成功不代表 `sys_user` 一定创建成功。
- 新客户账号没有分配角色或菜单权限。
- `sys_user.user_type=customer`，但 `UserType` 枚举只识别 `sys_user` 和 `app_user`。
- Sa-Token 权限解析会调用 `UserType.getUserType()`，客户账号触发权限判断时可能抛出类型不存在异常。
- 车辆数据中台当前只支持静态 Bearer Token 和 `viewer/operator/admin`，Principal 中没有 `customerId`、`tenantId` 或 VIN 范围。
- 客户账号创建复用了公开注册 RPC；该 RPC受 `sys.account.registerUser` 开关控制。生产若关闭自助注册，客户档案仍会成功但账号创建必然失败。
- 所有业务账号使用相同初始密码 `ln123456`，没有发现首次登录强制改密或一次性激活机制。外部客户上线前必须废弃该做法。
- 通用密码登录按 `tenantId + username` 查询，不按 `user_type` 区分；客户编码必须在租户内与其他类型账号全局唯一，并需要防止账号类型混淆。

推荐新增“业务账号开通”内部能力，不再复用公开注册开关：

1. 以 `(tenant_id, user_type, business_id)` 幂等开通客户账号；`business_id` 对客户即 `customer_info.id`。
2. 同一事务或 Outbox 中完成账号、客户角色和业务绑定；失败可重试并可见，不再吞异常。
3. 使用一次性激活链接或随机临时口令，首次登录强制设置密码；禁止共享默认密码。
4. 登录成功后校验账号主体类型为 `customer`，并从服务端绑定关系取得 `customerId`。
5. 客户停用、合作终止、账号删除时撤销会话并让车辆中台短时声明快速失效。
6. 存量补偿任务只处理缺失/异常账号，输出成功、冲突、跳过清单，不覆盖现有密码。

### P0：OneOS 地图和车辆查询没有客户级数据隔离

- `MapTruckController` 的列表、搜索、详情和信息树均未按客户过滤。
- 地图 SQL 默认返回所有符合运营状态的车辆。
- `VehicleInfoMapper` 仅声明业务部门数据权限；业务专员/主管的默认过滤逻辑当前被整体注释。
- 客户账号既没有部门数据范围，也没有独立客户数据范围。

### P1：代码、文档和映射存在漂移

- `VehicleInfo` 实体已移除客户和合同字段。
- `VehicleInfoMapper.xml` 的基础 ResultMap 和字段清单仍包含旧字段。
- `docs/VehicleInfo.md` 仍描述 `vehicle_info.customer_id` 并给出过时接口参数。
- 部分详情服务明确把客户和合同字段设置为 `null`。
- `RemoteContractMatchService.matchByVehicleAtTime` 已处理交还车时间边界，但合同命中时直接返回 `contract.customerId`，没有采用丙方优先的有效客户规则。
- `VehicleLeaseOrderRecordMapper.xml` 未完整映射实体字段，自定义查询取得的 `customerId` 等值可能为 `null`。
- 合同保存会重置交还车字段，而交还车聚合更新异常又不会阻断主流程，存在聚合状态与真实业务任务不一致的窗口。

### P0：车辆中台现有授权是“功能角色”，不是“数据范围”

当前 `Principal` 只有 `Name` 和 `Role`，鉴权中间件仅按 `viewer/operator/admin` 判断 HTTP 方法与功能权限。Store 接口和 SQL 构造器没有客户或 VIN Scope，`PrincipalFromContext` 也只被用于写操作的审计 Actor。

这会产生以下具体越权面：

| API 组 | 当前行为 | 客户开放前要求 |
| --- | --- | --- |
| 监控、车辆、实时位置 | 全量查询，可按 VIN/车牌筛选 | 所有列表、汇总、点位、详情统一限定授权 VIN |
| 轨迹、历史、原始帧、里程 | 接受调用方传入 VIN/关键字 | 先校验 VIN Scope，再访问 MySQL/TDengine；空范围返回空，不返回全量 |
| 告警 | 告警列表只按业务筛选；详情直接按事件 ID 查询 | 列表和详情都通过事件 VIN 校验，越权统一返回 404 |
| 导出 | 任务没有 owner/customerId，列表展示全局任务，知道 ID 即可下载 | 任务固化创建者、客户、VIN Scope 和快照版本；列表/下载校验所有权 |
| 运维质量、接入管理、规则配置 | 只按 viewer/operator/admin 控制 | 外部客户主体默认禁止，不能因拥有 viewer 角色而开放 |
| 车辆档案写入、同步 | 管理员可写 | 仅内部管理员或受信同步服务可用，客户主体永远禁止 |

尤其是导出任务当前保存在全局 `exports` Map 和 `jobs.json`，`ListHistoryExports()` 不区分创建者，`HistoryExportFile(id)` 也不校验主体；告警详情同样存在按 ID 直接读取的问题。这两处在客户入口上线前必须按 P0 修复。

## 5. 推荐集成架构

### 身份链路

外部客户登录仍由 OneOS 管理，OneOS 负责账号启停和密码策略。车辆数据中台不复制客户密码。

推荐两种方案，优先级如下：

1. OneOS Gateway 验证 Sa-Token 后，向车辆数据中台转发由共享密钥签名的身份声明，包含 `userId`、`customerId`、`tenantId`、`role`、过期时间和请求 ID。
2. 车辆数据中台收到 OneOS Access Token 后，调用 OneOS 内部会话校验接口获得同样的身份声明。

禁止信任浏览器直接传入的 `customerId`、客户名或 VIN 列表。

### 车辆范围同步

OneOS 对外提供内部服务接口，返回客户当前授权车辆快照及版本：

```json
{
  "customerId": 1001,
  "version": "2026-07-14T12:00:00.000Z",
  "vehicles": [
    {
      "vehicleId": 2001,
      "vin": "...",
      "plateNumber": "...",
      "operationStatus": "...",
      "modelName": "...",
      "brandName": "...",
      "contractId": 3001,
      "contractCode": "...",
      "projectName": "...",
      "scopeStartAt": "..."
    }
  ]
}
```

车辆中台保存只读投影，例如：

- `business_customer`
- `business_customer_vehicle_scope`
- `business_scope_sync_run`
- `business_scope_audit`

所有车辆 API 在 Store/SQL 层统一追加 VIN Scope，不能逐个页面自行过滤，也不能先查询全量后在前端过滤。

推荐把范围变成显式的 `QueryScope` 参数，而不是只放在 `context.Context` 中：Store 接口若没有 Scope 参数就无法编译，从机制上减少新增查询忘记加权限的概率。MySQL 查询优先 JOIN 本地范围投影表；TDengine 单车查询先做 VIN 授权检查，多车查询使用已授权 VIN 集合并设置数量上限。空 Scope 对外部客户必须恒等于“无数据”，绝不能解释为“不限制”。

### 数据请求原则

- 身份声明决定客户 ID。
- 客户 ID 决定 VIN Scope。
- VIN Scope 再约束监控、车辆、轨迹、历史、里程、告警、导出和地图聚合查询。
- 内部管理员可显式选择客户；外部客户不能覆盖身份中的客户 ID。
- 当 Scope 服务不可用或同步数据过期时，外部访问应失败关闭，不得降级为全量数据。

## 6. 分阶段实施

### 阶段 A：只读数据审计

- 执行 `oneos-readonly-audit.sql`。
- 确认生产表结构是否仍有 `vehicle_info.customer_id`。
- 统计客户账号覆盖率、启用率、角色覆盖率。
- 统计当前交付车辆的 VIN 完整率、客户完整率和客户档案匹配率。
- 抽样验证丙方客户、换车、已还车和多合同场景。

验收：形成数据质量基线，业务负责人确认“当前客户车辆”的唯一口径。

### 阶段 B：修复 OneOS 权威接口和账号能力

该阶段已停止：用户明确要求不修改 `ln-asset-management` 任何逻辑。以下内容仅保留为已知风险清单，不执行。

- 修复 `listByCustomerId`，按有效客户和交还车边界查询。
- 增加批量客户车辆快照接口，返回 VIN 和业务版本。
- 统一有效客户规则，覆盖丙方客户。
- 修复订单记录 Mapper 字段遗漏，并禁止合同更新覆盖已经发生的交还车事实。
- 对范围异常记录给出隔离清单，不将不确定归属车辆授权给任何外部客户。
- 补充客户账号类型、角色、启停和存量账号补偿。
- 新增专用业务账号开通能力，移除共享默认密码和对公开注册开关的依赖。
- 增加双客户越权测试。

验收：客户 A、B 的车辆集合互斥；已还车辆立即退出范围；接口默认失败关闭。

### 阶段 C：车辆数据中台身份和 Scope 投影

- 扩展 Principal，加入主体类型、外部用户 ID、客户 ID 和租户 ID。
- 增加 OneOS 身份校验或可信代理声明校验。
- 建立客户与车辆范围投影、版本和审计表。
- 在底层查询构建器统一注入 VIN Scope。
- 覆盖监控、车辆、轨迹、历史、统计、告警、导出、地图聚合和反向地理编码相关入口。

验收：任何 URL 参数、VIN 搜索、批量接口和导出均不能越权；Scope 过期时外部请求拒绝访问。

### 阶段 D：客户门户和入口

- 外部子域名提供独立登录页。
- 内部 OneOS 菜单以新标签页进入车辆数据中台。
- 外部页面隐藏接入配置、运维质量和管理型功能。
- 客户页默认展示授权车辆数量、实时地图、轨迹和里程统计。

验收：内部入口统一，外部入口独立；账号停用后现有会话及时失效。

### 阶段 E：历史里程补录

- 定义补录文件格式和来源平台。
- 以 VIN、自然日、来源和导入批次保证幂等。
- 导入约 20 天缺失里程并输出成功、冲突、缺 VIN 和异常跳变报告。
- 不伪造无法取得的历史轨迹，页面明确轨迹数据起始时间。

验收：补录前后总量可对账，重复导入不重复累计，每条补录记录可追溯。

## 7. 需要修改 OneOS 前必须同步的范围

预计至少涉及以下模块，尚未进行任何修改：

- `ln-asset-management/ln-asset-api`
- `ln-asset-management/src/main/java/com/ln/asset/api/impl/RemoteVehicleServiceImpl.java`
- `ln-asset-management` 的车辆/合同 Mapper 与 Service
- `ln-cloud/ruoyi-common-core` 的用户类型定义
- `ln-cloud/ruoyi-auth` 的客户登录策略
- `ln-cloud/ruoyi-system` 的客户账号角色和状态管理
- 可能新增 OneOS 内部 HTTP API、数据库索引和菜单脚本

修改前需要先同步：具体文件、接口契约、SQL 变更、兼容方案、回滚方案和测试范围。