Skip to content

requirements.md

Latest commit

 

History

History
293 lines (228 loc) · 7.28 KB

requirements.md

File metadata and controls

293 lines (228 loc) · 7.28 KB

MusicPilot - 需求分析文档 v2.0

版本: v2.0 更新: 增加 资源站点站点管理功能 最后更新: 2026-02-26

1. 项目概述

1.1 项目背景

MoviePilot 是一个 NAS 媒体库自动化管理工具，其核心能力是：

  • 资源站点管理: 管理多个 资源站点站点
  • 搜索资源: 在 资源站点搜索电影/电视剧资源
  • 下载种子: 从 资源站点下载种子文件
  • 整理入库: 下载后整理文件，刮削元数据（TMDB）

MusicPilot 参考其架构，专注于音乐领域的资源 自动化管理。

1.2 项目愿景

构建一个简洁、易用、自动化的音乐库管理工具，帮助用户：

  • 管理多个音乐 资源站点
  • 在 资源站点搜索高质量音乐资源
  • 自动下载种子文件
  • 自动整理和刮削元数据（MusicBrainz）
  • 统一管理和播放音乐

1.3 目标用户

  • 资源站点用户: 使用音乐 资源站点下载音乐
  • NAS 用户: 使用 NAS 存储音乐，需要 Web 界面管理
  • 音乐收藏家: 有大量音乐收藏，希望有序管理

2. 用户场景

场景 1: 管理音乐 资源站点

用户: 张三（资源站点用户） 背景: 使用多个音乐 资源站点

流程:

  1. 张三打开 MusicPilot Web 界面
  2. 进入"站点管理"
  3. 添加音乐 资源站点：
    • 输入站点名称（自定义名称）
    • 输入站点地址
    • 配置 Cookie / Passkey / User-Agent
    • 选择下载器（qBittorrent / Transmission）
    • 设置优先级
  4. 测试站点连接
  5. 站点添加成功，可开始搜索和下载

结果:

  • 资源站点配置完成
  • 可以搜索和下载

场景 2: 搜索音乐资源

用户: 张三 背景: 想下载某个 FLAC 专辑

流程:

  1. 张三打开 MusicPilot Web 界面
  2. 进入"搜索"页面
  3. 输入搜索关键词（如 "周杰伦 范特西 FLAC"）
  4. 选择搜索范围（所有站点或指定站点）
  5. 选择分类（音乐 / FLAC / MP3）
  6. 点击"搜索"
  7. 显示搜索结果列表：
    • 站点名称
    • 资源标题
    • 文件大小
    • 做种数/下载数
    • 发布时间
    • 免费状态
    • HR（Hit and Run）状态
  8. 选择合适的资源
  9. 查看资源详情（文件列表、格式、编码等）

结果:

  • 找到想要的 FLAC 专辑
  • 可以准备下载

场景 3: 下载 种子

用户: 张三 背景: 找到想要的资源，准备下载

流程:

  1. 张三选择资源
  2. 点击"下载"
  3. 选择下载器（qBittorrent / Transmission）
  4. 选择保存路径
  5. 确认下载
  6. MusicPilot 自动：
    • 从站点下载种子文件
    • 推送到下载器
    • 开始下载
  7. 显示下载进度

结果:

  • 种子文件推送到下载器
  • 开始下载

场景 4: 下载后整理和刮削

用户: 张三 背景: 下载完成，需要整理和刮削元数据

流程:

  1. 下载完成后，下载器通知 MusicPilot
  2. MusicPilot 自动：
    • 识别下载的文件（艺术家/专辑/曲目）
    • 查询 MusicBrainz 获取元数据
    • 按规则整理文件（Artist/Album/Track.flac）
    • 写入元数据标签（ID3v2/Vorbis）
    • 下载封面图片
    • 更新数据库
  3. 通知用户整理完成
  4. 用户可以在音乐库中看到新专辑

结果:

  • 文件已整理
  • 元数据已刮削
  • 可以播放

3. 功能需求

3.1 核心功能（MVP，P0）

FR-1.1 资源站点管理

  • 添加 资源站点（站点名称、地址、Cookie/Passkey、User-Agent、代理）
  • 编辑 资源站点配置
  • 删除 资源站点
  • 启用/禁用站点
  • 测试站点连接
  • 设置站点优先级
  • 站点 RSS 配置

