# 同步备份功能说明（PRD表格版）

> 整理来源：[[我的笔记/NAS需求文档/同步备份/备份功能说明]]
> 原始依据：[[我的笔记/NAS需求文档/同步备份/API_REFERENCE]]
> 用途：用于产品需求文档快速引用

## 1. 功能概述

| 项目 | 说明 |
|---|---|
| 功能名称 | 同步备份 |
| 功能目标 | 将本地指定目录备份到设备指定目录，并支持任务化管理 |
| 任务模式 | 创建任务 + 事件推送 + 任务管理 |
| 支持的配置项 | 增量备份、排除规则、定时备份 |
| 任务结果反馈 | 实时进度、完成结果、错误信息 |
| 任务管理能力 | 列表查看、暂停、恢复、取消、删除 |

---

## 2. 备份功能点总表

| 功能模块 | 功能点     | 是否支持 | 说明                                |
| ---- | ------- | ---- | --------------------------------- |
| 任务创建 | 新建备份任务  | 是    | 指定源目录、目标目录、备份配置                   |
| 备份模式 | 增量备份    | 是    | `incremental` 默认 `true`           |
| 备份模式 | 全量备份    | 是    | 显式传 `incremental: false`          |
| 规则配置 | 排除规则    | 是    | `exclude` 为 `string[]`，使用 glob 模式 |
| 计划执行 | 定时备份    | 是    | `schedule` 使用 cron 表达式            |
| 执行反馈 | 实时进度    | 是    | 返回百分比、速度、已传输大小、剩余时间、当前文件          |
| 执行反馈 | 完成统计    | 是    | 返回耗时、总文件数、总大小                     |
| 执行反馈 | 错误通知    | 是    | 返回错误信息和可选错误码                      |
| 任务管理 | 任务列表    | 是    | 可查看任务状态、进度、最近执行时间、下次执行时间          |
| 任务管理 | 暂停任务    | 是    | 支持运行中暂停                           |
| 任务管理 | 恢复任务    | 是    | 支持暂停后恢复                           |
| 任务管理 | 取消任务    | 是    | 支持取消，但取消后的状态值未明示                  |
| 任务管理 | 删除任务    | 是    | 支持删除任务                            |
| 辅助能力 | 完成后系统通知 | 是    | 示例中通过 `notification:show` 实现      |

---

## 3. 创建备份任务参数表

### 3.1 创建接口

| 项目 | 说明 |
|---|---|
| 接口 | `backup:create` |
| 调用方式 | `ipcRenderer.invoke('backup:create', payload)` |
| 返回值 | `taskId: string` |
| 说明 | 创建后通过事件监听进度、完成和错误 |

### 3.2 入参定义

| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `source` | `string` | 是 | - | 本地源路径 |
| `destination` | `string` | 是 | - | 设备目标路径 |
| `config.incremental` | `boolean` | 否 | `true` | 是否增量备份 |
| `config.exclude` | `string[]` | 否 | - | 排除规则，glob 模式 |
| `config.schedule` | `string` | 否 | - | 定时计划，cron 表达式 |

---

## 4. 产品规则说明表

### 4.1 增量 / 全量规则

| 规则项 | 结论 | 说明 |
|---|---|---|
| 默认备份方式 | 增量 | `incremental` 默认值为 `true` |
| 是否可改 | 可以 | `incremental` 是可选布尔字段 |
| 改为全量方式 | 显式设置 `incremental: false` | 创建任务时传入 |
| 当前未明确点 | 有 | “全量”具体是全复制、全覆盖还是全快照，文档未展开 |

### 4.2 排除规则

| 规则项 | 结论 | 说明 |
|---|---|---|
| 规则类型 | glob 模式 | 文档注释明确说明 |
| 是否支持多条 | 支持 | `exclude` 类型为 `string[]` |
| 是否可排除文件类型 | 可以 | 例：`*.tmp` |
| 是否可排除文件夹 | 可以 | 例：`node_modules/**` |
| 是否可混合配置 | 可以 | 可同时传文件规则和目录规则 |
| 当前未明确点 | 有 | 是否支持取反、完整 glob 变体、路径匹配基准、UI 交互方式均未展开 |

