# TalkingQ 硬件端注册、临时 Token、OTA 全流程接口文档

版本：2026-05-08  
适用对象：硬件固件、产测工具、工厂烧录工具开发同事  
代码依据：`gateway`、`register`、`token`、`ota` 当前源码

## 1. 总览

默认统一从 Gateway 调用：

```text
http://<gateway-host>:8090
```

不建议设备或工厂工具直连下游服务端口。Gateway 会统一做外部鉴权、限流、单飞控制，并自动给下游服务补充内部调用签名 `X-Internal-*`。

下游服务端口仅用于定位问题：

| 服务 | 默认端口 | Gateway 路由前缀 |
|---|---:|---|
| gateway | 8090 | - |
| register | 8097 | `/register/**` |
| token | 8095 | `/token/**` |
| ota | 8096 | `/ota/**` |

## 2. 全流程逻辑示意图

```mermaid
flowchart TD
    A[工厂产测/烧录工具] --> B{是否已有设备记录}
    B -->|无| C[调用 /register/api/v1/devices 或 /batch 创建设备]
    C --> C1[Gateway X-Factory-* HMAC 鉴权]
    C1 --> C2[Register 校验 X-Api-Key 是否启用/配额是否足够]
    C2 --> D[写入 sys_device 和 device_app 配置]
    B -->|有| E[设备生成 P-256 密钥对]
    D --> E
    E --> F[调用 /register/api/auth/challenge]
    F --> F1[首绑/重绑阶段需要 station_id + sig_b64 工位私钥签名]
    F1 --> G[服务返回 challenge_id/challenge]
    G --> H[设备用设备私钥签名 challenge 消息]
    H --> I[调用 /register/api/auth/response]
    I --> I1[服务验签后签发设备 JWT access_token]
    I1 --> J[设备携带设备 JWT 调用 /token/api/device/token]
    J --> K[Token 服务返回阿里云 DashScope 临时 token/appId/workspaceId/voiceId]
    K --> L[设备连接阿里云 WebSocket/语音链路]
    L --> M[设备定期调用 /ota/api/ota/versionInfoReport 上报固件版本]
    M --> N{是否需要升级}
    N -->|否| O[HTTP 204 No Content]
    N -->|是| P[返回最新 version/url/sha256/sizeBytes/force/update]
    P --> Q[设备下载固件并校验 SHA-256]
    Q --> R[设备升级重启后再次 versionInfoReport]
```

鉴权分层：

```mermaid
flowchart LR
    U[外部调用方] --> G[Gateway]
    G -->|/register/api/v1/**| FH[X-Factory-* HMAC + X-Api-Key]
    G -->|/token/** /ota/api/ota/**| DJ[设备 JWT ES256 + scope]
    G -->|/ota/api/program/**| PJ[小程序设备 JWT HS256, type=device]
    G -->|转发到下游| IH[Gateway 自动注入 X-Internal-*]
    FH --> R[register]
    DJ --> T[token/ota]
    PJ --> O[ota program]
    IH --> R
    IH --> T
```

## 3. 通用约定

| 项 | 说明 |
|---|---|
| Content-Type | JSON 接口统一使用 `application/json` |
| 时间戳 | 除特别说明外，均为 Unix 秒级时间戳 |
| Base64 | `sig_b64` 使用标准 Base64；设备公钥、challenge、设备签名使用 base64url 且无 padding |
| Authorization | 设备 JWT 调用格式：`Authorization: Bearer <access_token>` |
| 成功响应包装 | `AjaxResult`/`ResultMessage` 通常为 `{"code":200,"message":"...","data":...}` |
| 业务错误包装 | Register 认证错误通常为 `{"error_code":"...","message":"..."}`；Gateway 鉴权失败通常为 HTTP 401/403 |

## 4. Gateway 工厂 HMAC 鉴权

当前代码中 Gateway 工厂鉴权只拦截：

```text
/register/api/v1/**
```

也就是以下设备注册接口必须带 `X-Factory-*`：

```text
GET  /register/api/v1/devices/{deviceId}
POST /register/api/v1/devices
POST /register/api/v1/devices/batch
```

`/register/api/factory/**` 当前不在 Gateway `factory-auth.include-paths` 内，这类接口主要依赖请求体里的工位私钥签名 `sig_b64`。如果未来希望它们也经过 Gateway HMAC，需要把 Gateway 配置里的 `gateway.factory-auth.include-paths` 扩展到 `/register/api/factory/**`。

### 4.1 必填请求头

