# Zenoh RPC 接口说明

本文是服务端当前线上契约。`pet_collar_service` 二进制以 Zenoh **peer** 连接 Router；默认统一运行管理 API 和遥测处理。可选 `--role api` 或 `--role telemetry` 单独运行某个角色。管理 API 声明各域 queryable 并用 Query/Reply 完成请求-响应；遥测处理订阅 GPS、IMU、系统信息和行为结果 topic，验证数据并将其转发给 APP。没有 HTTP 入口。

生产环境可启动多个默认统一服务实例。它们声明相同 queryable；Zenoh 默认的 `BestMatching` 查询目标将一次 RPC 路由到一个匹配 queryable，不要将写操作查询发往 `All` 目标。各实例必须共享 tenant、Redis、开通配置和证书签发配置。遥测处理使用 Redis tenant-scoped 租约确保单活：租约每 5 秒续期，TTL 为 15 秒；租约丢失时实例停止消费，其他实例在租约释放/过期后接管。因此多个统一实例实现 API 负载均衡和遥测故障切换，但不是遥测并行负载均衡。遥测多活仍需按项圈分区队列或消费者组。

## 阅读路线

本文是服务端 API 与设备数据协议的独立参考；JSON 字段的意义、占位值、请求/响应格式和权限要求都在本文内说明。

| 开发任务 | 建议阅读顺序 |
| --- | --- |
| 第一次接入 RPC | §1 调用方式 → §2 请求信封 → §3 响应信封 → 对应 API 操作 |
| APP 登录和业务接口 | §4 身份/会话规则 → §5 错误码 → §6 `auth` → §7 `users` → §8 `collars` |
| ESP32/设备网关 | §8 开通、授权、控制和遥测 topic → §9 证书与在线租约 → §10 客户端处理约定 |
| 排查请求失败 | §2/§3 信封 → §5 错误码 → 对应 API 操作的前置条件 |

### 目录

