feat(auth): add customer demo acceptance gate

2026-07-16 17:20:51 +08:00
parent 7e9f46db2a
commit b2d469835e
7 changed files with 460 additions and 2 deletions
--- a/vehicle-data-platform/docs/customer-demo-acceptance.md
+++ b/vehicle-data-platform/docs/customer-demo-acceptance.md
@@ -0,0 +1,120 @@
+# 客户演示账号与验收手册
+
+更新时间：2026-07-16
+
+本手册用于 0716 会议 P0-08：向秦总、蒲总演示客户侧四个菜单，并在不扩大车辆 Scope、不保存明文密码的前提下形成可重复验收证据。
+
+## 当前生产基线
+
+截至 2026-07-16 17:16（Asia/Shanghai）：
+
+- ECS 共 1,024 辆权威绑定车辆。
+- 平台有 1 个管理员账号和 1 个既有客户账号。
+- 当前没有能从用户名或显示名明确对应“秦总、蒲总”的两个账号。
+- 会议纪要没有提供两人的登录名、初始密码、客户/租户标识和允许查看的车辆清单，因此不得猜测身份或直接扩大既有客户权限。
+
+账号创建时必须只授予：
+
+- `monitor`：全局监控
+- `vehicles`：车辆查询
+- `tracks`：轨迹回放
+- `statistics`：里程查询
+
+不得授予历史数据、告警、接入管理、运维质量或账号管理菜单。
+
+## 建议演示车辆
+
+以下是生产只读筛选得到的首选样本。状态会随实时上报变化，正式演示前必须重新运行门禁；若分类不再成立，应换成同类候选，而不是篡改状态。
+
+| 场景 | 车牌 | VIN | 当前证据 |
+| --- | --- | --- | --- |
+| 在线多来源 | 粤AGR6863 | `LB9A32A21R0LS1464` | GB32960 + JT808，2 个来源均在线且有位置 |
+| 在线单来源 | 浙F31088F | `LA9GG68L5PBAF4797` | JT808 单来源、在线且有位置 |
+| 无实时位置 | 沪BH391挂 | `LA9935J21F0YWT578` | 权威车辆存在，无来源、无位置 |
+| 离线但有最后位置 | 沪A09100F | `LKLG7C4E0NA774774` | JT808 来源离线，保留最后有效位置 |
+
+历史能力预检：
+
+| 车辆 | 2026-07-16 轨迹 | 2026-07-10 至 07-16 里程 |
+| --- | --- | --- |
+| 粤AGR6863 | 返回 1,600 个采样点，约 294.3 km，推荐 GB32960 | 7 个车辆日，约 542.8 km |
+| 浙F31088F | 返回 1,600 个采样点，约 111.8 km，推荐 JT808 | 7 个车辆日，约 360.0 km |
+| 沪A09100F | 返回 955 个点，约 31.9 km，推荐 JT808 | 7 个车辆日，约 280.82 km |
+
+这些数字只用于证明样本具备演示数据，不是业务结算口径。
+
+## 授权时间边界
+
+新账号分配车辆时会以实际创建/授权时间作为历史起点：
+
+- 轨迹只能查询授权开始后的数据。
+- 里程是自然日聚合；如果授权发生在当天零点之后，第一个可完整展示的里程日是下一自然日。
+- 不得为了演示直接回写或倒签 `valid_from`，否则会让客户看到真实授权前的数据并破坏审计。
+
+因此若计划 2026-07-17 演示，应在 2026-07-16 完成账号和车辆授权；轨迹范围从实际授权时间之后开始，里程使用 2026-07-17 当日或之后数据。
+
+## 自动验收门禁
+
+密码只通过临时环境变量传入，不写命令行、脚本、日志或 Git：
+
+```bash
+read -s DEMO_PASSWORD
+export DEMO_PASSWORD
+
+deploy/verify-customer-demo.py \
+  --base-url http://115.29.187.205:20300 \
+  --username '<确认后的登录名>' \
+  --expected-vins 'LB9A32A21R0LS1464,LA9GG68L5PBAF4797,LA9935J21F0YWT578,LKLG7C4E0NA774774' \
+  --multi-source-vin LB9A32A21R0LS1464 \
+  --single-source-vin LA9GG68L5PBAF4797 \
+  --no-location-vin LA9935J21F0YWT578 \
+  --offline-vin LKLG7C4E0NA774774 \
+  --denied-vin LNXNEGRR7SR318212 \
+  --track-vin LB9A32A21R0LS1464 \
+  --track-from '2026-07-16T17:00:00+08:00' \
+  --track-to '2026-07-17T17:00:00+08:00' \
+  --mileage-from 2026-07-17 \
+  --mileage-to 2026-07-17
+
+unset DEMO_PASSWORD
+```
+
+门禁验证：
+
+1. 登录成功且角色为 `customer`。
+2. 菜单严格等于四个客户菜单。
+3. 会话车辆数、实时列表和预期 VIN 集合完全一致。
+4. 四类样本仍符合在线/离线、来源数和位置可用性分类。
+5. 每台授权车辆可读取单车详情。
+6. 未授权 VIN 被 403/404 或按“未解析”隐藏。
+7. 指定车辆存在可回放轨迹和车辆日里程。
+8. 全局监控、车辆详情、轨迹和里程 SPA 路由可加载。
+9. 验收结束后主动注销临时会话。
+
+成功输出示例：
+
+```text
+customer_demo_gate=ok username=<account> vehicles=4 menus=monitor,statistics,tracks,vehicles samples=4 track=1 mileage=1 denied=1
+```
+
+## 演示顺序
+
+1. 使用客户账号登录，确认侧边栏只有四个菜单。
+2. 全局监控搜索四个样本，解释在线多源、在线单源、无位置和离线有位置。
+3. 选择粤AGR6863，进入单车详情，查看最新上报、推荐来源和全部来源差异。
+4. 返回原监控上下文，再进入轨迹回放。
+5. 打开里程查询，使用今天/昨天/近 7 天和协议优先级。
+6. 输入未授权 VIN，确认无法读取。
+7. 记录现场问题、责任人、优先级和是否阻塞交付。
+
+## 尚需业务确认
+
+正式创建两个账号前仍需确认：
+
+- 两个登录名或手机号；
+- 显示名称；
+- 各自初始密码的交付方式；
+- 两人是否共享上述 4 辆演示车，或分别使用不同车辆 Scope；
+- 可选的 OneOS/RuoYi `customerRef`、`tenantRef` 映射值。
+
+这些信息会直接改变真实客户身份和车辆数据可见范围，不能由开发侧猜测。