Qbit-Manager/开发指南.md

全方位开发指南：构建多客户端 qBittorrent 管理平台

项目愿景

创建一个现代化、集中式、高响应性的 Web 应用，允许用户在一个统一的界面中无缝管理和监控分布在不同设备上的多个 qBittorrent 客户端。目标是提供超越原生 WebUI 的用户体验，并完美适配桌面和移动设备。

---

阶段一：规划与设计 (Planning & Design)

这是项目成功的基石。在此阶段，我们明确“做什么”和“怎么做”。

1. 需求分析与功能定义

   • 核心功能 (MVP - 最小可行产品):
     • 客户端管理：能够安全地添加、编辑、删除和测试 qBittorrent 客户端的连接信息（地址、端口、凭据）。
     • 种子列表：能够聚合展示来自所有或选定客户端的种子，并显示关键信息（名称、进度、状态、速度）。
     • 基本操作：能够对单个或多个种子执行基本操作（暂停、恢复、删除）。
     • 全局概览：显示所有客户端的总上传/下载速度。
   • 进阶功能:
     • 详细信息：查看种子的文件列表、Tracker 状态、Peers 信息。
     • 高级操作：设置种子的分类、标签；调整优先级；重新校验。
     • 过滤与排序：按状态、客户端、分类、标签等对种子列表进行强大的筛选和排序。
     • 添加种子：支持通过磁力链接或种子文件添加新任务。
     • 系统设置：应用本身的主题切换（明亮/暗黑模式）、轮询间隔设置等。

2. 技术选型确认

   • 后端: Python + Flask。轻量、灵活，生态系统成熟，qbittorrent-api 库可直接使用。
   • 前端: Vue.js + Element Plus。现代化的前端框架，组件库美观且功能强大，非常适合构建数据驱动的管理后台。
   • 部署: Docker + Docker Compose。实现环境标准化、一键部署和轻松运维。

3. UI/UX 设计

   • 线框图与原型: 在编写任何代码之前，应该事先构思好完整且全面的UI布局及界面交互逻辑。 这包括但不限于：
     • 主仪表盘（Dashboard）布局。
     • 种子列表的表格/卡片设计。
     • 添加/编辑客户端的表单模态框。
     • 移动设备上的导航（如侧滑菜单）和布局。
     • 种子操作按钮的布局和交互效果。
     • 二级菜单的呼出方式和交互效果。
     • 详细信息页面的设计，包括文件列表、Tracker 状态、Peers 信息等。
     • 高级操作的确认提示和结果反馈。
     • 过滤与排序功能的交互设计。
     • 添加种子的流程，包括磁力链接输入和文件上传。
     • 系统设置的选项卡和布局。
   • 用户流程: 规划用户完成关键任务的路径。例如，“用户如何添加一个新的 qBittorrent 客户端并看到它的种子？”、“用户在手机上如何快速暂停一个正在下载的任务？”。

4. 数据结构设计

   • 客户端配置: 设计存储客户端信息的结构。例如，一个 JSON 文件，其中包含一个对象数组，每个对象代表一个客户端，拥有 id, name, host, port, username, password 等字段。
   • API 数据契约: 初步定义前后端交互的 JSON 数据格式。例如，一个种子的数据对象应该包含哪些字段，全局状态的数据对象又该如何组织。

---

阶段二：后端开发 (Backend Development)

后端是应用的“大脑”，负责所有逻辑处理和与 qBittorrent 的通信。

1. 环境与项目结构

   • 建立 Python 虚拟环境，并使用uv管理环境依赖，使用 python=3.10。
   • 采用蓝图（Blueprints）来组织 Flask 项目，按功能（如 clients_api, torrents_api）划分模块，保持代码清晰。

2. 配置管理

   • 将敏感信息（如默认密码、密钥）与代码分离。使用环境变量或外部配置文件 (config.py或.env或config.yml) 进行管理，这对于 Docker 部署尤其重要。
   • 设计一个安全的机制来存储用户添加的 qBittorrent 客户端凭据，初期可以是文件，但需注意权限控制。

3. API 设计与实现

   • 遵循 RESTful 设计原则，设计无状态、资源导向的 API 端点。
   • 实现阶段一中定义的所有 API 接口。
   • 重点实现一个聚合数据的核心接口（如 /api/maindata），该接口一次性返回前端所需的主要数据（全局速度、种子列表、分类列表等），以减少 HTTP 请求次数，优化前端加载性能。

