# 使用 Zenoh 官方 z_get 示例测试所有 API

自动化测试已整理为 [scripts/test-apis.sh](./scripts/test-apis.sh)，建议直接按
脚本的 `--help` 和 README 中的启动说明运行。也可以通过新增的 `api-test`
Cargo binary 以命令行参数运行完整测试：

```sh
cargo run --bin api-test -- \
  --endpoint tcp/127.0.0.1:7447 \
  --tenant demo \
  --phone +8613800138000 \
  --password 'test-password-123' \
  --provisioning-token "$COLLAR_PROVISIONING_TOKEN"
```

手机号必须未注册；服务端需已配置同一个 provisioning token。此命令会调用
`auth/sendSms` 获取注册验证码，并创建、解绑测试项圈和测试会话。运行
`cargo run --bin api-test -- --help` 查看参数说明。
下方保留逐项手动调试参考。

本文使用本机 Zenoh 官方 examples 编译出的 `z_get` 命令发送 Zenoh Query，
不是使用 HTTP 或 curl。`z_get` 会按 API key 发送一次查询，并打印服务端回复。

## 1. 启动依赖和服务

先启动 Redis、Zenoh Router 和本项目服务。以下默认 Router 地址为
`tcp/127.0.0.1:7447`、租户为 `demo`；如有不同，请修改后面的环境变量。

确认本机存在官方示例工具：

```sh
test -x /home/wayne/esp32/zenoh/target/release/examples/z_get
/home/wayne/esp32/zenoh/target/release/examples/z_get --help
```
配置测试变量：

```sh
export Z_GET=/home/wayne/esp32/zenoh/target/release/examples/z_get
export ZENOH_ENDPOINT=tcp/39.106.26.172:7447
export TENANT=demo
export REDIS_URL='redis://default:YourSecurePasswordHere@127.0.0.1:6379/'
export DEVICE_ID=api-test-device-1
export DEVICE_ID_2=api-test-device-2
export PHONE=+8613800138000
export PASSWORD='Test_password_2026'
```

`PHONE` 必须是尚未注册的号码。测试成功后，按命令输出手动复制 access /
refresh token 到对应变量。不要把生产账号或生产 token 用于测试。

## 2. 定义发送命令

此函数使用 Python 标准库生成合法 JSON（包括当前毫秒时间戳），再调用
Zenoh 官方 `z_get` 示例。调用格式为：
`api <domain> <operation> <payload-json> [device-id] [access-token]`。

```sh
api() {
  local domain="$1"
  local operation="$2"
  local payload="$3"
  local device_id="${4:-$DEVICE_ID}"
  local access_token="${5:-}"
  local now req_id envelope
  if [[ ( "$domain" == "auth" && "$operation" == "listSessions" ) ||
        ( "$domain" == "devices" && "$operation" == "list" ) ||
        ( "$domain" == "collars" && ( "$operation" == "list" || "$operation" == "listUsers" ) ) ]]; then
    device_id=""
    access_token="${4:-}"
  fi

  now=$(date +%s%3N)
  req_id="api_test-${now}"
  envelope=$(python3 - "$now" "$req_id" "$device_id" "$access_token" "$payload" <<'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

  echo $envelope &&
  "$Z_GET" \
    --connect "$ZENOH_ENDPOINT" \
    --selector "petpal/$TENANT/api/v1/$domain/$operation" \
    --payload "$envelope" \
    --timeout 10000
}
```

每次调用都会生成新的 reqId 和 ts。检查输出中的响应 envelope `code`、
`msg`、`data`；成功响应的 `code` 为 `0`。若命令超时，检查 Router、
服务进程和服务端日志。

## 3. 注册与登录

使用 debug 构建时，先调用 `auth/sendSms` 获取验证码（保存响应中的
`data.smsCode`，有效期为 10 分钟）。当前为开发/测试实现，不会真的发送
短信；release 构建在未配置短信提供方时返回 `503`。生产环境禁止在响应中
返回验证码。

### `auth/register`

预期：`code=0`，响应包含 access 和 refresh token。

```sh
export PHONE=+8613810451929
export PASSWORD='hihihiyou'
api auth sendSms "{\"phone\":\"$PHONE\",\"scope\":\"register\"}"
```

从响应的 `data.smsCode` 复制验证码后注册（将下面的 `验证码` 替换为实际值）：

