# Zenoh 替代 HTTP 接口 —— 设计实现文档

> 前置阅读：`docs/Zenoh替代HTTP接口可行性研究报告.md`（结论：分层替代——zenoh 承担实时推送 + CRUD RPC，文件二进制走 HTTP/OSS）
> 关联文档：`docs/Zenoh替代HTTP接口-交互约束.md`（App ↔ 服务端协议契约，双方共同遵守）
> 本文职责：架构、Key 命名、信封协议、Dart 工具类设计、FFI 扩展、服务端设计、安全设计
> 日期：2026-11-07

---

## 1. 总体架构

### 1.1 部署拓扑

```
                         ┌─────────────────────────── 公网 ───────────────────────────┐
                         │                                                            │
 ┌──────────┐  tls/7447  │   ┌─────────────┐   tcp/tls 局域网   ┌───────────────────┐  │
 │ PetPal   ├────────────┴──►│  zenohd     │◄─────────────────►│  PetPal 业务服务   │  │
 │ App 三端  │   client 模式  │  Router     │                   │  (peer 模式，      │  │
 │ (pico FFI)│               │  (公网入口)  │                   │   声明 queryable)  │  │
 └────┬─────┘               └──────┬──────┘                   └─────────┬─────────┘  │
      │                            │                                    │            │
      │  subscribe 实时流           │  put 持久化 / storage 插件          │  SQL       │
      ▼                            ▼                                    ▼            │
   UI/DB                      （可选）Storage(rocksdb)               业务数据库       │
                                                                                  └────────────┘
      ┌──────────┐   HTTPS    ┌──────────────┐
      │ OSS/CDN  │◄───────────┤ 文件上传下载   │  ← 唯一保留的 HTTP 直连（见 §7）
      └──────────┘   (含STS)  └──────────────┘
```

角色划分：

| 角色 | zenoh 模式 | 职责 |
|---|---|---|
| App（三端） | **client**（Book《Client Mode》：资源占用最小、零 scouting、专为移动设备设计） | `get()` 发起 RPC、`put()` 发指令、`subscribe()` 收实时流 |
| zenohd Router | **router**，公网入口，`tls/0.0.0.0:7447` | 路由、ACL 执行点、（可选）storage 持久化兜底 |
| 业务服务 | **peer**（与 router 同机/同内网，直连互通） | 声明 API queryable，鉴权、业务逻辑、落库 |
| 设备网关 | peer / client（按部署位置） | 桥接项圈硬件，publish 位置/状态/告警 |

### 1.2 为什么服务端用 peer 而非 client

Book《Sessions》章：peer 与 router 通过路由表互通但保持独立身份，避免业务服务成为 router 的"下属 client"（client 断连后订阅由 router 代持的语义不利于有状态业务服务做优雅发布/灰度）。业务服务直连 router 即 peer 即可，实现上只是 `mode: "peer"` + `connect.endpoints`。

### 1.3 通信模型与 REST 的对位

| REST | 本设计 | 说明 |
|---|---|---|
| `GET /pets/p123` | `get("petpal/api/v1/demo/pets/getInfo")` + body `{petId}` | 操作化 RPC，而非资源化 URL（理由见 §3.1） |
| `POST/PUT/DELETE` | 同上，operation 区分（`create/update/delete`） | 信封 `reqId` 保证写幂等 |
| `Authorization: Bearer` | 信封 `token` 字段 | 请求级鉴权，见 §6.3 |
| 轮询/WebSocket 推送 | `subscribe("petpal/{tenant}/{petId}/alarm/*")` | 复用现有 `ZenohClient.subscribe` |
| `Range`/`304`/CDN | **不替代**，走 OSS/CDN（§7） | — |

### 1.4 Router 高可用与信任边界

- **SPOF 消除**：公网入口至少 **2 台 zenohd router 组 mesh**（Book《Routing》：router 任意互连、链路状态路由自动选路，无需应用层干预）；App 侧 `connect.endpoints` 配置**有序主备 locator 列表**——`ZenohConfig.peer`（`ZENOH_PEER`）扩展为逗号分隔多 locator，FFI open 直接交给 pico/zenoh 原生 endpoints 语义处理。单台 router 宕机对 App 只是"一次重连 + 幂等读重试"，业务无感；
- **滚动升级**：升级节奏保证任一时刻至少一台 router 可达；窗口内的 `-1`（无响应者）属预期内故障，不做特殊处理（约束文档 §1.10）；
- **信任边界声明**：TLS 在 router 终结，payload（含 token 与业务数据）对 router **明文可见**——与 HTTPS 在 LB/网关终结等价，但必须写明安全前提：**router 属自建可信基础设施（与业务数据库同密级部署）**；若未来引入不可信托管方，需另行评估端到端加密方案（当前不做，登记为开放项）；
- **版本兼容**：zenohd router 与客户端（zenoh-pico 1.10.2）升级遵循官方 release notes 兼容矩阵——**router 先升、客户端灰度跟进**；三端验证清单（§5.3）在每次依赖升级后重跑。

