docs(oneos): publish API integration runbook

vehicle-data-platform/docs/oneos-customer-vehicle-scope-contract.md

@@ -14,23 +14,32 @@
 
 ## 2. 推荐接口
 
-### 查询客户车辆快照
+### 查询车辆中台全量业务范围快照
+
+车辆数据中台的定时同步需要一次读取全部客户的当前车辆范围，避免先拉客户列表再产生 N+1 请求。推荐由 OneOS 提供专用平台快照：
 
 ```http
-GET /inner/v1/customer-vehicle-scopes/{customerId}?cursor=&limit=500
+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": {
-    "customerId": "1001",
     "scopeVersion": "2026-07-14T12:00:00.123Z/987654",
     "generatedAt": "2026-07-14T12:00:00.123Z",
     "complete": true,
@@ -41,9 +50,14 @@ X-Request-Signature: <hmac-sha256>
         "vin": "LXXXXXXXXXXXXXXXX",
         "plateNumber": "沪A00000",
         "customerId": "1001",
+        "customerName": "示例客户",
         "contractId": "3001",
         "contractCode": "HT20260001",
         "projectName": "示例项目",
+        "departmentId": "4001",
+        "departmentName": "运营一部",
+        "responsibleUserId": "5001",
+        "responsibleUserName": "示例负责人",
         "modelName": "示例车型",
         "brandName": "示例品牌",
         "operationStatus": "2",
@@ -66,10 +80,25 @@ X-Request-Signature: <hmac-sha256>
 
 - 雪花 ID 一律用 JSON 字符串传输，避免 JavaScript 数字精度丢失。
 - `scopeVersion` 对同一业务快照稳定；分页中的每一页必须来自同一个快照。
-- `complete=false` 表示快照不完整，车辆中台不得发布该版本。
+- `generatedAt` 和 `scopeVersion` 在所有分页中必须完全一致。
+- 任意分页 `complete=false` 表示快照不完整，车辆中台不得发布该版本。
 - `items` 内 VIN 必须非空、标准化为大写并在当前快照内唯一。
 - `rejected` 只返回机器可读原因和内部车辆 ID，不返回敏感客户信息。
-- 建议 `ETag=scopeVersion`，支持 `If-None-Match` 降低同步流量。
+- 每页最多 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。
 
 ### 批量检查客户车辆归属