# 服务启动与 API 测试指南

本文面向本地隔离环境，覆盖服务启动、自动测试、手工 RPC 请求与响应及异常测试。
完整协议、字段限制和遥测签名规则以 [Zenoh RPC API](./zenoh-rpc-api.md) 为准。
ESP32 和 APP 的职责、接口与专项联调分别见
[ESP32 开发指南](./esp32-development.md)和[APP 开发指南](./app-development.md)。
服务使用 **Zenoh Query/Reply，不提供 HTTP API**；下列 `code` 是 JSON 中的业务码，
不是 HTTP 状态码。

## 1. 从干净系统部署测试环境

以下步骤以全新安装的 **Ubuntu 24.04 LTS x86_64** 为基线；其他发行版请换用等价
软件包命令。本指南假设代码仓库已通过有权限的 Git 地址检出，所有测试服务只绑定
本机回环地址，不提供 HTTP API，也不要在生产或共享 Redis/Router 上执行。

### 1.1 安装系统依赖

在仓库外的终端安装编译 Rust、Redis、Zenoh 示例和脚本所需的工具：

```sh
sudo apt update
sudo apt install -y \
  build-essential ca-certificates curl git jq libssl-dev pkg-config \
  protobuf-compiler python3 redis-server
```

使用 Rust 官方 rustup 安装器获取支持 Rust 2024 edition 的 stable 工具链；
Ubuntu 仓库自带的 `rustc` 可能太旧：

```sh
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal
source "$HOME/.cargo/env"
rustup toolchain install stable
rustup default stable
rustc --version
cargo --version
```

### 1.2 安装匹配版本的 Zenoh 工具

应用依赖 Zenoh `1.10.2`。安装同版本 Router：

```sh
cargo install zenohd --version 1.10.2 --locked
zenohd --version
```

`z_get` 和 `z_sub` 是 Zenoh Rust 示例，不保证随 `zenohd` 安装。由相同 release
tag 构建，避免命令行参数与服务使用的 Zenoh 版本不一致：

```sh
mkdir -p "$HOME/src"
git clone --depth 1 --branch 1.10.2 \
  https://github.com/eclipse-zenoh/zenoh.git "$HOME/src/zenoh-1.10.2"
cargo build --locked --release \
  --manifest-path "$HOME/src/zenoh-1.10.2/examples/Cargo.toml" \
  --example z_get --example z_sub
export Z_GET="$HOME/src/zenoh-1.10.2/target/release/examples/z_get"
export Z_SUB="$HOME/src/zenoh-1.10.2/target/release/examples/z_sub"
export PATH="$HOME/src/zenoh-1.10.2/target/release/examples:$PATH"
"$Z_GET" --help
"$Z_SUB" --help
```

如果要在新终端使用 shell 测试脚本，请在该终端重新设置 `Z_GET` 和 `Z_SUB`，
或将它们加入当前用户的 shell 配置。

### 1.3 检出并构建项目

将 `<项目 Git 地址>` 替换为团队提供的仓库地址；随后在仓库根目录执行构建。
`Cargo.lock` 将 Rust 依赖锁定为已验证版本：

```sh
git clone '<项目 Git 地址>' pet_collar_service
cd pet_collar_service
cargo test --locked
cargo build --locked --bins
```

首次构建需要互联网下载 Rust crates，耗时取决于网络和机器性能。编译失败时先看
缺失的系统库/编译器提示；不要用 `sudo cargo`，也不要修改 lockfile 来绕过错误。

### 1.4 可选：准备证书签发 API 的本地 CA

其余管理 RPC 不依赖证书；若要验证 `auth/issueZenohCredential` 的成功路径，必须在
启动管理服务前配置测试 CA。CA 和 APP 私钥只放在仓库之外的私有目录：

```sh
umask 077
TEST_CERT_DIR="$(mktemp -d "$HOME/petpal-test-ca.XXXXXX")"
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:prime256v1 \
  -out "$TEST_CERT_DIR/client-ca.key"
openssl req -new -x509 -key "$TEST_CERT_DIR/client-ca.key" \
  -out "$TEST_CERT_DIR/client-ca.crt" -days 30 \
  -subj '/CN=PetPal Local Test CA' \
  -addext 'basicConstraints=critical,CA:TRUE' \
  -addext 'keyUsage=critical,keyCertSign,cRLSign'
openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \
  -keyout "$TEST_CERT_DIR/app-session.key" \
  -out "$TEST_CERT_DIR/app-session.csr" \
  -subj '/CN=PetPal Local Test APP'
printf '测试证书目录：%s\n' "$TEST_CERT_DIR"
```

启动管理服务的终端需要设置 `ZENOH_CLIENT_CA_CERT_PATH` 和
`ZENOH_CLIENT_CA_KEY_PATH` 为上述证书路径。测试接口时，在已登录的 Bash 测试终端
执行以下命令；预期返回 300 秒有效的 `certificatePem`：

```sh
TEST_CERT_DIR='<1.4 打印的测试证书目录>'
CSR_PEM="$(cat "$TEST_CERT_DIR/app-session.csr")"
api_call auth issueZenohCredential 0 "$DEVICE_ID" "$ACCESS_TOKEN" csr_pem "$CSR_PEM"
```

未配置 CA 时预期为 `503`。测试完成后按本机密钥管理要求销毁该临时目录。

### 1.5 测试边界与准备

测试需要 Rust/Cargo、Zenoh 1.10.2 Router、Redis、Python 3 和 Bash。手工 RPC 与
Shell 集成测试还需要上一节构建的 `z_get`；遥测联调需要 `z_sub`。
使用**一次性手机号、独立 tenant 和独立 Redis**；测试会创建用户、会话和项圈，
部分记录在测试结束后仍保留。下面使用本机端口 `17447`、`16379` 和默认 tenant
`demo`；如果端口被占用，请选择空闲端口并同步修改所有命令。不要操作其他用户
或生产环境的 Redis、Router 或数据。

确认版本和命令：

```sh
cargo --version
zenohd --version
redis-cli --version
python3 --version
test -x "$Z_GET" && test -x "$Z_SUB"
timedatectl status
```

管理服务使用 **debug 构建**时，短信验证码会返回给测试客户端并打印在服务终端。
如果配置了完整的阿里云短信参数，debug 也会实际发送短信；未配置时则仅用于本地
联调，不调用短信供应商。release 必须配置阿里云短信，成功发送后只返回有效期，
不在响应或日志中打印验证码。

## 2. 启动服务

以下命令在仓库根目录执行，在不同终端分别保持前台运行。示例 Redis 无密码、
Router 使用明文 TCP，仅适用于本机隔离测试。

### 2.1 启动 Redis

在空闲端口启动专用的临时 Redis，禁止持久化：

```sh
redis-server --bind 127.0.0.1 --port 16379 --save "" --appendonly no
```

