NAS下载器产品竞品分析

libtorrent自研BT服务路线技术方案

# NAS下载器状态机 + 时序图文档

关联文档：[[我的笔记/NAS需求文档/下载器/NAS下载器详细需求文档]]、[[我的笔记/NAS需求文档/下载器/NAS下载器前后端接口清单]]

## 一、文档目的

用于统一前端、后端、客户端、测试对任务状态流转和关键业务时序的理解，避免状态定义不一致。

---

## 二、统一状态机

## 2.1 任务主状态机

```mermaid
stateDiagram-v2
    [*] --> waiting
    waiting --> metadata_fetching: magnet/torrent 需拉取元数据
    waiting --> downloading: https/分享直下 或 已有元数据
    metadata_fetching --> downloading: 元数据成功
    metadata_fetching --> failed: 元数据失败/超时

    downloading --> paused: 用户暂停
    paused --> downloading: 用户恢复

    downloading --> verifying: BT/PT 下载完成
    verifying --> seeding: 校验通过且需做种
    verifying --> completed: 校验通过且无需做种
    verifying --> failed: 校验失败

    downloading --> completed: HTTPS下载完成/分享转存完成
    downloading --> failed: 网络异常/权限异常/资源失效/磁盘不足
    downloading --> invalid: 资源失效
    downloading --> permission_denied: 权限失效

    seeding --> paused: 用户暂停做种
    seeding --> completed: 达到做种停止条件
    seeding --> failed: tracker/内部异常

    failed --> waiting: 用户重试
    invalid --> waiting: 用户重试且资源恢复可用
    permission_denied --> waiting: 用户重新认证或权限恢复
    completed --> [*]
```

## 2.2 状态说明表

| 状态 | 含义 | 对用户是否可见 | 典型来源 |
|---|---|---|---|
| waiting | 已创建，等待执行 | 是 | 并发限制、用户未自动启动 |
| metadata_fetching | 获取 magnet/torrent 元数据 | 是 | magnet、部分 torrent |
| downloading | 正在下载 | 是 | BT/PT/HTTPS/分享下载 |
| paused | 用户或系统暂停 | 是 | 手动暂停 |
| verifying | 校验数据完整性 | 是 | BT/PT 下载结束 |
| seeding | 正在做种 | 是 | BT/PT 校验通过后 |
| completed | 任务完成 | 是 | HTTPS 完成、BT/PT 完成或达停止做种条件 |
| failed | 执行失败 | 是 | 网络错误、内部错误 |
| invalid | 资源失效 | 是 | 404、分享取消、链接过期 |
| permission_denied | 权限失效 | 是 | 提取码错误、登录失效、目录无权限 |
| removed | 已删除 | 否（历史可选） | 用户删除 |

## 2.3 操作与状态合法性矩阵

| 当前状态 | 可执行操作 |
|---|---|
| waiting | 开始、删除 |
| metadata_fetching | 暂停、删除 |
| downloading | 暂停、删除、打开详情 |
| paused | 恢复、删除 |
| verifying | 等待、查看详情 |
| seeding | 暂停、删除、打开目录 |
| completed | 删除、打开目录 |
| failed | 重试、删除 |
| invalid | 删除、重试（若资源可恢复） |
| permission_denied | 重试、重新认证、删除 |

---

## 三、子状态补充

## 3.1 分享链接任务子状态

```mermaid
stateDiagram-v2
    [*] --> parse_share
    parse_share --> need_extract_code: 需要提取码
    need_extract_code --> parse_share: 用户重新输入提取码
    parse_share --> permission_denied: 提取码错误/无权限
    parse_share --> invalid: 链接失效/过期
    parse_share --> transfering: 可转存且用户选择转存
    parse_share --> downloading: 用户选择下载
    transfering --> completed: 转存成功
    transfering --> failed: 转存失败
```

## 3.2 PT 安全模式逻辑状态

```mermaid
flowchart TD
    A[上传torrent] --> B{是否private种}
    B -->|否| C[按公开BT策略]
    B -->|是| D[启用PT安全模式]
    D --> D1[关闭DHT]
    D --> D2[关闭PEX]
    D --> D3[关闭LSD]
    D --> D4[禁止公共Tracker注入]
    D --> D5[展示PT标识与风险提示]
```

---

## 四、关键时序图