### 4.3 任务状态

| 状态 | 含义 | 备注 |
|---|---|---|
| `idle` | 空闲 | 已创建未运行或等待运行 |
| `running` | 运行中 | 正在执行备份 |
| `paused` | 已暂停 | 可恢复 |
| `completed` | 已完成 | 成功结束 |
| `error` | 异常 | 执行失败 |

> 补充：文档中提供了 `backup:cancel`，但未明确取消后的状态字段名称。

---

## 5. 事件返回字段表

### 5.1 进度事件 `backup:progress`

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

### 5.2 完成事件 `backup:completed`

| 字段 | 类型 | 说明 |
|---|---|---|
| `taskId` | `string` | 任务 ID |
| `duration` | `number` | 耗时（秒） |
| `totalFiles` | `number` | 总文件数 |
| `totalSize` | `number` | 总大小（字节） |

### 5.3 错误事件 `backup:error`

| 字段 | 类型 | 说明 |
|---|---|---|
| `taskId` | `string` | 任务 ID |
| `error` | `string` | 错误描述 |
| `errorCode` | `string` | 可选错误码 |

---

## 6. 任务列表字段表

| 字段 | 说明 |
|---|---|
| `id` | 任务 ID |
| `name` | 任务名称 |
| `source` | 源路径 |
| `destination` | 目标路径 |
| `status` | 任务状态 |
| `progress.percent` | 当前进度 |
| `progress.speed` | 当前速度 |
| `progress.eta` | 预计剩余时间 |
| `createdAt` | 创建时间 |
| `lastRunAt` | 最近执行时间 |
| `nextRunAt` | 下次执行时间 |

---

## 7. 典型业务流程表

### 7.1 手动备份流程

| 步骤 | 用户/系统动作 | 对应接口 |
|---|---|---|
| 1 | 打开备份界面 | `window:openBackup`（可选） |
| 2 | 选择本地源目录 | `dialog:selectFolder` |
| 3 | 查看并确认设备目标目录 | `zimaos:listFiles` |
| 4 | 创建备份任务 | `backup:create` |
| 5 | 实时接收进度 | `backup:progress` |
| 6 | 接收完成或失败结果 | `backup:completed` / `backup:error` |
| 7 | 完成后发送通知 | `notification:show`（可选） |

### 7.2 定时备份流程

| 步骤 | 用户/系统动作 | 对应接口 |
|---|---|---|
| 1 | 选择源目录与目标目录 | `backup:create` 入参 |
| 2 | 配置增量、排除、定时 | `config.incremental` / `config.exclude` / `config.schedule` |
| 3 | 创建任务 | `backup:create` |
| 4 | 查看执行计划与历史 | `backup:list` |
| 5 | 根据需要暂停、恢复或删除 | `backup:pause` / `backup:resume` / `backup:delete` |

### 7.3 运行中控制流程

| 场景 | 操作 | 对应接口 |
|---|---|---|
| 临时停止任务 | 暂停 | `backup:pause` |
| 继续任务 | 恢复 | `backup:resume` |
| 中止当前任务 | 取消 | `backup:cancel` |
| 清理无用任务 | 删除 | `backup:delete` |

---

## 8. PRD 可直接引用的结论

| 结论项 | 结论 |
|---|---|
| 默认备份模式 | 默认增量备份 |
| 是否支持全量 | 支持，通过 `incremental: false` 实现 |
| 排除规则能力 | 支持多条 glob 规则，可排除文件和目录 |
| 定时能力 | 支持，通过 cron 表达式配置 |
| 进度可视化 | 支持，包含进度、速度、剩余时间、当前文件 |
| 结果反馈 | 支持完成统计与错误反馈 |
| 生命周期管理 | 支持查看、暂停、恢复、取消、删除 |
| 当前待确认项 | 全量语义、取消后的状态值、glob 语法边界、UI 配置方式 |