FR-1.2 搜索音乐资源

  • 在 资源站点搜索音乐
  • 支持关键词搜索（艺术家/专辑/曲目）
  • 支持分类过滤（音乐/FLAC/MP3/Lossless）
  • 支持站点范围选择（所有站点/指定站点）
  • 支持高级过滤（大小、格式、编码、免费状态）
  • 显示搜索结果（站点、标题、大小、做种/下载、发布时间、免费状态、HR）

FR-1.3 下载 种子

  • 下载种子文件
  • 推送到下载器（qBittorrent / Transmission）
  • 显示下载进度
  • 下载失败重试
  • 下载历史记录

FR-1.4 整理和刮削元数据

  • 识别下载文件（艺术家/专辑/曲目）
  • 查询 MusicBrainz 获取元数据
  • 按规则整理文件
  • 写入元数据标签
  • 下载封面图片
  • 更新数据库

FR-1.5 音乐库管理

  • 浏览音乐库（艺术家/专辑/曲目）
  • 播放音乐
  • 播放列表管理

3.2 高级功能（P1-P2）

FR-2.1 订阅功能

  • 订阅艺术家/专辑
  • 自动检查新发布
  • 自动下载新资源

FR-2.2 RSS 订阅

  • 配置站点 RSS
  • 自动获取新资源
  • 自动过滤和下载

FR-2.3 媒体服务器同步

  • 同步到 Plex/Jellyfin

FR-2.4 插件系统

  • 支持第三方 资源站点插件

4. 资源站点支持

4.1 支持的 资源站点类型

本项目支持通过插件扩展各种音乐 资源站点，用户可以根据需要配置自定义站点适配器。

5. 非功能需求

5.1 性能

  • API 响应时间 < 200ms (p95)
  • 搜索响应时间 < 3s
  • 下载整理速度 > 10 文件/分钟

5.2 可靠性

  • 种子下载失败自动重试
  • 元数据刮削失败记录日志
  • 站点连接失败提醒

6. 风险分析

风险 影响 概率 应对措施
资源站点 API 变更 高 高 模块化设计，易于更新站点适配器
种子站点被封 高 中 支持代理，支持多站点
Cookie/Passkey 泄露 高 低 加密存储，不显示完整信息
元数据刮削失败 中 中 支持手动匹配，记录失败原因

7. 验收标准

AC-1 资源站点管理

  • 可以添加/编辑/删除 资源站点
  • 可以测试站点连接
  • 可以启用/禁用站点

AC-2 搜索功能

  • 可以搜索音乐资源
  • 可以过滤和排序结果
  • 可以查看资源详情

AC-3 下载功能

  • 可以下载种子文件
  • 可以推送到下载器
  • 可以查看下载进度

AC-4 整理和刮削

  • 可以自动识别文件
  • 可以自动刮削元数据
  • 可以自动整理文件

8. 优先级排序

P0（必须有）

  • FR-1.1 资源站点管理
  • FR-1.2 搜索音乐资源
  • FR-1.3 下载 种子
  • FR-1.4 整理和刮削元数据
  • FR-1.5 音乐库管理

P1（重要）

  • FR-2.1 订阅功能
  • FR-2.2 RSS 订阅

P2（有价值）

  • FR-2.3 媒体服务器同步
  • FR-2.4 插件系统

附录

A. 资源站点配置说明

字段 说明 示例
站点名称 自定义名称 自定义名称
站点地址 资源站点域名 https://example.com
Cookie 认证 Cookie cccc_xxx=...
Passkey 认证 Passkey xxxxxxxxxxxx
User-Agent UA 字符串 Mozilla/5.0...
代理 是否使用代理 0/1
下载器 关联下载器 qBittorrent
优先级 搜索优先级 1-10
RSS 地址 RSS 订阅地址 https://.../rss

B. 术语表

  • 种子: 包含文件信息的种子文件
  • 做种: 分享下载的资源
  • 下载: 正在下载
  • 站点: 用户配置的音乐资源站点

变更记录:

版本 日期 变更内容
v2.0 2026-02-26 增加 资源站点管理功能，移除具体站点名称