4. 核心服务逻辑

   • 封装与 qbittorrent-api 的交互逻辑，创建一个服务层。
   • 实现并发请求逻辑，当需要从多个客户端获取数据时，使用并发工具（如 concurrent.futures）同时发起请求，而不是串行等待，这能极大提升响应速度。
   • 建立完善的错误处理机制。能优雅地处理网络超时、认证失败、客户端离线等各种异常，并向前端返回标准化的错误信息。

5. 安全性

   • CORS (跨源资源共享): 配置 Flask 以允许来自前端开发服务器的跨域请求。
   • (可选) 应用级认证: 如果需要多人使用或公网访问，应为应用本身增加一层认证，例如使用 JWT (JSON Web Tokens) 来保护 API。

---

阶段三：前端开发 (Frontend Development)

前端是应用的“脸面”，直接决定了用户体验。

1. 环境与项目结构

   • 使用 Vite 初始化 Vue 项目，获得极速的开发体验。
   • 建立清晰的目录结构：views 存放页面级组件，components 存放可复用的小组件，api 存放所有与后端通信的函数，store 存放状态管理逻辑，router 存放路由配置。

2. 状态管理 (State Management)

   • 使用 Pinia 作为全局状态管理器。
   • 创建不同的 Store 来管理不同的数据域，例如 clientStore (管理客户端列表)、torrentStore (管理种子数据、筛选条件)、appStore (管理全局加载状态、主题、通知)。

3. 组件化构建

   • 将 UI 拆分为可复用的组件。例如，一个 TorrentListItem 组件、一个 GlobalStats 组件、一个 ClientSelector 组件。
   • 页面由这些基础组件组合而成，遵循“自下而上”的构建思路。

4. 响应式布局策略

   • 采用“移动端优先”的设计理念。先设计好在小屏幕上的布局和交互，再通过媒体查询和 Element Plus 的响应式栅格系统逐步增强大屏幕的体验。
   • 灵活运用 ElDrawer（抽屉）、ElDialog（对话框）等容器组件，在不同尺寸的设备上提供最佳的交互模式。

5. 用户体验增强

   • 实时数据更新: 实现一个定时轮询机制，定期从后端获取最新数据并更新界面，给用户“实时”的感觉。
   • 加载状态: 在任何数据请求期间，都应有明确的加载指示（如骨架屏 ElSkeleton 或加载覆盖 v-loading），避免用户面对空白或无响应的界面。
   • 平滑过渡与动画: 利用 Vue 的 <Transition> 和 CSS transition 为元素的出现、消失和状态变化添加自然的动画效果，提升应用的流畅度和质感。
   • 用户反馈: 对用户的每一个操作（成功、失败、警告）都给予即时反馈，使用 Element Plus 的 ElNotification 或 ElMessage 组件。
   • 用户登录: 支持自定义用户名密码进行登录。

---

阶段四：集成与测试 (Integration & Testing)

确保前后端能正确协同工作，并保证软件质量。

1. 联调

   • 在本地同时运行前端开发服务器和后端 Flask 服务器。
   • 配置前端的开发代理，将所有 /api 请求转发到本地的后端端口，解决开发环境下的跨域问题。

2. 测试策略

   • 后端测试: 使用 pytest 等框架，对核心服务逻辑编写单元测试，对 API 端点编写集成测试。
   • 前端测试: 使用 Vitest 或 Jest 对关键组件和 Pinia Store 编写单元测试。
   • 端到端 (E2E) 测试: (可选，适用于复杂项目) 使用 Cypress 或 Playwright 模拟真实用户操作，测试关键用户流程是否通畅。
   • 手动测试: 根据阶段一设计的用户流程，创建一份测试用例清单，手动验证所有功能在不同设备（或浏览器开发者工具的移动视图）上是否正常工作。

---

阶段五：部署 (Deployment)

将开发好的应用发布上线。

1. 容器化

   • 为后端编写 Dockerfile，将其打包成一个包含 Gunicorn 的 Python 应用镜像。
   • 为前端编写多阶段 Dockerfile，先用 Node.js 环境构建出静态文件，再将这些文件放入一个轻量的 Nginx 镜像中。

2. 编排

   • 编写 docker-compose.yml 文件。
   • 定义 backend 和 frontend 两个服务。
   • 配置 Nginx 作为反向代理，将 Web 流量导向静态文件，将 API 请求 (/api/...) 转发到 backend 服务。
   • 使用 volumes 为后端配置数据持久化，确保应用数据（如客户端配置）在容器重启后不丢失。

3. 上线流程

   • 在服务器上安装 Docker 和 Docker Compose。
   • 将整个项目代码（包含所有 Dockerfile 和 docker-compose.yml）上传到服务器。
   • 运行 docker-compose up --build -d 命令一键构建并启动整个应用。
   • 通过 http://<服务器IP>:<指定端口> 访问您的应用。