```sh
api auth register "{\"phone\":\"$PHONE\",\"sms_code\":\"验证码\",\"password\":\"$PASSWORD\",\"device_name\":\"API test phone\",\"device_model\":\"Test model\",\"platform\":\"android\",\"os_ver\":\"test\"}"
```

### `auth/loginByPassword`

预期：正确密码返回 `code=0`；错误密码返回 `401`。不要对同一测试账号
连续输错五次，否则账号会锁定 15 分钟。

要单独测试登录，先使用一个已注册的测试账号，并按上文定义好 `api` 函数和
`PHONE`、`PASSWORD` 等变量，然后执行：

```sh
api auth loginByPassword "{\"phone\":\"$PHONE\",\"password\":\"$PASSWORD\",\"device_name\":\"API test phone\",\"device_model\":\"Test model\",\"platform\":\"android\",\"os_ver\":\"test\"}"
```

API key 为 `petpal/$TENANT/api/v1/auth/loginByPassword`。请求 envelope 会由
`api` 函数自动生成，包含当前时间戳和合法 `reqId`。密码登录需要 `deviceId`；
`auth/listSessions`、`devices/list`、`collars/list` 和 `collars/listUsers`
从 token 中识别当前用户，因此请求不需要 `deviceId`。成功时响应
`code` 应为 `0`，`data` 中会返回 `access`、`refresh` 和用户信息。若想检查
错误密码处理，可对专用测试账号执行一次以下命令，预期 `code=401`：

```sh
api auth loginByPassword "{\"phone\":\"$PHONE\",\"password\":\"wrong-password\",\"device_name\":\"API test phone\",\"device_model\":\"Test model\",\"platform\":\"android\",\"os_ver\":\"test\"}"
```

密码登录不需要短信验证码，也不需要在 envelope 顶层传入 `token`。

从成功响应复制 token：

```sh
export ACCESS_TOKEN='70232f99e585409aa32c3ccebcb903b4'
export REFRESH_TOKEN='b72042a1e8354c7a81d5fb4cbab02ce9'
```

使用第二台设备创建第二个 session，稍后用于 `revokeSession`：

```sh
api auth loginByPassword "{\"phone\":\"$PHONE\",\"password\":\"$PASSWORD\",\"device_name\":\"API test phone 2\",\"device_model\":\"Test model\",\"platform\":\"android\",\"os_ver\":\"test\"}" "$DEVICE_ID_2"
export ACCESS_TOKEN_2='粘贴第二次登录响应中的 access'
```

### `auth/loginBySms`

debug 构建下先使用 `auth/sendSms` 获取 `login` scope 验证码，再调用登录接口。
验证码一次有效；成功返回 `code=0` 和 access / refresh token。release 构建
尚未配置短信登录提供方时返回 `503`。

```sh
api auth sendSms "{\"phone\":\"$PHONE\",\"scope\":\"login\"}"
```

将响应中的 `data.smsCode` 复制为验证码后登录：

```sh
api auth loginBySms "{\"phone\":\"$PHONE\",\"sms_code\":\"验证码\",\"device_name\":\"API test phone\",\"device_model\":\"Test model\",\"platform\":\"android\",\"os_ver\":\"test\"}"
```

### `auth/loginByOauth`

预期：当前未配置 OAuth 提供方，返回 `503`。

```sh
api auth loginByOauth "{\"provider\":\"example\",\"code\":\"test-code\",\"device_name\":\"API test phone\",\"device_model\":\"Test model\",\"platform\":\"android\",\"os_ver\":\"test\"}"
```

## 4. 短信和账号接口

debug 构建下 `sendSms` 返回 `code=0`，并在 `data.smsCode` 返回随机六位验证码
（开发/测试用途，不会真的发送短信）；release 构建尚未接入短信提供方时
返回 `503`。短信登录、密码重置和手机号绑定也尚未接入提供方，release 构建预期返回 `503`。

### `auth/sendSms`

```sh
api auth sendSms "{\"phone\":\"$PHONE\",\"scope\":\"register\"}"
```

### `auth/resetPassword`

```sh
api auth resetPassword "{\"phone\":\"$PHONE\",\"sms_code\":\"123456\",\"password\":\"$PASSWORD\"}"
```

### `auth/bindPhone`

```sh
api auth bindPhone "{\"phone\":\"$PHONE\",\"sms_code\":\"123456\"}"
```

## 5. 会话接口

### `auth/refresh`