另开终端验证：

```sh
redis-cli -h 127.0.0.1 -p 16379 ping
```

预期为 `PONG`。如果使用已有隔离 Redis，应使用其实际 URL 和认证方式；
URL 中的特殊字符需进行 URL 编码。

### 2.2 启动 Zenoh Router

```sh
zenohd --no-multicast-scouting -l tcp/127.0.0.1:17447
```

保持进程运行。`--no-multicast-scouting` 用于避免本地测试 Router 响应组播发现。
服务与客户端仍需明确连接此 endpoint。

### 2.3 启动服务

本地测试可在一个终端以默认统一模式同时启动管理 API 和遥测处理。先复制
[service.example.yaml](../service.example.yaml) 到私有 `service.yaml`，将其中
`redis_url` 设置为 `redis://127.0.0.1:16379/`、`tenant` 保持为 `demo`，并把示例开通口令
替换为**专用于测试的随机值**；不要将真实口令写入仓库或共享终端日志。

```sh
export ZENOH_ROUTER_ENDPOINT='tcp/127.0.0.1:17447'
export ZENOH_TENANT='demo'
export COLLAR_PROVISIONING_TOKEN='<专用测试口令>'
unset REDIS_URL
# 需要测试 auth/issueZenohCredential 时，填入 1.4 输出的实际证书目录：
# export ZENOH_CLIENT_CA_CERT_PATH='<测试证书目录>/client-ca.crt'
# export ZENOH_CLIENT_CA_KEY_PATH='<测试证书目录>/client-ca.key'
cargo run --locked --bin pet_collar_service -- --config ./service.yaml
```

此处 Redis URL 来自 YAML；`unset REDIS_URL` 可防止环境变量按优先级覆盖它。不要把测试用的
无密码地址用于生产。

多实例部署时，每个实例默认运行统一服务；每个实例都处理管理 API Query，但 Redis 租约
只允许一个实例运行遥测订阅，其余实例等待接管。以下命令应由不同容器/终端或部署平台分别启动：

```sh
cargo run --locked --bin pet_collar_service -- --config ./service.yaml
```

所有实例必须使用相同配置，且不能被不同的 `REDIS_URL` 或 `--redis-url` 覆盖；各实例还须
配置相同的开通口令、短信服务及 APP 证书签发 CA。可用 `--role api` / `--role telemetry`
分别部署；租约也会限制多个遥测角色中仅一个活跃消费。

日志出现 `Management API queryables listening` 和
`GPS/IMU/system/behavior telemetry subscribers listening` 表示管理 API 和遥测处理均已
启动；仍需通过第 4 节实际请求确认 Router 端到端可达。若持续出现重试，检查 endpoint、
Redis 连接和认证。

也可复制 [service.example.yaml](../service.example.yaml) 到私有配置文件，替换
占位值后使用 `cargo run --locked --bin pet_collar_service -- --config ./service.yaml`。
配置优先级为 **CLI > 环境变量 > YAML > 默认值**；务必检查环境变量没有覆盖
预期配置。统一服务中的管理 API 与遥测处理共用 tenant、Redis 和 Router 配置。
证书和生产 TLS 配置见 [开发与配置](./development.md)。

默认统一模式会自动启动遥测处理，管理 API 测试无需额外服务进程；GPS/IMU、系统信息
和行为数据的连接、签名及 ACL 端到端验证见第 7 节。生产使用多个 API 副本时，只保留
一个活跃的遥测角色，避免多个订阅者造成序号竞争。

## 3. 自动测试

### 3.1 本地检查

```sh
cargo fmt --check
cargo test --locked
cargo check --locked --release
bash -n scripts/test-apis.sh
bash scripts/test-apis-source-test.sh
```

单元测试不需要运行 Redis 或 Router；这些命令不等同于真实网络集成测试。

### 3.2 Shell 集成测试

在测试客户端终端设置与管理服务一致的 endpoint、tenant 和开通口令。当前
一键脚本从密码登录开始，需要已注册的测试手机号；单步注册则需要未注册号码。

```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"
export PHONE='<已注册的测试手机号>'
export PASSWORD='<8至64字节的测试密码>'
export PROVISIONING_TOKEN='<与管理服务相同的测试口令>'
./scripts/test-apis.sh
```

每次调用打印 key、请求、响应和预期业务码，全部成功时显示
`All API checks passed.`。默认脱敏手机号、密码、验证码、token、配对码和证书等；
`SHOW_SENSITIVE=1` 会输出敏感内容，只能在私密终端使用，不要保存或分享输出。

当前脚本中的注册短信和注册调用已被注释，一键执行从密码登录开始，因此需要
已注册的测试账号；如需逐步注册，请使用第 4.2 节的 `source` 模式。其余一键
流程覆盖密码/短信登录、占位接口、刷新、设备列表与移除、项圈开通/绑定/查询/
解绑，以及部分异常场景。它不覆盖证书签发、分享邀请、publisher 授权或
端到端遥测；见第 6、7 节。脚本不会删除所有测试记录。

### 3.3 Rust 集成客户端

也可使用内置客户端，需换用另一个未注册手机号：

```sh
cargo run --locked --bin api-test -- \
  --endpoint tcp/127.0.0.1:17447 \
  --tenant demo \
  --phone '<另一个未注册的测试手机号>' \
  --password '<8至64字节的测试密码>' \
  --provisioning-token "$PROVISIONING_TOKEN"
```

预期最后输出 `All 17 API checks passed.`。该客户端的密码和口令通过命令行
参数传入，在共享机器上可能被其他用户通过进程信息看到；只在可信环境运行。

## 4. RPC 通用格式与手工调用

### 4.1 Key、请求和响应

请求使用 Zenoh `get`，selector 为精确 key：

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

不要对写操作使用 `All` query target；默认 `BestMatching` 会选择一个匹配的
queryable。通用请求信封：

```json
{
  "v": 2,
  "reqId": "manual-1731398400000",
  "deviceId": "test-device-1",
  "token": "<需要鉴权时填写 access token>",
  "ts": 1731398400000,
  "payload": {}
}
```

| 字段 | 测试要求 |
| --- | --- |
| `v` | 固定数字 `2`。 |
| `reqId` | 客户端生成的请求关联 ID，响应会回显此值；前缀只含 ASCII 字母、数字、`_`、`-`，最后一个 `-` 后必须是 13 位数字；不提供幂等保证。 |
| `ts` | 当前 Unix 毫秒，允许与服务端相差最多 120 秒；示例中的历史时间不能直接用于实际请求。 |
| `deviceId` | 除 `users/listDevices`、`users/listCollars`、`collars/listUsers`、`collars/getSystemInfo`、`collars/getCollarSettings` 外均必填；1–128 个 ASCII 字母、数字或 `-_.:`。需要设备鉴权的操作须与 token 所属设备一致。 |
| `token` | 需要用户鉴权时填 access token；`auth/refresh` 使用 `payload.refresh`，不使用 access token。 |
| `payload` | 必须是 JSON object，字段名为 snake_case；嵌套深度不超过 5。整个请求不超过 16 KB。 |

