# Zenoh 替代 HTTP 接口 —— App 与服务端交互约束

> 本文是 App 端与服务端的**协议契约**：双方任何一方违反本文条款，按联调缺陷处理。
> 配套阅读：`docs/Zenoh替代HTTP接口-设计实现.md`（架构与工具类设计）
> 状态字段说明：`【必须】`=强制；`【应当】`=强烈建议，偏离需评审；`【可以】`=可选。
> 日期：2026-11-07 · 版本 v2.0（对应信封协议 v2）

---

## 1. 传输与会话约束

| # | 约束 | 级别 |
|---|---|---|
| 1.1 | App 以 **client 模式**连接 router，locator 一律 `tls/` 前缀；`tcp/` 仅允许出现在 debug 构建连接本机调试 router（`tcp/10.0.2.2:7447` 等） | 【必须】 |
| 1.2 | 服务端各业务实例以 **peer 模式**接入；对外宣告的 API 域 key 格式见 §2 | 【必须】 |
| 1.3 | App 心跳沿用现有链路层 20s 周期、10s 超时、1s→30s 指数退避重连（`ZenohWebSocketTransport` 同参数），协议层不再叠加应用层心跳 | 【必须】 |
| 1.4 | 链路状态进入非 connected 时，所有 pending RPC **立即**失败（`ApiLinkDown` / `ApiNoResponder`），不等待恢复；业务 UI 必须可区分"网络不可用"与"服务不可用" | 【必须】 |
| 1.5 | 服务端 queryable 实例**常驻声明**；任何时刻一个 API key 至多一个权威 queryable（灰度/发布窗口除外，且窗口 ≤60s） | 【必须】 |
| 1.6 | 服务端下线/发布：先 undeclare → 排空存量请求（≤5s）→ 退出；**禁止直接杀进程**（App 侧会表现为超时重试风暴） | 【必须】 |
| 1.7 | 实时推送类通知（App 退后台/被杀仍需触达的告警）**不依赖 zenoh 长连接**，必须并行走 APNs / 华为 Push / FCM；zenoh 推送仅保证前台与短后台场景 | 【必须】 |
| 1.8 | 同一 userId 支持**多端同时登录与使用**（活跃会话上限 5，以 deviceId 为键互相独立）；达到上限时新登录拒绝（`4512`），**不做自动互踢**，详见 §6.4 | 【必须】 |
| 1.9 | 公网入口至少部署 **2 台 zenohd router 组 mesh**（互为备份）；App `connect.endpoints` 配置**有序主备 locator 列表**，连接失败自动切下一个（消除单点，见设计文档 §1.4） | 【必须】 |
| 1.10 | router 滚动升级/重启窗口内 App 侧表现为 `-1`（无响应者）——属**预期内故障**，幂等读重试即恢复；升级节奏须保证任一时刻至少一台 router 可达 | 【应当】 |
| 1.11 | 会话失效（登出 / `4403` 被剔除）时 App 必须同步清理本地状态：**退订全部业务订阅**、停止 `evt/` 上报、清空 pending RPC 队列——禁止"无凭据仍收推/仍上报"的半死状态 | 【必须】 |

## 2. Key Expression 约束

统一格式 `petpal/{tenant}/{scope}/{...}`，各段字符集 `[a-z0-9_-]`，禁止空段。

| # | 约束 | 级别 |
|---|---|---|
| 2.1 | API 域：`petpal/{tenant}/api/v1/{domain}/{op}`；`domain` ∈ 服务端注册域清单（pets / devices / auth / files / family / chat / report …），新增域需登记本文档附录 A 并双端同步版本号 | 【必须】 |
| 2.2 | `get()` 一律精确 key，**App 侧禁止在 API key 中使用 `*`/`**`**（复用 `ZenohKeyExprs.validatePublish` 同源校验） | 【必须】 |
| 2.3 | 服务端 queryable 声明粒度为 `petpal/{tenant}/api/v1/{domain}/**`，禁止更宽（如 `api/**`）——控制路由扇出（Book《Key Expressions》最佳实践） | 【必须】 |
| 2.4 | pub/sub 域沿用 v1 规范（status/location/alarm/behavior/cmd/ota），新增 `evt/{type}`（App 上报事件）；发布侧一律精确 key | 【必须】 |
| 2.5 | key 中禁止出现 PII（昵称、手机号、邮箱）；资源标识使用服务端分配短码 | 【必须】 |
| 2.6 | key 段数与语义不可重载：禁止把参数编码进 key（如 `pets/getInfo/p123`——petId 必须进 payload）；key 是"地址"不是"参数表" | 【必须】 |
| 2.7 | 主版本号进 key（`api/v1`）；v2 上线后 v1 保持 ≥2 个 App 版本周期并行，下线前公告 | 【必须】 |

