客户端同步备份功能产品需求文档 PRD

配套原型交互稿说明：[[我的笔记/NAS需求文档/同步备份/Figma原型交互稿说明（PC端+移动端）]]

1. 文档信息

项目	内容
产品名称	客户端同步备份
所属模块	NAS 客户端 / AWOL backup 应用
文档类型	产品需求文档（PRD）
版本号	v1.0
文档状态	待评审
创建日期	2026-04-24
更新日期	2026-05-05
参考资料	[[客户端备份功能615需求说明]]、[[我的笔记/NAS需求文档/同步备份/备份功能说明（PRD表格版）]]、[[我的笔记/NAS需求文档/同步备份/API_REFERENCE]]

---

2. 需求背景

当前客户端已具备基于 Zima OS 的同步与备份能力，但现有材料主要聚焦能力清单和界面草图，尚未形成一份对功能范围、状态流转、异常处理和边界条件定义清晰的需求文档。本期需要基于现有备份能力，对同步备份功能进行产品化定义，形成一套可直接供产品、设计、研发评审的同步备份 PRD。

需要解决的问题主要包括：

1. 用户缺少统一入口来创建和管理备份任务；
2. 用户不清楚自动备份的触发条件、生效范围和限制；
3. 任务状态、进度、失败原因与恢复路径定义不够清晰；
4. 排除规则、自动触发等配置能力缺少明确边界；
5. 多任务场景下缺少统一的任务级规则定义。

---

3. 产品目标

3.1 业务目标

1. 建立客户端统一的备份任务模型和规则定义；
2. 提升备份任务创建成功率与首次执行成功率；
3. 通过清晰的状态与异常定义降低研发和产品理解偏差；
4. 为后续任务详情、失败项管理、策略扩展能力打基础。

3.2 用户目标

1. 用户可以快速创建一个从本地到 NAS 的备份任务；
2. 用户可以明确每个任务当前所处状态；
3. 用户可以理解自动备份和排除规则的含义；
4. 用户在任务失败后可以获得清晰的原因和恢复路径；
5. 用户可以长期管理多个备份任务而不混淆。

---

4. 目标用户

1. NAS 客户端用户：希望把电脑或移动设备中的工作文件、项目文件、资料库备份到 NAS；
2. 多目录整理用户：需要长期管理多个本地目录到 NAS 的备份关系；
3. 轻运维用户：希望通过简单配置获得稳定可重复的自动备份能力；
4. 高价值资料用户：对数据安全敏感，关注备份成功率与结果可见性。

---

5. 产品定位

客户端同步备份是 NAS 客户端中的基础数据保护能力模块，负责将当前设备本地目录备份到 NAS 目标目录，并在应用进程存在时根据源目录内容变化自动触发备份任务，提供任务创建、任务执行、任务状态展示、异常恢复和排除规则配置能力，是后续文件管理、自动归档和跨端访问能力的重要底层模块。

---

6. 功能范围

6.1 本期范围

1. 客户端 AWOL backup 应用入口；
2. 新建备份任务；
3. 基础路径配置：源路径、目标路径；
4. 任务配置：排除规则、自动备份；
5. 任务列表展示：状态、进度、文件数、最近执行时间；
6. 任务操作：暂停、恢复、取消、删除；
7. 任务结果反馈：运行进度、完成、失败；
8. 异常提示与恢复机制；
9. 多任务管理。

6.2 非本期范围

1. 文件级失败清单管理页；
2. 完整任务历史版本追溯；
3. 备份内容差异对比页；
4. 双向同步、冲突解决机制；
5. 复杂的可视化规则编排器；
6. 任务编辑能力。

---

7. 核心用户场景

场景 1：首次创建备份任务

用户第一次打开 AWOL backup，希望快速选择本地目录和 NAS 目标目录，创建第一个备份任务。

场景 2：管理多个备份任务

用户已经存在多个任务，希望在任务列表中快速查看它们各自的状态，并按需暂停、恢复、取消或删除。

场景 3：本地目录变更后自动备份

用户创建任务后，继续在当前设备的源目录中新增、修改或删除文件，希望应用在进程存在时自动检测变化并触发备份。

场景 4：排除无效目录

用户希望排除 node_modules、缓存目录或临时文件，避免占用 NAS 空间和备份时间。

场景 5：失败后恢复

用户在任务过程中遇到 NAS 不可达、网络中断、目标路径不可写或空间不足，希望看到清晰提示并可直接重试或恢复。

---