| Header | 必填 | 说明 |
|---|---|---|
| `X-Api-Key` | 是 | 工厂注册 API Key；Gateway 查 Redis 是否启用，Register 查数据库额度 |
| `X-Factory-Timestamp` | 是 | Unix 秒级时间戳，默认允许偏移 300 秒 |
| `X-Factory-Nonce` | 是 | 每次请求唯一随机串，默认 300 秒内不可重复 |
| `X-Factory-Signature` | 是 | HMAC-SHA256 签名后标准 Base64 |

### 4.2 待签名 payload

Gateway 按下面 6 行拼接，换行符是 `\n`：

```text
<HTTP_METHOD>
<RAW_PATH>
<RAW_QUERY>
<BODY_SHA256_HEX>
<X-Factory-Timestamp>
<X-Factory-Nonce>
```

字段规则：

| 字段 | 说明 |
|---|---|
| `HTTP_METHOD` | 大写方法名，例如 `POST` |
| `RAW_PATH` | 原始路径，例如 `/register/api/v1/devices` |
| `RAW_QUERY` | 原始 query，不含 `?`；没有 query 时为空字符串 |
| `BODY_SHA256_HEX` | 请求体字节的 SHA-256 小写 hex；请求体为空时是空字符串，不是空 body 的 SHA-256 |
| `timestamp` | 与请求头完全一致 |
| `nonce` | 与请求头完全一致 |

签名计算：

```text
X-Factory-Signature = Base64( HMAC-SHA256(FACTORY_AUTH_SECRET, payload_utf8) )
```

注意：

| 项 | 说明 |
|---|---|
| `FACTORY_AUTH_SECRET` | 后端环境变量 `FACTORY_AUTH_SECRET`，必须由服务端安全下发给工厂工具，不应写死在固件里 |
| Redis 启用状态 | Gateway 会检查 `gateway:factory:api-key:enabled:{apiKey}` |
| DB 启用/配额 | Register 会检查 `factory_register_quota` 是否启用、未过期、额度足够 |
| 防重放 | 同一 `apiKey + nonce` 默认 300 秒内只能使用一次 |

### 4.3 Python 生成 Gateway 签名示例

```python
import base64
import hashlib
import hmac
import json
import time
import uuid

api_key = "factory-api-key"
secret = "factory-auth-secret"
method = "POST"
raw_path = "/register/api/v1/devices"
raw_query = ""
body_obj = {
    "deviceId": "550e8400-e29b-41d4-a716-446655440000",
    "deviceName": "0508-0001",
    "userId": 1,
    "appId": "mm_xxx",
    "workspaceId": "llm_xxx",
    "voiceId": "kenny",
    "product": "TQ_cat",
    "version": "1.0.0"
}
body = json.dumps(body_obj, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
body_hash = hashlib.sha256(body).hexdigest() if body else ""
payload = "\n".join([method, raw_path, raw_query, body_hash, timestamp, nonce])
signature = base64.b64encode(
    hmac.new(secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).digest()
).decode("ascii")

headers = {
    "Content-Type": "application/json",
    "X-Api-Key": api_key,
    "X-Factory-Timestamp": timestamp,
    "X-Factory-Nonce": nonce,
    "X-Factory-Signature": signature,
}
```

## 5. 工位私钥签名 `sig_b64`

工位签名用于工厂刷写/解锁/上报，以及设备首次绑定或强制重绑时证明“这台设备是在合法工位上生产/绑定”。

涉及接口：

```text
POST /register/api/factory/flash-key
POST /register/api/factory/unlock
POST /register/api/factory/report
POST /register/api/auth/challenge   首绑/重绑或 pending 阶段需要
POST /register/api/auth/response    pending 阶段需要
```

### 5.1 工位密钥配置

Register 服务通过环境变量 `DEVICE_AUTH_FACTORY_STATION_SECRETS_PATH` 指定工位公钥 JSON 文件。支持如下形式：

```json
{
  "station-001": {
    "factory_id": "factory-a",
    "public_key_pem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
  }
}
```

也支持 `public_key`、`public_key_pem_b64`、`public_key_b64` 字段。

### 5.2 待签名 JSON

服务端校验规则：

1. 从请求体中移除 `sig_b64`。
2. 对剩余 JSON 按 key 排序序列化。
3. 使用工位公钥验签。
4. 校验 `timestamp` 默认 300 秒时间窗。
5. 将 `station_id + nonce` 写入数据库防重放。

推荐工厂工具按如下规则生成待签名 bytes：

```python
canonical = json.dumps(payload_without_sig, ensure_ascii=False, separators=(",", ":"), sort_keys=True).encode("utf-8")
```

签名算法按工位公钥类型自动选择：