备份功能说明（PRD表格版）

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

API_REFERENCE

# Figma 原型交互稿说明（PC 端 + 移动端）

> 用途：把 [[我的笔记/NAS需求文档/同步备份/客户端同步备份功能产品需求文档PRD]] 直接转成可给设计和开发使用的原型范围、页面结构、交互流和标注要求。

## 1. 输出目标

本稿用于指导 Figma 产出以下交付物：

1. **PC 端高保真原型**
2. **移动端高保真原型**
3. **关键交互流**
4. **组件态与异常态**
5. **开发标注页**

要求：

- 不引入 PRD 本期范围外能力；
- 页面命名、状态命名、字段命名尽量与 API / PRD 一致；
- 设计稿可直接用于评审、开发排期和前端拆页。

---

## 2. Figma 文件建议结构

```text
00_Cover
01_UserFlow
10_PC_Wireframe
11_PC_HiFi
12_PC_States
20_Mobile_Wireframe
21_Mobile_HiFi
22_Mobile_States
30_Components
40_Dev_Handoff
```

### 2.1 画板尺寸建议

- **PC 主画板**：1440 × 900
- **PC 弹窗**：960 × 560
- **移动端画板**：390 × 844

---

## 3. 页面信息架构

### 3.1 PC 端信息架构

```text
备份管理首页
├── 空状态
├── 任务列表
├── 任务详情面板
├── 新建备份任务弹窗
└── 删除/取消二次确认弹窗
```

### 3.2 移动端信息架构

```text
Backup 首页
├── 当前任务卡片/空状态
├── 源路径选择
├── 目标路径选择
├── 备份选项
└── 运行中/完成/失败反馈
```

---

## 4. PC 端原型范围

## 4.1 页面清单

| 编号 | 页面 | 用途 | 备注 |
| --- | --- | --- | --- |
| PC-01 | 备份管理首页-无任务 | 首次进入空状态 | 对应参考图“暂无备份任务” |
| PC-02 | 新建备份任务-基础态 | 录入源路径、目标路径 | 默认仅展示基础配置 |
| PC-03 | 新建备份任务-高级配置展开 | 增量/全量、排除规则、定时 | 需含校验提示 |
| PC-04 | 任务列表-有任务 | 多任务管理入口 | 支持 idle/completed/error 卡片态 |
| PC-05 | 任务详情-运行中 | 展示进度、速度、剩余时间、当前文件 | 重点交互页 |
| PC-06 | 任务详情-已暂停 | 展示恢复入口 | 与 running 态联动 |
| PC-07 | 任务详情-失败 | 展示错误摘要与重试建议 | 需区分可恢复/不可恢复 |
| PC-08 | 删除任务确认弹窗 | 风险操作确认 | 文案需注明是否删除远端文件待确认 |

### 4.2 页面布局要求

#### A. 首页

- 顶部：页面标题、刷新按钮、`新建备份`
- 左侧：任务列表区
- 右侧：任务详情区
- 无任务时左侧为空状态，右侧为说明文案

#### B. 新建任务弹窗

- 字段区：
  - 源路径
  - 目标路径
  - 高级配置折叠区
- 底部操作：
  - 取消
  - 创建备份

#### C. 任务详情

- 顶部：任务名、状态标签、更多操作
- 中部：进度卡、路径信息、策略信息
- 底部：开始 / 暂停 / 恢复 / 删除

### 4.3 PC 端关键交互流

#### 流程 1：首次创建任务

`空状态首页 -> 点击新建备份 -> 选择源路径 -> 选择目标路径 -> 可选配置高级项 -> 创建成功 -> 生成 idle 任务卡片`

#### 流程 2：手动开始备份

