# OneOS 客户车辆范围内部接口契约（草案）

更新时间：2026-07-14

## 1. 目的与安全边界

该接口仅向车辆数据中台提供 OneOS 已确认的客户车辆授权范围，不提供密码，不允许浏览器直连，也不承担实时遥测查询。

- OneOS 是客户、合同、交还车事实和车辆档案的权威来源。
- 车辆数据中台只保存可重建的只读投影。
- 客户 ID 必须来自已验证的 OneOS 会话或内部同步任务，不能采用浏览器请求参数。
- 归属不确定、VIN 缺失、存在多客户冲突的车辆必须放入异常列表，不能进入授权列表。
- 内部请求需要服务身份认证、时间戳、防重放和请求 ID；网关必须剥离外部同名身份头。

## 2. 推荐接口

### 查询车辆中台全量业务范围快照

车辆数据中台的定时同步需要一次读取全部客户的当前车辆范围，避免先拉客户列表再产生 N+1 请求。推荐由 OneOS 提供专用平台快照：

```http
GET /inner/v1/vehicle-data-platform/customer-vehicle-scopes?cursor=&limit=500
Authorization: Service <service-token>
X-Request-Id: <uuid>
X-Request-Timestamp: <unix-seconds>
X-Request-Signature: <hmac-sha256>
```

签名原文必须逐字节使用：

```text
GET\n<path-and-sorted-query>\n<unix-seconds>\n<request-id>
```

双方使用独立共享密钥计算 HMAC-SHA256 小写十六进制；服务令牌与签名密钥不能相同。OneOS 应拒绝超过 60 秒的时间戳、重复 request ID、错误 audience 和外网来源。网关必须剥离外部传入的同名身份头。

响应：

```json
{
  "code": 0,
  "data": {
    "scopeVersion": "2026-07-14T12:00:00.123Z/987654",
    "generatedAt": "2026-07-14T12:00:00.123Z",
    "complete": true,
    "nextCursor": null,
    "items": [
      {
        "vehicleId": "2001",
        "vin": "LXXXXXXXXXXXXXXXX",
        "plateNumber": "沪A00000",
        "customerId": "1001",
        "customerName": "示例客户",
        "contractId": "3001",
        "contractCode": "HT20260001",
        "projectName": "示例项目",
        "departmentId": "4001",
        "departmentName": "运营一部",
        "responsibleUserId": "5001",
        "responsibleUserName": "示例负责人",
        "modelName": "示例车型",
        "brandName": "示例品牌",
        "operationStatus": "2",
        "scopeStartAt": "2026-07-01T08:00:00+08:00",
        "sourceUpdatedAt": "2026-07-14T11:59:58.456+08:00"
      }
    ],
    "rejected": [
      {
        "vehicleId": "2002",
        "reason": "VIN_MISSING"
      }
    ]
  },
  "requestId": "..."
}
```

约束：

- 雪花 ID 一律用 JSON 字符串传输，避免 JavaScript 数字精度丢失。
- `scopeVersion` 对同一业务快照稳定；分页中的每一页必须来自同一个快照。
- `generatedAt` 和 `scopeVersion` 在所有分页中必须完全一致。
- 任意分页 `complete=false` 表示快照不完整，车辆中台不得发布该版本。
- `items` 内 VIN 必须非空、标准化为大写并在当前快照内唯一。
- `rejected` 只返回机器可读原因和内部车辆 ID，不返回敏感客户信息。
- 每页最多 500 条；全部快照最多 50,000 条、100 页。游标不能重复。
- 客户、车辆、合同等雪花 ID 必须使用 JSON 字符串；部门和负责人允许为空，但不能伪造。
- 建议 `ETag=scopeVersion`，后续支持 `If-None-Match` 降低同步流量。

车辆中台已实现该契约的客户端：总同步超时默认 60 秒，单请求超时 10 秒；网络错误、HTTP 429 和 5xx 最多重试 3 次，其他 4xx、业务 code 非 0、JSON 异常、分页版本漂移、重复游标、越界行数或不完整快照立即失败关闭。

### 查询单个客户车辆快照

如 OneOS 还需要为内部业务提供客户级接口，可保留：

```http
GET /inner/v1/customer-vehicle-scopes/{customerId}?cursor=&limit=500
```

该接口不作为车辆中台全量定时同步的唯一入口，以免形成客户级 N+1。

### 批量检查客户车辆归属