| 工位公钥类型 | 服务端验签算法 | `sig_b64` 格式 |
|---|---|---|
| EC | `SHA256withECDSA` | DER ECDSA 签名字节再标准 Base64 |
| RSA | `RSASSA-PSS` + SHA-256 | 签名字节标准 Base64 |
| DSA | `SHA256withDSA` | 签名字节标准 Base64 |
| Ed25519/Ed448 | `Ed25519`/`Ed448` | 签名字节标准 Base64 |

如果工位使用 P-256 EC 私钥，`sig_b64` 必须是 DER ECDSA 签名的标准 Base64，不是 raw `r||s`。

### 5.3 Python 生成工位签名示例

```python
import base64
import json
import time
import uuid
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import ec

station_private_key_pem = b"""-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----"""
private_key = serialization.load_pem_private_key(station_private_key_pem, password=None)

payload = {
    "station_id": "station-001",
    "timestamp": int(time.time()),
    "nonce": uuid.uuid4().hex,
    "device_id": "550e8400-e29b-41d4-a716-446655440000"
}
canonical = json.dumps(payload, ensure_ascii=False, separators=(",", ":"), sort_keys=True).encode("utf-8")
sig_der = private_key.sign(canonical, ec.ECDSA(hashes.SHA256()))
payload["sig_b64"] = base64.b64encode(sig_der).decode("ascii")
```

## 6. 设备 P-256 认证协议

设备认证成功后，Register 服务签发 ES256 设备 JWT。该 JWT 后续用于调用 Token 和 OTA 设备接口。

### 6.1 设备公钥 `pub_key`

设备使用 P-256，也就是 `secp256r1`。`pub_key` 格式：

```text
base64url_no_padding( 0x04 || X[32] || Y[32] )
```

其中 `X`、`Y` 是 P-256 公钥坐标，固定 32 字节大端。

### 6.2 公钥指纹 `pub_key_jkt`

服务端按 JWK thumbprint 思路计算：

```json
{"crv":"P-256","kty":"EC","x":"<base64url(X)>","y":"<base64url(Y)>"}
```

然后：

```text
pub_key_jkt = base64url_no_padding( SHA256( compact_sorted_jwk_json_utf8 ) )
```

### 6.3 challenge 签名消息

设备调用 `/register/api/auth/challenge` 后，服务返回 `challenge_id` 和 `challenge`。设备用设备私钥签名下面的原始字节：

```text
UTF8("robot-auth-v1")
+ UUID_TO_16_BYTES(device_id)
+ base64url_decode(challenge_id)
+ base64url_decode(challenge)
+ base64url_decode(pub_key_jkt)
+ int32_be(key_version)
```

签名算法：P-256 ECDSA + SHA-256。  
提交给服务端的 `signature` 格式：

```text
base64url_no_padding( raw_r_32 || raw_s_32 )
```

注意这里和工位签名不同：设备签名要求 raw `r||s`，不是 DER。

### 6.4 rotate 签名消息

密钥轮换时，设备用当前私钥签名：

```text
UTF8("robot-rotate-v1")
+ UUID_TO_16_BYTES(device_id)
+ int32_be(current_key_version)
+ base64url_decode(new_pub_key_jkt)
+ base64url_decode(new_pub_key)
```

提交格式仍是：

```text
base64url_no_padding( raw_r_32 || raw_s_32 )
```

### 6.5 设备 JWT 内容

Register 签发的 JWT：

| Claim | 说明 |
|---|---|
| `sub` | `device_id` |
| `exp` | 默认当前时间 + 600 秒 |
| `scope` | 默认 `ota:report ota:read ota:confirm voice:session` |
| `kv` | 当前设备密钥版本 |

Gateway 对 `/token/**` 和 `/ota/**` 会校验：

1. JWT ES256 签名正确。
2. `exp` 未过期。
3. scope 命中接口规则。
4. Redis 中 `gateway:device:auth:{deviceId}` 的 `auth_status=active`。
5. JWT `kv` 等于当前 `key_version`，或等于仍在宽限期的 `prev_key_version`。

## 7. 推荐硬件调用顺序

### 7.1 工厂生产阶段

1. 工厂工具生成设备 UUID `deviceId` 和序列号 `serialNumber`。
2. 调用 `POST /register/api/v1/devices` 或 `/batch` 创建设备和默认应用配置。
3. 设备生成 P-256 密钥对。
4. 工厂工具或设备调用 `POST /register/api/auth/challenge`，首绑时带 `station_id/timestamp/nonce/sig_b64/pub_key/key_version`。
5. 设备签名 challenge 后调用 `POST /register/api/auth/response` 获取设备 JWT。
6. 设备保存私钥、`device_id`、`key_version`。不要保存工厂 HMAC secret 或工位私钥到设备固件。

### 7.2 设备运行阶段