## 3. 信封协议约束（v2）

### 3.1 请求信封（App get payload，UTF-8 JSON）

```json
{
  "v": 2,
  "reqId": "r42-1699365120000",
  "token": "eyJ...",
  "deviceId": "ios-3f2a",
  "ts": 1699365120000,
  "payload": { }
}
```

| 字段 | 类型 | 必填 | 约束 |
|---|---|---|---|
| `v` | int | 是 | 恒为 2；服务端遇到未知 v 回 `code=400` |
| `reqId` | string | 是 | `^\w+-\d{13}$`；同一逻辑操作重试**复用同一 reqId**；服务端幂等窗口 5min |
| `token` | string | 条件 | 除 `auth/loginBy*`、`auth/sendSms`、`auth/refresh` 外必填 |
| `deviceId` | string | 是 | 首次启动生成的 UUID；服务端校验与 refresh 绑定关系 |
| `ts` | int64 | 是 | Unix 毫秒；服务端拒绝偏离当前时间 ±120s 的请求（`code=400`） |
| `payload` | object | 是 | 业务参数；**snake_case 命名**（与现有线协议一致）；单信封序列化后 ≤16KB |

### 3.2 响应信封（服务端 reply payload）

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

| 字段 | 约束 |
|---|---|
| `v` | 恒为 2 |
| `reqId` | **必须与请求一致**；App 丢弃不一致 reply 并计数上报（拓扑异常信号） |
| `code` | 错误码，§4 |
| `msg` | 面向开发者的英文短描述；**用户文案由 App 端 l10n 生成**，服务端 msg 不直接展示 |
| `data` | 成功时的业务数据；分页统一 `{list, total, page, pageSize}`，pageSize ≤100 |
| `ts` | 服务端时间戳，App 用于时钟校准（偏差 >60s 提示用户校时——ts 窗口校验依赖它） |

### 3.3 兼容性规则

| # | 约束 | 级别 |
|---|---|---|
| 3.3.1 | 双端对未知字段一律忽略（前向兼容）；**禁止**依赖"对方没有新字段"做行为分支 | 【必须】 |
| 3.3.2 | 字段只增不改语义；确需变更时新增字段 + 旧字段保留 2 个版本 | 【必须】 |
| 3.3.3 | `payload` 嵌套深度 ≤5 层，列表单项 ≤2KB（超出说明建模有问题，评审处理） | 【应当】 |
| 3.3.4 | 布尔/枚举字段用语义化字符串（`"kind": "geofence"`），禁止魔法数字 | 【应当】 |
| 3.3.5 | **强制更新**：App 启动调 `app/checkUpdate`（免 token、幂等读），`version < minVersion` 时阻断使用并引导升级；服务端下线旧版本 op 支持前，先提升 minVersion | 【必须】 |

## 4. 错误码全集

服务端 `code` 对齐 HTTP 语义；App 侧由 `ZenohRpcClient` 映射为 `ZenohApiError` 子类。

| code | 含义 | 服务端义务 | App 侧处置 | 可重试 |
|---|---|---|---|---|
| 0 | 成功 | — | — | — |
| 400 | 参数错误 / ts 超窗 | msg 指明字段 | 提示，不重试 | ✗ |
| 401 | token 无效/过期 | — | 静默 refresh → 重放 1 次；再失败 → 登录页 | 由框架处理 |
| 403 | 已登录但无权限 | — | 提示 | ✗ |
| 404 | 资源不存在 / 未知 op | — | 业务缺省态 | ✗ |
| 409 | 冲突（重复提交/版本冲突） | 幂等命中也回 409+原结果说明 | 提示 | ✗ |
| 429 | 限流 | data 带 `retryAfterMs` | 退避后重试 | ✓（按 retryAfterMs） |
| 4403 | 会话已失效（被其他设备在设置页剔除 / 主动登出 / 风控吊销） | jti 黑名单即时生效 | 清会话 → 登录页（带原因："设备已被移除"等） | ✗ |
| 4510–4519 | auth 域自定义段（附录 A 登记制，其他域依次取 4520+） | msg 指明具体码 | 按域处理 | 视业务 |
| 500 | 服务端内部错误 | — | 指数退避，≤2 次 | ✓（仅幂等） |
| 502 | queryable 内部异常 | — | 同 500 | ✓（仅幂等） |
| 503 | 服务过载/维护 | data 可带 `retryAfterMs` | 同 500 + 全局降级横幅 | ✓ |
| 504 | 服务端处理超时 | — | 同 500 | ✓（仅幂等） |
| -1（App 合成） | 超时/无响应者（`kind` 无回复） | — | 幂等读重试 ≤2 次；写操作提示失败 | ✓（仅幂等） |
| -2（App 合成） | 链路断开即失败 | — | 网络异常 UI | — |