## 4.1 创建 BT/PT 任务时序

```mermaid
sequenceDiagram
    participant U as 用户
    participant FE as 前端
    participant API as 下载API
    participant ENG as 下载引擎
    participant DB as 任务存储
    participant WS as 实时推送

    U->>FE: 上传torrent/填写保存目录
    FE->>API: POST /parse/torrent
    API->>ENG: 解析torrent
    ENG-->>API: 返回元数据/private标记
    API-->>FE: 返回BT/PT信息
    U->>FE: 点击创建任务
    FE->>API: POST /tasks
    API->>DB: 写入任务(waiting)
    API->>ENG: 创建下载任务
    ENG-->>API: 创建成功
    API-->>FE: 返回task_id
    API->>WS: 推送task_created
    WS-->>FE: 新任务出现在列表
```

## 4.2 创建 Magnet 任务时序

```mermaid
sequenceDiagram
    participant U as 用户
    participant FE as 前端
    participant API as 下载API
    participant ENG as 下载引擎
    participant WS as 实时推送

    U->>FE: 粘贴magnet链接
    FE->>API: POST /parse
    API-->>FE: type=magnet
    U->>FE: 点击创建任务
    FE->>API: POST /tasks
    API->>ENG: 创建magnet任务
    API->>WS: 推送task_created(status=metadata_fetching)
    ENG->>ENG: 拉取元数据
    ENG->>API: 更新任务状态/元数据
    API->>WS: 推送task_updated(status=downloading)
    WS-->>FE: 页面状态更新
```

## 4.3 创建 HTTPS 任务时序

```mermaid
sequenceDiagram
    participant U as 用户
    participant FE as 前端
    participant API as 下载API
    participant HTTP as HTTP下载模块
    participant WS as 实时推送

    U->>FE: 输入https链接
    FE->>API: POST /parse
    API->>HTTP: 探测链接/重定向/文件名
    HTTP-->>API: 返回识别结果
    API-->>FE: type=https
    U->>FE: 点击创建
    FE->>API: POST /tasks
    API->>HTTP: 启动下载
    API->>WS: task_created(status=downloading)
    HTTP->>API: 上报进度
    API->>WS: task_updated
    HTTP->>API: 完成
    API->>WS: task_completed
```

## 4.4 分享链接转存时序

```mermaid
sequenceDiagram
    participant U as 用户
    participant FE as 前端
    participant API as 下载API
    participant SHARE as 分享服务
    participant DB as 任务存储
    participant WS as 实时推送

    U->>FE: 输入品牌分享链接
    FE->>API: POST /parse/share-link
    API->>SHARE: 预解析分享链接
    SHARE-->>API: 返回文件列表/权限/是否可转存
    API-->>FE: 展示分享内容
    U->>FE: 选择转存并点击创建
    FE->>API: POST /tasks(share_mode=transfer)
    API->>DB: 创建任务(waiting/downloading)
    API->>SHARE: 发起转存
    SHARE-->>API: 转存进度/结果
    API->>WS: 推送状态变化
    WS-->>FE: 前端更新为completed或failed
```

## 4.5 分享链接下载时序

```mermaid
sequenceDiagram
    participant U as 用户
    participant FE as 前端
    participant API as 下载API
    participant SHARE as 分享服务
    participant ENG as 下载引擎
    participant WS as 实时推送

    U->>FE: 选择分享链接下载模式
    FE->>API: POST /tasks(share_mode=download)
    API->>SHARE: 获取可下载地址/资源信息
    SHARE-->>API: 返回下载资源信息
    API->>ENG: 启动下载任务
    API->>WS: 推送task_created/downloading
    ENG->>API: 上报进度
    API->>WS: 推送task_updated
    ENG->>API: 下载完成
    API->>WS: 推送task_completed
```

## 4.6 暂停/恢复任务时序

```mermaid
sequenceDiagram
    participant U as 用户
    participant FE as 前端
    participant API as 下载API
    participant ENG as 下载引擎
    participant WS as 实时推送

    U->>FE: 点击暂停/恢复
    FE->>API: POST pause/resume
    API->>ENG: 执行暂停/恢复
    ENG-->>API: 执行结果
    API->>WS: 推送task_updated(status变化)
    WS-->>FE: 列表和详情同步刷新
```

## 4.7 删除任务时序