1. 若没有有效设备 JWT，重新走 challenge/response。
2. 携带设备 JWT 调用 `POST /token/api/device/token` 获取阿里云临时 token。
3. 使用返回的 `token/appId/workspaceId/voiceId` 接入语音链路。
4. 定期或开机调用 `POST /ota/api/ota/versionInfoReport` 上报固件版本。
5. 收到 204 表示无需升级；收到 200 且 `data.notUptodate=1` 表示需要升级。
6. 下载固件，校验 `sha256` 和 `sizeBytes`，升级后再次上报版本。

## 8. Register 接口

### 8.1 创建设备

```text
POST /register/api/v1/devices
```

鉴权：

| 层级 | 要求 |
|---|---|
| Gateway | 必须通过 `X-Factory-*` HMAC |
| Register | 必须通过 `X-Api-Key` 数据库启用/配额校验 |

请求体：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `deviceId` | string | 是 | 设备 UUID，后续设备认证要求 UUID 格式 |
| `userId` | integer | 是 | 绑定用户 ID |
| `deviceName` | string | 否 | 设备名称/序列号；为空时服务端生成 `MMdd` |
| `batchId` | string | 否 | 批次 |
| `clientId` | integer | 否 | 客户/渠道 ID |
| `functionNames` | string | 否 | 功能描述 |
| `ip` | string | 否 | 工厂或设备 IP |
| `location` | string | 否 | 位置信息 |
| `wifiName` | string | 否 | Wi-Fi 名称 |
| `chipModelName` | string | 否 | 芯片型号 |
| `type` | string | 否 | 设备类型 |
| `version` | string | 否 | 初始固件版本 |
| `state` | string | 否 | 状态，默认 `"1"` |
| `product` | string | 否 | 产品标识，用于 OTA 版本匹配 |
| `appId` | string | 否 | 阿里云应用 ID；为空使用默认值 |
| `workspaceId` | string | 否 | 阿里云 workspace；为空使用默认值 |
| `voiceId` | string | 否 | 声音 ID；为空使用默认值 `kenny` |

成功响应：

```json
{
  "code": 200,
  "message": "设备新建成功，app配置添加成功。",
  "data": {
    "deviceId": "550e8400-e29b-41d4-a716-446655440000",
    "deviceName": "0508-0001",
    "product": "TQ_cat",
    "version": "1.0.0"
  }
}
```

### 8.2 查询设备

```text
GET /register/api/v1/devices/{deviceId}
```

鉴权同创建设备，必须带 `X-Factory-*` 和 `X-Api-Key`。

响应：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "deviceId": "550e8400-e29b-41d4-a716-446655440000",
    "deviceName": "0508-0001",
    "product": "TQ_cat",
    "version": "1.0.0"
  }
}
```

### 8.3 批量创建设备

```text
POST /register/api/v1/devices/batch
```

鉴权同创建设备。

请求体：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `devices` | array | 是 | 设备列表 |
| `devices[].deviceId` | string | 是 | 设备 ID |
| `devices[].deviceName` | string | 否 | 设备名称 |
| `devices[].serialNumber` | string | 是 | 序列号，会写入 `deviceName` 和 `device_app.serialNumber` |
| `devices[].batchId` | string | 否 | 批次 |
| `devices[].clientId` | integer | 否 | 客户/渠道 ID |
| `devices[].product` | string | 否 | 产品标识 |
| `userId` | integer | 是 | 用户 ID |
| `appId` | string | 是 | 阿里云应用 ID |
| `workspaceId` | string | 是 | workspace |
| `voiceId` | string | 否 | 声音 ID |
| `state` | string | 否 | 状态，默认 `"1"` |

成功响应：

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "createdCount": 2,
    "appConfigCount": 2
  }
}
```

### 8.4 工厂申请刷写密钥

```text
POST /register/api/factory/flash-key
```

鉴权：请求体必须带工位私钥签名 `sig_b64`。当前 Gateway 不要求 `X-Factory-*`。

请求体：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `station_id` | string | 是 | 工位 ID |
| `timestamp` | integer | 是 | Unix 秒 |
| `nonce` | string | 是 | 防重放随机串，最长 128 |
| `device_id` | string | 是 | 设备 ID，最长 128 |
| `sig_b64` | string | 是 | 对移除 `sig_b64` 后的请求体做工位签名 |

成功响应：

| 字段 | 类型 | 说明 |
|---|---|---|
| `key_b64` | string | 32 字节刷写密钥的标准 Base64 |
| `issued_at` | string | UTC ISO 时间 |
| `expires_at` | string | UTC ISO 过期时间 |
| `expires_in` | integer | 默认 600 秒 |
| `server_time` | integer | 服务端 Unix 秒 |
| `factory_id` | string | 工位配置中的工厂 ID，可能为空 |
| `station_id` | string | 工位 ID |
| `sig_b64` | string | 服务端用工厂私钥签名响应 |
| `alg` | string | 响应签名算法，例如 `ecdsa-sha256` |