## 5. 超时、重试与 QoS 约束

| # | 约束 | 级别 |
|---|---|---|
| 5.1 | RPC 默认超时 5s，App 侧硬上限 15s（超限按 15s 执行并告警日志）；信封不传 timeout（超时是链路层参数，不进业务信封） | 【必须】 |
| 5.2 | 重试策略：幂等操作（读）在 `-1/502/503/504` 上指数退避（500ms、1s）重试 ≤2 次，**复用同一 reqId**；写操作永不自动重试，失败交给用户决策（服务端 reqId 幂等兜底用户手动重试） | 【必须】 |
| 5.3 | 429 退避：按 `data.retryAfterMs` 等待后重试 1 次；连续 2 次 429 触发全局熔断 10s（该用户 App 侧停止发请求，防雪崩） | 【应当】 |
| 5.4 | zenoh 优先级映射（App 发布侧）：`cmd/*` → InteractiveHigh；`api` get → 默认；`location` 订阅（服务端发布侧）→ Data；`evt/*` → Background + `CongestionControl::Drop` | 【必须】 |
| 5.5 | 服务端发布侧拥塞控制：告警/alarm → `Block`（不丢）；位置流 → `Drop`（允许丢点，保实时性）；全部带 HLC/Unix 毫秒 `ts` | 【必须】 |
| 5.6 | App 侧并发上限：同一时刻 in-flight RPC ≤8，超出排队（防页面快速切换打满 pending 表） | 【应当】 |

## 6. 鉴权与会话约束

### 6.1 登录（多方式，可扩展 OAuth）

登录方式与 op 清单（全部 auth 域 RPC、免 token）：

| op | payload 要点 | 说明 |
|---|---|---|
| `auth/loginByPassword` | `{phone, password}` + 设备四件套 | 密码登录 |
| `auth/loginBySms` | `{phone, smsCode}` + 设备四件套 | 验证码登录（先 `sendSms(scope=login)`） |
| `auth/loginByOauth` | `{provider, code}` + 设备四件套 | OAuth 授权码登录；`provider` ∈ `{wechat}`，新增 provider 走附录 A 登记制 |
| `auth/register` | `{phone, smsCode(scope=register), password}` + 设备四件套 | 密码账号注册（验证码验证手机号归属），注册成功即登录态 |
| `auth/resetPassword` | `{phone, smsCode(scope=resetPassword), newPassword}` | 忘记密码重置（免登录） |

设备四件套 = `deviceId, deviceName, deviceModel, osVer`（会话注册与设置页设备列表展示用）。统一响应（与登录方式无关）：

```
App                                      服务端(auth 域 queryable)
 │ get auth/loginBy{Password|Sms|Oauth}    │
 │ payload{方式专属凭据 + 设备四件套}         │  校验凭据 → 解析/创建 user
 │◄────────────────────────────────────────│  创建会话(jti)，deviceId 为键
 │ data{access, accessExpireAt,            │  不影响其他已登录设备
 │   refresh, refreshExpireAt,             │  access: 30min / refresh: 30d
 │   user, isNewUser}                      │  user 含 pets[] 归属清单
```