通用成功响应（`ts`、`reqId` 和数据为示例）：

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

失败示例：

```json
{"v":2,"reqId":"manual-1731398400000","code":401,"msg":"token is required","data":null,"ts":1731398400123}
```

响应 `reqId` 对应请求，`ts` 为服务端 Unix 毫秒；`code=0` 表示成功。
错误 `data` 通常为 `null`，`4512` 和短信锁定等例外会返回附加数据。
无 reply 或超时不是业务错误响应，应检查链路、服务和 tenant。

响应 JSON 字段含义：

| 字段 | 中文解释 |
| --- | --- |
| `v` | 响应信封版本，固定为 `2` |
| `reqId` | 回显请求中的关联 ID，用于匹配请求和响应 |
| `code` | 业务结果码；`0` 成功，非零表示接口处理失败 |
| `msg` | 面向开发者的结果说明；客户端应按 `code` 映射提示，不直接展示英文内容 |
| `data` | 接口业务结果；结构由具体操作决定，失败时通常为 `null` |
| `ts` | 服务端生成响应的 Unix 毫秒时间 |

`scripts/test-apis.sh` 按 `code` 判断预期结果，并从 `data.smsCode`、`data.access`、
`data.refresh` 等路径提取后续步骤所需值；这些路径中的字段语义见
[API 契约的字段中文说明](./zenoh-rpc-api.md#接口字段中文说明)。

### 4.2 可复用的手工请求

在安装了 `z_get` 和 Python 3 的 **Bash** 终端加载现有脚本。加载只定义函数和
初始化测试变量，不发送请求，也不改变当前 shell 的 `set` 选项。请在仓库根目录
运行；参数可以在加载后修改：

```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字节的测试密码>'
PROVISIONING_TOKEN='<与管理服务相同的测试口令>'
```

随后在**同一个终端**逐条执行；每条可单独调用并检查输出，不必复制响应中的
验证码或 token：

```sh
# debug 服务自动将返回的验证码保存到 SMS_CODE。
api_send_sms register
api_register                  # 保存 ACCESS_TOKEN 和 REFRESH_TOKEN
api_call users listDevices 0 "$DEVICE_ID" "$ACCESS_TOKEN"

api_call collars provisionCollar 0 "$DEVICE_ID" "" \
  provisioning_token "$PROVISIONING_TOKEN" collar_id "$COLLAR_ID" \
  pairing_code "$PAIRING_CODE" telemetry_key_id "api-test-${RUN_ID}" \
  telemetry_public_key "d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a"
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"

api_refresh                   # 自动替换 ACCESS_TOKEN 和 REFRESH_TOKEN
api_call collars unbind 0 "$DEVICE_ID" "$ACCESS_TOKEN" collar_id "$COLLAR_ID"
api_call auth logout 0 "$DEVICE_ID" "$ACCESS_TOKEN"
api_call users listDevices 4403 "$DEVICE_ID" "$ACCESS_TOKEN"
```

`source` 只加载函数并返回当前 Bash 提示符，不会运行完整测试序列或调用 `exit`。
函数会通过返回码报告失败；若当前 shell 开启了 `set -e`，请将可能失败的单步请求放在
条件语句中，避免 Bash 自身的 errexit 规则关闭交互 shell：

```sh
if api_call users listDevices 0 "$DEVICE_ID" "$ACCESS_TOKEN"; then
  echo "request succeeded"
else
  echo "request failed; shell is still available for the next command"
fi
```

完整批量测试只会在直接执行 `./scripts/test-apis.sh` 时运行。source 模式的回归检查：
`bash scripts/test-apis-source-test.sh`。

如果账号已经注册，可以直接使用 `api_login_password`；短信登录使用
`api_send_sms login`，然后 `api_login_sms`。这两个登录函数同样自动保存 token。
debug 的 `SMS_CODE` 自动提取；配置了短信供应商时，该验证码也会通过阿里云发送。
**release 不返回或打印验证码**，必须在短信送达后手工输入，再运行 `api_register`
或 `api_login_sms`：

```sh
read -r -s -p '短信验证码: ' SMS_CODE; printf '\n'
```

release 以及配置阿里云的 debug 构建都需要有效短信供应商配置，发送短信可能产生
费用。debug 服务终端会打印验证码，只能在可信终端查看；不要保存或分享终端日志，
也不要把验证码写入脚本或提交到仓库。`api_call` 的参数为
`域 操作 预期code deviceId token [字段 值 ...]`；
字段和值均按字符串编码，不适合 `streams` 数组等复杂 JSON 请求。响应保存在
`LAST_RESPONSE`，可用 `response_field data.<字段名>` 提取；该命令会直接输出
字段值，包括可能的敏感信息。默认打印经过脱敏；`SHOW_SENSITIVE=1` 会关闭脱敏。
函数失败会返回非零，不主动退出当前 shell；调用方若启用了 `set -e` 仍须遵循
自身 shell 的错误退出规则。所有状态只保存在当前 shell，重新 `source` 或退出
终端会重置会话变量，不会恢复已轮换的 token。

示例公钥只用于开通接口测试，不代表已配置能签名遥测的私钥。重复运行前选择
未注册手机号和全局资产系统尚未分配的新项圈 ID；不要覆盖已有项圈。服务端不拒绝
重复 ID，重复 provision 会覆盖原配对码和遥测公钥并保留绑定。刷新或同设备重新登录后旧 token
不再可用；**重放已使用的 refresh 会吊销该设备整个会话**。

## 5. 全部 RPC 请求及成功响应参数

本节每条请求都使用第 4 节信封；表中只展示 `payload` 和响应 `data`。
字符串中的 `<...>` 必须替换为实际值，时间均为 Unix 毫秒。失败时检查完整响应
的 `code`、`msg`、`data`；第 6 节给出测试场景。

### 5.1 身份与会话：auth

注册、密码登录、短信登录共用设备字段：`device_name`、`device_model`、
`os_ver` 为非空、最长 128 字节；`platform` 为 `ios`、`android` 或 `ohos`。
手机号为 5–32 个字符，仅允许数字、`+`、`-`；密码为 8–64 字节。

| 操作 | 鉴权 | 请求 `payload` 示例 | 成功 `data` 示例或结果 |
| --- | --- | --- | --- |
| `auth/sendSms` | 无 token | `{"phone":"<phone>","scope":"register"}`；scope 为 `register` 或 `login` | debug：打印并返回 `smsCode`；配置阿里云时同时发送；release：发送成功后仅返回 `{"expiresIn":600}`，不打印验证码 |
| `auth/register` | 无 token | `{"phone":"<phone>","sms_code":"123456","password":"<password>","device_name":"Test","device_model":"Phone","platform":"android","os_ver":"14"}` | 下方登录响应，`isNewUser=true` |
| `auth/loginByPassword` | 无 token | `{"phone":"<phone>","password":"<password>","device_name":"Test","device_model":"Phone","platform":"android","os_ver":"14"}` | 下方登录响应，`isNewUser=false` |
| `auth/loginBySms` | 无 token | `{"phone":"<phone>","sms_code":"123456","device_name":"Test","device_model":"Phone","platform":"android","os_ver":"14"}` | 下方登录响应，`isNewUser=false`；须先发送 `scope=login` 验证码 |
| `auth/loginByOauth` | 无 token | 脚本发送 `provider`、`code` 和设备字段作为占位数据；服务当前不读取这些字段 | 固定 `503`，`msg="login provider is not configured"`，`data=null` |
| `auth/resetPassword` | 无 token | 脚本发送 `phone`、`sms_code`、`new_password`；服务当前不读取这些字段 | 固定 `503`，`msg="SMS provider is not configured"`，`data=null` |
| `auth/bindPhone` | 无 token | 脚本发送 `phone`、`sms_code`；服务当前不读取这些字段 | 固定 `503`，`msg="SMS provider is not configured"`，`data=null` |
| `auth/refresh` | 无 access token；设备须匹配 refresh | `{"refresh":"<refresh>"}` | `{"access":"<new-access>","accessExpireAt":0,"refresh":"<new-refresh>","refreshExpireAt":0,"sessionId":"<session-id>"}` |
| `auth/logout` | access token，设备须匹配 | `{}` | `{"loggedOut":true}` |
| `auth/issueZenohCredential` | access token，设备须匹配；须配置签发 CA | `{"csr_pem":"-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----\n"}` | `{"sessionId":"<session-id>","certificatePem":"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n","expiresAt":0,"topicPrefix":"petpal/demo/users/<user-id>/sessions/<session-id>/telemetry/"}` |

登录成功 `data` 的完整结构：

```json
{
  "access": "<access-token>",
  "accessExpireAt": 1731400200000,
  "refresh": "<refresh-token>",
  "refreshExpireAt": 1733990400000,
  "sessionId": "<session-id>",
  "user": {"userId": "<user-id>", "phone": "<phone>"},
  "isNewUser": true,
  "deviceId": "test-device-1",
  "collarSettings": []
}
```

access 有效期 30 分钟，refresh 有效期 30 天。证书有效期 300 秒；未配置签发
CA 时证书接口返回 `503`。生成 CSR、构造请求及验证 mTLS 的部署要求见
[证书签发说明](./zenoh-rpc-api.md#authissuezenohcredential)。

### 5.2 用户和设备：users

所有操作都需要 access token。`listDevices` 和 `listCollars` 可省略 `deviceId`；
其余操作必须带与 access token 匹配的 `deviceId`。

| 操作 | 请求 `payload` | 成功响应 `data` |
| --- | --- | --- |
| `users/listDevices` | `{}` | `{"sessions":[{"deviceId":"test-device-1","deviceName":"Test","deviceModel":"Phone","platform":"android","loginAt":1731398400000,"sessionDurationMs":1000,"lastActiveAt":1731398401000,"current":true}]}` |
| `users/listCollars` | `{}` | `{"collars":["manual-collar-1"]}`；无绑定时数组为空 |
| `users/removeDevice` | `{"device_id":"test-device-2"}` | `{"revoked":true,"deviceId":"test-device-2"}`；只能移除另一台设备 |
| `users/telemetryHeartbeat` | `{}` | `{"sessionId":"<session-id>","onlineUntil":1731398460000}`；在线租约 60 秒 |

设备列表按 `lastActiveAt` 从新到旧排列，`current` 指本次 token 所属设备。

### 5.3 项圈：collars

| 操作 | 鉴权 / 前提 | 请求 `payload` | 成功响应 `data` |
| --- | --- | --- | --- |
| `collars/provisionCollar` | 无用户 token；需开通口令和合法 `deviceId` | `{"provisioning_token":"<secret>","collar_id":"manual-collar-1","pairing_code":"<pairing-code>","telemetry_key_id":"test-key-1","telemetry_public_key":"<32字节Ed25519公钥的64位hex>"}` | `{"collarId":"manual-collar-1","telemetryKeyId":"test-key-1","provisioned":true}` |
| `collars/bind` | access token，设备须匹配 | `{"collar_id":"manual-collar-1","pairing_code":"<pairing-code>"}` | `{"collarId":"manual-collar-1","bound":true}` |
| `collars/unbind` | access token，设备须匹配 | `{"collar_id":"manual-collar-1"}` | `{"collarId":"manual-collar-1","bound":false}` |
| `collars/listUsers` | access token；调用者已绑定；`deviceId` 可省略 | `{"collar_id":"manual-collar-1"}` | `{"collarId":"manual-collar-1","users":["<user-id>"]}` |
| `collars/getSystemInfo` | access token；调用者已绑定；`deviceId` 可省略 | `{"collar_id":"manual-collar-1"}` | `{"collarId":"manual-collar-1","systemInfo":{"reportedAt":1731398400000,"info":{"seq":1,"startupTime":1731398300000,"uptimeSeconds":100,"flashBytes":4194304,"manufacturer":"Example vendor","batteryPercent":87,"firmwareVersion":"1.2.3"}}}` |
| `collars/getCollarSettings` | access token；调用者已绑定；`deviceId` 可省略 | `{"collar_id":"manual-collar-1"}` | `{"collarId":"manual-collar-1","buzzerOn":false,"ledOn":false,"imuBatchIntervalSeconds":1,"gpsIntervalSeconds":1}` |
| `collars/setCollarSettings` | access token；调用者已绑定；需当前设备 `deviceId` | `{"collar_id":"manual-collar-1","buzzer_on":true,"led_on":false,"imu_batch_interval_seconds":1,"gps_interval_seconds":5}` | 完整用户设置、`deviceSettingsVersion` 和 `status="applied"` 或 `"pending"` |
| `collars/setGeofence` | access token；调用者已绑定；更新项圈共享围栏 | `{"collar_id":"manual-collar-1","center":{"latitude":39.9,"longitude":116.4}}` | `{"collarId":"manual-collar-1","center":{"latitude":39.9,"longitude":116.4},"vertices":[],"boundaryType":"circle","radiusMeters":2000}` |
| `collars/findPet` | access token；调用者已绑定；设备须在线并确认启动 | `{"collar_id":"manual-collar-1","duration_seconds":30}` | `{"collarId":"manual-collar-1","commandId":"<command-id>","status":"started","durationSeconds":30,"startedAt":1731398400000}` |
| `collars/createShareInvite` | access token，设备须匹配，调用者已绑定 | `{"collar_id":"manual-collar-1","streams":["gps"]}` | `{"inviteToken":"<invite-token>","expiresIn":900}` |
| `collars/acceptShareInvite` | 另一用户的 access token，设备须匹配 | `{"invite_token":"<invite-token>"}` | `{"collarId":"manual-collar-1","bound":true,"streams":["gps"]}` |
| `collars/authorizeGpsPublisher` | 不校验用户 token；仅可信网关；`deviceId` 等于项圈 ID | `{"collar_id":"manual-collar-1"}` | `{"collarId":"manual-collar-1","authorized":true}` |
| `collars/authorizeImuPublisher` | 同上 | `{"collar_id":"manual-collar-1"}` | `{"collarId":"manual-collar-1","authorized":true}` |

`collar_id` 和 `telemetry_key_id` 使用合法设备标识符字符集；配对码为
1–256 字节。重复开通同一项圈会覆盖配对码和遥测公钥，但保留已有绑定。
测试脚本在开通请求信封中也会携带当前 access token；该接口不使用用户 token 授权，
真正的开通凭据是 `payload.provisioning_token`，由服务配置和 Router ACL 共同保护。
创建分享时 `streams` 可省略（默认 `gps` 和 `imu`），也可指定非空的
`gps`/`imu` 数组；邀请有效 900 秒且只能成功接受一次。publisher 授权依赖
Router ACL 限制调用者，不能仅凭 `deviceId` 作为身份认证。
寻宠持续时间可选 5–120 秒，默认 30 秒；服务等待设备确认启动最多 5 秒。
围栏中心必须由 APP 固定提交；不带 `vertices` 时使用中心点周围 2 公里的默认圆，
带 `vertices` 时服务验证其为 3–64 个顶点的凸多边形。

## 6. 手工正反向测试与断言

这些用例应使用独立测试账号。先按第 4.2 节注册并开通、绑定项圈；执行依赖该
绑定的用例后再解绑和注销。不要依赖固定 token、验证码、用户 ID 或时间戳。

### 6.1 逐接口验收矩阵

服务当前注册 **27 个 API 操作**（包含 3 个固定返回 `503` 的占位接口）。按此表逐项发起一次成功/预期结果请求和至少一个
失败请求；第 5 节给出了每个成功请求的 `payload` 与响应 `data`，第 4 节给出通用
信封。验证时同时检查 `code`、关键 `data` 字段以及状态是否改变，不要只看客户端
打印的 `PASS`。可成功接口分别执行成功和失败路径；占位接口核对固定 `503` 响应。
涉及设备、分享、围栏或遥测的行应按表中前置条件执行。

| API | 成功路径断言 | 失败路径断言 |
| --- | --- | --- |
| `auth/sendSms` | 分别测试 `scope=register` 和 `login`；debug 打印并返回 6 位 `smsCode`、`expiresIn=600`，配置阿里云时应收到短信 | 非法 scope 为 `400`；已注册手机号请求 register 为 `4517` |
| `auth/register` | 新手机号取 register 短信码注册；`isNewUser=true`、返回 access/refresh/sessionId 和 `collarSettings=[]` | 错误或已消费验证码分别为 `4510`/`4511`；并发注册竞争中手机号已被占用时为 `4517` |
| `auth/loginByPassword` | 使用注册账号登录；`isNewUser=false`，设备信息匹配且 `collarSettings` 含该用户所有已绑定项圈 | 错误密码为 `401`；锁定用例达到阈值后为 `4514`（用专用手机号，锁定 15 分钟） |
| `auth/loginBySms` | 先发送 login 短信再登录；`isNewUser=false` 且响应含用户项圈设置 | 错误/缺失验证码分别为 `4510`/`4511`；未注册手机号为 `401` |
| `auth/loginByOauth` | 无成功路径；当前固定返回 `503`、`data=null` | 发送空 payload，确认 `msg=login provider is not configured` |
| `auth/resetPassword` | 无成功路径；当前固定返回 `503`、`data=null` | 发送空 payload，确认 `msg=SMS provider is not configured` |
| `auth/bindPhone` | 无成功路径；当前固定返回 `503`、`data=null` | 发送空 payload，确认 `msg=SMS provider is not configured` |
| `auth/refresh` | 使用有效 refresh；access/refresh 均轮换且 `sessionId` 不变 | 用专用会话重放旧 refresh 为 `4403`，并确认该设备会话被吊销；设备不匹配为 `403` |
| `auth/logout` | 使用当前设备 access token；返回 `loggedOut=true` | 再用同一 access token 请求受保护接口为 `4403` |
| `auth/issueZenohCredential` | 管理服务配置 CA 并提交有效 CSR；检查 sessionId、topicPrefix 和证书 | 无 CA 为 `503`；无效 CSR 为 `400`；设备不匹配为 `403` |
| `users/listDevices` | 带 access token 查询；检查当前设备、排序和会话时间字段 | 无效/已吊销 token 为 `401`/`4403` |
| `users/listCollars` | 绑定前检查空数组，绑定后检查包含项圈 ID 且排序稳定 | 无效/已吊销 token 为 `401`/`4403` |
| `users/removeDevice` | 用设备 A 的 token 移除设备 B；B 后续 token 返回 `4403` | 移除自身为 `400`；不存在设备为 `404` |
| `users/telemetryHeartbeat` | 当前 APP token 续租；`sessionId` 匹配且 `onlineUntil` 约为当前时间 + 60 秒 | 无效或已吊销 token 为 `401`/`4403` |
| `collars/provisionCollar` | 配置正确开通口令、合法项圈 ID 和 Ed25519 公钥；`provisioned=true` | 口令错误为 `403`；非法公钥为 `400`；未配置开通口令为 `503` |
| `collars/bind` | 用正确配对码绑定；重复绑定仍成功 | 错误配对码为 `403`；未开通项圈为 `404` |
| `collars/unbind` | 当前用户解绑；返回 `bound=false` 且 `users/listCollars` 不再包含该项圈 | 重复解绑为 `404`；其他用户绑定不应被移除 |
| `collars/listUsers` | 已绑定用户查询；结果包含绑定用户且按 userId 排序 | 未绑定用户为 `403` |
| `collars/getSystemInfo` | 模拟器发布有效签名系统信息后查询；核对 `reportedAt` 和 `info` | 已绑定但尚无上报为 `404`；未绑定为 `403` |
| `collars/getCollarSettings` | 新绑定项圈读取蜂鸣器/LED 关闭、IMU/GPS 间隔均为 1 秒；登录响应含相同配置 | 未绑定为 `403` |
| `collars/setCollarSettings` | 分别只改一个字段和同时修改多字段；读取确认未提交字段保留；第二用户设置同一项圈后验证彼此隔离 | 间隔 0、61、浮点数、非法布尔值或空更新为 `400`；未绑定为 `403`；设备离线返回 `pending`，登录不自动下发，在线后显式重试返回 `applied` |
| `collars/setGeofence` | 分别设置仅中心的 2 公里圆和合法凸多边形；检查 `boundaryType`、中心和顶点 | 非法坐标/非凸多边形为 `400`；未绑定为 `403` |
| `collars/findPet` | 在线 `collar-simulator` 确认启动；响应状态、commandId、collarId 和时长匹配，结束后恢复调用用户保存的蜂鸣器/LED 状态 | 时长越界或非整数为 `400`；离线无确认 5 秒为 `504`；未绑定为 `403` |
| `collars/createShareInvite` | 绑定用户创建默认流及 `streams=["gps"]` 邀请；默认包含 gps/imu | 空流数组、未知流或错误类型为 `400`；未绑定为 `403` |
| `collars/acceptShareInvite` | 另一用户接受邀请；核对绑定和授予的 streams | 自己接受为 `400`；已用、过期或不存在的 token 为 `404` |
| `collars/authorizeGpsPublisher` | 可信网关在项圈已开通、有遥测身份且至少有一个绑定用户时调用；返回 `authorized=true` | deviceId 不匹配、无绑定用户为 `403`；未知项圈为 `404` |
| `collars/authorizeImuPublisher` | 在与 GPS 授权相同的前置条件下调用；返回 `authorized=true` | 与 GPS 授权相同；另确认 Router ACL 不允许普通 APP 调用 |

其中分享测试必须使用两个不同用户；设备移除、refresh 重放和登出会吊销会话，应使用
可丢弃测试设备。`authorize*Publisher` 是网关前置检查，不会验证每个遥测样本；仍须
验证项圈签名和 Router ACL。遥测 topic 不是 RPC，其端到端验收见第 7 节。

### 6.2 常见正反向场景

| 场景 / 操作 | 请求变化或前提 | 预期 |
| --- | --- | --- |
| 注册短信 | 未注册手机号，`scope=register` | debug `0`，`data.smsCode` 为 6 位数字，终端也打印验证码，`expiresIn=600`；配置阿里云时应收到短信 |
| 已注册手机号 | 再次请求 `scope=register` | `4517` |
| 短信验证码错误 / 已消费 | 使用错误验证码 / 再用已成功消费的验证码 | 分别 `4510` / `4511`；验证码仅可使用一次 |
| 密码登录错误 | 使用注册账号和错误密码 | 前 4 次 `401`，第 5 次及锁定期间 `4514`；锁定 15 分钟 |
| 短信登录 | `sendSms` 使用 `scope=login`，将返回的验证码交给 `loginBySms` | `0`，`isNewUser=false`；同设备旧会话被替换 |
| 会话上限 | 同一账号用 5 个不同设备登录，再用第 6 个新设备登录 | `4512`，`data.sessions` 包含已有会话；已登录设备重新登录不受上限限制。脚本先登录主设备和第二设备，再登录设备 3–5，最后用设备 6 验证上限 |
| 移除设备 | 第二设备先登录；第一设备 `removeDevice` 传第二设备 ID | `0`；被移除设备 token 后续返回 `4403` |
| 移除自身 / 不存在设备 | `device_id` 为当前设备 / 不存在的设备 | 分别 `400` / `404` |
| refresh 轮换 | 使用有效 refresh，保存新旧 token | `0`，新旧 token 不同、`sessionId` 不变；再次使用旧 refresh 返回 `4403` 并吊销会话，须重新登录 |
| 配对码错误 / 未开通 | 对已开通项圈使用错误配对码 / 对不存在项圈绑定 | 分别 `403` / `404` |
| 重复解绑 | 对已解绑项圈再次 `unbind` | `404` |
| 绑定后的发布授权 | 用 `DEVICE_ID="$COLLAR_ID"` 调用两个 `authorize*Publisher`，payload 为对应 `collar_id` | 两者均 `0`、`authorized=true`；设备 ID 不一致或没有绑定用户为 `403` |
| 分享邀请 | 用户 A 已绑定，创建 `streams=["gps"]`；用户 B 登录并接受 | 创建和接受均 `0`，B 响应 `streams=["gps"]`；B 再次接受同一邀请为 `404`；A 接受自己的邀请为 `400` |
| 一键寻宠 | 已绑定用户触发 `collars/findPet`，项圈在线 | 响应 `status="started"`；项圈同时启动闪灯和蜂鸣器，包含匹配的 `commandId` 和时长 |
| 寻宠参数越界 | `duration_seconds` 为 4、121、非整数 | `400`，`msg="invalid duration_seconds"`；省略时使用 30 秒 |
| 未绑定用户寻宠 | 用未绑定用户 token 对已开通项圈调用 `findPet` | `403`，`msg="collar is not bound to this user"`，不向项圈发送命令 |
| 项圈离线/拒绝寻宠 | 不启动项圈 queryable，或设备回复 `status="rejected"` | 离线或 5 秒无确认返回 `504`；设备拒绝或确认字段错误返回 `502`，不可报告启动成功 |
| 设置默认电子围栏 | 已绑定用户提交合法 `center`，省略 `vertices` | 成功返回 `boundaryType="circle"`、`radiusMeters=2000`；该 APP 中心作为固定圆心 |
| 设置多边形围栏 | 提交合法中心和按顺/逆时针排列的凸多边形顶点 | 成功返回 `boundaryType="polygon"`；非凸、重复顶点、少于 3 或多于 64 个顶点返回 `400` |
| 未绑定用户设置围栏 | 使用未绑定用户 token 调用 `setGeofence` | `403`，不得覆盖共享围栏 |
| 在线心跳 | 已登录设备调用 `users/telemetryHeartbeat`，payload `{}` | `0`，响应 `sessionId` 与当前登录相同，`onlineUntil` 约为当前时间加 60 秒 |
| 证书签发 | 配置客户端签发 CA，用有效 access、匹配设备和合法 PEM CSR 调用 | `0`，返回证书、会话 ID、过期时间和 topic 前缀；未配置 CA 返回 `503` |
| 请求信封 | 修改 `v`、`reqId`、`ts`、设备 ID、payload 类型，或请求超过 16 KB | 各自返回 `400`；时间差超过 120 秒返回 `ts is outside the allowed window` |
| 未知操作 | 对已声明域调用 `auth/unknownOperation` | `404`，`msg="unknown operation"` |
| 未登录 / 已注销 | 不带 token / 注销后使用原 access | 分别 `401` / `4403` |
| 占位功能 | `loginByOauth`、`resetPassword`、`bindPhone` | 均为 `503`，不代表业务功能已实现 |

自动脚本还会用 `filler` 字段填充超长请求，以验证 16 KB 限制；`filler` 不是任何
业务接口字段。`loginByOauth`、`resetPassword` 和 `bindPhone` 的脚本参数同样只是占位
测试数据，服务不解析、不承诺其业务语义，接口当前固定返回 `503`。

证书和发布授权可用第 4.2 节的 `api_call` 按第 5 节 payload 构造。
分享邀请的 `streams` 为数组；需要显式指定时，请按第 4.1 节自行构造 JSON，
使用 `z_get` 调用（或省略 `streams` 测试默认值）。
分享需要两个不同用户；不要用同一用户的两台设备代替。测试 publisher 授权时
先保存原 `DEVICE_ID`，结束后恢复，以免后续 token 的设备校验失败。

例如，`api_call` 不能编码数组时，可在同一 Bash 会话直接调用 `z_get`。以下例子
测试只授予 GPS 的分享邀请；改用第 5 节中其他 `payload` 即可测试其他复杂请求：

```sh
NOW="$(date +%s%3N)"
REQ_ID="manual-${NOW}"
PAYLOAD_JSON="{\"collar_id\":\"${COLLAR_ID}\",\"streams\":[\"gps\"]}"
REQUEST_JSON="$(
  python3 - "$NOW" "$REQ_ID" "$DEVICE_ID" "$ACCESS_TOKEN" "$PAYLOAD_JSON" <<'PY'
import json
import sys

now, req_id, device_id, token, payload = sys.argv[1:]
request = {
    "v": 2,
    "reqId": req_id,
    "deviceId": device_id,
    "token": token,
    "ts": int(now),
    "payload": json.loads(payload),
}
print(json.dumps(request, separators=(",", ":")))
PY
)"
"$Z_GET" --connect "$ZENOH_ENDPOINT" \
  --selector "petpal/$TENANT/api/v1/collars/createShareInvite" \
  --payload "$REQUEST_JSON" --timeout 10000
```

`z_get` 输出的响应中应有 `code=0` 和 `data.expiresIn=900`。该请求会创建真实测试
邀请；用另一测试用户接受后再继续验证单次使用和权限。

常见业务码：`0` 成功、`400` 参数非法、`401` 凭证无效、`403` 无权限、
`404` 操作或记录不存在、`429` 短信锁定、`4403` 会话吊销、
`4510` 验证码错误、`4511` 验证码缺失/过期、`4512` 设备上限、
`4514` 密码锁定、`4517` 已注册、`500` 内部/Redis 错误、
`502` 短信供应商错误、`503` 未配置或未实现。
短信锁定及详细 `msg` 见 [API 错误码](./zenoh-rpc-api.md#5-错误码)。

## 7. 遥测和安全边界验证

### 7.1 运行项圈和行为模拟器

在独立测试 tenant 启动第 2 节的 Redis、Router 和统一 `pet_collar_service`。
以下过程还需 `z_sub` 和 `z_get`（Zenoh 1.10 示例程序）。
管理服务和模拟器必须使用同一 Router 和 tenant；示例使用本地明文 TCP，
不可用于生产。先在测试终端 `source ./scripts/test-apis.sh`，配置 `TENANT`、
`ZENOH_ENDPOINT`、`Z_GET`、测试账号密码和 `PROVISIONING_TOKEN`，并调用
`api_login_password`。按第 4.2 节初始化账号；以下调用均使用该终端。

1. 在私有目录生成一次性测试密钥。不要把私钥放进仓库，命令会拒绝覆盖已有文件。
   将输出的**公钥**复制到 `PUBKEY`；私钥不会输出。

   ```sh
   SIM_DIR="$(mktemp -d)"
   printf '模拟器目录: %s\n' "$SIM_DIR"
   cargo run --locked --bin collar-simulator -- --generate-key "$SIM_DIR/collar.key"
   PUBKEY='<上一步输出的公钥hex>'
   ```

2. 先从登录响应保存用户和会话 ID，再开通并绑定新测试项圈，建立在线租约。
   不要对现有真实项圈执行开通，否则会覆盖其配对码和公钥。

   ```sh
   USER_ID="$(response_field data.user.userId)"
   SESSION_ID="$(response_field data.sessionId)"
   api_call collars provisionCollar 0 "$DEVICE_ID" "" \
     provisioning_token "$PROVISIONING_TOKEN" collar_id "$COLLAR_ID" \
     pairing_code "$PAIRING_CODE" telemetry_key_id "sim-key-${RUN_ID}" \
     telemetry_public_key "$PUBKEY"
   api_call collars bind 0 "$DEVICE_ID" "$ACCESS_TOKEN" \
     collar_id "$COLLAR_ID" pairing_code "$PAIRING_CODE"
   api_call users telemetryHeartbeat 0 "$DEVICE_ID" "$ACCESS_TOKEN"
   printf 'user=%s session=%s collar=%s keyId=sim-key-%s\n' \
     "$USER_ID" "$SESSION_ID" "$COLLAR_ID" "$RUN_ID"
   ```

3. 另开终端启动独立的**行为处理服务**（当前使用启发式原型，尚非训练验证后的模型）。
   它缓存每个项圈的 IMU 样本，以 100 帧窗口、每秒滑动 1 次，尝试输出 `feeding`（进食）、
   `jumping`（跳跃）、`playing`（逗猫）、`scratching`（磨爪）、`rolling`（打滚）、
   `running`（奔跑）、`licking_fur`（舔毛）、`lying_down`（趴着）、`sleeping`（睡觉）、
   `standing`（站着）、`walking`（走路）、`sitting`（坐着）；无法判断时输出
   `unknown`（未知）。所有结果都标记 `simulated: true`：

   ```sh
   cargo run --locked --bin behavior-processor -- \
     --endpoint tcp/127.0.0.1:17447 --tenant demo
   ```

4. 再开终端，用第 2 步输出的实际 ID 订阅会话 topic。不同终端不会自动共享
   shell 变量，须替换尖括号中的值。确保订阅已建立，再发送样本。

   ```sh
   export Z_SUB="$HOME/src/zenoh-1.10.2/target/release/examples/z_sub"
   "$Z_SUB" --mode client --connect tcp/127.0.0.1:17447 \
     --key 'petpal/demo/users/<userId>/sessions/<sessionId>/telemetry/<collarId>/**'
   ```

5. 在第一终端运行模拟项圈。第一次运行会创建持久序号文件；系统信息按
   `--interval-ms` 发布，GPS 默认每秒发布一次，可由 APP 设置为 1–60 秒。IMU 默认每
   20 毫秒采一帧（50 Hz），每秒把采样帧合并到一个签名信封上报，并随机切换行为场景。
   模拟器声明 `setCollarSettings` queryable，以接收用户显式应用的完整配置；登录时不会自动改动设备。
   系统信息使用 `batteryPercent=100`、`firmwareVersion="1.0.0"` 示例值。服务端验签后逐帧送入
   `behavior-processor` 计算识别结果。可用 `--imu-interval-ms`
   调整采样频率（最小 10 毫秒）。`--count 5` 在发布 5 个 GPS 样本后退出，并在退出时发送
   未满 1 秒的最后一个 IMU 批次；省略则持续运行。可用 `--manufacturer`、
   `--flash-bytes` 修改模拟参数。

   ```sh
   cargo run --locked --bin collar-simulator -- \
     --endpoint "$ZENOH_ENDPOINT" --tenant "$TENANT" \
     --collar-id "$COLLAR_ID" --key-id "sim-key-${RUN_ID}" \
     --key-file "$SIM_DIR/collar.key" --sequence-file "$SIM_DIR/collar.seq" \
     --interval-ms 1000 --imu-interval-ms 20 \
     --manufacturer 'Test manufacturer' --flash-bytes 4194304 \
     --count 5
   ```

   调用 `collars/setGeofence` 时，为了验证越界告警，可把示例项圈当前位置
   `(39.9,116.4)` 设为圆心以确认不告警；再把中心改为 `(0,0)`，下一个 GPS 样本应在
   APP 的 `geofence` topic 产生一次 `outside_geofence` 告警。持续越界时不重复告警；
   将中心设回当前位置会让下一个样本回到围栏内并重新布防。测试时应省略模拟器
   `--count` 参数以保持控制台、GPS 和 IMU 发布器持续运行。

   订阅端应收到 `gps` 和 `behavior`，行为数据带 `simulated: true`，不应收到原始
   `imu`；边界外时还应收到 `geofence` 告警。遥测服务根据项圈绑定关系、GPS 分享权限
   和有效在线租约，将 GPS 与越界告警分发给所有符合条件的在线 APP；行为结果仍依据
   `imu` 分享权限路由。测试超过 60 秒时，在第一终端重新
   调用 `users/telemetryHeartbeat`。随后查询最新系统信息：

   ```sh
   api_call collars getSystemInfo 0 "$DEVICE_ID" "$ACCESS_TOKEN" collar_id "$COLLAR_ID"
   ```

   返回应包含启动时间、运行秒数、flash 字节数、厂家和上报时间。未绑定用户
   返回 `403`，无系统信息时返回 `404`。发布日志只表示本地提交，不表示服务
   已接收或 APP 已收到。

**序号和密钥安全**：同一项圈和 key ID 重启时必须复用原序号文件；丢失或回滚
序号文件会触发服务端重放保护。序号文件会被独占锁定，不能同时运行两个模拟器
使用同一文件。不要让不同序号文件并发模拟同一项圈和 key ID。私钥文件必须只允许
当前用户访问；不要分享密钥或日志。模拟器仅支持本地 TCP，生产部署须另行配置
TLS、认证和 Router ACL。

### 7.2 安全边界和异常测试

GPS/IMU/系统信息是 pub/sub topic，不是 RPC，也没有逐条业务响应。自动 API
集成客户端**不**验证遥测端到端交付、证书实际连接、Router ACL 或邀请分享。

完整部署验收应具备独立测试项圈 Ed25519 密钥对、已登记的公钥、可信网关、
已绑定用户、在线心跳和下行订阅客户端；生产环境还需配置 Router mTLS 和 ACL：

1. 启动统一服务，开通项圈并绑定用户，分别调用两个 publisher 授权接口。
2. APP 使用 `users/telemetryHeartbeat` 建立在线租约；按需通过
   `auth/issueZenohCredential` 申请证书并订阅当前会话的精确 topic。
3. 按 [遥测协议和签名格式](./zenoh-rpc-api.md#collarsreportgps-topic)
   用**对应私钥**发布合法样本；验证 GPS 和行为结果的 `collarId`、`stream`、
   `seq` 和数据，以及系统信息查询结果。原始 IMU 不应下发。
4. 使用错误签名、错误 key ID、非法字段或重复/递减序号分别发布；检查遥测服务
   日志并确认下行未收到该样本。还应验证无在线租约、无流权限和其他会话不能收到。
5. 停止行为算法订阅者后确认遥测服务仍可验证并发布 IMU；但没有算法输出时不会
   下发行为结果，GPS 仍可转发。服务不自动重试已接受的 IMU 序号。
6. 在配置了 mTLS/ACL 的 Router 上分别测试有效证书、无效证书和越权 topic，
   验证拒绝连接或拒绝操作；证书签发成功本身不证明 Router 已实施 ACL。
7. 运行持续模式的项圈模拟器后调用 `collars/findPet`；确认 API 只有在模拟器返回
   匹配的启动确认后成功。设备固件必须实现同一控制 queryable，并在真实闪灯和蜂鸣器
   启动后确认；模拟器日志不代表真实硬件动作。
8. 设置围栏后发布连续 GPS，检查只有进入围栏外时产生一次告警，返回围栏内后再次
   越界会重新告警；确认未配置中心时不执行判断，告警仅到在线且具有 GPS 权限的会话。

遥测为尽力投递且不保存历史；阴性测试须设置明确的观测窗口并查看服务日志，
不能仅将一次未收到样本视为安全验证通过。

## 8. 常见问题与清理

| 现象 | 排查 |
| --- | --- |
| 管理服务持续重连 Redis | 检查 Redis 进程、端口、URL、认证，以及 CLI/环境变量是否覆盖 YAML。 |
| `z_get` 超时或无响应 | 检查 Router 和管理服务日志、endpoint、tenant、精确 key、ACL；没有 queryable 时不一定收到 `404`。 |
| `z_get` 未找到 | 安装对应版本示例或设置脚本的 `Z_GET`；`zenohd` 不等于 `z_get`。 |
| `4517` | 测试手机号已注册，换用未注册手机号。 |
| `503` 开通不可用 | 管理服务未配置开通口令；token 不匹配则为 `403`。 |
| 自动测试取不到 `smsCode` | 只有 debug 响应包含验证码；release 应从实际短信中手工读取，且不在服务日志输出验证码。 |
| `auth/sendSms` 返回 `502` | 响应 `msg` 包含阿里云 HTTP 状态和 `Code`；本地 debug 测试请移除当前服务配置中的整个 `sms` 块、清除四个 `ALIBABA_CLOUD_`/`ALIYUN_SMS_` 环境变量并重启，实际发送则按 `Code` 检查密钥、签名、模板、手机号和余额。 |
| `401` / `4403` | 检查是否已刷新、重新登录或注销，以及是否使用了最新 token。 |
| 证书 `503` | 检查管理服务是否同时配置签发 CA 证书和私钥。 |

测试完成后仅停止**自己启动的**前台进程（各终端 `Ctrl+C`），并处理专用测试
环境。测试会留下用户、项圈和吊销标记；不要对共享 Redis 执行 `FLUSHDB`、
`FLUSHALL` 或不加核实地批量删除 key。优先销毁专用的临时实例/数据库，或仅
删除确认属于本次测试的数据。不要提交、分享测试口令、token、验证码、证书
私钥或未脱敏日志。