供登录后单车访问和安全审计使用，不代替快照同步：

```http
POST /inner/v1/customer-vehicle-scopes/check
Content-Type: application/json

{
  "customerId": "1001",
  "vins": ["LXXXXXXXXXXXXXXXX"]
}
```

响应必须对每个 VIN 返回 `allowed/denied/unknown`。`unknown` 与接口异常在外部访问场景中均按拒绝处理。

## 3. 当前车辆判定

候选记录至少满足：

```text
vehicle_info.del_flag = 0
vehicle_lease_order_record.del_flag = 0
最新有效 delivery_vehicle.delivery_status IN (2,3)
不存在该交车单对应的有效 return_vehicle_task.status IN (2,3,5)
vehicle_lease_order_record.customer_id = customerId（仅作为独立归属交叉校验）
VIN 非空且唯一
```

同时必须核验：

- 记录客户等于合同 `COALESCE(other_customer_id, customer_id)`；
- 不使用 `vehicle_lease_order_record.last_return_time` 判定当前生命周期；OneOS 还车草稿保存会提前写入该聚合字段；
- 聚合记录的合同、交车单和最近历史记录一致；
- 不存在同一 VIN/vehicleId 同时授权给多个客户；
- 合同保存没有覆盖已发生的交还车事实。

生产数据审计完成前，该判定仅为候选口径，不得直接开放外部客户。

## 4. 身份声明契约

客户请求由 OneOS Gateway 完成登录态验证后，可向车辆中台传递短时签名声明：

```json
{
  "iss": "oneos-gateway",
  "aud": "vehicle-data-platform",
  "sub": "1001",
  "subjectType": "customer",
  "customerId": "1001",
  "tenantId": "000000",
  "roles": ["customer_vehicle_viewer"],
  "iat": 1784001600,
  "exp": 1784001900,
  "jti": "..."
}
```

车辆中台必须校验发行方、受众、签名、有效期和 `jti`，并把 `customerId` 写入请求上下文。禁止从 Query、Body 或普通转发头覆盖它。

## 5. 车辆中台投影

建议表：

```text
business_customer
  customer_id, status, source_version, synced_at

business_customer_vehicle_scope
  customer_id, vin, vehicle_id, contract_id, scope_start_at,
  source_version, source_updated_at, published_at

business_scope_sync_run
  run_id, customer_id, source_version, status,
  received_count, accepted_count, rejected_count, started_at, finished_at, error

business_scope_audit
  request_id, principal_id, customer_id, action, vin, decision, reason, created_at
```

唯一约束至少包括 `(customer_id, vin)`；发布新版本时应在事务中整体切换，不能边分页边覆盖当前版本。

## 6. 失败策略

- 首次同步失败：客户门户不可用，不回退到全量车辆。
- 已有快照过期：达到配置的最大陈旧时间后拒绝访问，并告知“业务车辆范围同步异常”。
- 单车不在范围：统一返回 404，避免泄露 VIN 是否存在。
- 多客户冲突或 VIN 缺失：隔离并告警，不授权。
- OneOS 账号停用：会话校验立即失败；车辆中台短时声明最长建议 5 分钟。

## 7. 验收用例

1. 客户 A 无法通过 VIN、车牌、导出、轨迹、告警 ID 或分页游标访问客户 B 的车辆。
2. 车辆还车后，新快照发布即从客户范围移除；旧 URL 也返回 404。
3. 车辆再次交付给另一客户后，仅新客户可见。
4. `other_customer_id` 存在时，只授权给有效丙方客户。
5. 缺 VIN、多客户冲突、聚合与合同不一致的车辆不进入任何外部范围。
6. OneOS 不可用、签名错误、Scope 过期或分页版本变化时全部失败关闭。
7. 1,000 台车辆的快照分页结果无重复、无遗漏，条件请求可返回 304。
8. 所有拒绝决策保留 request ID、主体、VIN 摘要和原因，且不记录访问令牌。

## 8. 兼容与回滚

- 保留现有 Dubbo `RemoteVehicleService`，但在修复前明确标记 `listByCustomerId` 不可用于外部授权。
- 新 HTTP 内部接口使用独立 `/inner/v1` 前缀，不改变现有页面接口。
- 先以影子模式计算快照并与人工样本对账，再允许车辆中台消费。
- 若上线后异常，关闭客户入口并回退到上一个已验证 Scope 版本；不得回退为“无 Scope 查询”。