# 开发与配置指南

## 代码结构

| 文件 | 职责 |
| --- | --- |
| `src/main.rs` | 统一服务可执行程序入口 |
| `src/app.rs` | 共享配置、协议定义，以及按角色启动管理 API 和/或遥测处理的运行循环 |
| `src/service.rs` | 管理 RPC 的校验、分发及 Redis 存储 |
| `src/service/auth.rs` | 注册、登录、短信、设备会话、证书签发和心跳 |
| `src/service/collars.rs` | 项圈开通、绑定、数据流分享、用户级设备设置和发布者检查 |
| `src/service/geofence.rs` | 地理坐标校验、凸多边形验证及圆形/多边形围栏包含判断 |
| `src/service/telemetry.rs` | GPS/IMU/系统信息校验、Ed25519 验签、重放保护、已验证 IMU 发布、行为结果/围栏告警和会话数据转发 |
| `src/service/sms.rs` | 阿里云短信请求签名和发送 |
| `src/redis_store.rs` | 按 tenant 隔离的 Redis key 和共享持久化操作 |
| `src/tests.rs` | 不依赖在线 Redis 或 Zenoh 的单元测试 |
| `src/bin/api_test.rs` | Zenoh API 集成测试客户端 |
| `src/bin/collar-simulator.rs` | 签名发布系统信息、按已应用配置发布 GPS/IMU，并模拟寻宠和用户级设置控制的项圈测试程序 |
| `src/bin/behavior-processor.rs` | 独立行为处理服务：订阅已验证 IMU、运行启发式分类并发布行为结果；结果标记为模拟 |
| `scripts/test-apis.sh` | 使用 `z_get` 进行集成测试和异常场景验证 |

`pet_collar_service --role api` 声明三个管理 API queryable；`--role telemetry` 订阅
GPS、IMU、系统信息和行为结果 topic，保存系统信息、转发 GPS、向行为处理器发布验证后
的 IMU、分发行为结果并检查 Redis 健康状态。不传 `--role` 时同时运行两者，是默认的本地
开发模式。服务启动时从最终解析出的配置创建共享 `RuntimeConfig` 和 Redis client；API 与
遥测各自通过该 client 建立 multiplexed connection，并在断线后重连。默认服务实例
都会提供管理 API，但只有取得 Redis 租约的实例会声明遥测订阅；同一 tenant 的多个实例
因此可以共同承载 API Query，同时由单个遥测实例消费 Pub/Sub。租约每 5 秒续期，TTL 为
15 秒；持有者退出或失联后，其他实例可在租约过期后接管。这是遥测单活故障切换，不是
遥测并行负载均衡。严格扩展遥测吞吐量仍需按项圈分区队列/消费者组。行为分类仍由独立的
`behavior-processor` 二进制运行。

## 配置

配置可来自命令行参数、环境变量或 YAML，优先级依次为：
**命令行 > 环境变量 > YAML > 内置默认值**。未知 YAML 字段会被拒绝。
请复制 [service.example.yaml](../service.example.yaml) 到私有配置文件；不要把真实
凭据写入版本库。

| 配置项 | 命令行参数 | 环境变量 | YAML 字段 |
| --- | --- | --- | --- |
| 服务角色 | `--role api|telemetry`（默认同时启动两者） | — | — |
| Zenoh endpoint | `--zenoh-router-endpoint`（`--endpoint`） | `ZENOH_ROUTER_ENDPOINT` | `zenoh_router_endpoint` |
| Redis URL | `--redis-url` | `REDIS_URL` | `redis_url` |
| Tenant | `--tenant` | `ZENOH_TENANT` | `tenant` |
| 项圈开通口令 | `--collar-provisioning-token` | `COLLAR_PROVISIONING_TOKEN` | `collar_provisioning_token` |
| 客户端 CA 证书 | `--zenoh-client-ca-cert-path` | `ZENOH_CLIENT_CA_CERT_PATH` | `zenoh_client_ca_cert_path` |
| 客户端 CA 私钥 | `--zenoh-client-ca-key-path` | `ZENOH_CLIENT_CA_KEY_PATH` | `zenoh_client_ca_key_path` |
| Router 信任 CA | `--zenoh-router-root-ca-cert-path` | `ZENOH_ROUTER_ROOT_CA_CERT_PATH` | `zenoh_router_root_ca_cert_path` |
| 服务客户端证书 | `--zenoh-router-client-cert-path` | `ZENOH_ROUTER_CLIENT_CERT_PATH` | `zenoh_router_client_cert_path` |
| 服务客户端私钥 | `--zenoh-router-client-key-path` | `ZENOH_ROUTER_CLIENT_KEY_PATH` | `zenoh_router_client_key_path` |
| 阿里云短信配置 | `--alibaba-cloud-access-key-id`、`--alibaba-cloud-access-key-secret`、`--aliyun-sms-sign-name`、`--aliyun-sms-template-code` | `ALIBABA_CLOUD_ACCESS_KEY_ID`、`ALIBABA_CLOUD_ACCESS_KEY_SECRET`、`ALIYUN_SMS_SIGN_NAME`、`ALIYUN_SMS_TEMPLATE_CODE` | `sms.access_key_id`、`sms.access_key_secret`、`sms.sign_name`、`sms.template_code` |

