关联文档：[[我的笔记/NAS需求文档/下载器/NAS下载器详细需求文档]]、[[我的笔记/NAS需求文档/下载器/NAS下载器前后端接口清单]]
用于统一前端、后端、客户端、测试对任务状态流转和关键业务时序的理解，避免状态定义不一致。
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 --> [*]
| 状态 | 含义 | 对用户是否可见 | 典型来源 |
|---|---|---|---|
| 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 | 已删除 | 否（历史可选） | 用户删除 |
| 当前状态 | 可执行操作 |
|---|---|
| waiting | 开始、删除 |
| metadata_fetching | 暂停、删除 |
| downloading | 暂停、删除、打开详情 |
| paused | 恢复、删除 |
| verifying | 等待、查看详情 |
| seeding | 暂停、删除、打开目录 |
| completed | 删除、打开目录 |
| failed | 重试、删除 |
| invalid | 删除、重试（若资源可恢复） |
| permission_denied | 重试、重新认证、删除 |
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: 转存失败
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标识与风险提示]
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: 新任务出现在列表
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: 页面状态更新
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
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
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
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: 列表和详情同步刷新
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: 列表移除任务
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: 设置已保存
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: 显示“提取码错误，请重新输入”
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: 页面展示失败原因
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: 列表状态改为资源失效
failed / invalid / permission_denied 三类状态要做不同 UI 表达。verifying 和 metadata_fetching 不能被误显示为“暂停”或“失败”。本文作者:oyph
本文链接:
版权声明:本博客所有文章除特别声明外，均采用 BY-NC-SA 许可协议。转载请注明出处！