---

## 2. Key Expression 命名空间设计

### 2.1 总规范（扩展自 `lib/core/zenoh/zenoh_key_expr.dart`）

```
petpal/{tenant}/{scope}/{...}
```

| scope | 模式 | 说明 |
|---|---|---|
| `api/v1/{domain}/{op}` | get/queryable（**RPC**） | App→服务端请求-响应，本文 §3 |
| `status` / `location` / `behavior` / `ota` | pub/sub | 现有规范不变 |
| `alarm/{kind}` | pub/sub | 现有规范不变 |
| `cmd/{type}` | pub/sub（App put） | 现有规范不变 |
| `evt/{type}` | pub/sub（App put） | **新增**：App 上报事件（页面埋点、崩溃日志，Background 优先级） |

完整示例：

```
petpal/demo/api/v1/pets/getInfo          ← App get() 查宠物详情
petpal/demo/api/v1/auth/refresh          ← App get() 刷新 token
petpal/demo/api/v1/files/createUpload    ← App get() 申请 OSS 直传凭证
petpal/demo/p123/alarm/geofence          ← 服务端 push 告警（pub）
petpal/demo/u9f3/cmd/find                ← App put() 发寻宠指令
petpal/demo/u9f3/evt/crash               ← App put() 上报崩溃
```

**注意**：用户/宠物标识段（`p123`、`u9f3`）一律使用**服务端分配的不可读 UUID 短码**，禁止使用昵称、手机号等 PII——key 在 router 上明文可见且可能进入 storage 持久化（Book《Storages》），这是安全设计的一部分（§6.5）。

### 2.2 API 域与通配符使用规则

| 侧 | 表达式 | 规则 |
|---|---|---|
| 服务端 queryable 声明 | `petpal/{tenant}/api/v1/{domain}/**` | 每域一个 queryable，域内自路由到 op；**禁止全 `petpal/api/**` 大通配**（Book《Key Expressions》：宽通配符迫使路由器向更多订阅者扇出） |
| App get | `petpal/{tenant}/api/v1/{domain}/{op}` | **精确 key，禁止通配**（`validatePublish` 同源校验逻辑） |
| App/服务端 pub | 精确 key | 同现有 `validatePublish` |
| App sub | 允许 `*`/`**` | 同现有规范 |

### 2.3 版本演进

- 主版本进 key：`api/v1/...` → `api/v2/...` 并行期双域并存，App 按服务端返回的能力集切换（见约束文档 §8）；
- 域级灰度：新服务以新域名 `pets_v2` 上线 queryable，旧域保留，网关层做流量切分，App 无感。

---

## 3. RPC 协议设计（信封 v2）

### 3.1 为什么选"操作化 RPC"而非"资源化 REST 映射"

两种可选形态：

| 形态 | key 示例 | 评价 |
|---|---|---|
| A. 资源化（REST 直译） | get `.../pets/p123`（读）、put `.../pets/p123`（写） | 同一 key 上读写混合：App 侧 put 需要等 ack 而 RPC 需要等 reply，两条链路混用同一 key，router ACL 无法区分读写主体，调试也易混淆 |
| **B. 操作化（选定）** | get `.../pets/getInfo`、get `.../pets/update` | 一把钥匙一条链路：RPC 全部走 `get()/queryable`，`put()` 只留给 fire-and-forget 的指令/事件流；ACL 可按 op 精确放行 |

选 B。牺牲一点 REST 表达力，换来链路语义单一、ACL 精确、调试清晰。

### 3.2 请求信封（App → 服务端，`get()` 的 payload）

```json
{
  "v": 2,
  "reqId": "r42-1699365120000",
  "token": "eyJhbGciOi...",
  "deviceId": "ios-3f2a...",          
  "ts": 1699365120000,
  "payload": { "petId": "p123", "page": 1 }
}
```

- `v`：信封协议版本（2 = 本设计；1 为现有网关线协议，互不混用）；
- `reqId`：全局唯一，格式 `{seq}-{unixMs}`（沿用 `ZenohClient._nextReqId`），**写操作的服务端幂等键**；
- `token`：请求级凭证（§6.3），auth 域的 `login/refresh` 两个 op 除外；
- `deviceId`：设备指纹（登录时下发并绑定），服务端用于多端会话管理（§4.7）与风控；
- `ts`：客户端毫秒时间戳，服务端校验 ±120s 窗口（防重放，超窗拒绝 `code=400`）。

### 3.3 响应信封（服务端 → App，queryable 的 reply payload）

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

错误码体系（对齐 HTTP 语义，全集见交互约束文档 §4）：

