同步备份功能说明（从 API 文档提取）

来源：[[我的笔记/NAS需求文档/同步备份/API_REFERENCE]] 提取范围：备份 API 章节及文档中的“文件备份完整流程”示例

1. 备份能力概览

根据 API 文档，备份功能采用“创建任务 + 事件推送 + 任务管理”的模式实现。

核心能力包括：

1. 创建备份任务：指定本地源路径、设备目标路径以及备份配置。
2. 实时进度反馈：主进程持续推送进度、速度、当前文件、剩余时间等信息。
3. 完成结果通知：备份结束后返回耗时、文件数、总大小。
4. 错误上报：任务失败时推送错误信息和可选错误码。
5. 任务查询与管理：支持查看任务列表、暂停、恢复、取消、删除。
6. 定时/增量备份配置：在创建任务时可指定增量备份、排除规则、定时计划。

---

2. 备份功能点明细

2.1 创建备份任务 backup:create

用于新建一个备份任务。

调用方式：ipcRenderer.invoke('backup:create', payload)

参数结构：

• source: 源路径（本地）
• destination: 目标路径（设备）
• config.incremental: 是否增量备份，默认 true
• config.exclude: 排除规则，使用 glob 模式
• config.schedule: 定时备份计划，使用 cron 表达式

返回值：

• taskId: string：新建任务 ID

说明：

• 文档明确支持增量备份。
• 文档明确支持排除规则。
• 文档明确支持定时备份。
• 任务创建后，后续状态主要通过事件推送获取。

关于 config.incremental 增量备份开关的补充说明

API 文档原始定义为：

• incremental?: boolean
• 注释：增量备份（默认 true）

基于这段定义，可以明确确认：

1. incremental 是一个可选布尔字段，说明它不是固定不可改的系统行为，而是一个可配置项。
2. 注释写明 默认 true，因此在不传该字段时，系统会按增量备份处理。
3. 既然它是布尔开关，那么就存在与默认值相对的配置方式，即可以显式设置为 false。

也就是说，从 API 设计上判断：

• 默认行为：增量备份
• 是否可改：可以
• 改成全量的方式：创建任务时显式传 config.incremental: false

示例：默认增量备份

如果创建任务时不传 incremental：

typescript
await window.ipcRenderer.invoke('backup:create', {
  source: '/Users/xxx/Documents',
  destination: '/Data/Backup/Documents',
  config: {
    exclude: ['*.tmp']
  }
})

按文档定义，这种情况下会走默认 true，也就是按增量备份处理。

示例：改为全量备份

如果希望关闭增量备份，可在创建任务时显式传：

typescript
await window.ipcRenderer.invoke('backup:create', {
  source: '/Users/xxx/Documents',
  destination: '/Data/Backup/Documents',
  config: {
    incremental: false,
    exclude: ['*.tmp']
  }
})

这就是当前 API 文档中能够明确确认的“改为全量”的方式。

当前文档里还没有说明清楚的点

虽然可以确认 incremental: false 是关闭增量备份的入口，但 API 文档没有进一步解释“全量备份”在实现层面的精确定义，例如：

• 是否表示每次都重新完整复制全部文件
• 是否表示生成一份新的完整快照
• 是否是全量扫描后按覆盖方式同步

因此，按当前文档最稳妥的表述应当是：

incremental 默认值为 true，说明系统默认采用增量备份；如需改为非增量模式，可在创建任务时显式传入 incremental: false。但“全量”的具体执行语义，API 文档尚未展开。

关于 config.exclude 排除规则的补充说明

API 文档对排除规则的原始说明只有：

• exclude?: string[]
• 注释：排除规则（glob 模式）
• 示例：['*.tmp', 'node_modules/**']

基于这段定义，可以明确确认：

1. exclude 是字符串数组，因此支持多条规则同时配置。
2. 排除规则使用 glob 模式，不是只能选“文件类型”或只能选“文件夹”二选一。
3. 示例同时出现了：
   • *.tmp：表示可按文件类型/文件名模式排除
   • node_modules/**：表示可按目录及其全部内容排除

也就是说，从文档可以推断，排除规则至少支持以下几类用法：

• 排除特定格式文件

  • *.tmp
  • *.log
  • *.zip

• 排除某个子文件夹及其内容

  • node_modules/**
  • dist/**
  • cache/**

• 排除某个目录下的某类文件

  • temp/**/*.log

当前文档里还没有说明清楚的点

虽然 glob 和示例已经说明能力范围较灵活，但 API 文档没有明确写清楚下面这些细节：

• 是否支持更完整的 glob 语法变体
• 是否支持取反规则
• 匹配路径是相对源目录还是绝对路径
• UI 是否会提供复选、多选标签或手工录入方式

因此，按当前文档最稳妥的表述应当是：

exclude 支持通过 多条 glob 规则 排除文件或文件夹；可同时配置多个规则。但更细的匹配语法和界面交互方式，API 文档尚未展开。

---

2.2 进度推送 backup:progress

用于在备份过程中持续反馈执行进度。