### 8.5 工厂申请解锁凭据

```text
POST /register/api/factory/unlock
```

请求体：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `station_id` | string | 是 | 工位 ID |
| `timestamp` | integer | 是 | Unix 秒 |
| `nonce` | string | 是 | 防重放随机串 |
| `device_mac` | string | 是 | MAC，格式 `AA:BB:CC:DD:EE:FF` |
| `purpose` | string | 是 | 默认必须为 `factory_unlock` |
| `proto_version` | integer | 是 | 默认必须为 `1` |
| `sig_b64` | string | 是 | 工位签名 |

成功响应包含：

```json
{
  "device_mac": "aa:bb:cc:dd:ee:ff",
  "purpose": "factory_unlock",
  "proto_version": 1,
  "issued_at": "2026-05-08T01:00:00Z",
  "expires_at": "2026-05-08T01:05:00Z",
  "expires_in": 300,
  "server_time": 1778192400,
  "nonce": "base64url-random",
  "factory_id": "factory-a",
  "station_id": "station-001",
  "sig_b64": "...",
  "alg": "ecdsa-sha256"
}
```

### 8.6 工厂上报刷机/注册结果

```text
POST /register/api/factory/report
```

请求体必填：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `station_id` | string | 是 | 工位 ID |
| `timestamp` | integer | 是 | Unix 秒 |
| `nonce` | string | 是 | 防重放随机串 |
| `device_id` | string | 是 | 设备 ID |
| `firmware_version` | string | 是 | 烧录固件版本 |
| `steps.flash.status` | string | 是 | 刷写步骤状态 |
| `steps.register.status` | string | 是 | 注册步骤状态 |
| `success` | boolean/integer | 否 | 是否成功 |
| `operator` | string | 否 | 操作员 |
| `sig_b64` | string | 是 | 工位签名 |

成功响应：

```json
{
  "status": "ok",
  "report_id": "uuid",
  "server_time": 1778192400
}
```

### 8.7 发起设备认证挑战

```text
POST /register/api/auth/challenge
```

鉴权：

| 场景 | 是否需要工位签名 |
|---|---|
| 设备未绑定，首次写入 `pub_key` | 是 |
| 设备 pending 首绑未完成 | 是 |
| `force_rebind=true` 强制重绑 | 是 |
| 设备已 active 且 `key_version/pub_key` 匹配 | 否 |

请求体：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `device_id` | string | 是 | UUID 字符串 |
| `key_version` | integer | 是 | 正整数，首次一般为 `1` |
| `pub_key` | string | 首绑/重绑必填 | P-256 未压缩点 base64url |
| `force_rebind` | boolean | 否 | 强制重绑新公钥 |
| `station_id` | string | 视场景 | 工位 ID |
| `timestamp` | integer | 视场景 | Unix 秒 |
| `nonce` | string | 视场景 | 防重放随机串 |
| `sig_b64` | string | 视场景 | 工位签名 |

challenge 工位签名 payload 只包含非空字段：

```json
{
  "device_id": "...",
  "key_version": 1,
  "pub_key": "...",
  "force_rebind": false,
  "station_id": "station-001",
  "timestamp": 1778192400,
  "nonce": "..."
}
```

成功响应：

```json
{
  "challenge_id": "base64url-16bytes",
  "challenge": "base64url-32bytes",
  "expires_in": 60,
  "server_time": 1778192400
}
```

### 8.8 提交挑战响应并获取设备 JWT

```text
POST /register/api/auth/response
```

请求体：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `device_id` | string | 是 | UUID |
| `challenge_id` | string | 是 | challenge 接口返回 |
| `signature` | string | 是 | 设备私钥签名，base64url(raw r||s) |
| `station_id` | string | pending 阶段必填 | 工位 ID |
| `timestamp` | integer | pending 阶段必填 | Unix 秒 |
| `nonce` | string | pending 阶段必填 | 防重放随机串 |
| `sig_b64` | string | pending 阶段必填 | 工位签名 |

成功响应：

```json
{
  "access_token": "<device-jwt>",
  "token_ttl": 600
}
```

如果使用上一把仍在宽限期内的 key，响应可能包含：

```json
{
  "access_token": "<device-jwt>",
  "token_ttl": 600,
  "rotate_required": true,
  "server_key_version": 2
}
```

### 8.9 设备密钥轮换

```text
POST /register/api/auth/rotate
```