| code | 含义 | App 侧处置 |
|---|---|---|
| 0 | 成功 | — |
| 400 | 参数/时间窗校验失败 | 提示，不重试 |
| 401 | token 无效/过期 | 触发静默刷新后重放一次 |
| 403 | 无权限 | 提示，不重试 |
| 404 | 资源不存在 | 按业务缺省 |
| 409 | 冲突（版本/重复提交） | 提示 |
| 429 | 限流 | 按 `data.retryAfterMs` 退避 |
| 4510/4511 | 服务端自定义段 | 业务处理 |
| 500/502/503 | 服务端错误 | 指数退避重试（≤2 次） |
| 客户端合成 `-1` | **超时/无响应者** | 网络层合成，见 §4.3 |

### 3.4 多回复处理（Fan-out 语义）

`get()` 可能收到多条 reply（灰度期新旧服务并存、误配置多 queryable）。约定：

1. **权威响应** = 第一条 `kind=ok` 的 reply；收到后立即结束等待（不等 reply_done 的其余流），减少长尾延迟；
2. `kind=err` 的 reply 若是唯一回复，映射为对应 `code` 的 `ServerError`；
3. 所有回复的 `reqId` 必须与请求一致，不一致的丢弃并计数（可观测性信号，说明拓扑配置有误）；
4. 服务端拓扑约束：**同一 API key 同一时刻只允许一个权威 queryable**（约束文档 §2，router ACL 辅助保证）。

---

## 4. Dart 工具类设计

### 4.1 分层总览

```
┌────────────────────────────────────────────────────────┐
│ 业务 Notifier（providers.dart）                          │
│   调用 PetsApi.list() / AlarmApi.push(...) 等           │
├────────────────────────────────────────────────────────┤
│ 领域 API 门面（lib/core/zenoh/api/domains/*.dart）       │  ← 强类型、按域拆文件
│   PetsApi / AuthApi / FilesApi / FamilyApi / ChatApi    │
├────────────────────────────────────────────────────────┤
│ ZenohRpcClient（lib/core/zenoh/api/zenoh_rpc_client.dart）│ ← ★本文核心
│   信封封装 / 超时 / 重试 / token 注入与刷新 / 错误映射     │
├────────────────────────────────────────────────────────┤
│ ZenohClient（现有，lib/core/zenoh/zenoh_client.dart）     │
│   subscribe / put / get（原语级）                        │
├────────────────────────────────────────────────────────┤
│ ZenohTransport（现有：FFI / WebSocket 双实现）            │
└────────────────────────────────────────────────────────┘
```

原则：**不改动现有 `ZenohClient` 的原语语义**（get 返回多回复列表的行为保留），RPC 语义全部上移到 `ZenohRpcClient`，两层级各司其职；`ZenohClient` 保持 fail-soft，`ZenohRpcClient` 则是 **fail-loud**（API 调用必须给出明确的 `RpcResult`，绝不让 UI 把"超时"当"空数据"）。

### 4.2 核心类型

```dart
/// RPC 结果（替代异常驱动的 HTTP 封装风格；与 fail-soft 原语层明确区分）。
sealed class RpcResult<T> {
  const RpcResult();
  T get dataOrThrow;                 // 失败时抛 ZenohApiError（业务可选用法）
}

class RpcOk<T> extends RpcResult<T> {
  final T data;
  final int serverTs;                // 服务端权威时间，供时钟校准
}

class RpcErr<T> extends RpcResult<T> {
  final ZenohApiError error;
}

/// 错误分类（业务只 switch 这一层的子类型，禁止接触原始信封）。
sealed class ZenohApiError implements Exception {
  final String reqId;                // 全链路追踪 id
}
class ApiServerRejected   extends ZenohApiError { final int code; final String msg; }        // 服务端明确拒绝（4xx）
class ApiNoResponder      extends ZenohApiError {}                                          // 超时/无 queryable（-1）
class ApiLinkDown         extends ZenohApiError {}                                          // 链路断开时即失败
class ApiAuthRequired     extends ZenohApiError { final bool refreshable; }                 // 401 且刷新也失败
class ApiCancelled        extends ZenohApiError {}                                          // 调用方取消/页面销毁
```

### 4.3 ZenohRpcClient（伪代码级设计，约 200 行）

```dart
class ZenohRpcClient {
  ZenohRpcClient({
    required ZenohClient client,          // 复用现有 provider 单例
    required TokenStore tokens,           // §4.4
    this.defaultTimeout = const Duration(seconds: 5),
    this.maxTimeout = const Duration(seconds: 15),
  });

  /// 统一入口：所有领域门面都走这里。
  Future<RpcResult<Map<String, dynamic>>> call(
    String domain, {
    required String op,
    Map<String, dynamic>? payload,
    bool auth = true,                     // auth 域的 login/refresh 传 false
    bool idempotent = false,              // 读操作 true（可安全重试）
    Duration? timeout,
    int maxRetries = 2,
  }) async {
    // 1) 就绪门：未连接直接 ApiLinkDown，不空等（UI 立刻可给反馈）
    // 2) 信封组装：reqId/token/ts/deviceId + payload，key = api/v1/$domain/$op
    // 3) 单次尝试：client.get(key, payload: envelope, timeout)
    //    - 空 replies → ApiNoResponder（"空列表≠空数据"，这是与原语层的关键差异）
    //    - 取第一条 kind=ok → 解码响应信封；code!=0 → 按错误码表分类
    // 4) 401 且 auth=true：tokenStore.refresh() 成功 → 重放一次（仅一次，防循环）
    // 5) idempotent && (ApiNoResponder|502|503) && 重试预算>0：指数退避重试
    //    写操作永不自动重试（幂等由服务端按 reqId 保证，但重放风险留给显式策略）
    // 6) 全程 reqId 贯穿日志：[rpc] domain/op reqId code costMs
  }

  /// 带取消的调用（页面 dispose 时取消 pending，避免无效重试与状态错乱）。
  Future<RpcResult<T>> callCancellable(...);
}
```