`任务卡片/详情页 -> 点击开始 -> 进入 running -> 持续刷新 percent/speed/eta/currentFile -> completed 或 error`

#### 流程 3：暂停与恢复

`running -> 点击暂停 -> paused -> 点击恢复 -> running`

#### 流程 4：失败恢复

`error -> 查看错误原因 -> 修复环境/路径/权限 -> 重试或恢复`

### 4.4 PC 页面必须体现的字段

- 任务名称 `name`
- 源路径 `source`
- 目标路径 `destination`
- 状态 `status`
- 当前进度 `progress.percent`
- 当前速度 `progress.speed`
- 预计剩余时间 `progress.eta`
- 最近执行时间 `lastRunAt`
- 下次执行时间 `nextRunAt`
- 当前文件 `currentFile`
- 完成统计 `duration / totalFiles / totalSize`

---

## 5. 移动端原型范围

## 5.1 页面清单

| 编号 | 页面 | 用途 | 备注 |
| --- | --- | --- | --- |
| M-01 | Backup 首页-空状态/未配置 | 首次进入 | 需保留简洁引导 |
| M-02 | Backup 首页-运行中 | 展示当前任务进度 | 对应参考图主界面 |
| M-03 | 源路径选择 | 选择本机目录 | 入口可为底部按钮或卡片选择 |
| M-04 | 目标路径选择 | 选择 NAS 目录 | 需体现 NAS 路径浏览 |
| M-05 | 备份选项 | 增量/全量、排除规则、定时 | 可做成独立页 |
| M-06 | 备份完成 | 展示结果摘要 | 包括总文件数与耗时 |
| M-07 | 备份失败 | 展示错误与恢复操作 | 含重试 |
| M-08 | 设置页 | 自动前台备份等开关 | 对应参考图“备份选项” |

### 5.2 移动端布局要求

- 顶部：标题 + 设置入口
- 主卡片：当前任务状态
- 配置卡片：
  - From（本地目录）
  - To（NAS 目录）
  - Options（备份选项）
- 底部主按钮：
  - 未开始：开始备份 / 创建任务
  - 运行中：暂停 / 停止
  - 异常：重试

### 5.3 移动端关键交互流

#### 流程 1：快速配置

`首页 -> 选择 From -> 选择 To -> 进入备份选项 -> 保存 -> 返回首页`

#### 流程 2：启动备份

`首页 -> 点击开始备份 -> running -> completed`

#### 流程 3：异常处理

`running -> error -> 展示错误原因与建议 -> 重试`

---

## 6. 组件与状态清单

### 6.1 通用组件

1. 顶部标题栏
2. 主按钮 / 次按钮 / 危险按钮
3. 路径选择器
4. 任务卡片
5. 状态标签
6. 进度条
7. 空状态
8. Toast / Banner
9. 确认弹窗
10. 开关 / 单选 / 多行输入

### 6.2 状态标签统一

| 状态 | 展示文案 | 颜色建议 |
| --- | --- | --- |
| `idle` | 空闲 | 中性灰 |
| `running` | 备份中 | 蓝色 |
| `paused` | 已暂停 | 橙色 |
| `completed` | 已完成 | 绿色 |
| `error` | 失败 | 红色 |

### 6.3 必出异常态

1. 源路径为空
2. 目标路径为空
3. cron 非法
4. 排除规则格式错误
5. NAS 不可达
6. NAS 空间不足
7. 目标路径不可写
8. 网络异常中断

---

## 7. 视觉方向

以现有参考图为基础，保留以下风格特征：

- **PC 端**：浅色背景、轻渐变、圆角卡片、左右分栏
- **移动端**：大标题、白底卡片、超大圆角主按钮、弱分割线
- **整体关键词**：轻量、可信赖、系统工具感、非复杂专业运维工具

### 7.1 建议设计原则

