# APP 接口与业务开发指南

本文面向 iOS/Android/鸿蒙 APP 开发，完整说明登录会话、项圈绑定、系统信息、电子围栏、
一键寻宠、分享、实时订阅和测试流程。字段类型与服务端完整校验以
[Zenoh RPC API](./zenoh-rpc-api.md) 为准；新项圈制造开通及 ESP32 上报/控制协议见
[ESP32 开发指南](./esp32-development.md)，环境安装和服务启动见[测试指南](./testing.md)。

服务通过 Zenoh Query/Reply 和 Pub/Sub 对外提供接口，**没有 HTTP REST API**。RPC 响应中
`code` 是业务码，不是 HTTP 状态码。当前仓库不包含移动 APP 实现。

## 1. APP 能力与调用边界

APP 通过 access token 调用用户和项圈管理 RPC，并使用短期会话证书订阅自己的实时 topic。
项圈遥测由 ESP32 发布；行为结果由服务器行为处理器生成。APP 不直接发布 GPS/IMU、
不订阅原始 IMU，也不直接向项圈控制 key 发送寻宠命令。

| 业务 | APP 入口 | 结果 |
| --- | --- | --- |
| 用户登录和设备会话 | `auth/*`、`users/*` | 访问 token、刷新 token、会话及在线租约 |
| 项圈绑定管理 | `users/listCollars`、`collars/bind`、`unbind`、`listUsers` | 当前 APP 用户与项圈的绑定关系 |
| 系统信息 | `collars/getSystemInfo` | 最近一次通过项圈签名和序号验证的系统信息 |
| 实时定位与围栏 | `collars/setGeofence`，订阅 `gps` / `geofence` | GPS 数据和越界告警 |
| 一键寻宠 | `collars/findPet` | 等待设备确认 LED 和蜂鸣器动作 |
| 分享 | `collars/createShareInvite`、`acceptShareInvite` | 按 GPS/行为流权限与另一用户共享 |
| 行为识别 | 订阅 `behavior` | 接收服务端处理 IMU 后产生的英文行为标签 |

`collars/provisionCollar` 是管理端/制造开通接口，不属于一般 APP 操作。全局
`COLLAR_PROVISIONING_TOKEN` 不得放入 APP 或 ESP32；APP 首次绑定只使用该项圈的
`pairing_code`。

项目业务规则要求 `collar_id` 跨 tenant 全局唯一且不可变，应由制造/资产系统分配 UUID
或厂商序列号。服务端当前只按 tenant 隔离存储和 topic，未强制全局唯一；不同 tenant
使用相同 ID 会形成独立记录，但仍违反业务规则。APP 应将 `(tenant, collar_id)` 一起用于
本地缓存、路由和埋点，同时不能把 tenant 隔离误认为系统已经验证过 ID 全局唯一。

## 2. 通用 RPC 调用约定

### 2.1 Key、请求和响应

客户端对精确 key 执行 Zenoh `get`：

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

完整请求 envelope：

```json
{
  "v": 2,
  "reqId": "app-1731398400000",
  "token": "<需要鉴权的 access token>",
  "deviceId": "ios-device-001",
  "ts": 1731398400000,
  "payload": {}
}
```

| 字段 | 约定 |
| --- | --- |
| `v` | 固定数字 `2` |
| `reqId` | 非空 ASCII 前缀、连字符和 13 位 Unix 毫秒时间戳；服务验证格式但不提供幂等保证 |
| `token` | 需登录的 RPC 使用 access token；注册/登录/发短信/refresh 不使用 access token |
| `deviceId` | 1–128 个 ASCII 字母、数字或 `-_.:`；受设备会话保护的请求必须匹配 token 的设备 |
| `ts` | Unix 毫秒；与服务端时间相差不得超过 120 秒 |
| `payload` | JSON object；字段名为 snake_case，嵌套深度和请求大小受限 |

