ApuClient 开发者接入指南

本指南面向 Flutter、iOS、Android、平板和电脑客户端的开发人员。目标是使用同一套 NAS 文件权限、文件浏览、断点传输和最终提交语义；局域网使用 HTTP，经过用户批准的远程连接使用 WebRTC 受限 RPC。这里的“目录备份”指客户端枚举文件并逐项上传，不代表双向同步、删除传播、全目录事务或后台系统权限已经由服务端自动完成。

1. NAS 认证、目录和 HTTP 文件接口：先完成登录、根目录选择、分页和普通下载。
2. 持久上传、断点摘要与提交回执：实现任务数据库、分块校验、暂停恢复和成功判定。
3. 云端发现、配对与签名：实现设备身份、短码配对、所有者批准及信令验证。
4. WebRTC v1 与受限 RPC：在同一业务语义上建立直连，不把云信令当数据通道。
5. 既有文件互传 HTTP 协议：兼容旧peer配对、任务与缓存下载。
6. 目录备份、任务调度与故障恢复：处理手机系统限制、队列、云备份和恢复语义。

NAS 登录 Bearer 用于 NAS API；云端 sync Bearer 只用于发现与信令；旧文件互传 peer 的 claimToken 只用于其自己的 peer 接口。云服务不会因为配对就获得 NAS 文件权限，APP 也不能把 cloud Bearer 发给 NAS 登录接口。私钥、NAS 密码、配对码和会话令牌不进入公开日志、URL 或普通偏好设置。

客户端应先查询 capabilities，以实际可用功能和版本决定路径。旧 WebRTC 单文件 begin/data/commit 与新版持久上传协议共存，限制和断点语义不同；保留 hello 字段并不表示它的旧文件大小上限适用于所有新操作。产品升级前，必须验证目标 NAS 已安装相应接口，而不是仅根据本文存在就假定旧版本可调用。

一次上传必须具备服务器已提交的回执，且路径、长度和 SHA-256 与本地预期一致。只收到网络 ACK、进度达到百分之百、传输缓存 ready 或云 mailbox delivered 都不能视为最终文件成功。下载必须正确处理 HTTP 200/206/416、文件变化与本地部分文件，目录任务应保存逐文件结果而不是一条笼统成功记录。

代码配套说明位于 NAS 项目 docs/APP-SYNC-API.md；云协议位于 apuos-server/docs/SYNC-PROTOCOL.md。两项目独立发布，联调时记录实际版本和提交；真机后台权限、移动网络、不同 NAT 与原生平台构建需单独验收。

NAS仓库 docs/backup/app-sync-operations.json 提供12项显式操作的必填/可选字段、请求样例、响应字段、权限和限制，并描述HTTP与WebRTC封装。它是轻量操作目录，不宣称完整OpenAPI或自动生成SDK；运行时仍先读取capabilities，真正的安全校验以NAS实现为准。

例如HTTP请求为下列结构；同一operation/params放入WebRTC的rpc命令即可，但远程root与path受批准目录约束，不直接照搬HTTP绝对范围。

{"operation":"uploads.list","params":{"offset":0,"limit":16}}

uploads.create内的requestId要由APP生成并长期保存；示例中的占位ID不能在所有任务中复用。HTTP NAS响应有data外层，云同步响应是裸JSON对象，WebRTC又是rpc-result封装，开发时使用三个明确解析入口，不用一个模糊“通用请求”把字段混合。