关键防暗坑设计：

- **"空列表陷阱"**：原语层 `get()` 失败/超时/无匹配者都返回空列表（fail-soft 语义正确），但 RPC 层绝不能复用此语义——`ApiNoResponder` 与"业务空结果"（`code=0, data={list:[]}`）必须可区分，否则 UI 会出现"断网时看起来没养宠物"的暗坑；
- **刷新风暴**：并发多个 401 时，`TokenStore.refresh()` 内部用单飞锁（single-flight），只发一次 refresh RPC，其余共享结果；refresh 失败统一收敛为 `ApiAuthRequired` → 踢回登录页；
- **重试预算与 reqId**：重试**复用同一 reqId**（服务端幂等窗口内去重），而不是生成新 id——否则服务端可能重复扣减库存类操作；
- **超时上限**：信封里的 `timeout_ms` 超过 15s 一律按 15s 下发（约束文档 §5），防止业务随手传 60s 把长连接挂满；
- **取消语义**：`callCancellable` 页面销毁时完成 completer 但**不发 unsub**——zenoh get 是单次请求，服务端继续处理无害，只是结果被丢弃。

### 4.4 TokenStore（lib/core/zenoh/api/token_store.dart）

```dart
class TokenStore {
  // access：短效（30min），内存持有，不落盘（杀进程即失效，安全性优先）
  // refresh：长效（30d），flutter_secure_storage 等价物落盘（鸿蒙端注意选型）
  // deviceId：首次启动生成 UUID，登录时上报绑定

  Future<String?> access();                 // 过期前 60s 内主动判失效
  Future<RpcResult<void>> refresh();        // single-flight 锁
  Future<void> logout();                    // 通知服务端吊销 + 清本地
}
```

登录/刷新流程（约束文档 §6 有时序图）：

1. 任一登录方式（`auth/loginByPassword` / `auth/loginBySms` / `auth/loginByOauth`，多方式与账号-身份模型见约束文档 §6.1）→ 统一返回 `{access, refresh, user, isNewUser}`；登录方式对会话层透明，TokenStore 无感知；
2. 后续所有 RPC 由 `ZenohRpcClient` 自动注入 `token`；
3. 401 → `refresh()`（payload: refresh+deviceId）→ 换新 access 并重放原请求一次；
4. refresh 也 401 → `ApiAuthRequired` → 退出登录态；
5. 多端共存：同一 userId 支持多端同时登录（上限 5，会话以 deviceId 为键互相独立，新登录不踢旧端，约束文档 §6.4）；本设备被其他设备在设置页剔除时，下一次 RPC 收 `code=4403` → 清会话回登录页；
6. 会话失效清理（登出 / `4403` / 密码重置吊销）：清 token **之外必须同步退订全部业务订阅**（逐个 `ZenohClient.unsubscribe`）、停止 `evt/` 上报、清空 pending 队列——防止"无凭据仍收推/仍上报"的半死状态（约束文档 §1.11）。

### 4.5 领域门面（示例）

```dart
class PetsApi {
  PetsApi(this._rpc);
  final ZenohRpcClient _rpc;

  Future<RpcResult<PetDetail>> getInfo(String petId) => _rpc
      .call('pets', op: 'getInfo', payload: {'petId': petId}, idempotent: true)
      .then((r) => r.map((d) => PetDetail.fromJson(d['pet'])));

  Future<RpcResult<void>> rename(String petId, String name) =>
      _rpc.call('pets', op: 'rename', payload: {'petId': petId, 'name': name});
}

class AuthApi {
  AuthApi(this._rpc);
  final ZenohRpcClient _rpc;

  /// 三种登录方式共用同一返回（{access, refresh, user, isNewUser}）与
  /// 会话模型（多端共存 §4.7）；登录页 UI 三 Tab 各对应一个方法，
  /// 成功后统一交 TokenStore 存取，后续流程完全一致。
  Future<RpcResult<LoginResp>> loginByPassword({
    required String phone, required String password, required DeviceInfo device,
  }) => _rpc.call('auth', op: 'loginByPassword', auth: false, ...);

  Future<RpcResult<LoginResp>> loginBySms({
    required String phone, required String smsCode, required DeviceInfo device,
  }) => _rpc.call('auth', op: 'loginBySms', auth: false, ...);

  /// provider 登记制（约束文档附录 A）：新增 OAuth 方式（Apple/华为/QQ…）
  /// = App 侧接该端原生 SDK 取 code + 本方法传新 provider 值，
  /// 协议层（信封/key/token/会话）零改动。
  Future<RpcResult<LoginResp>> loginByOauth({
    required String provider,   // 'wechat'，附录 A 登记
    required String code,       // provider SDK 返回的一次性授权码
    required DeviceInfo device,
  }) => _rpc.call('auth', op: 'loginByOauth', auth: false, ...);

  /// 密码账号注册（验证码验证手机号归属），成功即登录态。
  Future<RpcResult<void>> register({
    required String phone, required String smsCode, required String password, required DeviceInfo device,
  });

  /// 忘记密码重置（免登录）。重置为安全事件：服务端吊销该账号全部会话。
  Future<RpcResult<void>> resetPassword({
    required String phone, required String smsCode, required String newPassword,
  });

  /// OAuth 首登后绑定手机号（scope=bindPhone 的验证码）。
  Future<RpcResult<void>> bindPhone({required String phone, required String smsCode});
}
```