`users/listDevices`、`users/listCollars`、`collars/listUsers`、`collars/getSystemInfo`、
`collars/getCollarSettings`
允许省略 `deviceId`；其余 APP RPC 必须提供。精确规则和请求限制见
[请求信封规范](./zenoh-rpc-api.md#2-请求信封)。

通用成功响应：

```json
{
  "v": 2,
  "reqId": "app-1731398400000",
  "code": 0,
  "msg": "ok",
  "data": {},
  "ts": 1731398400123
}
```

| 响应字段 | 中文解释 |
| --- | --- |
| `v` | 响应协议版本，固定为 `2` |
| `reqId` | 对应请求的关联 ID |
| `code` | 业务结果码，`0` 表示成功 |
| `msg` | 面向开发者的结果说明；APP 不应直接展示给用户 |
| `data` | 操作的成功结果；失败时通常为 `null` |
| `ts` | 服务端生成响应的 Unix 毫秒时间 |

失败时 `data` 通常为 `null`。APP 应根据 `code` 做本地化，不要将英文 `msg` 直接作为用户
提示。没有 reply 或超时属于链路/服务故障，不要转换为空列表或成功状态。RPC 精确 key
和响应格式示例：

```sh
z_get --connect tcp/127.0.0.1:7447 \
  --selector 'petpal/demo/api/v1/users/listCollars' \
  --payload '{"v":2,"reqId":"app-1731398400000","token":"<access>","ts":1731398400000,"payload":{}}' \
  --timeout 10000
```

建议 Query 超时为 10 秒。不要在 selector 中使用通配符，也不要将写操作发往 `All`
query target。

### 2.2 登录、设备和会话

登录/注册 payload 的设备字段统一为 `device_name`、`device_model`、`platform`、
`os_ver`。`platform` 为 `ios`、`android` 或 `ohos`。手机号建议 E.164 格式，密码为
8–64 字节；完整长度和字符约束见 [auth API](./zenoh-rpc-api.md#6-身份认证-auth)。

成功登录响应 `data`：

```json
{
  "access": "<access token>",
  "accessExpireAt": 1731400200000,
  "refresh": "<refresh token>",
  "refreshExpireAt": 1733990400000,
  "sessionId": "<APP 会话ID>",
  "user": { "userId": "<用户ID>", "phone": "<手机号>" },
  "isNewUser": false,
  "deviceId": "ios-device-001",
  "collarSettings": [
    {
      "collarId": "collar-001",
      "buzzerOn": false,
      "ledOn": false,
      "imuBatchIntervalSeconds": 1,
      "gpsIntervalSeconds": 5
    }
  ]
}
```

`collarSettings` 是当前用户全部已绑定项圈的设置，按 `collarId` 排序；无绑定项圈时为空数组。
APP 应在登录成功时保存并展示这份数据，不要仅凭登录响应把配置写入设备。

access token 约 30 分钟，refresh token 约 30 天。刷新成功后必须保存新 refresh token 并
丢弃旧 token；重放已用 refresh token 会吊销该设备的会话。access token 绑定一个
`deviceId`，不得在其他设备复用。

## 3. APP 身份与用户 API

### 3.1 `auth` 域

| 操作 | 鉴权 | 请求 `payload` | 成功结果 / 说明 |
| --- | --- | --- | --- |
| `auth/sendSms` | 无 access token；需 `deviceId` | `{"phone":"<手机号>","scope":"register"}` 或 `scope="login"` | debug 成功返回 `smsCode`、`expiresIn=600`；release 发送成功后只返回 `expiresIn` |
| `auth/register` | 无 access token | `phone`、`sms_code`、`password`、设备字段 | 创建用户并登录，`isNewUser=true` |
| `auth/loginByPassword` | 无 access token | `phone`、`password`、设备字段 | 密码登录，`isNewUser=false` |
| `auth/loginBySms` | 无 access token | `phone`、`sms_code`、设备字段 | 短信登录，不会自动注册 |
| `auth/refresh` | 不使用 access token；`deviceId` 要匹配 refresh | `{"refresh":"<refresh token>"}` | access/refresh 轮换，`sessionId` 保持 |
| `auth/logout` | access token，当前 `deviceId` | `{}` | `{"loggedOut":true}`，只吊销当前设备 |
| `auth/issueZenohCredential` | access token，当前 `deviceId` | `{"csr_pem":"<PEM CSR>"}` | 签发 300 秒有效客户端证书和会话 topic 信息 |
| `auth/loginByOauth` | 无 access token | `{}` | 当前固定返回 `503`，provider 未配置 |
| `auth/resetPassword` | 无 access token | `{}` | 当前固定返回 `503`，短信供应商未配置 |
| `auth/bindPhone` | 无 access token | `{}` | 当前固定返回 `503`，短信供应商未配置 |

Debug 服务在未配置短信供应商时可本地返回验证码；配置了完整阿里云短信参数时会真实
发短信，服务终端也会打印 debug 验证码。Release 必须发送真实短信，响应和日志不泄露
验证码。错误密码、验证码错误、过期或已使用验证码、登录设备上限等错误码见 API 契约。

Debug 构建会把每个 API 请求和应答写入同一个日志文件，格式为
`[timestamp][<--/-->][API key][payload]`：`<--` 表示收到请求，`-->` 表示服务应答；
最后一段是紧凑的请求/应答 envelope JSON，外层日志不是 JSON。默认文件为服务当前目录下的
`logs/pet_collar_service_<UTC启动时间>.log`；每次 API 服务启动都会在 `logs/` 下新建文件，
并自动创建该目录。单个文件达到 1 MB 后，后续日志切换到
`logs/pet_collar_service_<同一启动时间>_1.log`、`_2.log` 等文件，轮转文件沿用启动时间戳。
Unix 上文件权限限制为 `0600`。
默认会将 access/refresh token、密码、验证码、手机号、配对码、开通口令、邀请令牌、
CSR 和证书等值替换为 `[REDACTED]`。仅在受控的本地排错环境中，启动 debug 服务前设置
`SHOW_SENSITIVE=1`，才会把这些敏感值也写入日志；例如：

```sh
SHOW_SENSITIVE=1 cargo run
```

Release 构建不会生成此 API 请求/应答日志。Debug 短信验证码仍会单独输出到服务终端；
包含真实凭据或验证码的日志不得提交、上传或分享。

### 3.2 `users` 域

这些接口都需要 access token：

| 操作 | `deviceId` | 请求 `payload` | 成功 `data` / 用途 |
| --- | --- | --- | --- |
| `users/listDevices` | 可省略 | `{}` | `{"sessions":[...]}`，当前用户设备会话 |
| `users/listCollars` | 可省略 | `{}` | `{"collars":["collar-001"]}`，按 ID 排序 |
| `users/removeDevice` | 必须是当前设备 | `{"device_id":"<另一台设备ID>"}` | `{"revoked":true,"deviceId":"..."}` |
| `users/telemetryHeartbeat` | 必须是当前设备 | `{}` | `{"sessionId":"...","onlineUntil":<Unix毫秒>}` |

`users/listDevices` 中每个 session 含 `deviceId`、设备名称/型号、平台、登录时间、
会话时长、最后活跃时间及 `current` 标记；按最后活跃时间从新到旧排列。
`removeDevice` 只能移除另一台设备；移除自身返回 `400`，不存在设备返回 `404`，被移除
设备的 token 后续返回 `4403`。APP 应至少每 60 秒调用一次 `telemetryHeartbeat`；
在线租约决定该 APP 会话是否收到实时数据。

## 4. 项圈管理和业务 API

所有以下 APP 操作都使用 `petpal/{tenant}/api/v1/{domain}/{operation}`。除
`users/listCollars` 之外，表中的 collars 请求都需要 `collar_id`。完整响应 envelope
仍遵循第 2 节。

| 操作 | 鉴权 / 前提 | 请求 `payload` | 成功 `data` |
| --- | --- | --- | --- |
| `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":["<userId>"]}` |
| `collars/getSystemInfo` | access token；已绑定；`deviceId` 可省略 | `{"collar_id":"..."}` | `{"collarId":"...","systemInfo":{"reportedAt":0,"info":{...}}}` |
| `collars/getCollarSettings` | access token；已绑定；`deviceId` 可省略 | `{"collar_id":"..."}` | 蜂鸣器、LED、IMU/GPS 间隔 |
| `collars/setCollarSettings` | access token；已绑定；当前设备 `deviceId` | `collar_id`，以及一个或多个设置字段 | 返回完整的用户设置、`deviceSettingsVersion`；`status` 为 `applied` 或 `pending` |
| `collars/setGeofence` | access token；已绑定；当前设备 `deviceId` | `collar_id`、数字类型 `center`、可选 `vertices` | 返回中心、顶点、`boundaryType`；圆形另有 `radiusMeters=2000` |
| `collars/findPet` | access token；已绑定；当前设备 `deviceId` | `{"collar_id":"...","duration_seconds":30}` | `collarId`、`commandId`、`status="started"`、时长和 `startedAt` |
| `collars/createShareInvite` | access token；已绑定；当前设备 `deviceId` | `{"collar_id":"...","streams":["gps","imu"]}` | `{"inviteToken":"...","expiresIn":900}` |
| `collars/acceptShareInvite` | 另一用户 access token；当前设备 `deviceId` | `{"invite_token":"..."}` | `{"collarId":"...","bound":true,"streams":["gps","imu"]}` |

### 4.1 绑定关系和系统信息

新项圈须先由管理端 `collars/provisionCollar` 开通，再由 APP 用户提交配对码调用
`collars/bind`。成功后用 `users/listCollars` 核对项圈列表。用户与项圈是多对多关系；
重复绑定仍成功，解绑只移除当前用户的绑定，不会删除其他用户的权限。

#### 配对码发放与首次绑定流程

以下是建议的生产流程；当前仓库只实现了开通和绑定接口，尚未实现配对码自动生成、制卡、
发放或 APP 扫码功能。

1. **制造/开通**：制造或管理系统为每台项圈分配全局唯一的 `collar_id`，使用安全随机数
   生成该项圈独立的高强度 `pairing_code`，并准备设备遥测公钥及其 key ID。受信任的管理端
   使用开通口令调用 `collars/provisionCollar`，将这些信息登记到服务端。服务端只保存
   配对码的 Argon2 哈希，不会在接口响应中返回明文配对码。
2. **发放**：建议将项圈 ID 和配对码印在包装内的保密码卡上，并遮盖配对码，避免从包装
   外部直接看到；也可将两者编码为卡片上的二维码。制卡、运输和交付过程须保护明文，
   不要将其写入普通日志。密码卡或二维码应由实际用户妥善保管。
3. **用户操作**：用户打开 APP 并注册或登录，选择“添加项圈”，扫描密码卡二维码；在
   扫码功能尚未实现时，手动输入卡上的项圈 ID 和配对码。这里描述的是建议的 APP 交互，
   并非当前仓库已有的移动端界面。
4. **APP 绑定**：APP 使用登录所得 access token 和对应的 `deviceId`，向
   `petpal/{tenant}/api/v1/collars/bind` 发送通用 RPC 信封，业务 `payload` 为：

   ```json
   {
     "collar_id": "collar-001",
     "pairing_code": "<密码卡上的配对码>"
   }
   ```

   `collar_id` 和配对码必须与开通时登记的值一致；通用信封格式见第 2 节。
5. **确认结果**：服务端验证配对码并建立用户与项圈的绑定，成功响应的 `data` 为
   `{"collarId":"collar-001","bound":true}`。APP 可调用 `users/listCollars` 确认。
   配对码错误返回 `403`，项圈未开通返回 `404`；APP 应给出适当的本地化提示。

`pairing_code` 是单台项圈的用户绑定凭据，不是管理端共享的
`COLLAR_PROVISIONING_TOKEN`，也不是设备遥测私钥；后两者均不应交给 APP 用户。测试脚本中的
`pair-${RUN_ID}-11` 是测试值，不适合生产使用。

当前配对码**不是一次性码，也没有过期时间**；任何登录用户持正确的项圈 ID 和配对码都可
绑定，并获得 GPS/IMU 流权限。建议家人通过下文的分享邀请获得所需流权限，而不是转发
配对码。配对码丢失或泄露后的身份核验、换码及撤销其他用户权限流程尚需设计；仅当前用户
解绑不会移除其他用户的绑定。

`collars/listUsers` 只允许已绑定该项圈的用户查看，user ID 按字符串排序。`getSystemInfo`
返回最近一次签名和序号验证通过的系统信息，包括电量百分比 `batteryPercent` 和固件版本
`firmwareVersion`；未绑定为 `403`，尚未收到系统信息为
`404`。此数据不等同于设备在线状态，项圈列表目前也不包含型号、固件或在线字段。

### 4.2 电子围栏和 GPS 告警

任一当前绑定用户可以设置该项圈共享的围栏。APP 必须提供地图中心。省略 `vertices` 或
传空数组时，服务使用中心周围默认 2,000 米圆：

```json
{
  "collar_id": "collar-001",
  "center": { "latitude": 39.9, "longitude": 116.4 }
}
```

自定义边界为按顺时针或逆时针排列的凸多边形，3–64 个不同顶点，每点含合法
`latitude`、`longitude`。坐标必须是 JSON 数字，不能编码成字符串。成功响应包含
共享 `center`、`vertices`、`boundaryType`；无效或非凸边界返回 `400`，未绑定返回
`403`。修改围栏会清除旧判断状态，下一个有效 GPS 样本重新判断。

服务仅处理已验签且序号递增的 GPS。首次位于围栏外或从内到外时，向在线、已绑定/获分享
且有 GPS 权限的 APP 会话发布一次 `outside_geofence`。持续在外不重复发送，返回围栏内会
重新布防。告警不存历史，APP 离线时不补发。

### 4.3 一键寻宠

APP 通过 `collars/findPet` 控制项圈，不能直接访问内部控制 key。`duration_seconds`
为可选整数，范围 5–120，默认 30 秒。服务等待 ESP32 实际启动 LED 和蜂鸣器并返回有效
ACK 后才向 APP 报成功。成功 `data` 示例：

```json
{
  "collarId": "collar-001",
  "commandId": "<命令ID>",
  "status": "started",
  "durationSeconds": 30,
  "startedAt": 1731398400000
}
```

非法时长为 `400`，未绑定为 `403`，项圈离线/5 秒内无有效 ACK 为 `504`，设备拒绝或
ACK 格式错误为 `502`。APP 应区分“命令已发送”和“设备确认已启动”。

### 4.4 项圈设置

设置保存在当前用户与项圈的组合下；首次绑定默认蜂鸣器和 LED 关闭，IMU/GPS 间隔均为
1 秒。不同用户可为同一共享项圈保存不同设置。蜂鸣器和 LED 是设备输出开关，间隔单位
为秒、范围 1–60。设置 API 可部分更新字段，未提供字段保留该用户此前保存的值。

例如同时开启蜂鸣器、关闭 LED，并设置 GPS 每 5 秒上报：

```sh
api_call_json collars setCollarSettings 0 "$DEVICE_ID" "$ACCESS_TOKEN" \
  collar_id "$COLLAR_ID" buzzer_on true led_on false gps_interval_seconds 5
api_call_json collars getCollarSettings 0 "$DEVICE_ID" "$ACCESS_TOKEN" \
  collar_id "$COLLAR_ID"
```

设置会先保存在服务器，再尝试将完整配置下发给在线设备。收到设备确认时 `status` 为
`applied`；设备不在线或 5 秒内无有效确认时为 `pending`，但用户设置仍已保存。登录只同步
到 APP，不会自动应用到设备；设备在线后由用户显式调用设置接口重试。共享项圈的实际硬件
状态由最近一次成功应用的用户设置决定。`findPet` 寻宠期间会临时开启蜂鸣器和 LED，结束
后恢复发起调用用户保存的输出状态。

### 4.5 分享

已绑定用户可创建 900 秒有效、只能接受一次的邀请。`streams` 可省略（默认 `gps` 和
`imu`），或为非空 `["gps"]`、`["imu"]`、`["gps","imu"]`。`imu` 权限控制行为结果流，
不是原始 IMU。必须由不同用户接受；创建者接受自己的邀请返回 `400`，无效、过期或已用
邀请返回 `404`。接受后新用户成为该项圈的共享用户，流权限按邀请返回。

### 4.6 APP 接口输入/输出字段逐项说明

以下为各 APP RPC 的完整业务字段释义；`{}` 表示该接口没有业务请求字段。通用信封字段见
§2.1。数值时间均为 Unix 毫秒，除非字段名或说明另有单位。
自动脚本只覆盖核心登录、设备管理和项圈开通/绑定流程；APP 端完整接口及每个成功响应字段
以本表为准，测试步骤和请求信封字段另见[测试指南](./testing.md#4-rpc-通用格式与手工调用)。

| 接口 | 请求字段中文解释 | 成功响应 `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`：要吊销的另一台 APP 设备 ID | `revoked`：是否已吊销；`deviceId`：被移除设备 ID |
| `users/telemetryHeartbeat` | 无业务字段 | `sessionId`：当前 APP 会话 ID；`onlineUntil`：会话在线租约截止时间 |
| `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` 内：`seq` 为系统信息序号，`startupTime` 为启动 Unix 毫秒时间，`uptimeSeconds` 为运行秒数，`flashBytes` 为 Flash 容量字节数，`manufacturer` 为制造商，`batteryPercent` 为电量百分比，`firmwareVersion` 为固件版本 |
| `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 上报间隔秒数；可只提交要修改的字段 | 返回保存后的完整设置（各字段含义同 `getCollarSettings`）；`deviceSettingsVersion`：设备端用于拒绝过期命令的版本；`status`：`applied` 表示设备确认应用，`pending` 表示已保存但设备尚未确认；`syncError`：可选的同步失败原因 |
| `collars/setGeofence` | `collar_id`：项圈 ID；`center.latitude`：围栏中心纬度；`center.longitude`：围栏中心经度；`vertices`：可选的多边形顶点数组，各点用 `latitude`、`longitude` 表示 | `collarId`：项圈 ID；`center`：围栏中心；`vertices`：多边形边界顶点（圆形时为空）；`boundaryType`：`circle` 或 `polygon`；`radiusMeters`：圆形半径，固定 2000 米 |
| `collars/findPet` | `collar_id`：项圈 ID；`duration_seconds`：可选寻宠时长，5–120 秒，默认 30 秒 | `collarId`：项圈 ID；`commandId`：设备命令 ID；`status`：设备确认状态；`durationSeconds`：实际时长；`startedAt`：设备确认启动时间 |
| `collars/createShareInvite` | `collar_id`：项圈 ID；`streams`：可选授权流数组，可含 `gps`、`imu` | `inviteToken`：一次性分享邀请码；`expiresIn`：邀请有效秒数 |
| `collars/acceptShareInvite` | `invite_token`：收到的一次性邀请码 | `collarId`：获分享的项圈 ID；`bound`：是否建立共享绑定；`streams`：实际授予的数据流权限 |

#### 登录响应字段

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

APP 不直接调用 `collars/provisionCollar` 或 `collars/authorize*Publisher`：项圈开通由受信任
管理端执行，发布授权仅供可信设备网关调用，字段说明见 [ESP32 开发指南](./esp32-development.md)。

## 5. APP 会话证书和实时订阅

### 5.1 申请 Zenoh 会话证书

APP 在本机生成私钥和 PEM PKCS#10 CSR；私钥不得上传。服务使用配置的客户端 CA 签发
300 秒有效的 client-auth 证书。请求仍需当前 access token 和匹配的 `deviceId`：

```json
{
  "v": 2,
  "reqId": "cert-1731398400000",
  "token": "<access token>",
  "deviceId": "ios-device-001",
  "ts": 1731398400000,
  "payload": { "csr_pem": "-----BEGIN CERTIFICATE REQUEST-----\n...\n" }
}
```

成功 `data`：

```json
{
  "sessionId": "<session ID>",
  "certificatePem": "<客户端证书 PEM>",
  "expiresAt": 1731398700000,
  "topicPrefix": "petpal/demo/users/<userId>/sessions/<sessionId>/telemetry/"
}
```

未配置 CA 返回 `503`，无效 CSR 返回 `400`。服务端签发证书不会自动配置 Router TLS、
CA 信任或 ACL；Router 必须信任签发 CA 并按证书的 tenant/user/session 身份限制 topic。
APP 私钥留在本地安全存储，证书过期前重新申请。`auth/issueZenohCredential` 只适用于
APP 会话，不是 ESP32 遥测凭据。

### 5.2 订阅实时数据

APP 仅订阅当前 user、session 和项圈对应的精确 topic：

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

GPS 消息包含位置、速度、航向等；行为消息包含英文 `behavior` 标签及 `simulated`；
围栏消息含 `alert="outside_geofence"`、位置和边界信息。APP 不订阅原始 IMU，也不发布
行为结果。GPS 和围栏受 GPS stream 权限控制，行为结果受 `imu` stream 权限控制；
共享用户只能看到邀请授予的流。

`data` 内字段说明：

| 消息类型 | 字段 | 中文解释 |
| --- | --- | --- |
| GPS | `latitude` / `longitude` | 纬度（-90 至 90 度）/ 经度（-180 至 180 度） |
| GPS | `altitude` | 海拔，单位米 |
| GPS | `speed` | 可选速度，单位米/秒 |
| GPS | `heading` | 可选航向角，单位度 |
| GPS | `accuracy` | 可选定位精度，单位米 |
| 行为 | `collarId` | 产生该行为结果的项圈 ID |
| 行为 | `behavior` | 识别出的行为标签，例如 `walking` |
| 行为 | `simulated` | 是否为模拟识别结果 |
| 围栏 | `alert` | 告警类型，目前为 `outside_geofence` |
| 围栏 | `position.latitude` / `position.longitude` | 触发告警的位置坐标 |
| 围栏 | `boundaryType` | 围栏类型，`circle` 或 `polygon` |
| 围栏 | `center.latitude` / `center.longitude` | 围栏中心坐标 |

GPS/行为/围栏 topic 是尽力而为实时流，不保证送达、无历史查询或离线补发。APP 建立
Zenoh 会话时须使用证书指定的身份和 `topicPrefix`；定期发送 heartbeat 保持在线租约。

| 字段 | 中文解释 |
| --- | --- |
| `v` | 实时消息协议版本，固定为 `2` |
| `reqId` | 对应遥测样本的关联 ID |
| `ts` | 样本采集时间，Unix 毫秒 |
| `payload.collarId` | 上报数据的项圈 ID |
| `payload.stream` | 数据流类型：`gps`、`behavior` 或 `geofence` |
| `payload.seq` | 对应数据流的单调递增序号 |
| `payload.data` | 该流具体内容；GPS 字段见下表，行为和围栏字段见后文 |

三种 APP 下行消息的 payload 结构如下；GPS 和行为数据放在 `data` 中，围栏告警是 GPS
stream 权限下的独立 `geofence` 消息：

```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 }
  }
}
```

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

```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 }
    }
  }
}
```

行为标签采用英文机器值：`feeding`、`jumping`、`playing`、`scratching`、`rolling`、
`running`、`licking_fur`、`lying_down`、`sleeping`、`standing`、`walking`、`sitting`、
`unknown`。展示名称由 APP 自行本地化；`simulated=true` 表示当前原型结果，不是生产模型
质量保证。

## 6. APP 端本地测试流程

### 6.1 启动和登录

按[测试指南](./testing.md)启动独立 Redis、Router 和统一 `pet_collar_service`。验证 APP 实时
数据还需要启动 `behavior-processor` 和已按
[ESP32 联调步骤](./esp32-development.md#8-本地设备联调和验收)开通、绑定的
`collar-simulator`。所有终端使用相同测试 tenant 和 endpoint；变量不在终端间共享。

在仓库根目录 Bash 终端加载测试脚本：

```sh
export ZENOH_ENDPOINT='tcp/127.0.0.1:17447'
export TENANT='demo'
export Z_GET="$HOME/src/zenoh-1.10.2/target/release/examples/z_get"
source ./scripts/test-apis.sh
PHONE='<一次性测试手机号>'
PASSWORD='<8至64字节的测试密码>'
```

新账号注册：

```sh
api_send_sms register
# Debug 通常已从响应保存 SMS_CODE；Release 收到短信后手工输入：
if [[ -z "$SMS_CODE" ]]; then
  read -r -s -p '短信验证码: ' SMS_CODE
  printf '\n'
