# 架构与安全边界

## 系统范围

应用由 Rust Zenoh peer `pet_collar_service` 和 Redis 组成。该二进制默认同时运行管理 API
和遥测处理，也可用 `--role api` 或 `--role telemetry` 单独启动：API 角色通过 `auth`、
`users` 和 `collars` RPC 域管理
用户、APP 设备会话和项圈；遥测角色接收经过签名验证的项圈遥测，并向 APP 会话 topic
发布符合权限条件的数据。当前 wire 协议见
[Zenoh RPC API 说明](./zenoh-rpc-api.md)。

## 项圈标识与租户隔离

系统业务规则要求 `collarId` 跨所有 tenant 全局唯一且不可变。设备出厂/资产系统必须为
每台物理项圈分配一个 UUID 或厂商序列号；更换硬件视为新设备并分配新 ID，不能复用旧
项圈 ID。建议采用标准 UUID，或经规范化的厂商序列号（1–128 个 ASCII 字母、数字及
`-_.:`）。客户端和日志应把 `(tenant, collarId)` 作为完整资源键，同时保证 `collarId`
本身不会在其他 tenant 被重新分配。

Redis 键和 Zenoh topic 仍按 tenant 分区，因此同一个 ID 出现在两个 tenant 时，当前实现
会将它们作为两条独立记录处理；这不符合全局唯一的业务规则。`collars/provisionCollar`
目前只校验 ID 格式并写入 tenant-scoped 记录，不查询全局资产注册表，也不拒绝跨 tenant
重复 ID。同一 tenant 内重复开通会覆盖已登记的配对码和遥测身份并保留绑定关系。全局唯一
性和不可变性必须由制造/资产发号系统与开通流程保证；不要把 tenant 隔离误认为 ID 冲突保护。

## 运行时数据流

管理服务为每个 RPC 域声明一个 queryable：

```text
petpal/{tenant}/api/v1/auth/**
petpal/{tenant}/api/v1/users/**
petpal/{tenant}/api/v1/collars/**
```

遥测服务订阅以下经过签名的源 topic：

```text
petpal/{tenant}/api/v1/collars/reportGps/{collarId}
petpal/{tenant}/api/v1/collars/reportImu/{collarId}
petpal/{tenant}/api/v1/collars/reportSystemInfo/{collarId}
```

Redis 保存用户记录、不透明 token 的哈希、设备会话、项圈绑定、分享权限和在线
会话租约。启动时从同一解析后的 `redis_url` 创建共享 Redis client；管理 API 和遥测
处理分别通过该 client 建立连接，连接或健康检查失败时各自尝试重新连接。角色拆分后
每个进程会独立读取配置并建立连接，部署时必须确保解析出的 Redis URL 相同。

API 副本共享 tenant、Redis、Router 和 API 凭据；Zenoh 默认的 BestMatching query 路由
将一次请求交给匹配的 queryable。多个统一服务实例均可提供 API，但通过 Redis 中
tenant-scoped 的短期租约选出单个遥测处理者；租约持有者每 5 秒续期、15 秒过期，失联后
其他实例可接管。Pub/Sub 样本不会被多个活跃遥测副本重复消费，因此这提供统一服务的 API
负载均衡和遥测故障切换，而非遥测吞吐量扩展。遥测多活仍需先引入按项圈分区的队列或消费者组。
各服务进程连接 Router 时可以使用
`tcp/` 或 `tls/`；该设置只控制服务进程到 Router 的链路。Router 监听器和客户端传输方式
需要分别配置。

## APP 会话

登录时，服务会在 APP 设备会话之外创建随机 `sessionId`。客户端在本机生成私钥和
CSR；`auth/issueZenohCredential` 使用配置的客户端 CA 签署 CSR，并返回有效期为
五分钟的客户端身份验证证书。私钥不会发送给服务端。

通过身份验证的 APP 调用 `users/telemetryHeartbeat` 续租，在线租约有效期为
60 秒。服务只向仍持有有效租约的会话发送遥测。登出或移除设备时，服务会清理对应
租约。