Provider 装配（`lib/core/zenoh/zenoh_provider.dart` 追加）：

```dart
final zenohRpcProvider = Provider<ZenohRpcClient>((ref) =>
    ZenohRpcClient(client: ref.watch(zenohClientProvider), tokens: ref.watch(tokenStoreProvider)));
final petsApiProvider = Provider((ref) => PetsApi(ref.watch(zenohRpcProvider)));
```

### 4.6 与现有调试页的整合

`/zenoh-debug` 扩展一个 "API 调试" Tab：域/操作下拉 + payload 编辑器 + 直接调用 `ZenohRpcClient` 并展示信封级请求/响应。等价于这个架构里的 Postman，弥补 zenoh 生态可调试性短板（可行性报告 R5/R7 的缓解措施之一）。

### 4.7 会话管理（多端登录与设置页设备剔除）

多端模型：**会话以 deviceId 为键**，每台设备持有各自独立的 access/refresh/jti。`TokenStore` 无需感知"其他设备"的存在——多端隔离天然成立，并发模型与单端完全一致；跨设备的会话操作全部收敛在服务端会话表（`userId → {deviceId → session}`）。

**新增门面**（`lib/core/zenoh/api/domains/sessions_api.dart`）：

```dart
class SessionInfo {
  final String deviceId;   // 本端比对 current 标记
  final String deviceName; // 用户可读名（登录时上报，如"小新的 iPhone"）
  final String deviceModel;
  final String platform;   // ios / android / ohos
  final DateTime loginAt;
  final DateTime lastActiveAt;
  final bool current;
}

class SessionsApi {
  SessionsApi(this._rpc);
  final ZenohRpcClient _rpc;

  /// 设置页设备列表。auth/listSessions，幂等读。
  Future<RpcResult<List<SessionInfo>>> list();

  /// 剔除指定设备。auth/revokeSession；目标为当前设备时服务端回 400。
  Future<RpcResult<void>> revoke(String deviceId);
}
```

**App 侧行为约束**：

| 场景 | 处置 |
|---|---|
| 设置页"登录设备管理"入口 | 列表页展示（current 端置顶带"本机"标记），剔除操作二次确认后调 `revoke` |
| 本端被其他设备剔除 | 某次 RPC 收 `4403` → 复用 `ApiAuthRequired` 的收敛路径：清会话 → 登录页，附"设备已被移除"文案（进 l10n 三语表） |
| 登录收到 `4512`（会话数达上限） | 登录页弹出只读设备列表引导剔除，剔除成功后重试登录；**不得**自动替用户剔除任何设备 |
| 单端 logout | 仅清本端会话，不涉及其他设备 |

**为什么被剔除端不做实时踢下线**：key 空间不引入 userId 段（约束文档 §8.1，避免广播流泄露设备列表），zenoh 长连接也不保证离线/被杀进程可达——服务端 jti 黑名单 + 下次 RPC 的 `4403` 是**即时生效**的权威兜底（下一次任何请求都进不来）；"立即感知"作为体验优化交给系统推送通道（与告警推送共用基建，【应当】级）。

---

## 5. FFI / 原生层扩展设计

现有 `native/zenoh_ffi.h` 只含 open/subscribe/put，需扩展 get 与 TLS。**范围明确：App 端只需要 get（发起方），不需要实现 queryable（应答方在服务端）**——这大幅缩小三端原生工作量。

### 5.1 新增 C API

```c
// 带 TLS 的会话打开（取代 zffi_session_open；旧函数保留兼容调试直连）
// ca / cert / key 为 PEM 字符串（非文件路径——移动端证书放 assets，避免落盘明文）
zffi_result_t zffi_session_open_ex(
    const char* locator, const char* mode,
    const char* ca_pem, const char* cert_pem, const char* key_pem,
    zffi_session_t** out);

// 发起 get：replies 经回调流式回吐，done 后回调终态。
// cb(replies_json, len) 一次聚合回调实现最简（pico 的 z_get + z_fifo channel
// 收集后序列化），避免多次回调跨 FFI 的生命周期管理。
zffi_result_t zffi_session_get(
    zffi_session_t* s, const char* key_expr,
    const char* payload_json, uint32_t timeout_ms,
    zffi_get_callback cb, void* user_data);
```