fi
api_register
```

已注册账号登录：

```sh
api_login_password
USER_ID="$(response_field data.user.userId)"
SESSION_ID="$(response_field data.sessionId)"
```

`api_login_password`、`api_login_sms` 会把 token 保存在当前 shell 的 `ACCESS_TOKEN` 和
`REFRESH_TOKEN` 中。Debug 配置阿里云 SMS 时会真实发短信；Release 不会在响应或日志中
打印验证码。使用一次性手机号和隔离服务，避免真实短信费用和真实数据。

### 6.2 正确构造数字、对象和数组 payload

现有脚本的 `api_call` 适用于 payload 全为字符串的 API。围栏中心/顶点、寻宠时长和
`streams` 数组须保持 JSON 类型；在加载 `scripts/test-apis.sh` 后可定义以下 helper：

```sh
api_call_json() {
  local domain="$1" operation="$2" expected_code="$3"
  local device_id="$4" token="$5" payload_json="$6"
  local now req_id request output actual_code
  now="$(date +%s%3N)" || return 1
  req_id="manual-${now}"
  request="$(
    python3 - "$now" "$req_id" "$device_id" "$token" "$payload_json" <<'PY'
import json
import sys

now, req_id, device_id, token, payload = sys.argv[1:]
request = {"v": 2, "reqId": req_id, "ts": int(now), "payload": json.loads(payload)}
if device_id:
    request["deviceId"] = device_id
if token:
    request["token"] = token
print(json.dumps(request, separators=(",", ":")))
PY
  )" || return 1
  output="$(
    "$Z_GET" --connect "$ZENOH_ENDPOINT" \
      --selector "petpal/$TENANT/api/v1/$domain/$operation" \
      --payload "$request" --timeout 10000 2>&1
  )" || { printf '%s\n' "$output" >&2; return 1; }
  LAST_RESPONSE="$(
    Z_GET_OUTPUT="$output" python3 <<'PY'