请求体：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `device_id` | string | 是 | UUID |
| `key_version` | integer | 是 | 当前 key version |
| `new_pub_key` | string | 是 | 新 P-256 公钥 base64url |
| `new_pub_key_jkt` | string | 是 | 新公钥指纹 |
| `signature` | string | 是 | 当前私钥对 rotate 消息签名，base64url(raw r||s) |

成功响应：

```json
{
  "key_version": 2
}
```

## 9. Token 服务所有接口

Token 接口都需要设备 JWT，且必须包含 `voice:session` scope。

通用 Header：

```text
Authorization: Bearer <device_access_token>
Content-Type: application/json
```

### 9.1 获取阿里云临时 Token

```text
POST /token/api/device/token
```

请求体：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `deviceId` | string | 与 `serialNumber` 至少一个 | 设备 ID |
| `serialNumber` | string | 与 `deviceId` 至少一个 | 设备序列号 |
| `appId` | string | 否 | DTO 中存在，当前设备接口实际使用数据库 `device_app` 配置 |
| `workspaceId` | string | 否 | DTO 中存在，当前设备接口实际使用数据库 `device_app` 配置 |
| `voiceId` | string | 否 | DTO 中存在，当前设备接口实际使用数据库 `device_app` 配置 |

如果同时传 `deviceId` 和 `serialNumber`，服务端会校验两者是否匹配。

成功响应：

```json
{
  "code": 200,
  "message": "获取token成功",
  "data": {
    "appId": "mm_xxx",
    "workspaceId": "llm_xxx",
    "voiceId": "kenny",
    "token": "dashscope-temp-token",
    "deviceId": "550e8400-e29b-41d4-a716-446655440000",
    "serialNumber": "0508-0001",
    "expires_at": 1778194200,
    "tokenExpireTime": "2026-05-08T09:30:00",
    "roleKey": "default",
    "roleName": "默认角色",
    "favoriteTeamCode": "",
    "favoriteTeamName": "",
    "favoriteTeamStatus": ""
  }
}
```

说明：

| 字段 | 说明 |
|---|---|
| `token` | 阿里云 DashScope 临时 token，默认申请 1800 秒 |
| `expires_at` | 阿里云真实过期秒级时间戳 |
| `tokenExpireTime` | 本地时区格式化时间 |
| `appId/workspaceId/voiceId` | 设备连接语音服务时需要使用 |
| `roleKey/roleName` | 当前应用角色信息，可能为空字符串 |
| `favoriteTeam*` | 收藏球队信息，未配置时为空字符串 |

Token 服务会优先返回 Redis 缓存中的有效 token；距离过期不足 10 秒时刷新。

### 9.2 强制刷新阿里云临时 Token

```text
POST /token/api/device/token/refresh
```

鉴权、请求体、响应字段与 `/token` 相同。区别是忽略现有缓存，强制调用阿里云刷新。

成功响应：

```json
{
  "code": 200,
  "message": "刷新token成功",
  "data": {
    "appId": "mm_xxx",
    "workspaceId": "llm_xxx",
    "voiceId": "kenny",
    "token": "new-dashscope-temp-token",
    "deviceId": "550e8400-e29b-41d4-a716-446655440000",
    "serialNumber": "0508-0001",
    "expires_at": 1778194200,
    "tokenExpireTime": "2026-05-08T09:30:00",
    "roleKey": "",
    "roleName": "",
    "favoriteTeamCode": "",
    "favoriteTeamName": "",
    "favoriteTeamStatus": ""
  }
}
```

## 10. OTA 服务所有接口

### 10.1 设备上报固件版本并检查升级

```text
POST /ota/api/ota/versionInfoReport
```

鉴权：

| 层级 | 要求 |
|---|---|
| Gateway | 设备 JWT，有 `ota:report` scope |
| OTA 服务 | 设备 JWT 二次校验，有 `ota:report` scope |

Header：

```text
Authorization: Bearer <device_access_token>
Content-Type: application/json
```

请求体：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `deviceId` | string | 是 | 设备 ID |
| `serialNumber` | string | 否 | 设备序列号，当前代码未参与主要逻辑 |
| `version` | string | 是 | 当前固件版本，例如 `1.0.0` 或 `v1.0.0` |
| `isUpdate` | integer | 否 | 设备是否确认升级，版本上报接口当前主要使用 `deviceId/version` |

无升级响应：

```text
HTTP/1.1 204 No Content
Cache-Control: no-store
```

需要升级响应：

```json
{
  "code": 200,
  "message": "固件版本信息上报成功",
  "data": {
    "version": "1.0.1",
    "url": "https://download-url-or-short-link",
    "sha256": "64位hex",
    "sizeBytes": 1234567,
    "force": 0,
    "update": 0,
    "notUptodate": 1
  }
}
```