实现要点（基于 zenoh-pico 1.10.2，源码已 vendored 在 `docs/zenoh-pico-1.10.2/`）：

- `z_get` 使用 `z_fifo_channel` + `z_call` 收集 reply（pico 原生支持 queryable 对端的 err reply，kind 直接透传）；
- 超时由 pico 侧保证到期（不依赖 Dart 层 timer——FFI 回调丢失时 Dart 层超时兜底，两层防御）；
- replies JSON 结构沿用线协议 `reply`/`reply_done` 语义：`{"replies":[{kind,payload,ts}...],"done":true}`；
- **payload 保持 JSON 字符串**（与现有 `zffi_put` 一致）。RPC 信封 <16KB，无需字节流接口；文件二进制走 HTTP（§7），因此**本轮不做 `zffi_put_bytes`**，砍掉一个三端验证项。

### 5.2 Dart 侧绑定变更

- `zenoh_ffi_bindings.dart`：新增 `zffi_session_open_ex` / `zffi_session_get` 探针与绑定（沿用"逐候选加载 + version() 符号探针"模式，`zenoh_ffi_bindings.dart:46-82`）；
- `zenoh_ffi_transport.dart`：实现 GetMsg（删除 `:221-223` 的恒 false 占位），复用异步 open 看门狗模式（30s watchdog）；
- `zenoh_config.dart`：新增 `ZENOH_TLS_CA`（PEM 内容，dart-define 传入，打包进对应平台的编译期常量）。

### 5.3 三端验证清单（每端过一遍才算完成）

| 项 | iOS | 鸿蒙 | Android |
|---|---|---|---|
| get 基本往返（对 zenohd 内置 z_queryable） | ☐ | ☐ | ☐（首次接入，先补 `.so` 产出，照 `tool/build_zenoh_native.sh`） |
| get 超时（对无响应 key） | ☐ | ☐ | ☐ |
| err reply 透传 | ☐ | ☐ | ☐ |
| tls/ 连接（单向验证） | ☐ | ☐ | ☐ |
| tls/ + usrpwd（如 pico 支持） | ☐ | ☐ | ☐ |
| 后台/前台切换、Wi-Fi↔蜂窝切换后 get 恢复 | ☐ | ☐ | ☐ |

> 鸿蒙端注意：交叉编译沿用 `ohos.toolchain.cmake` + `-DZP_PLATFORM=linux`，新增 TLS 依赖（mbedTLS）需重验 musl 符号（参照 `docs/Zenoh原生FFI接入-鸿蒙.md` 的 pthread_cancel 教训，提前 `nm` 检查）。

---

## 6. 安全设计

三层纵深（对应可行性报告 §3.4 的"协议层覆盖不了、必须自建"清单）：

### 6.1 传输层：TLS

- locator 一律 `tls/` 前缀、**主备列表**（≥2 台 router，见 §1.4）；**禁止 `tcp/` 出现在 release 构建**（`ZenohConfig` 加 assert，debug 允许本机 `tcp/10.0.2.2` 调试）；
- App 只做**单向 TLS + CA 校验**（不强制客户端证书——见可行性报告：移动端证书下发/吊销/轮换是坑）；App 内嵌 PEM 放 assets，**双 CA 内嵌**（主 CA + 备份 CA）支持服务端证书轮换：轮换期两套证书都在有效信任链内，App 更新无需服务端协调；
- 服务端↔router、设备网关↔router 之间启用 **mTLS**（`client_auth: true`，Book《TLS》配置原样落地）：基础设施实体身份可控且长期稳定，适合证书；移动 App 不适合，两者区别对待；
- 会话恢复：App 端 TLS session 复用由 pico/mbedTLS 自行管理，设计上不额外处理，但三端验证清单含"切换网络后恢复"项。

### 6.2 连接层：router ACL（粗粒度、default deny）

```json5
// zenohd access_control（Book《ACL》配置模式，按需裁剪）
{
  access_control: {
    enabled: true,
    default_permission: "deny",
    rules: [
      // App：只允许 get API 域 + 发 cmd/evt 域
      { id: "app-rpc",  messages: ["request"],         flows: ["ingress"], permission: "allow",
        key_exprs: ["petpal/*/api/v1/**"],             subjects: [{ username: "app-clients" }] },
      { id: "app-pub",  messages: ["put"],             flows: ["ingress"], permission: "allow",
        key_exprs: ["petpal/*/cmd/*/*", "petpal/*/evt/**"], subjects: [{ username: "app-clients" }] },
      // 业务服务：API 应答 + 全域推送/订阅（服务自身可信，粒度放宽）
      { id: "svc",      messages: ["put", "declare_subscriber"], flows: ["ingress","egress"],
        permission: "allow", key_exprs: ["petpal/**"], subjects: [{ cert_common_name: "petpal-svc" }] },
      // 设备网关：只允许设备数据源域
      { id: "dev",      messages: ["put"],             flows: ["ingress"], permission: "allow",
        key_exprs: ["petpal/*/*/status", "petpal/*/*/location", "petpal/*/*/alarm/*"],
        subjects: [{ username: "device-gateway" }] },
    ],
  },
}
```