import json
import os
import re

replies = []
for line in os.environ["Z_GET_OUTPUT"].splitlines():
    match = re.match(r"^>> Received \('([^']+)': '(.*)'\)$", line)
    if match:
        try:
            replies.append(json.loads(match.group(2)))
        except json.JSONDecodeError:
            pass
if not replies:
    raise SystemExit("No JSON API response found in z_get output")
print(json.dumps(replies[-1], separators=(",", ":")))
PY
  )" || return 1
  printf '%s\n' "$LAST_RESPONSE" | print_json || return 1
  actual_code="$(response_field code)" || return 1
  if [[ "$actual_code" != "$expected_code" ]]; then
    printf 'Expected code %s, got %s\n' "$expected_code" "$actual_code" >&2
    return 1
  fi
}
```

响应保存于 `LAST_RESPONSE`；可用 `response_field data.inviteToken` 提取字段。
默认会脱敏 token、验证码、证书等字段，不要开启 `SHOW_SENSITIVE=1` 后分享日志。

### 6.3 项圈管理 API 验收

先按[ESP32 指南](./esp32-development.md#8-本地设备联调和验收)创建并开通新测试项圈，
但先不要启动模拟器，以便检查无系统信息时的 `404`。以下 `COLLAR_ID`、
`PAIRING_CODE`、`ACCESS_TOKEN` 均须替换为当前测试 shell 的实际值。对已有真实项圈不要
重复 provision。

```sh
# 项圈列表：空列表或已绑定列表均为 code=0
api_call users listCollars 0 "$DEVICE_ID" "$ACCESS_TOKEN"