- [1. 调用方式与接口速查](#1-调用方式)
- [2. 请求信封](#2-请求信封)
- [3. 响应信封](#3-响应信封)
- [4. 身份、会话和短信](#4-身份会话和短信)
- [5. 错误码](#5-错误码)
- [6. 身份认证（auth）](#6-身份认证-auth)
- [7. 用户与设备（users）](#7-用户与设备-users)
- [8. 项圈、设备控制和遥测（collars）](#8-项圈-collars)
- [9. Zenoh 会话凭据与在线租约](#9-zenoh-会话凭据与在线租约)
- [10. 客户端处理约定](#10-客户端处理约定)
- [11. 架构与安全](#11-架构与安全)

### 本文示例中的占位符

尖括号内的内容是说明性占位值，不是可直接发送的值。替换时保留 JSON 原有类型；字符串位置保留双引号，数值位置不要加引号。路径中的 `{tenant}`、`{domain}`、`{operation}` 也必须替换为实际路径段。

| 占位写法 | 实际含义及取值来源 |
| --- | --- |
| `{tenant}` / `<tenant>` | 服务配置的租户名；开发示例默认 `demo`，必须与 Router key 和服务配置一致。 |
| `{domain}` / `{operation}` | API 域和已注册操作名；只能使用本文列出的 `auth`、`users`、`collars` 接口，不是自由输入字段。 |
| `<phone>` / `<手机号>` | 用户手机号，5–32 个字符，只允许数字、`+`、`-`。 |
| `<password>` / `<密码>` | 用户密码，8–64 字节；只应出现在注册或密码登录请求中。 |
| `<sms_code>` / `<验证码>` | 对应手机号和 `scope` 收到的 6 位短信验证码；有效期 600 秒且成功使用后失效。 |
| `<access-token>` / `<access>` | 登录或刷新响应中的访问令牌；放在信封 `token` 字段，并与 `deviceId` 所属设备匹配。 |
| `<refresh-token>` / `<refresh>` | 登录或上一次刷新响应中的刷新令牌；放在 `auth/refresh` 的 `payload.refresh`，每次刷新后都要替换旧值。 |
| `<deviceId>` | APP 设备 ID 或设备/网关身份 ID；需要设备匹配的操作必须与对应 token 或 `collar_id` 相符。 |
| `<user-id>` / `<userId>` | 登录响应 `data.user.userId` 中的用户 ID。 |
| `<session-id>` / `<sessionId>` | 登录响应 `data.sessionId` 中的 APP 会话 ID；刷新 token 不会改变它。 |
| `<collar-id>` / `<collarId>` | 资产系统分配且保持不变的项圈 ID；开通和绑定时使用同一个值。 |
| `<pairing-code>` | 为单台项圈生成、交给用户绑定用的配对码；不是开通口令或遥测私钥。 |
| `<provisioning-token>` / `<secret>` | 管理服务配置的共享开通口令；只放在 `payload.provisioning_token`，不要写入固件或 APP。 |
| `<telemetry-key-id>` / `<key-id>` | 开通时登记的遥测公钥标识；必须与签名信封 `auth.keyId` 一致。 |
| `<64 hex characters>` | 32 字节 Ed25519 公钥的 64 位十六进制编码；是公钥，不是设备私钥。 |
| `<128 hex characters>` | 64 字节 Ed25519 签名的 128 位十六进制编码；需由对应设备私钥针对完整信封内容生成。 |
| `<CSR PEM>` / `<certificate PEM>` | APP 本地生成的 PEM PKCS#10 CSR / 服务签发的 PEM 客户端证书；APP 私钥不发送给服务。 |
| `<command-id>` / `<命令 ID>` | 服务生成的设备控制命令关联 ID；设备确认时必须原样回显。 |
| `...` | 省略或隐藏的示意内容。若在引号内（如 `"access":"..."`），用真实字符串替换 `...` 并保留引号；若未加引号，则表示结构被省略，必须补全为合法 JSON 后才能发送。 |
| 示例中的 `0` 时间戳 | 仅当字段说明标记为时间占位值时，替换为实际 Unix 毫秒时间；其他字段的数值 `0` 仍可能是合法数据。 |

已注册 27 个 API 操作（其中 3 个占位接口固定返回 `503`）：

| 域 | Key 后缀 | 用户 access token |
| --- | --- | --- |
| auth | `register` `loginByPassword` `loginBySms` `loginByOauth` `sendSms` `refresh` `logout` `resetPassword` `bindPhone` `issueZenohCredential` | `logout`、`issueZenohCredential` 需要 |
| users | `listDevices` `listCollars` `removeDevice` `telemetryHeartbeat` | 都需要 |
| collars | `provisionCollar` `bind` `unbind` `listUsers` `getSystemInfo` `getCollarSettings` `setCollarSettings` `setGeofence` `findPet` `createShareInvite` `acceptShareInvite` `authorizeGpsPublisher` `authorizeImuPublisher` | 除开通、两个发布者检查外都需要 |

`loginByOauth`、`resetPassword`、`bindPhone` 已占位，调用后固定返回 `503`。

## 1. 调用方式

客户端对**精确 key** 发 Zenoh `get`，payload 为 UTF-8 JSON 信封。服务把 JSON 响应 reply 到同一个 key。

```text
petpal/{tenant}/api/v1/{domain}/{operation}
```

默认租户是 `demo`，例如密码登录：

```text
petpal/demo/api/v1/auth/loginByPassword
```

约束：

- key 必须正好 6 段。`tenant`、`domain`、`operation` 只允许 ASCII 字母、数字、`_`、`-`。
- key 里的 tenant 必须等于服务配置的 tenant，否则 `403`，`msg` 为 `tenant does not match service`。
- 不要在 key 中放手机号、用户 ID、项圈 ID 或通配符。`petpal/{tenant}/api/v1/auth/**` 这类 key 会得到 `404`。
- 服务只声明 `petpal/{tenant}/api/v1/auth/**`、`.../collars/**`、`.../users/**` 三个域。未知域返回 `404`，`msg` 为 `unknown API key`；已知域中的未知操作返回 `404`，`msg` 为 `unknown operation`。
- 查询不带 payload 时返回 `400`，`msg` 为 `request payload is required`，此时 `reqId` 为空字符串。
- 服务本身不设 RPC 处理超时。联调客户端使用 10 秒查询超时。

Zenoh 1.10 的 `z_get` 示例：

```sh
z_get \
  --connect tcp/127.0.0.1:7447 \
  --selector 'petpal/demo/api/v1/auth/sendSms' \
  --payload '{"v":2,"reqId":"r1-1731398400000","deviceId":"ios-3f2a","ts":1731398400000,"payload":{"phone":"+8613800138000","scope":"login"}}' \
  --timeout 10000
```

### RPC 请求/应答速查

以下 `payload` 字段名均为 snake_case；所有调用还必须带第 2 节定义的 v2 请求信封。成功结果是通用响应信封的 `data` 字段。示例中的 `0` 是时间戳占位值。每个字段的具体规则和错误条件见后续操作说明。

| API key 后缀 | `token` / `deviceId` | `payload` | 成功 `data` |
| --- | --- | --- | --- |
| `auth/sendSms` | 无 access token；需要 `deviceId` | `phone`, `scope`（`register` 或 `login`） | debug：`{ "smsCode": "...", "expiresIn": 600 }`；release：`{ "expiresIn": 600 }` |
| `auth/register` | 无 access token；需要 `deviceId` | `phone`, `sms_code`, `password`, `device_name`, `device_model`, `platform`, `os_ver` | 注册登录数据，见 §4.1 |
| `auth/loginByPassword` | 无 access token；需要 `deviceId` | `phone`, `password`, `device_name`, `device_model`, `platform`, `os_ver` | 登录数据，见 §4.1 |
| `auth/loginBySms` | 无 access token；需要 `deviceId` | `phone`, `sms_code`, `device_name`, `device_model`, `platform`, `os_ver` | 登录数据，见 §4.1 |
| `auth/loginByOauth` | 无 access token；需要 `deviceId` | 当前不读取 payload，`{}` 即可 | 不成功；固定返回 `503`，`data: null` |
| `auth/resetPassword` | 无 access token；需要 `deviceId` | 当前不读取 payload，`{}` 即可 | 不成功；固定返回 `503`，`data: null` |
| `auth/bindPhone` | 无 access token；需要 `deviceId` | 当前不读取 payload，`{}` 即可 | 不成功；固定返回 `503`，`data: null` |
| `auth/refresh` | 不使用 access token；需要 `deviceId` | `refresh` | `{ "access": "...", "accessExpireAt": 0, "refresh": "...", "refreshExpireAt": 0, "sessionId": "..." }` |
| `auth/logout` | 需要 access token 和当前设备 `deviceId` | `{}` | `{ "loggedOut": true }` |
| `auth/issueZenohCredential` | 需要 access token 和当前设备 `deviceId`；仅 mTLS 签发开启时可用 | `csr_pem` | `{ "sessionId": "...", "certificatePem": "...", "expiresAt": 0, "topicPrefix": "..." }` |
| `users/listDevices` | 需要 access token；`deviceId` 可省略 | `{}` | `{ "sessions": [{ "deviceId": "...", "deviceName": "...", "deviceModel": "...", "platform": "...", "loginAt": 0, "sessionDurationMs": 0, "lastActiveAt": 0, "current": true }] }` |
| `users/listCollars` | 需要 access token；`deviceId` 可省略 | `{}` | `{ "collars": ["collar-001"] }` |
| `users/removeDevice` | 需要 access token 和当前设备 `deviceId` | `device_id`（要移除的另一台设备） | `{ "revoked": true, "deviceId": "..." }` |
| `users/telemetryHeartbeat` | 需要 access token 和当前设备 `deviceId` | `{}` | `{ "sessionId": "...", "onlineUntil": 0 }` |
| `collars/provisionCollar` | 无 access token；需要合法 `deviceId` | `provisioning_token`, `collar_id`, `pairing_code`, `telemetry_key_id`, `telemetry_public_key` | `{ "collarId": "...", "telemetryKeyId": "...", "provisioned": true }` |
| `collars/bind` | 需要 access token 和当前设备 `deviceId` | `collar_id`, `pairing_code` | `{ "collarId": "...", "bound": true }` |
| `collars/unbind` | 需要 access token 和当前设备 `deviceId` | `collar_id` | `{ "collarId": "...", "bound": false }` |
| `collars/listUsers` | 需要 access token；`deviceId` 可省略 | `collar_id` | `{ "collarId": "...", "users": ["user-id"] }` |
| `collars/getSystemInfo` | 需要 access token、已绑定；`deviceId` 可省略 | `collar_id` | `{ "collarId": "...", "systemInfo": { "reportedAt": 0, "info": { "seq": 1, "startupTime": 0, "uptimeSeconds": 0, "flashBytes": 4194304, "manufacturer": "...", "batteryPercent": 87, "firmwareVersion": "1.2.3" } } }` |
| `collars/getCollarSettings` | 需要 access token、已绑定；`deviceId` 可省略 | `collar_id` | `{ "collarId": "...", "buzzerOn": false, "ledOn": false, "imuBatchIntervalSeconds": 1, "gpsIntervalSeconds": 1 }` |
| `collars/setCollarSettings` | 需要 access token、已绑定及当前设备 `deviceId` | `collar_id`，以及一个或多个 `buzzer_on`, `led_on`, `imu_batch_interval_seconds`, `gps_interval_seconds` | 返回保存后的完整用户设置、`deviceSettingsVersion` 和 `status` |
| `collars/setGeofence` | 需要 access token、已绑定及当前设备 `deviceId` | `collar_id`, `center`, 可选 `vertices` | `{ "collarId": "...", "center": { "latitude": 39.9, "longitude": 116.4 }, "vertices": [], "boundaryType": "circle", "radiusMeters": 2000 }` |
| `collars/findPet` | 需要 access token、已绑定及当前设备 `deviceId` | `collar_id`, 可选 `duration_seconds`（5–120，默认 30） | `{ "collarId": "...", "commandId": "...", "status": "started", "durationSeconds": 30, "startedAt": 0 }` |
| `collars/createShareInvite` | 需要 access token 和当前设备 `deviceId` | `collar_id`, 可选 `streams` | `{ "inviteToken": "...", "expiresIn": 900 }` |
| `collars/acceptShareInvite` | 需要 access token 和当前设备 `deviceId` | `invite_token` | `{ "collarId": "...", "bound": true, "streams": ["gps"] }` |
| `collars/authorizeGpsPublisher` | 无 access token；需要 `deviceId == collar_id` | `collar_id` | `{ "collarId": "...", "authorized": true }` |
| `collars/authorizeImuPublisher` | 无 access token；需要 `deviceId == collar_id` | `collar_id` | `{ "collarId": "...", "authorized": true }` |

`loginByOauth`、`resetPassword`、`bindPhone` 目前是未实现占位接口。publisher 检查接口只允许受信任网关调用；网关身份必须由部署侧 Router ACL 限定。

### 接口字段中文说明

以下逐个说明所有 RPC 的业务请求字段和成功响应 `data` 字段；字段名与 JSON 保持一致。
请求/响应信封字段另见第 2、3 节。

| 接口 | 请求字段中文解释 | 成功响应 `data` 字段中文解释 |
| --- | --- | --- |
| `auth/sendSms` | `phone`：手机号；`scope`：验证码用途，`register` 为注册、`login` 为登录 | `smsCode`：仅 debug 返回的验证码；`expiresIn`：验证码有效秒数 |
| `auth/register` | `phone`：手机号；`sms_code`：短信验证码；`password`：登录密码；`device_name`：设备显示名称；`device_model`：设备型号；`platform`：操作系统平台；`os_ver`：系统版本 | 返回登录数据，字段见下方“登录响应” |
| `auth/loginByPassword` | `phone`：手机号；`password`：登录密码；`device_name`：设备显示名称；`device_model`：设备型号；`platform`：操作系统平台；`os_ver`：系统版本 | 返回登录数据，字段见下方“登录响应” |
| `auth/loginBySms` | `phone`：手机号；`sms_code`：短信验证码；`device_name`：设备显示名称；`device_model`：设备型号；`platform`：操作系统平台；`os_ver`：系统版本 | 返回登录数据，字段见下方“登录响应” |
| `auth/loginByOauth` | 无；当前不读取业务字段 | 未实现，固定返回 `503` |
| `auth/resetPassword` | 无；当前不读取业务字段 | 未实现，固定返回 `503` |
| `auth/bindPhone` | 无；当前不读取业务字段 | 未实现，固定返回 `503` |
| `auth/refresh` | `refresh`：用于轮换令牌的刷新令牌 | `access`：新访问令牌；`accessExpireAt`：访问令牌过期时间；`refresh`：新刷新令牌；`refreshExpireAt`：刷新令牌过期时间；`sessionId`：保持不变的会话 ID |
| `auth/logout` | 无业务字段 | `loggedOut`：是否已吊销当前设备会话 |
| `auth/issueZenohCredential` | `csr_pem`：客户端提供的 PEM 编码证书签名请求 | `sessionId`：APP 会话 ID；`certificatePem`：签发的客户端证书；`expiresAt`：证书过期时间；`topicPrefix`：证书获准访问的 topic 前缀 |
| `users/listDevices` | 无业务字段 | `sessions`：有效设备会话列表；每项的 `deviceId` 为设备 ID、`deviceName` 为设备名称、`deviceModel` 为设备型号、`platform` 为平台、`loginAt` 为登录时间、`sessionDurationMs` 为会话持续毫秒数、`lastActiveAt` 为最后活跃时间、`current` 表示是否为当前会话 |
| `users/listCollars` | 无业务字段 | `collars`：当前用户已绑定项圈 ID 列表 |
| `users/removeDevice` | `device_id`：要吊销的另一台设备 ID | `revoked`：是否已吊销；`deviceId`：被移除设备 ID |
| `users/telemetryHeartbeat` | 无业务字段 | `sessionId`：当前 APP 会话 ID；`onlineUntil`：会话在线租约截止时间 |
| `collars/provisionCollar` | `provisioning_token`：管理端开通口令；`collar_id`：项圈 ID；`pairing_code`：APP 绑定配对码；`telemetry_key_id`：遥测签名公钥 ID；`telemetry_public_key`：Ed25519 公钥的 64 位十六进制字符串 | `collarId`：项圈 ID；`telemetryKeyId`：登记的遥测公钥 ID；`provisioned`：是否开通成功 |
| `collars/bind` | `collar_id`：项圈 ID；`pairing_code`：项圈配对码 | `collarId`：项圈 ID；`bound`：是否已绑定 |
| `collars/unbind` | `collar_id`：要解绑的项圈 ID | `collarId`：项圈 ID；`bound`：解绑后为 `false` |
| `collars/listUsers` | `collar_id`：项圈 ID | `collarId`：项圈 ID；`users`：已绑定用户 ID 列表 |
| `collars/getSystemInfo` | `collar_id`：项圈 ID | `collarId`：项圈 ID；`systemInfo.reportedAt`：上报时间；`systemInfo.info`：最近一次有效系统信息，字段见 §8 |
| `collars/getCollarSettings` | `collar_id`：项圈 ID | `collarId`：项圈 ID；`buzzerOn`：蜂鸣器开关；`ledOn`：LED 开关；`imuBatchIntervalSeconds`：IMU 批量上报间隔秒数；`gpsIntervalSeconds`：GPS 上报间隔秒数 |
| `collars/setCollarSettings` | `collar_id`：项圈 ID；`buzzer_on`：蜂鸣器开关；`led_on`：LED 开关；`imu_batch_interval_seconds`：IMU 批量上报间隔秒数；`gps_interval_seconds`：GPS 上报间隔秒数。可部分更新，间隔范围为 1–60 秒 | 返回已保存的完整设置；`deviceSettingsVersion`：设备命令单调递增版本；`status`：`applied` 表示设备确认应用，`pending` 表示已保存但未确认；`syncError`：可选的设备同步失败原因 |
| `collars/setGeofence` | `collar_id`：项圈 ID；`center.latitude`：围栏中心纬度；`center.longitude`：围栏中心经度；`vertices`：可选的多边形边界顶点数组 | `collarId`：项圈 ID；`center`：围栏中心；`vertices`：边界顶点；`boundaryType`：`circle` 或 `polygon`；`radiusMeters`：圆形围栏半径（米） |
| `collars/findPet` | `collar_id`：项圈 ID；`duration_seconds`：可选寻宠时长，单位秒 | `collarId`：项圈 ID；`commandId`：设备控制命令 ID；`status`：启动状态；`durationSeconds`：实际寻宠时长；`startedAt`：设备确认启动时间 |
| `collars/createShareInvite` | `collar_id`：项圈 ID；`streams`：可选的数据流权限列表 | `inviteToken`：一次性分享邀请码；`expiresIn`：邀请有效秒数 |
| `collars/acceptShareInvite` | `invite_token`：收到的一次性分享邀请码 | `collarId`：获分享的项圈 ID；`bound`：是否已建立共享绑定；`streams`：授予的数据流权限 |
| `collars/authorizeGpsPublisher` | `collar_id`：请求发布 GPS 的项圈 ID | `collarId`：项圈 ID；`authorized`：是否允许发布 |
| `collars/authorizeImuPublisher` | `collar_id`：请求发布 IMU 的项圈 ID | `collarId`：项圈 ID；`authorized`：是否允许发布 |

通用响应信封字段：

| 字段 | 中文解释 |
| --- | --- |
| `v` | 响应协议版本，固定为 `2` |
| `reqId` | 对应请求的关联 ID；可用于将响应与发起的请求配对 |
| `code` | 业务结果码，`0` 表示成功，非零表示失败 |
| `msg` | 面向开发者的结果说明；客户端应按 `code` 本地化，不直接展示给用户 |
| `data` | 操作返回的数据对象；成功时按接口定义，失败时通常为 `null` |
| `ts` | 服务端生成响应的 Unix 毫秒时间 |

#### 登录响应字段

注册、密码登录和短信登录共用以下字段：`access` 是访问令牌，`accessExpireAt` 是其过期时间；
`refresh` 是刷新令牌，`refreshExpireAt` 是其过期时间；`sessionId` 是服务端会话 ID；
`user.userId` 是用户 ID，`user.phone` 是手机号；`isNewUser` 表示本次是否新注册；
`deviceId` 是本次登录设备 ID；`collarSettings` 是该用户已绑定项圈的设置数组。
数组每项包含 `collarId`（项圈 ID）、`buzzerOn`（蜂鸣器开关）、`ledOn`（LED 开关）、
`imuBatchIntervalSeconds`（IMU 批量上报间隔秒数）和 `gpsIntervalSeconds`（GPS 上报间隔秒数）。

## 2. 请求信封

顶层字段是 camelCase，`payload` 内字段是 snake_case。

```json
{
  "v": 2,
  "reqId": "r42-1699365120000",
  "token": "可选，不透明 access token",
  "deviceId": "ios-3f2a",
  "ts": 1699365120000,
  "payload": {}
}
```

| 字段 | 规则 |
| --- | --- |
| `v` | 必须为 `2`。其他值返回 `400`，`msg` 为 `unsupported envelope version`。 |
| `reqId` | 最后一个 `-` 之前是非空前缀，只含 ASCII 字母、数字、`_`、`-`；之后正好 13 位数字。例如 `r42-1699365120000`、`api_test_1-1699365120000`。非法值返回 `400`，`msg` 为 `invalid reqId`。服务校验格式，**不**把它当作幂等键，重试同一 `reqId` 会再次执行。 |
| `token` | 需要登录的操作放 access token。登录、注册、发短信、刷新 token、开通项圈都不读取这个字段。 |
| `deviceId` | 见下一节。允许 1–128 个字符，字符集为 ASCII 字母、数字和 `-` `_` `.` `:`。 |
| `ts` | Unix 毫秒。与服务端当前时间相差超过 120 秒返回 `400`，`msg` 为 `ts is outside the allowed window`。 |
| `payload` | 必须是 JSON object。嵌套的 object/array 深度超过 5 返回 `400`。缺字段或类型不是非空字符串时，`msg` 为 `missing or invalid {field}`。 |

整段请求 UTF-8 字节数上限为 16KB，超出返回 `400`，`msg` 为 `request exceeds 16KB`。无法解析的 JSON 返回 `400`，`msg` 以 `invalid request envelope:` 开头。

### 哪些操作可以省略 deviceId

以下五个操作从 access token 识别用户和设备，信封里不要依赖 `deviceId`，省略时按空字符串处理：

- `users/listDevices`
- `users/listCollars`
- `collars/listUsers`
- `collars/getSystemInfo`
- `collars/getCollarSettings`

其余 22 个操作都必须带合法 `deviceId`，否则 `400`，`msg` 为 `invalid deviceId`。

需要用户 token、并且要求 `deviceId` 的操作，还会核对该值是否等于 token 所属设备。不一致返回 `403`：

- access token：`token belongs to another device`（`logout`、`users/removeDevice`、`collars/bind`、`collars/unbind`）
- refresh token：`refresh token belongs to another device`

## 3. 响应信封

所有 RPC 共用以下响应结构：

```json
{
  "v": 2,
  "reqId": "r42-1699365120000",
  "code": 0,
  "msg": "ok",
  "data": {},
  "ts": 1699365120123
}
```

| 字段 | 含义 |
| --- | --- |
| `v` | 响应信封协议版本，固定为数字 `2`。 |
| `reqId` | 原样回显请求关联 ID，用来匹配请求和响应；它不提供幂等保证。 |
| `code` | 业务结果码；`0` 表示成功，非零表示失败。它不是 HTTP 状态码。 |
| `msg` | 面向开发者的英文结果说明；客户端应按 `code` 本地化，不要直接展示给用户。 |
| `data` | 操作结果对象；成功时按操作定义，失败时通常为 `null`，特定错误可携带诊断数据。 |
| `ts` | 服务端生成响应时的 Unix 毫秒时间戳。 |

成功响应的 `msg` 为 `ok`。失败时 `data` 通常为 `null`；`4512` 会返回现存会话列表，
短信验证锁定会返回 `retryAfterMs`。没有 reply 或超时不是业务错误响应，应检查 Router、
tenant、服务进程和精确 key。

## 4. 身份、会话和短信

### 4.1 令牌（Token）

注册和登录成功后签发一对不透明 token。实现是 UUID，只在 Redis 保存 SHA-256。access token 有效期 30 分钟，refresh token 有效期 30 天。

成功登录（注册、密码登录、短信登录）的 `data`：

```json
{
  "access": "32位十六进制",
  "accessExpireAt": 1699366920000,
  "refresh": "32位十六进制",
  "refreshExpireAt": 1701957120000,
  "sessionId": "服务端生成的会话 ID",
  "user": { "userId": "32位十六进制", "phone": "+8613800138000" },
  "isNewUser": false,
  "deviceId": "ios-3f2a",
  "collarSettings": [
    {
      "collarId": "collar-001",
      "buzzerOn": false,
      "ledOn": false,
      "imuBatchIntervalSeconds": 1,
      "gpsIntervalSeconds": 5
    }
  ]
}
```

`auth/register` 的 `isNewUser` 为 `true`，两种登录为 `false`。`auth/refresh` 返回新的 `access`、`refresh`、过期时间和不变的 `sessionId`。

同一账号使用相同 `deviceId` 再次登录会替换该设备的会话：旧 access / refresh 立即失效，
旧 session 的遥测在线租约被清理，并签发新的 token 和 `sessionId`。其他设备的会话保持有效。

### 4.2 会话上限

同一用户最多 5 个仍有效的设备会话。第 6 台**新**设备登录返回 `4512`，`msg` 为 `active session limit reached`，`data.sessions` 列出当前会话，服务不会自动踢掉任何设备：

```json
{
  "sessions": [
    {
      "deviceId": "ios-3f2a",
      "deviceName": "Wayne's phone",
      "deviceModel": "Phone 16",
      "platform": "ios",
      "loginAt": 1699365120000,
      "lastActiveAt": 1699365120000
    }
  ]
}
```

`data.sessions` 中每个对象只包含以下字段（与成功的 `users/listDevices` 结果不同）：

| 字段 | 含义 |
| --- | --- |
| `deviceId` | 已占用会话的设备 ID。 |
| `deviceName` | 登录时提交的设备显示名称。 |
| `deviceModel` | 登录时提交的设备型号。 |
| `platform` | `ios`、`android` 或 `ohos`。 |
| `loginAt` | 登录时间，Unix 毫秒。 |
| `lastActiveAt` | 最近一次成功访问时间，Unix 毫秒。 |

已登录设备再次登录不受这个上限影响。

### 4.3 设备信息

注册和两种登录的 `payload` 都要带：

| 字段 | 规则 |
| --- | --- |
| `device_name` | 非空，最长 128 字节 |
| `device_model` | 非空，最长 128 字节 |
| `platform` | 只能是 `ios`、`android`、`ohos` |
| `os_ver` | 非空，最长 128 字节 |

### 4.4 密码和锁定

密码长度为 8–64 字节。连续 5 次密码失败后锁定 15 分钟，期间以及触发锁定的那一次都返回 `4514`，`msg` 为 `account is temporarily locked`。失败计数从第一次失败起 15 分钟后过期。成功密码登录会清除计数。未注册手机号也记一次失败并返回 `401`，`msg` 为 `invalid credentials`，因此错误号码也可能被锁。

### 4.5 短信验证码

`auth/sendSms` 的 `scope` 只能是 `register` 或 `login`。验证码是 6 位数字，保存 10 分钟，校验成功后立即删除，只能使用一次。

- **debug 构建**（`cargo run`，未加 `--release`）始终把验证码放在 `data.smsCode` 并打印到服务终端。配置了完整阿里云短信参数时先向供应商发送；未配置时仅用于本地联调，不发送外部短信。
- **release 构建**必须先调用阿里云短信，供应商接受后才写入 Redis。响应只有 `expiresIn`，日志也不包含验证码。模板参数为 `code`（验证码）和 `time`（固定字符串 `10`，单位分钟）。

`scope=register` 且手机号已注册时，不发送、不保存验证码，直接返回 `4517`。

校验失败：

| 情况 | code | msg | data |
| --- | --- | --- | --- |
| 验证码错误 | 4510 | `invalid SMS code` | `null` |
| 没有验证码或已过期 | 4511 | `SMS code is missing or expired` | `null` |
| 同一验证码错误达到 10 次 | 429 | `SMS code attempt limit reached` | `{ "retryAfterMs": 900000 }` |
| 1 小时内因此作废 3 个验证码，或仍处于锁定中 | 429 | `SMS verification is temporarily locked` | `{ "retryAfterMs": 900000 }` |

第 10 次错误会作废当前验证码。锁定持续 15 分钟。

### 4.6 刷新令牌轮换和吊销

`auth/refresh` 同时轮换 access 和 refresh。旧 refresh 进入已使用名单，保留到原 refresh 过期。

- 再次提交已轮换的 refresh：服务吊销该设备整个会话，返回 `4403`，`msg` 为 `refresh token replay detected`。
- 会话已被登出或剔除后使用旧 refresh：`4403`，`msg` 为 `session was revoked`。
- 未知或过期：`401`，`msg` 为 `invalid or expired refresh token`。
- 与会话中记录不一致，或并发轮换失败：`401`，分别为 `invalid or rotated refresh token`、`refresh token has already been rotated`。

登出或剔除后，原 access token 返回 `4403`，`msg` 为 `session was revoked`。从未签发或已自然过期、且不在吊销名单中的 access token 返回 `401`，`msg` 为 `invalid or expired token`。

通过 access token 访问会更新该会话的 `last_active_at`，并把会话记录的 TTL 续到 30 天。access token 自身仍按签发时的 30 分钟过期，不会因普通请求延长。

## 5. 错误码

| code | 含义 | 本服务中的典型 msg |
| --- | --- | --- |
| 0 | 成功 | `ok` |
| 400 | 信封或参数不合法 | `invalid reqId`、`invalid phone`、`password must be 8-64 bytes`、`invalid pairing_code`、`invalid center coordinates`、`invalid geofence vertices`、`invalid duration_seconds`、`use logout to remove the current device` |
| 401 | 凭证无效或过期 | `invalid credentials`、`token is required`、`invalid or expired token`、`session not found` |
| 403 | 已识别调用方但无权操作 | `tenant does not match service`、`invalid provisioning token`、`collar is not bound to this user`、`token belongs to another device` |
| 404 | key、操作或绑定不存在 | `unknown API key`、`unknown operation`、`session not found`、`collar is not bound to this user` |
| 429 | 短信校验锁定 | 见 §4.5，`data.retryAfterMs` 为 900000 |
| 4403 | 会话已吊销或 refresh 重放 | `session was revoked`、`refresh token replay detected` |
| 4510 | 短信验证码错误 | `invalid SMS code` |
| 4511 | 短信验证码缺失或过期 | `SMS code is missing or expired` |
| 4512 | 活跃会话已达 5 个 | `active session limit reached` |
| 4514 | 密码登录锁定 15 分钟 | `account is temporarily locked` |
| 4517 | 手机号已注册 | `phone is already registered` |
| 500 | Redis 或内部错误 | `Redis error: ...`、`internal error: ...` |
| 502 | 设备确认无效/拒绝，或短信供应商失败 | `collar did not confirm findPet started`、`SMS provider request failed: ...`（不含带手机号/验证码的 URL）、`SMS provider rejected the request (HTTP ..., Code=...)`、`invalid response from SMS provider` |
| 504 | 项圈未在 5 秒内确认寻宠已启动 | `collar did not confirm findPet within 5 seconds` |
| 503 | 功能未实现或未配置 | 见各操作 |

设计文档中的 `409`、`4513`、`4515`、`4516` 以及 `4520` 以后的域错误码，本服务还没有返回。

配对码错误和项圈不存在使用不同 code，文案相同，避免客户端只靠文案区分：

- 项圈未开通：`404`，`unknown collar or invalid pairing code`
- 项圈存在但配对码错误：`403`，`unknown collar or invalid pairing code`

## 6. 身份认证（auth）

手机号为 5–32 个字符，只允许数字、`+`、`-`。建议使用 E.164，例如 `+8613800138000`。

登录类操作共用的设备字段见 §4.3。下面的示例只写 `payload`；信封的 `v`、`reqId`、`ts`、`deviceId` 仍要按第 2 节带上。

### auth/sendSms

免 token。debug 构建可在未配置短信供应商时本地联调；若配置了供应商则会实际发送短信。release 构建必须配齐四个阿里云短信参数。

```json
{ "phone": "+8613800138000", "scope": "register" }
```

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `phone` | string | 接收验证码的手机号；5–32 个字符，只能包含数字、`+`、`-`。 |
| `scope` | string | 验证码用途，只能是 `register`（注册）或 `login`（登录）。 |

debug 成功：

```json
{ "smsCode": "042817", "expiresIn": 600 }
```

release 成功：

```json
{ "expiresIn": 600 }
```

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `smsCode` | string，可选 | 仅 debug 构建返回的 6 位短信验证码；release 不返回。 |
| `expiresIn` | integer | 验证码有效时长，单位秒，当前为 600。 |

| 条件 | code | msg |
| --- | --- | --- |
| `scope` 不是 `register` 或 `login` | 400 | `invalid SMS scope` |
| `scope=register` 且手机号已注册 | 4517 | `phone is already registered` |
| release 且短信配置缺失 | 503 | `SMS provider is not configured` |
| 阿里云调用失败或返回非 OK | 502 | 见 §5 |

### auth/register

免 token。校验 `register` 范围的短信验证码，创建用户并直接登录。

```json
{
  "phone": "+8613800138000",
  "sms_code": "042817",
  "password": "correct-horse",
  "device_name": "Wayne's phone",
  "device_model": "Phone 16",
  "platform": "ios",
  "os_ver": "18.0"
}
```

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `phone` | string | 注册账号手机号；5–32 个字符，只能包含数字、`+`、`-`。 |
| `sms_code` | string | 通过 `scope=register` 获取的 6 位验证码；成功使用后立即失效。 |
| `password` | string | 新账号登录密码，8–64 字节。 |
| `device_name` | string | 当前 APP 设备的显示名称，非空，最长 128 字节。 |
| `device_model` | string | 当前 APP 设备型号，非空，最长 128 字节。 |
| `platform` | string | APP 操作系统，取值 `ios`、`android` 或 `ohos`。 |
| `os_ver` | string | APP 操作系统版本，非空，最长 128 字节。 |

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `access` | string | 新签发的访问令牌。 |
| `accessExpireAt` | integer | 访问令牌过期时间，Unix 毫秒。 |
| `refresh` | string | 新签发的刷新令牌。 |
| `refreshExpireAt` | integer | 刷新令牌过期时间，Unix 毫秒。 |
| `sessionId` | string | 当前 APP 会话 ID。 |
| `user` | object | 用户资料对象。 |
| `user.userId` | string | 用户 ID。 |
| `user.phone` | string | 注册手机号。 |
| `isNewUser` | boolean | 是否由本次注册新建用户，固定为 `true`。 |
| `deviceId` | string | 当前登录设备 ID。 |
| `collarSettings` | array | 当前用户已绑定项圈的设置列表；无绑定项圈时为空数组。 |
| `collarSettings[].collarId` | string | 设置所属项圈 ID。 |
| `collarSettings[].buzzerOn` | boolean | 蜂鸣器开关状态。 |
| `collarSettings[].ledOn` | boolean | LED 开关状态。 |
| `collarSettings[].imuBatchIntervalSeconds` | integer | IMU 批量上报间隔，单位秒。 |
| `collarSettings[].gpsIntervalSeconds` | integer | GPS 上报间隔，单位秒。 |

手机号在校验短信之后、写入之前被并发注册时返回 `4517`。

### auth/loginByPassword

免 token。同一 `deviceId` 重复登录会轮换该设备 token。

```json
{
  "phone": "+8613800138000",
  "password": "correct-horse",
  "device_name": "Wayne's phone",
  "device_model": "Phone 16",
  "platform": "android",
  "os_ver": "14"
}
```

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `phone` | string | 已注册账号手机号。 |
| `password` | string | 账号密码，8–64 字节。 |
| `device_name` | string | 当前 APP 设备的显示名称，非空，最长 128 字节。 |
| `device_model` | string | 当前 APP 设备型号，非空，最长 128 字节。 |
| `platform` | string | APP 操作系统，取值 `ios`、`android` 或 `ohos`。 |
| `os_ver` | string | APP 操作系统版本，非空，最长 128 字节。 |

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `access` | string | 新签发的访问令牌。 |
| `accessExpireAt` | integer | 访问令牌过期时间，Unix 毫秒。 |
| `refresh` | string | 新签发的刷新令牌。 |
| `refreshExpireAt` | integer | 刷新令牌过期时间，Unix 毫秒。 |
| `sessionId` | string | 当前 APP 会话 ID。 |
| `user` | object | 用户资料对象。 |
| `user.userId` | string | 用户 ID。 |
| `user.phone` | string | 已注册手机号。 |
| `isNewUser` | boolean | 是否为新用户，固定为 `false`。 |
| `deviceId` | string | 当前登录设备 ID。 |
| `collarSettings` | array | 当前用户已绑定项圈的设置列表；无绑定项圈时为空数组。 |
| `collarSettings[].collarId` | string | 设置所属项圈 ID。 |
| `collarSettings[].buzzerOn` | boolean | 蜂鸣器开关状态。 |
| `collarSettings[].ledOn` | boolean | LED 开关状态。 |
| `collarSettings[].imuBatchIntervalSeconds` | integer | IMU 批量上报间隔，单位秒。 |
| `collarSettings[].gpsIntervalSeconds` | integer | GPS 上报间隔，单位秒。 |

密码错误为 `401`；锁定为 `4514`；新设备超过 5 个会话为 `4512`。

### auth/loginBySms

免 token。校验 `login` 范围的一次性验证码。手机号未注册返回 `401`，`msg` 为 `invalid credentials`，不自动注册。

```json
{
  "phone": "+8613800138000",
  "sms_code": "042817",
  "device_name": "Wayne's phone",
  "device_model": "Phone 16",
  "platform": "ohos",
  "os_ver": "5.0"
}
```

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `phone` | string | 已注册账号手机号。 |
| `sms_code` | string | 通过 `scope=login` 获取的 6 位一次性验证码。 |
| `device_name` | string | 当前 APP 设备的显示名称，非空，最长 128 字节。 |
| `device_model` | string | 当前 APP 设备型号，非空，最长 128 字节。 |
| `platform` | string | APP 操作系统，取值 `ios`、`android` 或 `ohos`。 |
| `os_ver` | string | APP 操作系统版本，非空，最长 128 字节。 |

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `access` | string | 新签发的访问令牌。 |
| `accessExpireAt` | integer | 访问令牌过期时间，Unix 毫秒。 |
| `refresh` | string | 新签发的刷新令牌。 |
| `refreshExpireAt` | integer | 刷新令牌过期时间，Unix 毫秒。 |
| `sessionId` | string | 当前 APP 会话 ID。 |
| `user` | object | 用户资料对象。 |
| `user.userId` | string | 用户 ID。 |
| `user.phone` | string | 已注册手机号。 |
| `isNewUser` | boolean | 是否为新用户，固定为 `false`。 |
| `deviceId` | string | 当前登录设备 ID。 |
| `collarSettings` | array | 当前用户已绑定项圈的设置列表；无绑定项圈时为空数组。 |
| `collarSettings[].collarId` | string | 设置所属项圈 ID。 |
| `collarSettings[].buzzerOn` | boolean | 蜂鸣器开关状态。 |
| `collarSettings[].ledOn` | boolean | LED 开关状态。 |
| `collarSettings[].imuBatchIntervalSeconds` | integer | IMU 批量上报间隔，单位秒。 |
| `collarSettings[].gpsIntervalSeconds` | integer | GPS 上报间隔，单位秒。 |

验证码错误、缺失或过期时返回 §4.5 中对应的短信错误码。

### auth/loginByOauth

免 token。当前不读取 `payload`；可以发送 `{}`。固定返回：

请求 `payload` 不含当前支持字段；OAuth 登录尚未实现，不能把任意字段当作已受支持的协议。

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| — | — | 当前没有支持的业务字段；调用时发送空对象 `{}`。 |

```json
{ "v": 2, "reqId": "...", "code": 503, "msg": "login provider is not configured", "data": null, "ts": 0 }
```

固定失败响应字段（该接口没有成功 `data`）：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `code` | integer | 固定为 `503`，表示 OAuth 登录提供方尚未配置/实现。 |
| `msg` | string | 固定为 `login provider is not configured`。 |
| `data` | null | 不返回业务数据。 |

### auth/resetPassword

免 token。当前不读取 `payload`；可以发送 `{}`。固定返回：

请求 `payload` 不含当前支持字段；密码重置尚未实现，不能把 `phone`、`sms_code` 或
`new_password` 等占位参数当作有效接口字段。

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| — | — | 当前没有支持的业务字段；调用时发送空对象 `{}`。 |

```json
{ "v": 2, "reqId": "...", "code": 503, "msg": "SMS provider is not configured", "data": null, "ts": 0 }
```

固定失败响应字段（该接口没有成功 `data`）：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `code` | integer | 固定为 `503`，表示密码重置接口尚未实现。 |
| `msg` | string | 固定为 `SMS provider is not configured`。 |
| `data` | null | 不返回业务数据。 |

### auth/bindPhone

免 token。当前不读取 `payload`；可以发送 `{}`。请求没有已支持的业务字段，手机号绑定尚未实现。
固定返回与 `auth/resetPassword` 相同的 `503` 响应。配好阿里云短信也不会启用这两个操作；
`sendSms` 不接受对应 scope。

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| — | — | 当前没有支持的业务字段；调用时发送空对象 `{}`。 |

固定失败响应字段（该接口没有成功 `data`）：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `code` | integer | 固定为 `503`，表示手机号绑定接口尚未实现。 |
| `msg` | string | 固定为 `SMS provider is not configured`。 |
| `data` | null | 不返回业务数据。 |

### auth/refresh

免 access token。`deviceId` 必须是签发该 refresh token 的那台设备。

```json
{ "refresh": "登录响应里的 refresh" }
```

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `refresh` | string | 当前设备最近一次登录或刷新得到的刷新令牌；每个 refresh 只能成功轮换一次。 |

成功返回新 token、过期时间和原 `sessionId`：

```json
{
  "access": "...",
  "accessExpireAt": 1699366920000,
  "refresh": "...",
  "refreshExpireAt": 1701957120000,
  "sessionId": "..."
}
```

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `access` | string | 轮换后新签发的访问令牌。 |
| `accessExpireAt` | integer | 新访问令牌过期时间，Unix 毫秒。 |
| `refresh` | string | 轮换后新签发的刷新令牌；必须替换本地旧值。 |
| `refreshExpireAt` | integer | 新刷新令牌过期时间，Unix 毫秒。 |
| `sessionId` | string | 原会话 ID；刷新不会改变会话 ID。 |

调用方必须丢弃旧 refresh。旧 refresh 再提交会触发重放保护并吊销该设备会话。

### auth/logout

需要 access token，且 `deviceId` 必须匹配。请求 `payload` 为 `{}`，没有业务字段；信封
中的 `token` 和 `deviceId` 标识需要注销的当前会话。

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| — | — | 无业务字段；发送空对象 `{}`，会话由信封中的 `token` 和 `deviceId` 确定。 |

成功：

```json
{ "loggedOut": true }
```

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `loggedOut` | boolean | 当前设备会话已注销，成功时固定为 `true`。 |

只吊销当前设备。之后该 access token 返回 `4403`。

## 7. 用户与设备（users）

`users` 域管理当前用户的 APP 登录设备和设备会话。

### users/listDevices

需要 access token，可以省略 `deviceId`。请求 `payload` 为 `{}`，没有业务字段；当前用户由
信封中的 access token 确定。响应中的 `data.sessions` 列出当前用户仍有效的 APP 设备会话，
包含设备信息、登录时间、会话时长和最后活跃时间（毫秒）。

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| — | — | 无业务字段；发送空对象 `{}`，当前用户由信封中的 access token 确定。 |

```json
{
  "sessions": [
    {
      "deviceId": "ios-3f2a",
      "deviceName": "Wayne's phone",
      "deviceModel": "Phone 16",
      "platform": "ios",
      "loginAt": 1699365120000,
      "sessionDurationMs": 880000,
      "lastActiveAt": 1699366000000,
      "current": true
    }
  ]
}
```

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `sessions` | array | 当前用户有效的 APP 设备会话列表；按 `lastActiveAt` 从新到旧排列。 |
| `sessions[].deviceId` | string | 会话所属设备 ID。 |
| `sessions[].deviceName` | string | 设备显示名称。 |
| `sessions[].deviceModel` | string | 设备型号。 |
| `sessions[].platform` | string | 操作系统平台。 |
| `sessions[].loginAt` | integer | 登录时间，Unix 毫秒。 |
| `sessions[].sessionDurationMs` | integer | 会话持续时间，单位毫秒。 |
| `sessions[].lastActiveAt` | integer | 最近活跃时间，Unix 毫秒。 |
| `sessions[].current` | boolean | 是否为信封 `deviceId` 对应的当前会话。 |

按 `lastActiveAt` 从新到旧排序。`current` 表示该条是否为本次 token 所属设备。已过期的会话记录会被从集合中清掉，不出现在列表里。

### users/listCollars

需要 access token，可以省略 `deviceId`。请求 `payload` 为 `{}`，没有业务字段；当前用户由
信封中的 access token 确定。返回当前用户绑定的项圈 ID，按字符串升序排列。

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| — | — | 无业务字段；发送空对象 `{}`，当前用户由信封中的 access token 确定。 |

```json
{ "collars": ["collar-001", "collar-002"] }
```

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collars` | array of string | 当前用户绑定的项圈 ID，按字符串升序排列。 |

### users/removeDevice

需要 access token，且信封 `deviceId` 必须是当前设备。用于剔除**另一台**设备。

```json
{ "device_id": "android-9c1b" }
```

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `device_id` | string | 要吊销的另一台 APP 设备 ID；不能是信封 `deviceId` 所代表的当前设备。 |

成功：

```json
{ "revoked": true, "deviceId": "android-9c1b" }
```

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `revoked` | boolean | 目标设备会话已吊销，成功时固定为 `true`。 |
| `deviceId` | string | 被移除设备的 ID。 |

| 条件 | code | msg |
| --- | --- | --- |
| `device_id` 等于当前设备 | 400 | `use logout to remove the current device` |
| `device_id` 字符非法 | 400 | `invalid device_id` |
| 该用户没有这台设备的会话 | 404 | `session not found` |

被剔除设备的下一次 access 或 refresh 返回 `4403`。本服务不通过 Zenoh 推送剔除事件。

## 8. 项圈（collars）

项目业务规则要求项圈 ID 跨 tenant 全局唯一且不可变，制造/资产系统应为每台物理项圈分配
UUID 或厂商序列号。服务端当前只校验 ID 格式，不分配 ID 或检查其全局唯一性；Redis 记录
和 topic 按 tenant 隔离，不代表 ID 冲突会被服务端拒绝。客户端应将 `(tenant, collar_id)`
作为完整资源键，并由开通流程保证 `collar_id` 不会在其他 tenant 或其他设备上复用。
同一 tenant 内对已存在的 `collar_id` 再次调用 `provisionCollar` 会覆盖该记录的配对码
和遥测身份而保留已有绑定，不会返回“ID 已占用”；不同 tenant 重用 ID 则会形成独立记录，
但同样违反全局 ID 业务规则。当前 provision API 没有跨 tenant 冲突检查、ID 转移或 ID
修改操作；开通成功不能证明该 ID 已全局唯一注册。

#### collarId 分配与设备注入

推荐由制造/资产系统为每台物理项圈分配一个标准 UUID（建议小写、带连字符的 UUIDv4）。
UUID 应由可信开通工具或资产系统使用安全随机数生成一次，再写入全局资产台账；不要在
固件每次启动、恢复出厂或重新刷机时重新生成。若沿用厂商序列号，应确认其在所有供应商和
tenant 范围内唯一，并固定规范化格式；当前服务按字面区分大小写，因此大小写不同会被当作
不同 ID。

分配和启用流程：

1. 在全局资产台账中以 `collar_id` 建立唯一约束，原子地登记/保留新 ID，并关联物理厂商
   序列号、型号/批次及状态。退役 ID 也保留记录，永不重新分配。
2. 将同一个 `collar_id` 写入项圈的受保护设备身份区，并生成包含该 ID 的二维码或标签。
   重新刷写固件不得改变此身份；资产台账、设备身份和开通请求必须逐字一致。
3. 由受信任的制造/部署客户端把登记过的 ID 传给 `collars/provisionCollar`。只有开通成功
   后才把台账状态标记为已开通；失败应保留原 ID 并重试/排查，不能另造 ID 绕过失败。
4. 设备绑定 tenant 是独立的部署归属信息，不改变 `collar_id`。迁移 tenant 时走受控迁移
   流程，不把同一个物理设备当成新项圈重新发号。

是否需要单独开发工具，取决于是否已有权威资产系统：已有 MES/ERP/CMDB 时，优先在其中实现
唯一分配并让开通流程读取它，无需再建一套发号服务。若没有，则至少需要一个唯一约束的资产
台账和一个受信任的轻量工具，用于生成 UUID、原子登记，并把输出交给标签打印及开通流程；
仅运行 `uuidgen` 或在本地脚本里随机生成 ID，无法证明该 ID 已登记、未被其他操作员使用
或未来不会复用。工具可以很小，不必做成独立在线服务；但多个操作员必须使用同一权威台账，
而不是各自维护副本。

本仓库提供一个**本地 SQLite 台账工具** `scripts/collar-id-ledger.py`，可为小规模试点
生成 UUIDv4、记录物理设备信息、拒绝重复 ID/厂商序列号，并记录每次状态变化的操作人和时间。
它不调用 `provisionCollar`，也不替代服务端全局冲突校验。默认数据库位于
`$XDG_DATA_HOME/pet-collar-service/collar-id-ledger.sqlite3`，未设置 `XDG_DATA_HOME` 时使用
`~/.local/share/pet-collar-service/collar-id-ledger.sqlite3`；使用 `--db` 可指定路径。

生成 UUID 并登记资产信息：

```sh
python3 scripts/collar-id-ledger.py --operator factory-user allocate \
  --manufacturer Acme --vendor-serial SN-1001 --model C1 --batch B2026 \
  --tenant tenant-a
```

输出 JSON 中的 `collar_id` 是发放给该物理项圈的 ID；默认生成 UUIDv4。若要直接使用厂商
序列号作为 ID，可用 `--collar-id` 显式指定，但该 ID 必须符合服务字符集且经全局台账确认
唯一。提供 `--vendor-serial` 时必须同时提供 `--manufacturer`，以便阻止同一厂商序列号重复登记。
`--operator` 默认为当前操作系统用户名。工具不会覆盖或重新分配已登记/已退役 ID，也没有
删除记录的命令。

查询和更新台账：

```sh
python3 scripts/collar-id-ledger.py list --status allocated
python3 scripts/collar-id-ledger.py show <collarId>
python3 scripts/collar-id-ledger.py history <collarId>
python3 scripts/collar-id-ledger.py --operator deploy-user mark-provisioned <collarId> \
  --notes "provisionCollar succeeded"
python3 scripts/collar-id-ledger.py --operator asset-admin retire <collarId>
```

`mark-provisioned` 应在 `collars/provisionCollar` 成功后执行；`retire` 是永久状态，不能重新
启用或复用 ID。`history` 可查看分配、开通、退役的操作人、时间和备注。数据库文件默认仅
当前操作系统用户可读写。这个 SQLite 版本适用于同一台可信工作站上的单一台账；不要让多个
操作员各持一份数据库副本，也不要把网络文件系统上的 SQLite 当作多机资产注册服务。多操作员/
多工厂部署应接入现有 MES/ERP/CMDB 或建设有唯一约束的中心台账。`scripts/test-apis.sh` 生成
的 UUID 仍仅用于测试。当前 `provisionCollar` 不做全局唯一性校验，台账与 API 的联动防冲突
仍需后续服务端实现。

#### 发现跨 tenant 重复 ID 时的处置

跨 tenant 重号不会让当前 Redis 记录自动合并或互相覆盖，因为存储和 topic 均有 tenant
命名空间；但会造成资产归属歧义，也违反全局 ID 规则。发现后按以下步骤处理，不要对其中
任一记录直接重复 provision：

1. 暂停为该 ID 开通新记录，并记录涉及的 tenant、物理项圈、厂商序列号、遥测 key ID、
   绑定用户和最近上报时间。确认是否是同一物理设备迁移 tenant，还是两台设备误用了同一 ID。
2. 查制造/资产发号台账，确定 ID 的唯一合法归属。若两台物理设备共用 ID，保留原始资产
   对应的 ID；为另一台设备分配从全局台账确认未使用的新 UUID/厂商序列号，并同步更新
   设备标识、开通凭据和相关用户绑定。新 ID 不是原记录的原地改名，旧 tenant 的记录和
   绑定不会自动迁移。
3. 若是同一设备迁移 tenant，先停止旧 tenant 的设备发布和控制，再进行有备份的人工数据/
   绑定迁移；确认旧归属已退役后，才在新 tenant 开通。当前服务没有跨 tenant transfer/
   deprovision API，不能仅在新 tenant 重复 provision 并假定旧记录已转移。
4. 按 tenant 分别核验 `users/listCollars`、`collars/listUsers`、系统信息和遥测 topic。
   迁移或纠正后用设备实际私钥对新 topic 发布新样本，并确认只有预期 tenant/APP 会话收到数据。

对后续开通，制造/资产系统应在全局注册表中原子分配不可重复的 `collar_id`。若要由服务端
保证不冲突，还需实现跨 tenant 的全局 ID 注册表，并让 `provisionCollar` 在原子操作中认领
ID：同 tenant 的合法凭据更新可按明确的轮换策略处理；已被其他 tenant 认领时必须拒绝，
且不能写入任一 tenant 的项圈记录。当前版本尚未实现该注册表或冲突错误码。

用户和项圈是多对多：一个用户可绑定多个项圈，一个项圈可被多个用户绑定。重复 bind 仍返回成功。

项圈列表接口归属 `users` 域，见 `users/listCollars`；目前仅返回 ID，没有名称、型号、固件或在线状态。

### collars/provisionCollar

开通使用的是管理服务的共享管理口令，不是项圈身份凭据，也不是用户 access token。请区分以下名称：

| 名称 | 保存/使用位置 | 用途 |
| --- | --- | --- |
| `COLLAR_PROVISIONING_TOKEN` | 管理服务的 CLI、环境变量或 YAML 配置 | 服务端期望的开通口令。优先级为 CLI > 环境变量 > YAML；未配置时开通接口返回 `503`。 |
| `provisioning_token` | `collars/provisionCollar` 请求的 `payload` 字段 | 调用方提交的口令。服务端将它与 `COLLAR_PROVISIONING_TOKEN` 做常量时间比较；不匹配返回 `403`。服务端不会把这个全局口令写入 Redis。 |
| `PROVISIONING_TOKEN` | `scripts/test-apis.sh` 等测试客户端的本地 shell 变量 | 只是测试脚本变量名，用来把同一口令填入 `payload.provisioning_token`。它不是服务端识别的环境变量，也不是项圈固件的配置项。 |

调用流程如下：

1. 在管理服务端通过 `COLLAR_PROVISIONING_TOKEN` 配置一个高熵口令。多副本管理服务必须配置相同值；更改该值后，仍使用旧值的客户端会立即收到 `403`。
2. 受信任的开通客户端把同一口令放入 `payload.provisioning_token`，再对精确 key `petpal/{tenant}/api/v1/collars/provisionCollar` 发起 Zenoh Query。这个接口不校验用户 access token，但请求信封仍须包含合法 `deviceId`、有效时间戳和其余必需字段。`deviceId` 不是身份认证，授权依据是开通口令以及部署侧 Router ACL。
3. 校验通过后，服务只把项圈 ID、配对码的 Argon2 哈希、遥测 `key_id` 和 Ed25519 公钥写入 Redis；不会保存或下发全局开通口令。后续 `collars/bind` 使用 `pairing_code`，遥测签名验证使用对应项圈私钥；两者都不是 `COLLAR_PROVISIONING_TOKEN`。

因此，真实项圈通常不应持有这个全局开通口令。应由受信任的管理端或制造/部署开通工具调用该接口；项圈只保存自己的遥测私钥和分配给它的 `key_id`。本仓库的 `collar-simulator` 也不读取 `PROVISIONING_TOKEN`。不要把全局口令写入固件、版本库或普通日志；远程调用应使用 TLS，并通过 Router ACL 限制可访问该开通 key 的客户端。

信封还必须带 `deviceId`，但它只需是合法标识符，不必等于 `collar_id`。请求示例：

```json
{
  "provisioning_token": "与服务配置相同的管理口令",
  "collar_id": "collar-001",
  "pairing_code": "pair-001-123456",
  "telemetry_key_id": "collar-key-7",
  "telemetry_public_key": "<64 hex characters>"
}
```

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `provisioning_token` | string | 管理端共享开通口令，必须与服务端配置一致；仅可信开通工具持有。 |
| `collar_id` | string | 资产系统分配的项圈唯一 ID；需符合设备标识符字符集。 |
| `pairing_code` | string | 此项圈专属的 APP 绑定码，1–256 字节；服务端只保存其 Argon2 哈希。 |
| `telemetry_key_id` | string | 此项圈 Ed25519 遥测公钥标识，必须与签名信封的 `auth.keyId` 一致。 |
| `telemetry_public_key` | string | 32 字节 Ed25519 公钥的 64 位十六进制编码；不包含私钥。 |

`pairing_code` 为 1–256 字节，服务只保存 Argon2 哈希。`telemetry_key_id` 是合法标识符；`telemetry_public_key` 必须是可解码的 32 字节 Ed25519 公钥的 hex 编码。再次开通同一 tenant 的 `collar_id` 会覆盖配对码和遥测公钥，已有用户绑定保留；服务不会检测 ID 冲突，调用前必须由开通系统保证 `collar_id` 跨 tenant 全局唯一且不可变。

成功：

```json
{ "collarId": "collar-001", "telemetryKeyId": "collar-key-7", "provisioned": true }
```

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collarId` | string | 已开通的项圈 ID。 |
| `telemetryKeyId` | string | 登记的 Ed25519 遥测公钥标识。 |
| `provisioned` | boolean | 开通成功标志，成功时固定为 `true`。 |

| 条件 | code | msg |
| --- | --- | --- |
| 服务未配置 provisioning token | 503 | `collar provisioning is disabled` |
| token 不匹配 | 403 | `invalid provisioning token` |
| 配对码为空或超过 256 字节 | 400 | `invalid pairing_code` |
| `collar_id` 非法 | 400 | `invalid collar_id` |

### collars/bind

需要 access token，且 `deviceId` 匹配。

```json
{ "collar_id": "collar-001", "pairing_code": "pair-001-123456" }
```

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collar_id` | string | 要绑定的已开通项圈 ID。 |
| `pairing_code` | string | 开通时为该项圈登记的配对码；服务端以哈希校验，不在响应中回传。 |

成功：`{ "collarId": "collar-001", "bound": true }`。

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collarId` | string | 已绑定的项圈 ID。 |
| `bound` | boolean | 绑定状态，成功时固定为 `true`。 |

### collars/unbind

需要 access token，且 `deviceId` 匹配。只删除当前用户的绑定，不影响其他用户。

```json
{ "collar_id": "collar-001" }
```

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collar_id` | string | 要从当前用户绑定列表中移除的项圈 ID。 |

成功：`{ "collarId": "collar-001", "bound": false }`。当前用户本来就没绑定该 ID 时返回 `404`，`msg` 为 `collar is not bound to this user`。

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collarId` | string | 已解绑的项圈 ID。 |
| `bound` | boolean | 解绑后的绑定状态，成功时固定为 `false`。 |

### collars/listUsers

需要 access token，可以省略 `deviceId`。只有已经绑定该项圈的用户可以查看。

```json
{ "collar_id": "collar-001" }
```

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collar_id` | string | 要查询绑定用户列表的项圈 ID；调用用户必须已绑定该项圈。 |

成功：

```json
{ "collarId": "collar-001", "users": ["user-id-a", "user-id-b"] }
```

用户 ID 按字符串升序。调用方未绑定该项圈时返回 `403`，`msg` 为 `collar is not bound to this user`。

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collarId` | string | 被查询的项圈 ID。 |
| `users` | array of string | 当前绑定该项圈的用户 ID，按字符串升序排列。 |

### collars/getSystemInfo

需要 access token，`deviceId` 可省略。请求 `{"collar_id":"collar-001"}`。
请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collar_id` | string | 要读取最新系统信息的项圈 ID；调用用户必须已绑定该项圈。 |

成功返回 `data.collarId` 及最近一次已验证的 `data.systemInfo`，格式见下方系统信息
topic。未绑定返回 `403`；尚无系统信息返回 `404`、`collar system info not available`。
数据保存在 Redis，只有后续有效的系统信息样本才覆盖。

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collarId` | string | 系统信息所属项圈 ID。 |
| `systemInfo` | object | 最近一次经签名验证并保存的系统信息包装对象。 |
| `systemInfo.reportedAt` | integer | 系统信息信封的上报时间，Unix 毫秒。 |
| `systemInfo.info` | object | 项圈上报的系统信息 payload。 |
| `systemInfo.info.seq` | integer | 系统信息流序号。 |
| `systemInfo.info.startupTime` | integer | 本次启动时间，Unix 毫秒。 |
| `systemInfo.info.uptimeSeconds` | integer | 启动后运行秒数。 |
| `systemInfo.info.flashBytes` | integer | Flash 容量，单位字节。 |
| `systemInfo.info.manufacturer` | string | 制造商名称。 |
| `systemInfo.info.batteryPercent` | integer | 电池电量百分比，0–100。 |
| `systemInfo.info.firmwareVersion` | string | 固件版本字符串。 |

### collars/setGeofence

任一当前绑定用户都可更新该项圈共享的围栏。APP 必须提供固定地图中心；`vertices`
是按顺时针或逆时针排列的凸多边形顶点，每点包含 `latitude`、`longitude`。顶点可省略
或设为空数组，表示没有自定义多边形，服务改用 APP 中心周围 2,000 米的默认圆形区域。
没有中心配置之前，GPS 不触发围栏判断。重复提交会更新边界并清除旧 inside/outside
状态，使下一个有效 GPS 样本重新判定。

```json
{
  "collar_id": "collar-001",
  "center": { "latitude": 39.9, "longitude": 116.4 },
  "vertices": [
    { "latitude": 39.89, "longitude": 116.39 },
    { "latitude": 39.89, "longitude": 116.41 },
    { "latitude": 39.91, "longitude": 116.41 },
    { "latitude": 39.91, "longitude": 116.39 }
  ]
}
```

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collar_id` | string | 要更新电子围栏的项圈 ID；调用用户必须已绑定该项圈。 |
| `center` | object | 固定围栏中心，包含数值字段 `latitude` 和 `longitude`；坐标分别限制在 -90–90、-180–180 度。 |
| `center.latitude` | number | 围栏中心纬度，单位度。 |
| `center.longitude` | number | 围栏中心经度，单位度。 |
| `vertices` | array of object，可选 | 多边形边界点列表；省略或空数组表示使用中心点周围的默认 2,000 米圆。 |
| `vertices[].latitude` | number | 多边形顶点纬度，单位度。 |
| `vertices[].longitude` | number | 多边形顶点经度，单位度。 |

多边形要求 3–64 个不同顶点，坐标须合法且按顺序形成凸集。成功响应会返回共享
`center`、`vertices`、`boundaryType`；默认圆还会返回 `radiusMeters: 2000`。未绑定返回
`403`；中心、顶点、非凸或退化多边形非法返回 `400`。

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collarId` | string | 围栏所属项圈 ID。 |
| `center` | object | 固定围栏中心坐标。 |
| `center.latitude` | number | 中心纬度，单位度。 |
| `center.longitude` | number | 中心经度，单位度。 |
| `vertices` | array of object | 多边形顶点；圆形围栏时为空数组。 |
| `vertices[].latitude` | number | 多边形顶点纬度，单位度。 |
| `vertices[].longitude` | number | 多边形顶点经度，单位度。 |
| `boundaryType` | string | 围栏形状，`circle` 或 `polygon`。 |
| `radiusMeters` | integer，可选 | 圆形围栏半径，单位米；默认圆形返回 `2000`，多边形不返回。 |

### 越界告警处理

服务只在收到有效的签名 GPS 且完成序号检查后计算围栏。若未配置 APP 固定中心，暂不
进行判断；APP 先调用 `collars/setGeofence` 写入中心，可省略 `vertices` 来使用默认
2 公里圆，也可同时设置凸多边形。

项圈从围栏内（或尚无判断状态）进入围栏外时，服务向所有在线、已绑定/获分享权限且
具有该项圈 GPS 流权限的 APP 会话发布一次 `geofence` 告警。后续越界位置不重复告警；
项圈回到边界内后重新布防。更新围栏会清除旧状态，下一个 GPS 样本重新判断。
告警是尽力而为的实时事件，不保存历史或在 APP 上线后补发。

APP 会话订阅：

```text
petpal/{tenant}/users/{userId}/sessions/{sessionId}/telemetry/{collarId}/geofence
```

完整告警信封见遥测协议部分。

### collars/findPet

已绑定用户（包括通过分享邀请绑定的用户）可触发项圈寻宠。服务会等待项圈确认
闪灯和蜂鸣器已经启动后才返回成功。`duration_seconds` 可省略（默认 30 秒），
必须是 5–120 的整数；设备离线或 5 秒内未确认返回 `504`，未绑定返回 `403`。

```json
{ "collar_id": "collar-001", "duration_seconds": 30 }
```

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collar_id` | string | 要启动寻宠的已绑定项圈 ID。 |
| `duration_seconds` | integer，可选 | 寻宠持续时间，单位秒；省略时为 30，允许范围 5–120。 |

成功响应：

```json
{
  "collarId": "collar-001",
  "commandId": "5b2b6f2d87d74c2ba5d14c9a2c2f0e2a",
  "status": "started",
  "durationSeconds": 30,
  "startedAt": 1731398400000
}
```

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collarId` | string | 执行寻宠的项圈 ID。 |
| `commandId` | string | 与设备控制命令对应的关联 ID。 |
| `status` | string | 命令状态；成功响应固定为 `started`。 |
| `durationSeconds` | integer | 设备确认的寻宠持续时间，单位秒。 |
| `startedAt` | integer | 设备确认启动时间，Unix 毫秒。 |

服务向项圈专属控制 queryable 发起 Zenoh Query，精确 key 为
`petpal/{tenant}/internal/collars/{collarId}/commands/findPet`。项圈必须为自身 key
声明 queryable。请求和设备回复格式如下：

```json
{
  "v": 1,
  "command": "findPet",
  "commandId": "<命令 ID>",
  "collarId": "collar-001",
  "durationSeconds": 30,
  "restoreBuzzerOn": false,
  "restoreLedOn": false
}
```

设备控制请求 payload 字段（服务发给项圈，不是 APP 请求 payload）：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `v` | integer | 设备命令协议版本，固定为 `1`。 |
| `command` | string | 命令名称，固定为 `findPet`。 |
| `commandId` | string | 本次控制命令 ID；设备回复必须原样回显。 |
| `collarId` | string | 接收命令的项圈 ID。 |
| `durationSeconds` | integer | 寻宠持续时间，单位秒。 |
| `restoreBuzzerOn` | boolean | 寻宠结束后恢复的蜂鸣器开关状态。 |
| `restoreLedOn` | boolean | 寻宠结束后恢复的 LED 开关状态。 |

设备须在实际启动闪灯和蜂鸣器后，以同一 key 回复 `status: "started"`、相同的
`commandId`、`collarId` 和 `durationSeconds`，并附正数 `startedAt` Unix 毫秒时间戳。
寻宠结束后必须恢复 `restoreBuzzerOn` 和 `restoreLedOn` 指定的状态；两项值来自发起用户
已保存的设置。
无法启动时回复 `status: "rejected"`；服务不会将拒绝回复当成成功。此命令 topic
必须由 Router ACL 限制为服务查询、对应项圈声明 queryable；APP 不得直接控制项圈。
仓库内的 `collar-simulator` 仅模拟并记录灯光/蜂鸣器动作，不驱动物理硬件。

项圈对 `findPet` 命令的应答 payload 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `v` | integer | 设备命令协议版本，固定为 `1`。 |
| `commandId` | string | 收到命令的关联 ID，必须原样回显。 |
| `collarId` | string | 应答项圈 ID，必须与命令一致。 |
| `status` | string | 启动成功时为 `started`；无法启动时可为 `rejected`，服务不会将其视为成功。 |
| `durationSeconds` | integer | 设备确认的寻宠持续时间，必须与命令一致。 |
| `startedAt` | integer | 实际启动时间，正数 Unix 毫秒；`status` 为 `started` 时必填。 |

### collars/getCollarSettings 与 collars/setCollarSettings

设置保存在 `(userId, collarId)` 维度。每次注册/登录成功响应都一次性返回当前用户所有
已绑定项圈的 `collarSettings` 数组，按 `collarId` 排序；无项圈时为空数组。每个用户的
设置互不覆盖。首次绑定的默认值为蜂鸣器关闭、LED 关闭、IMU 批量上传 1 秒、GPS 上报
1 秒。

#### `collars/getCollarSettings`

请求 `payload` 为：

```json
{ "collar_id": "collar-001" }
```

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collar_id` | string | 要读取设置的项圈 ID；返回当前用户对该项圈保存的设置。 |

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collarId` | string | 设置所属项圈 ID。 |
| `buzzerOn` | boolean | 蜂鸣器开关状态。 |
| `ledOn` | boolean | LED 开关状态。 |
| `imuBatchIntervalSeconds` | integer | IMU 批量上报间隔，单位秒。 |
| `gpsIntervalSeconds` | integer | GPS 上报间隔，单位秒。 |

#### `collars/setCollarSettings`

请求 `payload` 示例：

```json
{
  "collar_id": "collar-001",
  "buzzer_on": true,
  "led_on": false,
  "imu_batch_interval_seconds": 1,
  "gps_interval_seconds": 5
}
```

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collar_id` | string | 要修改设置的项圈 ID；调用用户必须已绑定该项圈。 |
| `buzzer_on` | boolean，可选 | 是否开启蜂鸣器；省略时保留该用户现有值。 |
| `led_on` | boolean，可选 | 是否开启 LED；省略时保留该用户现有值。 |
| `imu_batch_interval_seconds` | integer，可选 | IMU 数据累积后批量上报的间隔，单位秒，1–60；省略时保留现值。 |
| `gps_interval_seconds` | integer，可选 | GPS 上报间隔，单位秒，1–60；省略时保留现值。 |

`setCollarSettings` 可只提交部分字段，其余字段保持该用户对该项圈的当前设置；蜂鸣器和
LED 是设备当前输出的开/关状态，两个上报间隔范围为 1–60 秒。服务先持久化用户设置，
再向在线项圈发送完整配置。设备 5 秒内确认时返回 `status: "applied"`；未确认时返回
`status: "pending"`，但用户设置仍已保存。登录只把设置返回 APP，不会自动重写设备状态；
设备离线后，APP 可在设备在线时再次调用设置接口应用。共享项圈上，各用户设置独立保留，
设备的实际状态由最后一次成功应用的设置决定。

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collarId` | string | 设置所属项圈 ID。 |
| `buzzerOn` | boolean | 保存的蜂鸣器开关状态。 |
| `ledOn` | boolean | 保存的 LED 开关状态。 |
| `imuBatchIntervalSeconds` | integer | 保存的 IMU 批量上报间隔，单位秒。 |
| `gpsIntervalSeconds` | integer | 保存的 GPS 上报间隔，单位秒。 |
| `deviceSettingsVersion` | integer | 递增的设备设置版本号。 |
| `status` | string | `applied` 表示设备确认应用，`pending` 表示已保存但尚未确认。 |
| `syncError` | string，可选 | 设备同步未确认时的原因代码：`invalid_device_ack`、`device_rejected_or_unavailable`、`device_unavailable` 或 `device_offline_or_ack_timeout`；出现时设置仍已保存。 |

配置命令使用项圈专属 queryable：

```text
petpal/{tenant}/internal/collars/{collarId}/commands/setCollarSettings
```

命令的 `deviceSettingsVersion` 对设备单调递增，避免不同用户并发设置时旧命令覆盖新命令。
IMU/GPS 间隔与蜂鸣器、LED 状态统一通过 `getCollarSettings` 和 `setCollarSettings` 读取及更新。

设备设置控制请求 payload 字段（服务发给项圈）：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `v` | integer | 设备命令协议版本，固定为 `1`。 |
| `command` | string | 命令名称，固定为 `setCollarSettings`。 |
| `commandId` | string | 本次控制命令 ID；设备确认必须原样回显。 |
| `collarId` | string | 接收配置的项圈 ID。 |
| `deviceSettingsVersion` | integer | 单调递增的设备设置版本；设备不得应用低于本地版本的命令。 |
| `buzzerOn` / `ledOn` | boolean | 命令要求应用的蜂鸣器 / LED 状态。 |
| `imuBatchIntervalSeconds` | integer | 命令要求应用的 IMU 批量上报间隔，单位秒。 |
| `gpsIntervalSeconds` | integer | 命令要求应用的 GPS 上报间隔，单位秒。 |

项圈对 `setCollarSettings` 命令的应答 payload 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `v` | integer | 设备命令协议版本，固定为 `1`。 |
| `commandId` | string | 收到命令的关联 ID，必须原样回显。 |
| `collarId` | string | 应答项圈 ID，必须与命令一致。 |
| `status` | string | 应用成功时固定为 `applied`。 |
| `deviceSettingsVersion` | integer | 已应用设置版本，必须与命令版本一致。 |
| `buzzerOn` | boolean | 实际应用的蜂鸣器开关状态，必须与命令一致。 |
| `ledOn` | boolean | 实际应用的 LED 开关状态，必须与命令一致。 |
| `imuBatchIntervalSeconds` | integer | 实际应用的 IMU 批量上报间隔，必须与命令一致。 |
| `gpsIntervalSeconds` | integer | 实际应用的 GPS 上报间隔，必须与命令一致。 |

### collars/authorizeGpsPublisher / collars/authorizeImuPublisher

这是遥测 topic 的发布前检查 RPC，仅供可信设备网关调用，不校验用户 access token。必须通过 Zenoh ACL 限制调用者。网关应在声明对应 publisher 前调用；信封 `deviceId` 必须等于 `collar_id`。服务检查项圈已开通、已登记遥测身份且至少绑定一个用户。`deviceId` 一致性检查不替代 Zenoh ACL 或遥测签名验证。此 RPC 只返回授权结果，不返回任何用户设置。

```json
{ "collar_id": "collar-001" }
```

请求 `payload` 字段：

| 接口 | 字段 | JSON 类型 | 含义 |
| --- | --- | --- | --- |
| `collars/authorizeGpsPublisher` | `collar_id` | string | 要授权发布 GPS 的项圈 ID；请求信封 `deviceId` 必须与它一致。 |
| `collars/authorizeImuPublisher` | `collar_id` | string | 要授权发布 IMU 的项圈 ID；请求信封 `deviceId` 必须与它一致。 |

两个操作都成功响应：`{ "collarId": "collar-001", "authorized": true }`。

成功响应 `data` 字段（两个操作结构相同）：

| 接口 | 字段 | JSON 类型 | 含义 |
| --- | --- | --- | --- |
| `collars/authorizeGpsPublisher` | `collarId` | string | 已授权发布 GPS 的项圈 ID。 |
| `collars/authorizeGpsPublisher` | `authorized` | boolean | 是否授权；成功时固定为 `true`。 |
| `collars/authorizeImuPublisher` | `collarId` | string | 已授权发布 IMU 的项圈 ID。 |
| `collars/authorizeImuPublisher` | `authorized` | boolean | 是否授权；成功时固定为 `true`。 |

未知项圈返回 `404`；项圈缺少遥测身份、没有绑定用户或 `deviceId` 不匹配返回 `403`。
数据之后通过 topic 发布，不会对每个样本产生 RPC 响应。

### collars/reportGps 主题

`reportGps` 是 Zenoh pub/sub topic，不是 RPC。每个项圈使用独立 key：

```text
petpal/{tenant}/api/v1/collars/reportGps/{collarId}
```

可信网关先调用相应的 publisher 检查，再对该 key 声明 publisher 并发布 v2 信封。项圈 `collarId` 由 topic key 提供，不放在 payload 中；采样时间是信封顶层 `ts`，只要求为正的 Unix 毫秒时间戳，不受 RPC 的 ±120 秒窗口限制。GPS、IMU 和系统信息的 `payload.seq` 必须为正整数，并对该项圈、key ID、流单调递增。

```json
{
  "v": 2,
  "reqId": "gps-1731398400000",
  "ts": 1731398400000,
  "payload": {
    "latitude": 39.9,
    "longitude": 116.4,
    "altitude": 42.0,
    "seq": 42,
    "speed": 2.5,
    "heading": 180.0,
    "accuracy": 4.0
  },
  "auth": { "keyId": "collar-key-7", "signature": "<128 hex characters>" }
}
```

`reportGps` 的 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `seq` | integer | GPS 流正整数序号；同一项圈和 key ID 下必须严格递增。 |
| `latitude` | number | 纬度，单位度，范围 -90 至 90。 |
| `longitude` | number | 经度，单位度，范围 -180 至 180。 |
| `altitude` | number | 海拔，单位米。 |
| `speed` | number，可选 | 地面速度，单位米/秒，不能为负。 |
| `heading` | number，可选 | 航向角，单位度，范围 `[0, 360)`。 |
| `accuracy` | number，可选 | 水平定位精度，单位米，不能为负。 |

`latitude`、`longitude`、`altitude` 必填；`speed`、`heading`、`accuracy` 可选。纬度范围为 -90 至 90，经度为 -180 至 180；`altitude` 和 `accuracy` 单位为米，`speed` 为米/秒，速度与精度不能为负；航向范围为 `[0, 360)` 度。样本超出 16KB、信封或数值非法时服务会丢弃并记录错误；topic 发布本身没有 RPC 成功响应。

IMU 的 payload 必须包含 `seq`、`frame`（`body` 或 `world`）、`accelMps2` 和 `gyroRadS`；可选 `orientation` 为归一化 quaternion。加速度单位为 m/s²，角速度为 rad/s。样例：

```json
{
  "seq": 901,
  "frame": "body",
  "accelMps2": { "x": 0.1, "y": 0.0, "z": 9.8 },
  "gyroRadS": { "x": 0.01, "y": 0.02, "z": 0.0 },
  "orientation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 }
}
```

单帧 `reportImu` 的 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `seq` | integer | IMU 流正整数序号；同一项圈和 key ID 下必须严格递增。 |
| `frame` | string | 坐标参考系：`body` 为设备机身坐标，`world` 为世界坐标。 |
| `accelMps2` | object | 加速度向量，单位 m/s²；必须包含数值子字段 `x`、`y`、`z`。 |
| `accelMps2.x` / `.y` / `.z` | number | 加速度在对应坐标轴的分量。 |
| `gyroRadS` | object | 角速度向量，单位 rad/s；必须包含数值子字段 `x`、`y`、`z`。 |
| `gyroRadS.x` / `.y` / `.z` | number | 角速度在对应坐标轴的分量。 |
| `orientation` | object，可选 | 设备姿态的归一化四元数；包含 `x`、`y`、`z`、`w` 数值分量。 |
| `orientation.x` / `.y` / `.z` / `.w` | number | 姿态四元数分量。 |

服务端同时接受单帧 payload 和批量 payload。批量时 `payload.samples` 包含按 `seq`、`ts`
递增排列的帧；每帧包含自己的时间戳和 `imu` 数据，整个批次由一个信封签名：

```json
{
  "samples": [
    {
      "ts": 1731398400000,
      "imu": {
        "seq": 901,
        "frame": "body",
        "accelMps2": { "x": 0.1, "y": 0.0, "z": 9.8 },
        "gyroRadS": { "x": 0.01, "y": 0.02, "z": 0.0 }
      }
    },
    {
      "ts": 1731398400020,
      "imu": {
        "seq": 902,
        "frame": "body",
        "accelMps2": { "x": 0.2, "y": 0.0, "z": 9.7 },
        "gyroRadS": { "x": 0.02, "y": 0.01, "z": 0.0 }
      }
    }
  ]
}
```

批量 `reportImu` 的外层 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `samples` | array | 按采样时间递增排列的 IMU 帧；最多 8192 帧。 |
| `samples[].ts` | integer | 单帧采样时间，Unix 毫秒。 |
| `samples[].imu` | object | 单帧 IMU 数据，结构和字段含义同上方单帧 payload。 |

IMU 批次最大 2 MB、最多 8192 帧；服务验签后逐帧执行序号检查并送入行为处理器。
仓库模拟器默认每 20 毫秒采一帧、每 1 秒发布一个批次；实际 ESP32 可继续使用单帧
格式或按相同批次格式上报。IMU topic 为
`petpal/{tenant}/api/v1/collars/reportImu/{collarId}`。
系统信息 topic 为 `petpal/{tenant}/api/v1/collars/reportSystemInfo/{collarId}`，
使用相同签名信封，payload 为：

```json
{"seq":1,"startupTime":1731398300000,"uptimeSeconds":100,"flashBytes":4194304,"manufacturer":"Example vendor","batteryPercent":87,"firmwareVersion":"1.2.3"}
```

`reportSystemInfo` 的 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `seq` | integer | 系统信息流正整数序号；同一项圈和 key ID 下必须严格递增。 |
| `startupTime` | integer | 本次启动时间，Unix 毫秒；必须为正且不晚于信封 `ts`。 |
| `uptimeSeconds` | integer | 本次启动后的运行时长，单位秒，非负。 |
| `flashBytes` | integer | Flash 容量，单位字节，必须为正。 |
| `manufacturer` | string | 制造商名称，非空，最长 128 字节。 |
| `batteryPercent` | integer | 电池电量百分比，范围 0–100。 |
| `firmwareVersion` | string | 固件版本字符串，非空，最长 64 字节。 |

`startupTime` 是正的 Unix 毫秒且不得晚于信封 `ts`；`uptimeSeconds` 为非负整数，
`flashBytes` 为正整数（字节），`manufacturer` 为非空、最长 128 字节的字符串；
`batteryPercent` 为 0–100 的整数百分比，`firmwareVersion` 为非空、最长 64 字节的字符串。
系统信息仅需项圈已开通和有效签名，不要求已有用户绑定。持久化格式为
`{"reportedAt":<信封ts>,"info":<上述payload>}`，重放检查和保存原子执行。

遥测 `auth` 必填，使用项圈 provisioning 时登记的 key ID，并以该项圈 Ed25519 私钥签名。签名输入为 UTF-8 字节串
`petpal-telemetry-v1\n{tenant}\n{topicKey}\n{v}\n{reqId}\n{ts}\n{keyId}\n{canonicalPayloadJson}`；
payload JSON 由 serde_json 序列化，签名为 64 字节 hex 编码：

```json
"auth": { "keyId": "collar-key-7", "signature": "<128 hex characters>" }
```

遥测处理校验数据结构、登记的 key ID、公钥签名和单调序号后，
把 GPS 转发给在线 APP。系统信息保存最新值。原始 IMU 不下发给 APP。GPS 转发信封的
`ts` 仍在顶层：

```json
{
  "v": 2,
  "reqId": "gps-1731398400000",
  "ts": 1731398400000,
  "payload": {
    "collarId": "collar-001",
    "stream": "gps",
    "seq": 42,
    "data": { "latitude": 39.9, "longitude": 116.4, "altitude": 42.0, "seq": 42 }
  }
}
```

### collars/reportBehavior 主题与 IMU 行为识别链路（Zenoh pub/sub，不是 RPC）

项圈上传 IMU 的源 topic 为：

```text
petpal/{tenant}/api/v1/collars/reportImu/{collarId}
```

遥测服务验证项圈签名和 IMU 序号后，将样本转发到内部处理 topic：

```text
petpal/{tenant}/internal/collars/{collarId}/imu
```

`behavior-processor` 订阅内部 IMU topic，按项圈维护 100 帧滑动窗口，每次滑动 50 帧。
在默认 50 Hz 采样率下，每个识别窗口约 2 秒，约每秒产生一次结果。处理器依据加速度、
角速度及窗口内的运动特征计算行为类别；它不会从输入中直接复制一个行为标签。
当前原型计算去均值加速度 RMS、各轴/合成角速度 RMS、加速度幅值峰值与低谷、角速度
积分旋转量，以及基于样本时间戳估算的周期频率；静止姿势还参考 body 坐标系的重力主轴
和静止持续时间。规则阈值将这些特征映射到行为标签，无法判定时返回 `unknown`，并非
机器学习模型推理。
处理后将结果发布到上行结果 topic：

```text
petpal/{tenant}/api/v1/collars/reportBehavior/{collarId}
```

处理器到遥测服务的结果信封示例（该 topic 不是 RPC，不会返回 RPC 应答）：

```json
{
  "v": 2,
  "reqId": "imu-1731398400000",
  "ts": 1731398400000,
  "payload": {
    "collarId": "collar-001",
    "seq": 901,
    "behavior": "standing",
    "simulated": true
  }
}
```

`reportBehavior` 的 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collarId` | string | 生成该行为结果的项圈 ID；必须与 topic 中的项圈 ID 一致。 |
| `seq` | integer | 行为结果正整数序号；同一项圈的结果序号必须递增。 |
| `behavior` | string | 行为识别标签，取值为下文列出的英文枚举之一。 |
| `simulated` | boolean | 是否为模拟/原型识别结果；仓库当前处理器的输出为 `true`。 |

`behavior` 使用英文机器标签：`feeding`（进食）、`jumping`（跳跃）、`playing`（逗猫）、
`scratching`（磨爪）、`rolling`（打滚）、`running`（奔跑）、`licking_fur`（舔毛）、
`lying_down`（趴着）、`sleeping`（睡觉）、`standing`（站着）、`walking`（走路）、
`sitting`（坐着）和 `unknown`（未知）。

遥测服务订阅 `reportBehavior/*`，校验信封版本、请求 ID、时间戳、topic 与 `collarId`
一致性、正整数序号、非空 `behavior`（最长 128 字节）及布尔值 `simulated`；同一项圈的
行为序号必须递增。服务随后将结果分发到每个接收用户自己的 APP 会话 topic：

```text
petpal/{tenant}/users/{userId}/sessions/{sessionId}/telemetry/{collarId}/behavior
```

APP 收到的信封示例：

```json
{
  "v": 2,
  "reqId": "imu-1731398400000",
  "ts": 1731398400000,
  "payload": {
    "collarId": "collar-001",
    "stream": "behavior",
    "seq": 901,
    "data": {
      "collarId": "collar-001",
      "behavior": "standing",
      "simulated": true
    }
  }
}
```

APP 收到的行为结果 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collarId` | string | 产生该行为结果的项圈 ID。 |
| `stream` | string | 消息类型，固定为 `behavior`。 |
| `seq` | integer | 对应的行为结果序号。 |
| `data` | object | 行为结果数据对象，字段如下表。 |
| `data.collarId` | string | 产生该行为结果的项圈 ID。 |
| `data.behavior` | string | 行为识别英文标签。 |
| `data.simulated` | boolean | 是否为模拟/原型识别结果。 |

仅在线且已绑定/获分享该项圈、并拥有 `imu` 行为流权限的 APP 会话会收到结果；在线状态
由 `users/telemetryHeartbeat` 租约决定。未授权的租户用户不会收到广播。APP 订阅结果
topic，而不是发布结果。处理器未运行时，内部 IMU 使用尽力而为传递，不会缓存待处理
样本或在处理器恢复后补算。

仓库内的 `behavior-processor` 当前是独立运行的启发式原型：所有输出标记
`simulated: true`，不等同于训练验证后的生产模型。行为规则及模拟步骤见
[测试指南](./testing.md#7-遥测和安全边界验证)。

下行 GPS topic 为
`petpal/{tenant}/users/{userId}/sessions/{sessionId}/telemetry/{collarId}/gps`。
越界告警使用同一会话路径下的 `geofence` 流：

```text
petpal/{tenant}/users/{userId}/sessions/{sessionId}/telemetry/{collarId}/geofence
```

仅在 GPS 从围栏内（或尚无状态）进入围栏外时发布一次；回到边界内会重新布防。
告警复用 GPS `reqId`、时间戳和序号，且遵循 GPS 分享权限及在线租约。示例：

```json
{
  "v": 2,
  "reqId": "gps-1731398400000",
  "ts": 1731398400000,
  "payload": {
    "collarId": "collar-001",
    "stream": "geofence",
    "seq": 42,
    "data": {
      "alert": "outside_geofence",
      "position": { "latitude": 39.92, "longitude": 116.4 },
      "boundaryType": "circle",
      "center": { "latitude": 39.9, "longitude": 116.4 }
    }
  }
}
```

APP 收到的 GPS 与围栏消息 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collarId` | string | 产生遥测或告警的项圈 ID。 |
| `stream` | string | 消息类型：GPS 为 `gps`，越界告警为 `geofence`。 |
| `seq` | integer | 关联 GPS 样本的序号。 |
| `data` | object | GPS 位置或围栏告警数据；具体字段见下表。 |
| `data.latitude` / `data.longitude` | number | 纬度/经度，单位度。 |
| `data.altitude` | number | GPS 海拔，单位米。 |
| `data.speed` | number，可选 | 地面速度，单位米/秒。 |
| `data.heading` | number，可选 | 航向角，单位度。 |
| `data.accuracy` | number，可选 | 定位精度，单位米。 |
| `data.seq` | integer | GPS 样本序号；与 `payload.seq` 对应。 |
| `data.alert` | string | 围栏告警类型，当前为 `outside_geofence`。 |
| `data.position` | object | 触发越界的坐标对象，含纬度 `latitude` 和经度 `longitude`。 |
| `data.boundaryType` | string | 围栏形状：`circle` 或 `polygon`。 |
| `data.center` | object | 围栏中心坐标对象，含 `latitude` 和 `longitude`。 |

客户端须使用 `auth/issueZenohCredential` 返回的 session ID 和短期 mTLS 证书订阅自己的精确 topic。服务不保存遥测历史；流使用 `Priority::Data` 与 `CongestionControl::Drop`，不保证送达或补发。

行为识别相关 topic 必须通过 Router ACL 默认拒绝并按角色放行：仅遥测服务可发布内部
IMU topic，行为处理器可订阅；行为处理器可发布 `reportBehavior`，遥测服务可订阅；
APP 会话只能订阅自身授权的 `behavior` topic。独立行为处理器的启动命令和端到端
检查步骤见[测试指南](./testing.md#7-遥测和安全边界验证)。

## 9. Zenoh 会话凭据与在线租约

登录鉴权 RPC 与 GPS/IMU/围栏告警 topic 都使用 Zenoh；它们共用传输方式。服务的 `zenoh_router_endpoint` 根据 scheme 选择服务进程到 Router 的连接：`tcp/host:port` 为明文 TCP，`tls/host:port` 为 mTLS。APP/项圈客户端也必须连接 Router 上对应的 endpoint；此配置不会远程修改客户端或 Router。

服务进程连接使用 `tcp/` 时，相关 Zenoh 通信通过明文 TCP；使用 `tls/` 时，该服务进程到 Router 的链路使用 mTLS。管理服务可独立配置 APP 会话证书签发 CA，与其自身 Router 链路使用 TCP 或 TLS 无关。Router 的 TLS listener、受信任 CA 和 topic ACL 仍需单独配置。当前仓库没有项圈 X.509 证书签发流程；项圈使用 TLS endpoint 前，需要在设备侧提供 Router 信任的客户端证书；否则应让项圈连接 TCP endpoint。

Zenoh Router 可同时开放 TCP 与 mTLS endpoint，例如 JSON5 配置：

```json5
{
  listen: {
    endpoints: [
      "tcp/0.0.0.0:7447",
      "tls/0.0.0.0:7448",
    ],
  },
  transport: {
    link: {
      tls: {
        enable_mtls: true,
        root_ca_certificate: "/etc/zenoh/app-client-ca.crt",
        listen_certificate: "/etc/zenoh/router.crt",
        listen_private_key: "/etc/zenoh/router.key",
      },
    },
  },
}
```

Router 可以同时提供两种 listener，但各端要按所选模式配置：TCP 模式时服务、APP 和项圈使用 `tcp/router-host:7447`，API 与遥测都为明文；mTLS 模式时服务和已有证书的 APP 使用 `tls/router-host:7448`。Router 的 TLS listener 必须信任客户端证书签发 CA；客户端则应配置签发 Router 服务器证书的 CA。若要让项圈也使用 mTLS，必须先为项圈部署客户端证书签发和安装流程。若部署不允许明文 TCP，应移除 TCP listener。

默认统一服务使用一个 Router endpoint，管理 API 与遥测处理共用该 endpoint 和传输方式。
生产环境的 API 与遥测角色可使用各自的配置文件和 Router endpoint；API 副本之间仍应保持
配置一致。使用 TCP 明文时：

```yaml
zenoh_router_endpoint: "tcp/router-host:7447"
```

可通过同一二进制以角色启动服务；部署平台应为各副本注入相应配置和环境变量：

```sh
cargo run --release --bin pet_collar_service -- --role api --config ./service.yaml
cargo run --release --bin pet_collar_service -- --role telemetry --config ./service.yaml
```

扩 API 时增加 `--role api` 副本即可；遥测仍只启动一个实例。当前遥测是 Zenoh Pub/Sub
订阅者，不支持直接水平扩容。统一服务可以多副本部署，遥测由租约保证单活。

使用统一服务且启用 mTLS 时，该进程证书身份必须同时具有管理 API 和遥测 topic 所需的
Router ACL 权限。使用分离角色时，可为 API 和遥测配置独立客户端证书及 ACL；所有 API
副本的 ACL 和证书签发 CA 应一致。管理 API 若还要签发 APP 客户端证书，另配置 APP 签发 CA：

```yaml
zenoh_router_endpoint: "tls/router-host:7448"
zenoh_router_root_ca_cert_path: "/etc/pet-collar/ca/router-ca.crt"
zenoh_router_client_cert_path: "/etc/pet-collar/certs/service-client.crt"
zenoh_router_client_key_path: "/etc/pet-collar/certs/service-client.key"
zenoh_client_ca_cert_path: "/etc/pet-collar/ca/app-client-ca.crt"
zenoh_client_ca_key_path: "/etc/pet-collar/ca/app-client-ca.key"
```

### auth/issueZenohCredential

需要有效 access token 和匹配的 `deviceId`。客户端在本地生成私钥及其 CSR，并提交 `csr_pem`；服务器使用配置的 CA 签发 300 秒有效的 client-auth 证书。私钥不会发送给服务器。配置 `ZENOH_CLIENT_CA_CERT_PATH` 和 `ZENOH_CLIENT_CA_KEY_PATH`（或 YAML/CLI 对应项）后可用，与管理进程连接 Router 使用 `tcp/` 还是 `tls/` 无关；未配置时返回 `503`。

请求 `payload`：

```json
{ "csr_pem": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----\n" }
```

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `csr_pem` | string | APP 本地生成的 PEM PKCS#10 证书签名请求；包含客户端公钥，最大 8 KB。对应私钥不得上传。 |

成功 `data`：

```json
{
  "sessionId": "...",
  "certificatePem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
  "expiresAt": 1699365420000,
  "topicPrefix": "petpal/demo/users/<userId>/sessions/<sessionId>/telemetry/"
}
```

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `sessionId` | string | 当前 APP 会话 ID。 |
| `certificatePem` | string | 由服务端 CA 签发的短期客户端证书 PEM；私钥仍由 APP 保管。 |
| `expiresAt` | integer | 证书到期时间，Unix 毫秒。 |
| `topicPrefix` | string | 与该会话证书关联的遥测订阅 topic 前缀。 |

`expiresAt` 是 Unix 毫秒时间戳；客户端应在证书到期前重新申请证书。部署 Router 时必须信任此 CA，并根据证书 `O=tenant`、`OU=userId`、`CN=sessionId` 强制精确 topic ACL；服务端签发证书本身不会配置或强制 Router ACL。

#### APP 客户端生成并使用证书

Zenoh 不会替 APP 生成客户端证书。流程是：APP 在本机生成私钥和 CSR，将 CSR 通过 `auth/issueZenohCredential` 发给服务端；服务端只签 CSR 中的公钥，返回短期客户端证书。私钥始终保留在 APP 本机。

1. **服务端配置签发 CA。** 服务需要一对 CA 证书和匹配的私钥：

   ```yaml
   zenoh_client_ca_cert_path: "/etc/pet-collar/ca/client-ca.crt"
   zenoh_client_ca_key_path: "/etc/pet-collar/ca/client-ca.key"
   ```

   两项必须同时设置；缺少时证书签发接口不可用。CA 私钥必须妥善保护，不要放进客户端、仓库或普通日志。

2. **APP 本地生成密钥和 CSR。** 例如使用 OpenSSL 创建 RSA 私钥和 PEM 格式 CSR：

   ```sh
   umask 077
   openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out app-session.key
   openssl req -new -key app-session.key -out app-session.csr -subj "/CN=app-session"
   ```

   `app-session.key` 是秘密，只留在此客户端；不要上传。CSR 可提交给服务端，最大 8 KB。移动端也可以使用平台密钥库生成密钥/CSR，只要提交 PEM 编码的 PKCS#10 CSR。

3. **用当前登录会话申请证书。** 请求必须带有效的 `token`、匹配的 `deviceId`，并把 CSR 文件内容作为 `payload.csr_pem` 字符串。以下命令使用 `jq` 保留 CSR 中的换行并生成 v2 信封：

   ```sh
   TS="$(date +%s%3N)"
   REQ_ID="cert-${TS}"
   REQUEST="$(jq -cn \
     --arg token "$ACCESS_TOKEN" \
     --arg deviceId "$DEVICE_ID" \
     --arg reqId "$REQ_ID" \
     --arg csr_pem "$(cat app-session.csr)" \
     --argjson ts "$TS" \
     '{v:2,reqId:$reqId,token:$token,deviceId:$deviceId,ts:$ts,payload:{csr_pem:$csr_pem}}')"

   z_get \
     --connect tcp/127.0.0.1:7447 \
     --selector 'petpal/demo/api/v1/auth/issueZenohCredential' \
     --payload "$REQUEST" \
     --timeout 10000
   ```

   将成功响应 `data.certificatePem` 解码为 PEM 并保存为 `app-session.crt`；同时保存 `sessionId`、`expiresAt` 和 `topicPrefix`。证书有效期为 300 秒。证书主体由服务端设置为 `O=<tenant>`、`OU=<userId>`、`CN=<sessionId>`，CSR 自带的主体不会决定这些身份字段。

4. **把证书和原私钥配置给 Zenoh 客户端。** Zenoh 1.10 的 JSON5 配置示例：

   ```json5
   {
     connect: {
       endpoints: ["tls/router.example:7447"],
     },
     transport: {
       link: {
         tls: {
           enable_mtls: true,
           root_ca_certificate: "/etc/pet-app/router-ca.crt",
           connect_certificate: "/secure/app-session.crt",
           connect_private_key: "/secure/app-session.key",
         },
       },
     },
   }
   ```

   `root_ca_certificate` 是**客户端用来验证 Router 服务器证书**的 CA；`connect_certificate` 和 `connect_private_key` 是本次会话的客户端证书和第 2 步生成的私钥。Router 也必须启用 TLS/mTLS，并将签发 APP 证书的 CA 配置为其客户端信任根；服务不会替 Router 配置 TLS、CA 信任或 ACL。不要关闭服务器名称验证。

5. **按证书身份订阅会话 topic。** 使用响应里的 `sessionId` 和 `topicPrefix` 构造该会话获准的精确 topic；心跳续期在线租约。证书到期前重新生成 CSR 并再次申请证书，然后用新证书建立/更新 Zenoh 连接。

此流程用于 APP 会话的 mTLS。项圈上报 GPS/IMU 使用独立的项圈 Ed25519 遥测签名密钥，不要将 APP 客户端证书当作项圈遥测签名密钥。

### users/telemetryHeartbeat

需要有效 access token 和匹配的 `deviceId`。续期当前 APP 会话的 60 秒在线租约；客户端至少每 60 秒调用一次。无在线租约的会话不会收到遥测样本。注销或移除设备时，服务会清理该租约。

请求 `payload` 为 `{}`，没有业务字段；信封中的 `token` 与 `deviceId` 指定要续租的 APP 会话。

请求 `payload` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| — | — | 无业务字段；发送空对象 `{}`，由信封中的 `token` 和 `deviceId` 指定会话。 |

成功 `data`：

```json
{ "sessionId": "...", "onlineUntil": 1699365180000 }
```

成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `sessionId` | string | 被续租的 APP 会话 ID。 |
| `onlineUntil` | integer | 在线租约截止时间，Unix 毫秒。 |

`onlineUntil` 是租约过期时刻的 Unix 毫秒时间戳。

### collars/createShareInvite / collars/acceptShareInvite

已绑定项圈的用户可创建分享邀请；`streams` 可省略（默认 `gps` 和 `imu`），或提供非空的 `["gps"]`、`["imu"]`、`["gps","imu"]`。`imu` 权限控制行为结果的接收，不再发送原始 IMU。邀请 900 秒有效且只能接受一次。被邀请用户以 `invite_token` 接受后，仅获授被选中的流权限。

创建邀请请求 `payload`：

```json
{ "collar_id": "collar-001", "streams": ["gps", "imu"] }
```

创建请求字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collar_id` | string | 要分享的项圈 ID；邀请创建者必须已绑定该项圈。 |
| `streams` | array of string，可选 | 授权的数据流；可包含 `gps`、`imu`，省略时默认二者都授权；空数组或未知值返回 `400`。`imu` 控制行为结果权限，不会向 APP 发送原始 IMU。 |

`streams` 可省略；省略时授权 `gps` 和 `imu`。成功 `data`：

```json
{ "inviteToken": "...", "expiresIn": 900 }
```

创建邀请成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `inviteToken` | string | 一次性分享邀请令牌；被邀请用户用它接受邀请。 |
| `expiresIn` | integer | 邀请有效时长，单位秒，当前为 900。 |

接受邀请请求 `payload`：

```json
{ "invite_token": "上一步返回的 inviteToken" }
```

接受请求字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `invite_token` | string | 邀请创建时返回的一次性 token；须由另一用户在 900 秒有效期内使用。 |

成功 `data`：

```json
{ "collarId": "collar-001", "bound": true, "streams": ["gps", "imu"] }
```

接受邀请成功响应 `data` 字段：

| 字段 | JSON 类型 | 含义 |
| --- | --- | --- |
| `collarId` | string | 获得分享权限的项圈 ID。 |
| `bound` | boolean | 是否已建立共享绑定，成功时固定为 `true`。 |
| `streams` | array of string | 实际授予的遥测权限，元素为 `gps` 和/或 `imu`。 |

## 10. 客户端处理约定

- 以 `code` 分支，不要把超时或无 queryable 当成空列表。Zenoh 在超时内没有 reply 时，客户端应显示链路或服务不可用。
- `401` 可以用 refresh token 换新 access 后重试一次原请求。`auth/refresh` 自己返回 `401` 或 `4403` 时不要再刷新。
- `4403` 表示当前设备会话已经结束，应清除本地 token 并回到登录。
- `4512` 应展示 `data.sessions`，让用户先在已登录设备上调用 `users/removeDevice`，再重试登录。
- 写操作没有服务端 `reqId` 幂等。自动重试可能重复登录、重复开通或重复绑定。绑定和开通本身可以安全重复；注册和刷新不行。
- debug 服务返回的 `smsCode` 只用于开发。release 响应和日志都不应记录验证码、密码、token 或 provisioning token。

## 11. 架构与安全

本文件只维护 API wire contract。多对多绑定、会话级 telemetry topic、
证书生命周期和 Router ACL 边界见
[architecture.md](./architecture.md)；不要以历史设计稿替代当前接口说明。