每个 APP 会话使用独立 topic 接收数据：

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

服务仅向在线且绑定/获分享项圈访问权的 APP 会话发布被授权的流。分享权限中的
`gps` 控制 GPS 与围栏告警；`imu` 控制行为识别结果，不代表 APP 可以订阅原始 IMU。
各会话通过自身证书和 Router ACL 只能订阅自己的会话 topic。
分享邀请 900 秒有效且只能接受一次；邀请人可授予 `gps`、`imu` 或两者。

## 电子围栏

任一已绑定用户可通过 `collars/setGeofence` 为项圈设置共享围栏，包含 APP 固定地图
中心和可选的凸多边形顶点；没有多边形时，使用该中心周围 2 公里的圆形边界。没有
收到 APP 中心前不执行围栏判断。每个有效 GPS 样本在验签和序号检查后立即与围栏比较；
进入边界外时只发送一次告警，回到边界内后重新布防。边界更新会重置状态，下一个 GPS
样本重新判定。

告警以 `geofence` 流发送到项圈的所有在线、绑定/获分享权限且具有 GPS 流权限的 APP
会话。告警是边沿触发的临时事件，不保存历史、不补发；没有在线接收者时不会在之后
上线时重播。Redis 保存共享边界和当前 inside/outside 状态。

## 用户级项圈设置

服务在 Redis 中按 `(userId, collarId)` 保存蜂鸣器、LED、IMU 批量上传周期和 GPS 上报周期。
注册/登录成功响应一次性包含用户已绑定项圈的 `collarSettings`。默认蜂鸣器和 LED 关闭，
IMU/GPS 周期均为 1 秒；周期范围 1–60 秒。

用户显式更新设置后，服务持久化用户偏好，并将完整设置及单调递增的设备版本下发给在线
项圈：

```text
petpal/{tenant}/internal/collars/{collarId}/commands/setCollarSettings
```

登录仅同步偏好到 APP，不自动应用到设备；离线更新返回 `pending`，用户需在设备在线时显式
重试。共享项圈上，各用户偏好独立保存，实际硬件状态由最近一次成功应用的完整设置决定。

## 一键寻宠

已绑定项圈的任意用户（包含接受分享邀请的用户）可调用 `collars/findPet`。管理服务
验证 access token 和绑定关系后，向项圈专属控制 queryable 发送带随机 `commandId`
的寻宠请求。项圈应同时启动闪灯和蜂鸣器，确认启动后回复；管理服务校验命令 ID、
项圈 ID、持续时间及 `startedAt` 后才向 APP 返回成功。默认持续 30 秒，APP 可指定
5–120 秒。服务最多等待设备确认 5 秒；设备离线或未确认时返回超时/错误，不会伪报
执行成功。

```text
petpal/{tenant}/internal/collars/{collarId}/commands/findPet
```

此 topic 使用 Zenoh Query/Reply：项圈为自己的 key 声明 queryable，管理服务发起
精确 key 查询。请求包含 `commandId` 和 `durationSeconds`；设备回复 `status=started`
或 `status=rejected`。Router ACL 必须只允许管理服务向控制 key 发起查询，并只允许
对应项圈声明自己的控制 queryable。仓库模拟器只记录模拟的灯光/蜂鸣器动作，不会
驱动物理硬件；固件需实现该协议并在真实输出启动后回复。

## 遥测接入与系统信息

项圈开通时，管理员登记项圈专属的 Ed25519 `keyId` 和公钥。项圈对每个样本签名；
网关可以转发样本，但不得替换项圈签名。

遥测服务先校验源 topic、信封、payload 结构和值范围、登记的 key ID、公钥签名，
以及项圈每个遥测流递增的序号。通过检查的 GPS 会被转发到有 GPS 权限的在线 APP
会话。系统信息和对应序号会原子保存，并可由已绑定用户通过 `collars/getSystemInfo`
查询。项圈 IMU 验证后交由独立行为识别流程处理，详见下节。

## 行为识别

行为识别是独立的 IMU 订阅、分析和结果分发流程，不是 APP 调用的 RPC：