8. 业务流程

flowchart LR
    A[打开 AWOL backup 应用] --> B{是否已有备份任务}
    B -- 否 --> C[创建任务]
    B -- 是 --> D[查看任务列表]
    C --> E[配置源路径 目标路径 排除规则]
    E --> F{配置校验是否通过}
    F -- 否 --> G[提示错误并修正]
    F -- 是 --> H[任务创建完成]
    H --> I[idle]
    D --> I
    I --> J{应用进程存在且源目录内容变动}
    J --> K[running]
    K --> L{执行结果}
    L -- 成功 --> M[completed]
    L -- 失败 --> N[error]
    L -- 暂停 --> O[paused]
    O --> P[resume]
    P --> K

---

9. 功能定义

9.1 功能清单总表

功能模块	功能点	是否本期支持	定义
应用入口	AWOL backup 入口	是	提供客户端统一入口进入同步备份功能
任务创建	新建备份任务	是	为单个源路径与单个目标路径建立一条备份任务
任务配置	源路径配置	是	选择当前设备本地目录作为备份源
任务配置	目标路径配置	是	选择 NAS 目录作为备份目标
任务配置	排除规则	是	使用多条 glob 规则排除文件或目录
任务配置	自动备份	是	应用进程存在时，无论前台或后台，检测到源目录内容变化后自动触发任务
任务管理	查询任务列表	是	查询所有任务的状态、进度、时间信息
任务管理	暂停任务	是	对运行中的任务执行暂停
任务管理	恢复任务	是	对暂停中的任务恢复执行
任务管理	取消任务	是	对当前任务执行取消；取消后下次文件变动触发备份任务时继续执行备份
任务管理	删除任务	是	删除任务配置，删除任务不影响已备份的文件
执行反馈	进度反馈	是	返回进度百分比、速度、已传输、总量、剩余时间、当前文件
执行反馈	完成反馈	是	返回耗时、总文件数、总大小
执行反馈	错误反馈	是	返回错误信息和可选错误码

9.2 任务模型定义

字段	类型	是否必填	说明
id	string	是	任务 ID
name	string	是	任务名称；已用户选择的源路径名来自动命名，不支持修改
source	string	是	本地源路径
destination	string	是	NAS 目标路径
status	enum	是	idle / running / paused / completed / error
config.exclude	string[]	否	排除规则，glob 模式
config.autoBackup	boolean	否	自动备份开关；若研发未提供显式字段，则作为产品侧默认能力处理
createdAt	number	是	创建时间
lastRunAt	number	否	最近执行时间
updatedAt	number	否	最近状态或进度更新时间

9.3 任务创建定义

1. 一个任务必须且只允许绑定一个源路径和一个目标路径；
2. 用户可创建多个任务；
3. 源路径为当前设备本地目录，目标路径为 NAS 目录；
4. 创建时可同时配置排除规则；
5. 自动备份为本期核心能力，应用进程存在时生效；
6. “创建即启动首次扫描”创建完成后的默认状态定义为 idle 空闲状态；立即过渡到 running 运行状态
7. 任务创建后应进入任务列表，并可展示后续执行状态与进度。

9.4 任务执行定义

1. 本期任务执行以自动触发为主：应用进程存在时，无论前台或后台，检测到源目录内容变化后自动触发任务；
2. 任务运行期间需持续上报进度；
3. 运行完成后上报统计结果；
4. 运行失败后返回错误信息；
5. 任务支持暂停与恢复；
6. API 文档未明确独立的 start 接口，因此“用户主动开始任务”是否作为入口能力需研发确认；
7. 取消任务后，文档未明确其最终状态枚举值。

9.5 自动备份定义

项目	定义	当前待确认点
生效条件	AWOL backup 应用进程存在	进程被完全退出后是否仍有系统级后台能力待确认
生效范围	前台运行、后台运行均应生效	不同端侧的后台保活能力待确认
触发条件	源目录内文件或目录发生新增、修改、删除等变化	本地删除不影响 NAS 侧（本地删除，NAS 不自动删除）
触发对象	单个任务绑定的源路径与目标路径	同一路径被多个任务监听时的处理策略待确认
执行策略	变化触发后启动对应任务，并更新任务状态与进度	高频变更下的合并、去抖、排队策略待确认

9.6 排除规则定义