字段说明：

| 字段 | 说明 |
|---|---|
| `version` | 最新固件版本 |
| `url` | 下载地址；如果启用 COS 预签名，会返回短期可用预签名 URL；如果启用短链，可能返回 `/ota/s/{token}` |
| `sha256` | 固件 SHA-256 hex，设备下载后必须校验 |
| `sizeBytes` | 固件大小，设备可用于下载完整性校验 |
| `force` | `1` 强制升级，`0` 非强制 |
| `update` | 设备是否已确认升级状态 |
| `notUptodate` | `1` 需要升级，`0` 不需要升级 |

异常响应：

| 场景 | HTTP | 响应 |
|---|---:|---|
| `deviceId` 为空 | 400 | `{"code":500,"message":"设备ID不能为空"}` |
| `version` 为空 | 400 | `{"code":500,"message":"固件版本不能为空"}` |
| OTA 下载链接生成失败且 strict-mode=true | 503 | `{"code":503,"message":"OTA下载链接生成失败","data":{"errorCode":"OTA_DOWNLOAD_URL_UNAVAILABLE","reason":"..."}}` |
| JWT 缺失/过期/scope 不匹配 | 401 | Gateway 或服务过滤器返回未授权 |

### 10.2 小程序查询设备版本比对结果

```text
GET /ota/api/program/getVersionInfoCompare/{deviceId}
```

该接口属于小程序/管理侧设备查询接口，不使用设备 JWT scope。Gateway 按 Program Token 校验：

| 要求 | 说明 |
|---|---|
| Header | `Authorization: Bearer <program-device-jwt>` |
| 签名 | HS256，密钥为 Gateway `jwt.secret` |
| Claim `type` | 必须为 `device` |
| Claim `sub` | 必须等于路径中的 `{deviceId}` |

