feat: expand vehicle data platform capabilities

vehicle-data-platform/docs/oneos-sso-deployment-runbook.md

@@ -0,0 +1,118 @@
+# OneOS 单点登录部署与验收手册
+
+更新时间：2026-07-24
+
+## 1. 代码范围
+
+| 系统 | 仓库/分支 | 交付内容 |
+|---|---|---|
+| OneOS 认证服务 | `/Users/lingniu/project/ai-coding/oneos/ln-cloud` / `dev-ssl-codex` | Ticket、introspection、防重放、Nacos 和菜单 SQL |
+| OneOS Web | `/Users/lingniu/project/ai-coding/oneos/ln-one-os-web` / `dev-ssl-codex` | 受登录保护的车辆中台中转页 |
+| 车辆数据中台 | `/Users/lingniu/project/ai-coding/lingniu-vehicle-ingest` | Ticket 兑换、账号/Scope 同步、本地会话、回调页 |
+
+## 2. 生成密钥
+
+分别生成两个不同的随机值，不要使用示例值，也不要提交到 Git：
+
+```bash
+openssl rand -hex 32  # Service Token
+openssl rand -hex 32  # HMAC Signing Secret
+```
+
+双边的 Service Token 必须一致，双边的 Signing Secret 必须一致。两种密钥不能互相复用。
+
+## 3. OneOS 配置
+
+在 `ruoyi-auth.yml` 对应 Nacos 环境发布：
+
+```yaml
+oneos:
+  vehicle-platform-sso:
+    enabled: true
+    callback-url: https://vehicle.example.com/auth/oneos/callback
+    service-token: ${实际 Service Token}
+    signing-secret: ${实际 Signing Secret}
+    audience: vehicle-platform
+    ticket-ttl-seconds: 60
+    clock-skew-seconds: 60
+    allowed-return-paths:
+      - /vehicles
+      - /monitor
+      - /tracks
+      - /statistics
+```
+
+将 `script/config/nacos/ruoyi-gateway.yml` 中新增的 introspection 白名单同步到对应环境。该白名单只跳过用户 Sa-Token 校验，接口自身仍强制校验 Service Token、HMAC、时间戳和 Request ID。
+
+执行：
+
+```text
+script/sql/update/update_vehicle_platform_sso_20260724.sql
+```
+
+然后在 OneOS 角色管理中：
+
+- 给允许进入中台的角色分配“车辆数据中台”，获得 `vehicle:platform:access`；
+- 仅给业务负责人角色分配“查看部门车辆”，获得 `vehicle:scope:department`；
+- 普通业务人员不要分配 `vehicle:scope:department`。
+
+## 4. 车辆数据中台配置
+
+先执行中台迁移，至少包括：
+
+```text
+deploy/migrations/013_platform_identity_access.sql
+deploy/migrations/039_oneos_business_user_scope.sql
+```
+
+设置环境变量：
+
+```dotenv
+AUTH_MODE=enforce
+ONEOS_SSO_ENABLED=true
+ONEOS_SSO_INTROSPECTION_URL=https://oneos.example.com/auth/inner/v1/sso/vehicle-platform/introspect
+ONEOS_SSO_SERVICE_TOKEN=${与 OneOS 相同的 Service Token}
+ONEOS_SSO_SIGNING_SECRET=${与 OneOS 相同的 Signing Secret}
+ONEOS_SSO_AUDIENCE=vehicle-platform
+ONEOS_SSO_DEFAULT_MENUS=vehicles
+ONEOS_SSO_REQUEST_TIMEOUT_MS=3000
+ONEOS_SSO_SESSION_TTL_MINUTES=30
+```
+
+中台会为 OneOS 用户即时创建或更新 `platform_user`，并事务更新：
+
+- `platform_user_menu`；
+- `platform_user_business_scope`；
+- `platform_user_session`；
+- `platform_auth_audit`。
+
+OneOS 会话默认 30 分钟失效；用户可从 OneOS 菜单无感重新进入。这样角色或部门权限变更不会沿用本地 12 小时账号会话。
+
+## 5. 权限验收
+
+至少准备三个 OneOS 账号：
+
+1. 业务一部负责人：有入口权限和部门权限；
+2. 业务一部普通人员：只有入口权限；
+3. 业务二部负责人：有入口权限和部门权限。
+
+逐项验证：
+
+- 三个账号从 OneOS 菜单进入时均不再次输入密码；
+- 负责人只能看到其 `department_ids` 对应部门的车辆；
+- 普通人员只能看到 `responsible_user_id = OneOS userId` 的车辆；
+- 业务一部账号不能看到业务二部车辆；
+- 部门、业务负责人、客户、状态多选只能缩小结果，不能越权扩大；
+- 同一 Ticket 第二次兑换返回 401；
+- Ticket 超过 60 秒后兑换返回 401；
+- 修改 `audience`、HMAC、时间戳或 Request ID 后请求失败；
+- 禁用入口权限后 OneOS 菜单消失，直接调用 Ticket 接口返回 403。
+
+## 6. 回滚
+
+按以下顺序回滚，已有中台本地账号不受影响：
+
+1. 在 OneOS 角色中撤销“车辆数据中台”菜单；
+2. 设置中台 `ONEOS_SSO_ENABLED=false` 并重启；
+3. 设置 OneOS `oneos.vehicle-platform-sso.enabled=false`；
+4. 保留账号、Scope 和审计数据用于追溯，不执行破坏性删除。