====== 目录备份、任务队列与故障恢复 ======
客户端目录备份建立在逐文件上传上。服务端没有接收一个文件夹就自动保证全部完成的事务；手机相册授权、文件枚举、队列和后台调度由客户端处理，NAS 负责已授权目录内的文件校验与发布。自动删除传播、双向冲突合并、原设备删除和全目录回滚不属于当前接口承诺。

===== APP 本地任务设计 =====
  - 取得用户明确授权的相册或目录范围，记录需要上传的文件及相对层级。
  - 查询 NAS 能力和目标范围，逐级创建目录，遇到同名项先核实其类型。
  - 为每文件计算完整 SHA-256，生成固定 requestId，保存 root/path/name/size/hash 与本地文件标识。
  - 用相同 requestId 恢复同一文件任务；元数据变化时新建任务，不能把不同内容塞进旧任务。
  - 保存服务端 uploadId、received、prefixDigest 和最终 receipt。每文件只有 committed 回执完整时才记为已备份。
  - 汇总成功、冲突、失败和不确定项；整个目录只有全部应处理文件均有结果后才结束，不能依据总发送字节数显示完整成功。

手机后台行为受 iOS、Android 和平板系统权限、休眠及调度限制，网页联调通过不能代替原生后台验收。客户端保存队列后可在下次被系统允许运行时继续；不要向用户承诺关闭应用后所有系统都持续上传。

===== 暂停、恢复与重新配对 =====
暂停应先停止发送新块，再调用对应上传 action，并保存服务器确认的状态。恢复时查询权威断点并验证已确认前缀；内存中的 16 KiB segment 进度不代表磁盘持久化。网络、进程或授权会话中断后，从服务器 received 对应的 2 MiB 边界重新发送当前未持久块。

云配对过期不等于删除已持久上传数据。重新获得同一客户端身份、账号和目录范围的授权后，再列出或读取可见任务；如果公钥、账号或目标范围改变，服务端上下文隔离可能使旧任务不可见。不能通过提交旧 uploadId 或伪造 clientContext 取回其他范围的任务。

===== 同名与提交不确定 =====
最终文件禁止覆盖。发生同名冲突，先检查目标内容与业务规则，再由用户选择另一个名字并新建任务；不能因为同名就认为已备份。commit_uncertain 表示可能已经发布而回执未能可靠保存，必须保留原件并检查目标/记录，不能自动覆盖、自动再发或删除源文件。成功回执只证明当时发布，不证明文件永远存在。

===== NAS 到云端或其他设备的备份接口 =====
这些是另一组管理员控制接口，不等于手机上传，不通过受限 WebRTC RPC 对远程 APP 开放。当前需要 Linux 主账号、符合要求的文件身份与可用云传输引擎，还要有 backup.read/manage 等原能力。
<code http>
GET /api/v1/backup/jobs
POST /api/v1/backup/jobs/preview
Content-Type: application/json

{"mode":"backup","connectionId":"<已配置连接>","root":"data","path":"<本地目录>","remotePath":"<远端父目录>"}
</code>
mode 为 backup、restore、sync。preview 返回 previewId、expiresAt、files、bytes、warnings、实际源/目标字段，可含 versionPath；有效期 5 分钟。创建只提交：
<code json>
{"previewId":"<预览ID>","confirm":true}
</code>
POST /api/v1/backup/jobs 成功为 202 queued。预览期内连接配置版本或本地目录身份变化会拒绝，不能跳过预览手工构造执行路径。状态列表 data.items 包含 id、mode、connectionId、root、path、remotePath、status、phase、progress、bytesTransferred、totalBytes、filesTransferred、totalFiles、createdAt，可含 errorCode、finishedAt 和 versionPath。

POST /api/v1/backup/jobs/{id}/pause、resume、cancel 均提交 {confirm:true}。pause/resume 只控制仍活跃的 queued/running/paused 任务；服务重启后原活动任务标记 interrupted，不承诺跨重启字节级续传。队列当前最多 4 个等待任务，保存最近 100 条记录；扫描限制包括深度 64、条目 100000 和 15 秒预算。

完整备份创建独立 apuos-时间-ID 目标；单向 sync 写 current，被替换文件保存在 versions/任务ID，不传播源删除。restore 创建新的 restore-时间-ID 目录，避免直接覆盖业务原件。创建任务不等于自动计划运行，任务 completed 也应结合抽查和恢复演练验证。有关用户操作见 [[backup/overview|备份与恢复]]。

===== 验收矩阵 =====
至少验证：正常文件与最后不足一块、断网后恢复、ACK丢失重试、应用与 NAS 重启、过期重登录、权限撤销、目录变只读、空间不足、同名冲突、摘要错误、commit响应丢失、不同账号/公钥隔离、手机后台暂停和 NAT 无法直连。测试只用可删除的隔离目录，禁止为了证明恢复能力破坏用户业务文件。协议能运行和目标硬件全部场景已验收必须分别记录。