- 【必须】三种方式共用**同一会话模型**（多端共存 §6.4、刷新 §6.2、上限 4512）——登录方式对会话层完全透明，refresh / logout / 设置页剔除均与登录方式无关；
- 【必须】**账号-身份分离模型**：一个 user 可挂多条凭据（1 个密码 + 1 个手机号 + N 条 OAuth identity `{provider, openid, unionid}`）；登录 = 凭据解析到 user。同账号从任一方式登录都是同一个 user，资源权限完全一致；
- 【必须】OAuth 采用**授权码模式**：App 端仅经 provider SDK 取一次性 `code`；换 token、存 openid/unionid、持有 appid/secret 全部在服务端，App 永不接触 provider 的 access_token 与密钥；
- 【必须】OAuth `code` 单次消费、5min 过期，服务端按 code 幂等去重（重放回 `4515`）；未登记的 `provider` 回 `400`；
- 【必须】账号绑定：OAuth 首登自动建号（`isNewUser=true`）；`auth/bindPhone`（短信验证，`scope=bindPhone`）把手机号挂到当前账号；手机号已被其他账号绑定时回 `4516`，**服务端不做自动合并**（冲突走人工申诉流程）；
- 【必须】密码凭据：App 仅内存传递、永不落盘；服务端加盐慢哈希（argon2id/bcrypt）；长度 8–64 位；
- 【必须】防爆破/防滥用：密码登录按账号限频——连续 5 次失败回 `4514` 锁定 15min（锁定期内正确密码也拒绝，短信验证解锁）；`sendSms` 按手机号限频（60s/条、日上限 10 条），超频回 `429`；
- 【必须】`sendSms` 带用途段：`scope ∈ {login, register, resetPassword, bindPhone}`，验证码按 scope 校验用途，不可跨用（防"登录验证码当绑定凭证"的交叉攻击）；
- 【必须】**验证码校验限频**（限发送频次 ≠ 限爆破）：按 `phone+scope` 维度限制校验失败——单个验证码 10 次失败即作废；1 小时内连续作废 3 个验证码 → 该手机号锁定 15min（超限校验回 `429`）；
- 【必须】密码重置是**安全事件**：`resetPassword` 成功后服务端吊销该 userId 的**全部**会话（所有设备重新登录，防止凭据泄露方凭旧会话存留）；
- 【应当】OAuth 新账号不强制绑定手机号；策略调整需同步本表与 l10n 文案；
- 【可以】验证码通道沿用现有 Mock（演示版），正式版接短信服务商；微信 SDK 各端原生接入（iOS / Android / 鸿蒙各自 SDK），`code` 取得后走统一 RPC，协议层不感知 provider 差异。

### 6.2 刷新（single-flight）

```
任意 RPC 收 401 → TokenStore.refresh()（并发请求共享一次调用）
 │ get auth/refresh
 │ payload{refresh, deviceId}
 │◄─ data{access, accessExpireAt}   │ 成功 → 原请求重放 1 次（同 reqId）
 │◄─ code=401                       │ 失败 → 清会话 → 登录页
```

- 【必须】refresh RPC 本身失败不触发再次 refresh（防递归）；
- 【必须】refresh token 换发后旧的立即失效（rotation），服务端检测旧 refresh 重放 → 视为泄露，吊销整个会话（401 + 4403）。

### 6.3 请求鉴权

- 【必须】服务端 queryable 入口中间件顺序：验签 → 过期 → jti 黑名单 → tenant 匹配（`token.tenant` == key 第 2 段）→ 资源归属（payload 中 petId/userId ∈ `user.pets` 派生清单）→ handler；
- 【必须】tenant 不匹配一律 403（结构性防跨租户越权，见设计文档 §6.3）；
- 【必须】服务端日志记录 `{reqId, uid, op, code, costMs}`，token 不落日志。

### 6.4 多端共存与会话管理（设置页剔除设备）

多端并行模型：会话以 **deviceId 为键**，同一 userId 下各会话的 access/refresh/jti 完全独立，登录互不影响。

**登录规则**

- 【必须】任何新登录**不踢**任何已登录设备；
- 【必须】活跃会话数达上限（5）时新登录拒绝：`code=4512`，`data.sessions` 携带会话摘要，App 引导去设置页剔除后再试。

**会话管理 RPC（设置页"登录设备管理"）**

```
App                                服务端(auth 域 queryable)
 │ get auth/listSessions            │  当前 userId 全部活跃会话
 │◄─ data{sessions:[{deviceId,      │  （lastActiveAt 每次
 │    deviceName, deviceModel,      │   access/refresh 刷新）
 │    platform, loginAt,            │
 │    lastActiveAt, current}]}      │
 │ get auth/revokeSession           │  目标会话 jti 入黑名单
 │ payload{deviceId}                │  （即时生效）
 │◄─ code=0                         │
```

