feat(mobile, orpheus): download

[roitium]

Summary by CodeRabbit

新增功能

• 下载设置页面 - 新增专属设置页面，用户可自定义配置最大并发下载数量
• 下载菜单项 - 在设置中新增"下载"选项，快速访问下载相关设置
• 下载管理增强 - 支持重试失败的下载任务和恢复暂停中的下载
• 批量重试功能 - 新增"重试失败"按钮，可一键重试所有失败的下载任务

[safedep]

SafeDep Report Summary

No dependency changes detected. Nothing to scan.

View complete scan results →

_{This report is generated by SafeDep Github App}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
bbplayer-docs	Building	Preview, Comment	May 2, 2026 5:57am

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: edf76869-3df9-4af5-9584-2e9bfe88d114

📥 Commits

Reviewing files that changed from the base of the PR and between d68a1c8 and 42d3f7c.

📒 Files selected for processing (14)

• apps/mobile/src/app/(tabs)/settings/index.tsx
• apps/mobile/src/app/_layout.tsx
• apps/mobile/src/app/download.tsx
• apps/mobile/src/app/settings/download.tsx
• apps/mobile/src/features/downloads/DownloadHeader.tsx
• apps/mobile/src/features/downloads/DownloadTaskItem.tsx
• apps/mobile/src/hooks/stores/useAppStore.ts
• apps/mobile/src/types/core/appStore.ts
• packages/orpheus/android/build.gradle
• packages/orpheus/android/src/main/java/expo/modules/orpheus/ExpoOrpheusModule.kt
• packages/orpheus/android/src/main/java/expo/modules/orpheus/util/DownloadUtil.kt
• packages/orpheus/ios/ExpoOrpheusModule.swift
• packages/orpheus/ios/OrpheusDownloadManager.swift
• packages/orpheus/src/ExpoOrpheusModule.ts

---

Walkthrough

该 PR 添加了下载设置和重试功能，包括配置最大并行下载任务数的新设置页面，并在原生层（Android/iOS）实现相应控制 API，同时更新下载 UI 组件以支持恢复/重试已停止或失败的下载任务。

Changes

Download Settings & Retry Capability

Layer / File(s)	Summary
Data Types apps/mobile/src/types/core/appStore.ts	Settings 接口新增 downloadMaxParallelTasks: number 字段。
Store & Side Effects apps/mobile/src/hooks/stores/useAppStore.ts	初始化 downloadMaxParallelTasks 为 1，当更新此值时调用 Orpheus.setDownloadMaxParallelTasks(...) 同步到原生层。
Native Module Contract packages/orpheus/src/ExpoOrpheusModule.ts	定义三个新的原生模块方法：resumeDownload(id: string)、retryDownload(track: Track)、setDownloadMaxParallelTasks(maxParallelTasks: number)。
Android Native Implementation packages/orpheus/android/src/main/java/expo/modules/orpheus/ExpoOrpheusModule.kt	实现三个异步函数分别调用 DownloadService 和 DownloadUtil 来恢复、重试和配置并行下载。
Android Parallelism Control packages/orpheus/android/src/main/java/expo/modules/orpheus/util/DownloadUtil.kt	引入可配置的 maxParallelDownloads 变量与边界常数，新增 setMaxParallelDownloads() 方法来动态调整并行度。
Android Dependency packages/orpheus/android/build.gradle	kotlinx-serialization-json 从 1.6.0 升级至 1.8.1。
iOS Native Implementation packages/orpheus/ios/ExpoOrpheusModule.swift	新增 resumeDownload、retryDownload、setDownloadMaxParallelTasks 等函数导出；移除旧 setLyricsInternal 并新增 setDesktopLyricsInternal、setStatusBarLyricsInternal、debugTriggerError；更新 updateSpectrumData 指针检查逻辑；重格式化事件监听器代码。
iOS Download Manager packages/orpheus/ios/OrpheusDownloadManager.swift	新增 resumeDownload(id:) 方法用于通过 id 查询并恢复下载。
App Initialization apps/mobile/src/app/_layout.tsx	应用启动时从存储读取 downloadMaxParallelTasks 并调用 Orpheus.setDownloadMaxParallelTasks(...) 初始化；注册新路由 settings/download。
Settings Index apps/mobile/src/app/(tabs)/settings/index.tsx	在"歌词"列表项后新增"下载"设置项，点击跳转至 /settings/download。
Download Settings Page apps/mobile/src/app/settings/download.tsx	实现 DownloadSettingsPage 页面，含函数式菜单用于选择并行下载任务数；包含 NowPlayingBar 和安全区域适配。
Download Query Helpers apps/mobile/src/app/download.tsx	新增 canRetryDownloadTask() 函数判断任务是否可重试；DownloadHeader 传入 retryableCount 和 onRetryAll 回调；onRetryAll 并发地恢复或重试可重试任务。
Download Header Component apps/mobile/src/features/downloads/DownloadHeader.tsx	DownloadHeaderProps 新增 retryableCount 和 onRetryAll；渲染"重试失败"按钮，禁用条件为 retryableCount === 0。
Download Task Item apps/mobile/src/features/downloads/DownloadTaskItem.tsx	新增 canRetryDownloadTask() 辅助函数；扩展 getStatusText() 支持 STOPPED、REMOVING、RESTARTING 状态；替换重试按钮逻辑：已停止时调用 Orpheus.resumeDownload(task.id)，已失败时调用 Orpheus.retryDownload(retryTrack)；更新 icons 依赖列表。

Sequence Diagram

sequenceDiagram
    participant User as 用户
    participant SettingsUI as 设置UI<br/>(settings/download)
    participant AppStore as App Store<br/>(useAppStore)
    participant NativeModule as 原生模块<br/>(Orpheus)
    participant DownloadMgr as 下载管理器<br/>(Android/iOS)
    participant DownloadUI as 下载UI<br/>(DownloadTaskItem)

    Note over User,DownloadUI: 场景1: 配置最大并行任务数
    User->>SettingsUI: 打开下载设置，选择并行任务数
    SettingsUI->>AppStore: setSettings({downloadMaxParallelTasks: 3})
    AppStore->>NativeModule: Orpheus.setDownloadMaxParallelTasks(3)
    NativeModule->>DownloadMgr: setMaxParallelDownloads(3)
    Note over DownloadMgr: 更新DownloadManager配置<br/>后续下载受新限制

    Note over User,DownloadUI: 场景2: 重试/恢复失败的下载
    User->>DownloadUI: 点击"重试失败"按钮
    DownloadUI->>AppStore: 获取可重试任务列表
    AppStore->>NativeModule: 对FAILED任务：retryDownload(track)<br/>对STOPPED任务：resumeDownload(id)
    NativeModule->>DownloadMgr: 重新加入或恢复下载队列
    DownloadMgr-->>DownloadUI: 下载状态更新事件
    DownloadUI->>User: 刷新UI展示下载进度

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: some improvements #193：均修改 DownloadUtil.kt，涉及下载并行度控制和 HTTP 数据源实现。
• feat: settings page #118：均修改设置 UI 结构和 src/app/(tabs)/settings/index.tsx，涉及新设置项和路由扩展。
• feat: car lyrics #270：均修改原生模块导出接口 ExpoOrpheusModule，涉及歌词和调试函数的更新。

Suggested labels

enhancement

---

🐰 下载优化添新章，并行重试齐登场，
设置菜单闪闪亮，失败重来也不妨，
原生 API 来护航，从此下载更轻松！ ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-issue-248-download-throttle

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}