```mermaid
sequenceDiagram
    participant U as 用户
    participant FE as 前端
    participant API as 下载API
    participant ENG as 下载引擎
    participant FILE as 文件服务
    participant WS as 实时推送

    U->>FE: 点击删除并确认
    FE->>API: DELETE /tasks/{id}?delete_files=true/false
    API->>ENG: 停止任务
    alt delete_files=true
        API->>FILE: 删除已下载文件
    end
    API->>WS: 推送task_removed
    WS-->>FE: 列表移除任务
```

## 4.8 设置保存时序

```mermaid
sequenceDiagram
    participant U as 用户
    participant FE as 前端
    participant API as 设置API
    participant ENG as 下载引擎

    U->>FE: 修改设置并点击保存
    FE->>API: PUT /download-settings
    API->>API: 参数校验与权限校验
    API->>ENG: 更新运行时配置
    ENG-->>API: 生效成功
    API-->>FE: 保存成功
    FE-->>U: Toast: 设置已保存
```

---

## 五、异常时序图

## 5.1 提取码错误

```mermaid
sequenceDiagram
    participant U as 用户
    participant FE as 前端
    participant API as 下载API
    participant SHARE as 分享服务

    U->>FE: 输入分享链接和错误提取码
    FE->>API: POST /parse/share-link
    API->>SHARE: 校验提取码
    SHARE-->>API: 提取码错误
    API-->>FE: permission_denied / 4005
    FE-->>U: 显示“提取码错误，请重新输入”
```

## 5.2 磁盘空间不足

```mermaid
sequenceDiagram
    participant ENG as 下载引擎
    participant API as 下载API
    participant WS as 实时推送
    participant FE as 前端
    participant NTF as 通知中心

    ENG->>API: 上报磁盘空间不足
    API->>API: 更新任务状态为failed
    API->>WS: 推送task_failed(error=DL-003)
    API->>NTF: 发送磁盘空间不足通知
    WS-->>FE: 页面展示失败原因
```

## 5.3 资源失效

```mermaid
sequenceDiagram
    participant ENG as 下载引擎/分享服务
    participant API as 下载API
    participant WS as 实时推送
    participant FE as 前端

    ENG->>API: 上报404/链接过期/分享取消
    API->>API: 更新状态为invalid
    API->>WS: 推送task_updated(status=invalid)
    WS-->>FE: 列表状态改为资源失效
```

---

## 六、前端实现建议

1. 前端内部状态机建议直接复用后端状态枚举。
2. 列表页和详情页都基于同一份任务 store。
3. WebSocket 推送只做增量更新，不替代首屏拉取。
4. 对 `failed / invalid / permission_denied` 三类状态要做不同 UI 表达。
5. `verifying` 和 `metadata_fetching` 不能被误显示为“暂停”或“失败”。

---

## 七、测试关注点

- [ ] 所有状态迁移是否合法
- [ ] 不合法状态下按钮是否正确禁用
- [ ] WebSocket 推送是否能正确驱动 UI 变更
- [ ] PT 任务不会误进入公共 BT 逻辑
- [ ] 分享链接转存与下载两条链路状态是否清晰区分
- [ ] 错误状态是否能重试并回到 waiting/downloading


NAS下载器状态机+时序图文档

NAS下载器应用需求规划文档

# NAS下载器测试用例清单

关联文档：[[我的笔记/NAS需求文档/下载器/NAS下载器详细需求文档]]、[[我的笔记/NAS需求文档/下载器/NAS下载器前后端接口清单]]

## 一、测试范围

V1 核心范围：
- BT 种子
- 私有 PT 种子
- Magnet 磁力链
- HTTPS 下载
- 品牌分享链接下载/转存
- 任务列表/详情/设置/通知
- Web/App 远程管理

---

## 二、冒烟用例

| 编号 | 模块 | 用例标题 | 预期结果 | 优先级 |
|---|---|---|---|---|
| SMK-001 | 任务创建 | 可成功创建 BT 任务 | 任务进入下载流程 | P0 |
| SMK-002 | 任务创建 | 可成功创建 Magnet 任务 | 进入元数据获取/下载流程 | P0 |
| SMK-003 | HTTPS | 可成功创建 HTTPS 任务 | 文件开始下载 | P0 |
| SMK-004 | 分享链接 | 可成功解析品牌分享链接 | 展示文件列表 | P0 |
| SMK-005 | 列表管理 | 列表可展示任务状态 | 状态正确展示 | P0 |
| SMK-006 | 任务操作 | 暂停/恢复/删除可用 | 操作成功 | P0 |
| SMK-007 | 设置 | 可保存基础设置 | 设置生效 | P0 |
| SMK-008 | 通知 | 下载完成后收到通知 | 通知成功展示 | P0 |

