跳到主要内容

AOVIS 样机联调前数据准备清单

适用对象：硬件 / 固件 / App / 后端 / 测试同事
适用阶段：设备样机首次联调、用户绑定联调、KVS / IoT / 数据套餐联调前准备
当前版本基于：aovis-direct-store 已上线的 sample integration readiness 方案
注意：本文档描述的是当前系统可联调的 provisional 数据契约，不是最终量产工厂方案

1. 目标​

在设备样机开始联调前，统一明确：

  1. 哪些数据必须由硬件/工厂提供
  2. 哪些数据必须由后端预置到数据库
  3. 哪些数据必须由 App/测试同事准备
  4. 哪些能力现在可以测
  5. 哪些能力仍然依赖 AWS / EIOTCLUB / 正式 provisioning 合同

2. 当前系统最小联调闭环​

当前系统已经支持以下最小闭环：

  1. 测试用户登录并获得 App Token
  2. 后端预置一条待绑定 Device 记录
  3. 样机提交 aovis_device_id + activation_code (+ iccid)
  4. 后端校验：
    • 用户已登录
    • 设备存在
    • activation_code 哈希匹配
    • iccid 与预置 Device.iccid 一致（如提交）
  5. 绑定成功后：
    • 创建 DeviceOwnership
    • 更新 Device.ownerUserId
    • 写入 AuditLog
    • 返回绑定成功结果

3. 联调前必须准备的数据​

3.1 用户侧必须准备​

项目是否必需提供方说明
测试用户账号必需App / 测试一个真实可登录的测试账号（Google / Apple / Magic Link 均可）
App Token必需App / 测试登录成功后拿到的 aovis_app_... token，用于调用绑定和设备接口
测试账号邮箱建议App / 测试便于排查和后台定位用户
测试设备名称可选App / 测试如 iPhone 15 Pro / Pixel 8，用于 token 发放记录

3.2 样机侧必须准备​

项目是否必需提供方说明
aovis_device_id必需硬件 / 固件当前系统里的设备绑定主标识
activation_code必需硬件 / 工厂 / 固件当前样机阶段 provisional 激活码
iccid强烈建议硬件 / 工厂设备内嵌 SIM/eSIM 的 ICCID；如要测 SIM 一致性则必需
firmware_version建议固件联调记录和问题排查使用
serial_number建议硬件 / 工厂便于和工厂批次、外壳标签对应
model建议硬件 / 工厂如 NEXA Prime 4K

3.3 后端数据库必须预置​

至少需要一条 Device 记录，字段建议如下：

字段是否必需说明
aoviseDeviceId必需必须与样机提交的 aovis_device_id 一致
activationCodeHash必需样机 activation_code 的 SHA-256 哈希
iccid强烈建议如果样机会上报 ICCID，则这里必须预置同一个值
ownerUserId建议为空样机首次绑定前应为空
bindingStatus建议 pending表示待绑定
firmwareVersion可选可先空，绑定时回写
status建议 ACTIVE便于后续权限校验

4. 当前绑定接口实际要求​

当前接口：

POST /api/devices/activate
Authorization: Bearer <app_token>
Content-Type: application/json

请求体：

{
  "aovis_device_id": "AOVIS_SAMPLE_001",
  "activation_code": "SAMPLE-ACT-001",
  "iccid": "8988308650104486856",
  "firmware_version": "1.0.3"
}

当前校验规则​

必需规则​

  • 必须带 Authorization: Bearer <app_token>
  • aovis_device_id 必须存在
  • activation_code 必须存在
  • 后端必须能找到对应 Device
  • activation_code 的 SHA-256 必须等于 Device.activationCodeHash

ICCID 规则​

  • 如果请求里带了 iccid
    • 后端 Device.iccid 必须已预置
    • 且两者必须完全一致
  • 如果不一致，会返回：
    • iccid_mismatch
  • 如果后端没预置但请求带了，会返回：
    • iccid_not_preprovisioned

绑定冲突规则​

  • 如果设备已被其他用户绑定，会返回：
    • device_already_bound

5. 当前联调前推荐的样机资料模板​

建议每台样机提前整理成一行记录，交给后端导入或手工预置。

sample_nameaovis_device_idactivation_codeactivationCodeHashiccidfirmware_versionserial_numbermodel测试账号邮箱备注
Sample-001AOVIS_SAMPLE_001SAMPLE-ACT-001<sha256>89883086501044868561.0.3SN-001NEXA Prime 4K[email protected]首台样机