# 使用正确配对码绑定
api_call collars bind 0 "$DEVICE_ID" "$ACCESS_TOKEN" \
  collar_id "$COLLAR_ID" pairing_code "$PAIRING_CODE"

# 用户项圈列表、项圈绑定用户列表
api_call users listCollars 0 "$DEVICE_ID" "$ACCESS_TOKEN"
api_call collars listUsers 0 "$DEVICE_ID" "$ACCESS_TOKEN" collar_id "$COLLAR_ID"

# 模拟器上报系统信息前预期 404；上报后预期 0
api_call collars getSystemInfo 404 "$DEVICE_ID" "$ACCESS_TOKEN" collar_id "$COLLAR_ID"
# 按 ESP32 指南启动模拟器并等待至少一轮 system-info 发布后：
api_call collars getSystemInfo 0 "$DEVICE_ID" "$ACCESS_TOKEN" collar_id "$COLLAR_ID"

# 设置默认圆形围栏，中心为模拟器固定 GPS 坐标
api_call_json collars setGeofence 0 "$DEVICE_ID" "$ACCESS_TOKEN" \
  "{\"collar_id\":\"$COLLAR_ID\",\"center\":{\"latitude\":39.9,\"longitude\":116.4}}"

# 在线模拟器确认寻宠
api_call_json collars findPet 0 "$DEVICE_ID" "$ACCESS_TOKEN" \
  "{\"collar_id\":\"$COLLAR_ID\",\"duration_seconds\":10}"