---

## 三、详细测试用例

## 3.1 任务创建

| 编号 | 前置条件 | 操作步骤 | 预期结果 |
|---|---|---|---|
| CT-001 | 用户已登录且目录可写 | 打开添加任务弹窗 | 弹窗成功打开 |
| CT-002 | 无 | 输入 magnet 链接 | 自动识别为 magnet |
| CT-003 | 无 | 输入普通 https 链接 | 自动识别为 https |
| CT-004 | 无 | 输入品牌分享链接 | 自动识别为分享链接 |
| CT-005 | 有 torrent 文件 | 上传公开种 torrent | 识别为 BT，展示文件列表 |
| CT-006 | 有私有种 torrent | 上传私有种 torrent | 识别为 PT，展示 PT 安全模式提示 |
| CT-007 | 目录无权限 | 选择不可写目录创建任务 | 禁止创建并提示 |
| CT-008 | 已存在相同任务 | 再次创建同资源任务 | 弹出重复任务策略提示 |
| CT-009 | 磁盘空间不足 | 创建大文件任务 | 创建前或创建后明确预警 |

## 3.2 BT / PT 下载

| 编号 | 前置条件 | 操作步骤 | 预期结果 |
|---|---|---|---|
| BT-001 | 公开 BT 资源可用 | 创建公开 BT 任务 | 正常连接 Peer 并下载 |
| BT-002 | 私有 PT 资源可用 | 创建 PT 任务 | 默认关闭 DHT/PEX/LSD |
| BT-003 | 私有 PT 任务 | 查看详情页 | PT 标签和安全模式提示可见 |
| BT-004 | 私有 PT 任务 | 检查 tracker 配置 | 未注入公共 Tracker |
| BT-005 | BT 多文件种子 | 仅选择部分文件下载 | 仅下载选中文件 |
| BT-006 | 下载完成的 BT 任务 | 触发校验 | 进入 verifying 后状态正确 |
| BT-007 | 做种规则为 ratio=2 | 达到分享率 | 自动停止做种 |
| BT-008 | tracker 异常 | 手动 reannounce | tracker 状态刷新 |

## 3.3 Magnet 磁力链

| 编号 | 前置条件 | 操作步骤 | 预期结果 |
|---|---|---|---|
| MG-001 | 可用 magnet 链接 | 创建任务 | 进入 metadata_fetching |
| MG-002 | 元数据可拉取 | 等待完成 | 成功展示名称/文件列表 |
| MG-003 | 无效 magnet | 创建任务 | 提示链接非法或元数据失败 |
| MG-004 | 网络受限 | 拉取元数据超时 | 提示超时并支持重试 |

## 3.4 HTTPS 下载

| 编号 | 前置条件 | 操作步骤 | 预期结果 |
|---|---|---|---|
| HP-001 | 可用 HTTPS 链接 | 创建任务 | 下载开始 |
| HP-002 | 链接 302 跳转 | 创建任务 | 可正确跳转并下载 |
| HP-003 | 服务端支持 Range | 下载过程中中断再恢复 | 任务可续传 |
| HP-004 | 目标目录存在同名文件 | 创建任务 | 弹出冲突策略 |
| HP-005 | 资源 404 | 创建任务 | 提示资源不存在 |
| HP-006 | 资源 403 | 创建任务 | 提示无权限 |
| HP-007 | SSL 异常 | 创建任务 | 提示证书异常 |

## 3.5 品牌分享链接