预期：返回 `code=0` 和新 access / refresh token。旧 refresh token 被轮换，
请把新 token 复制到变量，后续使用新值。

```sh
api auth refresh "{\"refresh\":\"$REFRESH_TOKEN\"}"
```

```sh
export ACCESS_TOKEN='粘贴刷新响应中的 access'
export REFRESH_TOKEN='粘贴刷新响应中的 refresh'
```

### `auth/listSessions`

预期：返回 `code=0` 和当前用户的设备会话列表。

```sh
api auth listSessions '{}' "$ACCESS_TOKEN"
```

### `auth/revokeSession`

预期：使用主设备的 token 撤销第二台设备，返回 `code=0`。尝试撤销当前
设备应返回 `400`；撤销不存在的设备应返回 `404`。

```sh
api auth revokeSession "{\"device_id\":\"$DEVICE_ID_2\"}" "$DEVICE_ID" "$ACCESS_TOKEN"
```

## 6. APP 设备信息接口

`devices/list` 查询当前用户的 APP 登录设备和会话信息，与项圈绑定列表分开。
预期：返回 `code=0`，`data.sessions` 包含设备 ID、设备名称/型号、平台、
登录时间、最近活动时间及当前设备标记。

```sh
api devices list '{}' "$ACCESS_TOKEN"
```

## 7. 项圈绑定接口

项圈操作使用独立的 `collars` domain；之前使用 `devices` domain 的项圈 key
已迁移，不再兼容。

设置项圈 ID 和配对码；`PROVISIONING_TOKEN` 必须与运行服务时配置的
`COLLAR_PROVISIONING_TOKEN` 相同：

```sh
export COLLAR_ID=api-test-collar-1
export PAIRING_CODE=pair-test-123456
export PROVISIONING_TOKEN='填入服务端 COLLAR_PROVISIONING_TOKEN 的值'
```

### `collars/provisionCollar`

预期：配置 provisioning token 后返回 `code=0`；服务端未配置时返回
`503`，提供了错误 token 时返回 `403`。

```sh
api collars provisionCollar "{\"provisioning_token\":\"$PROVISIONING_TOKEN\",\"collar_id\":\"$COLLAR_ID\",\"pairing_code\":\"$PAIRING_CODE\"}" "$DEVICE_ID" "$ACCESS_TOKEN"
```

### `collars/bind`

预期：返回 `code=0`，项圈与当前用户绑定。

```sh
api collars bind "{\"collar_id\":\"$COLLAR_ID\",\"pairing_code\":\"$PAIRING_CODE\"}" "$DEVICE_ID" "$ACCESS_TOKEN"
```

### `collars/list`

预期：只需顶层 `token` 和空 payload，不需要 `DEVICE_ID`。返回 `code=0`，
`data.collars` 中包含刚绑定的项圈 ID。当前存储尚无
名称、型号、固件版本或在线状态字段，因此该接口只返回项圈 ID。

```sh
api collars list '{}' "$ACCESS_TOKEN"
```

### `collars/listUsers`

预期：返回 `code=0`，`data.users` 中包含当前用户 ID；查询未绑定的项圈
应返回 `403`。此查询只需顶层 `token` 和 `collar_id`，不需要 `DEVICE_ID`。

```sh
api collars listUsers "{\"collar_id\":\"$COLLAR_ID\"}" "$ACCESS_TOKEN"
```

### `collars/unbind`

预期：返回 `code=0`；对相同项圈再次解绑应返回 `404`。

```sh
api collars unbind "{\"collar_id\":\"$COLLAR_ID\"}" "$DEVICE_ID" "$ACCESS_TOKEN"
```

## 8. 注销与额外验证

### `auth/logout`

完成上面的登录态和设备 API 测试后再执行。预期：返回 `code=0`；该 token
之后再使用会返回 `4403`。

```sh
api auth logout '{}' "$DEVICE_ID" "$ACCESS_TOKEN"
```

- 使用第五个不同的 `deviceId` 登录后，再用第六个新设备登录，应返回
  `4512` 并在 `data.sessions` 中附带现有会话。
- 把请求中的 `ts` 改为两分钟前，应返回 `400`。
- 把 selector 改成未知 API key，应返回 `404`。
- 复用已轮换的 refresh token 会触发 token 重放保护并撤销关联 session；
  建议在该账号测试的最后执行。
- 注册、登录、设备绑定和会话撤销会修改 Redis 中的数据，请使用独立的
  测试租户/账号，避免影响真实数据。