diff --git a/README.md b/README.md index 9e487bd..15c8196 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,18 @@ # OpenBridge -基于 OpenList 的直链下载编排与容量适配系统 +> ⚡ OpenBridge — Complementary bridge service for OpenList +> OpenBridge 是 OpenList 的配套桥接服务，用于补全 OpenList 部分存储驱动缺失的**总容量、已用空间、剩余容量查询能力**，对外提供标准化容量接口，兼容 OpenList API 规范，轻量易部署。 -## 技术栈 -- Go (Backend) -- Vue3 (Frontend) -- aria2 (Download Engine) +[![GitHub Stars](https://img.shields.io/github/stars/SixEngineer/OpenBridge)](https://github.com/SixEngineer/OpenBridge) +[![GitHub Forks](https://img.shields.io/github/forks/SixEngineer/OpenBridge)](https://github.com/SixEngineer/OpenBridge) +[![License](https://img.shields.io/github/license/SixEngineer/OpenBridge)](LICENSE) +**OpenBridge** works as an auxiliary service for OpenList. +Some storage drivers in OpenList lack the capacity‑query capability, cannot return total/used/free storage space. +OpenBridge implements the missing capacity interface, returning standardized storage capacity data to OpenList. +## ✨ Features +- 📦 补全 OpenList 缺失的存储容量查询（总容量 / 已用 / 剩余空间） +- 🔌 兼容 OpenList API 格式，可直接对接 +- ⚡ 轻量高性能，低资源开销 +- 🖥️ 跨平台部署，简单配置即可运行 diff --git a/docs/API.md b/docs/API.md deleted file mode 100644 index ddb8619..0000000 --- a/docs/API.md +++ /dev/null @@ -1,337 +0,0 @@ -# OpenBridge API 文档（临时开发版） - -> 版本：v0.1 (Draft) -> 更新时间：2026-03-28 -> 适用对象：后端开发 / 前端开发 / 自动化脚本开发 - ---- - -# 一、设计原则 - -## 1.1 分层设计 - -API 按业务模块划分： - -* 认证与管理员接口 -* 系统状态接口 -* OpenList 适配接口 -* Provider 扩展接口 -* 下载编排接口 -* aria2 任务接口 -* 容量（Quota）接口 -* 配置接口 -* 日志与调试接口 - -## 1.2 统一返回格式 - -### 成功 - -```json -{ - "code": 0, - "message": "ok", - "data": {} -} -``` - -### 失败 - -```json -{ - "code": 1001, - "message": "error message", - "data": null -} -``` - -## 1.3 通用约定 - -### 基础路径 - -``` -/api/v1 -``` - -### 鉴权方式 - -``` -Authorization: Bearer -``` - -### 分页参数 - -```json -{ - "page": 1, - "page_size": 20 -} -``` - -### 时间格式 - -``` -ISO8601 -``` - ---- - -# 二、认证 API - -## 2.1 登录 - -**POST /api/v1/auth/login** - -请求： - -```json -{ - "username": "admin", - "password": "123456" -} -``` - -返回： - -```json -{ - "code": 0, - "data": { - "access_token": "xxx", - "refresh_token": "xxx", - "expires_in": 7200, - "user": { - "id": 1, - "username": "admin", - "role": "super_admin" - } - } -} -``` - -错误码： - -* 1: wrong password -* 2: unknown user / error - ---- - -## 2.2 登出 - -**POST /api/v1/auth/logout** - ---- - -## 2.3 用户偏好设置 - -**PUT /api/v1/users/me/preferences** - -```json -{ - "theme": "dark", - "default_home": "downloads", - "show_debug_info": true -} -``` - ---- - -# 三、系统状态 API - -## 3.1 健康检查 - -**GET /api/v1/system/health** - -## 3.2 仪表盘 - -**GET /api/v1/system/dashboard** - -## 3.3 组件状态 - -**GET /api/v1/system/status** - ---- - -# 四、OpenList 适配 API - -## 4.1 测试连接 - -**POST /api/v1/openlist/test** - -## 4.2 获取驱动列表 - -**GET /api/v1/openlist/drivers** - -## 4.3 获取目录列表 - -**POST /api/v1/fs/list** - -## 4.4 获取文件信息 - -**POST /api/v1/openlist/fs/get** - -## 4.5 获取原始下载入口 - -**POST /api/v1/fs/raw-link** - ---- - -# 五、Provider API（核心扩展层） - -## 5.1 获取 Provider 列表 - -**GET /api/v1/providers** - -## 5.2 Provider 详情 - -**GET /api/v1/providers/{provider_id}** - -## 5.3 激活 Provider - -**POST /api/v1/providers/{provider_id}/activate** - -## 5.4 停用 Provider - -**POST /api/v1/providers/{provider_id}/deactivate** - -## 5.5 更新二次认证 - -**PUT /api/v1/providers/{provider_id}/secondary-auth** - -## 5.6 测试二次认证 - -**POST /api/v1/providers/{provider_id}/secondary-auth/test** - -## 5.7 能力查询 - -**GET /api/v1/providers/{provider_id}/capabilities** - ---- - -# 六、下载编排 API - -## 6.1 解析下载链路 - -**POST /api/v1/download/resolve** - -## 6.2 提交下载任务 - -**POST /api/v1/download/tasks** - -## 6.3 获取任务列表 - -**GET /api/v1/download/tasks** - -## 6.4 任务详情 - -**GET /api/v1/download/tasks/{task_id}** - -## 6.5 重试任务 - -**POST /api/v1/download/tasks/{task_id}/retry** - -## 6.6 取消任务 - -**POST /api/v1/download/tasks/{task_id}/cancel** - -## 6.7 删除任务 - -**DELETE /api/v1/download/tasks/{task_id}** - ---- - -# 七、容量（Quota）API - -## 7.1 查询路径容量 - -**POST /api/v1/quota/query** - -## 7.2 刷新 Provider 容量 - -**POST /api/v1/quota/providers/{provider_id}/refresh** - -## 7.3 Provider 容量状态 - -**GET /api/v1/quota/providers/{provider_id}** - ---- - -# 八、系统配置 API - -## 8.1 获取配置 - -**GET /api/v1/settings** - -## 8.2 更新 OpenList 配置 - -**PUT /api/v1/settings/openlist** - -## 8.3 更新 aria2 配置 - -**PUT /api/v1/settings/aria2** - -## 8.4 下载策略 - -**PUT /api/v1/settings/download-policy** - -## 8.5 Quota 策略 - -**PUT /api/v1/settings/quota-policy** - ---- - -# 九、调试 API - -## 9.1 下载调试 - -**GET /api/v1/debug/download/{task_id}** - -## 9.2 Provider 调试 - -**GET /api/v1/debug/providers/{provider_id}** - -## 9.3 继承关系 - -**GET /api/v1/debug/inheritance** - ---- - -# 十、设计说明（重要） - -## 10.1 架构核心思想 - -* OpenBridge = OpenList + Provider 扩展 + aria2 编排层 -* 不替代 OpenList，仅做增强 -* Provider = OpenList Storage 的“增强视图” - -## 10.2 关键能力 - -* 二次认证（解决 quota 与下载认证不一致问题） -* 下载链路解析（302 + header 注入） -* aria2 任务映射 -* quota 统一抽象 - -## 10.3 Debug 模式 - -关键接口支持： - -* redirect_chain -* final_url -* headers -* cache_hit -* fallback_reason - ---- - -# 十一、后续优化建议（开发阶段） - -* [ ] 增加错误码规范文档 -* [ ] 定义 provider_id 生成规则 -* [ ] 增加 WebSocket（任务推送） -* [ ] 增加限流与权限模型 -* [ ] OpenAPI / Swagger 自动生成 - ---- - -# 备注 - -该文档为临时开发版本，字段与接口可能调整。 diff --git a/docs/backend_dev.md b/docs/backend_dev.md deleted file mode 100644 index 36a18d9..0000000 --- a/docs/backend_dev.md +++ /dev/null @@ -1,100 +0,0 @@ - -API 接口文档：https://openbridge.apifox.cn - -卢宇扬、郑源羽 - -#### 2026.04.06 - -按照项目规范搭建了后端的基本框架，详细如下。 - -``` -backend/ -├── main.go # 程序入口文件 -├── go.mod -├── go.sum -├── openbridge.db # SQLite 数据库文件 -├── internal/ # 内部业务代码 -│ ├── domain/ # 领域层 - 定义核心业务模型和接口 -│ ├── handler/ # 表现层 - HTTP 处理器，处理请求和响应 -│ ├── repository/ # 数据访问层 - 数据库操作实现 -│ ├── usecase/ # 应用层 - 业务逻辑实现 -│ └── tool/ # 工具层 - 通用工具函数 -└── pkg/ # 可被外部引用的公共包 - └── db/ # 数据库相关公共包 -``` - -实现了以下两个提供给前端的接口，这里只做简要介绍，具体查看 API 接口文档。 - -- 上传AccessToken - -由于大多数网盘都需要access token进行身份验证，因此需要将用户的access token上传到服务器，以便服务器可以代表用户进行操作。服务器将access token存储在数据库中，以便在需要时使用。 - -- 上传RefreshToken - -由于access token通常具有较短的有效期，因此需要定期刷新access token。服务器将refresh token存储在数据库中，以便在需要时使用。 - -下一次开发任务：实现获取容量相关的接口。 - -#### 2026.04.16 - -- 实现了Zap日志系统，目前能够以JSON格式输出日志。 - -日志格式示例如下，这是一个HTTP请求的日志输出。 - -```json -{ - "level":"info", - "ts":"2026-04-16T10:15:00.533+0800", - "caller":"middleware/access_log.go:42", - "msg":"", - "request_id":"req_e98c1cbd7fb4978034497fff", - "method":"GET", - "path":"/api/v1/provider/info", - "status":1000, - "latency":0.0011538 -} -``` - -- 实现了以下接口，具体信息查看 API 接口文档。 - -其中涵盖了provider的增删改查，quota的查询和同步。目前暂时使用mock数据作为返回内容。 - -POST /api/v1/provider -DELETE /api/v1/provider -PUT /api/v1/provider -GET /api/v1/provider/info -GET /api/v1/provider/list -POST /api/v1/quota/query -POST /api/v1/quota/sync - -#### 2026.04.24 - -- 完成 Baidu Provider 首版接入，支持真实容量获取。 - -- 在保留现有 provider/quota 接口的前提下，新增 Mount + Quota Policy MVP，支持 `real / inherit / virtual` 三种模式及对应校验逻辑。 - -- 扩展 QuotaSnapshot，补充 mode、sync_status、error_message 等字段，用于记录每次配额解析结果与失败原因。 - -- 新增接口： - -POST /api/v1/mount -GET /api/v1/mount/:id/quota -POST /api/v1/mount/:id/quota/sync - -- 已完成基础验证，原有 mock provider 与 quota query/sync 流程保持兼容。 - -#### 2026.04.30 - -TODO：完善 Refresh Token 机制，支持自动刷新 Access Token。 - -目前已经尝试由我们自己的 `refresh_token` 生成新的 `access_token`，但发现 Baidu 提供的 API 需要在百度开放平台配置一个应用，并申请上线审核，暂时无法实现。 - -#### 2026.06.07 - -- 修复 OpenFileLocation Windows 下路径含空格或相对路径时 explorer /select, 定位错误的问题 - - getActualFilePath 增加 filepath.Abs + strings.TrimSpace 确保返回绝对路径 - - OpenFile（cmd /c start）不受影响，因为 start 使用 ShellExecute Win32 API，可直接处理相对路径和含空格路径 - -- RetryTask: 修复重复 AddURI 的 bug，改为 if/else 分支 -- GetTask: 同步 aria2 状态时处理 GID not found 情况，标记为 error -- 新增 DownloadUseCase.getActualFilePath 降级逻辑（DownloadDir + FileName 拼接） \ No newline at end of file diff --git a/docs/frontend_dev.md b/docs/frontend_dev.md deleted file mode 100644 index 6bc0bcf..0000000 --- a/docs/frontend_dev.md +++ /dev/null @@ -1,1165 +0,0 @@ -# OpenBridge 前端开发日志 - -> 说明：本文档不是最终方案文档，也不是结题总结。 -> 它的用途是记录前端到当前为止做了什么、为什么这样做、现在处于什么状态，后续继续开发时应持续追加，不断完善。 - ---- - -## 日志使用规则 - -- 这份文档按“开发日志”维护 -- 每完成一项前端工作，就在文档中新增记录 -- 记录重点是：做了什么、当前状态、涉及文件、后续待做 -- 不写最终结论，不写终局判断 -- 文档应随着项目推进持续补充 - ---- - -## 2026-04-07 前端方向确认 - -### 本次确认内容 - -- 明确项目文档中前端技术栈为 `Vue3` -- 明确当前仓库里原始的 [frontend](/e:/se_work/Monorepo/frontend) 目录尚未正式开发 -- 明确当前后端代码实现还比较早，前端可以先独立推进 -- 明确前端现阶段应以 mock 数据驱动开发，而不是等待完整后端 - -### 当前理解 - -根据当前仓库与文档，`OpenBridge` 前端更适合做成一个“管理控制台”，而不是普通网盘页面或纯展示页。 - -页面重点应围绕以下模块展开： - -- Dashboard -- OpenList -- Providers -- Download Tasks -- Quota -- Settings -- Debug - -### 当前状态 - -- 前端可以启动独立搭建 -- 不必等待后端全部完成 -- 当前开发应以“先搭控制台骨架”为主 - ---- - -## 2026-04-07 页面结构规划整理 - -### 本次完成内容 - -根据项目定位，整理出一套适合 `OpenBridge` 的前端页面结构。 - -### 规划结果 - -建议前端页面结构为： - -```text -OpenBridge Frontend -├─ 登录 / 入口 -├─ Dashboard -├─ OpenList -├─ Providers -├─ Download Tasks -├─ Quota -├─ Settings -└─ Debug -``` - -### 页面作用说明 - -#### Dashboard - -- 展示系统总览 -- 展示运行状态 -- 展示任务、告警、服务健康情况 - -#### OpenList - -- 展示 OpenList 接入相关功能入口 -- 后续可放连接测试、驱动列表、目录浏览等内容 - -#### Providers - -- 展示 Provider 列表和状态 -- 展示能力信息和认证方式 - -#### Download Tasks - -- 展示下载任务列表 -- 展示进度、状态、目标路径等内容 - -#### Quota - -- 展示容量信息 -- 展示各 Provider 的使用情况 - -#### Settings - -- 放置配置相关页面 - -#### Debug - -- 放置调试、排错和链路分析内容 - -### 当前状态 - -- 页面结构已形成统一认识 -- 后续开发可以按这套结构推进 - ---- - -## 2026-04-07 控制台原型建立 - -### 本次完成内容 - -独立创建了一个新的前端原型目录： - -- [frontend_test](/e:/se_work/Monorepo/frontend_test) - -该目录不影响原始 [frontend](/e:/se_work/Monorepo/frontend)，作为单独的前端原型开发空间。 - -### 当前技术实现 - -在 `frontend_test` 中已完成以下基础搭建： - -- `Vue3` -- `Vite` -- `TypeScript` -- `Vue Router` -- `Pinia` - -### 当前已建立的项目结构 - -已建立的主要结构包括： - -- 路由入口 -- 全局入口 -- 页面目录 -- 组件目录 -- 样式目录 -- mock 数据目录 -- store 目录 - -### 当前已建立的页面 - -当前已经建立这些页面文件： - -- [DashboardView.vue](/e:/se_work/Monorepo/frontend_test/src/views/DashboardView.vue) -- [OpenListView.vue](/e:/se_work/Monorepo/frontend_test/src/views/OpenListView.vue) -- [ProviderView.vue](/e:/se_work/Monorepo/frontend_test/src/views/ProviderView.vue) -- [DownloadTasksView.vue](/e:/se_work/Monorepo/frontend_test/src/views/DownloadTasksView.vue) -- [QuotaView.vue](/e:/se_work/Monorepo/frontend_test/src/views/QuotaView.vue) -- [SettingsView.vue](/e:/se_work/Monorepo/frontend_test/src/views/SettingsView.vue) -- [DebugView.vue](/e:/se_work/Monorepo/frontend_test/src/views/DebugView.vue) -- [LoginView.vue](/e:/se_work/Monorepo/frontend_test/src/views/LoginView.vue) - -### 当前已建立的布局组件 - -已建立的主要布局文件： - -- [AppShell.vue](/e:/se_work/Monorepo/frontend_test/src/components/layout/AppShell.vue) -- [AppSidebar.vue](/e:/se_work/Monorepo/frontend_test/src/components/layout/AppSidebar.vue) -- [AppTopbar.vue](/e:/se_work/Monorepo/frontend_test/src/components/layout/AppTopbar.vue) - -### 当前已建立的基础通用组件 - -- [PageHeader.vue](/e:/se_work/Monorepo/frontend_test/src/components/common/PageHeader.vue) -- [MetricCard.vue](/e:/se_work/Monorepo/frontend_test/src/components/common/MetricCard.vue) -- [StatusBadge.vue](/e:/se_work/Monorepo/frontend_test/src/components/common/StatusBadge.vue) - -### 当前样式情况 - -已建立全局样式文件： - -- [index.css](/e:/se_work/Monorepo/frontend_test/src/styles/index.css) - -当前样式方向是： - -- 控制台式布局 -- 左侧导航 + 顶部栏 + 主内容区 -- 玻璃感卡片 -- 偏工程系统风格 - -### 当前状态 - -- 控制台壳子已经建立 -- 路由与页面关系已经打通 -- 当前页面已有基础视觉效果 -- 多数业务页目前仍属于“结构占位 + 部分演示数据”阶段 - ---- - -## 2026-04-07 mock 数据接入 - -### 本次完成内容 - -为避免等待后端接口，已使用 mock 数据驱动控制台原型。 - -### 当前 mock 数据文件 - -- [dashboard.ts](/e:/se_work/Monorepo/frontend_test/src/mock/dashboard.ts) -- [provider.ts](/e:/se_work/Monorepo/frontend_test/src/mock/provider.ts) -- [tasks.ts](/e:/se_work/Monorepo/frontend_test/src/mock/tasks.ts) -- [quota.ts](/e:/se_work/Monorepo/frontend_test/src/mock/quota.ts) - -### 当前 store 文件 - -- [console.ts](/e:/se_work/Monorepo/frontend_test/src/stores/console.ts) - -### 当前 mock 数据作用 - -当前这些数据用于支撑： - -- Dashboard 指标卡片 -- 服务健康状态 -- 最近任务 -- 告警信息 -- Provider 列表 -- 下载任务列表 -- Quota 卡片 - -### 当前状态 - -- 前端展示内容不依赖真实接口 -- 可以先独立继续做页面 -- 后续联调时需要逐步替换为真实接口数据 - ---- - -## 2026-04-07 关于登录页面的处理说明 - -### 当前情况 - -在 `frontend_test` 中已建立： - -- [LoginView.vue](/e:/se_work/Monorepo/frontend_test/src/views/LoginView.vue) - -但该页面当前只是静态页面占位，不是正式登录流程。 - -### 当前未实现内容 - -以下内容目前都还没有做： - -- token 保存 -- 登录状态管理 -- 路由守卫 -- 权限控制 -- 登出逻辑 - -### 当前状态说明 - -也就是说，当前 `frontend_test` 更接近“控制台原型”而不是“完整带鉴权系统的前端”。 - -这个问题在讨论中已经被指出，后续不应把现在这套登录占位理解为最终方案。 - ---- - -## 2026-04-07 免登录门户方案确认 - -### 本次确认内容 - -在讨论中提出了一种新的入口方式： - -- 不使用传统登录页作为主要入口 -- 使用一个视觉上更有设计感的 `OpenBridge` 字标启动页 -- 只要 `OpenList` 没断开，就允许进入控制台 - -### 当前方案理解 - -该方案的核心逻辑是： - -1. 用户先看到一个沉浸式 `OpenBridge` 门户页 -2. 门户页展示当前 OpenList 连接状态 -3. 若连接正常，点击字标即可进入控制台 -4. 控制台本体保持独立 - -### 当前状态 - -- 已形成明确方案 -- 方案偏向课程项目展示效果 -- 暂不走传统登录页路线 - ---- - -## 2026-04-07 免登录门户原型建立 - -### 本次完成内容 - -独立创建了一个新的门户目录： - -- [frontend_portal](/e:/se_work/Monorepo/frontend_portal) - -该目录同样不影响原始 [frontend](/e:/se_work/Monorepo/frontend) 和 [frontend_test](/e:/se_work/Monorepo/frontend_test)。 - -### 当前已建立内容 - -已建立以下文件： - -- [package.json](/e:/se_work/Monorepo/frontend_portal/package.json) -- [main.ts](/e:/se_work/Monorepo/frontend_portal/src/main.ts) -- [App.vue](/e:/se_work/Monorepo/frontend_portal/src/App.vue) -- [styles.css](/e:/se_work/Monorepo/frontend_portal/src/styles.css) - -### 当前门户页功能 - -当前门户页实现了： - -- 大型 `OpenBridge` 字标展示 -- OpenList 连接状态显示 -- 点击字标进入控制台 -- 点击按钮进入控制台 - -### 当前跳转目标 - -当前门户页目标地址为： - -```text -http://localhost:5173/dashboard -``` - -即指向 `frontend_test` 控制台。 - -### 当前状态 - -- 免登录门户原型已建立 -- 门户页和控制台已分离 -- 当前连接状态还是演示逻辑，未接真实接口 - ---- - -## 2026-04-08 门户页视觉精简与说明收敛 - -### 本次完成内容 - -对 `frontend_portal` 门户页做了一轮收敛式调整，目标是把页面从“演示说明页”继续压缩成更纯粹的“启动入口页”。 - -本次主要完成： - -- 移除右上角的演示用连接状态切换开关 -- 移除底部 3 个解释性信息卡片 -- 移除按钮下方的目标地址说明文案，不再在页面上暴露跳转目标 -- 调整 `OpenBridge` 字标样式，缓解 `g` 下沿和 `e` 右侧的视觉截断感 -- 保留左上角连接状态和中间主按钮，继续维持“单页入口”结构 - -### 涉及文件 - -- [App.vue](/e:/se_work/Monorepo/frontend_portal/src/App.vue) -- [styles.css](/e:/se_work/Monorepo/frontend_portal/src/styles.css) - -### 调整原因 - -- 右上角开关会让页面过于像演示面板，而不是正式入口 -- 底部说明卡片信息密度低，会稀释入口页的焦点 -- 跳转目标地址属于开发实现细节，不适合直接展示给用户 -- 门户页目前的核心职责是“确认可进入并发起进入”，不需要承担解释过多背景信息的任务 - -### 当前状态 - -- 门户页结构已经明显简化 -- 页面视觉焦点集中在品牌字标、连接状态和进入动作 -- 当前仍保留本地演示逻辑：连接状态为前端内部状态，点击后跳转到 `http://localhost:5173/dashboard` -- `frontend_portal` 现阶段更适合被理解为“控制台启动页原型”，而不是完整业务首页 - -### 后续待做 - -- 将连接状态从本地 `ref` 状态切换为真实健康检查结果 -- 决定门户页是否保留英文文案，或统一改为中文 -- 如果后续继续优化视觉，可考虑将 `OpenBridge` 字标替换为更稳定的品牌化方案，而不是仅靠超粗文字样式支撑 - ---- - -## 2026-04-08 正式前端目录收敛 - -### 本次完成内容 - -将此前分散在 `frontend_test` 与 `frontend_portal` 两个原型目录中的成果正式收敛到 [frontend](/e:/se_work/Monorepo/frontend)。 - -本次主要完成： - -- 以 `frontend_test` 作为正式前端工程底座，补全 `frontend` 目录的 Vue + Vite + TypeScript 工程结构 -- 将门户页整合进正式前端，新增首页入口页 [PortalView.vue](/e:/se_work/Monorepo/frontend/src/views/PortalView.vue) -- 调整路由结构，使 `/` 作为门户页，`/dashboard` 作为控制台首页 -- 将门户页点击进入的行为从“跳到外部原型地址”改为“跳到同一前端工程内的控制台路由” -- 为正式前端目录安装依赖并完成构建验证 -- 清理原型目录 [frontend_test](/e:/se_work/Monorepo/frontend_test) 与 [frontend_portal](/e:/se_work/Monorepo/frontend_portal)，避免团队后续继续基于临时目录开发 - -### 涉及文件 - -- [package.json](/e:/se_work/Monorepo/frontend/package.json) -- [vite.config.ts](/e:/se_work/Monorepo/frontend/vite.config.ts) -- [index.ts](/e:/se_work/Monorepo/frontend/src/router/index.ts) -- [PortalView.vue](/e:/se_work/Monorepo/frontend/src/views/PortalView.vue) -- [frontend_开发文档.md](/e:/se_work/frontend_开发文档.md) - -### 调整原因 - -- 团队协作时应只保留一个正式前端目录，避免多人分别在不同原型目录继续开发 -- `frontend_test` 与 `frontend_portal` 各自承担了一部分能力，但并行存在不利于分支协作、联调和答辩说明 -- 将门户页与控制台合并到同一工程后，项目结构更符合 Monorepo 下正式应用目录的定位 - -### 当前状态 - -- [frontend](/e:/se_work/Monorepo/frontend) 已成为唯一正式前端工程 -- 正式前端已可通过 `npm run dev` 启动，并通过 `npm run build` 构建验证 -- 首页为门户页，门户页进入后跳转到同工程内的 `/dashboard` -- 旧原型目录已完成阶段使命，不再作为后续开发目标 - -### 后续待做 - -- 将控制台页面中的演示数据逐步替换为真实接口 -- 视团队决定，统一前端页面文案语言风格 -- 后续所有前端新功能都应基于 [frontend](/e:/se_work/Monorepo/frontend) 继续推进 - ---- - -## 当前目录说明 - -### 原始目录 - -- [frontend](/e:/se_work/Monorepo/frontend) - - 当前为正式前端工程，包含门户页与控制台 - -### 当前目录状态 - -- `frontend_test` - - 原控制台原型目录，现已并入 `frontend` - -- `frontend_portal` - - 原门户页原型目录，现已并入 `frontend` - -### 当前文档文件 - -- [frontend_开发文档.md](/e:/se_work/Monorepo/frontend_开发文档.md) - - 用途：持续记录前端开发进度 - ---- - -## 当前已知待继续完善内容 - -以下内容目前还没有完成，后续开发时可继续往日志中追加： - -- `frontend` 页面中文化 -- Dashboard 内容继续细化 -- OpenList 页面从占位升级为真实结构 -- Providers 页面增加更多管理交互 -- Tasks 页面增加详情、筛选、状态动作 -- Quota 页面增加更清晰的数据展示 -- Settings 页面补充真实配置表单 -- Debug 页面补充调试结构 -- mock 数据逐步向真实接口字段收拢 -- 门户页连接状态改为真实健康检查 - ---- - -## 2026-04-19 前后端接口对接 - -### 本次完成内容 - -完成前端控制台核心业务模块与后端接口的对接，将此前基于 mock 数据的页面替换为真实 API 调用。 - -本次主要完成： - -- **Provider 模块对接** - - 实现 Provider 列表获取 - - 实现 Provider 注册功能 - - 实现 Provider 编辑功能 - - 实现 Provider 删除功能 - - 新增 ProviderFormDialog 表单对话框组件 - -- **Quota 模块对接** - - 实现配额查询功能（不触发远端同步） - - 实现配额同步功能（调用远端接口） - - 展示总配额、已用配额、可用配额及使用进度条 - -- **Token 模块对接** - - 新增 Token 管理页面 - - 实现 Token 上传功能 - - 支持选择网盘类型（mock/baidu/aliyun/quark） - -- **基础设施完善** - - 安装并配置 axios 请求库 - - 创建统一的请求封装 `utils/request.ts` - - 配置 Vite 代理解决跨域问题 - - 完善 TypeScript 类型定义，匹配后端数据结构 - - 调整状态管理 `stores/console.ts`，接入真实 API - - 适配前端状态显示组件（StatusBadge）以匹配后端状态值（active/disabled/expired/error） - -### 涉及文件 - -**新增文件：** -- [frontend/src/utils/request.ts](/e:/se_work/Monorepo/frontend/src/utils/request.ts) -- [frontend/src/api/provider.ts](/e:/se_work/Monorepo/frontend/src/api/provider.ts) -- [frontend/src/api/quota.ts](/e:/se_work/Monorepo/frontend/src/api/quota.ts) -- [frontend/src/api/token.ts](/e:/se_work/Monorepo/frontend/src/api/token.ts) -- [frontend/src/types/quota.ts](/e:/se_work/Monorepo/frontend/src/types/quota.ts) -- [frontend/src/types/token.ts](/e:/se_work/Monorepo/frontend/src/types/token.ts) -- [frontend/src/views/TokenView.vue](/e:/se_work/Monorepo/frontend/src/views/TokenView.vue) -- [frontend/src/components/provider/ProviderFormDialog.vue](/e:/se_work/Monorepo/frontend/src/components/provider/ProviderFormDialog.vue) -- [frontend/.env.development](/e:/se_work/Monorepo/frontend/.env.development) - -**修改文件：** -- [frontend/package.json](/e:/se_work/Monorepo/frontend/package.json)（添加 axios 依赖） -- [frontend/vite.config.ts](/e:/se_work/Monorepo/frontend/vite.config.ts)（添加代理配置） -- [frontend/src/stores/console.ts](/e:/se_work/Monorepo/frontend/src/stores/console.ts) -- [frontend/src/views/ProviderView.vue](/e:/se_work/Monorepo/frontend/src/views/ProviderView.vue) -- [frontend/src/views/QuotaView.vue](/e:/se_work/Monorepo/frontend/src/views/QuotaView.vue) -- [frontend/src/types/provider.ts](/e:/se_work/Monorepo/frontend/src/types/provider.ts) -- [frontend/src/types/common.ts](/e:/se_work/Monorepo/frontend/src/types/common.ts) -- [frontend/src/components/common/PageHeader.vue](/e:/se_work/Monorepo/frontend/src/components/common/PageHeader.vue) -- [frontend/src/components/common/StatusBadge.vue](/e:/se_work/Monorepo/frontend/src/components/common/StatusBadge.vue) -- [frontend/src/components/layout/AppSidebar.vue](/e:/se_work/Monorepo/frontend/src/components/layout/AppSidebar.vue) -- [frontend/src/router/index.ts](/e:/se_work/Monorepo/frontend/src/router/index.ts) -- [frontend/src/styles/index.css](/e:/se_work/Monorepo/frontend/src/styles/index.css) - -### 当前状态 - -- Provider 模块已完成完整的增删改查功能，数据来源于真实后端接口 -- Quota 模块已完成查询与同步功能，可正确展示配额数据 -- Token 模块已完成上传功能，可向指定网盘类型上传 Token -- 前端通过 Vite 代理方式解决跨域问题，无需依赖后端 CORS 配置 -- 所有对接模块均已在本地完成测试，功能正常运行 - -### 后续待做 - -- Dashboard 页面数据接入真实接口 -- OpenList 页面从占位升级为真实功能 -- Download Tasks 页面等待后端接口完成后进行对接 -- Quota 历史快照展示（等待后端暴露 QuotaSnapshot 接口） -- 统一前后端响应码处理逻辑 -- 完善全局错误处理和用户提示 - ---- - -## 2026-06-05 前端交互细节优化 - -### 本次完成内容 - -对前端多个页面进行了交互细节和 UI 优化，包括复选框多选、排序、配额展示、管理员模式等。 - -- **下载任务页复选框多选** - - 新增列首全选复选框（始终可见，浅蓝色 `accent-color: #bfdbfe`） - - 行复选框默认不可见，hover 行时显示 - - 选中后复选框保持可见 - - 支持全选/取消全选，切换筛选标签时清空选中 - - 统一清除按钮：有选中项时显示”清除 (N)”，有已完成任务时显示”清空全部” - -- **移除刷新按钮** - - 下载任务页移除手动刷新按钮，刷新浏览器即可 - -- **OpenList 默认排序改为降序** - - `sortOrder` 默认值从 `'asc'` 改为 `'desc'` - -- **配额管理页简化** - - 移除”查询配额”按钮，只保留”同步配额” - - 进入页面后自动同步一次配额 - -- **Provider 表单调整** - - 注册按钮与描述文字对齐 - -- **页面头部调整** - - 移除所有页面左上角的”模块”小字 - -- **登录/退出流程修复** - - 退出登录后跳转到 `/login` 而非首页 - - 修复退出后仍能查看数据的问题 - -- **管理员模式** - - 双击顶部栏 OpenList 状态指示器切换管理员模式 - - 管理员模式持久化到 localStorage - - 侧边栏 Debug 页面仅管理员可见 - - 路由守卫拦截非管理员访问 `/debug` - -- **Mock Provider 配额单位修正** - - Mock 类型配额从 MB 改为 GB 展示（Dashboard/Provider/Quota 三个页面） - - Mock 数据源数值重新计算（1000 MB → 1024000 GB 等） - -- **Dashboard 存储用量卡片交互** - - 点击”存储用量”指标卡展开所有 Provider 配额明细 - - 展开后可点击选择某一个作为默认展示（主指标卡显示选中 Provider 的名称和数据） - -- **i18n 翻译修正** - - “Provider” 统一翻译为”服务商” - - 新增 `tasks.clear_selected` 等翻译键 - -### 涉及文件 - -- `frontend/src/views/DownloadTasksView.vue` -- `frontend/src/views/DashboardView.vue` -- `frontend/src/views/QuotaView.vue` -- `frontend/src/views/ProviderView.vue` -- `frontend/src/views/OpenListView.vue` -- `frontend/src/components/common/PageHeader.vue` -- `frontend/src/components/common/MetricCard.vue` -- `frontend/src/components/layout/AppTopbar.vue` -- `frontend/src/components/layout/AppSidebar.vue` -- `frontend/src/stores/console.ts` -- `frontend/src/router/index.ts` -- `frontend/src/i18n/locales/zh-CN.json` -- `frontend/src/i18n/locales/en.json` -- `frontend/src/mock/provider.ts` - -### 当前状态 - -- 下载任务页支持复选框多选和批量清除 -- Dashboard 存储用量卡片支持展开和选择默认 Provider -- 管理员模式已实现，可以保护敏感页面 -- Mock 数据配额单位已对齐 MB/GB -- 页面整体交互流畅度提升 - -### 后续待做 - -- 下载页复选框样式微调（对齐、选中态可见性） - ---- - -## 2026-06-06 前端细节修复与 Provider 表单增强 - -### 本次完成内容 - -修复了多项 UI 细节问题，增强 Provider 注册表单的易用性，完善国际化文案。 - -- **复选框交互修复** - - 选中（checked）的复选框保持可见，不依赖 hover 状态 - - 移除 `padding-top: 2px` 使复选框与文件名文字对齐 - -- **Settings 页面 OpenList 卡片精简** - - 移除状态字段中的驱动数量文字（仍保留连接状态圆点指示器） - - 新增 `openlist_connected` 翻译键 - -- **侧边栏翻译优化** - - `openlist_desc`: “网盘源访问” → “文件浏览” - - `providers_desc`: “适配器注册” → “服务商管理” - -- **Provider 注册表单增强** - - 百度网盘：access_token 输入框旁新增”点我获取 Token”按钮，跳转 https://api.oplist.org - - 夸克网盘：Cookie 输入框旁新增”点我获取 Cookie”按钮，跳转 https://pan.quark.cn - - 百度提示文案改为”通过百度网盘验证登录填写对应的 Key，获取令牌” - - 后端类型选项”通用（推荐）”改为”通用” - -- **下载任务详情增强** - - 直链行新增”点击复制”按钮（复制到剪贴板，短暂显示”已复制!”） - - 直链改为横向滚动显示，不再撑破容器 - -- **OpenList 文件浏览器修复** - - 过滤 API 返回的 `provider: “unknown”`，改为显示当前路径 - -- **国际化同步** - - 同步更新 en.json 中对应的翻译文案（Baidu hint、Generic、copy_link、get_cookie 等） - - 新增 `tasks.copy_link`、`provider_form.get_token`、`provider_form.get_cookie` 翻译键 - -### 涉及文件 - -- `frontend/src/views/DownloadTasksView.vue` -- `frontend/src/views/OpenListView.vue` -- `frontend/src/views/SettingsView.vue` -- `frontend/src/components/provider/ProviderFormDialog.vue` -- `frontend/src/i18n/locales/zh-CN.json` -- `frontend/src/i18n/locales/en.json` -- `docs/frontend_dev.md` - -### 当前状态 - -- Provider 表单对百度网盘和夸克网盘提供了快捷跳转入口，降低用户操作成本 -- 直链复制功能已可用 -- 翻译文案持续优化，中英文同步维护 -- 复选框交互符合预期：未选中的 hover 显示，选中的常驻可见 - -### 后续待做 - -- 下载任务详情面板响应式布局优化 -- Provider 表单校验增强（如 token/cookie 非空校验） -- 下载任务页选中项批量操作功能完善（如批量重新下载） - -## 2026-05-28 前端交互链路完善 - -### 本次完成内容 - -完善了前端多个模块的交互链路，打通从 Provider 注册 → Mount 创建 → 配额查看 → 文件浏览 → 下载的完整流程。 - -- **Provider 表单重构** - - 将表单从"选择 OpenList 驱动"改为直接选择后端支持的三种 Provider 类型（通用/百度网盘/本地存储） - - 百度网盘类型显示 access_token 输入框 - - 本地存储类型显示路径输入框，路径存入 account_id 字段 - - Provider 卡片页对本地类型显示"本地路径"而非"账户ID" - -- **Quota 页面完善** - - 修复 MB 显示问题（后端以 MB 为单位返回，前端 formatBytes 按字节处理），增加 formatQuotaMB 中间转换函数 - - 创建 Mount 时支持选择配额模式：Real（真实容量）/ Virtual（虚拟容量），Inherit 预留 - - Virtual 模式可输入虚拟总容量（MB） - - 增加操作状态反馈提示（成功/失败） - -- **OpenList 文件列表增加下载入口** - - 文件列表每行增加"下载"按钮（仅文件类型） - - 点击后弹出下载确认弹窗 - - 弹窗自动解析直链，显示文件名/大小/Provider/直链/是否走代理 - - 可选填下载目录，确认后提交到 aria2 - -- **下载任务列表改造** - - 从单任务创建页改为任务列表视图 - - 显示所有历史任务，支持状态筛选（All/Active/Completed/Failed等） - - 每个任务显示文件名/大小/状态/进度/创建时间 - - 点击行展开详情面板 - - 活跃任务自动每 5 秒刷新，完成后自动停止 - -### 涉及文件 - -**新增文件：** -- `frontend/src/components/download/DownloadDialog.vue` - -**修改文件：** -- `frontend/src/views/OpenListView.vue` -- `frontend/src/views/QuotaView.vue` -- `frontend/src/views/DownloadTasksView.vue` -- `frontend/src/views/ProviderView.vue` -- `frontend/src/components/provider/ProviderFormDialog.vue` -- `frontend/src/stores/console.ts` -- `frontend/src/api/task.ts` -- `frontend/src/types/download.ts` - -### 当前状态 - -- Provider 表单已覆盖后端支持的三种类型 -- Quota 页面已支持 Real/Virtual 配额模式，Mount 创建后可查询和同步 -- 文件浏览到下载的链路已打通：OpenList 文件列表 → 下载弹窗 → 确认 → aria2 -- 下载任务列表可查看所有历史任务和实时进度 -- 本次所有改动不涉及后端代码 - -### 后续待做 - -- 下载确认弹窗成功后跳转到任务列表的交互优化 -- Inherit 配额模式需后端暴露 mount 列表 API 后再启用 -- aria2 未启动时的错误提示优化 -- 任务列表手动刷新按钮的加载状态细化 - ---- - -## 2026-06-06 Settings/Debug 页面重构与路由权限调整 - -### 本次完成内容 - -对 Settings、Dashboard、Debug 三个页面进行了功能重分布，并调整了 Debug 页面的访问权限策略。 - -- **Settings 页面精简** - - 移除只读状态信息（API 连接、OpenList 状态、服务商统计） - - 仅保留用户可配置项：aria2 RPC URL（管理员可修改）和默认下载目录 - - OpenList 基础 URL 字段，仅管理员可修改 - - 已连接状态用圆点指示器简化显示 - -- **Dashboard 页面调整** - - OpenList 状态卡片替换为 aria2 RPC 连接状态 - - 系统健康检测增加 aria2 状态检查（通过直接 JSON-RPC 调用 `aria2.getVersion`） - - 保留顶部 OpenList 连接状态指示器 - -- **Debug 页面完善** - - 新增 API 连接信息面板（Base URL / Proxy Target / Timeout） - - 重置用户数据功能从 Settings 移至 Debug - - 重置按钮仅管理员可见 - -- **权限策略调整** - - Debug 页面改为所有用户可见（移除路由 `meta.admin` 守卫和侧边栏过滤） - - 只有重置数据按钮受管理员权限控制 - -- **其他修复** - - Provider 表单百度/夸克增加外部链接按钮 - - 下载任务详情直链增加复制按钮 - - OpenList 文件浏览器过滤 `provider: "unknown"` - - 复选框对齐修复 - -### 涉及文件 - -- `frontend/src/views/DashboardView.vue` -- `frontend/src/views/SettingsView.vue` -- `frontend/src/views/DebugView.vue` -- `frontend/src/router/index.ts` -- `frontend/src/components/layout/AppSidebar.vue` -- `frontend/src/components/provider/ProviderFormDialog.vue` -- `frontend/src/views/OpenListView.vue` -- `frontend/src/views/DownloadTasksView.vue` -- `frontend/src/i18n/locales/zh-CN.json` -- `frontend/src/i18n/locales/en.json` -- `docs/frontend_dev.md` - -### 当前状态 - -- Settings 页面功能定位明确：仅展示用户可配置项 -- Dashboard 更加专注系统实时状态（aria2 RPC 取代 OpenList 状态卡） -- Debug 作为诊断入口，对所有用户可见，破坏性操作受管理员权限保护 -- 管理员模式已从"页面级拦截"改为"操作级控制" - ---- - -## 2026-06-06 下载状态重构与交互完善 - -### 本次完成内容 - -对下载任务的状态机逻辑进行全面重构，联动后端修复 aria2 离线检测，优化轮询策略、清空按钮行为、登录键盘导航和 Dashboard 交互细节。 - -- **下载状态机重构（前后端协作）** - - 后端 `CreateTask`：初始状态从 `"active"` 改为 `"waiting"`，更准确表达刚提交尚未开始的状态 - - 后端 `GetTask`：TellStatus 成功时写入 `FinishedAt` 时间戳；TellStatus 返回"GID not found"且当前不是 `complete` 时将任务标记为 `error` - - 修复 aria2 错误消息匹配：aria2 实际返回 `"GID xxxx is not found"`（非文档中的 `"No such download"`），字符串匹配改为 `strings.Contains(err.Error(), "not found")` - - 修复全部标记为 error 的问题：增加 `&& task.Status != "complete"` 保护，已完成的任务不受影响 - - aria2 网络错误（如连接被拒）保留当前状态，不误判为 error - - 预留空 GID 检查和类型断言安全保护 - -- **轮询优化（前端）** - - 移除 12 次硬限制（原 12×25s=5min），改为无限制轮询 - - 间隔从 25s 缩短到 5s - - 仅当存在活跃任务（等待/下载中）时保持轮询，全部结束后自动停止 - -- **清空按钮行为重写** - - 根据当前筛选标签删除任务（如"失败"标签只删失败任务） - - 不再全部页面一刀切删除 - - 未选中时显示"清空当前"，有选中项时显示"清除 (N)" - -- **Dashboard 挂载点卡片改进** - - 移除活跃挂载点下方的已用量显示（无实际意义） - - 实现点开展示所有挂载点列表 - - 展开挂载点时自动折叠存储用量展开，反之亦然（互斥展开） - -- **登录页键盘导航** - - 进入页面自动聚焦用户名输入框（`autofocus`） - - 用户名框按回车跳转到密码框 `passwordInput.value?.focus()` - - 密码框按回车触发登录 - - 用户名已填但密码为空时聚焦密码框而不是显示错误提示 - -- **MetricCard 组件优化** - - trend 字段为空时不渲染空白行（`v-if="item.trend"`） - -- **下载任务详情增强** - - 直链行新增"点击复制"按钮（Clipboard API） - - 直链横向滚动显示 - - 已完成界面显示完成时间（`FinishedAt`），其他标签显示创建时间 - -- **国际化补充** - - zh-CN：`finished_col`、"完成时间"、`clear_filtered`、"清空当前" - - en.json：`finished_col`、"Finished"、`clear_filtered`、"Clear Current" - -### 涉及文件 - -- `frontend/src/views/DownloadTasksView.vue`（状态映射、轮询、清空、详情面板） -- `frontend/src/views/DashboardView.vue`（挂载点展开、互斥逻辑） -- `frontend/src/views/LoginView.vue`（键盘导航、自动聚焦） -- `frontend/src/components/common/MetricCard.vue`（条件渲染 trend） -- `frontend/src/i18n/locales/zh-CN.json` -- `frontend/src/i18n/locales/en.json` -- `backend/internal/usecase/download_usecase.go`（状态机、FinishedAt、error 检测） - -### 当前状态 - -- 下载状态机逻辑完整：waiting → active → complete/error，aria2 离线可正确检测 -- 轮询 5s 间隔实时感知任务状态变化，无活跃任务时零开销 -- 清空按钮行为匹配用户当前筛选视图，不再误删 -- Dashboard 和登录页交互更流畅 - -### 后续待做 - -- 批量下载操作（全选后批量重试/删除） -- aria2 RPC 重连机制（aria2 重启后自动恢复任务状态同步） -- 错误详情弹窗（点击失败任务查看具体错误信息） - ---- - ---- - -## 2026-06-06 配额管理重构：多挂载点、虚拟配额、继承模式 - -### 本次完成内容 - -对配额管理页面进行了重构，从单挂载点模式扩展为多挂载点支持，新增虚拟配额和继承配额模式，同时完善了挂载点的增删改查和用户信息展示。 - -- **后端 Mount CRUD** - - Repository 层新增 `DeleteMountPoint` 和 `UpdateMountPoint` 方法 - - Usecase 层新增 `DeleteMount` 和 `UpdateMount` 方法 - - HTTP handler 新增 `DELETE /api/v1/mount/:id` 和 `PUT /api/v1/mount/:id` 端点 - - 后端暴露 `GET /api/v1/mount` 端点，返回所有挂载点列表（供继承模式选择父挂载点） - -- **前端 Store 重构** - - `mounts` 从单一对象改为 `mountMap`（providerId → mount[] 多对一映射） - - 新增 `fetchMounts` 方法，从后端 GET /api/v1/mount 加载挂载点 - - Store 统一管理 Provider → Mount 的关联关系 - -- **QuotaView 页面重写** - - 每个 Provider 下可管理多个挂载点 - - 挂载点卡片展示：名称、配额模式标签、配额数据、操作按钮 - - 支持创建 Mount → 选择配额模式（Real / Virtual / Inherit） - - Real 模式：从网盘/磁盘获取真实容量 - - Virtual 模式：手动输入总容量（MB） - - Inherit 模式：选择已有的 Real 挂载点作为父挂载点，镜像其配额 - - 支持编辑挂载点名称和虚拟配额数值 - - 支持删除挂载点（确认弹窗） - - 创建和同步配额时的加载状态和结果提示 - -- **用户信息展示** - - Settings 页新增用户信息卡片 - - 展示用户名、角色（Admin/User/Guest/Visitor）、SSO ID、OTP 状态、账户状态 - - 从 OpenList `/api/user/info` 接口获取 - -### 涉及文件 - -**后端新增：** -- `backend/internal/repository/mount_repo.go`（DeleteMountPoint, UpdateMountPoint） -- `backend/internal/usecase/mount_usecase.go`（DeleteMount, UpdateMount） - -**后端修改：** -- `backend/internal/handler/mount_handler.go`（DELETE/PUT 路由处理） -- `backend/internal/handler/download_handler.go`（OpenFileLocation 后续修复） -- `backend/main.go`（注册新路由） - -**前端修改：** -- `frontend/src/views/QuotaView.vue`（多挂载点、三种模式、编辑/删除） -- `frontend/src/stores/console.ts`（mounts → mountMap 重构、fetchMounts） -- `frontend/src/api/mount.ts`（新增 list/delete/update API） -- `frontend/src/api/settings.ts`（新增 getUserInfo） -- `frontend/src/types/mount.ts`（类型定义） -- `frontend/src/types/user.ts`（类型定义） -- `frontend/src/views/SettingsView.vue`（用户信息卡片） -- `frontend/src/i18n/locales/zh-CN.json` -- `frontend/src/i18n/locales/en.json` - -### 当前状态 - -- 配额管理支持 Real / Virtual / Inherit 三种模式 -- 每个 Provider 可管理多个挂载点 -- 挂载点支持在线编辑和删除 -- 用户信息已集成到设置页面 - -### 后续待做 - -- Inherit 模式链式继承校验（防止循环引用） -- 配额同步进度反馈优化 - ---- - -## 2026-06-06 管理员权限中间件 - -### 本次完成内容 - -为后端添加管理员权限中间件，前端配合实现基于角色的权限控制。 - -- **后端中间件** - - 新增 `internal/api/middleware/admin_checker.go`，通过 OpenList `/api/user/info` 验证当前用户角色 - - 定义 `AdminRole` 常量，要求用户 role 为 `"admin"` - - 非管理员返回 403 + 错误码 `ErrorCodeForbidden = 1008` - - 中间件挂载在需要管理员权限的路由上 - -- **前端权限控制** - - Pinia store 持久化用户角色（`userRole`） - - 新增 `isAdmin` getter - - 登录成功后将角色写入 store - - ProviderView：非管理员隐藏注册按钮 - - QuotaView：非管理员隐藏创建 Mount / 删除 / 同步按钮 - - ProviderFormDialog：非管理员隐藏编辑按钮 - -### 涉及文件 - -**后端新增：** -- `backend/internal/api/middleware/admin_checker.go` - -**后端修改：** -- `backend/main.go`（挂载中间件到路由） - -**前端修改：** -- `frontend/src/stores/console.ts`（userRole / isAdmin） -- `frontend/src/views/ProviderView.vue` -- `frontend/src/views/QuotaView.vue` -- `frontend/src/components/provider/ProviderFormDialog.vue` - -### 当前状态 - -- 管理员权限系统前后端已打通 -- 非管理员无法执行破坏性操作（注册/删除/编辑 Provider 和 Mount） - ---- - -## 2026-06-07 配额图表替换为环形图 - -### 本次完成内容 - -将配额管理页面的进度条替换为 SVG 环形图（donut chart），视觉表现更清晰。 - -- **DonutChart 组件** - - 纯 SVG 实现，无第三方依赖 - - 显示已用量百分比（居中文字） - - 支持多段着色环（已用/可用） - - 浅色/暗色主题自适应 - -- **QuotaView 集成** - - 挂载点卡片内的配额进度条改为 DonutChart - - 卡片下方仍保留文字数值（已用/总量） - -### 涉及文件 - -- `frontend/src/components/quota/DonutChart.vue`（新增） -- `frontend/src/views/QuotaView.vue` - ---- - -## 2026-06-07 下载任务重试与打开文件功能 - -### 本次完成内容 - -为下载任务列表增加重试（失败任务）和打开文件/定位文件夹（已完成任务）功能，同时修复了多项 UI 问题。 - -- **重试功能** - - 后端：`POST /download/tasks/:id/retry` 重新提交 aria2 下载 - - 修复原 RetryTask bug：AddURI 和 AddURIWithOptions 重复调用问题 - - 前端：失败状态的任务在日期右侧显示重试按钮 - - 重试按钮适配暗色主题 - - API 层新增 `retryTask()` 接口 - -- **打开文件 / 在文件夹中显示** - - 后端： - - 新增 `OpenFile`（调用系统默认应用打开文件） - - 新增 `OpenFileLocation`（在文件管理器中定位文件） - - 新增 `getActualFilePath` 辅助函数：优先从 aria2 tellStatus 获取 `files[0].path`，降级使用 `DownloadDir + FileName` 拼接 - - 修复 Windows 路径格式：使用 `filepath.FromSlash` 将 aria2 返回的正斜杠路径（`D:/Downloads/file.zip`）转换为 Windows 反斜杠格式（`D:\Downloads\file.zip`） - - 修复 explorer 命令：直接调用 `explorer /select,path`，不通过 `cmd /c` 中转 - - 前端：已完成任务的 action 列显示两个图标 - - 文档图标 → 打开文件 - - 文件夹图标 → 在文件夹中显示 - - 自定义 CSS tooltip（`data-tooltip` + `::after` 伪元素，悬停立即显示） - - API 层新增 `openFile()` 和 `openFileLocation()` 接口 - -- **同时修复的问题** - - 修复 v-for 作用域变量 `t` 遮蔽 i18n `t()` 方法的问题（改用 `$t()`） - - 修复自定义 tooltip 因 `overflow: hidden` 被裁剪的问题 - - 修复表格表头（居中）与数据列（左对齐）不一致的问题 - - 前端 fetchAllTasks 清理 store 中已失效的任务 ID，避免 `record not found` 400 错误 - -### 涉及文件 - -**后端：** -- `backend/internal/usecase/download_usecase.go`（RetryTask 修复、OpenFile、OpenFileLocation、getActualFilePath、filepath.FromSlash） -- `backend/internal/handler/download_handler.go`（新增路由处理） -- `backend/internal/pkg/myerror/error_code.go`（新增 ErrorCodeDownloadOpenFailed） -- `backend/main.go`（注册 /open 和 /open-location 路由） - -**前端：** -- `frontend/src/views/DownloadTasksView.vue`（重试按钮、打开文件图标、tooltip、对齐修复） -- `frontend/src/api/task.ts`（retryTask、openFile、openFileLocation） -- `frontend/src/i18n/locales/en.json`（retry/open 文案，logout → Re-login） -- `frontend/src/i18n/locales/zh-CN.json` - -### 当前状态 - -- 失败任务可一键重试 -- 已完成任务可直接打开文件或在文件夹中定位 -- 打开文件/定位文件夹均从 aria2 获取真实路径，路径格式已修复 Windows 兼容性 -- 自定义 tooltip 悬停即显，暗色主题适配 - ---- - -## 2026-06-07 暗色模式补充：Quota 页面硬编码颜色修复 - -### 本次完成内容 - -修复暗色模式下 Quota 页面的几处硬编码黑白颜色，包括 Select 组件、空状态提示等。 - -### 涉及文件 - -- `frontend/src/views/QuotaView.vue` - -### 当前状态 - -- 所有页面的暗色模式已无残留硬编码颜色 - ---- - -## 2026-06-07 开发日志（本文件） - -### 本次完成内容 - -- 补充本次会话开发日志到 `docs/frontend_dev.md` - -### 后续待做 - -- 继续下载任务详情面板的响应式布局优化 -- aria2 重连机制（aria2 重启后自动恢复状态同步） - -### 本次完成内容 - -对前端所有页面进行了暗色模式（dark mode）适配，将 scoped CSS 中的硬编码颜色替换为 CSS 变量，确保通过 `[data-theme="dark"]` 切换时所有页面自动响应。 - -- **CSS 变量体系** - - 全局 `index.css` 新增 `[data-theme="dark"]` 块，覆盖 `--surface`/`--text`/`--muted`/`--border`/`--accent`/`--gold`/`--shadow` 等核心变量 - - 暗色主题使用深蓝底色（`#0d1b2a`→`#152238` 渐变）、浅色文字（`#e2e8f0`）、半透明表面（`rgba(26,42,66,0.9)`） - - 侧边栏、进度条、登录表单输入框均添加暗色覆盖 - -- **主题切换机制** - - AppTopbar 新增太阳/月亮 SVG 图标切换按钮 - - 通过 `document.documentElement.dataset.theme` 切换 - - 偏好持久化到 `localStorage`（key: `openbridge_theme`） - -- **页面逐一修复**（以下文件的所有 `background: white`/`color: #111827`/`border: #e5e7eb` 等替换为 `var(--)`） - - | 页面 | 主要改动 | - |------|---------| - | `AppTopbar.vue` | 顶栏背景/边框、语言切换按钮、主题切换按钮、状态指示器 | - | `DashboardView.vue` | 指标卡片、操作卡片、展开面板、按钮、存储用量区域 | - | `OpenListView.vue` | 面包屑、文件表格头部/行、排序箭头、加载/空状态提示 | - | `ProviderView.vue` | Provider 卡片、编辑/删除按钮悬停态、空状态、Toast | - | `ProviderFormDialog.vue` | 弹窗背景/边框、标签、输入框、提示区、按钮 | - | `DownloadTasksView.vue` | 标签页、表格/行/头部、详情面板、直链、按钮、空状态 | - | `QuotaView.vue` | 控制栏、配额卡片、模式选择、虚拟输入、空状态、离线横幅 | - | `SettingsView.vue` | 设置卡片、标签文字、输入框 | - | `DebugView.vue` | Ping 结果、Provider 行、API 信息、危险面板 | - -- **语义颜色保留** - - 蓝色主按钮（`#3b82f6`）、红色危险操作（`#dc2626`）、状态徽章（绿/蓝/黄/红）保持原色 - - 语义颜色在两种主题下均有意义，不替换 - -- **后端离线检测完善**（跨页面） - - Dashboard/Quota 页新增 `checkBackend()` 健康检查 - - 通过 `GET /api/v1/provider/list` 确认后端连通性 - - 离线时禁用操作按钮、标记卡片为陈旧状态、配额同步显示 error - - 挂载点展开仅在在线状态可点击 - -- **aria2 跨机检测修复** - - 前端不再直接 fetch aria2 RPC（存在 CORS/地址配置问题） - - 后端新增 `GET /api/v1/download/aria2-status`，调用 `aria2.getVersion` - - 前端改为请求该后端代理端点 - -- **其他修复** - - Portal 页 `isConnected` 从硬编码 true 改为真实健康检查 - - 路由守卫改用 `localStorage` 直接读取（解决 Pinia 时序问题） - - 右上角"退出登录"改为"重新登录" - - Settings 底部增加版本信息 `OpenBridge v0.1.0` - -### 涉及文件 - -- `frontend/src/styles/index.css` -- `frontend/src/components/layout/AppTopbar.vue` -- `frontend/src/views/DashboardView.vue` -- `frontend/src/views/OpenListView.vue` -- `frontend/src/views/ProviderView.vue` -- `frontend/src/components/provider/ProviderFormDialog.vue` -- `frontend/src/views/DownloadTasksView.vue` -- `frontend/src/views/QuotaView.vue` -- `frontend/src/views/SettingsView.vue` -- `frontend/src/views/DebugView.vue` -- `frontend/src/views/PortalView.vue` -- `frontend/src/router/index.ts` -- `backend/internal/tool/aria2_client.go` -- `backend/internal/usecase/download_usecase.go` -- `backend/internal/handler/download_handler.go` -- `backend/main.go` -- `docs/frontend_dev.md` - -### 当前状态 - -- 所有页面均支持暗色模式，通过顶栏月亮/太阳图标一键切换 -- 主题偏好自动保存，刷新/重启后保持 -- 后端离线检测覆盖 Dashboard/Quota，aria2 状态跨机可用 -- 语义颜色（按钮、徽章）保持不变，不影响功能理解 -- 设置页面底部新增版本信息 - -### 后续待做 - -- 继续跟踪新增页面/组件的暗色模式兼容 -- aria2 重连机制（aria2 重启后自动恢复状态同步） -- 考虑是否支持"跟随系统主题"选项（`prefers-color-scheme`） -- 检查第三方组件（如弹窗、通知）的暗色适配 \ No newline at end of file diff --git a/docs/homework2.md b/docs/homework2.md deleted file mode 100644 index fce4a9e..0000000 --- a/docs/homework2.md +++ /dev/null @@ -1,57 +0,0 @@ -# 软件需求与设计文档分工说明 - -## 一、文档概述与整合（1） -- **负责人**：周子滨 -- **内容**： - - 文档整体结构整理与统一 - - 各部分内容整合与校对 - - 所有图表（PlantUML代码）统一编译与输出 - ---- - -## 二、软件系统的一般性描述（2） -- **负责人**：崔乘玮 - ---- - -## 三、功能优先级与迭代（3.1 & 3.2） -- **负责人**：崔乘玮、后端团队 - ---- - -## 四、用例分析（3.3.1） -### 1. 下载文件、获取容量 -- **负责人**：郑源羽、卢宇扬、崔乘玮 - -### 2. 登录 / 配置 -- **负责人**：宋丞罡、陈志睿 - ---- - -## 五、顺序图（3.3.2） -### 1. 下载文件、获取容量 -- **负责人**：崔乘玮 - -### 2. 登录 / 配置 -- **负责人**：宋丞罡、陈志睿 - ---- - -## 六、软件需求的分析类模型及描述（3.3.3） -### 1. 下载子系统、容量子系统 -- **负责人**：崔乘玮、郑源羽、卢宇扬 - -### 2. 系统管理类图 -- **负责人**：陈志睿 - ---- - -## 七、软件的非功能性需求（3.4） -- **负责人**：崔乘玮 - ---- - -## 八、图表规范说明 -- 所有图表统一使用 **PlantUML** 编写 -- 图表源码由各模块负责人提供 -- 最终由 **周子滨** 统一编译、整理并嵌入文档 diff --git a/docs/openbridge_presentation.md b/docs/openbridge_presentation.md deleted file mode 100644 index ac5dedd..0000000 --- a/docs/openbridge_presentation.md +++ /dev/null @@ -1,102 +0,0 @@ -# OpenBridge：面向 OpenList 的下载与挂载控制台 - -## 为什么做这个产品 - -- OpenList 能统一管理网盘文件，但“真正用起来”的最后一公里仍然分散：下载、挂载、容量展示、跨设备直链都要分别折腾。 -- 手机端直链经常拿到 `127.0.0.1` 或 OpenList 代理地址，离开服务端电脑就不可用。 -- rclone 命令配置复杂，多个 Mount 聚合、停挂、清理旧配置对普通用户不友好。 -- Provider 容量、Mount 虚拟配额、aria2 下载任务、主机资源缺少一个统一控制台。 - -## 我们的目标 - -把 OpenList 从“文件入口”补成“可演示、可管理、可多设备使用”的本地网盘工作台。 - -![仪表盘总览](docs/screenshots/user_manual/09-dashboard-overview.png) - -# 功能概览：按角色看系统能做什么 - -## 普通用户 - -- 登录后进入仪表盘，查看服务状态、主机资源、存储总量和带宽。 -- 浏览当前 OpenList 用户根目录，支持排序、面包屑跳转、大目录完整加载。 -- 单文件下载：当前设备下载、复制直链、二维码转移、提交到服务端 aria2。 -- 文件夹下载：ZIP 打包下载，或对百度文件夹批量解析直链清单。 -- 查看下载任务：筛选、排序、查看详情、复制直链、重试失败任务。 - -## 管理员 - -- 注册/编辑/删除 Provider：通用、百度、夸克、本地存储。 -- 创建/编辑/删除 Mount，支持真实配额和虚拟配额。 -- 配置 rclone：普通、union、combine，写入配置、挂载、停止挂载、删除配置。 -- 配置 OpenList、aria2、rclone、本地路径选择、FILETREE 缓存、重启/退出服务。 - -![OpenList 文件浏览](docs/screenshots/user_manual/15-openlist-browser.png) - -# 技术栈与系统架构 - -## 前端 - -- Vue 3 + TypeScript + Vite：组件化页面、类型约束、生产构建快。 -- Pinia：集中管理登录态、Provider、Mount、任务 ID、用户角色和本地偏好。 -- Vue Router：管理员与普通用户页面权限隔离。 -- Axios：统一携带设备 ID，下载/大目录场景支持无限超时。 - -## 后端 - -- Go + Gin：轻量 HTTP API、静态前端内嵌、WebDAV 代理。 -- GORM + SQLite：本地化部署，保存 Provider、Mount、任务、rclone 配置。 -- OpenList API/WebDAV：复用 OpenList 文件能力和用户权限。 -- aria2 JSON-RPC：服务端电脑执行下载。 -- rclone CLI：自动写配置、挂载、停挂、清理。 - -## 架构流向 - -`浏览器/手机` → `OpenBridge 前端` → `Go API` → `OpenList / aria2 / rclone / 本地系统` - -![下载确认弹窗](docs/screenshots/user_manual/19-download-dialog.png) - -# 亮点与技术难点 - -## 亮点 - -- 多设备会话：设备 ID 绑定登录态，普通账号默认最多 5 台设备在线。 -- 用户根目录隔离：不同 OpenList 用户看到的 `/` 对应各自可见根目录。 -- 终端直下：百度等非 OpenList 代理直链可复制、二维码转移、当前设备直下。 -- WebDAV Mount：文件能力复用 OpenList，容量展示改写为 Mount 层配额。 -- rclone 管理闭环：从配置、写入、挂载到停挂/删除，全流程前端化。 - -## 难点 - -- 大文件夹扫描与下载不能被 30 秒超时打断，需要前后端下载链路无限超时。 -- FILETREE 缓存要加速文件树，但不能阻塞正常文件浏览。 -- OpenList 换源后 Provider、Mount、rclone 配置必须按端口/源隔离。 -- Windows 下打开文件夹、中文文件名、特殊符号路径要避免 shell 转义坑。 -- WebDAV `PROPFIND` 响应要改写 `href`、`quota-used-bytes`、`quota-available-bytes`。 - -![Rclone 配置](docs/screenshots/user_manual/54-rclone-card.png) - -# 软件规模与 10 分钟展示建议 - -## 软件规模 - -- 功能用例总数：42 个，按用户故事合并统计。 -- 代码源文件总数：117 个，统计后端 Go + 前端 Vue/TS/CSS/HTML/JSON。 -- 代码总行数：21459 行，排除 `node_modules`、`dist`、截图和文档。 -- 后端 API/路由：49 个。 -- 前端路由：11 个。 - -## 规模背后的模块 - -- 前端页面：仪表盘、OpenList、服务商、下载任务、配额、Rclone、设置、Debug。 -- 后端用例层：用户、Provider、Mount、Storage、Download、Rclone、Settings、System。 -- 外部集成：OpenList、aria2、rclone、WebDAV、本地文件选择和主机指标。 - -## 推荐节奏 - -- 0:00-1:30：为什么做，讲 OpenList 的“最后一公里”痛点。 -- 1:30-3:20：功能概览，按普通用户和管理员两条线讲。 -- 3:20-5:20：技术栈与难点，突出 Go + Vue + OpenList/aria2/rclone/WebDAV 集成。 -- 5:20-9:20：演示 4 个闭环：文件浏览 → 下载弹窗 → 配额/Mount → rclone 配置。 -- 9:20-10:00：总结亮点：多设备、直链、Mount 配额、rclone 闭环、大目录无限超时。 - -![下载任务](docs/screenshots/user_manual/26-tasks-overview.png) diff --git a/docs/openlist_api.md b/docs/openlist_api.md deleted file mode 100644 index 3302ea2..0000000 --- a/docs/openlist_api.md +++ /dev/null @@ -1,180 +0,0 @@ - - -下面是 OpenList API 文档中各接口分类及其作用的详细说明： - ---- - -### **Authentication（认证）** - -- **User login** `POST` — 用户通过用户名和密码进行标准登录，获取 JWT 令牌。 -- **User login with pre-hashed password** `POST` — 使用预哈希密码登录，适用于密码已在客户端完成哈希处理的场景，避免明文传输密码。 -- **LDAP login** `POST` — 通过 LDAP（轻量级目录访问协议）服务器进行身份验证登录，适用于企业内部统一认证体系。 -- **User logout** `GET` — 用户登出，使当前会话或令牌失效。 -- **Generate 2FA secret** `POST` — 为当前用户生成双因素认证（2FA）的密钥（通常是一个 TOTP 密钥和二维码），用于绑定验证器应用。 -- **Verify and enable 2FA** `POST` — 验证用户输入的 2FA 验证码是否正确，验证通过后正式启用双因素认证。 -- **SSO login redirect** `GET` — 将用户重定向到 SSO（单点登录）提供商的认证页面，发起 SSO 登录流程。 -- **SSO callback handler** `GET` — 处理 SSO 提供商认证完成后的回调，接收授权码或令牌，完成 SSO 登录。 -- **Begin WebAuthn login** `GET` — 发起 WebAuthn（无密码认证）登录流程，返回认证挑战（challenge），供浏览器调用身份验证器。 -- **Finish WebAuthn login** `POST` — 完成WebAuthn 登录，提交身份验证器的签名响应，服务端验证后签发令牌。 -- **Begin WebAuthn registration** `GET` — 发起 WebAuthn 凭据注册流程，返回注册挑战，供用户绑定新的安全密钥或设备。 -- **Finish WebAuthn registration** `POST` — 完成 WebAuthn 凭据注册，提交身份验证器的注册数据，服务端保存凭据。 -- **Delete WebAuthn credential** `POST` — 删除指定的 WebAuthn 凭据，解绑某个安全密钥或设备。 -- **Get WebAuthn credentials** `GET` — 获取当前用户已注册的所有 WebAuthn 凭据列表。 - ---- - -### **User（用户自身操作）** - -- **Get current user info** — 获取当前登录用户的个人信息（用户名、权限、偏好等）。 -- **Update current user** — 更新当前用户的个人资料，如昵称、密码、偏好设置等。 -- **List my SSH public keys** — 列出当前用户已添加的所有 SSH 公钥。 -- **Add SSH public key** — 为当前用户添加一个新的 SSH 公钥，可用于 SSH 方式访问存储后端。 -- **Delete SSH public key** — 删除当前用户的某个 SSH 公钥。 - ---- - -### **Admin — 用户管理** - -- **List all users (Admin)** `GET` — 管理员获取系统中所有用户的列表（支持分页）。 -- **Get user by ID (Admin)** `GET` — 管理员根据用户 ID 获取单个用户的详细信息。 -- **Create new user (Admin)** `POST` — 管理员创建新用户账号，指定用户名、密码、权限等。 -- **Update user (Admin)** `POST` — 管理员更新指定用户的信息，如修改权限、禁用账号等。 -- **Delete user (Admin)** `POST` — 管理员删除指定用户账号。 -- **Cancel user 2FA (Admin)** `POST` — 管理员取消/重置指定用户的双因素认证（在用户丢失验证器时使用）。 -- **Clear user cache (Admin)** `POST` — 管理员清除指定用户的缓存数据，强制刷新。 -- **List user SSH keys (Admin)** `GET` — 管理员列出指定用户的所有 SSH 公钥。 -- **Delete user SSH key (Admin)** `POST` — 管理员删除指定用户的某个 SSH 公钥。 - ---- - -### **Admin — 存储管理** - -- **List all storages (Admin)** `GET` — 管理员获取所有已挂载存储的列表。 -- **Get storage by ID (Admin)** `GET` — 管理员根据存储 ID 获取单个存储的详细配置信息。 -- **Create storage (Admin)** `POST` — 管理员创建新的存储挂载，将外部存储（如本地磁盘、对象存储、网盘等）接入系统。 -- **Update storage (Admin)** `POST` — 管理员更新指定存储的配置，如修改挂载路径、驱动参数等。 -- **Delete storage (Admin)** `POST` — 管理员删除指定的存储挂载。 -- **Enable storage (Admin)** `POST` — 管理员启用指定的存储挂载，使其可用。 -- **Disable storage (Admin)** `POST` — 管理员禁用指定的存储挂载，暂停其使用但不删除配置。 -- **Reload all storages (Admin)** `POST` — 管理员重新加载所有存储配置，使配置变更生效。 - ---- - -### **Admin — 驱动管理** - -- **List all drivers (Admin)** `GET` — 获取所有可用的存储驱动及其配置模板（当前页面展示的接口）。 -- **Get driver names (Admin)** `GET` — 仅获取所有驱动的名称列表，比完整列表更轻量。 -- **Get driver info (Admin)** `GET` — 获取指定驱动的详细信息，包括其支持的配置项和参数说明。 - ---- - -### **Admin — 系统设置** - -- **List all settings (Admin)** `GET` — 管理员获取系统所有配置项的列表。 -- **Get setting by key (Admin)** `GET` — 管理员根据配置键名获取单个配置项的值。 -- **Save settings (Admin)** `POST` — 管理员保存/更新系统配置项。 -- **Delete setting (Admin)** `POST` — 管理员删除指定的配置项（恢复为默认值）。 -- **Reset API token (Admin)** `POST` — 管理员重置系统的 API 令牌，旧令牌即刻失效。 - ---- - -### **Admin — 元数据管理** - -- **List all metas (Admin)** `GET` — 管理员获取所有元数据配置的列表（元数据用于为特定目录/文件自定义显示或行为）。 -- **Get meta by ID (Admin)** `GET` — 管理员根据 ID 获取单个元数据配置的详情。 -- **Create meta (Admin)** `POST` — 管理员创建新的元数据配置，如为某个路径设置密码、说明、排序规则等。 -- **Update meta (Admin)** `POST` — 管理员更新指定的元数据配置。 -- **Delete meta (Admin)** `POST` — 管理员删除指定的元数据配置。 - ---- - -### **Admin — 搜索索引管理** - -- **Build search index (Admin)** `POST` — 管理员触发全量搜索索引构建，从头扫描所有文件建立索引。 -- **Update search index (Admin)** `POST` — 管理员触发增量搜索索引更新，只处理变更部分。 -- **Stop indexing (Admin)** `POST` — 管理员停止正在进行的索引构建/更新任务。 -- **Clear search index (Admin)** `POST` — 管理员清除所有搜索索引数据。 -- **Get indexing progress (Admin)** `GET` — 管理员获取当前索引任务的进度信息。 - ---- - -### **File System（文件系统操作）** - -- **List directory contents** — 列出指定目录下的文件和子目录。 -- **Get file or directory info** — 获取指定文件或目录的详细信息（大小、修改时间等）。 -- **Search files and directories** — 按关键词搜索文件和目录。 -- **Get directory tree** — 获取目录的树形结构，以层级方式展示文件组织。 -- **Get additional file operations** — 获取文件支持的其他操作（如直链、预览等）。 -- **Create directory** — 创建新目录。 -- **Rename file or directory** — 重命名指定的文件或目录。 -- **Batch rename files** — 批量重命名多个文件。 -- **Regex-based rename** — 使用正则表达式匹配并重命名文件。 -- **Move files or directories** — 移动文件或目录到目标路径。 -- **Recursive move** — 递归移动，将目录及其所有内容一起移动。 -- **Copy files or directories** — 复制文件或目录到目标路径。 -- **Remove files or directories** — 删除指定的文件或目录。 -- **Remove empty directories** — 删除空目录（不删除含文件的目录）。 -- **Upload file (stream)** — 以流式方式上传文件，适合大文件传输。 -- **Upload file (form)** — 以表单方式上传文件，适合小文件或浏览器端上传。 -- **Add offline download task** — 添加离线下载任务，由服务器端下载指定 URL 的文件到存储中。 -- **Decompress archive** — 解压缩归档文件（如 zip、tar.gz 等）。 -- **Get archive metadata** — 获取归档文件的元数据信息，不解压。 -- **List archive contents** — 列出归档文件内的文件列表，不解压。 - ---- - -### **Public（公开接口）** - -- **Get public settings** — 获取公开的系统设置信息（无需认证），如站点名称、公告等。 -- **Get available offline download tools** — 获取系统可用的离线下载工具列表（如 aria2 等）。 -- **Get supported archive extensions** — 获取系统支持的归档文件扩展名列表。 - ---- - -### **Sharing（分享管理）** - -- **List all shares** — 列出所有文件分享记录。 -- **Get share by ID** — 根据分享 ID 获取单个分享的详细信息。 -- **Create file share** — 创建新的文件/目录分享链接。 -- **Update share** — 更新分享的配置（如修改密码、过期时间等）。 -- **Delete share** — 删除指定的分享。 -- **Enable share** — 启用指定的分享，使其可被访问。 -- **Disable share** — 禁用指定的分享，暂停访问但不删除记录。 - ---- - -### **TS 版本接口** - -- **文件操作接口** — TypeScript 版本的文件操作接口封装。 -- **用户操作接口** — TypeScript 版本的用户操作接口封装。 -- **挂载管理接口** — TypeScript 版本的存储挂载管理接口封装。 - ---- - -### **密钥站接口** - -文档中未展开详细说明，推测为与密钥/许可证管理相关的专用接口。 - ---- - -### **Schemas（数据模型）** - -这些不是接口，而是 API 请求/响应中使用的数据结构定义： - -- **ApiResponse** — 通用 API 响应结构（包含 code、message、data）。 -- **ErrorResponse** — 错误响应结构。 -- **PageReq** — 分页请求参数（页码、每页数量）。 -- **Pagination** — 分页元数据（总条数、总页数等）。 -- **User** — 用户数据模型。 -- **LoginRequest / LoginResponse** — 登录请求/响应模型。 -- **UserResponse / UsersListResponse** — 用户信息/用户列表响应模型。 -- **FsObject** — 文件系统对象模型（文件或目录的属性）。 -- **FsListRequest / FsListResponse** — 目录列表请求/响应模型。 -- **FsGetRequest / FsGetResponse** — 文件信息获取请求/响应模型。 -- **FsMkdirRequest** — 创建目录请求模型。 -- **FsRenameRequest** — 重命名请求模型。 -- **FsMoveCopyRequest** — 移动/复制请求模型。 -- **FsRemoveRequest** — 删除请求模型。 -- **StorageDetails / Storage** — 存储配置详情/摘要模型。 -- **DriverInfo** — 驱动信息模型（包含驱动名称和配置模板）。 -- **StorageResponse / StoragesListResponse** — 存储信息/存储列表响应模型。 \ No newline at end of file diff --git a/docs/project_plan_sections.txt b/docs/project_plan_sections.txt deleted file mode 100644 index aa02393..0000000 --- a/docs/project_plan_sections.txt +++ /dev/null @@ -1,770 +0,0 @@ -二、项目计划 - -本项目围绕 OpenBridge 控制台展开，目标是在 OpenList 已具备文件访问能力的基础上，补齐服务商管理、Mount 配额管理、下载任务编排、rclone 本地挂载、WebDAV Mount 代理、系统设置、资源监控、用户手册和发布交付等能力。项目采用前后端分离加本地化部署的方式推进，前端负责交互界面、状态展示和用户操作入口，后端负责 OpenList 对接、Provider 与 Mount 数据管理、aria2 与 rclone 工具调度、设置持久化、数据备份还原和接口服务。 - -项目整体按 11 周推进。前期重点完成需求确认、技术栈选择、工程骨架、后端配置系统、数据库模型、前端基础布局和登录会话机制。中期围绕核心业务功能展开，依次完成 Provider 与 Mount 管理、OpenList 文件浏览、文件操作、直链解析、文件夹下载、aria2 下载任务和 rclone 挂载配置。后期重点进行系统设置、主机资源监控、前端体验优化、权限隔离、OpenList 源隔离、文档完善、打包发布和最终验收，确保系统具备完整可演示、可部署、可维护的闭环能力。 - -项目计划采用“功能模块逐步闭环”的方式推进。每一周均设置本周定位、本周目标、任务拆分、验收标准和交付物。每个阶段完成后，先由对应模块负责人完成自测，再由项目经理进行集成测试和问题反馈，最后统一合入主线。对于登录、数据隔离、文件操作、下载任务、rclone 挂载、备份还原等关键功能，采用多轮回归测试方式，保证前后端行为一致、页面显示正确、接口返回稳定。 - -总体里程碑如下： - -第 1 周：完成需求确认、产品边界划分和前后端工程骨架。 -第 2 周：完成后端基础设施、配置系统、数据库和统一响应规范。 -第 3 周：完成 OpenList 登录、设备会话、权限控制和登录失效检测。 -第 4 周：完成 Provider、Mount 和配额管理闭环。 -第 5 周：完成 OpenList 文件浏览、用户根目录映射和基础文件管理能力。 -第 6 周：完成直链解析、当前设备下载、百度终端直下和文件夹 ZIP 下载。 -第 7 周：完成 aria2 下载任务、进度刷新、停止、重试、打开文件和删除文件。 -第 8 周：完成 WebDAV Mount 代理和 rclone 配置、挂载、停止挂载能力。 -第 9 周：完成设置中心、主机资源监控、路径选择器、自动启动和界面优化。 -第 10 周：完成跨模块集成补齐、OpenList 源隔离、用户手册和演示材料。 -第 11 周：完成最终回归测试、打包发布、版本标签、Release 和完整交付闭环。 - - -三、团队成员分工说明 - -角色 人员姓名 -1、项目经理 崔乘玮 -2、后端 郑源羽 -3、后端 卢宇扬 -4、前端 宋丞罡 -5、前端 陈志睿 -6、文档 周子滨 - -分工说明： - -崔乘玮主要负责项目整体规划、需求拆分、进度安排、模块协调和阶段验收，同时参与 Provider、Mount、配置、文档和测试相关工作。项目经理需要在每周根据当前进度安排任务，推动成员完成对应模块，并在功能合并后进行测试和问题反馈，保证不同模块之间的数据结构、接口风格和交互逻辑保持一致。 - -郑源羽主要负责后端功能开发，重点参与 OpenList 对接、下载任务、直链解析、aria2 调度、文件夹下载、后端接口和相关业务逻辑实现。后端工作需要保证接口稳定、错误返回明确，并处理大目录解析、文件下载超时、任务状态同步等实际使用问题。 - -卢宇扬主要负责后端和 API 文档相关工作，参与用户登录、设备会话、权限控制、设置接口、系统接口、调试接口和 API 文档整理。该部分工作需要确保后端接口与前端调用保持一致，并在文档中说明接口用途、请求参数、返回字段和权限要求。 - -宋丞罡主要负责前端主界面和 OpenList 相关页面开发，包括入口页、登录页、侧边栏、顶部栏、OpenList 文件浏览、文件选择器和部分页面交互。前端工作需要保证页面结构清晰、操作入口明确，并兼顾桌面端和移动端显示效果。 - -陈志睿主要负责仪表盘、资源监控、前端视觉优化和部分设置页面开发，包括系统资源占用、存储用量、带宽指标、主题适配、动画效果和响应式布局。该部分工作需要提升整体界面观感，并保证黑夜模式、亮色模式和不同屏幕尺寸下的可读性。 - -周子滨主要负责文档、Debug 页面、截图整理和最终材料补充，包括用户手册、API 文档、任务周报、演示材料、截图收集和部分调试功能说明。文档工作需要覆盖产品功能、页面按钮、使用步骤、接口说明和常见问题，为最终展示和验收提供支撑。 - - -四、进度跟踪记录 - -Week 1 任务说明：需求确认、产品边界与项目骨架 - -本周定位： -本周完成 OpenBridge 的产品定义和工程起步，明确系统要解决的问题：在 OpenList 已经具备文件访问能力的基础上，补齐服务商管理、Mount 配额、下载编排、rclone 挂载和可视化控制台。 - -本周目标： -- 明确管理员和普通用户的使用场景。 -- 确定前后端技术栈和本地化部署方式。 -- 建立 Monorepo 工程结构。 -- 搭建前端基础页面和后端基础服务。 -- 输出第一版需求说明、架构说明和接口草案。 - -任务拆分： -产品与文档： -- 梳理核心角色：管理员、普通用户、运行 OpenBridge 的服务端电脑、其他下载终端。 -- 梳理核心功能：仪表盘、OpenList 文件浏览、服务商管理、配额管理、下载任务、rclone、设置、调试页。 -- 明确普通用户只可见仪表盘、OpenList、服务商和下载任务。 -- 明确管理员可见全部页面和管理操作。 -- 编写初版产品说明和页面导航说明。 - -后端： -- 初始化 Go 后端工程。 -- 引入 Gin 作为 HTTP 框架。 -- 规划 config、handler、usecase、repository、domain、tool 分层。 -- 提供基础启动入口和健康检查能力。 -- 预留 /api/v1 API 前缀。 - -前端： -- 初始化 Vue 3、Vite、TypeScript 工程。 -- 引入 Pinia、Vue Router、i18n 基础能力。 -- 搭建入口页、登录页和控制台布局。 -- 设计侧边栏、顶部栏、页面头部等公共组件。 -- 建立基础样式变量，预留亮色与黑夜模式。 - -验收标准： -- 本地可以启动前端开发服务。 -- 本地可以启动后端服务。 -- 浏览器能访问入口页和登录页。 -- 项目目录结构清晰，前后端职责边界明确。 -- 需求文档能说明“为什么做 OpenBridge”和“要完成哪些页面”。 - -交付物： -- Monorepo 基础工程。 -- 初版产品说明。 -- 初版架构说明。 -- 初版页面导航设计。 - - -Week 2 任务说明：后端基础设施、配置系统与数据模型 - -本周定位： -本周完成后端基础设施，让后续 Provider、Mount、下载任务、设置和用户会话都能在统一的配置、错误、日志和数据库体系上开发。 - -本周目标： -- 建立统一 API 响应结构。 -- 建立错误码和错误返回规范。 -- 建立 .env 配置读取与默认配置生成机制。 -- 建立 SQLite 与 GORM 数据访问基础。 -- 建立基础数据模型和自动迁移。 -- 支持前端静态资源嵌入后端。 - -任务拆分： -后端基础设施： -- 定义统一返回结构：code、message、data。 -- 定义成功码和常见错误码。 -- 封装配置读取逻辑，支持 APP_NAME、APP_ENV、APP_PORT、APP_VERSION。 -- 支持程序首次启动时自动生成 .env。 -- 支持 APP_AUTO_OPEN_BROWSER，为后续启动自动打开浏览器做准备。 -- 建立日志输出规则，保留请求、错误和关键业务日志。 - -数据层： -- 引入 SQLite 作为本地数据库。 -- 使用 GORM 管理数据模型。 -- 定义 Provider、Mount、QuotaSnapshot、DownloadTask、RcloneProfile、会话等核心实体的基础字段。 -- 实现数据库初始化和自动迁移。 -- 保证数据库路径可通过 .env 配置。 - -前端基础： -- 封装统一请求工具。 -- 设置 API Base URL。 -- 处理统一响应格式。 -- 建立基础 Store，用于保存登录态、角色、设备 ID 和常用缓存。 - -验收标准： -- 后端启动时能读取或生成 .env。 -- /api/v1 下接口统一返回 JSON。 -- SQLite 数据库能正常创建和迁移。 -- 前端请求封装能处理成功和失败响应。 -- 后端静态资源嵌入方案可用。 - -交付物： -- 后端配置系统。 -- 统一响应和错误体系。 -- 数据库初始化和基础实体。 -- 前端请求封装。 - - -Week 3 任务说明：OpenList 登录、设备会话与权限控制 - -本周定位： -本周打通 OpenBridge 与 OpenList 的登录关系，解决“前端假登录”“后端重启不失效”“换源不重登”等问题，为后续按用户根目录、按 OpenList 源隔离数据打基础。 - -本周目标： -- 通过 OpenList 账号登录 OpenBridge。 -- 保存设备级会话，而不是只依赖前端本地状态。 -- 支持后端重启、OpenList 重启、OpenList 换源后的重新登录检测。 -- 支持普通用户和管理员权限区分。 -- 支持账号最多在线设备数量限制，默认 5 台。 -- 支持本地登录超时时间由前端本地设置。 - -任务拆分： -后端： -- 实现 POST /api/v1/user/login。 -- 登录时转发 OpenList 认证并获取 OpenList 用户信息。 -- 保存当前设备会话、OpenList Base URL、用户信息和后端实例指纹。 -- 实现 GET /api/v1/user/info。 -- 实现 GET /api/v1/user/session-status。 -- 会话校验时检查后端实例、OpenList 源、OpenList 用户和设备 ID。 -- 管理同一账号的设备数量，普通账号默认最多 5 台，管理员可配置。 -- 实现管理员权限中间件。 - -前端： -- 登录页对接真实登录接口。 -- 生成并持久化 X-OpenBridge-Device-ID。 -- 全局请求自动携带设备 ID。 -- 路由守卫在进入控制台页面前校验会话。 -- 普通用户隐藏配额、Rclone、设置、Debug 页面。 -- Debug 页不出现在侧边栏，只允许直接访问 /debug。 -- 设置页加入本地登录超时时间。 - -数据与安全： -- 避免只靠 localStorage 判断登录。 -- 设备会话与 OpenList 源绑定。 -- 切换 OpenList Base URL 后要求重新登录。 -- 后端重启后前端能够检测并回到登录页。 - -验收标准： -- 登录成功后可进入控制台。 -- 删除或重启后端后，前端会检测到会话失效。 -- 切换 OpenList Base URL 后需要重新登录。 -- 普通用户看不到管理员页面。 -- 超过设备限制时禁止继续登录。 - -交付物： -- 用户登录 API。 -- 设备会话机制。 -- 权限中间件。 -- 前端登录和路由守卫。 - - -Week 4 任务说明：Provider、Mount 与配额管理闭环 - -本周定位： -本周完成服务商和 Mount 的核心模型，把 OpenBridge 从“能登录的控制台”推进到“能管理存储来源和配额”的系统。 - -本周目标： -- 建立 Provider 抽象和服务商注册能力。 -- 支持通用、百度、本地、夸克等 Provider 类型的统一管理。 -- 建立 Mount 模型，绑定 Provider 与 OpenList 路径。 -- 支持真实配额和虚拟配额。 -- 前端完成服务商管理和配额管理页面。 -- 服务商、Mount、配额按 OpenList Base URL 隔离。 - -任务拆分： -后端： -- 定义 ProviderAccount 实体。 -- 实现 Provider Repository 和 UseCase。 -- 实现 Provider 注册、列表、详情、编辑、删除接口。 -- 定义 MountPoint 实体。 -- 实现 Mount 创建、列表、编辑、删除接口。 -- 定义配额模式：real 和 virtual。 -- 实现 Mount 配额查询和同步。 -- 记录 QuotaSnapshot。 -- 对 Provider、Mount、QuotaSnapshot 加入 OpenList 源隔离字段。 - -Provider 能力： -- 通用 Provider：适配 OpenList 已有挂载路径。 -- 百度 Provider：保存 access token，为后续直链解析准备。 -- 本地 Provider：读取本机路径容量。 -- 夸克 Provider：保存 Cookie 和账号标识，为后续容量同步准备。 - -前端： -- 服务商管理页展示服务商卡片。 -- 支持新增、编辑、删除服务商。 -- 服务商表单支持不同 Provider 类型的字段切换。 -- 配额管理页支持选择 Provider。 -- 展示 Provider 总使用量和总容量。 -- 支持创建、编辑和删除 Mount。 -- 支持真实容量和虚拟容量显示。 -- 修复下拉菜单遮挡问题。 - -验收标准： -- 管理员可以新增、编辑、删除服务商。 -- 管理员可以为服务商创建 Mount。 -- Mount 能正确显示真实或虚拟配额。 -- 普通用户只能查看服务商和基础信息，不能执行管理操作。 -- 更换 OpenList 端口后不会看到旧源的 Provider 和 Mount。 - -交付物： -- Provider API。 -- Mount API。 -- 配额同步 API。 -- 服务商管理页面。 -- 配额管理页面。 - - -Week 5 任务说明：OpenList 文件浏览、用户根目录与文件管理 - -本周定位： -本周把 OpenList 文件能力接入 OpenBridge，让用户能在控制台中浏览自己可见的 OpenList 根目录，并补齐基础文件管理能力。 - -本周目标： -- 支持按当前 OpenList 用户根目录浏览文件。 -- 支持 OpenList 文件列表分页加载，避免只显示前 50 个文件。 -- 支持文件详情读取。 -- 支持删除、重命名、复制、剪切和粘贴。 -- 支持文件类型图标和多选复选框。 -- 支持下载任务和路径输入场景复用文件选择器。 -- 引入 FILETREE 文件索引缓存。 - -任务拆分： -后端： -- 实现 GET /api/v1/storage/drivers。 -- 实现 GET /api/v1/storage/driverInfo。 -- 实现 GET /api/v1/storage/files。 -- 实现 GET /api/v1/storage/file。 -- 实现 POST /api/v1/storage/files/remove。 -- 实现 POST /api/v1/storage/file/rename。 -- 实现 POST /api/v1/storage/files/copy。 -- 实现 POST /api/v1/storage/files/move。 -- 请求 OpenList 时携带当前设备会话对应的 OpenList 认证信息。 -- 将 OpenBridge 的 / 映射到当前 OpenList 用户可见根目录。 -- 对 OpenList 源和用户根目录进行路径归一化处理。 -- 删除、移动、复制、重命名后刷新 FILETREE 缓存。 - -缓存： -- 维护 FILETREE 文件树缓存结构。 -- 支持配置缓存磁盘上限，最小 4 KB。 -- 支持配置缓存层数，范围 1 到 5。 -- 启动时读取缓存，退出或重启时写回缓存。 -- 缓存预热不得阻塞正常文件浏览。 - -前端： -- OpenList 页面显示面包屑路径。 -- 文件列表展示名称、大小、修改时间和操作。 -- 支持按名称、大小、修改时间排序。 -- 支持自动分页加载。 -- 支持文件夹、图片、视频、音频、压缩包、PDF、Office、代码等类型图标。 -- 支持表头复选框和行复选框。 -- 支持工具栏复制、剪切、粘贴、删除、重命名、详细信息。 -- 支持行内详情和重命名按钮。 -- 支持 OpenList 路径选择器，用于下载任务源路径和其他路径输入场景。 - -验收标准： -- 不同 OpenList 用户进入 /openlist 时看到自己的根目录。 -- 文件超过 50 个时前端能继续加载。 -- 删除、重命名、复制、移动操作能同步到 OpenList。 -- 文件夹可进入，文件可查看详情和发起下载。 -- 切换 OpenList Base URL 后文件浏览上下文不会串源。 - -交付物： -- Storage API。 -- OpenList 文件浏览器。 -- OpenList 路径选择器。 -- FILETREE 缓存能力。 - - -Week 6 任务说明：直链解析、终端直下与文件夹下载 - -本周定位： -本周围绕“拿到文件后如何下载”建立下载入口。重点不是 aria2 任务管理，而是直链解析、当前设备下载、百度终端直下、二维码、直链清单和文件夹 ZIP。 - -本周目标： -- 支持从 OpenList 路径解析文件直链。 -- 区分 OpenList 代理直链和真实可直连链接。 -- 支持当前设备直接下载文件。 -- 支持百度单文件终端直下。 -- 支持复制直链和生成二维码。 -- 支持文件夹打包 ZIP 下载。 -- 支持百度文件夹批量解析直链清单。 -- 移除大文件夹解析场景的固定短超时。 - -任务拆分： -后端： -- 实现 POST /api/v1/download/resolve。 -- 实现 GET /api/v1/download/direct。 -- 实现 HEAD /api/v1/download/direct。 -- 实现 GET /api/v1/download/folder-zip。 -- 对百度 Provider 解析真实直链，返回 is_openlist_proxy=false。 -- 对 OpenList 代理链接保留代理下载能力。 -- 处理手机访问 127.0.0.1 直链失败问题，优先提供真实直链或局域网可访问链接。 -- 文件夹 ZIP 下载不设置固定 30 秒超时。 -- 文件夹扫描支持较大目录树。 - -前端： -- OpenList 文件行打开下载确认弹窗。 -- 单文件弹窗展示路径、文件名、大小、Provider、直链和代理状态。 -- 当 is_openlist_proxy=false 时优先展示百度直链下载、复制直链和生成二维码。 -- 文件夹弹窗展示文件数量和总大小。 -- 百度文件夹支持生成直链清单。 -- 其他文件夹支持打包为 ZIP 下载。 -- 下载目录输入框支持本机目录选择。 - -用户体验： -- 明确当前设备下载不会进入服务端 aria2 任务列表。 -- 明确 ZIP 下载由 OpenBridge 打包输出。 -- 明确直链清单适合发送到其他终端自行下载。 - -验收标准： -- 单文件可以解析直链。 -- 百度单文件可以复制真实直链或生成二维码。 -- 手机端不会拿到只能电脑本机使用的 127.0.0.1 下载地址。 -- 文件夹可以打包 ZIP 下载。 -- 百度文件夹可以生成直链清单。 -- 大文件夹解析不会因为 30 秒前端超时直接失败。 - -交付物： -- Direct Link API。 -- DownloadDialog 直链下载弹窗。 -- 文件夹 ZIP 下载能力。 -- 直链清单能力。 - - -Week 7 任务说明：aria2 下载任务、进度、停止与重试 - -本周定位： -本周完成服务端下载任务闭环。OpenBridge 负责把 OpenList 文件解析为直链，再提交给运行在服务端电脑上的 aria2，并持续同步任务状态。 - -本周目标： -- 支持创建 aria2 下载任务。 -- 保存任务与 aria2 GID 映射。 -- 支持任务列表、任务详情和状态筛选。 -- 支持每秒刷新活跃任务状态。 -- 支持进度条、下载速度和预测进度。 -- 支持停止单个任务和批量停止任务。 -- 支持失败或手动停止任务重试。 -- 支持打开已下载文件、打开所在文件夹和删除本地文件。 - -任务拆分： -后端： -- 封装 aria2 JSON-RPC Client。 -- 实现 POST /api/v1/download/tasks。 -- 实现 GET /api/v1/download/tasks/:id。 -- 实现 GET /api/v1/download/aria2-status。 -- 实现 POST /api/v1/download/tasks/:id/stop。 -- 实现 POST /api/v1/download/tasks/stop。 -- 实现 POST /api/v1/download/tasks/:id/retry。 -- 实现 POST /api/v1/download/tasks/:id/open。 -- 实现 POST /api/v1/download/tasks/:id/open-location。 -- 实现 POST /api/v1/download/tasks/:id/delete-file。 -- 任务实体保存 Progress、CompletedLength、TotalLength、DownloadSpeed、RetryCount 等字段。 -- 修复特殊文件名打开所在文件夹失败问题。 -- 删除本地文件时保留任务记录，并将状态更新为 deleted。 - -前端： -- 下载任务页支持创建任务。 -- 源路径支持 OpenList 文件选择器。 -- 目标目录支持本机目录选择。 -- 任务列表支持筛选：全部、等待中、下载中、暂停、停止、文件已删除、失败、完成。 -- 任务列表支持排序和多选。 -- 任务行展示进度条、下载速度、已下载大小和总大小。 -- 任务行支持停止、删除文件、清除记录、重试、打开文件、打开所在文件夹。 -- 任务详情展示完整字段和操作按钮。 -- 存在活跃任务时默认每秒刷新。 - -状态规则： -- 等待中、下载中、暂停中任务可以停止。 -- 失败和已停止任务可以重试。 -- 已完成、已停止和失败任务可以删除本地文件。 -- 清除记录不删除本地文件。 - -验收标准： -- 从 OpenList 页面和任务页面都能创建 aria2 下载任务。 -- 任务进度、速度和状态能持续更新。 -- 停止任务后可重试。 -- 失败任务可重试。 -- 已完成任务可打开文件或所在文件夹。 -- 删除文件后任务记录仍存在且状态为文件已删除。 -- 批量停止能返回成功列表和失败列表。 - -交付物： -- aria2 Client。 -- DownloadTask API。 -- 下载任务页面。 -- 任务状态同步逻辑。 - - -Week 8 任务说明：WebDAV Mount 代理与 rclone 挂载配置 - -本周定位： -本周完成本地盘符挂载链路。OpenBridge 通过 WebDAV 代理复用 OpenList 文件能力，同时用 OpenBridge Mount 层配额改写客户端看到的容量，再通过 rclone 管理本地挂载。 - -本周目标： -- 支持按 Mount 暴露 WebDAV 根。 -- WebDAV 文件能力复用 OpenList。 -- WebDAV 容量展示使用 OpenBridge Mount 配额。 -- 支持 rclone 配置保存、写入、挂载、停止挂载和删除。 -- 支持普通、Union、Combine 三种挂载方式。 -- 支持 rclone 路径从设置页保存到 .env。 -- 修复 OpenList 端口更换后 rclone 仍引用旧配置的问题。 - -任务拆分： -WebDAV 代理： -- 实现 /api/v1/webdav/mounts/:id。 -- 根据 Mount ID 找到对应 mount_path。 -- 将文件操作代理到 {OPENLIST_BASE_URL}/dav{mount.mount_path}。 -- 透传客户端 Authorization 给 OpenList。 -- 改写 PROPFIND 中的 href、Location、Content-Location。 -- 改写 quota-used-bytes 和 quota-available-bytes。 -- 支持常见 WebDAV 方法：OPTIONS、PROPFIND、GET、HEAD、PUT、DELETE、MKCOL、MOVE、COPY。 - -rclone 后端： -- 定义 RcloneProfile 实体。 -- RcloneProfile 按 OpenList Base URL 隔离。 -- 保存配置名、挂载方式、Mount IDs、用户名、暗文密码和目标路径。 -- 实现配置列表、新增、编辑、删除。 -- 实现写入 rclone 配置。 -- 实现启动 rclone mount。 -- 实现停止对应挂载进程。 -- Mount 被删除后，旧 rclone 配置需要刷新状态或阻止继续挂载。 - -前端： -- 新增 Rclone 页面。 -- 新增配置弹窗。 -- 支持选择 Mount。 -- 支持普通、Union、Combine 三种模式。 -- 支持目标盘符或本地目录输入。 -- 支持本机路径选择器。 -- 配置卡片展示写入、挂载、停止挂载、删除和复制命令。 - -验收标准： -- 单个 Mount 可以通过 WebDAV 地址访问。 -- rclone 可把 Mount 挂载为本地盘符。 -- 容量展示尽量贴近 OpenBridge Mount 配额。 -- Union/Combine 配置能保留多个 Mount 的识别信息。 -- 停止挂载后本地盘符释放。 -- 删除配置后 rclone 中旧配置不继续残留为可用状态。 -- 更换 OpenList 端口后旧源 rclone 配置不会串到新源。 - -交付物： -- WebDAV Mount 代理。 -- Rclone Profile API。 -- Rclone 配置页面。 -- WebDAV Mount 使用说明。 - - -Week 9 任务说明：设置中心、主机资源、性能与界面体验 - -本周定位： -本周完成控制台的运行时管理能力。目标是让用户不再手动改命令和配置文件，而是在前端完成 OpenList、aria2、rclone、缓存、登录策略和服务控制配置。 - -本周目标： -- 设置页拆分为清晰的配置卡片。 -- 支持 aria2 RPC、aria2 路径和自动启动。 -- 支持 rclone 路径保存。 -- 支持 OpenList Base URL 保存并触发重新登录。 -- 支持本地路径和文件选择器。 -- 支持重启和退出 OpenBridge。 -- 支持启动自动打开浏览器。 -- 支持主机资源和带宽监控。 -- 优化前端动画、主题和响应式布局。 - -任务拆分： -后端设置： -- 实现 GET /api/v1/settings。 -- 实现 PUT /api/v1/settings/openlist。 -- 实现 PUT /api/v1/settings/aria2。 -- 实现 PUT /api/v1/settings/rclone。 -- 实现 PUT /api/v1/settings/session。 -- 实现 PUT /api/v1/settings/app。 -- 实现 PUT /api/v1/settings/filetree。 -- 设置写入 .env，并更新运行时配置。 -- 设置返回 app_version，前端底部显示 OpenBridge vX.X。 - -系统能力： -- 实现 POST /api/v1/system/pick-path。 -- 实现 GET /api/v1/system/metrics。 -- 实现 POST /api/v1/system/restart。 -- 实现 POST /api/v1/system/exit。 -- 主机资源展示整机 CPU、内存、磁盘和 OpenBridge 进程占用。 -- 带宽展示上行、下行、OpenBridge、OpenList、aria2 和 rclone 相关指标。 -- 服务启动时根据配置自动打开浏览器。 -- 服务启动时根据配置自动拉起 aria2。 - -前端体验： -- 设置页分为用户信息、aria2、默认下载目录、其他设置、服务控制、FILETREE、Rclone、OpenList、重置用户数据。 -- rclone 设置单独成框。 -- aria2 路径、自动启动、rclone 路径能正确保存。 -- 默认下载目录和路径输入均支持文件或目录选择器。 -- 仪表盘展示总空间、Provider 用量、主机资源、系统健康和快捷操作。 -- 顶部栏展示实时上下行速度。 -- 支持用户选择是否开启动画效果。 -- 修复仪表盘、服务商、配额页面大面积空白和黑夜模式可读性问题。 - -验收标准： -- 设置页保存后重启仍生效。 -- aria2 能自动启动。 -- rclone 路径能写入 .env 并用于 rclone 操作。 -- 点击重启服务和退出服务行为明确。 -- 仪表盘资源占用每秒刷新且无明显卡顿。 -- 前端在桌面和移动端都能正常渲染。 - -交付物： -- Settings API。 -- System API。 -- 设置页面。 -- 仪表盘和顶部栏指标。 -- 本机路径选择器。 - - -Week 10 任务说明：集成补齐、数据重置、前端汉化与文档完善 - -本周定位： -本周围绕完整性和一致性做补齐，处理真实使用中暴露的问题，让系统从“功能可用”进入“可交付演示”的状态。 - -本周目标： -- 完善 OpenList 源隔离和用户根目录逻辑。 -- 完善重置用户数据策略。 -- 完善 Quark、Baidu、Local、Generic Provider 的页面和后端行为。 -- 完善 OpenList 文件管理操作。 -- 优化下载任务刷新、停止、重试和删除文件体验。 -- 完善前端汉化和图标。 -- 完成用户手册、API 文档、PPT 和团队贡献材料。 - -任务拆分： -后端集成： -- Provider、Mount、rclone、下载任务按 OpenList Base URL 隔离。 -- OpenList 不同用户按用户根目录访问文件。 -- 切换 OpenList Base URL 后要求重新登录。 -- 重置用户数据分为当前 OpenList 源和全部数据。 -- 修复默认密码、OpenList 端口和 Mount 绑定关系。 -- 优化大文件夹解析和文件选择超时。 -- 文件浏览缓存预热不得影响正常使用。 -- Quark Provider 支持 Cookie、配额同步和状态展示。 -- Baidu Provider 支持直链解析和终端直下场景。 - -前端集成： -- OpenList 文件页补齐删除、重命名、复制、剪切、粘贴、详情和文件图标。 -- 下载任务页补齐单个停止、批量停止、删除本地文件、失败或停止后重试。 -- 下载任务进度条优先使用 aria2 进度，必要时用速度预测。 -- Provider 编辑功能可用。 -- 配额管理下拉菜单不被遮挡。 -- OpenList 文件浏览加载超过 50 个文件。 -- 入口页、侧边栏、顶部栏、仪表盘、设置页进行统一汉化和视觉优化。 -- 新增 OpenBridge 图标和 favicon。 - -文档与演示材料： -- 编写用户手册，覆盖每个页面和按钮。 -- 补充 API 文档，覆盖当前后端真实接口。 -- 插入已有截图，对新增但未截图位置保留占位符。 -- 编写 PPT，说明产品背景、功能概览、技术栈、亮点难点和软件规模。 -- 编写团队贡献说明和实践心得。 - -验收标准： -- OpenList 文件、Provider、Mount、rclone 在不同 OpenList 源之间不串数据。 -- 普通用户和管理员看到的页面符合权限设计。 -- 下载任务支持完整生命周期管理。 -- OpenList 文件管理操作能真实作用于 OpenList。 -- 用户手册能按步骤覆盖前端全部页面。 -- API 文档能和后端路由保持一致。 - -交付物： -- 完整前端功能修复。 -- 完整后端集成修复。 -- 用户手册。 -- API 文档。 -- 演示 PPT。 -- 团队贡献文档。 - - -Week 11 任务说明：最终验收、打包发布与链路闭环 - -本周定位： -本周完成最终交付闭环。目标是让代码、文档、构建产物、Release、演示材料和端到端测试全部对应同一个版本。 - -本周目标： -- 完成全链路回归测试。 -- 完成前端生产构建并嵌入后端。 -- 完成 Windows EXE 打包。 -- 自动生成或提供 .env.example。 -- 完成 Git 分支合并、版本标签和 GitHub Release。 -- 上传发布附件。 -- 完成用户手册、PDF、PPT 和演示视频交付。 - -任务拆分： -测试闭环： -- 测试登录、会话过期、后端重启、OpenList 换源和设备限制。 -- 测试仪表盘资源指标和顶部栏带宽显示。 -- 测试 Provider 新增、编辑、删除。 -- 测试 Mount 创建、编辑、删除、配额同步和 WebDAV 容量展示。 -- 测试 OpenList 文件浏览、分页、详情、删除、重命名、复制、剪切和粘贴。 -- 测试单文件直链、二维码、当前设备下载和文件夹 ZIP。 -- 测试百度直链清单。 -- 测试 aria2 创建任务、进度、停止、批量停止、重试、打开文件、删除本地文件。 -- 测试 rclone 配置写入、挂载、停止挂载和删除配置。 -- 测试设置保存、服务重启、退出和自动打开浏览器。 - -构建发布： -- 运行 npm run build。 -- 将 frontend/dist 同步到 backend/web/dist。 -- 运行 go test ./...。 -- 运行 go build -o openbridge.exe ./backend 或等价构建命令。 -- 确认 APP_VERSION=v1.3。 -- 确认 .env.example 与实际配置项一致。 -- 创建版本提交。 -- 合并到 dev。 -- 合并到 main。 -- 创建并推送 v1.3 标签。 -- 创建 GitHub Release。 -- 上传 openbridge.exe、.env.example 和演示视频附件。 - -文档交付： -- 用户手册 Markdown 与现有页面保持一致。 -- 用户手册 PDF 可打开。 -- API 文档覆盖当前接口。 -- PPT 不超过 5 页，讲清功能概览、技术栈和软件规模。 -- 演示视频和截图路径可追溯。 -- 任务周计划整理为 Week 1 到 Week 11 单独文件。 - -验收标准： -- dev 和 main 指向同一发布提交。 -- v1.3 标签指向 main 发布提交。 -- Release 页面存在且附件可下载。 -- 打包 EXE 可启动服务并自动生成 .env。 -- 浏览器能访问本地控制台。 -- 主要功能链路均能完成一次端到端演示。 -- 文档、PPT、视频和代码版本一致。 - -交付物： -- openbridge.exe。 -- .env.example。 -- GitHub Release。 -- v1.3 标签。 -- 用户手册 Markdown 和 PDF。 -- 产品演示 PPT。 -- 产品演示视频。 -- Week 1 到 Week 11 任务说明文件。 - - -五、风险管理 - -1、需求范围膨胀风险 - -风险说明： -项目功能覆盖 OpenList 文件浏览、Provider 管理、Mount 配额、下载任务、rclone 挂载、WebDAV 代理、设置中心、资源监控和文档交付，功能点较多，容易在开发后期不断增加新需求，导致进度被压缩。 - -应对措施： -将需求按优先级拆分为核心链路和增强功能。核心链路包括登录、文件浏览、Provider、Mount、下载任务和设置保存；增强功能包括动画优化、二维码、终端直下、资源监控、备份还原等。每周明确交付边界，新增需求优先评估是否影响主链路和最终交付。 - -2、OpenList 接口兼容风险 - -风险说明： -OpenBridge 依赖 OpenList 的登录、文件列表、文件详情、删除、重命名、复制、移动、WebDAV 和直链解析能力。若 OpenList 版本变化、接口返回结构不同或用户根目录策略不同，可能导致文件浏览和下载链路异常。 - -应对措施： -后端对 OpenList 请求进行统一封装，集中处理 token、base path、OpenList Base URL、路径归一化和错误返回。文件浏览按用户根目录映射，OpenList 换源后强制重新登录，避免不同源或不同用户之间串数据。 - -3、数据隔离风险 - -风险说明： -系统支持切换 OpenList Base URL，不同 OpenList 源下的 Provider、Mount、下载任务和 rclone 配置如果没有隔离，可能出现旧源数据在新源下显示或错误挂载的问题。 - -应对措施： -Provider、DownloadTask、RcloneProfile 等数据加入 OpenList Base URL 作用域字段，Mount 通过 Provider 关系实现源隔离。更换 OpenList Base URL 后要求重新登录，并在列表查询、配置保存、重置数据和 rclone 操作中按源过滤。 - -4、下载任务稳定性风险 - -风险说明： -大文件夹解析、文件夹 ZIP、百度直链解析和 aria2 下载任务可能耗时较长，如果使用固定短超时，容易造成前端误报失败。aria2 状态也可能与数据库记录不同步，导致进度条或任务状态不准确。 - -应对措施： -取消大文件夹和文件下载场景的固定短超时。下载任务优先读取 aria2 返回的进度、速度、已完成大小和总大小；aria2 状态缺失时使用数据库记录和速度预测补充展示。支持停止、批量停止、失败或停止后重试，并明确清除记录与删除本地文件的区别。 - -5、rclone 挂载风险 - -风险说明： -rclone 需要依赖本机 rclone.exe、WebDAV 地址、认证信息和 Mount ID。如果 Mount 被删除、OpenList 端口更换或 rclone 配置未更新，可能出现旧配置残留、挂载失败或挂载到错误目录的问题。 - -应对措施： -rclone 配置按 OpenList Base URL 隔离，并在配置中保存 Mount IDs、用户名、暗文密码和目标路径。Mount 删除后同步刷新 rclone 配置状态或阻止继续挂载。设置页提供 rclone 路径选择并写入 .env，减少手动命令输入错误。 - -6、前端体验和兼容风险 - -风险说明： -页面较多且信息密度较高，仪表盘、服务商、配额管理、下载任务和 OpenList 文件浏览都需要在桌面和移动端显示。如果样式布局不稳定，可能出现大面积空白、黑夜模式可读性差、下拉菜单遮挡等问题。 - -应对措施： -统一页面布局、卡片样式、主题变量和响应式规则。对仪表盘、服务商和配额页面进行专项修复，保证黑夜模式和亮色模式均可读。对下拉菜单层级、文件列表分页、移动端侧边栏和动画效果进行单独测试。 - -7、本地环境依赖风险 - -风险说明： -OpenBridge 依赖本机环境运行，包括 openbridge.exe、.env、SQLite 数据库、aria2、rclone 和浏览器。不同电脑上的路径、端口、防火墙和工具安装情况可能不同，影响开箱即用。 - -应对措施： -程序首次启动自动生成 .env，并提供 .env.example。设置页支持 aria2 路径、rclone 路径、OpenList Base URL、自动启动和自动打开浏览器配置。文档中说明各配置项用途和排错方法，发布时提供 exe 与示例配置文件。 - -8、数据安全与误操作风险 - -风险说明： -系统支持删除 OpenList 文件、删除本地下载文件、重置数据和还原备份，这些操作具有破坏性。如果确认提示不足或文档说明不清，可能造成误删或数据覆盖。 - -应对措施： -前端对删除、重置、还原等危险操作增加确认提示。重置数据拆分为当前 OpenList 源数据和全部数据。备份还原支持无密码明文备份和带密码加密备份，并明确还原会覆盖当前全部用户数据。用户手册中说明危险操作的影响范围。 - -9、进度和协作风险 - -风险说明： -项目成员分工包含前端、后端、文档和测试，多模块之间依赖较强。如果接口定义不稳定或合并不及时，可能影响后续成员开发。 - -应对措施： -采用每周任务拆分和阶段验收机制。后端先明确 API 路径、请求体和返回字段，前端按接口封装统一调用。项目经理负责每周协调任务、跟踪进度、测试合并结果，并在发现问题后及时分配修复任务。 - -10、交付一致性风险 - -风险说明： -最终需要同时提交代码、用户手册、API 文档、PPT、演示视频、打包程序、.env.example、Git 标签和 Release。如果版本不一致，可能出现文档描述与软件功能不匹配的问题。 - -应对措施： -最终阶段统一以 v1.3 作为交付版本，前端底部版本号来自 APP_VERSION。发布前执行完整回归测试，确保用户手册、API 文档、PPT 和 Release 附件对应同一代码版本。最终合并到 dev 和 main 后创建标签并发布 Release。 diff --git a/docs/task/week1.md b/docs/task/week1.md deleted file mode 100644 index cd1b80a..0000000 --- a/docs/task/week1.md +++ /dev/null @@ -1,54 +0,0 @@ -# Week 1 任务说明：需求确认、产品边界与项目骨架 - -## 本周定位 - -本周完成 OpenBridge 的产品定义和工程起步，明确系统要解决的问题：在 OpenList 已经具备文件访问能力的基础上，补齐服务商管理、Mount 配额、下载编排、rclone 挂载和可视化控制台。 - -## 本周目标 - -- 明确管理员和普通用户的使用场景。 -- 确定前后端技术栈和本地化部署方式。 -- 建立 Monorepo 工程结构。 -- 搭建前端基础页面和后端基础服务。 -- 输出第一版需求说明、架构说明和接口草案。 - -## 任务拆分 - -### 产品与文档 - -- 梳理核心角色：管理员、普通用户、运行 OpenBridge 的服务端电脑、其他下载终端。 -- 梳理核心功能：仪表盘、OpenList 文件浏览、服务商管理、配额管理、下载任务、rclone、设置、调试页。 -- 明确普通用户只可见仪表盘、OpenList、服务商和下载任务。 -- 明确管理员可见全部页面和管理操作。 -- 编写初版产品说明和页面导航说明。 - -### 后端 - -- 初始化 Go 后端工程。 -- 引入 Gin 作为 HTTP 框架。 -- 规划 `config`、`handler`、`usecase`、`repository`、`domain`、`tool` 分层。 -- 提供基础启动入口和健康检查能力。 -- 预留 `/api/v1` API 前缀。 - -### 前端 - -- 初始化 Vue 3、Vite、TypeScript 工程。 -- 引入 Pinia、Vue Router、i18n 基础能力。 -- 搭建入口页、登录页和控制台布局。 -- 设计侧边栏、顶部栏、页面头部等公共组件。 -- 建立基础样式变量，预留亮色与黑夜模式。 - -## 验收标准 - -- 本地可以启动前端开发服务。 -- 本地可以启动后端服务。 -- 浏览器能访问入口页和登录页。 -- 项目目录结构清晰，前后端职责边界明确。 -- 需求文档能说明“为什么做 OpenBridge”和“要完成哪些页面”。 - -## 交付物 - -- Monorepo 基础工程。 -- 初版产品说明。 -- 初版架构说明。 -- 初版页面导航设计。 diff --git a/docs/task/week10.md b/docs/task/week10.md deleted file mode 100644 index 95b44db..0000000 --- a/docs/task/week10.md +++ /dev/null @@ -1,66 +0,0 @@ -# Week 10 任务说明：集成补齐、数据重置、前端汉化与文档完善 - -## 本周定位 - -本周围绕完整性和一致性做补齐，处理真实使用中暴露的问题，让系统从“功能可用”进入“可交付演示”的状态。 - -## 本周目标 - -- 完善 OpenList 源隔离和用户根目录逻辑。 -- 完善重置用户数据策略。 -- 完善 Quark、Baidu、Local、Generic Provider 的页面和后端行为。 -- 完善 OpenList 文件管理操作。 -- 优化下载任务刷新、停止、重试和删除文件体验。 -- 完善前端汉化和图标。 -- 完成用户手册、API 文档、PPT 和团队贡献材料。 - -## 任务拆分 - -### 后端集成 - -- Provider、Mount、rclone、下载任务按 OpenList Base URL 隔离。 -- OpenList 不同用户按用户根目录访问文件。 -- 切换 OpenList Base URL 后要求重新登录。 -- 重置用户数据分为当前 OpenList 源和全部数据。 -- 修复默认密码、OpenList 端口和 Mount 绑定关系。 -- 优化大文件夹解析和文件选择超时。 -- 文件浏览缓存预热不得影响正常使用。 -- Quark Provider 支持 Cookie、配额同步和状态展示。 -- Baidu Provider 支持直链解析和终端直下场景。 - -### 前端集成 - -- OpenList 文件页补齐删除、重命名、复制、剪切、粘贴、详情和文件图标。 -- 下载任务页补齐单个停止、批量停止、删除本地文件、失败或停止后重试。 -- 下载任务进度条优先使用 aria2 进度，必要时用速度预测。 -- Provider 编辑功能可用。 -- 配额管理下拉菜单不被遮挡。 -- OpenList 文件浏览加载超过 50 个文件。 -- 入口页、侧边栏、顶部栏、仪表盘、设置页进行统一汉化和视觉优化。 -- 新增 OpenBridge 图标和 favicon。 - -### 文档与演示材料 - -- 编写用户手册，覆盖每个页面和按钮。 -- 补充 API 文档，覆盖当前后端真实接口。 -- 插入已有截图，对新增但未截图位置保留占位符。 -- 编写 PPT，说明产品背景、功能概览、技术栈、亮点难点和软件规模。 -- 编写团队贡献说明和实践心得。 - -## 验收标准 - -- OpenList 文件、Provider、Mount、rclone 在不同 OpenList 源之间不串数据。 -- 普通用户和管理员看到的页面符合权限设计。 -- 下载任务支持完整生命周期管理。 -- OpenList 文件管理操作能真实作用于 OpenList。 -- 用户手册能按步骤覆盖前端全部页面。 -- API 文档能和后端路由保持一致。 - -## 交付物 - -- 完整前端功能修复。 -- 完整后端集成修复。 -- 用户手册。 -- API 文档。 -- 演示 PPT。 -- 团队贡献文档。 diff --git a/docs/task/week11.md b/docs/task/week11.md deleted file mode 100644 index 0b44bbd..0000000 --- a/docs/task/week11.md +++ /dev/null @@ -1,75 +0,0 @@ -# Week 11 任务说明：最终验收、打包发布与链路闭环 - -## 本周定位 - -本周完成最终交付闭环。目标是让代码、文档、构建产物、Release、演示材料和端到端测试全部对应同一个版本。 - -## 本周目标 - -- 完成全链路回归测试。 -- 完成前端生产构建并嵌入后端。 -- 完成 Windows EXE 打包。 -- 自动生成或提供 `.env.example`。 -- 完成 Git 分支合并、版本标签和 GitHub Release。 -- 上传发布附件。 -- 完成用户手册、PDF、PPT 和演示视频交付。 - -## 任务拆分 - -### 测试闭环 - -- 测试登录、会话过期、后端重启、OpenList 换源和设备限制。 -- 测试仪表盘资源指标和顶部栏带宽显示。 -- 测试 Provider 新增、编辑、删除。 -- 测试 Mount 创建、编辑、删除、配额同步和 WebDAV 容量展示。 -- 测试 OpenList 文件浏览、分页、详情、删除、重命名、复制、剪切和粘贴。 -- 测试单文件直链、二维码、当前设备下载和文件夹 ZIP。 -- 测试百度直链清单。 -- 测试 aria2 创建任务、进度、停止、批量停止、重试、打开文件、删除本地文件。 -- 测试 rclone 配置写入、挂载、停止挂载和删除配置。 -- 测试设置保存、服务重启、退出和自动打开浏览器。 - -### 构建发布 - -- 运行 `npm run build`。 -- 将 `frontend/dist` 同步到 `backend/web/dist`。 -- 运行 `go test ./...`。 -- 运行 `go build -o openbridge.exe ./backend` 或等价构建命令。 -- 确认 `APP_VERSION=v1.3`。 -- 确认 `.env.example` 与实际配置项一致。 -- 创建版本提交。 -- 合并到 `dev`。 -- 合并到 `main`。 -- 创建并推送 `v1.3` 标签。 -- 创建 GitHub Release。 -- 上传 `openbridge.exe`、`.env.example` 和演示视频附件。 - -### 文档交付 - -- 用户手册 Markdown 与现有页面保持一致。 -- 用户手册 PDF 可打开。 -- API 文档覆盖当前接口。 -- PPT 不超过 5 页，讲清功能概览、技术栈和软件规模。 -- 演示视频和截图路径可追溯。 -- 任务周计划整理为 Week 1 到 Week 11 单独文件。 - -## 验收标准 - -- `dev` 和 `main` 指向同一发布提交。 -- `v1.3` 标签指向 `main` 发布提交。 -- Release 页面存在且附件可下载。 -- 打包 EXE 可启动服务并自动生成 `.env`。 -- 浏览器能访问本地控制台。 -- 主要功能链路均能完成一次端到端演示。 -- 文档、PPT、视频和代码版本一致。 - -## 交付物 - -- `openbridge.exe` -- `.env.example` -- GitHub Release -- `v1.3` 标签 -- 用户手册 Markdown 和 PDF -- 产品演示 PPT -- 产品演示视频 -- Week 1 到 Week 11 任务说明文件 diff --git a/docs/task/week2.md b/docs/task/week2.md deleted file mode 100644 index 262ab11..0000000 --- a/docs/task/week2.md +++ /dev/null @@ -1,55 +0,0 @@ -# Week 2 任务说明：后端基础设施、配置系统与数据模型 - -## 本周定位 - -本周完成后端基础设施，让后续 Provider、Mount、下载任务、设置和用户会话都能在统一的配置、错误、日志和数据库体系上开发。 - -## 本周目标 - -- 建立统一 API 响应结构。 -- 建立错误码和错误返回规范。 -- 建立 `.env` 配置读取与默认配置生成机制。 -- 建立 SQLite 与 GORM 数据访问基础。 -- 建立基础数据模型和自动迁移。 -- 支持前端静态资源嵌入后端。 - -## 任务拆分 - -### 后端基础设施 - -- 定义统一返回结构：`code`、`message`、`data`。 -- 定义成功码和常见错误码。 -- 封装配置读取逻辑，支持 `APP_NAME`、`APP_ENV`、`APP_PORT`、`APP_VERSION`。 -- 支持程序首次启动时自动生成 `.env`。 -- 支持 `APP_AUTO_OPEN_BROWSER`，为后续启动自动打开浏览器做准备。 -- 建立日志输出规则，保留请求、错误和关键业务日志。 - -### 数据层 - -- 引入 SQLite 作为本地数据库。 -- 使用 GORM 管理数据模型。 -- 定义 Provider、Mount、QuotaSnapshot、DownloadTask、RcloneProfile、会话等核心实体的基础字段。 -- 实现数据库初始化和自动迁移。 -- 保证数据库路径可通过 `.env` 配置。 - -### 前端基础 - -- 封装统一请求工具。 -- 设置 API Base URL。 -- 处理统一响应格式。 -- 建立基础 Store，用于保存登录态、角色、设备 ID 和常用缓存。 - -## 验收标准 - -- 后端启动时能读取或生成 `.env`。 -- `/api/v1` 下接口统一返回 JSON。 -- SQLite 数据库能正常创建和迁移。 -- 前端请求封装能处理成功和失败响应。 -- 后端静态资源嵌入方案可用。 - -## 交付物 - -- 后端配置系统。 -- 统一响应和错误体系。 -- 数据库初始化和基础实体。 -- 前端请求封装。 diff --git a/docs/task/week3.md b/docs/task/week3.md deleted file mode 100644 index 750bd29..0000000 --- a/docs/task/week3.md +++ /dev/null @@ -1,59 +0,0 @@ -# Week 3 任务说明：OpenList 登录、设备会话与权限控制 - -## 本周定位 - -本周打通 OpenBridge 与 OpenList 的登录关系，解决“前端假登录”“后端重启不失效”“换源不重登”等问题，为后续按用户根目录、按 OpenList 源隔离数据打基础。 - -## 本周目标 - -- 通过 OpenList 账号登录 OpenBridge。 -- 保存设备级会话，而不是只依赖前端本地状态。 -- 支持后端重启、OpenList 重启、OpenList 换源后的重新登录检测。 -- 支持普通用户和管理员权限区分。 -- 支持账号最多在线设备数量限制，默认 5 台。 -- 支持本地登录超时时间由前端本地设置。 - -## 任务拆分 - -### 后端 - -- 实现 `POST /api/v1/user/login`。 -- 登录时转发 OpenList 认证并获取 OpenList 用户信息。 -- 保存当前设备会话、OpenList Base URL、用户信息和后端实例指纹。 -- 实现 `GET /api/v1/user/info`。 -- 实现 `GET /api/v1/user/session-status`。 -- 会话校验时检查后端实例、OpenList 源、OpenList 用户和设备 ID。 -- 管理同一账号的设备数量，普通账号默认最多 5 台，管理员可配置。 -- 实现管理员权限中间件。 - -### 前端 - -- 登录页对接真实登录接口。 -- 生成并持久化 `X-OpenBridge-Device-ID`。 -- 全局请求自动携带设备 ID。 -- 路由守卫在进入控制台页面前校验会话。 -- 普通用户隐藏配额、Rclone、设置、Debug 页面。 -- Debug 页不出现在侧边栏，只允许直接访问 `/debug`。 -- 设置页加入本地登录超时时间。 - -### 数据与安全 - -- 避免只靠 localStorage 判断登录。 -- 设备会话与 OpenList 源绑定。 -- 切换 OpenList Base URL 后要求重新登录。 -- 后端重启后前端能够检测并回到登录页。 - -## 验收标准 - -- 登录成功后可进入控制台。 -- 删除或重启后端后，前端会检测到会话失效。 -- 切换 OpenList Base URL 后需要重新登录。 -- 普通用户看不到管理员页面。 -- 超过设备限制时禁止继续登录。 - -## 交付物 - -- 用户登录 API。 -- 设备会话机制。 -- 权限中间件。 -- 前端登录和路由守卫。 diff --git a/docs/task/week4.md b/docs/task/week4.md deleted file mode 100644 index 0ab74c3..0000000 --- a/docs/task/week4.md +++ /dev/null @@ -1,62 +0,0 @@ -# Week 4 任务说明：Provider、Mount 与配额管理闭环 - -## 本周定位 - -本周完成服务商和 Mount 的核心模型，把 OpenBridge 从“能登录的控制台”推进到“能管理存储来源和配额”的系统。 - -## 本周目标 - -- 建立 Provider 抽象和服务商注册能力。 -- 支持通用、百度、本地、夸克等 Provider 类型的统一管理。 -- 建立 Mount 模型，绑定 Provider 与 OpenList 路径。 -- 支持真实配额和虚拟配额。 -- 前端完成服务商管理和配额管理页面。 -- 服务商、Mount、配额按 OpenList Base URL 隔离。 - -## 任务拆分 - -### 后端 - -- 定义 ProviderAccount 实体。 -- 实现 Provider Repository 和 UseCase。 -- 实现 Provider 注册、列表、详情、编辑、删除接口。 -- 定义 MountPoint 实体。 -- 实现 Mount 创建、列表、编辑、删除接口。 -- 定义配额模式：`real` 和 `virtual`。 -- 实现 Mount 配额查询和同步。 -- 记录 QuotaSnapshot。 -- 对 Provider、Mount、QuotaSnapshot 加入 OpenList 源隔离字段。 - -### Provider 能力 - -- 通用 Provider：适配 OpenList 已有挂载路径。 -- 百度 Provider：保存 access token，为后续直链解析准备。 -- 本地 Provider：读取本机路径容量。 -- 夸克 Provider：保存 Cookie 和账号标识，为后续容量同步准备。 - -### 前端 - -- 服务商管理页展示服务商卡片。 -- 支持新增、编辑、删除服务商。 -- 服务商表单支持不同 Provider 类型的字段切换。 -- 配额管理页支持选择 Provider。 -- 展示 Provider 总使用量和总容量。 -- 支持创建、编辑和删除 Mount。 -- 支持真实容量和虚拟容量显示。 -- 修复下拉菜单遮挡问题。 - -## 验收标准 - -- 管理员可以新增、编辑、删除服务商。 -- 管理员可以为服务商创建 Mount。 -- Mount 能正确显示真实或虚拟配额。 -- 普通用户只能查看服务商和基础信息，不能执行管理操作。 -- 更换 OpenList 端口后不会看到旧源的 Provider 和 Mount。 - -## 交付物 - -- Provider API。 -- Mount API。 -- 配额同步 API。 -- 服务商管理页面。 -- 配额管理页面。 diff --git a/docs/task/week5.md b/docs/task/week5.md deleted file mode 100644 index 0a63770..0000000 --- a/docs/task/week5.md +++ /dev/null @@ -1,67 +0,0 @@ -# Week 5 任务说明：OpenList 文件浏览、用户根目录与文件管理 - -## 本周定位 - -本周把 OpenList 文件能力接入 OpenBridge，让用户能在控制台中浏览自己可见的 OpenList 根目录，并补齐基础文件管理能力。 - -## 本周目标 - -- 支持按当前 OpenList 用户根目录浏览文件。 -- 支持 OpenList 文件列表分页加载，避免只显示前 50 个文件。 -- 支持文件详情读取。 -- 支持删除、重命名、复制、剪切和粘贴。 -- 支持文件类型图标和多选复选框。 -- 支持下载任务和路径输入场景复用文件选择器。 -- 引入 FILETREE 文件索引缓存。 - -## 任务拆分 - -### 后端 - -- 实现 `GET /api/v1/storage/drivers`。 -- 实现 `GET /api/v1/storage/driverInfo`。 -- 实现 `GET /api/v1/storage/files`。 -- 实现 `GET /api/v1/storage/file`。 -- 实现 `POST /api/v1/storage/files/remove`。 -- 实现 `POST /api/v1/storage/file/rename`。 -- 实现 `POST /api/v1/storage/files/copy`。 -- 实现 `POST /api/v1/storage/files/move`。 -- 请求 OpenList 时携带当前设备会话对应的 OpenList 认证信息。 -- 将 OpenBridge 的 `/` 映射到当前 OpenList 用户可见根目录。 -- 对 OpenList 源和用户根目录进行路径归一化处理。 -- 删除、移动、复制、重命名后刷新 FILETREE 缓存。 - -### 缓存 - -- 维护 FILETREE 文件树缓存结构。 -- 支持配置缓存磁盘上限，最小 4 KB。 -- 支持配置缓存层数，范围 1 到 5。 -- 启动时读取缓存，退出或重启时写回缓存。 -- 缓存预热不得阻塞正常文件浏览。 - -### 前端 - -- OpenList 页面显示面包屑路径。 -- 文件列表展示名称、大小、修改时间和操作。 -- 支持按名称、大小、修改时间排序。 -- 支持自动分页加载。 -- 支持文件夹、图片、视频、音频、压缩包、PDF、Office、代码等类型图标。 -- 支持表头复选框和行复选框。 -- 支持工具栏复制、剪切、粘贴、删除、重命名、详细信息。 -- 支持行内详情和重命名按钮。 -- 支持 OpenList 路径选择器，用于下载任务源路径和其他路径输入场景。 - -## 验收标准 - -- 不同 OpenList 用户进入 `/openlist` 时看到自己的根目录。 -- 文件超过 50 个时前端能继续加载。 -- 删除、重命名、复制、移动操作能同步到 OpenList。 -- 文件夹可进入，文件可查看详情和发起下载。 -- 切换 OpenList Base URL 后文件浏览上下文不会串源。 - -## 交付物 - -- Storage API。 -- OpenList 文件浏览器。 -- OpenList 路径选择器。 -- FILETREE 缓存能力。 diff --git a/docs/task/week6.md b/docs/task/week6.md deleted file mode 100644 index a113a82..0000000 --- a/docs/task/week6.md +++ /dev/null @@ -1,62 +0,0 @@ -# Week 6 任务说明：直链解析、终端直下与文件夹下载 - -## 本周定位 - -本周围绕“拿到文件后如何下载”建立下载入口。重点不是 aria2 任务管理，而是直链解析、当前设备下载、百度终端直下、二维码、直链清单和文件夹 ZIP。 - -## 本周目标 - -- 支持从 OpenList 路径解析文件直链。 -- 区分 OpenList 代理直链和真实可直连链接。 -- 支持当前设备直接下载文件。 -- 支持百度单文件终端直下。 -- 支持复制直链和生成二维码。 -- 支持文件夹打包 ZIP 下载。 -- 支持百度文件夹批量解析直链清单。 -- 移除大文件夹解析场景的固定短超时。 - -## 任务拆分 - -### 后端 - -- 实现 `POST /api/v1/download/resolve`。 -- 实现 `GET /api/v1/download/direct`。 -- 实现 `HEAD /api/v1/download/direct`。 -- 实现 `GET /api/v1/download/folder-zip`。 -- 对百度 Provider 解析真实直链，返回 `is_openlist_proxy=false`。 -- 对 OpenList 代理链接保留代理下载能力。 -- 处理手机访问 `127.0.0.1` 直链失败问题，优先提供真实直链或局域网可访问链接。 -- 文件夹 ZIP 下载不设置固定 30 秒超时。 -- 文件夹扫描支持较大目录树。 - -### 前端 - -- OpenList 文件行打开下载确认弹窗。 -- 单文件弹窗展示路径、文件名、大小、Provider、直链和代理状态。 -- 当 `is_openlist_proxy=false` 时优先展示百度直链下载、复制直链和生成二维码。 -- 文件夹弹窗展示文件数量和总大小。 -- 百度文件夹支持生成直链清单。 -- 其他文件夹支持打包为 ZIP 下载。 -- 下载目录输入框支持本机目录选择。 - -### 用户体验 - -- 明确当前设备下载不会进入服务端 aria2 任务列表。 -- 明确 ZIP 下载由 OpenBridge 打包输出。 -- 明确直链清单适合发送到其他终端自行下载。 - -## 验收标准 - -- 单文件可以解析直链。 -- 百度单文件可以复制真实直链或生成二维码。 -- 手机端不会拿到只能电脑本机使用的 `127.0.0.1` 下载地址。 -- 文件夹可以打包 ZIP 下载。 -- 百度文件夹可以生成直链清单。 -- 大文件夹解析不会因为 30 秒前端超时直接失败。 - -## 交付物 - -- Direct Link API。 -- DownloadDialog 直链下载弹窗。 -- 文件夹 ZIP 下载能力。 -- 直链清单能力。 diff --git a/docs/task/week7.md b/docs/task/week7.md deleted file mode 100644 index 07ba844..0000000 --- a/docs/task/week7.md +++ /dev/null @@ -1,70 +0,0 @@ -# Week 7 任务说明：aria2 下载任务、进度、停止与重试 - -## 本周定位 - -本周完成服务端下载任务闭环。OpenBridge 负责把 OpenList 文件解析为直链，再提交给运行在服务端电脑上的 aria2，并持续同步任务状态。 - -## 本周目标 - -- 支持创建 aria2 下载任务。 -- 保存任务与 aria2 GID 映射。 -- 支持任务列表、任务详情和状态筛选。 -- 支持每秒刷新活跃任务状态。 -- 支持进度条、下载速度和预测进度。 -- 支持停止单个任务和批量停止任务。 -- 支持失败或手动停止任务重试。 -- 支持打开已下载文件、打开所在文件夹和删除本地文件。 - -## 任务拆分 - -### 后端 - -- 封装 aria2 JSON-RPC Client。 -- 实现 `POST /api/v1/download/tasks`。 -- 实现 `GET /api/v1/download/tasks/:id`。 -- 实现 `GET /api/v1/download/aria2-status`。 -- 实现 `POST /api/v1/download/tasks/:id/stop`。 -- 实现 `POST /api/v1/download/tasks/stop`。 -- 实现 `POST /api/v1/download/tasks/:id/retry`。 -- 实现 `POST /api/v1/download/tasks/:id/open`。 -- 实现 `POST /api/v1/download/tasks/:id/open-location`。 -- 实现 `POST /api/v1/download/tasks/:id/delete-file`。 -- 任务实体保存 `Progress`、`CompletedLength`、`TotalLength`、`DownloadSpeed`、`RetryCount` 等字段。 -- 修复特殊文件名打开所在文件夹失败问题。 -- 删除本地文件时保留任务记录，并将状态更新为 `deleted`。 - -### 前端 - -- 下载任务页支持创建任务。 -- 源路径支持 OpenList 文件选择器。 -- 目标目录支持本机目录选择。 -- 任务列表支持筛选：全部、等待中、下载中、暂停、停止、文件已删除、失败、完成。 -- 任务列表支持排序和多选。 -- 任务行展示进度条、下载速度、已下载大小和总大小。 -- 任务行支持停止、删除文件、清除记录、重试、打开文件、打开所在文件夹。 -- 任务详情展示完整字段和操作按钮。 -- 存在活跃任务时默认每秒刷新。 - -### 状态规则 - -- 等待中、下载中、暂停中任务可以停止。 -- 失败和已停止任务可以重试。 -- 已完成、已停止和失败任务可以删除本地文件。 -- 清除记录不删除本地文件。 - -## 验收标准 - -- 从 OpenList 页面和任务页面都能创建 aria2 下载任务。 -- 任务进度、速度和状态能持续更新。 -- 停止任务后可重试。 -- 失败任务可重试。 -- 已完成任务可打开文件或所在文件夹。 -- 删除文件后任务记录仍存在且状态为文件已删除。 -- 批量停止能返回成功列表和失败列表。 - -## 交付物 - -- aria2 Client。 -- DownloadTask API。 -- 下载任务页面。 -- 任务状态同步逻辑。 diff --git a/docs/task/week8.md b/docs/task/week8.md deleted file mode 100644 index b8b53c8..0000000 --- a/docs/task/week8.md +++ /dev/null @@ -1,65 +0,0 @@ -# Week 8 任务说明：WebDAV Mount 代理与 rclone 挂载配置 - -## 本周定位 - -本周完成本地盘符挂载链路。OpenBridge 通过 WebDAV 代理复用 OpenList 文件能力，同时用 OpenBridge Mount 层配额改写客户端看到的容量，再通过 rclone 管理本地挂载。 - -## 本周目标 - -- 支持按 Mount 暴露 WebDAV 根。 -- WebDAV 文件能力复用 OpenList。 -- WebDAV 容量展示使用 OpenBridge Mount 配额。 -- 支持 rclone 配置保存、写入、挂载、停止挂载和删除。 -- 支持普通、Union、Combine 三种挂载方式。 -- 支持 rclone 路径从设置页保存到 `.env`。 -- 修复 OpenList 端口更换后 rclone 仍引用旧配置的问题。 - -## 任务拆分 - -### WebDAV 代理 - -- 实现 `/api/v1/webdav/mounts/:id`。 -- 根据 Mount ID 找到对应 `mount_path`。 -- 将文件操作代理到 `{OPENLIST_BASE_URL}/dav{mount.mount_path}`。 -- 透传客户端 Authorization 给 OpenList。 -- 改写 `PROPFIND` 中的 `href`、`Location`、`Content-Location`。 -- 改写 `quota-used-bytes` 和 `quota-available-bytes`。 -- 支持常见 WebDAV 方法：`OPTIONS`、`PROPFIND`、`GET`、`HEAD`、`PUT`、`DELETE`、`MKCOL`、`MOVE`、`COPY`。 - -### rclone 后端 - -- 定义 RcloneProfile 实体。 -- RcloneProfile 按 OpenList Base URL 隔离。 -- 保存配置名、挂载方式、Mount IDs、用户名、暗文密码和目标路径。 -- 实现配置列表、新增、编辑、删除。 -- 实现写入 rclone 配置。 -- 实现启动 `rclone mount`。 -- 实现停止对应挂载进程。 -- Mount 被删除后，旧 rclone 配置需要刷新状态或阻止继续挂载。 - -### 前端 - -- 新增 Rclone 页面。 -- 新增配置弹窗。 -- 支持选择 Mount。 -- 支持普通、Union、Combine 三种模式。 -- 支持目标盘符或本地目录输入。 -- 支持本机路径选择器。 -- 配置卡片展示写入、挂载、停止挂载、删除和复制命令。 - -## 验收标准 - -- 单个 Mount 可以通过 WebDAV 地址访问。 -- rclone 可把 Mount 挂载为本地盘符。 -- 容量展示尽量贴近 OpenBridge Mount 配额。 -- Union/Combine 配置能保留多个 Mount 的识别信息。 -- 停止挂载后本地盘符释放。 -- 删除配置后 rclone 中旧配置不继续残留为可用状态。 -- 更换 OpenList 端口后旧源 rclone 配置不会串到新源。 - -## 交付物 - -- WebDAV Mount 代理。 -- Rclone Profile API。 -- Rclone 配置页面。 -- WebDAV Mount 使用说明。 diff --git a/docs/task/week9.md b/docs/task/week9.md deleted file mode 100644 index 28eb065..0000000 --- a/docs/task/week9.md +++ /dev/null @@ -1,70 +0,0 @@ -# Week 9 任务说明：设置中心、主机资源、性能与界面体验 - -## 本周定位 - -本周完成控制台的运行时管理能力。目标是让用户不再手动改命令和配置文件，而是在前端完成 OpenList、aria2、rclone、缓存、登录策略和服务控制配置。 - -## 本周目标 - -- 设置页拆分为清晰的配置卡片。 -- 支持 aria2 RPC、aria2 路径和自动启动。 -- 支持 rclone 路径保存。 -- 支持 OpenList Base URL 保存并触发重新登录。 -- 支持本地路径和文件选择器。 -- 支持重启和退出 OpenBridge。 -- 支持启动自动打开浏览器。 -- 支持主机资源和带宽监控。 -- 优化前端动画、主题和响应式布局。 - -## 任务拆分 - -### 后端设置 - -- 实现 `GET /api/v1/settings`。 -- 实现 `PUT /api/v1/settings/openlist`。 -- 实现 `PUT /api/v1/settings/aria2`。 -- 实现 `PUT /api/v1/settings/rclone`。 -- 实现 `PUT /api/v1/settings/session`。 -- 实现 `PUT /api/v1/settings/app`。 -- 实现 `PUT /api/v1/settings/filetree`。 -- 设置写入 `.env`，并更新运行时配置。 -- 设置返回 `app_version`，前端底部显示 `OpenBridge vX.X`。 - -### 系统能力 - -- 实现 `POST /api/v1/system/pick-path`。 -- 实现 `GET /api/v1/system/metrics`。 -- 实现 `POST /api/v1/system/restart`。 -- 实现 `POST /api/v1/system/exit`。 -- 主机资源展示整机 CPU、内存、磁盘和 OpenBridge 进程占用。 -- 带宽展示上行、下行、OpenBridge、OpenList、aria2 和 rclone 相关指标。 -- 服务启动时根据配置自动打开浏览器。 -- 服务启动时根据配置自动拉起 aria2。 - -### 前端体验 - -- 设置页分为用户信息、aria2、默认下载目录、其他设置、服务控制、FILETREE、Rclone、OpenList、重置用户数据。 -- rclone 设置单独成框。 -- aria2 路径、自动启动、rclone 路径能正确保存。 -- 默认下载目录和路径输入均支持文件或目录选择器。 -- 仪表盘展示总空间、Provider 用量、主机资源、系统健康和快捷操作。 -- 顶部栏展示实时上下行速度。 -- 支持用户选择是否开启动画效果。 -- 修复仪表盘、服务商、配额页面大面积空白和黑夜模式可读性问题。 - -## 验收标准 - -- 设置页保存后重启仍生效。 -- aria2 能自动启动。 -- rclone 路径能写入 `.env` 并用于 rclone 操作。 -- 点击重启服务和退出服务行为明确。 -- 仪表盘资源占用每秒刷新且无明显卡顿。 -- 前端在桌面和移动端都能正常渲染。 - -## 交付物 - -- Settings API。 -- System API。 -- 设置页面。 -- 仪表盘和顶部栏指标。 -- 本机路径选择器。 diff --git a/docs/user_manual.md b/docs/user_manual.md index fc0516f..9d387d0 100644 --- a/docs/user_manual.md +++ b/docs/user_manual.md @@ -1,12 +1,5 @@ # OpenBridge 用户手册与 API 文档 -| 完成人 | 任务 | -| --- | --- | -| 崔乘玮 | 规划框架，完成 Provider 和 Mount 部分，合并文档 | -| 宋丞罡 | 完成主界面部分 | -| 郑源宇 | 完成 rclone 和下载任务部分 | -| 卢宇扬 | 完成 API 文档部分和 debug 部分 | -| 陈志睿 | 完成仪表盘部分 | -| 周子滨 | 完成 debug 和截图部分 | + 本文档说明 OpenBridge 的各项前端功能、常见使用方式和后端 API，并已按章节插入截图；少数不适合展示的步骤以文字说明为主。 diff --git "a/docs/\345\233\242\351\230\237\345\274\200\345\217\221.md" "b/docs/\345\233\242\351\230\237\345\274\200\345\217\221.md" deleted file mode 100644 index 4ee4d4f..0000000 --- "a/docs/\345\233\242\351\230\237\345\274\200\345\217\221.md" +++ /dev/null @@ -1,341 +0,0 @@ -# OpenBridge 团队开发规范 - -## 1. 文档目的 - -为保证 OpenBridge 项目开发过程中的协作效率、代码质量和版本管理规范，团队统一采用本规范进行开发、提交、合并、测试和文档维护。 - -本规范适用于项目所有成员。 - -> 本规范在项目开发过程中可根据实际情况进行适当调整，并由项目负责人统一维护。 - ---- - -## 2. 项目协作原则 - -* 所有人都在统一 GitHub 仓库中协作开发 -* 不允许直接在主分支上随意修改代码 -* 每位成员在自己的功能分支上开发 -* 所有代码合并必须通过 PR（Pull Request）进行 -* 提交信息、分支命名、目录结构尽量统一 -* 每次开发都要保证“自己写的部分至少能运行或说明当前状态” -* 发现问题及时记录到 Issue 或会议纪要中 - ---- - -## 3. 仓库与分支管理规范 - -### 3.1 仓库说明 - -本项目采用单仓库（Monorepo）结构，统一管理后端、前端和文档资源。 - -```text -openbridge/ -├── backend/ # Go 后端 -├── frontend/ # Vue 前端 -├── docs/ # 项目文档 -├── scripts/ # 启动或辅助脚本 -└── README.md -``` - ---- - -### 3.2 分支说明 - -* `main`：稳定分支，用于保存最终可展示版本 -* `dev`：开发主分支，用于集成日常开发成果 -* `feature/*`：功能开发分支 -* `fix/*`：问题修复分支 -* `docs/*`：文档修改分支 - ---- - -### 3.3 分支使用规则 - -#### main 分支 - -* 禁止直接提交代码 -* 只允许通过 PR 从 dev 合并进入 -* 用于保存最终稳定版本 - -#### dev 分支 - -* 作为团队主开发分支 -* 所有功能开发完成后合并到 dev -* 联调与测试基于 dev - -#### feature 分支 - -示例： - -```text -feature/backend-init -feature/frontend-dashboard -feature/redirect-resolver -feature/quota-provider -``` - -#### fix 分支 - -```text -fix/login-bug -fix/api-error -``` - -#### docs 分支 - -```text -docs/readme-update -docs/meeting-notes -``` - ---- - -### 3.4 分支保护策略（重要） - -#### main 分支保护 - -* 禁止直接 push -* 必须通过 PR 合并 -* 至少 1 人 Review - -#### dev 分支建议 - -* 推荐通过 PR 合并 -* 合并前保证代码可运行 - ---- - -## 4. 开发流程规范 - -### 4.1 基本流程 - -1. 切换到 dev 并拉取最新代码 -2. 创建 feature 分支 -3. 编写代码 -4. 本地测试 -5. 提交并 push -6. 创建 PR -7. Review -8. 合并 - ---- - -### 4.2 标准命令 - -```bash -git checkout dev -git pull origin dev -git checkout -b feature/xxx - -git add . -git commit -m "feat: xxx" -git push -u origin feature/xxx -``` - ---- - -### 4.3 合并规则 - -* 必须通过 PR -* PR 标题清晰 -* 合并前无冲突 -* 合并后删除分支 - ---- - -## 5. 提交规范 - -### 5.1 提交格式 - -```text -类型: 描述 -``` - -### 5.2 类型说明 - -* feat：新功能 -* fix：修复 -* docs：文档 -* refactor：重构 -* style：格式 -* test：测试 -* chore：杂项 - -### 5.3 示例 - -```text -feat: 初始化后端服务 -fix: 修复下载接口错误 -docs: 更新README -``` - ---- - -## 6. Pull Request 规范 - -### 6.1 PR 标题 - -```text -[模块] 功能说明 -``` - -示例： - -```text -[backend] 初始化服务 -[frontend] 添加仪表盘 -``` - ---- - -### 6.2 PR 内容模板 - -```md -## 本次修改 -- xxx - -## 当前状态 -- 已测试 - -## 注意事项 -- xxx -``` - ---- - -## 7. 代码规范 - -### 7.1 通用 - -* 命名清晰 -* 避免重复代码 -* 重要逻辑加注释 -* 配置与业务分离 -* 不提交敏感信息 - ---- - -### 7.2 后端规范（Go） - -* 统一 JSON 返回 -* 错误处理明确 -* 模块分层 - -```text -backend/ -├── cmd/ -├── internal/ -│ ├── adapter/ -│ ├── resolver/ -│ ├── quota/ -│ ├── provider/ -│ └── config/ -``` - ---- - -### 7.3 前端规范（Vue） - -* 组件复用 -* API统一封装 -* 错误提示清晰 - ---- - -### 7.4 接口约定规范（新增） - -#### 统一返回格式 - -```json -{ - "code": 0, - "message": "success", - "data": {} -} -``` - -#### 状态码 - -| code | 含义 | -| ---- | ---- | -| 0 | 成功 | -| 1 | 一般错误 | -| 2 | 参数错误 | -| 3 | 权限错误 | - ---- - -## 8. 文档规范 - -### 必备文档 - -* README.md -* docs/api.md -* docs/architecture.md -* docs/meeting-notes/ - ---- - -## 9. Issue 管理 - -示例： - -```text -[Backend] 初始化服务 -[Bug] 下载失败 -``` - ---- - -## 10. 环境规范 - -统一： - -* Go版本 -* Node版本 -* npm版本 - ---- - -## 11. 测试规范 - -* 提交前自测 -* 联调前统一接口 -* Bug需记录 - ---- - -## 12. 安全规范 - -* 不上传 token -* 不泄露 cookie -* 不提交敏感信息 - ---- - -## 13. 团队沟通 - -* 重要决策必须记录 -* 每周至少一次会议 - ---- - -## 14. 项目说明 - -本项目以“可运行 + 可演示 + 可答辩”为目标，强调工程规范与团队协作。 - ---- - -## 15. 简版约定（必须遵守） - -* 不直接改 main -* 开发基于 dev -* 使用 feature 分支 -* 必须 PR 合并 -* commit 规范 -* 写完自测 -* 接口变更需沟通 -* 不提交敏感信息 -* 出问题及时沟通 - ---- diff --git "a/docs/\346\226\207\346\241\243\346\241\206\346\236\266.md" "b/docs/\346\226\207\346\241\243\346\241\206\346\236\266.md" deleted file mode 100644 index d7b2d2b..0000000 --- "a/docs/\346\226\207\346\241\243\346\241\206\346\236\266.md" +++ /dev/null @@ -1,37 +0,0 @@ -## 我们可能要做的文档 - -根据课件和我了解的信息，我们要完成的文档大概分为: - -- 开发者文档 -- 用户文档（或者用户手册） -- 项目运维文档 - -#### 1. 开发者文档 - -开发者文档主要是给写代码的人看的，实际上就是工作留痕，记录我们用到的环境、技术等。 -例如，要配哪些环境（比如我们用的go是1.25.8），怎么配环境，以及项目的流程架构图。 - -环境技术这些，我会根据你们的讨论来写，倒是不用太操心。架构图就看你们大概能定下来前后端的细节没有。 -> 我提议我们参考鸿蒙的开发者手册: [text](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-dev-guide) - -#### 2. 用户手册 - -用户手册比较好写，照着UI手把手教就行了。我还打算把使用OpenList的教程写进去，不然有点单薄了，如果老师不深究，稍微蹭一点OpenList的招牌，我觉得是OK的。 - -主要内容包括：OpenList的下载和使用，UI界面各个按钮的功能，怎么注册登录等等。 -- 这一部分打算写一点FAQ，所以你们测试UI的时候碰到什么奇怪的bug记得记录一下，我写进去。到时候问起软件测试，我们也不至于没东西回答。 - -#### 3. 项目运维 - -主要是变更日志，这一部分需要你们帮忙多一点，即你们觉得有版本改动（demo也可以算）的时候记得说一声，前后端都是。 -有报错以及怎么解决（尤其是后端），也记录在维护手册里面。 - -#### 4. 总结补充 - -总的来说，大部分内容不用操心，拜托各位留心的地方就是: -1. 版本更新时，记录一下 更新/修复了什么内容; -2. 配环境、API接口的说明; -3. 报错信息和解决办法; -4. 偶尔回答一下某个写文档的技术栈为空的猪B的询问; - -以及在框架没定下来的时候我可以去前端帮忙。 \ No newline at end of file diff --git "a/docs/\351\231\204\344\273\266 7.\347\254\254 12 \347\273\204-OpenBridge \347\263\273\347\273\237-\344\272\247\345\223\201\344\275\277\347\224\250\350\257\264\346\230\216\344\271\246.pdf" "b/docs/\351\231\204\344\273\266 7.\347\254\254 12 \347\273\204-OpenBridge \347\263\273\347\273\237-\344\272\247\345\223\201\344\275\277\347\224\250\350\257\264\346\230\216\344\271\246.pdf" deleted file mode 100644 index 2042315..0000000 Binary files "a/docs/\351\231\204\344\273\266 7.\347\254\254 12 \347\273\204-OpenBridge \347\263\273\347\273\237-\344\272\247\345\223\201\344\275\277\347\224\250\350\257\264\346\230\216\344\271\246.pdf" and /dev/null differ diff --git "a/docs/\351\231\204\344\273\266 9.\347\254\254 12 \347\273\204-OpenBridge \347\263\273\347\273\237-\344\272\247\345\223\201\346\274\224\347\244\272 PPT.pptx" "b/docs/\351\231\204\344\273\266 9.\347\254\254 12 \347\273\204-OpenBridge \347\263\273\347\273\237-\344\272\247\345\223\201\346\274\224\347\244\272 PPT.pptx" deleted file mode 100644 index 19f5fe1..0000000 Binary files "a/docs/\351\231\204\344\273\266 9.\347\254\254 12 \347\273\204-OpenBridge \347\263\273\347\273\237-\344\272\247\345\223\201\346\274\224\347\244\272 PPT.pptx" and /dev/null differ diff --git "a/docs/\351\241\271\347\233\256\346\236\266\346\236\204\346\226\207\346\241\243.md" "b/docs/\351\241\271\347\233\256\346\236\266\346\236\204\346\226\207\346\241\243.md" deleted file mode 100644 index fded09d..0000000 --- "a/docs/\351\241\271\347\233\256\346\236\266\346\236\204\346\226\207\346\241\243.md" +++ /dev/null @@ -1,962 +0,0 @@ -# OpenBridge 项目架构文档 - -> **基于 OpenList 的直链下载编排与容量适配系统** -> -> 更新时间：2026-05-12 -> 项目状态：开发中（前后端已完成基础对接） - ---- - -## 📋 目录 - -- [一、项目概述](#一项目概述) -- [二、技术栈](#二技术栈) -- [三、整体架构](#三整体架构) -- [四、后端架构](#四后端架构) -- [五、前端架构](#五前端架构) -- [六、API 设计](#六api-设计) -- [七、数据模型](#七数据模型) -- [八、开发状态](#八开发状态) -- [九、部署架构](#九部署架构) - ---- - -## 一、项目概述 - -### 1.1 项目定位 - -OpenBridge 是一个基于 OpenList 的直链下载编排与容量适配系统，核心作用是： - -- **增强 OpenList**：不替代 OpenList，仅做功能增强 -- **Provider 扩展层**：为 OpenList Storage 提供增强视图 -- **下载编排**：通过 aria2 实现高效下载任务管理 -- **容量适配**：统一抽象不同网盘的容量查询与管理 - -### 1.2 核心能力 - -1. **二次认证**：解决 quota 与下载认证不一致问题 -2. **下载链路解析**：处理 302 跳转 + header 注入 -3. **aria2 任务映射**：将 OpenList 资源映射为 aria2 下载任务 -4. **Quota 统一抽象**：跨网盘统一容量查询与监控 - ---- - -## 二、技术栈 - -### 2.1 后端技术栈 - -| 技术 | 版本 | 用途 | -|------|------|------| -| **Go** | 1.25.8 | 核心后端语言 | -| **Gin** | 1.12.0 | Web 框架 | -| **GORM** | 1.31.0 | ORM 框架 | -| **SQLite** | 1.6.0 | 数据库 | -| **Zap** | 1.27.1 | 日志框架 | -| **godotenv** | 1.5.1 | 环境变量管理 | - -### 2.2 前端技术栈 - -| 技术 | 版本 | 用途 | -|------|------|------| -| **Vue 3** | 3.5.13 | 前端框架 | -| **TypeScript** | 5.8.3 | 类型系统 | -| **Vite** | 6.3.5 | 构建工具 | -| **Vue Router** | 4.5.1 | 路由管理 | -| **Pinia** | 3.0.3 | 状态管理 | -| **Axios** | 1.15.0 | HTTP 客户端 | - -### 2.3 外部依赖 - -- **OpenList**：网盘聚合服务 -- **aria2**：下载引擎 - ---- - -## 三、整体架构 - -### 3.1 系统架构图 - -``` -┌─────────────────────────────────────────────────────────────┐ -│ 用户浏览器 │ -└──────────────────────┬──────────────────────────────────────┘ - │ HTTP/WebSocket -┌──────────────────────▼──────────────────────────────────────┐ -│ Frontend (Vue 3) │ -│ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ 门户页 │ │ 控制台 │ │ 管理页面 │ │ -│ │ (Portal) │ │ (Dashboard) │ │ (CRUD) │ │ -│ └─────────────┘ └──────────────┘ └──────────────┘ │ -└──────────────────────┬──────────────────────────────────────┘ - │ REST API (/api/v1) -┌──────────────────────▼──────────────────────────────────────┐ -│ Backend (Go + Gin) │ -│ ┌─────────────────────────────────────────────────────┐ │ -│ │ Handler Layer (HTTP) │ │ -│ │ Auth / Provider / Quota / Token / Download / ... │ │ -│ └──────────────────────┬──────────────────────────────┘ │ -│ ┌──────────────────────▼──────────────────────────────┐ │ -│ │ UseCase Layer (业务逻辑) │ │ -│ │ ProviderUseCase / QuotaUseCase / TokenUseCase │ │ -│ └──────────────────────┬──────────────────────────────┘ │ -│ ┌──────────────────────▼──────────────────────────────┐ │ -│ │ Domain Layer (核心领域模型) │ │ -│ │ Entity / Interface / Providers (扩展点) │ │ -│ └──────────────────────┬──────────────────────────────┘ │ -│ ┌──────────────────────▼──────────────────────────────┐ │ -│ │ Repository Layer (数据访问) │ │ -│ │ ProviderRepo / QuotaRepo / TokenRepo │ │ -│ └──────────────────────┬──────────────────────────────┘ │ -└─────────────────────────┼──────────────────────────────────┘ - │ - ┌──────────────┼──────────────┐ - │ │ │ - ┌──────▼─────┐ ┌────▼────┐ ┌──────▼──────┐ - │ SQLite DB │ │ OpenList│ │ aria2 │ - │ (本地) │ │ (外部) │ │ (外部) │ - └────────────┘ └─────────┘ └─────────────┘ -``` - -### 3.2 核心流程 - -#### 3.2.1 Provider 管理流程 - -``` -用户 → 前端 Provider 管理页面 - → POST /api/v1/providers (注册 Provider) - → Backend: ProviderHandler → ProviderUseCase → ProviderRepo - → 存储到 SQLite - → 返回 Provider ID -``` - -#### 3.2.2 容量查询流程 - -``` -用户 → 前端 Quota 页面 - → POST /api/v1/quota/query (查询容量) - → Backend: 检查缓存 → 若过期则调用 Provider 接口 - → 更新 QuotaSnapshot - → 返回容量数据 -``` - -#### 3.2.3 下载任务流程 - -``` -用户 → 选择文件 → 提交下载 - → POST /api/v1/download/tasks - → Backend: 解析链路 → 生成 aria2 任务 - → aria2 执行下载 - → 更新任务状态 -``` - ---- - -## 四、后端架构 - -### 4.1 目录结构 - -``` -backend/ -├── main.go # 程序入口 -├── go.mod # Go 模块依赖 -├── go.sum -├── openbridge.db # SQLite 数据库 -├── data/ # 数据目录（运行时数据） -└── internal/ # 内部业务代码 - ├── config/ # 配置管理 - │ └── config.go - ├── domain/ # 领域层（核心） - │ ├── entity/ # 实体定义 - │ │ ├── provider_account.go # Provider 账户实体 - │ │ ├── quota.go # 配额实体 - │ │ ├── quota_snapshot.go # 配额快照实体 - │ │ ├── token.go # Token 实体 - │ │ └── downtask.go # 下载任务实体 - │ ├── interfaces/ # 接口定义 - │ │ └── provider_interface.go # Provider 接口 - │ └── providers/ # Provider 实现（扩展点） - │ └── mock_provider.go # Mock Provider 示例 - ├── handler/ # 表现层（HTTP 处理器） - │ ├── provider_handler.go # Provider 接口处理 - │ ├── quota_handler.go # Quota 接口处理 - │ └── token_handler.go # Token 接口处理 - ├── middleware/ # 中间件 - │ ├── access_log.go # 访问日志 - │ └── request_id.go # 请求 ID - ├── repository/ # 数据访问层 - │ ├── provider_repo.go # Provider 数据访问 - │ ├── quota_repo.go # Quota 数据访问 - │ └── token_repo.go # Token 数据访问 - ├── usecase/ # 应用层（业务逻辑） - │ ├── provider_usecase.go # Provider 业务逻辑 - │ ├── quota_usecase.go # Quota 业务逻辑 - │ └── token_usecase.go # Token 业务逻辑 - ├── pkg/ # 内部公共包 - │ ├── logger/ # 日志工具 - │ │ └── logger.go - │ └── myerror/ # 错误码定义 - │ └── error_code.go - └── tool/ # 工具层 - ├── httpresult.go # HTTP 统一返回 - └── provider_register.go # Provider 注册器 -``` - -### 4.2 分层架构 - -#### 4.2.1 Handler Layer（表现层） - -**职责**： -- 处理 HTTP 请求 -- 参数验证 -- 调用 UseCase 层 -- 返回统一格式响应 - -**示例**： -```go -// provider_handler.go -func (h *ProviderHandler) ListProviders(c *gin.Context) { - providers, err := h.useCase.ListProviders() - if err != nil { - tool.ReturnError(c, myerror.ErrInternal, err.Error()) - return - } - tool.ReturnSuccess(c, providers) -} -``` - -#### 4.2.2 UseCase Layer（应用层） - -**职责**： -- 实现核心业务逻辑 -- 编排多个 Repository 操作 -- 业务规则校验 - -**示例**： -```go -// provider_usecase.go -func (uc *ProviderUseCase) CreateProvider(req *ProviderCreateRequest) error { - // 业务逻辑：验证、转换、存储 - provider := &entity.ProviderAccount{ - Name: req.Name, - Type: req.Type, - Status: "active", - } - return uc.repo.Create(provider) -} -``` - -#### 4.2.3 Domain Layer（领域层） - -**职责**： -- 定义核心实体 -- 定义业务接口 -- Provider 扩展点 - -**核心实体**： -```go -// entity/provider_account.go -type ProviderAccount struct { - ID uint `gorm:"primaryKey"` - Name string `gorm:"not null"` - Type string `gorm:"not null"` // mock/baidu/aliyun/quark - Status string `gorm:"not null"` // active/disabled/expired/error - CreatedAt time.Time - UpdatedAt time.Time -} -``` - -#### 4.2.4 Repository Layer（数据访问层） - -**职责**： -- 封装数据库操作 -- 提供 CRUD 接口 - -**示例**： -```go -// provider_repo.go -func (r *ProviderRepository) Create(provider *entity.ProviderAccount) error { - return r.db.Create(provider).Error -} -``` - -### 4.3 关键设计模式 - -#### 4.3.1 Provider 接口（策略模式） - -```go -// domain/interfaces/provider_interface.go -type Provider interface { - GetQuota() (*QuotaInfo, error) // 获取容量 - RefreshToken() error // 刷新 Token - GetDownloadURL(path string) (string, error) // 获取下载链接 - ValidateToken() error // 验证 Token -} -``` - -**扩展示例**： -```go -// domain/providers/mock_provider.go -type MockProvider struct { - account *entity.ProviderAccount -} - -func (p *MockProvider) GetQuota() (*QuotaInfo, error) { - // 模拟返回容量数据 - return &QuotaInfo{ - Total: 1099511627776, // 1TB - Used: 549755813888, // 500GB - }, nil -} -``` - -#### 4.3.2 统一错误处理 - -```go -// pkg/myerror/error_code.go -const ( - ErrSuccess = 0 - ErrInternal = 1001 - ErrInvalidParams = 1002 - ErrNotFound = 1003 - ErrUnauthorized = 1004 -) - -// tool/httpresult.go -func ReturnError(c *gin.Context, code int, msg string) { - c.JSON(http.StatusOK, gin.H{ - "code": code, - "message": msg, - "data": nil, - }) -} -``` - ---- - -## 五、前端架构 - -### 5.1 目录结构 - -``` -frontend/ -├── public/ # 静态资源 -├── src/ -│ ├── api/ # API 请求封装 -│ │ ├── provider.ts # Provider API -│ │ ├── quota.ts # Quota API -│ │ └── token.ts # Token API -│ ├── components/ # 组件 -│ │ ├── common/ # 通用组件 -│ │ │ ├── PageHeader.vue -│ │ │ ├── MetricCard.vue -│ │ │ └── StatusBadge.vue -│ │ ├── layout/ # 布局组件 -│ │ │ ├── AppShell.vue -│ │ │ ├── AppSidebar.vue -│ │ │ └── AppTopbar.vue -│ │ └── provider/ # Provider 专用组件 -│ │ └── ProviderFormDialog.vue -│ ├── mock/ # Mock 数据（已废弃） -│ ├── router/ # 路由配置 -│ │ └── index.ts -│ ├── stores/ # 状态管理 -│ │ └── console.ts -│ ├── styles/ # 全局样式 -│ │ └── index.css -│ ├── types/ # TypeScript 类型定义 -│ │ ├── common.ts -│ │ ├── provider.ts -│ │ ├── quota.ts -│ │ └── token.ts -│ ├── utils/ # 工具函数 -│ │ └── request.ts # Axios 封装 -│ ├── views/ # 页面视图 -│ │ ├── PortalView.vue # 门户页 -│ │ ├── DashboardView.vue # 仪表盘 -│ │ ├── ProviderView.vue # Provider 管理 -│ │ ├── QuotaView.vue # 容量管理 -│ │ ├── TokenView.vue # Token 管理 -│ │ ├── DownloadTasksView.vue # 下载任务 -│ │ ├── SettingsView.vue # 设置 -│ │ └── DebugView.vue # 调试 -│ ├── App.vue # 根组件 -│ ├── main.ts # 入口文件 -│ └── env.d.ts # 类型声明 -├── index.html -├── vite.config.ts # Vite 配置 -├── tsconfig.json # TypeScript 配置 -├── package.json -└── .env.development # 开发环境配置 -``` - -### 5.2 页面架构 - -#### 5.2.1 路由结构 - -```typescript -// router/index.ts -const routes = [ - { - path: '/', - name: 'portal', - component: PortalView, // 门户页（启动入口） - }, - { - path: '/dashboard', - name: 'dashboard', - component: DashboardView, // 仪表盘 - }, - { - path: '/providers', - name: 'providers', - component: ProviderView, // Provider 管理 - }, - { - path: '/quota', - name: 'quota', - component: QuotaView, // 容量管理 - }, - { - path: '/tokens', - name: 'tokens', - component: TokenView, // Token 管理 - }, - { - path: '/tasks', - name: 'tasks', - component: DownloadTasksView, // 下载任务 - }, - { - path: '/settings', - name: 'settings', - component: SettingsView, // 设置 - }, - { - path: '/debug', - name: 'debug', - component: DebugView, // 调试 - }, -] -``` - -#### 5.2.2 页面功能 - -| 页面 | 功能 | 状态 | -|------|------|------| -| **PortalView** | 门户页，展示品牌与连接状态 | ✅ 已完成 | -| **DashboardView** | 仪表盘，系统总览 | 🚧 占位中 | -| **ProviderView** | Provider 增删改查 | ✅ 已完成 | -| **QuotaView** | 容量查询与同步 | ✅ 已完成 | -| **TokenView** | Token 上传管理 | ✅ 已完成 | -| **DownloadTasksView** | 下载任务列表 | 🚧 占位中 | -| **SettingsView** | 系统设置 | 🚧 占位中 | -| **DebugView** | 调试工具 | 🚧 占位中 | - -### 5.3 状态管理（Pinia） - -```typescript -// stores/console.ts -export const useConsoleStore = defineStore('console', { - state: () => ({ - providers: [] as Provider[], - quotaData: null as QuotaInfo | null, - isLoading: false, - }), - actions: { - async fetchProviders() { - const data = await getProviders() - this.providers = data - }, - async syncQuota(providerId: number) { - const data = await syncProviderQuota(providerId) - this.quotaData = data - }, - }, -}) -``` - -### 5.4 API 请求封装 - -#### 5.4.1 Axios 配置 - -```typescript -// utils/request.ts -const request = axios.create({ - baseURL: import.meta.env.VITE_API_BASE_URL || '/api/v1', - timeout: 10000, -}) - -// 请求拦截器 -request.interceptors.request.use(config => { - // 添加 token 等 - return config -}) - -// 响应拦截器 -request.interceptors.response.use( - response => { - const { code, data, message } = response.data - if (code !== 0) { - console.error('API Error:', message) - return Promise.reject(new Error(message)) - } - return data - }, - error => Promise.reject(error) -) -``` - -#### 5.4.2 API 模块 - -```typescript -// api/provider.ts -export async function getProviders(): Promise { - return request.get('/providers') -} - -export async function createProvider(data: ProviderCreateRequest): Promise { - return request.post('/providers', data) -} - -export async function updateProvider(id: number, data: ProviderUpdateRequest): Promise { - return request.put(`/providers/${id}`, data) -} - -export async function deleteProvider(id: number): Promise { - return request.delete(`/providers/${id}`) -} -``` - -### 5.5 跨域处理 - -```typescript -// vite.config.ts -export default defineConfig({ - server: { - proxy: { - '/api': { - target: 'http://localhost:8080', - changeOrigin: true, - }, - }, - }, -}) -``` - ---- - -## 六、API 设计 - -### 6.1 API 基础规范 - -**基础路径**：`/api/v1` - -**统一返回格式**： - -```json -{ - "code": 0, - "message": "ok", - "data": {} -} -``` - -**错误码规范**： - -| 错误码 | 含义 | -|-------|------| -| 0 | 成功 | -| 1001 | 内部错误 | -| 1002 | 参数错误 | -| 1003 | 资源不存在 | -| 1004 | 未授权 | - -### 6.2 核心 API 接口 - -#### 6.2.1 Provider API - -| 方法 | 路径 | 功能 | 状态 | -|------|------|------|------| -| GET | `/providers` | 获取 Provider 列表 | ✅ | -| POST | `/providers` | 创建 Provider | ✅ | -| GET | `/providers/:id` | 获取 Provider 详情 | ✅ | -| PUT | `/providers/:id` | 更新 Provider | ✅ | -| DELETE | `/providers/:id` | 删除 Provider | ✅ | - -**创建 Provider 示例**： - -```json -POST /api/v1/providers -{ - "name": "百度网盘账号1", - "type": "baidu" -} - -Response: -{ - "code": 0, - "message": "ok", - "data": { - "id": 1, - "name": "百度网盘账号1", - "type": "baidu", - "status": "active", - "created_at": "2026-04-19T10:00:00Z" - } -} -``` - -#### 6.2.2 Quota API - -| 方法 | 路径 | 功能 | 状态 | -|------|------|------|------| -| POST | `/quota/query` | 查询容量（不触发同步） | ✅ | -| POST | `/quota/providers/:id/refresh` | 刷新 Provider 容量 | ✅ | -| GET | `/quota/providers/:id` | 获取 Provider 容量状态 | ✅ | - -**容量查询示例**： - -```json -POST /api/v1/quota/query -{ - "provider_id": 1 -} - -Response: -{ - "code": 0, - "data": { - "total": 1099511627776, // 1TB - "used": 549755813888, // 500GB - "available": 549755813888, // 500GB - "usage_percent": 50.0, - "updated_at": "2026-04-19T10:30:00Z" - } -} -``` - -#### 6.2.3 Token API - -| 方法 | 路径 | 功能 | 状态 | -|------|------|------|------| -| POST | `/tokens` | 上传 Token | ✅ | -| GET | `/tokens` | 获取 Token 列表 | ✅ | -| DELETE | `/tokens/:id` | 删除 Token | ✅ | - -**上传 Token 示例**： - -```json -POST /api/v1/tokens -{ - "type": "baidu", - "access_token": "xxx", - "refresh_token": "yyy", - "expires_in": 7200 -} - -Response: -{ - "code": 0, - "message": "ok", - "data": { - "id": 1, - "type": "baidu", - "status": "active", - "expires_at": "2026-04-19T12:00:00Z" - } -} -``` - ---- - -## 七、数据模型 - -### 7.1 核心实体 - -#### 7.1.1 ProviderAccount（Provider 账户） - -```go -type ProviderAccount struct { - ID uint `gorm:"primaryKey"` - Name string `gorm:"not null"` // Provider 名称 - Type string `gorm:"not null"` // 类型：mock/baidu/aliyun/quark - Status string `gorm:"not null"` // 状态：active/disabled/expired/error - CreatedAt time.Time - UpdatedAt time.Time -} -``` - -#### 7.1.2 Token（访问令牌） - -```go -type Token struct { - ID uint `gorm:"primaryKey"` - Type string `gorm:"not null"` // 网盘类型 - AccessToken string `gorm:"not null"` - RefreshToken string - ExpiresAt time.Time - Status string `gorm:"not null"` // active/expired - CreatedAt time.Time - UpdatedAt time.Time -} -``` - -#### 7.1.3 Quota（配额） - -```go -type Quota struct { - ID uint `gorm:"primaryKey"` - ProviderID uint `gorm:"not null"` // 关联 Provider - Total int64 `gorm:"not null"` // 总容量（字节） - Used int64 `gorm:"not null"` // 已用容量（字节） - Available int64 `gorm:"not null"` // 可用容量（字节） - UpdatedAt time.Time -} -``` - -#### 7.1.4 QuotaSnapshot（配额快照） - -```go -type QuotaSnapshot struct { - ID uint `gorm:"primaryKey"` - ProviderID uint `gorm:"not null"` - Total int64 `gorm:"not null"` - Used int64 `gorm:"not null"` - Available int64 `gorm:"not null"` - CreatedAt time.Time // 快照时间 -} -``` - -#### 7.1.5 DownloadTask（下载任务） - -```go -type DownloadTask struct { - ID uint `gorm:"primaryKey"` - Name string `gorm:"not null"` // 文件名 - ProviderID uint `gorm:"not null"` // 来源 Provider - SourcePath string `gorm:"not null"` // 源路径 - TargetPath string `gorm:"not null"` // 目标路径 - Status string `gorm:"not null"` // pending/running/completed/failed - Progress float64 `gorm:"default:0"` // 进度百分比 - Aria2GID string // aria2 任务 ID - CreatedAt time.Time - UpdatedAt time.Time -} -``` - -### 7.2 实体关系图 - -``` -┌─────────────────┐ -│ ProviderAccount │ -│ - id │ -│ - name │ -│ - type │ -│ - status │ -└────────┬────────┘ - │ - │ 1:1 - │ -┌────────▼────────┐ ┌──────────────┐ -│ Quota │ │ Token │ -│ - provider_id │ │ - type │ -│ - total │ │ - access_token -│ - used │ │ - refresh_token -└────────┬────────┘ └──────────────┘ - │ - │ 1:N - │ -┌────────▼────────┐ ┌──────────────┐ -│ QuotaSnapshot │ │ DownloadTask │ -│ - provider_id │ │ - provider_id -│ - total │ │ - name │ -│ - used │ │ - status │ -│ - created_at │ │ - progress │ -└─────────────────┘ └──────────────┘ -``` - ---- - -## 八、开发状态 - -### 8.1 已完成功能 - -#### 后端 -- ✅ 基础框架搭建（Gin + GORM + SQLite） -- ✅ 分层架构实现（Handler / UseCase / Repository） -- ✅ Provider 管理接口（增删改查） -- ✅ Quota 管理接口（查询、同步） -- ✅ Token 管理接口（上传、查询） -- ✅ 统一错误处理 -- ✅ 日志中间件 -- ✅ Mock Provider 示例 - -#### 前端 -- ✅ Vue 3 + TypeScript 工程化搭建 -- ✅ 门户页设计与实现 -- ✅ 控制台布局（Sidebar + Topbar） -- ✅ Provider 管理页面（完整 CRUD） -- ✅ Quota 管理页面（查询 + 同步） -- ✅ Token 管理页面（上传） -- ✅ Axios 请求封装 -- ✅ Vite 代理配置 -- ✅ 状态管理（Pinia） - -### 8.2 进行中功能 - -- 🚧 Dashboard 页面（系统总览） -- 🚧 OpenList 页面（文件浏览） -- 🚧 Download Tasks 页面（任务管理） -- 🚧 Settings 页面（系统配置） -- 🚧 Debug 页面（调试工具） - -### 8.3 待开发功能 - -- ⏳ aria2 集成（下载引擎） -- ⏳ OpenList API 对接 -- ⏳ Provider 实现（百度网盘、阿里云盘、夸克网盘） -- ⏳ 下载链路解析（302 跳转处理） -- ⏳ WebSocket 实时推送 -- ⏳ 用户认证与权限管理 -- ⏳ 日志查询与分析 - ---- - -## 九、部署架构 - -### 9.1 开发环境 - -``` -┌─────────────────┐ ┌─────────────────┐ -│ Frontend Dev │ │ Backend Dev │ -│ localhost:5173 │─────▶│ localhost:8080 │ -│ (Vite) │ │ (Go + Gin) │ -└─────────────────┘ └─────────────────┘ - │ - ┌────────┼────────┐ - │ │ │ - ┌──────▼──┐ ┌───▼───┐ ┌─▼────┐ - │ SQLite │ │OpenList│ aria2 │ - └─────────┘ └────────┘ └──────┘ -``` - -**启动方式**： - -```bash -# 后端 -cd backend -go run main.go - -# 前端 -cd frontend -npm run dev -``` - -### 9.2 生产环境（建议） - -``` - ┌─────────────┐ - │ Nginx │ - │ (反向代理) │ - └──────┬──────┘ - │ - ┌─────────────┴─────────────┐ - │ │ -┌───────▼────────┐ ┌────────▼─────────┐ -│ Frontend │ │ Backend │ -│ (Static) │ │ (Go Binary) │ -│ /usr/share/ │ │ /opt/openbridge│ -│ nginx/html │ └──────────────────┘ -└────────────────┘ │ - ┌────────┼────────┐ - │ │ │ - ┌──────▼──┐ ┌───▼───┐ ┌─▼────┐ - │ SQLite │ │OpenList│ aria2 │ - └─────────┘ └────────┘ └──────┘ -``` - -**部署建议**： - -1. **前端**：打包为静态文件，使用 Nginx 托管 -2. **后端**：编译为二进制，使用 systemd 管理 -3. **数据库**：SQLite 适合单机部署，生产环境可考虑 PostgreSQL -4. **反向代理**：Nginx 处理静态文件 + API 转发 - ---- - -## 十、开发规范 - -### 10.1 代码规范 - -#### 后端 Go 规范 -- 遵循 Go 官方代码风格 -- 使用 `gofmt` 格式化代码 -- 错误处理不允许省略 -- 导出函数必须添加注释 - -#### 前端 TypeScript 规范 -- 使用 TypeScript 严格模式 -- 组件使用 `