1. 遥测处理验证项圈 IMU 签名、数据范围和单调序号后，发布已验证样本：
   `petpal/{tenant}/internal/collars/{collarId}/imu`。
2. `behavior-processor` 订阅该内部 topic，按项圈维护 100 帧滑动窗口，每次滑动 50 帧。
   默认 50 Hz 时每窗约 2 秒，约每秒输出一次。处理器从去均值加速度 RMS、各轴/合成
   角速度 RMS、加速度幅值峰值、角速度积分旋转量和周期频率等特征计算行为类别；静止
   姿势还参考 body 坐标系重力主轴与静止时长。它处理 IMU 特征，不从输入中复制行为标签。
3. 处理器将结果发布到 `petpal/{tenant}/api/v1/collars/reportBehavior/{collarId}`。
   遥测服务订阅结果，验证 envelope、项圈 ID、行为类别和结果序号，再由 APP 会话租约、
   项圈绑定/分享关系及 `imu` 权限筛选接收者。
4. 每个符合条件的在线 APP 会话收到自己的 topic：
   `petpal/{tenant}/users/{userId}/sessions/{sessionId}/telemetry/{collarId}/behavior`。
   APP 订阅此结果 topic，不订阅内部 IMU，也不能向结果 topic 发布识别结果。

识别标签使用英文机器值，并在文档中配有中文含义：`feeding`（进食）、`jumping`（跳跃）、
`playing`（逗猫）、`scratching`（磨爪）、`rolling`（打滚）、`running`（奔跑）、
`licking_fur`（舔毛）、`lying_down`（趴着）、`sleeping`（睡觉）、`standing`（站着）、
`walking`（走路）、`sitting`（坐着）和 `unknown`（未知）。

仓库内的 `behavior-processor` 当前是启发式原型，未使用经训练和验证的生产模型，结果
标记为 `simulated: true`，不应作为实际识别准确率承诺。输入、内部 IMU、处理器结果和
APP 下行均使用尽力而为投递，不保存行为历史、不保证送达或补发。处理器未运行时，
内部样本可能丢失；遥测服务已接受的 IMU 序号不会因处理器恢复而重放。

## 部署侧安全职责

- 使用网络策略、认证和 TLS 保护 Redis 与 Router。
- 将客户端 CA 私钥保存在版本库之外，并限制访问权限。
- 配置 Router 信任客户端 CA，并对每个 APP 会话 topic 执行默认拒绝、基于证书
  subject 的 ACL。服务签发证书**不会**自动配置或执行 Router ACL。
- `zenoh_router_endpoint` 决定服务自身到 Router 的传输方式：`tcp/` 为明文，
  `tls/` 使用 mTLS。这不会修改 Router 监听器或 APP/项圈客户端的连接方式。
  TCP 监听器仍是明文，不会自动获得 mTLS 保护。
- 仅允许可信网关调用 publisher 检查 RPC。该检查不是发布者身份认证；每个样本
  仍必须进行 Ed25519 签名验证。
- 使用 Router ACL 限制内部 IMU 和行为结果 topic。内部 IMU 只允许遥测角色发布、
  算法订阅；行为结果只允许算法发布、遥测服务订阅，防止未授权客户端注入数据。
- 使用 Router ACL 限制寻宠控制 queryable：只允许管理服务查询对应项圈的控制 key，
  项圈只声明自身 key；APP 不得直接向控制 topic 发送命令。
- 按 APP 会话限制 `geofence` 告警 topic 的订阅权限；围栏更新只能经管理 RPC 完成，
  且调用用户必须当前绑定该项圈。
- 使用独立的项圈开通口令，并限制开通凭据的访问范围。

## 当前限制

- 本版本库不包含 Zenoh Router 配置或 ACL 吊销适配器。生产环境的会话隔离依赖
  部署侧正确配置 ACL。
- 服务会拒绝重放的遥测序号，但尚未限制样本速率或样本最大时间跨度。
- 遥测为临时、尽力而为数据，不提供历史重放。
- OAuth、密码重置和手机号绑定接口已注册，但目前固定返回 `503`。