`zenoh_router_endpoint` 的 scheme 决定进程连接 Router 的传输方式：`tcp/host:port`
使用明文 TCP；`tls/host:port` 使用 mTLS，并要求配置 Router 信任 CA 和该进程的
客户端证书及私钥。若管理服务需要处理 `auth/issueZenohCredential`，还要配置 APP
证书签发 CA；遥测服务不需要这些签名密钥。将私钥保存在有访问控制的部署目录中。
生产环境应通过密钥管理服务或受限环境变量注入机密，不要通过命令行参数传递。

使用配置文件启动：

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

生产环境推荐以相同配置启动多个统一服务副本；省略 `--role` 即同时运行管理 API 与遥测：

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

以上命令由部署平台启动多个副本。所有副本必须使用相同 tenant、Redis、Router、开通配置、
短信设置和 APP 证书签发配置。配置、环境变量和部署密钥应通过受限的部署系统注入。若设置
`REDIS_URL` 或传入 `--redis-url`，仍按 **CLI > 环境变量 > YAML** 优先级覆盖 YAML；
请确保各实例解析出的 Redis URL 完全一致。需要以 YAML 为准时，取消 `REDIS_URL` 并省略
`--redis-url`。也可使用 `--role api` / `--role telemetry` 分别部署；多个遥测角色同样由
Redis 租约限制为一个活跃消费者。

本地开发时先启动 Zenoh Router 和 Redis。默认 Zenoh endpoint 为
`tcp/127.0.0.1:7447`；Redis URL 应包含适用于本地实例的连接信息和认证配置。
随后启动统一服务进程：

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

## 配置行为

- Debug 构建在完整配置阿里云短信时会发送真实短信；未配置时仅供本地联调。
  debug 响应和服务终端都会显示验证码。
- Release 构建必须配置阿里云短信并发送成功；验证码只保存在服务端，不在响应或日志中显示。
- 短信模板必须接收 `code` 和 `time` 两个参数；`time` 表示十分钟。
- API 和遥测角色可使用配置的 Router endpoint，通过 `tcp/` 明文或 `tls/` mTLS 连接。
  默认同时启动两者时使用同一 Router 身份；行为处理器是独立进程，若需安全隔离，应为其单独
  配置 Router 身份和 ACL。
- 只要配置 APP 签发 CA，管理服务就可以签发 APP 会话证书；这与管理服务连接
  Router 时使用 TCP 或 TLS 无关。APP/项圈客户端 endpoint 和 Router listener
  需要分别配置。
- 服务不会管理 Router 信任设置、mTLS listener 或 topic ACL。部署安全职责见
  [架构与安全边界](./architecture.md#部署侧安全职责)。
- 项圈模拟器和行为模拟器只用于本地联调；模拟行为结果不是生产算法。启动与使用
  方法见[遥测测试指南](./testing.md#7-遥测和安全边界验证)。

## Redis 数据

Redis key 按 tenant 命名空间隔离。逻辑数据包括：

- 手机号索引和用户认证记录；
- 设备会话、access/refresh token 索引（仅保存 token 的哈希）；
- 短时有效的短信验证码和验证锁；
- 项圈配对码哈希、遥测公钥、用户绑定和数据流权限；
- 最新项圈系统信息；
- 短时有效的分享邀请、在线会话租约和各遥测流的序号高水位。

具体 key 名称以 [redis_store.rs](../src/redis_store.rs) 为准。不要通过清空共享
Redis 数据库来重置测试；请使用专用 tenant/数据库，并按
[测试指南](./testing.md)中的建议清理测试数据。

## 新增 RPC

1. 在 `src/service.rs` 的分发逻辑中实现操作，并在 `src/app.rs` 的支持操作列表中注册。
2. 在相应的 `src/service/*.rs` 模块中实现业务逻辑。
3. 如果操作允许省略 `deviceId`，更新其校验规则和测试客户端行为。
4. 添加有针对性的单元测试；Redis/Zenoh 行为通过集成客户端验证。
5. 更新 [Zenoh RPC API 契约](./zenoh-rpc-api.md)及相关测试覆盖。

不要把业务逻辑放进 Zenoh 接收循环。新增公开域之前，必须同时补充 API 契约并
检查部署侧 ACL。