```

额外验收自定义凸多边形和越界告警：用 `api_call_json` 传递 3–64 个顺/逆时针凸顶点；
将模拟器默认圆心改为 `(0,0)` 后下一条 GPS 应触发一次 `outside_geofence`，再次越界不重复。
非法坐标/非凸多边形为 `400`，未绑定用户为 `403`。

### 6.4 分享和用户设备管理

创建分享邀请（必须由已绑定用户执行）：

```sh
api_call_json collars createShareInvite 0 "$DEVICE_ID" "$ACCESS_TOKEN" \
  "{\"collar_id\":\"$COLLAR_ID\",\"streams\":[\"gps\",\"imu\"]}"
INVITE_TOKEN="$(response_field data.inviteToken)"
```

在另一测试用户自己的 shell 中登录另一账号，使用它自己的 `DEVICE_ID` 和 `ACCESS_TOKEN`
接受邀请：

```sh
source ./scripts/test-apis.sh
PHONE='<第二个测试用户手机号>'
PASSWORD='<第二个测试用户密码>'
api_login_password
COLLAR_ID='<创建邀请的项圈 ID>'
INVITE_TOKEN='<创建者安全传递的一次性 inviteToken>'
api_call collars acceptShareInvite 0 "$DEVICE_ID" "$ACCESS_TOKEN" \
  invite_token "$INVITE_TOKEN"