示例说明​

  • activationCodeHash 由后端根据明文 activation_code 生成
  • 明文 activation_code 不建议长期散落在群里，应通过受控表单或安全文档流转
  • aovis_device_id 必须是设备端实际上报给后端的值，不要临时猜

6. 联调前推荐分工​

6.1 硬件 / 工厂 / 固件提供​

至少提供：

  1. aovis_device_id
  2. activation_code
  3. iccid
  4. serial_number
  5. firmware_version

如果后面要做 AWS KVS / IoT 正式联调，建议同时准备：

  1. thingName（如已有）
  2. 设备证书 / provisioning 方案说明
  3. KVS stream / channel 命名约定

6.2 后端准备​

  1. 预置 Device 记录
  2. 生成并写入 activationCodeHash
  3. 预置 Device.iccid
  4. 确认用户账号可登录
  5. 如需测试高级能力，补齐：
    • awsIotThingName
    • kvsStreamName
    • kvsChannelArn
    • 对应 Entitlement

6.3 App / 测试准备​

  1. 准备测试账号
  2. 获取 app_token
  3. 用真实样机数据调用 /api/devices/activate
  4. 记录：
    • 请求参数
    • 返回码
    • 绑定是否成功
    • 后续 /account/devices 是否能看到设备

7. 如果要继续测 KVS / WebRTC / 云回放，还要额外准备什么​

当前仅“绑定成功”还不够。

如果还要测以下接口：

  • /api/devices/[id]/stream
  • /api/devices/[id]/clip
  • /api/devices/[id]/webrtc
  • /api/devices/[id]/shadow
  • /api/devices/[id]/command
  • /api/ai/summary

则还要额外准备：

7.1 Device 的 AWS 映射字段​

字段说明
awsIotThingName设备在 AWS IoT 中的 Thing 名称
kvsStreamNameKVS 回放流名
kvsChannelArnKVS WebRTC Channel ARN

如果这些字段没准备，当前系统会返回：

  • device_not_provisioned

7.2 Entitlement（按能力）​

能力当前要求
live_view目前主要要求设备已 provisioned
cloud_playback需要对应 entitlement
event_clip需要 cloud_playback entitlement
ai_summary需要 ai_summary entitlement

所以如果你要测：

  • 回放
  • 片段下载
  • AI 摘要

还要给测试账号补相应 Entitlement。

8. 如果要继续测 EIOTCLUB / 数据套餐，还要额外准备什么​

8.1 建议额外准备​

项目提供方说明
SimCard.iccid 记录后端本地数据库已有该卡
EIOTCLUB 可查卡状态供应商 / 后端确认卡真实存在于供应商侧
测试用数据套餐运营 / 后端可用于 purchase / activation 测试
Stripe 测试用户/订单测试 / 后端如需测数据套餐支付链路

8.2 当前注意事项​

  • 当前系统已经能处理 data-plan webhook / refund / audit
  • 但供应商实际套餐、卡状态、回调能否联动，还依赖真实 EIOTCLUB 配置

9. 最小联调清单（可以直接执行）​

9.1 最小 4 件套​

如果你现在只想开始“设备与用户绑定”联调，最少准备：

  1. 一个能登录的测试账号
  2. 一个可用的 app_token
  3. 一个真实的 aovis_device_id
  4. 一个与后端 hash 匹配的 activation_code

9.2 推荐 5 件套​

再加上：

  1. 一个与后台 Device.iccid 一致的 iccid

这样就能一起测：

  • 登录
  • 绑定
  • ICCID 一致性校验
  • DeviceOwnership 创建
  • 审计日志写入

10. 当前不能误解成已完成的事项​

以下内容还不能当成正式量产能力：

  1. activation_code 只是 provisional 样机方案
  2. 还没有正式工厂 provisioning 合同
  3. 还没有正式的量产二维码 / claim token 流程
  4. AWS Cognito / IoT / KVS 还不是完整生产打通状态
  5. EIOTCLUB 全链路联动仍依赖真实供应商配置

11. 给团队的简短结论​

当前样机联调前，至少要准备：

  • 一个能登录并拿到 app_token 的测试用户
  • 一条已预置的 Device
  • 样机真实的 aovis_device_id
  • 对应明文 activation_code
  • 后端写好的 activationCodeHash
  • 样机真实 iccid 与后端 Device.iccid 一致

满足这些条件后，就可以开始进行第一阶段设备绑定联调。