配合连接级身份（Book《Token-Based Auth》usrpwd）：App 端用**打包内置的公共凭证**（仅标识"我是 App"这一个粗粒度角色，泄露影响面 = 穷举出公共凭证，配合 TLS 拦截成本高，可接受）；真正的用户身份在请求层（§6.3）。**切忌**给每用户发连接级凭证——连接级身份等于把用户体系下沉进 router，吊销/换密/运维复杂度失控。

### 6.3 请求层：token + 业务级细粒度授权（服务端网关强制）

- 凭证形态：JWT（HS256/RS256 服务端自选），access 30min / refresh 30d 绑定 deviceId；
- 服务端 queryable 入口统一走**鉴权中间件**：验签 → 过期校验 → `token.tenant == key 中 tenant 段` 校验（**防跨租户越权的第一道闸**）→ 资源归属校验（petId ∈ token 用户的宠物列表）；
- key 与 token 的租户绑定是**结构性防御**：即使业务代码忘了校验，key 前缀也对不上租户——设计上让越权需要同时绕过两层；
- 写操作幂等：服务端按 `reqId` 维护 5 分钟幂等窗口（去重表），重放同 reqId 返回首次结果（约束文档 §7）；
- 防重放：`ts` ±120s 窗口（§3.2）+ 敏感操作（改密、支付类预留）额外要求 `payload.nonce`。

### 6.4 反向通道（服务端→App 推送）的鉴权

订阅没有"每次请求带 token"的机会——App 的订阅流只受 router ACL 粗控，**推送数据的细粒度隔离完全靠"key 里编码身份" + 服务端发布前校验**：

- 推送 key 一律含 `tenant` 与具体资源段（`petpal/{tenant}/{petId}/alarm/*`）；
- 服务端发布告警前校验 petId 归属（发布侧校验，而不是依赖订阅侧自觉）；
- App 订阅 `petpal/{tenant}/**` 收到的数据仍需按业务过滤展示（即使收不到别人租户的，也不做"收到的都信"假设）。

### 6.5 其他安全细则

| 项 | 决策 |
|---|---|
| key 内 PII | 禁止（§2.1）；资源标识用服务端短码 |
| 日志脱敏 | token/refresh 全程不落 App 日志（`ZenohRpcClient` 日志层只打 reqId 与前 6 位摘要） |
| 崩溃上报 | 走 `evt/crash`（Background 优先级 + Drop 拥塞控制），内容不含 token |
| 服务端吊销 | logout / 设置页剔除（`revokeSession`）/ 风控封禁 → 服务端把目标会话 jti 入黑名单，网关中间件即时生效（JWT 无状态要靠这层补）；多端场景按 deviceId 精确吊销单会话，不影响其他设备；密码重置吊销该 userId 全部会话（安全事件）。jti 黑名单存储：内存 LRU（按活跃会话量级）+ 持久化兜底（服务重启不失效，避免吊销被重启冲掉） |
| 登录凭据 | 密码仅内存传递（TLS 传输 + 服务端 argon2id/bcrypt 慢哈希，App 永不落盘）；OAuth 只在 App 侧持一次性 code（5min 单次消费），provider access_token / appid/secret 全部留在服务端；验证码按 scope 用途隔离（约束文档 §6.1） |
| 密钥轮换 | JWT 签名 kid 字段 + 双 key 并行验签窗口；TLS CA 双 CA 内嵌（§6.1） |

---

## 7. 文件上传下载（保留 HTTP 的边界设计）

按可行性报告结论：**二进制不走 zenoh**，但"要不要上传/下什么/谁有权传"这些元数据全部走 zenoh RPC，形成闭合：

```
┌─ zenoh RPC ────────────────────────────────────────┐
│ files/createUpload  → { ossKey, stsAccessKeyId,     │
│                          stsAccessKeySecret, stsToken, │
│                          expireAt, maxBytes, region, bucket } │
│ files/commit        → 服务端校验 sha256/size 后入库  │
│ files/getDownloadUrl → { url, expireAt }  (CDN 签名 URL) │
└────────────────────────────────────────────────────┘
┌─ HTTP 直连 ─────────────────────────────────────────┐
│ PUT https://{bucket}.oss-xxx.aliyuncs.com/{ossKey}   │  ← STS 直传，不经过业务服务器
│ GET https://cdn.xxx.com/{ossKey}?signature=...       │  ← CDN 签名 URL 下载
└──────────────────────────────────────────────────────┘
```