- 重要操作尽量单主按钮
- 高级配置默认折叠
- 运行状态优先展示“进度 + 剩余时间 + 当前文件”
- 异常状态优先展示“原因 + 下一步”
- 避免出现超出本期能力的历史对比、文件差异、双向同步

---

## 8. 开发标注要求

## 8.1 字段映射

| UI 字段 | API / 数据字段 |
| --- | --- |
| 任务名 | `name` |
| 源路径 | `source` |
| 目标路径 | `destination` |
| 状态 | `status` |
| 进度 | `progress.percent` |
| 速度 | `progress.speed` |
| 剩余时间 | `progress.eta` |
| 最近执行时间 | `lastRunAt` |
| 下次执行时间 | `nextRunAt` |
| 当前文件 | `backup:progress.currentFile` |
| 完成结果 | `backup:completed` |
| 错误摘要 | `backup:error.error` |

### 8.2 交互标注

设计稿中需显式标注：

1. 按钮点击后触发的动作
2. 页面跳转或弹窗打开关系
3. 状态切换条件
4. 字段校验时机
5. 空数据与超长文本处理

### 8.3 不可遗漏的说明

- `incremental` 默认 `true`
- `schedule` 为任务级配置，不是全局配置
- `cancel` 后的最终状态待研发确认
- 删除任务是否删除 NAS 远端文件待确认
- API 未明确独立 `start` 接口，开始动作需研发确认实现方式

---

## 9. Figma 生成提示词（可直接使用）

## 9.1 PC 端 Prompt

```text
请基于“NAS 桌面端同步备份”场景生成一套可交付研发的 PC 端高保真原型。

产品目标：
- 用户从本地目录备份到 NAS 目录
- 支持创建任务、查看任务列表、查看详情、运行进度、暂停/恢复、删除
- 支持高级配置：增量/全量、排除规则、定时备份

页面必须包含：
1. 备份管理首页空状态
2. 新建备份任务弹窗
3. 高级配置展开态
4. 有任务列表首页
5. 任务详情运行中
6. 已暂停
7. 失败态
8. 删除确认弹窗

视觉要求：
- 浅色、轻渐变背景
- 圆角卡片
- 左任务列表右详情分栏
- 中文界面
- 工具型产品风格，简洁可信赖

交互要求：
- 标注开始、暂停、恢复、删除、重试
- 标注状态 idle/running/paused/completed/error
- 标注 percent/speed/eta/currentFile/lastRunAt/nextRunAt
- 不要设计双向同步、历史版本、文件差异对比
```

## 9.2 移动端 Prompt

```text
请基于“NAS 移动端同步备份”场景生成一套可交付研发的移动端高保真原型。

产品目标：
- 用户配置本机目录到 NAS 目录的备份任务
- 展示任务运行进度、完成结果、失败恢复
- 提供备份选项页

页面必须包含：
1. 首页空状态
2. 首页运行中状态
3. 源路径选择
4. 目标路径选择
5. 备份选项页
6. 完成页
7. 失败页
8. 设置页

视觉要求：
- 大标题
- 白底卡片
- 高圆角
- 中文界面
- 简洁工具型风格

交互要求：
- 展示 From / To / Options
- 展示 percent、speed、transferred、total、eta
- 提供开始、暂停、停止、重试
- 不要设计超出本期的文件级失败清单和历史差异页
```

---

## 10. 设计评审检查清单

- [ ] PC 和移动端页面范围齐全
- [ ] 所有核心状态都已出稿
- [ ] 高级配置已覆盖增量/全量、排除规则、定时
- [ ] 空状态、异常态、删除确认都已覆盖
- [ ] 页面文案与 PRD / API 字段一致
- [ ] 没有引入本期范围外能力
- [ ] 已补充开发标注页



同步备份功能说明（PRD表格版）

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

Zima Client V2 API 参考文档

Figma 原型交互稿说明（PC 端 + 移动端）

NAS 设置（控制面板）模块产品需求文档

文档信息