推送字段：

• taskId: 任务 ID
• percent: 进度百分比（0-100）
• speed: 传输速度（bytes/s）
• transferred: 已传输字节数
• total: 总字节数
• eta: 预计剩余时间（秒）
• currentFile: 当前处理文件

可支撑的前端能力：

• 进度条展示
• 实时速度展示
• 剩余时间估算
• 当前文件展示

---

2.3 完成事件 backup:completed

用于在任务成功结束后返回统计结果。

推送字段：

• taskId: 任务 ID
• duration: 总耗时（秒）
• totalFiles: 总文件数
• totalSize: 总大小（字节）

可支撑的前端能力：

• 成功提示
• 备份结果汇总
• 系统通知展示

---

2.4 错误事件 backup:error

用于在备份失败时返回错误信息。

推送字段：

• taskId: 任务 ID
• error: 错误描述
• errorCode?: 可选错误码

可支撑的前端能力：

• 错误提示
• 重试引导
• 异常日志记录

---

2.5 获取任务列表 backup:list

用于查看当前已有的备份任务及其状态。

返回字段：

• id
• name
• source
• destination
• status: idle | running | paused | completed | error
• progress.percent
• progress.speed
• progress.eta
• createdAt
• lastRunAt?
• nextRunAt?

说明：

• 该接口可用于任务列表页、任务详情页和定时任务看板。
• lastRunAt / nextRunAt 说明系统支持查看最近执行时间与下次执行时间。

---

2.6 任务控制接口

backup:pause

暂停任务。

backup:resume

恢复任务。

backup:cancel

取消任务。

backup:delete

删除任务。

说明：

• 文档给出了“暂停 / 恢复 / 取消 / 删除”能力。
• backup:list 的状态枚举里没有单独列出 cancelled 状态；因此可以确认“支持取消操作”，但取消后的最终状态表现，文档中未进一步展开。

---

3. 备份相关辅助接口

虽然不属于“备份 API”主章节，但文档中的完整流程示例表明，备份功能通常还会配合以下接口一起使用：

3.1 选择本地源目录 dialog:selectFolder

用于让用户选择需要备份的本地文件夹。

3.2 浏览设备目录 zimaos:listFiles

用于查看设备端路径，确定备份目标位置。

3.3 系统通知 notification:show

用于在备份完成后弹出系统通知。

3.4 打开备份窗口 window:openBackup

用于打开备份功能界面。

---

4. 备份流程梳理

4.1 手动创建并执行备份流程

text
打开备份界面
  -> 选择本地源文件夹
  -> 选择/确认设备目标目录
  -> 调用 backup:create 创建任务
  -> 监听 backup:progress 更新进度
  -> 成功时接收 backup:completed
  -> 失败时接收 backup:error
  -> 可选：调用 notification:show 发送完成通知

对应 API 顺序

1. window:openBackup（可选）
2. dialog:selectFolder
3. zimaos:listFiles
4. backup:create
5. backup:progress（事件监听）
6. backup:completed / backup:error（事件监听）
7. notification:show（可选）

---

4.2 定时备份配置流程

text
用户填写源目录和目标目录
  -> 配置 incremental / exclude / schedule
  -> 调用 backup:create 创建任务
  -> 后续通过 backup:list 查看 nextRunAt / lastRunAt / status
  -> 需要时可 pause / resume / delete

关键点

• 定时能力入口在 backup:create.config.schedule
• 增量能力入口在 backup:create.config.incremental
• 排除能力入口在 backup:create.config.exclude
• 运行结果查看入口在 backup:list

---

4.3 运行中任务控制流程

text
任务运行中
  -> 可调用 backup:pause 暂停
  -> 可调用 backup:resume 恢复
  -> 可调用 backup:cancel 取消
  -> 不再需要时调用 backup:delete 删除任务

---

5. 可归纳出的备份状态流转

基于文档中给出的状态枚举和控制接口，可整理出如下状态视图：

text
idle -> running -> completed
              -> error
              -> paused -> running

补充说明：

• 文档明确列出了 idle / running / paused / completed / error。
• 文档提供了 backup:cancel，但未明确说明取消后在列表中的状态值，因此这里不额外推断取消态名称。

---

6. 文档中明确支持的备份功能点汇总

功能点	是否明确支持	依据
新建备份任务	是	backup:create
增量备份	是	config.incremental
排除规则	是	config.exclude
定时备份	是	config.schedule
查看实时进度	是	backup:progress
查看完成统计	是	backup:completed
错误上报	是	backup:error
查看任务列表	是	backup:list
暂停任务	是	backup:pause
恢复任务	是	backup:resume
取消任务	是	backup:cancel
删除任务	是	backup:delete
完成后系统通知	是	示例中使用 notification:show

---

7. 一句话总结

这套备份 API 的设计重点是：通过 backup:create 定义备份任务，通过事件获取执行结果，通过 backup:list + pause/resume/cancel/delete 完成任务生命周期管理，并支持增量、排除和定时备份配置。