约束（全集见交互约束文档 §9）：单文件 ≤20MB（App 场景：头像/照片/日志包）；STS 凭证 15min 有效且限定 ossKey 前缀与 MIME；上传后必须 `commit`，否则孤儿文件定时清理；下载一律签名 URL（防直链外传），`sha256` 元数据供 App 校验完整性。

这个边界让 zenoh 链路 payload 恒为 JSON 小信封（<16KB），FFI 无需字节流通道，传输可靠性问题全部甩给成熟的 OSS/CDN。

---

## 8. 服务端 queryable 设计要点

（给出契约，具体实现语言不限；建议 Rust `zenoh` crate 或 Node/Python 官方绑定）

```
每个服务实例启动时：
  open(peer 模式, connect tls://router:7447)
  对每个域 declare_queryable("petpal/{tenant}/api/v1/{domain}/**")
  收 query → 解析 op（query.key_expr() 最后一段）→ 鉴权中间件 → 路由到 handler
  → query.reply(query.key_expr(), response_envelope_json)
  → 收到 cancel/finalize 后优雅 undeclare（发布窗口内旧实例先撤声明再退场，
    避免请求打到已死实例表现为超时——这是 RPC 形态下"发布下线"的正确姿势）
```

| 要点 | 设计 |
|---|---|
| op 分发 | 域 queryable 内部按 key 最后一段路由 handler；未知 op 回 `code=404` |
| 超时对齐 | 服务端处理超时 = 客户端 timeout（默认 5s）− 500ms 网络预算，超时自行放弃并回 504 语义（`code=504`） |
| 优雅发布 | 先 undeclare → 等待存量请求排空（≤5s）→ 进程退出；配合 App 侧重试（幂等读）实现零感知发布 |
| 存储兜底（可选进阶） | 热点只读数据（宠物品种表等）可用 router storage 插件（Book《Storages》）做 `get` 兜底：queryable 离线时 router 回缓存值，App 端无感降级；**写域绝不挂 storage** |
| 可观测 | 每请求打 `{reqId, op, uid, code, costMs}` 结构化日志；reqId 与 App 端贯通 |
| 限流 | 服务端网关层按 uid 令牌桶（10 qps / burst 20），超限回 429 + `retryAfterMs`；router ACL 无法做按用户限流（连接级粗控），必须在这层做 |

---

## 9. 实施阶段（承接可行性报告 §5，落到本文设计物）

| 阶段 | 交付物 | 验收标准 |
|---|---|---|
| P0 原生扩展 | `zffi_session_open_ex` + `zffi_session_get`；三端 `.so/.xcframework` 产出（Android 首次接入） | §5.3 清单全绿 |
| P1 RPC 骨架 | 信封 v2 codec + `ZenohRpcClient` + `TokenStore` + auth 域核心 op 打通（loginByPassword / loginBySms / refresh） | 登录→拉宠物列表全链路走 zenoh，断网/超时/401 场景单测通过；微信 OAuth（loginByOauth/bindPhone）在 P2 与各端原生 SDK 联调 |
| P2 业务迁移 | pets/devices/fences/alarms/chat 各域门面；`providers.dart` 数据源从 Mock 切 RPC | 业务全功能可用；`/zenoh-debug` API 调试 Tab 上线 |
| P3 安全加固 | tls/ 全端启用、ACL 上线、幂等/限流/日志 | 渗透用例（跨租户、重放、无 token）全部拒绝 |
| P4 文件通道 | files 域 RPC + OSS 直传/CDN 下载 | 头像上传、寻宠启事照片、日志包下载全链路 |

---

## 10. 附录：设计决策记录（ADR 摘要）

| # | 决策 | 备选 | 理由 |
|---|---|---|---|
| D1 | RPC 走操作化 key（get 语义统一） | 资源化 REST 直译 | ACL/链路/调试单一化，§3.1 |
| D2 | App 单向 TLS，不强制客户端证书 | 全端 mTLS | 移动端证书生命周期管理成本，§6.1 |
| D3 | 连接级身份用公共凭证 + 请求级用户 token | 每用户连接级凭证 | 吊销/运维成本，§6.2 |
| D4 | 权威响应取首条 ok reply 即止 | 等全部 reply_done 合并 | 降低长尾延迟；拓扑上保证单权威 queryable，§3.4 |
| D5 | 文件二进制走 OSS/CDN，zenoh 只传元数据 | zenoh 分片传输 | CDN 成本/体验不可替代，§7 |
| D6 | RPC 层 fail-loud（RpcResult），原语层保持 fail-soft | 全局 fail-soft | 防止"断网伪装成空数据"暗坑，§4.1 |
| D7 | 信封 token 内存持有不落盘 | refresh 一并落盘明文 | 攻击面收敛；refresh 用安全存储，§4.4 |
| D8 | 本轮不做 zffi_put_bytes 字节流接口 | 支持 zenoh 二进制大包 | payload 恒 <16KB，砍三端验证项，§5.1 |