| 编号 | 前置条件 | 操作步骤 | 预期结果 |
|---|---|---|---|
| SH-001 | 有公开分享链接 | 输入链接 | 可展示文件列表 |
| SH-002 | 有提取码分享链接 | 输入错误提取码 | 提示提取码错误 |
| SH-003 | 有提取码分享链接 | 输入正确提取码 | 校验通过并展示文件列表 |
| SH-004 | 分享支持转存 | 选择转存模式 | 资源直接落到目标目录 |
| SH-005 | 分享仅支持下载 | 选择下载模式 | 创建真实下载任务 |
| SH-006 | 分享已过期 | 输入链接 | 提示已过期 |
| SH-007 | 分享被取消 | 输入链接 | 提示资源失效 |
| SH-008 | 用户无权限 | 输入链接 | 提示无权限或引导登录 |

## 3.6 任务列表与详情

| 编号 | 前置条件 | 操作步骤 | 预期结果 |
|---|---|---|---|
| LS-001 | 存在多状态任务 | 切换左侧筛选 | 列表内容正确变化 |
| LS-002 | 存在任务 | 搜索任务名 | 正确返回匹配结果 |
| LS-003 | 选中多个任务 | 执行批量暂停 | 所有任务暂停 |
| LS-004 | 存在失败任务 | 查看列表 | 可看到错误摘要 |
| LS-005 | 打开任务详情 | 查看概览/文件/日志 | 信息完整可见 |
| LS-006 | PT 任务详情 | 查看 tracker 页签 | tracker 状态和分享率可见 |

## 3.7 设置与通知

| 编号 | 前置条件 | 操作步骤 | 预期结果 |
|---|---|---|---|
| ST-001 | 管理员登录 | 修改默认下载目录 | 保存成功并生效 |
| ST-002 | 普通用户登录 | 访问设置页 | 仅可见权限范围内内容 |
| ST-003 | 设置全局下载限速 | 开始下载任务 | 速度受限生效 |
| ST-004 | 设置分时段限速 | 到达指定时间段 | 新速度策略生效 |
| ST-005 | 任务下载完成 | 观察通知中心 | 收到完成通知 |
| ST-006 | 任务失败 | 观察通知中心 | 收到失败通知 |

## 3.8 远程管理与一致性

| 编号 | 前置条件 | 操作步骤 | 预期结果 |
|---|---|---|---|
| RM-001 | Web 已登录 | 创建 magnet 任务 | App/Web 都可见 |
| RM-002 | App 已登录 | 创建 https 任务 | Web 列表同步出现 |
| RM-003 | App 中暂停任务 | Web 端观察 | 状态同步为 paused |
| RM-004 | Web 中删除任务 | App 端观察 | 任务同步消失 |

## 3.9 稳定性与异常

| 编号 | 前置条件 | 操作步骤 | 预期结果 |
|---|---|---|---|
| EX-001 | 正在下载任务 | 重启下载服务 | 任务可恢复 |
| EX-002 | 正在下载任务 | 重启整机 | 任务可恢复 |
| EX-003 | 下载中磁盘写满 | 继续下载 | 提示空间不足并停止 |
| EX-004 | 长时间做种 | 持续运行 24h+ | 状态稳定，无异常泄漏 |
| EX-005 | 中文文件名资源 | 下载并完成 | 文件名显示和保存正确 |

---

## 四、性能测试建议

| 编号 | 场景 | 指标要求 |
|---|---|---|
| PF-001 | 100 条任务列表加载 | < 2 秒 |
| PF-002 | 20 个活跃任务并发 | 系统可用，无明显卡顿 |
| PF-003 | WebSocket 高频状态更新 | 前端不卡顿、状态无错乱 |
| PF-004 | 10GB+ 文件续传 | 恢复成功，数据不损坏 |

---

## 五、回归测试重点

每次版本回归至少覆盖：
- BT / PT / Magnet / HTTPS / 分享链接 五类创建
- 暂停 / 恢复 / 删除 / 重试
- PT 安全模式
- 分享链接提取码和过期
- Web/App 状态同步
- 重启恢复

---

## 六、上线前验收项

- [ ] P0 功能用例全部通过
- [ ] P0 阻断级 Bug 为 0
- [ ] PT 专项用例全部通过
- [ ] 分享链接专项用例全部通过
- [ ] Web/App 一致性通过
- [ ] 稳定性测试通过
- [ ] 性能测试达到基线


NAS 下载器产品竞品分析（飞牛NAS / 绿联 / 群晖 / qBittorrent / Tr

libtorrent + 自研 BT 服务路线技术方案

NAS下载器状态机 + 时序图文档

NAS下载器应用软件需求规划

文档信息

NAS下载器测试用例清单