成功响应：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "notUptodate": 1,
    "version": "1.0.1"
  }
}
```

### 10.3 小程序上报升级确认

```text
POST /ota/api/program/versionUpdateConfirm
```

鉴权同上一节 Program Token。Gateway 会从 JSON body 里读取 `deviceId`，并要求 JWT `sub` 与其一致。

请求体：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `deviceId` | string | 是 | 设备 ID |
| `isUpdate` | integer | 是 | 是否确认升级，通常 `1` 是、`0` 否 |
| `version` | string | 否 | DTO 中存在，当前确认接口不使用 |
| `serialNumber` | string | 否 | DTO 中存在，当前确认接口不使用 |

成功响应：

```json
{
  "code": 200,
  "message": "固件版本升级确认成功"
}
```

### 10.4 OTA 短链跳转

```text
GET /ota/s/{token}
```

鉴权：无。Gateway 设备 JWT 忽略 `/ota/s/**`。

用途：当 OTA 开启短链时，`versionInfoReport` 返回短链接，设备访问短链接会跳转到真实 COS 预签名 URL。

响应：

| 场景 | HTTP | 说明 |
|---|---:|---|
| token 格式非法 | 404 | 无响应体 |
| token 不存在或已过期 | 410 | 无响应体 |
| token 有效 | 307 | `Location` 为真实下载 URL |

`token` 格式要求：

```text
^[A-Za-z0-9_-]{8,128}$
```

## 11. curl 调用示例

### 11.1 创建设备

```bash
curl -X POST "http://<gateway-host>:8090/register/api/v1/devices" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <api-key>" \
  -H "X-Factory-Timestamp: <timestamp>" \
  -H "X-Factory-Nonce: <nonce>" \
  -H "X-Factory-Signature: <signature>" \
  -d '{"deviceId":"550e8400-e29b-41d4-a716-446655440000","deviceName":"0508-0001","userId":1,"appId":"mm_xxx","workspaceId":"llm_xxx","voiceId":"kenny","product":"TQ_cat","version":"1.0.0"}'
```

### 11.2 设备获取 challenge

```bash
curl -X POST "http://<gateway-host>:8090/register/api/auth/challenge" \
  -H "Content-Type: application/json" \
  -d '{"device_id":"550e8400-e29b-41d4-a716-446655440000","key_version":1,"pub_key":"<pub_key>","station_id":"station-001","timestamp":1778192400,"nonce":"<nonce>","sig_b64":"<station_sig>"}'
```

### 11.3 设备提交 challenge 签名

```bash
curl -X POST "http://<gateway-host>:8090/register/api/auth/response" \
  -H "Content-Type: application/json" \
  -d '{"device_id":"550e8400-e29b-41d4-a716-446655440000","challenge_id":"<challenge_id>","signature":"<device_raw_rs_sig_b64url>"}'
```

### 11.4 获取阿里云临时 Token

```bash
curl -X POST "http://<gateway-host>:8090/token/api/device/token" \
  -H "Authorization: Bearer <device_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"deviceId":"550e8400-e29b-41d4-a716-446655440000"}'
```

### 11.5 OTA 版本上报

```bash
curl -X POST "http://<gateway-host>:8090/ota/api/ota/versionInfoReport" \
  -H "Authorization: Bearer <device_access_token>" \
  -H "Content-Type: application/json" \
  -d '{"deviceId":"550e8400-e29b-41d4-a716-446655440000","version":"1.0.0"}'
```

## 12. 常见问题排查

| 现象 | 优先检查项 |
|---|---|
| `/register/api/v1/**` 返回 401 | `X-Factory-*` 是否缺失、timestamp 是否超过 300 秒、body hash 是否按真实字节计算、空 body hash 是否误用了 SHA256(empty) |
| `/register/api/v1/**` 返回 403 | `X-Api-Key` 是否在 Redis `gateway:factory:api-key:enabled:{apiKey}` 中启用 |
| Register 返回 `API_KEY_INVALID_OR_DISABLED` | 数据库 `factory_register_quota` 是否启用、是否过期 |
| Register 返回 `API_KEY_QUOTA_EXCEEDED` | 工厂 API Key 注册额度不足 |
| 工位签名失败 | canonical JSON 是否排序且紧凑、是否移除了 `sig_b64`、ECDSA 是否用了 DER 签名、`station_id` 是否存在于 secrets 文件 |
| challenge 返回 `AUTH_PUB_KEY_MISMATCH` | 已绑定设备上报了不同 `pub_key`，需要确认是否应 `force_rebind=true` |
| response 返回 `AUTH_SIG_INVALID` | 设备签名消息拼接顺序、UUID 16 字节、大端 key_version、raw `r||s` 编码是否正确 |
| Token/OTA 返回 401 | 设备 JWT 是否过期、scope 是否包含 `voice:session` 或 `ota:report`、Gateway Redis auth 状态是否 active、`kv` 是否匹配 |
| OTA 一直 204 | 当前版本已不低于最新版本，或产品 `product` 没有匹配到可比较最新版本 |
| OTA 503 | COS/短链配置不完整，且 `OTA_DOWNLOAD_STRICT_MODE=true` |

## 13. 代码依据

| 模块 | 文件 |
|---|---|
| Gateway 工厂 HMAC | `gateway/src/main/java/com/talkingq/gateway/filter/FactoryAuthGlobalFilter.java` |
| Gateway 设备 JWT | `gateway/src/main/java/com/talkingq/gateway/filter/DeviceJwtAuthGlobalFilter.java` |
| Gateway Program JWT | `gateway/src/main/java/com/talkingq/gateway/filter/JwtAuthGlobalFilter.java` |
| Gateway 路由与鉴权配置 | `gateway/src/main/resources/application.yml` |
| 注册设备接口 | `register/src/main/java/com/talkingq/controller/DeviceController.java` |
| 工位签名校验 | `register/src/main/java/com/talkingq/deviceauth/service/StationSignatureVerifier.java` |
| 工厂接口 | `register/src/main/java/com/talkingq/deviceauth/controller/FactoryAuthController.java` |
| 设备认证接口 | `register/src/main/java/com/talkingq/deviceauth/controller/DeviceAuthController.java` |
| 设备认证实现 | `register/src/main/java/com/talkingq/deviceauth/service/impl/DeviceAuthServiceImpl.java` |
| 设备 JWT 签发 | `register/src/main/java/com/talkingq/deviceauth/jwt/DeviceJwtSigner.java` |
| Token 接口 | `token/src/main/java/com/talkingq/controller/DeviceTokenController.java` |
| Token 实现 | `token/src/main/java/com/talkingq/service/impl/TokenServiceImpl.java` |
| 阿里云 token 调用 | `token/src/main/java/com/talkingq/dialogue/token/providers/AliyunAppTokenService.java` |
| OTA 设备接口 | `ota/src/main/java/com/talkingq/controller/OTAController.java` |
| OTA 小程序接口 | `ota/src/main/java/com/talkingq/controller/OTAProgramController.java` |
| OTA 短链接口 | `ota/src/main/java/com/talkingq/controller/OtaShortLinkController.java` |
| OTA 版本逻辑 | `ota/src/main/java/com/talkingq/service/impl/DeviceUpdateServiceImpl.java` |
| OTA 下载 URL | `ota/src/main/java/com/talkingq/service/impl/OtaDownloadUrlService.java` |