```

应返回 `bound=true` 和 `streams=["gps","imu"]`。邀请创建者自己接受为 `400`；无效或已
使用 token 为 `404`。用不同账号的 APP 订阅 topic，验证 GPS 和行为流按权限分发。

完成实时流和分享测试后解绑当前用户：

```sh
api_call collars unbind 0 "$DEVICE_ID" "$ACCESS_TOKEN" collar_id "$COLLAR_ID"
api_call collars unbind 404 "$DEVICE_ID" "$ACCESS_TOKEN" collar_id "$COLLAR_ID"
api_call users listCollars 0 "$DEVICE_ID" "$ACCESS_TOKEN"
```

分享接收者仍拥有自己的绑定，owner 解绑不应移除接收者权限。

用户会话测试：

```sh
api_call users listDevices 0 "$DEVICE_ID" "$ACCESS_TOKEN"
api_call users telemetryHeartbeat 0 "$DEVICE_ID" "$ACCESS_TOKEN"
```

`removeDevice` 需先让同一账号以第二个 `deviceId` 登录，再由当前设备移除另一设备；不要
移除当前设备：

```sh
api_call auth loginByPassword 0 "$DEVICE_ID_2" "" \
  phone "$PHONE" password "$PASSWORD" \
  device_name 'APP secondary' device_model 'Test phone' platform android os_ver 'test'