- 【必须】`revokeSession` 目标为**当前设备**时拒绝（`code=400`，提示改走退出登录）；目标会话不存在/已失效回 `code=404`；
- 【必须】被剔除设备在下一次**任意 RPC** 收 `4403`（jti 黑名单）→ 清会话 → 登录页（msg 注明"设备已被移除"）。被剔除时若 App 在前台且空闲，最长感知延迟 = 下一次 RPC 触发时刻；
- 【应当】剔除动作实时通知：服务端经系统推送通道（APNs/华为 Push/FCM，与告警推送共用基建）向目标设备发"设备已被移除"通知，App 点击后立即清会话——zenoh 长连接不保证（离线/被杀收不到，与 §1.7 同理）；
- 【应当】闲置清理：30 天未活跃（lastActiveAt）的会话服务端自动失效，不占上限名额；
- 【必须】会话摘要中的 `deviceId`/`deviceName` 仅本人可见；设备列表数据**只经 RPC 拉取**，不做广播流（避免在 key 空间引入 userId 段，见 §8.1）。

**登出规则（多端语义变更）**

- 【必须】`auth/logout` 仅吊销**当前 deviceId** 的会话，其他设备不受影响（单端登出）。

## 7. 幂等与一致性约束

| # | 约束 | 级别 |
|---|---|---|
| 7.1 | 服务端对**写操作**按 `reqId` 维护 5min 幂等窗口（内存 LRU + 可选持久化）；命中返回首次执行结果（`data.idempotentReplay: true` 标记） | 【必须】 |
| 7.2 | `ts` 防重放窗口 ±120s；敏感操作类目（预留：改密/支付）额外校验 `payload.nonce` 一次性 | 【应当】 |
| 7.3 | 实时流（status/location/alarm）不做可靠投递；App 侧以信封/ts 做乱序容忍与幂等消费（沿用轨迹库 `UNIQUE(pet_id, ts)` 模式） | 【必须】 |
| 7.4 | 需要"断线补齐"的数据（轨迹、告警历史）**不靠重放**，走 RPC 拉历史接口（服务端 DB 为准）；可选进阶：router storage 插件兜底只读热点（设计文档 §8） | 【必须】 |
| 7.5 | 双写一致性：RPC 成功后相关实时流可能尚未刷新，App 以 RPC 响应为权威、流数据做乐观更新 | 【应当】 |

## 8. 推送流（服务端 → App）约束

| # | 约束 | 级别 |
|---|---|---|
| 8.1 | 服务端发布前校验资源归属（发布侧鉴权，不依赖订阅侧），见设计文档 §6.4 | 【必须】 |
| 8.2 | 流消息复用信封 v2 结构（无 `code`，恒 0；`payload` 为流数据）；`ts` 必填，供乱序判定 | 【必须】 |
| 8.3 | App 订阅范围 ≤ `petpal/{tenant}/**`；仅订阅 `user.pets` 派生 key（首页多宠物用 `*/status` 通配，但收到非白名单 petId 的样本静默丢弃） | 【应当】 |
| 8.4 | alarm 流必须可从"最后收到的时间"增量补齐：alarm 携带递增 `seq`，App 检测断档即触发 RPC 拉历史 | 【应当】 |

## 9. 文件上传下载约束（HTTP 通道，唯一例外）

| # | 约束 | 级别 |
|---|---|---|
| 9.1 | 流程：`files/createUpload`（RPC）→ OSS STS 直传（HTTP PUT）→ `files/commit`（RPC，校验 sha256/size）→ 入库 | 【必须】 |
| 9.2 | STS 凭证：15min 有效，policy 限定 `ossKey` 前缀 + MIME + `maxBytes`；**禁止**下发长期 AK/SK | 【必须】 |
| 9.3 | 大小：单文件 ≤20MB；图片格式白名单 jpg/png/webp/heic；下载一律 CDN 签名 URL（5min 有效，防盗链） | 【必须】 |
| 9.4 | 未 `commit` 的 OSS 孤儿文件，服务端定时任务 24h 清理 | 【必须】 |
| 9.5 | App 上传失败重试：HTTP 层自身重试；`commit` 幂等（按 sha256 去重） | 【应当】 |
| 9.6 | 文件元数据（owner、sha256、size、mime、业务关联 id）只经 zenoh RPC 传递 | 【必须】 |

## 10. 可观测性与联调约定