1. 排除规则类型为 string[]；
2. 每条规则采用 glob 模式；
3. 可同时配置多条规则；
4. 可排除文件类型，也可排除目录及其内容；
5. 典型示例：*.tmp、*.log、node_modules/**、dist/**；
6. 是否支持取反、完整 glob 变体、路径匹配基准未在 API 中说明。

9.7 任务操作定义

1. 暂停任务：仅对 running 状态任务生效；暂停后进入 paused 状态；
2. 恢复任务：仅对 paused 状态任务生效；恢复后进入 running 状态；
3. 取消任务：用于终止当前正在执行的任务；取消后的任务状态待研发确认；
4. 删除任务：用于删除任务配置；是否同时删除 NAS 上已备份文件待确认；
5. 查询任务列表：用于获取所有任务状态、进度、时间信息和错误摘要。

---

10. 状态定义

10.1 状态枚举

状态	英文枚举	定义	可进入下一状态	备注
无任务	-	系统中尚未创建任何任务	创建任务	UI 概念，不属于任务枚举
空闲	idle	任务已创建但当前未执行	running / paused* / error*	paused/error 是否可直接进入取决于实现
运行中	running	任务正在扫描或传输数据	paused / completed / error	需实时刷新进度
已暂停	paused	任务被用户或系统中断并暂停	running / error	支持恢复
已完成	completed	本轮任务成功结束	running / idle	再次执行后的回流状态待确认
失败	error	本轮任务执行失败	running / idle	需保留失败原因

10.2 状态流转

text
无任务 -> idle -> running -> completed
                -> paused -> running
                -> error

补充说明：

1. API 明确给出了 idle / running / paused / completed / error；
2. API 提供 cancel 操作，但没有明确 cancelled 状态枚举；
3. 因此本期不将“已取消”定义为正式任务状态，待研发确认后补充。

10.3 状态展示要求

1. 每个任务必须展示当前状态；
2. running 状态下必须展示实时进度；
3. completed 状态下必须展示最近一次成功执行时间；
4. error 状态下必须展示错误摘要；
5. paused 状态下必须可被识别为“可恢复”状态。

---

11. 异常情况定义

11.1 异常清单

异常类型	触发条件	影响范围	系统处理	用户反馈	恢复方式
源路径不存在	源目录被删除、移动	单任务	阻止启动或中断任务	提示重新选择源路径	修正源路径后重新执行
源路径无权限	本地目录无读取权限	单任务	阻止启动或中断任务	提示授权或更换目录	权限恢复后重试
目标路径不存在	NAS 目录不存在	单任务	启动失败或尝试创建	提示检查目标路径	目标路径修正后重试
目标路径不可写	NAS 无写权限	单任务	启动失败或执行失败	提示检查权限	权限修复后重试
NAS 不可达	设备离线、连接失败	单任务 / 多任务	任务暂停或失败	引导检查 NAS 连接	恢复连接后继续
NAS 空间不足	可用空间低于任务需求	单任务	任务失败或暂停	提示清理空间	空间恢复后重试
网络异常	网络断开、链路中断	单任务 / 多任务	暂停或失败	提示网络异常	网络恢复后继续
单文件读取失败	文件损坏、被占用	单任务局部	跳过或记录失败项	展示失败摘要	支持后续重试
配置非法	路径格式错误、排除规则格式错误	单任务	禁止创建	给出具体错误提示	修正配置后保存
任务被取消	用户主动取消	单任务	终止当前执行	提示已取消	后续重新执行待确认

11.2 异常处理原则

1. 配置类异常应在创建或保存阶段前置校验；
2. 运行类异常应尽量保留现场信息，不可只返回“失败”；
3. 单文件失败不应默认拖垮整个任务，除非错误达到任务级别；
4. 用户可恢复的异常应提供明确下一步指引；
5. 对于多任务场景，单任务异常不应影响其他任务。

11.3 异常恢复要求

1. 网络恢复后允许任务继续执行；
2. NAS 连接恢复后允许继续或重试；
3. 路径修复后任务可重新启动；
4. 若仅部分文件失败，应支持后续失败项重试；
5. 所有异常都应保留可追踪的任务级错误信息。

---

12. 边界条件与业务规则

12.1 能力边界

边界项	当前定义
自动备份生效条件	应用进程存在时生效，前台和后台均应支持
自动备份触发条件	监听源目录内容变化后触发对应任务
任务数量	支持多个任务，未见上限定义
源路径数量	单任务单源路径
目标路径数量	单任务单目标路径
排除规则数量	支持多条，未见上限定义
任务编辑	API 文档未体现编辑接口
任务启动	API 文档未体现独立 start 接口，需确认
删除语义	仅删除任务配置还是同时删除远端文件，未明确
取消后的状态	未明确

12.2 创建边界条件

1. 源路径不能为空；
2. 目标路径不能为空；
3. 源路径必须可访问；
4. 目标路径必须存在或可创建，并可写；
5. 若配置排除规则，必须符合可接受的 glob 语法；
6. 同一源路径是否允许创建多个指向不同目标的任务，API 未限制，本期视为允许；
7. 同一路径组合不允许重复创建完全相同任务

12.3 运行边界条件

1. 任务运行期间若配置变更，是否立即生效还是下一轮生效，待确认；
2. 任务暂停后应保留上下文，恢复时尽量延续当前进度；
3. completed 状态任务在源目录再次变化后允许重新进入执行；
4. error 状态任务允许恢复或重试；
5. 若任务处于 running，是否允许直接删除，需确认是先取消再删除还是直接删除；
6. 高频文件变化场景下应避免重复创建大量执行任务，需具备合并或排队策略。

12.4 数据展示边界条件

1. 若任务从未执行，lastRunAt 可为空；
2. 若总文件数尚未确定，可先展示已传输信息，再补全总量；
3. 若当前文件路径过长，展示层需支持截断，但数据层应保留完整值；
4. 若应用进程不存在期间发生文件变化，重新打开应用后的状态展示与补偿扫描策略待确认。

12.5 默认规则

1. 默认启用自动备份能力；
2. 默认不配置排除规则；
3. 默认创建后进入空闲态；
4. 默认按任务维度独立管理进度和执行时间；
5. 默认以源目录内容变化作为自动触发条件。

---

13. 验收标准

13.1 功能验收

1. 用户可从客户端进入 AWOL backup 应用；
2. 用户可创建首个备份任务；
3. 用户可配置源路径和目标路径；
4. 用户可配置排除规则；
5. 应用进程存在时，源目录内容变化可自动触发对应备份任务；
6. 系统可返回任务列表、状态、进度和时间信息；
7. 系统可正确展示 idle / running / paused / completed / error 状态；
8. 任务失败时可反馈错误信息；
9. 任务执行后可展示最近执行时间和传输统计。

13.2 体验验收

1. 用户可在文案层面理解自动备份的生效条件；
2. 用户可明确知道应用在前台或后台运行时均可触发自动备份；
3. 用户可明确知道排除规则支持多条且可排除文件与目录；
4. 用户可在任务列表中识别任务状态、进度和异常原因；
5. 异常提示应明确指出原因和下一步建议。

---

14. 研发实现注意事项

1. 任务状态机应独立设计，避免页面状态与后台任务状态强耦合；
2. 任务卡片、详情、事件推送应共享同一任务数据源；
3. 运行中状态建议通过事件推送更新进度；
4. 自动备份、排除规则均应在任务模型中保留或具备可回显的数据来源；
5. 自动备份需明确监听对象、触发策略、去抖策略和队列策略；
6. 若后续增加“编辑任务”，任务模型需支持配置回显；
7. 删除任务时需明确是否仅删除任务配置，不删除 NAS 上已备份文件；
8. 若研发已有独立启动接口，需补充到 API 文档与产品文档中。

---

15. 风险与待确认项

1. API 文档未体现独立 start 接口，但任务列表原型中可能存在“开始”操作，需确认真实启动方式；
2. cancel 操作后的状态名称和 UI 表现待确认；
3. 任务名称是系统默认生成还是用户可编辑，待确认；---系统默认以源路径名作为任务名，不支持用户修改
4. 排除规则是否在本期提供可视化录入，还是先使用文本规则录入，待确认；
5. 自动备份监听的是源目录还是目标目录，需结合需求说明措辞进一步确认；
6. 应用进程被完全退出后是否仍支持备份触发，需研发明确；
7. 应用进程不存在期间发生的文件变化，重新打开后是否需要补偿扫描，需研发明确；
8. 高频文件变化下的触发合并、任务排队与进度展示策略待确认；
9. 删除任务是否影响已备份到 NAS 的实际文件，待确认；
10. 相同路径组合的任务是允许重复创建

---

16. 附录

16.1 来源文档

• [[客户端备份功能615需求说明]]
• [[我的笔记/NAS需求文档/同步备份/备份功能说明]]
• [[我的笔记/NAS需求文档/同步备份/备份功能说明（PRD表格版）]]
• [[我的笔记/NAS需求文档/同步备份/API_REFERENCE]]