SECOND_ACCESS_TOKEN="$(response_field data.access)"
api_call users removeDevice 0 "$DEVICE_ID" "$ACCESS_TOKEN" device_id "$DEVICE_ID_2"
api_call users listDevices 4403 "$DEVICE_ID_2" "$SECOND_ACCESS_TOKEN"
```

注销测试放在所有其他受保护 API 测试之后：

```sh
api_call auth logout 0 "$DEVICE_ID" "$ACCESS_TOKEN"
api_call users listDevices 4403 "$DEVICE_ID" "$ACCESS_TOKEN"
```

### 6.5 认证、证书及异常验收

使用一次性账号覆盖 `sendSms(register/login)`、`register`、密码登录、短信登录和 token
刷新。`api_refresh` 会自动替换当前 shell 的 access/refresh；不要把已使用的旧 refresh
重放到日常账号，因为重放会吊销该设备会话。验证 OAuth、重置密码和绑定手机号接口时，
当前版本预期固定返回 `503`。

验证 APP mTLS 证书前，管理服务须配置本地测试 CA（步骤见
[测试指南](./testing.md#14-可选准备证书签发-api-的本地-ca)）。APP 本地创建私钥与 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 test session'
CSR_PEM="$(cat app-session.csr)"
api_call auth issueZenohCredential 0 "$DEVICE_ID" "$ACCESS_TOKEN" csr_pem "$CSR_PEM"
```

成功响应包含 300 秒有效证书、`sessionId`、`expiresAt` 和 `topicPrefix`。未配置 CA 为
`503`，无效 CSR 为 `400`；真实 APP 需用返回证书、本地私钥和 Router CA 建立 mTLS，
并由 Router ACL 限制会话 topic。证书接口不可替代 ESP32 的设备凭据。

| API / 功能 | 成功验收 | 失败验收 |
| --- | --- | --- |
| `auth/sendSms` | debug 本地验证码或短信送达；`expiresIn=600` | 非法 scope `400`；已注册手机号注册 `4517` |
| `auth/register` | 新账号登录成功、返回 token 和 session | 错误/缺失验证码对应短信错误码；手机号已注册 `4517` |
| `auth/loginByPassword` | 返回当前设备会话 | 错密码 `401`；达到阈值锁定 `4514` |
| `auth/loginBySms` | login 短信码登录成功 | 未注册手机号 `401`；错误/过期码错误 |
| `auth/refresh` | token 轮换且 session ID 不变 | 重放旧 refresh 吊销设备会话 |
| `auth/logout` | `loggedOut=true` | 同 token 后续访问 `4403` |
| `auth/issueZenohCredential` | 配 CA 后签发 300 秒证书 | 无 CA `503`；无效 CSR `400` |
| `auth/loginByOauth` / `resetPassword` / `bindPhone` | 当前无成功路径 | 固定 `503` |
| `users/listDevices` | 会话列表含当前设备和时间字段 | 无效 token `401`；已吊销 token `4403` |
| `users/listCollars` | 绑定后包含项圈 ID | 无效/已吊销 token `401`/`4403` |
| `users/removeDevice` | 删除同账号另一设备 | 删除自己 `400`；不存在设备 `404` |
| `users/telemetryHeartbeat` | `onlineUntil` 约为当前时间 + 60 秒 | 无效/已吊销 token `401`/`4403` |
| `collars/bind` | 正确配对码成功；重复绑定仍成功 | 错误码 `403`；未开通 ID `404` |
| `collars/unbind` | 当前用户解除绑定 | 重复解绑 `404`；其他用户绑定不应受影响 |
| `collars/listUsers` | owner/分享用户被列出 | 未绑定用户 `403` |
| `collars/getSystemInfo` | 返回最新系统信息 | 未上报 `404`；未绑定 `403` |
| `collars/setGeofence` | 默认圆和有效凸多边形成功 | 非法/非凸 `400`；未绑定 `403` |
| `collars/findPet` | 在线设备确认后 `started` | 时长非法 `400`；离线无 ACK `504`；设备拒绝 `502` |
| `collars/createShareInvite` | 有效 GPS/IMU 授权创建 900 秒邀请 | 空/未知 stream `400`；未绑定 `403` |
| `collars/acceptShareInvite` | 第二个用户得到匹配流权限 | 创建者接受 `400`；失效/过期/已用 `404` |

GPS、行为和围栏 topic 的成功/权限测试见第 5 节及
[ESP32 端到端验收](./esp32-development.md#8-本地设备联调和验收)。发布/订阅没有逐样本
RPC code；验收 APP 是否真的收到授权 topic，而不是只看发送端日志。

## 7. APP 上线检查

- access token 与其 `deviceId` 绑定；refresh 成功后原子替换 token，退出时清除本机凭据。
- 业务错误按 `code` 处理并本地化；超时显示链路/服务不可用，不能伪装成无项圈或无数据。
- 心跳至少每 60 秒续租；证书到期前刷新并按新 session 身份重建订阅。
- 只订阅当前会话和已授权项圈的 GPS、behavior、geofence topic；不订阅原始 IMU。
- 默认围栏半径 2 公里；共享用户的围栏是项圈级共享配置，修改会影响所有绑定用户。
- 寻宠等待设备 ACK；只有 `status="started"` 才提示成功。
- 邀请 token 一次性且有效期 900 秒；只向预期用户安全传递，不写日志或埋点。
- 实时数据不存历史、不补发离线样本；UI 必须区分实时状态与最新已接收数据。