| # | 约束 | 级别 |
|---|---|---|
| 10.1 | `reqId` 为全链路追踪键：App 日志、服务端日志、告警流水全部携带 | 【必须】 |
| 10.2 | App 端 `ZenohRpcClient` 统一日志格式：`[rpc] {domain}/{op} reqId={reqId} code={code} cost={ms} retry={n}`；token 只打前 6 位 | 【必须】 |
| 10.3 | 服务端 metric 最小集：每域 QPS、P95 延迟、错误码分布、queryable 存活数、幂等命中率 | 【应当】 |
| 10.4 | App 时钟漂移 >60s（对照响应 `ts`）→ 提示校时（ts 窗口校验依赖真实时钟） | 【应当】 |
| 10.5 | 联调工具：`/zenoh-debug` API 调试 Tab（等价 Postman）；服务端联调期在 router 挂 rest 插件（`http_port: 8000`，Book《Router Mode》）供 `curl` 旁路验证 | 【应当】 |

## 11. 上线验收矩阵（双端签字依据）

| 用例 | 预期 |
|---|---|
| 正常 RPC 往返 | code=0，P95 <300ms（同区） |
| 停服务后 App 调 RPC | -1（ApiNoResponder），UI 明确网络错误，**不显示空数据** |
| access 过期边界 | 自动 refresh + 重放成功，用户无感 |
| refresh 也过期 | 进入登录页 |
| 三台设备同时登录同账号 | 三端会话互不影响，各自 RPC 正常 |
| 设置页剔除设备 B | B 下一次 RPC 收 4403 并登出；A/C 无感 |
| revokeSession 传当前设备 deviceId | 400，提示改走退出登录 |
| 会话数达上限（5）后新端登录 | 4512 + sessions 摘要，App 引导剔除后可登录 |
| 单端 logout | 仅该端失效，其他设备正常使用 |
| 密码连续错误 5 次 | 4514 锁定 15min，锁定期内正确密码亦拒绝 |
| 微信登录 code 重放 | 4515 |
| 微信首登（新用户） | 自动建号，isNewUser=true，资源权限与老用户一致 |
| 微信账号 bindPhone（手机号未被占用） | 绑定后可用密码/验证码登录同一账号 |
| bindPhone 时手机号已被其他账号绑定 | 4516，不自动合并 |
| sendSms 60s 内重发 | 429 + retryAfterMs |
| sendSms(scope=login) 的验证码用于 bindPhone | 4510（scope 不匹配拒绝） |
| 单个验证码连续校验失败 10 次 | 验证码作废；1h 内作废 3 个 → 手机号锁定 15min |
| 密码重置后旧设备请求 | 该 userId 全部会话吊销，各端 401→refresh 失败→登录页 |
| 主 router 宕机 | App 自动切备 router，幂等读重试恢复，用户无感 |
| 低于 minVersion 的 App 启动 | 阻断使用并引导升级 |
| 重放同一写 reqId | 幂等命中，data.idempotentReplay=true |
| 伪造跨租户 key（token.tenant=demo, key=petpal/other/…） | 403 |
| ts 偏移 >120s 的请求 | 400 |
| 100 qps 压测单用户 | 429 + retryAfterMs，App 熔断生效 |
| 16KB 边界 payload | 成功；>16KB 被 App 端拒绝发送 |
| tls 断链（中间人剥离 TLS） | 连接失败，无明文回退 |
| 飞行模式→恢复 | 链路自动恢复，订阅重声明，幂等读自动重试成功 |
| 杀进程后收到告警 | 系统推送通道触达（不依赖 zenoh） |

## 附录 A：域与错误码登记表（新增必登记）

| 域 | ops | 负责人 | 自定义错误码段 |
|---|---|---|---|
| auth | loginByPassword / loginBySms / loginByOauth / register / resetPassword / sendSms / bindPhone / refresh / logout / listSessions / revokeSession | 待定 | 4510 验证码错误 · 4511 验证码过期 · 4512 会话数达上限 · 4513 手机号未注册 · 4514 账号锁定 · 4515 OAuth 授权失败（code 无效/过期/重放/未登记 provider） · 4516 手机号已被其他账号绑定 · 4517 手机号已注册 |
| pets | getInfo / list / create / update / delete / rename | 待定 | 4520 |
| devices | bind / unbind / listStatus / getFirmware | 待定 | 4530 |
| files | createUpload / commit / getDownloadUrl / delete | 待定 | 4540 |
| family | 邀请/成员管理（待细化） | 待定 | 4550 |
| chat | 发送/历史（待细化） | 待定 | 4560 |
| report | 轨迹/健康报告（待细化） | 待定 | 4570 |
| app | checkUpdate（免 token、幂等读；强制更新判定，约束 §3.3.5） | 待定 | 4580 |
| profile | getProfile / updateProfile（昵称等；头像二进制走 files 域） | 待定 | 4590 |
