Phase 2 详细实施计划：音乐库 + 基本体验

Context

Phase 1 已完成（基础播放功能可用）。Phase 2 的目标是让 app 像一个正经的音乐播放器一样浏览和管理音乐：引入 Room 数据库、按歌曲/专辑/艺术家/文件夹浏览、专辑封面、播放模式、搜索等。

依赖关系总览

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
Week 1 (数据层):
  libs.versions.toml + build.gradle.kts (Room 依赖)
    → data/entity/*.kt
    → data/db/AppDatabase.kt
    → data/dao/*.kt
    → di/DatabaseModule.kt
    → data/mapper/EntityMapper.kt
    → scanner/MetadataReader.kt
    → scanner/LibraryScanner.kt

Week 2 (浏览 UI):
  ui/component/AlbumArt.kt
    → ui/screen/SongListScreen.kt
    → ui/screen/AlbumListScreen.kt + AlbumDetailScreen.kt
    → ui/screen/ArtistListScreen.kt + ArtistDetailScreen.kt
    → ui/screen/FolderBrowserScreen.kt
    → ui/screen/LibraryScreen.kt (Tab 宿主)
    → ui/navigation/AppNavigation.kt (改造)

Week 3 (播放功能):
  player/RepeatMode.kt
    → player/PlaybackState.kt (改)
    → player/PlayerController.kt (改)
    → player/ExoPlayerController.kt (改)
    → ui/screen/QueueScreen.kt
    → ui/screen/NowPlayingScreen.kt (改)
    → data/entity/Playlist*.kt + dao/PlaylistDao.kt
    → data/db/AppDatabase.kt (version 2)
    → ui/screen/PlaylistScreen.kt + PlaylistDetailScreen.kt

Week 4 (打磨):
  ui/component/MiniPlayer.kt (改)
  ui/screen/SearchScreen.kt

代码风格要求

  • ViewModel 写在对应 Screen/Component 的同一文件内，定义在 composable 上方
  • 所有注释使用中文
  • 状态模式：private val _state = MutableStateFlow(...) + val state = _state.asStateFlow()
  • DI：@Singleton 服务层, @HiltViewModel ViewModel, @Inject constructor
  • Composable：hiltViewModel(), collectAsStateWithLifecycle(), Scaffold+TopAppBar
  • 数据类默认值：中文（“未知艺术家”、“未知专辑”）
  • 私有 composable 和工具函数放文件底部
  • Entity 与 AudioFile 分离，通过 EntityMapper 转换

Week 1：Room 数据库 + 元数据解析

1.1 构建配置修改

gradle/libs.versions.toml — 添加：

1
2
3
4
5
6
7
# [versions] 区域添加
room = "2.7.1"

# [libraries] 区域添加
room-runtime = { group = "androidx.room", name = "room-runtime", version.ref = "room" }
room-ktx = { group = "androidx.room", name = "room-ktx", version.ref = "room" }
room-compiler = { group = "androidx.room", name = "room-compiler", version.ref = "room" }

app/build.gradle.kts — 添加：

1
2
3
4
5
6
7
8
9
10
// android 块内添加
ksp {
    arg("room.schemaLocation", "$projectDir/schemas")
}

// dependencies 块内添加
// Room
implementation(libs.room.runtime)
implementation(libs.room.ktx)
ksp(libs.room.compiler)

1.2 新建 data/entity/TrackEntity.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
package io.kyonqi.musicplayer.data.entity

import androidx.room.Entity
import androidx.room.PrimaryKey

/**
 * 音轨数据库实体
 * 与 AudioFile (UI/域模型) 分离，数据库专用
 */
@Entity(tableName = "tracks")
data class TrackEntity(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,
    val uri: String,                          // content:// URI 字符串
    val filePath: String = "",                // 文件绝对路径
    val displayName: String = "",             // 文件名
    val title: String = displayName,          // 标题
    val artist: String = "未知艺术家",         // 艺术家
    val albumArtist: String = "",             // 专辑艺术家
    val album: String = "未知专辑",            // 专辑名
    val genre: String = "",                   // 流派
    val trackNumber: Int = 0,                 // 音轨号
    val discNumber: Int = 0,                  // 碟号
    val year: Int = 0,                        // 年份
    val durationMs: Long = 0L,                // 时长（毫秒）
    val size: Long = 0L,                      // 文件大小（字节）
    val mimeType: String = "",                // MIME 类型
    val sampleRate: Int = 0,                  // 采样率
    val bitDepth: Int = 0,                    // 位深
    val dateModified: Long = 0L,              // 文件修改时间戳
    val dateAdded: Long = 0L,                 // 入库时间戳
)

1.3 新建 data/entity/AlbumEntity.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
package io.kyonqi.musicplayer.data.entity

import androidx.room.Entity
import androidx.room.PrimaryKey

/**
 * 专辑数据库实体
 */
@Entity(tableName = "albums")
data class AlbumEntity(
    @PrimaryKey(autoGenerate = true)
    val albumId: Long = 0,
    val name: String = "未知专辑",            // 专辑名
    val artist: String = "未知艺术家",         // 专辑艺术家
    val trackCount: Int = 0,                  // 歌曲数
    val coverUri: String = "",                // 封面 URI
    val year: Int = 0,                        // 年份
)

1.4 新建 data/entity/ArtistEntity.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
package io.kyonqi.musicplayer.data.entity

import androidx.room.Entity
import androidx.room.PrimaryKey

/**
 * 艺术家数据库实体
 */
@Entity(tableName = "artists")
data class ArtistEntity(
    @PrimaryKey(autoGenerate = true)
    val artistId: Long = 0,
    val name: String = "未知艺术家",           // 艺术家名
    val albumCount: Int = 0,                   // 专辑数
    val trackCount: Int = 0,                   // 歌曲数
)

1.5 新建 data/dao/TrackDao.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
package io.kyonqi.musicplayer.data.dao

import androidx.room.Dao
import androidx.room.Insert
import androidx.room.OnConflictStrategy
import androidx.room.Query
import io.kyonqi.musicplayer.data.entity.TrackEntity
import kotlinx.coroutines.flow.Flow

/**
 * 音轨数据访问对象
 */
@Dao
interface TrackDao {

    // 获取全部音轨，按标题排序
    @Query("SELECT * FROM tracks ORDER BY title ASC")
    fun getAllTracks(): Flow<List<TrackEntity>>

    // 按添加时间降序
    @Query("SELECT * FROM tracks ORDER BY dateAdded DESC")
    fun getAllTracksByDateAdded(): Flow<List<TrackEntity>>

    // 按时长升序
    @Query("SELECT * FROM tracks ORDER BY durationMs ASC")
    fun getAllTracksByDuration(): Flow<List<TrackEntity>>

    // 按专辑名获取音轨
    @Query("SELECT * FROM tracks WHERE album = :albumName ORDER BY discNumber ASC, trackNumber ASC")
    fun getTracksByAlbum(albumName: String): Flow<List<TrackEntity>>

    // 按艺术家获取音轨
    @Query("SELECT * FROM tracks WHERE artist = :artist ORDER BY album ASC, trackNumber ASC")
    fun getTracksByArtist(artist: String): Flow<List<TrackEntity>>

    // 按文件夹路径获取音轨
    @Query("SELECT * FROM tracks WHERE filePath LIKE :folderPath || '%' ORDER BY displayName ASC")
    fun getTracksByFolder(folderPath: String): Flow<List<TrackEntity>>

    // 搜索音轨（标题、艺术家、专辑模糊匹配）
    @Query("""
        SELECT * FROM tracks 
        WHERE title LIKE '%' || :query || '%' 
           OR artist LIKE '%' || :query || '%' 
           OR album LIKE '%' || :query || '%' 
        ORDER BY title ASC
    """)
    fun searchTracks(query: String): Flow<List<TrackEntity>>

    // 获取所有不同的文件夹路径
    @Query("SELECT DISTINCT SUBSTR(filePath, 1, LENGTH(filePath) - LENGTH(displayName)) AS folder FROM tracks ORDER BY folder ASC")
    fun getAllFolders(): Flow<List<String>>

    // 同步获取全部音轨（非 Flow，用于扫描汇总）
    @Query("SELECT * FROM tracks")
    suspend fun getAllTracksOnce(): List<TrackEntity>

    // 获取全部音轨数量
    @Query("SELECT COUNT(*) FROM tracks")
    suspend fun getTrackCount(): Int

    // 批量插入
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertAll(tracks: List<TrackEntity>)

    // 单条插入
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insert(track: TrackEntity)

    // 删除全部
    @Query("DELETE FROM tracks")
    suspend fun deleteAll()

    // 按 URI 删除
    @Query("DELETE FROM tracks WHERE uri = :uri")
    suspend fun deleteByUri(uri: String)

    // 获取所有 URI（用于增量扫描比对）
    @Query("SELECT uri FROM tracks")
    suspend fun getAllUris(): List<String>
}

1.6 新建 data/dao/AlbumDao.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
package io.kyonqi.musicplayer.data.dao

import androidx.room.Dao
import androidx.room.Insert
import androidx.room.OnConflictStrategy
import androidx.room.Query
import io.kyonqi.musicplayer.data.entity.AlbumEntity
import kotlinx.coroutines.flow.Flow

/**
 * 专辑数据访问对象
 */
@Dao
interface AlbumDao {

    // 获取全部专辑
    @Query("SELECT * FROM albums ORDER BY name ASC")
    fun getAllAlbums(): Flow<List<AlbumEntity>>

    // 按艺术家获取专辑
    @Query("SELECT * FROM albums WHERE artist = :artist ORDER BY year DESC")
    fun getAlbumsByArtist(artist: String): Flow<List<AlbumEntity>>

    // 按 ID 获取专辑
    @Query("SELECT * FROM albums WHERE albumId = :albumId")
    suspend fun getAlbumById(albumId: Long): AlbumEntity?

    // 批量插入
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertAll(albums: List<AlbumEntity>)

    // 单条插入并返回 ID
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insert(album: AlbumEntity): Long

    // 删除全部
    @Query("DELETE FROM albums")
    suspend fun deleteAll()

    // 搜索专辑
    @Query("SELECT * FROM albums WHERE name LIKE '%' || :query || '%' ORDER BY name ASC")
    fun searchAlbums(query: String): Flow<List<AlbumEntity>>
}

1.7 新建 data/dao/ArtistDao.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
package io.kyonqi.musicplayer.data.dao

import androidx.room.Dao
import androidx.room.Insert
import androidx.room.OnConflictStrategy
import androidx.room.Query
import io.kyonqi.musicplayer.data.entity.ArtistEntity
import kotlinx.coroutines.flow.Flow

/**
 * 艺术家数据访问对象
 */
@Dao
interface ArtistDao {

    // 获取全部艺术家
    @Query("SELECT * FROM artists ORDER BY name ASC")
    fun getAllArtists(): Flow<List<ArtistEntity>>

    // 按 ID 获取艺术家
    @Query("SELECT * FROM artists WHERE artistId = :artistId")
    suspend fun getArtistById(artistId: Long): ArtistEntity?

    // 批量插入
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertAll(artists: List<ArtistEntity>)

    // 单条插入并返回 ID
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insert(artist: ArtistEntity): Long

    // 删除全部
    @Query("DELETE FROM artists")
    suspend fun deleteAll()

    // 搜索艺术家
    @Query("SELECT * FROM artists WHERE name LIKE '%' || :query || '%' ORDER BY name ASC")
    fun searchArtists(query: String): Flow<List<ArtistEntity>>
}

1.8 新建 data/db/AppDatabase.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
package io.kyonqi.musicplayer.data.db

import androidx.room.Database
import androidx.room.RoomDatabase
import io.kyonqi.musicplayer.data.dao.AlbumDao
import io.kyonqi.musicplayer.data.dao.ArtistDao
import io.kyonqi.musicplayer.data.dao.TrackDao
import io.kyonqi.musicplayer.data.entity.AlbumEntity
import io.kyonqi.musicplayer.data.entity.ArtistEntity
import io.kyonqi.musicplayer.data.entity.TrackEntity

/**
 * 应用数据库
 * 版本 1：音轨、专辑、艺术家
 */
@Database(
    entities = [
        TrackEntity::class,
        AlbumEntity::class,
        ArtistEntity::class,
    ],
    version = 1,
    exportSchema = true
)
abstract class AppDatabase : RoomDatabase() {
    abstract fun trackDao(): TrackDao
    abstract fun albumDao(): AlbumDao
    abstract fun artistDao(): ArtistDao
}

Week 3 时将升级为 version 2，添加 PlaylistEntity + PlaylistTrackCrossRef

1.9 新建 di/DatabaseModule.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
package io.kyonqi.musicplayer.di

import android.content.Context
import androidx.room.Room
import dagger.Module
import dagger.Provides
import dagger.hilt.InstallIn
import dagger.hilt.android.qualifiers.ApplicationContext
import dagger.hilt.components.SingletonComponent
import io.kyonqi.musicplayer.data.dao.AlbumDao
import io.kyonqi.musicplayer.data.dao.ArtistDao
import io.kyonqi.musicplayer.data.dao.TrackDao
import io.kyonqi.musicplayer.data.db.AppDatabase
import javax.inject.Singleton

/**
 * 数据库依赖注入模块
 */
@Module
@InstallIn(SingletonComponent::class)
object DatabaseModule {

    // 提供数据库实例
    @Provides
    @Singleton
    fun provideDatabase(
        @ApplicationContext context: Context
    ): AppDatabase {
        return Room.databaseBuilder(
            context,
            AppDatabase::class.java,
            "music_library.db"
        ).build()
    }

    // 提供音轨 DAO
    @Provides
    fun provideTrackDao(db: AppDatabase): TrackDao = db.trackDao()

    // 提供专辑 DAO
    @Provides
    fun provideAlbumDao(db: AppDatabase): AlbumDao = db.albumDao()

    // 提供艺术家 DAO
    @Provides
    fun provideArtistDao(db: AppDatabase): ArtistDao = db.artistDao()
}

1.10 新建 data/mapper/EntityMapper.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
package io.kyonqi.musicplayer.data.mapper

import android.net.Uri
import io.kyonqi.musicplayer.data.entity.TrackEntity
import io.kyonqi.musicplayer.model.AudioFile

/**
 * 实体与域模型之间的映射函数
 * TrackEntity (数据库) <-> AudioFile (UI/播放器)
 */

// TrackEntity → AudioFile
fun TrackEntity.toAudioFile(): AudioFile {
    return AudioFile(
        uri = Uri.parse(uri),
        displayName = displayName,
        title = title,
        artist = artist,
        album = album,
        durationMs = durationMs,
        size = size,
        mimeType = mimeType,
        sampleRate = sampleRate,
        bitDepth = bitDepth,
    )
}

// AudioFile → TrackEntity（用于从 MediaStore 扫描结果转换）
fun AudioFile.toTrackEntity(
    filePath: String = "",
    albumArtist: String = "",
    genre: String = "",
    trackNumber: Int = 0,
    discNumber: Int = 0,
    year: Int = 0,
    dateModified: Long = 0L,
    dateAdded: Long = System.currentTimeMillis(),
): TrackEntity {
    return TrackEntity(
        uri = uri.toString(),
        filePath = filePath,
        displayName = displayName,
        title = title,
        artist = artist,
        albumArtist = albumArtist,
        album = album,
        genre = genre,
        trackNumber = trackNumber,
        discNumber = discNumber,
        year = year,
        durationMs = durationMs,
        size = size,
        mimeType = mimeType,
        sampleRate = sampleRate,
        bitDepth = bitDepth,
        dateModified = dateModified,
        dateAdded = dateAdded,
    )
}

// List 批量映射
fun List<TrackEntity>.toAudioFiles(): List<AudioFile> = map { it.toAudioFile() }

1.11 新建 scanner/MetadataReader.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
package io.kyonqi.musicplayer.scanner

import android.content.Context
import android.media.MediaExtractor
import android.media.MediaFormat
import android.media.MediaMetadataRetriever
import android.net.Uri
import dagger.hilt.android.qualifiers.ApplicationContext
import io.kyonqi.musicplayer.data.entity.TrackEntity
import javax.inject.Inject
import javax.inject.Singleton

/**
 * 元数据读取器
 * 使用 MediaMetadataRetriever 和 MediaExtractor 读取音频文件的详细标签信息
 */
@Singleton
class MetadataReader @Inject constructor(
    @ApplicationContext private val context: Context
) {

    /**
     * 读取指定 URI 的详细元数据，返回 TrackEntity
     * 读取失败时使用 fallback 值（文件名等）
     */
    fun readMetadata(
        uri: Uri,
        displayName: String,
        fileSize: Long,
        mimeType: String,
        dateModified: Long,
        filePath: String = "",
    ): TrackEntity {
        val retriever = MediaMetadataRetriever()
        return try {
            retriever.setDataSource(context, uri)

            // 基础标签
            val title = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_TITLE)
                ?: displayName.substringBeforeLast(".")
            val artist = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_ARTIST)
                ?: "未知艺术家"
            val albumArtist = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_ALBUMARTIST)
                ?: ""
            val album = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_ALBUM)
                ?: "未知专辑"
            val genre = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_GENRE)
                ?: ""
            val year = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_YEAR)
                ?.toIntOrNull() ?: 0
            val trackNumber = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_CD_TRACK_NUMBER)
                ?.parseTrackNumber() ?: 0
            val discNumber = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_DISC_NUMBER)
                ?.parseTrackNumber() ?: 0
            val durationMs = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_DURATION)
                ?.toLongOrNull() ?: 0L

            // 采样率和位深通过 MediaExtractor 读取
            val (sampleRate, bitDepth) = extractAudioFormat(uri)

            TrackEntity(
                uri = uri.toString(),
                filePath = filePath,
                displayName = displayName,
                title = title,
                artist = artist,
                albumArtist = albumArtist,
                album = album,
                genre = genre,
                trackNumber = trackNumber,
                discNumber = discNumber,
                year = year,
                durationMs = durationMs,
                size = fileSize,
                mimeType = mimeType,
                sampleRate = sampleRate,
                bitDepth = bitDepth,
                dateModified = dateModified,
                dateAdded = System.currentTimeMillis(),
            )
        } catch (e: Exception) {
            // 读取失败，使用基本信息创建实体
            TrackEntity(
                uri = uri.toString(),
                filePath = filePath,
                displayName = displayName,
                title = displayName.substringBeforeLast("."),
                size = fileSize,
                mimeType = mimeType,
                dateModified = dateModified,
                dateAdded = System.currentTimeMillis(),
            )
        } finally {
            retriever.release()
        }
    }

    /**
     * 通过 MediaExtractor 读取采样率和位深
     */
    private fun extractAudioFormat(uri: Uri): Pair<Int, Int> {
        val extractor = MediaExtractor()
        return try {
            extractor.setDataSource(context, uri, null)
            for (i in 0 until extractor.trackCount) {
                val format = extractor.getTrackFormat(i)
                val mime = format.getString(MediaFormat.KEY_MIME) ?: continue
                if (mime.startsWith("audio/")) {
                    val sampleRate = format.getIntOrDefault(MediaFormat.KEY_SAMPLE_RATE, 0)
                    val bitDepth = format.getIntOrDefault(
                        MediaFormat.KEY_PCM_ENCODING, 0
                    ).toBitDepth()
                    return@try Pair(sampleRate, bitDepth)
                }
            }
            Pair(0, 0)
        } catch (e: Exception) {
            Pair(0, 0)
        } finally {
            extractor.release()
        }
    }
}

// 解析音轨号（可能是 "3/12" 格式）
private fun String.parseTrackNumber(): Int {
    return split("/").firstOrNull()?.trim()?.toIntOrNull() ?: 0
}

// MediaFormat 安全读取整数
private fun MediaFormat.getIntOrDefault(key: String, default: Int): Int {
    return try {
        getInteger(key)
    } catch (e: Exception) {
        default
    }
}

// PCM 编码值转位深
private fun Int.toBitDepth(): Int {
    return when (this) {
        2 -> 16    // AudioFormat.ENCODING_PCM_16BIT
        3 -> 8     // AudioFormat.ENCODING_PCM_8BIT
        4 -> 32    // AudioFormat.ENCODING_PCM_FLOAT
        21 -> 24   // AudioFormat.ENCODING_PCM_24BIT_PACKED
        22 -> 32   // AudioFormat.ENCODING_PCM_32BIT
        else -> 0
    }
}

1.12 新建 scanner/LibraryScanner.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
package io.kyonqi.musicplayer.scanner

import android.content.ContentUris
import android.content.Context
import android.net.Uri
import android.provider.MediaStore
import dagger.hilt.android.qualifiers.ApplicationContext
import io.kyonqi.musicplayer.data.dao.AlbumDao
import io.kyonqi.musicplayer.data.dao.ArtistDao
import io.kyonqi.musicplayer.data.dao.TrackDao
import io.kyonqi.musicplayer.data.entity.AlbumEntity
import io.kyonqi.musicplayer.data.entity.ArtistEntity
import io.kyonqi.musicplayer.data.entity.TrackEntity
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.withContext
import javax.inject.Inject
import javax.inject.Singleton

/**
 * 扫描进度状态
 */
data class ScanProgress(
    val isScanning: Boolean = false,
    val current: Int = 0,
    val total: Int = 0,
    val message: String = "",
)

/**
 * 音乐库扫描器
 * 替代原来的 FileScanner，负责完整的扫描 → 元数据读取 → 入库流程
 */
@Singleton
class LibraryScanner @Inject constructor(
    @ApplicationContext private val context: Context,
    private val metadataReader: MetadataReader,
    private val trackDao: TrackDao,
    private val albumDao: AlbumDao,
    private val artistDao: ArtistDao,
) {
    // 扫描进度
    private val _scanProgress = MutableStateFlow(ScanProgress())
    val scanProgress: StateFlow<ScanProgress> = _scanProgress.asStateFlow()

    /**
     * 全量扫描：清库重建
     */
    suspend fun fullScan() = withContext(Dispatchers.IO) {
        _scanProgress.value = ScanProgress(isScanning = true, message = "正在清理旧数据...")

        // 清除旧数据
        trackDao.deleteAll()
        albumDao.deleteAll()
        artistDao.deleteAll()

        // 从 MediaStore 查询所有音频文件
        val rawEntries = queryMediaStore()
        _scanProgress.value = ScanProgress(
            isScanning = true, total = rawEntries.size, message = "正在读取元数据..."
        )

        // 逐个读取元数据并入库（分批插入提高性能）
        val tracks = mutableListOf<TrackEntity>()
        rawEntries.forEachIndexed { index, entry ->
            val track = metadataReader.readMetadata(
                uri = entry.uri,
                displayName = entry.displayName,
                fileSize = entry.size,
                mimeType = entry.mimeType,
                dateModified = entry.dateModified,
                filePath = entry.filePath,
            )
            tracks.add(track)

            _scanProgress.value = _scanProgress.value.copy(
                current = index + 1,
                message = "正在扫描: ${entry.displayName}"
            )

            // 每 50 条批量插入一次
            if (tracks.size >= 50) {
                trackDao.insertAll(tracks)
                tracks.clear()
            }
        }
        // 插入剩余的
        if (tracks.isNotEmpty()) {
            trackDao.insertAll(tracks)
        }

        // 构建专辑和艺术家汇总表
        _scanProgress.value = _scanProgress.value.copy(message = "正在整理音乐库...")
        buildAlbumSummary()
        buildArtistSummary()

        _scanProgress.value = ScanProgress(isScanning = false, message = "扫描完成")
    }

    /**
     * 增量扫描：只更新变化的文件
     */
    suspend fun incrementalScan() = withContext(Dispatchers.IO) {
        _scanProgress.value = ScanProgress(isScanning = true, message = "正在检查变化...")

        val existingUris = trackDao.getAllUris().toSet()
        val rawEntries = queryMediaStore()

        // 找出新增和已删除的
        val currentUris = rawEntries.map { it.uri.toString() }.toSet()
        val newEntries = rawEntries.filter { it.uri.toString() !in existingUris }
        val deletedUris = existingUris - currentUris

        // 删除不存在的
        deletedUris.forEach { trackDao.deleteByUri(it) }

        _scanProgress.value = ScanProgress(
            isScanning = true, total = newEntries.size, message = "正在扫描新文件..."
        )

        // 添加新文件
        val tracks = mutableListOf<TrackEntity>()
        newEntries.forEachIndexed { index, entry ->
            val track = metadataReader.readMetadata(
                uri = entry.uri,
                displayName = entry.displayName,
                fileSize = entry.size,
                mimeType = entry.mimeType,
                dateModified = entry.dateModified,
                filePath = entry.filePath,
            )
            tracks.add(track)
            _scanProgress.value = _scanProgress.value.copy(current = index + 1)

            if (tracks.size >= 50) {
                trackDao.insertAll(tracks)
                tracks.clear()
            }
        }
        if (tracks.isNotEmpty()) {
            trackDao.insertAll(tracks)
        }

        // 重新构建汇总表
        if (newEntries.isNotEmpty() || deletedUris.isNotEmpty()) {
            albumDao.deleteAll()
            artistDao.deleteAll()
            buildAlbumSummary()
            buildArtistSummary()
        }

        _scanProgress.value = ScanProgress(isScanning = false, message = "扫描完成")
    }

    /**
     * 从 MediaStore 查询原始音频条目
     */
    private fun queryMediaStore(): List<RawAudioEntry> {
        val entries = mutableListOf<RawAudioEntry>()

        val projection = arrayOf(
            MediaStore.Audio.Media._ID,
            MediaStore.Audio.Media.DISPLAY_NAME,
            MediaStore.Audio.Media.SIZE,
            MediaStore.Audio.Media.MIME_TYPE,
            MediaStore.Audio.Media.DATE_MODIFIED,
            MediaStore.Audio.Media.DATA,         // 文件路径
            MediaStore.Audio.Media.DURATION,
        )

        val selection = "${MediaStore.Audio.Media.DURATION} > ?"
        val selectionArgs = arrayOf("30000")
        val sortOrder = "${MediaStore.Audio.Media.TITLE} ASC"

        context.contentResolver.query(
            MediaStore.Audio.Media.EXTERNAL_CONTENT_URI,
            projection, selection, selectionArgs, sortOrder
        )?.use { cursor ->
            val idCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media._ID)
            val nameCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.DISPLAY_NAME)
            val sizeCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.SIZE)
            val mimeCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.MIME_TYPE)
            val dateCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.DATE_MODIFIED)
            val dataCol = cursor.getColumnIndexOrThrow(MediaStore.Audio.Media.DATA)

            while (cursor.moveToNext()) {
                val id = cursor.getLong(idCol)
                val uri = ContentUris.withAppendedId(
                    MediaStore.Audio.Media.EXTERNAL_CONTENT_URI, id
                )
                entries.add(
                    RawAudioEntry(
                        uri = uri,
                        displayName = cursor.getString(nameCol) ?: "Unknown",
                        size = cursor.getLong(sizeCol),
                        mimeType = cursor.getString(mimeCol) ?: "",
                        dateModified = cursor.getLong(dateCol),
                        filePath = cursor.getString(dataCol) ?: "",
                    )
                )
            }
        }
        return entries
    }

    /**
     * 从 tracks 表构建专辑汇总
     */
    private suspend fun buildAlbumSummary() {
        val allTracks = trackDao.getAllTracksOnce()
        val albumGroups = allTracks.groupBy { Pair(it.album, it.albumArtist.ifEmpty { it.artist }) }
        val albumEntities = albumGroups.map { (key, tracks) ->
            val (albumName, artistName) = key
            val coverUri = tracks.firstOrNull()?.uri ?: ""
            AlbumEntity(
                name = albumName,
                artist = artistName,
                trackCount = tracks.size,
                coverUri = coverUri,
                year = tracks.maxOf { it.year },
            )
        }
        albumDao.insertAll(albumEntities)
    }

    /**
     * 从 tracks 表构建艺术家汇总
     */
    private suspend fun buildArtistSummary() {
        val allTracks = trackDao.getAllTracksOnce()
        val artistGroups = allTracks.groupBy { it.artist }
        val artistEntities = artistGroups.map { (name, tracks) ->
            val albumCount = tracks.map { it.album }.distinct().size
            ArtistEntity(
                name = name,
                albumCount = albumCount,
                trackCount = tracks.size,
            )
        }
        artistDao.insertAll(artistEntities)
    }
}

/**
 * MediaStore 查询的原始条目（只含文件层面信息，不含标签）
 */
private data class RawAudioEntry(
    val uri: Uri,
    val displayName: String,
    val size: Long,
    val mimeType: String,
    val dateModified: Long,
    val filePath: String,
)

FileScanner.kt 保留不动，等 Week 2 替换完成后可删除。

Week 2：专辑封面 + 浏览 UI

2.1 新建 ui/component/AlbumArt.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
package io.kyonqi.musicplayer.ui.component

import android.net.Uri
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.size
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.MusicNote
import androidx.compose.material3.Icon
import androidx.compose.material3.MaterialTheme
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp
import coil3.compose.AsyncImage
import coil3.request.ImageRequest
import coil3.request.crossfade

/**
 * 专辑封面组件
 * 使用 Coil AsyncImage 加载封面
 * 加载失败时显示默认音乐图标
 */
@Composable
fun AlbumArt(
    uri: Uri?,
    modifier: Modifier = Modifier,
    size: Dp = 48.dp,
    contentDescription: String? = "专辑封面",
) {
    if (uri == null) {
        AlbumArtPlaceholder(modifier = modifier.size(size))
        return
    }

    val context = LocalContext.current
    val model = ImageRequest.Builder(context)
        .data(uri)
        .crossfade(true)
        .build()

    AsyncImage(
        model = model,
        contentDescription = contentDescription,
        modifier = modifier.size(size),
        contentScale = ContentScale.Crop,
        error = {
            AlbumArtPlaceholder(modifier = Modifier.fillMaxSize())
        },
    )
}

/**
 * 默认封面占位组件
 */
@Composable
private fun AlbumArtPlaceholder(modifier: Modifier = Modifier) {
    Box(
        modifier = modifier,
        contentAlignment = Alignment.Center
    ) {
        Icon(
            Icons.Default.MusicNote,
            contentDescription = null,
            modifier = Modifier.fillMaxSize(0.5f),
            tint = MaterialTheme.colorScheme.onSurfaceVariant
        )
    }
}

2.2 新建 ui/screen/LibraryScreen.kt

替代 FileBrowseScreen 作为主入口。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
package io.kyonqi.musicplayer.ui.screen

import android.Manifest
import android.os.Build
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Refresh
import androidx.compose.material.icons.filled.Search
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.LinearProgressIndicator
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Tab
import androidx.compose.material3.TabRow
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.TrackDao
import io.kyonqi.musicplayer.scanner.LibraryScanner
import io.kyonqi.musicplayer.ui.component.PermissionHandler
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch
import javax.inject.Inject

/**
 * 音乐库主界面 ViewModel
 * 负责管理 Tab 状态和触发初始扫描
 */
@HiltViewModel
class LibraryViewModel @Inject constructor(
    private val libraryScanner: LibraryScanner,
    private val trackDao: TrackDao,
) : ViewModel() {

    // 当前选中的 Tab 索引
    private val _selectedTab = MutableStateFlow(0)
    val selectedTab = _selectedTab.asStateFlow()

    // 扫描进度
    val scanProgress = libraryScanner.scanProgress

    // 数据库中的音轨数量
    private val _trackCount = MutableStateFlow(0)
    val trackCount = _trackCount.asStateFlow()

    // Tab 标题列表
    val tabs = listOf("歌曲", "专辑", "艺术家", "文件夹")

    fun selectTab(index: Int) {
        _selectedTab.value = index
    }

    // 首次加载时检查数据库，如果空则全量扫描
    fun initLibrary() {
        viewModelScope.launch {
            val count = trackDao.getTrackCount()
            _trackCount.value = count
            if (count == 0) {
                libraryScanner.fullScan()
                _trackCount.value = trackDao.getTrackCount()
            }
        }
    }

    // 手动刷新
    fun refreshLibrary() {
        viewModelScope.launch {
            libraryScanner.incrementalScan()
            _trackCount.value = trackDao.getTrackCount()
        }
    }
}

/**
 * 音乐库主屏幕
 * 包含权限检查、Tab 导航、扫描进度显示
 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun LibraryScreen(
    onNavigateToAlbumDetail: (Long) -> Unit,
    onNavigateToArtistDetail: (Long) -> Unit,
    onNavigateToNowPlaying: () -> Unit,
    onNavigateToSearch: () -> Unit,
    onNavigateToQueue: () -> Unit,
    viewModel: LibraryViewModel = hiltViewModel(),
) {
    val selectedTab by viewModel.selectedTab.collectAsStateWithLifecycle()
    val scanProgress by viewModel.scanProgress.collectAsStateWithLifecycle()

    // 权限处理
    val permission = if (Build.VERSION.SDK_INT >= 33) {
        Manifest.permission.READ_MEDIA_AUDIO
    } else {
        Manifest.permission.READ_EXTERNAL_STORAGE
    }
    PermissionHandler(
        permission = permission,
        onGranted = { viewModel.initLibrary() }
    )

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text("音乐库") },
                actions = {
                    // 搜索按钮
                    IconButton(onClick = onNavigateToSearch) {
                        Icon(Icons.Default.Search, "搜索")
                    }
                    // 刷新按钮
                    IconButton(onClick = { viewModel.refreshLibrary() }) {
                        Icon(Icons.Default.Refresh, "刷新")
                    }
                }
            )
        }
    ) { padding ->
        Column(modifier = Modifier.fillMaxSize().padding(padding)) {
            // 扫描进度条
            if (scanProgress.isScanning) {
                LinearProgressIndicator(
                    progress = {
                        if (scanProgress.total > 0)
                            scanProgress.current.toFloat() / scanProgress.total
                        else 0f
                    },
                    modifier = Modifier.fillMaxWidth()
                )
                Text(
                    text = scanProgress.message,
                    style = MaterialTheme.typography.labelSmall,
                    modifier = Modifier.padding(horizontal = 16.dp, vertical = 4.dp)
                )
            }

            // Tab 栏
            TabRow(selectedTabIndex = selectedTab) {
                viewModel.tabs.forEachIndexed { index, title ->
                    Tab(
                        selected = selectedTab == index,
                        onClick = { viewModel.selectTab(index) },
                        text = { Text(title) }
                    )
                }
            }

            // Tab 内容
            when (selectedTab) {
                0 -> SongListScreen(onNavigateToNowPlaying = onNavigateToNowPlaying)
                1 -> AlbumListScreen(onAlbumClick = onNavigateToAlbumDetail)
                2 -> ArtistListScreen(onArtistClick = onNavigateToArtistDetail)
                3 -> FolderBrowserScreen()
            }
        }
    }
}

2.3 新建 ui/screen/SongListScreen.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
package io.kyonqi.musicplayer.ui.screen

import android.net.Uri
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.itemsIndexed
import androidx.compose.material3.Card
import androidx.compose.material3.FilterChip
import androidx.compose.material3.ListItem
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.TrackDao
import io.kyonqi.musicplayer.data.entity.TrackEntity
import io.kyonqi.musicplayer.data.mapper.toAudioFiles
import io.kyonqi.musicplayer.player.PlayerController
import io.kyonqi.musicplayer.ui.component.AlbumArt
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.flatMapLatest
import kotlinx.coroutines.flow.stateIn
import javax.inject.Inject

/**
 * 排序方式
 */
enum class SongSortOrder {
    TITLE,       // 按标题
    DATE_ADDED,  // 按添加时间
    DURATION,    // 按时长
}

/**
 * 歌曲列表 ViewModel
 */
@HiltViewModel
class SongListViewModel @Inject constructor(
    private val trackDao: TrackDao,
    private val player: PlayerController,
) : ViewModel() {

    private val _sortOrder = MutableStateFlow(SongSortOrder.TITLE)
    val sortOrder = _sortOrder.asStateFlow()

    // 根据排序方式切换数据源
    val tracks: StateFlow<List<TrackEntity>> = _sortOrder.flatMapLatest { order ->
        when (order) {
            SongSortOrder.TITLE -> trackDao.getAllTracks()
            SongSortOrder.DATE_ADDED -> trackDao.getAllTracksByDateAdded()
            SongSortOrder.DURATION -> trackDao.getAllTracksByDuration()
        }
    }.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())

    fun setSortOrder(order: SongSortOrder) {
        _sortOrder.value = order
    }

    fun onTrackClick(index: Int) {
        val trackList = tracks.value
        if (index in trackList.indices) {
            val audioFiles = trackList.toAudioFiles()
            player.setQueue(audioFiles, index)
        }
    }
}

/**
 * 全部歌曲列表
 */
@Composable
fun SongListScreen(
    onNavigateToNowPlaying: () -> Unit = {},
    viewModel: SongListViewModel = hiltViewModel(),
) {
    val tracks by viewModel.tracks.collectAsStateWithLifecycle()
    val sortOrder by viewModel.sortOrder.collectAsStateWithLifecycle()

    Column(modifier = Modifier.fillMaxSize()) {
        // 排序选项栏
        SortBar(
            currentOrder = sortOrder,
            onOrderChange = { viewModel.setSortOrder(it) }
        )

        LazyColumn(modifier = Modifier.fillMaxSize()) {
            itemsIndexed(tracks) { index, track ->
                SongListItem(
                    track = track,
                    onClick = { viewModel.onTrackClick(index) }
                )
            }
        }
    }
}

/**
 * 歌曲列表项：封面缩略图 + 标题 + 艺术家 + 时长
 * 设为 internal 以便 ArtistDetailScreen 等复用
 */
@Composable
internal fun SongListItem(track: TrackEntity, onClick: () -> Unit) {
    ListItem(
        headlineContent = {
            Text(track.title, maxLines = 1, overflow = TextOverflow.Ellipsis)
        },
        supportingContent = {
            Text(
                "${track.artist} · ${formatDuration(track.durationMs)}",
                maxLines = 1, overflow = TextOverflow.Ellipsis
            )
        },
        leadingContent = {
            Card(modifier = Modifier.size(48.dp)) {
                AlbumArt(
                    uri = Uri.parse(track.uri),
                    size = 48.dp,
                )
            }
        },
        modifier = Modifier.clickable(onClick = onClick)
    )
}

/**
 * 排序选项栏
 */
@Composable
private fun SortBar(
    currentOrder: SongSortOrder,
    onOrderChange: (SongSortOrder) -> Unit,
) {
    Row(
        modifier = Modifier.fillMaxWidth().padding(horizontal = 16.dp, vertical = 8.dp),
        horizontalArrangement = Arrangement.spacedBy(8.dp)
    ) {
        SongSortOrder.entries.forEach { order ->
            FilterChip(
                selected = currentOrder == order,
                onClick = { onOrderChange(order) },
                label = {
                    Text(
                        when (order) {
                            SongSortOrder.TITLE -> "名称"
                            SongSortOrder.DATE_ADDED -> "添加时间"
                            SongSortOrder.DURATION -> "时长"
                        }
                    )
                }
            )
        }
    }
}

private fun formatDuration(ms: Long): String {
    val totalSeconds = ms / 1000
    return "%d:%02d".format(totalSeconds / 60, totalSeconds % 60)
}

2.4 新建 ui/screen/AlbumListScreen.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
package io.kyonqi.musicplayer.ui.screen

import android.net.Uri
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.aspectRatio
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.grid.GridCells
import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
import androidx.compose.foundation.lazy.grid.items
import androidx.compose.material3.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.AlbumDao
import io.kyonqi.musicplayer.data.entity.AlbumEntity
import io.kyonqi.musicplayer.ui.component.AlbumArt
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.stateIn
import javax.inject.Inject

/**
 * 专辑列表 ViewModel
 */
@HiltViewModel
class AlbumListViewModel @Inject constructor(
    private val albumDao: AlbumDao,
) : ViewModel() {
    val albums: StateFlow<List<AlbumEntity>> = albumDao.getAllAlbums()
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())
}

/**
 * 专辑网格列表
 */
@Composable
fun AlbumListScreen(
    onAlbumClick: (Long) -> Unit,
    viewModel: AlbumListViewModel = hiltViewModel(),
) {
    val albums by viewModel.albums.collectAsStateWithLifecycle()

    if (albums.isEmpty()) {
        Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
            Text("暂无专辑", style = MaterialTheme.typography.bodyLarge)
        }
        return
    }

    LazyVerticalGrid(
        columns = GridCells.Adaptive(minSize = 150.dp),
        contentPadding = PaddingValues(16.dp),
        horizontalArrangement = Arrangement.spacedBy(12.dp),
        verticalArrangement = Arrangement.spacedBy(12.dp),
        modifier = Modifier.fillMaxSize()
    ) {
        items(albums, key = { it.albumId }) { album ->
            AlbumGridItem(
                album = album,
                onClick = { onAlbumClick(album.albumId) }
            )
        }
    }
}

/**
 * 专辑网格项
 */
@Composable
private fun AlbumGridItem(album: AlbumEntity, onClick: () -> Unit) {
    Card(
        modifier = Modifier.fillMaxWidth().clickable(onClick = onClick),
    ) {
        Column {
            // 专辑封面（正方形）
            Card(
                modifier = Modifier.fillMaxWidth().aspectRatio(1f),
                colors = CardDefaults.cardColors(
                    containerColor = MaterialTheme.colorScheme.surfaceVariant
                )
            ) {
                AlbumArt(
                    uri = if (album.coverUri.isNotEmpty()) Uri.parse(album.coverUri) else null,
                    modifier = Modifier.fillMaxSize(),
                    size = 150.dp,
                )
            }
            // 专辑信息
            Column(modifier = Modifier.padding(8.dp)) {
                Text(
                    album.name,
                    style = MaterialTheme.typography.bodyMedium,
                    maxLines = 1, overflow = TextOverflow.Ellipsis
                )
                Text(
                    album.artist,
                    style = MaterialTheme.typography.bodySmall,
                    color = MaterialTheme.colorScheme.onSurfaceVariant,
                    maxLines = 1, overflow = TextOverflow.Ellipsis
                )
            }
        }
    }
}

2.5 新建 ui/screen/AlbumDetailScreen.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
package io.kyonqi.musicplayer.ui.screen

import android.net.Uri
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.itemsIndexed
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ArrowBack
import androidx.compose.material.icons.filled.PlayArrow
import androidx.compose.material3.Button
import androidx.compose.material3.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextAlign
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.SavedStateHandle
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.AlbumDao
import io.kyonqi.musicplayer.data.dao.TrackDao
import io.kyonqi.musicplayer.data.entity.AlbumEntity
import io.kyonqi.musicplayer.data.entity.TrackEntity
import io.kyonqi.musicplayer.data.mapper.toAudioFiles
import io.kyonqi.musicplayer.player.PlayerController
import io.kyonqi.musicplayer.ui.component.AlbumArt
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch
import javax.inject.Inject

/**
 * 专辑详情 ViewModel
 */
@HiltViewModel
class AlbumDetailViewModel @Inject constructor(
    savedStateHandle: SavedStateHandle,
    private val albumDao: AlbumDao,
    private val trackDao: TrackDao,
    private val player: PlayerController,
) : ViewModel() {

    private val albumId: Long = savedStateHandle.get<Long>("albumId") ?: 0L

    private val _album = MutableStateFlow<AlbumEntity?>(null)
    val album = _album.asStateFlow()

    private val _tracks = MutableStateFlow<List<TrackEntity>>(emptyList())
    val tracks = _tracks.asStateFlow()

    init {
        viewModelScope.launch {
            val albumEntity = albumDao.getAlbumById(albumId)
            _album.value = albumEntity
            albumEntity?.let { a ->
                trackDao.getTracksByAlbum(a.name).collect { trackList ->
                    _tracks.value = trackList
                }
            }
        }
    }

    // 播放全部
    fun playAll() {
        val trackList = _tracks.value
        if (trackList.isNotEmpty()) {
            player.setQueue(trackList.toAudioFiles(), 0)
        }
    }

    // 播放指定曲目
    fun playAt(index: Int) {
        val trackList = _tracks.value
        if (index in trackList.indices) {
            player.setQueue(trackList.toAudioFiles(), index)
        }
    }
}

/**
 * 专辑详情页
 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun AlbumDetailScreen(
    onBack: () -> Unit,
    viewModel: AlbumDetailViewModel = hiltViewModel(),
) {
    val album by viewModel.album.collectAsStateWithLifecycle()
    val tracks by viewModel.tracks.collectAsStateWithLifecycle()

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(album?.name ?: "专辑") },
                navigationIcon = {
                    IconButton(onClick = onBack) {
                        Icon(Icons.AutoMirrored.Filled.ArrowBack, "返回")
                    }
                }
            )
        }
    ) { padding ->
        LazyColumn(
            modifier = Modifier.fillMaxSize().padding(padding)
        ) {
            // 专辑头部信息
            item {
                AlbumHeader(
                    album = album,
                    trackCount = tracks.size,
                    onPlayAll = { viewModel.playAll() }
                )
            }
            // 歌曲列表
            itemsIndexed(tracks) { index, track ->
                AlbumTrackItem(
                    track = track,
                    trackIndex = index + 1,
                    onClick = { viewModel.playAt(index) }
                )
            }
        }
    }
}

/**
 * 专辑头部：封面 + 信息 + 全部播放
 */
@Composable
private fun AlbumHeader(
    album: AlbumEntity?,
    trackCount: Int,
    onPlayAll: () -> Unit,
) {
    Column(
        modifier = Modifier.fillMaxWidth().padding(16.dp),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        // 大封面
        Card(
            modifier = Modifier.size(200.dp),
            colors = CardDefaults.cardColors(
                containerColor = MaterialTheme.colorScheme.surfaceVariant
            )
        ) {
            AlbumArt(
                uri = album?.coverUri?.takeIf { it.isNotEmpty() }?.let { Uri.parse(it) },
                modifier = Modifier.fillMaxSize(),
                size = 200.dp,
            )
        }
        Spacer(Modifier.height(16.dp))
        Text(
            album?.name ?: "",
            style = MaterialTheme.typography.headlineSmall,
            textAlign = TextAlign.Center
        )
        Text(
            "${album?.artist ?: ""} · $trackCount 首歌曲",
            style = MaterialTheme.typography.bodyMedium,
            color = MaterialTheme.colorScheme.onSurfaceVariant
        )
        if ((album?.year ?: 0) > 0) {
            Text(
                "${album?.year}",
                style = MaterialTheme.typography.bodySmall,
                color = MaterialTheme.colorScheme.outline
            )
        }
        Spacer(Modifier.height(12.dp))
        Button(onClick = onPlayAll) {
            Icon(Icons.Default.PlayArrow, null, modifier = Modifier.size(18.dp))
            Spacer(Modifier.width(8.dp))
            Text("全部播放")
        }
        Spacer(Modifier.height(8.dp))
    }
}

/**
 * 专辑内歌曲项（显示序号而非封面）
 */
@Composable
private fun AlbumTrackItem(track: TrackEntity, trackIndex: Int, onClick: () -> Unit) {
    ListItem(
        headlineContent = {
            Text(track.title, maxLines = 1, overflow = TextOverflow.Ellipsis)
        },
        supportingContent = {
            Text(formatDuration(track.durationMs))
        },
        leadingContent = {
            Text(
                "$trackIndex",
                style = MaterialTheme.typography.bodyMedium,
                color = MaterialTheme.colorScheme.onSurfaceVariant
            )
        },
        modifier = Modifier.clickable(onClick = onClick)
    )
}

private fun formatDuration(ms: Long): String {
    val totalSeconds = ms / 1000
    return "%d:%02d".format(totalSeconds / 60, totalSeconds % 60)
}

2.6 新建 ui/screen/ArtistListScreen.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
package io.kyonqi.musicplayer.ui.screen

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Person
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.ArtistDao
import io.kyonqi.musicplayer.data.entity.ArtistEntity
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.stateIn
import javax.inject.Inject

/**
 * 艺术家列表 ViewModel
 */
@HiltViewModel
class ArtistListViewModel @Inject constructor(
    private val artistDao: ArtistDao,
) : ViewModel() {
    val artists: StateFlow<List<ArtistEntity>> = artistDao.getAllArtists()
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())
}

/**
 * 艺术家列表
 */
@Composable
fun ArtistListScreen(
    onArtistClick: (Long) -> Unit,
    viewModel: ArtistListViewModel = hiltViewModel(),
) {
    val artists by viewModel.artists.collectAsStateWithLifecycle()

    if (artists.isEmpty()) {
        Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
            Text("暂无艺术家", style = MaterialTheme.typography.bodyLarge)
        }
        return
    }

    LazyColumn(modifier = Modifier.fillMaxSize()) {
        items(artists, key = { it.artistId }) { artist ->
            ArtistListItem(
                artist = artist,
                onClick = { onArtistClick(artist.artistId) }
            )
        }
    }
}

/**
 * 艺术家列表项
 */
@Composable
private fun ArtistListItem(artist: ArtistEntity, onClick: () -> Unit) {
    ListItem(
        headlineContent = {
            Text(artist.name, maxLines = 1, overflow = TextOverflow.Ellipsis)
        },
        supportingContent = {
            Text("${artist.albumCount} 张专辑 · ${artist.trackCount} 首歌曲")
        },
        leadingContent = {
            Surface(
                modifier = Modifier.size(48.dp),
                shape = CircleShape,
                color = MaterialTheme.colorScheme.secondaryContainer
            ) {
                Box(contentAlignment = Alignment.Center) {
                    Icon(Icons.Default.Person, null)
                }
            }
        },
        modifier = Modifier.clickable(onClick = onClick)
    )
}

2.7 新建 ui/screen/ArtistDetailScreen.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
package io.kyonqi.musicplayer.ui.screen

import android.net.Uri
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.foundation.lazy.itemsIndexed
import androidx.compose.foundation.shape.CircleShape
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ArrowBack
import androidx.compose.material.icons.filled.Person
import androidx.compose.material.icons.filled.PlayArrow
import androidx.compose.material3.Button
import androidx.compose.material3.Card
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.SavedStateHandle
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.AlbumDao
import io.kyonqi.musicplayer.data.dao.ArtistDao
import io.kyonqi.musicplayer.data.dao.TrackDao
import io.kyonqi.musicplayer.data.entity.AlbumEntity
import io.kyonqi.musicplayer.data.entity.ArtistEntity
import io.kyonqi.musicplayer.data.entity.TrackEntity
import io.kyonqi.musicplayer.data.mapper.toAudioFiles
import io.kyonqi.musicplayer.player.PlayerController
import io.kyonqi.musicplayer.ui.component.AlbumArt
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch
import javax.inject.Inject

/**
 * 艺术家详情 ViewModel
 */
@HiltViewModel
class ArtistDetailViewModel @Inject constructor(
    savedStateHandle: SavedStateHandle,
    private val artistDao: ArtistDao,
    private val albumDao: AlbumDao,
    private val trackDao: TrackDao,
    private val player: PlayerController,
) : ViewModel() {

    private val artistId: Long = savedStateHandle.get<Long>("artistId") ?: 0L

    private val _artist = MutableStateFlow<ArtistEntity?>(null)
    val artist = _artist.asStateFlow()

    private val _albums = MutableStateFlow<List<AlbumEntity>>(emptyList())
    val albums = _albums.asStateFlow()

    private val _tracks = MutableStateFlow<List<TrackEntity>>(emptyList())
    val tracks = _tracks.asStateFlow()

    init {
        viewModelScope.launch {
            val artistEntity = artistDao.getArtistById(artistId)
            _artist.value = artistEntity
            artistEntity?.let { a ->
                launch {
                    albumDao.getAlbumsByArtist(a.name).collect { _albums.value = it }
                }
                launch {
                    trackDao.getTracksByArtist(a.name).collect { _tracks.value = it }
                }
            }
        }
    }

    fun playAll() {
        val trackList = _tracks.value
        if (trackList.isNotEmpty()) {
            player.setQueue(trackList.toAudioFiles(), 0)
        }
    }

    fun playAt(index: Int) {
        val trackList = _tracks.value
        if (index in trackList.indices) {
            player.setQueue(trackList.toAudioFiles(), index)
        }
    }
}

/**
 * 艺术家详情页
 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun ArtistDetailScreen(
    onBack: () -> Unit,
    onAlbumClick: (Long) -> Unit,
    viewModel: ArtistDetailViewModel = hiltViewModel(),
) {
    val artist by viewModel.artist.collectAsStateWithLifecycle()
    val albums by viewModel.albums.collectAsStateWithLifecycle()
    val tracks by viewModel.tracks.collectAsStateWithLifecycle()

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(artist?.name ?: "艺术家") },
                navigationIcon = {
                    IconButton(onClick = onBack) {
                        Icon(Icons.AutoMirrored.Filled.ArrowBack, "返回")
                    }
                }
            )
        }
    ) { padding ->
        LazyColumn(modifier = Modifier.fillMaxSize().padding(padding)) {
            // 艺术家信息头
            item {
                Column(
                    modifier = Modifier.fillMaxWidth().padding(16.dp),
                    horizontalAlignment = Alignment.CenterHorizontally
                ) {
                    Surface(
                        modifier = Modifier.size(100.dp),
                        shape = CircleShape,
                        color = MaterialTheme.colorScheme.secondaryContainer
                    ) {
                        Box(contentAlignment = Alignment.Center) {
                            Icon(Icons.Default.Person, null, Modifier.size(48.dp))
                        }
                    }
                    Spacer(Modifier.height(12.dp))
                    Text(artist?.name ?: "", style = MaterialTheme.typography.headlineSmall)
                    Text(
                        "${artist?.albumCount ?: 0} 张专辑 · ${artist?.trackCount ?: 0} 首歌曲",
                        style = MaterialTheme.typography.bodyMedium,
                        color = MaterialTheme.colorScheme.onSurfaceVariant
                    )
                    Spacer(Modifier.height(12.dp))
                    Button(onClick = { viewModel.playAll() }) {
                        Icon(Icons.Default.PlayArrow, null, Modifier.size(18.dp))
                        Spacer(Modifier.width(8.dp))
                        Text("全部播放")
                    }
                }
            }

            // 专辑部分
            if (albums.isNotEmpty()) {
                item {
                    Text(
                        "专辑",
                        style = MaterialTheme.typography.titleMedium,
                        modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp)
                    )
                }
                items(albums) { album ->
                    ListItem(
                        headlineContent = { Text(album.name) },
                        supportingContent = { Text("${album.trackCount} 首 · ${album.year}") },
                        leadingContent = {
                            Card(modifier = Modifier.size(48.dp)) {
                                AlbumArt(
                                    uri = album.coverUri.takeIf { it.isNotEmpty() }?.let { Uri.parse(it) },
                                    size = 48.dp
                                )
                            }
                        },
                        modifier = Modifier.clickable { onAlbumClick(album.albumId) }
                    )
                }
            }

            // 全部歌曲
            item {
                Text(
                    "歌曲",
                    style = MaterialTheme.typography.titleMedium,
                    modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp)
                )
            }
            itemsIndexed(tracks) { index, track ->
                SongListItem(track = track, onClick = { viewModel.playAt(index) })
            }
        }
    }
}

2.8 新建 ui/screen/FolderBrowserScreen.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
package io.kyonqi.musicplayer.ui.screen

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.itemsIndexed
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.ExpandLess
import androidx.compose.material.icons.filled.ExpandMore
import androidx.compose.material.icons.filled.Folder
import androidx.compose.material.icons.filled.FolderOpen
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.TrackDao
import io.kyonqi.musicplayer.data.entity.TrackEntity
import io.kyonqi.musicplayer.data.mapper.toAudioFiles
import io.kyonqi.musicplayer.player.PlayerController
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.stateIn
import kotlinx.coroutines.launch
import javax.inject.Inject

/**
 * 文件夹浏览 ViewModel
 */
@HiltViewModel
class FolderBrowserViewModel @Inject constructor(
    private val trackDao: TrackDao,
    private val player: PlayerController,
) : ViewModel() {

    // 所有文件夹路径
    val folders: StateFlow<List<String>> = trackDao.getAllFolders()
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())

    // 当前展开的文件夹及其歌曲
    private val _expandedFolder = MutableStateFlow<String?>(null)
    val expandedFolder = _expandedFolder.asStateFlow()

    private val _folderTracks = MutableStateFlow<List<TrackEntity>>(emptyList())
    val folderTracks = _folderTracks.asStateFlow()

    fun toggleFolder(folderPath: String) {
        if (_expandedFolder.value == folderPath) {
            _expandedFolder.value = null
            _folderTracks.value = emptyList()
        } else {
            _expandedFolder.value = folderPath
            viewModelScope.launch {
                trackDao.getTracksByFolder(folderPath).collect {
                    _folderTracks.value = it
                }
            }
        }
    }

    fun playTrack(index: Int) {
        val trackList = _folderTracks.value
        if (index in trackList.indices) {
            player.setQueue(trackList.toAudioFiles(), index)
        }
    }
}

/**
 * 文件夹浏览页
 */
@Composable
fun FolderBrowserScreen(
    viewModel: FolderBrowserViewModel = hiltViewModel(),
) {
    val folders by viewModel.folders.collectAsStateWithLifecycle()
    val expandedFolder by viewModel.expandedFolder.collectAsStateWithLifecycle()
    val folderTracks by viewModel.folderTracks.collectAsStateWithLifecycle()

    if (folders.isEmpty()) {
        Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
            Text("暂无文件夹", style = MaterialTheme.typography.bodyLarge)
        }
        return
    }

    LazyColumn(modifier = Modifier.fillMaxSize()) {
        folders.forEach { folder ->
            // 文件夹项
            item(key = "folder_$folder") {
                ListItem(
                    headlineContent = {
                        Text(
                            folder.trimEnd('/').substringAfterLast('/'),
                            maxLines = 1, overflow = TextOverflow.Ellipsis
                        )
                    },
                    supportingContent = {
                        Text(folder, style = MaterialTheme.typography.bodySmall)
                    },
                    leadingContent = {
                        Icon(
                            if (expandedFolder == folder) Icons.Default.FolderOpen
                            else Icons.Default.Folder,
                            null
                        )
                    },
                    trailingContent = {
                        Icon(
                            if (expandedFolder == folder) Icons.Default.ExpandLess
                            else Icons.Default.ExpandMore,
                            null
                        )
                    },
                    modifier = Modifier.clickable { viewModel.toggleFolder(folder) }
                )
            }
            // 展开时显示歌曲列表
            if (expandedFolder == folder) {
                itemsIndexed(folderTracks) { index, track ->
                    ListItem(
                        headlineContent = {
                            Text(track.title, maxLines = 1, overflow = TextOverflow.Ellipsis)
                        },
                        supportingContent = {
                            Text("${track.artist} · ${formatDuration(track.durationMs)}")
                        },
                        modifier = Modifier
                            .clickable { viewModel.playTrack(index) }
                            .padding(start = 24.dp)
                    )
                }
            }
        }
    }
}

private fun formatDuration(ms: Long): String {
    val totalSeconds = ms / 1000
    return "%d:%02d".format(totalSeconds / 60, totalSeconds % 60)
}

2.9 修改 ui/navigation/AppNavigation.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@Composable
fun AppNavigation() {
    val navController = rememberNavController()

    Box(modifier = Modifier.fillMaxSize()) {
        Column(modifier = Modifier.fillMaxSize()) {
            NavHost(
                navController = navController,
                startDestination = "library",    // 从 "browser" 改为 "library"
                modifier = Modifier.weight(1f)
            ) {
                // 音乐库主页（含 Tab）
                composable("library") {
                    LibraryScreen(
                        onNavigateToAlbumDetail = { albumId -> navController.navigate("album_detail/$albumId") },
                        onNavigateToArtistDetail = { artistId -> navController.navigate("artist_detail/$artistId") },
                        onNavigateToNowPlaying = { navController.navigate("now_playing") },
                        onNavigateToSearch = { navController.navigate("search") },
                        onNavigateToQueue = { navController.navigate("queue") },
                    )
                }

                // 专辑详情
                composable(
                    route = "album_detail/{albumId}",
                    arguments = listOf(navArgument("albumId") { type = NavType.LongType })
                ) {
                    AlbumDetailScreen(onBack = { navController.popBackStack() })
                }

                // 艺术家详情
                composable(
                    route = "artist_detail/{artistId}",
                    arguments = listOf(navArgument("artistId") { type = NavType.LongType })
                ) {
                    ArtistDetailScreen(
                        onBack = { navController.popBackStack() },
                        onAlbumClick = { albumId -> navController.navigate("album_detail/$albumId") }
                    )
                }

                // 正在播放
                composable("now_playing") {
                    NowPlayingScreen(
                        onBack = { navController.popBackStack() },
                        onOpenQueue = { navController.navigate("queue") }
                    )
                }

                // 播放队列 (Week 3)
                composable("queue") {
                    QueueScreen(onBack = { navController.popBackStack() })
                }

                // 搜索 (Week 4)
                composable("search") {
                    SearchScreen(
                        onBack = { navController.popBackStack() },
                        onAlbumClick = { albumId -> navController.navigate("album_detail/$albumId") },
                        onArtistClick = { artistId -> navController.navigate("artist_detail/$artistId") }
                    )
                }

                // 播放列表详情 (Week 3)
                composable(
                    route = "playlist_detail/{playlistId}",
                    arguments = listOf(navArgument("playlistId") { type = NavType.LongType })
                ) {
                    PlaylistDetailScreen(onBack = { navController.popBackStack() })
                }
            }

            // 迷你播放条
            MiniPlayer(onClick = { navController.navigate("now_playing") })
        }
    }
}

FileBrowseScreen.kt 不再路由，可删除或保留。

Week 3：播放队列 + 播放模式

3.1 新建 player/RepeatMode.kt

1
2
3
4
5
6
7
8
9
10
package io.kyonqi.musicplayer.player

/**
 * 循环播放模式
 */
enum class RepeatMode {
    OFF,    // 不循环
    ONE,    // 单曲循环
    ALL,    // 列表循环
}

3.2 修改 player/PlaybackState.kt

添加两个字段：

1
2
3
4
5
6
7
8
9
10
11
data class PlaybackState(
    val currentTrack: AudioFile? = null,
    val isPlaying: Boolean = false,
    val positionMs: Long = 0L,
    val durationMs: Long = 0L,
    val queue: List<AudioFile> = emptyList(),
    val currentIndex: Int = -1,
    val repeatMode: RepeatMode = RepeatMode.OFF,      // 新增
    val shuffleEnabled: Boolean = false,               // 新增
    val outputInfo: OutputInfo = OutputInfo(),
)

3.3 修改 player/PlayerController.kt

接口添加两个方法：

1
2
3
4
5
// 切换循环模式 (OFF → ALL → ONE → OFF)
fun toggleRepeatMode()

// 切换随机播放
fun toggleShuffle()

3.4 修改 player/ExoPlayerController.kt

添加实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
override fun toggleRepeatMode() {
    val current = _state.value.repeatMode
    val next = when (current) {
        RepeatMode.OFF -> RepeatMode.ALL
        RepeatMode.ALL -> RepeatMode.ONE
        RepeatMode.ONE -> RepeatMode.OFF
    }
    _state.update { it.copy(repeatMode = next) }

    exoPlayer.repeatMode = when (next) {
        RepeatMode.OFF -> Player.REPEAT_MODE_OFF
        RepeatMode.ONE -> Player.REPEAT_MODE_ONE
        RepeatMode.ALL -> Player.REPEAT_MODE_ALL
    }
}

override fun toggleShuffle() {
    val newShuffle = !_state.value.shuffleEnabled
    _state.update { it.copy(shuffleEnabled = newShuffle) }
    exoPlayer.shuffleModeEnabled = newShuffle
}

3.5 新建 ui/screen/QueueScreen.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
package io.kyonqi.musicplayer.ui.screen

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.itemsIndexed
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ArrowBack
import androidx.compose.material.icons.filled.MusicNote
import androidx.compose.material.icons.filled.PlayArrow
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.ListItemDefaults
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextOverflow
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.model.AudioFile
import io.kyonqi.musicplayer.player.PlayerController
import javax.inject.Inject

/**
 * 播放队列 ViewModel
 */
@HiltViewModel
class QueueViewModel @Inject constructor(
    private val player: PlayerController,
) : ViewModel() {
    val playbackState = player.playbackState

    fun playAt(index: Int) = player.playAt(index)
}

/**
 * 播放队列页面
 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun QueueScreen(
    onBack: () -> Unit,
    viewModel: QueueViewModel = hiltViewModel(),
) {
    val state by viewModel.playbackState.collectAsStateWithLifecycle()

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text("播放队列 (${state.queue.size})") },
                navigationIcon = {
                    IconButton(onClick = onBack) {
                        Icon(Icons.AutoMirrored.Filled.ArrowBack, "返回")
                    }
                }
            )
        }
    ) { padding ->
        if (state.queue.isEmpty()) {
            Box(
                modifier = Modifier.fillMaxSize().padding(padding),
                contentAlignment = Alignment.Center
            ) {
                Text("队列为空", style = MaterialTheme.typography.bodyLarge)
            }
        } else {
            LazyColumn(modifier = Modifier.fillMaxSize().padding(padding)) {
                itemsIndexed(state.queue) { index, track ->
                    val isPlaying = index == state.currentIndex
                    QueueItem(
                        track = track,
                        isPlaying = isPlaying,
                        onClick = { viewModel.playAt(index) }
                    )
                }
            }
        }
    }
}

/**
 * 队列项（高亮当前播放）
 */
@Composable
private fun QueueItem(track: AudioFile, isPlaying: Boolean, onClick: () -> Unit) {
    ListItem(
        headlineContent = {
            Text(
                track.title,
                maxLines = 1,
                overflow = TextOverflow.Ellipsis,
                color = if (isPlaying) MaterialTheme.colorScheme.primary
                        else MaterialTheme.colorScheme.onSurface
            )
        },
        supportingContent = {
            Text(
                "${track.artist} · ${formatDuration(track.durationMs)}",
                maxLines = 1
            )
        },
        leadingContent = {
            if (isPlaying) {
                Icon(
                    Icons.Default.PlayArrow,
                    "正在播放",
                    tint = MaterialTheme.colorScheme.primary
                )
            } else {
                Icon(Icons.Default.MusicNote, null)
            }
        },
        modifier = Modifier.clickable(onClick = onClick),
        colors = if (isPlaying) {
            ListItemDefaults.colors(
                containerColor = MaterialTheme.colorScheme.primaryContainer.copy(alpha = 0.3f)
            )
        } else {
            ListItemDefaults.colors()
        }
    )
}

private fun formatDuration(ms: Long): String {
    val totalSeconds = ms / 1000
    return "%d:%02d".format(totalSeconds / 60, totalSeconds % 60)
}

3.6 修改 ui/screen/NowPlayingScreen.kt

  1. ViewModel 添加：

    1
    2
    fun toggleRepeatMode() = player.toggleRepeatMode()
    fun toggleShuffle() = player.toggleShuffle()

  2. Screen 参数添加 onOpenQueue: () -> Unit

  3. 封面区域替换为 AlbumArt 组件：

    1
    2
    3
    Card(modifier = Modifier.size(200.dp), ...) {
        AlbumArt(uri = state.currentTrack?.uri, modifier = Modifier.fillMaxSize(), size = 200.dp)
    }

  4. 播放控制栏下方添加循环/随机/队列按钮行：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    Row(modifier = Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.SpaceEvenly) {
        // 随机播放
        IconButton(onClick = { viewModel.toggleShuffle() }) {
            Icon(Icons.Default.Shuffle, "随机播放",
                tint = if (state.shuffleEnabled) primary else onSurfaceVariant)
        }
        // 循环模式（三态图标）
        IconButton(onClick = { viewModel.toggleRepeatMode() }) {
            Icon(
                when (state.repeatMode) {
                    RepeatMode.ONE -> Icons.Default.RepeatOne
                    else -> Icons.Default.Repeat
                }, "循环模式",
                tint = if (state.repeatMode != RepeatMode.OFF) primary else onSurfaceVariant)
        }
        // 队列按钮
        IconButton(onClick = onOpenQueue) {
            Icon(Icons.Default.QueueMusic, "播放队列")
        }
    }

3.7 新建 data/entity/PlaylistEntity.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
package io.kyonqi.musicplayer.data.entity

import androidx.room.Entity
import androidx.room.PrimaryKey

/**
 * 播放列表实体
 */
@Entity(tableName = "playlists")
data class PlaylistEntity(
    @PrimaryKey(autoGenerate = true)
    val playlistId: Long = 0,
    val name: String = "",                    // 播放列表名称
    val createdAt: Long = System.currentTimeMillis(),
    val updatedAt: Long = System.currentTimeMillis(),
)

3.8 新建 data/entity/PlaylistTrackCrossRef.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
package io.kyonqi.musicplayer.data.entity

import androidx.room.Entity
import androidx.room.ForeignKey
import androidx.room.Index

/**
 * 播放列表与音轨的关联表
 */
@Entity(
    tableName = "playlist_track_cross_ref",
    primaryKeys = ["playlistId", "trackId"],
    foreignKeys = [
        ForeignKey(
            entity = PlaylistEntity::class,
            parentColumns = ["playlistId"],
            childColumns = ["playlistId"],
            onDelete = ForeignKey.CASCADE
        ),
        ForeignKey(
            entity = TrackEntity::class,
            parentColumns = ["id"],
            childColumns = ["trackId"],
            onDelete = ForeignKey.CASCADE
        )
    ],
    indices = [
        Index("playlistId"),
        Index("trackId")
    ]
)
data class PlaylistTrackCrossRef(
    val playlistId: Long,
    val trackId: Long,
    val sortOrder: Int = 0,               // 在播放列表中的排序位置
)

3.9 新建 data/dao/PlaylistDao.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
package io.kyonqi.musicplayer.data.dao

import androidx.room.Dao
import androidx.room.Insert
import androidx.room.OnConflictStrategy
import androidx.room.Query
import androidx.room.Transaction
import io.kyonqi.musicplayer.data.entity.PlaylistEntity
import io.kyonqi.musicplayer.data.entity.PlaylistTrackCrossRef
import io.kyonqi.musicplayer.data.entity.TrackEntity
import kotlinx.coroutines.flow.Flow

/**
 * 播放列表数据访问对象
 */
@Dao
interface PlaylistDao {

    // 获取全部播放列表
    @Query("SELECT * FROM playlists ORDER BY updatedAt DESC")
    fun getAllPlaylists(): Flow<List<PlaylistEntity>>

    // 获取播放列表中的歌曲
    @Transaction
    @Query("""
        SELECT t.* FROM tracks t 
        INNER JOIN playlist_track_cross_ref ref ON t.id = ref.trackId 
        WHERE ref.playlistId = :playlistId 
        ORDER BY ref.sortOrder ASC
    """)
    fun getTracksForPlaylist(playlistId: Long): Flow<List<TrackEntity>>

    // 创建播放列表
    @Insert
    suspend fun createPlaylist(playlist: PlaylistEntity): Long

    // 添加歌曲到播放列表
    @Insert(onConflict = OnConflictStrategy.IGNORE)
    suspend fun addTrackToPlaylist(crossRef: PlaylistTrackCrossRef)

    // 从播放列表移除歌曲
    @Query("DELETE FROM playlist_track_cross_ref WHERE playlistId = :playlistId AND trackId = :trackId")
    suspend fun removeTrackFromPlaylist(playlistId: Long, trackId: Long)

    // 删除播放列表
    @Query("DELETE FROM playlists WHERE playlistId = :playlistId")
    suspend fun deletePlaylist(playlistId: Long)

    // 更新播放列表的 updatedAt
    @Query("UPDATE playlists SET updatedAt = :timestamp WHERE playlistId = :playlistId")
    suspend fun updateTimestamp(playlistId: Long, timestamp: Long = System.currentTimeMillis())
}

3.10 修改 data/db/AppDatabase.kt (version 2)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
@Database(
    entities = [
        TrackEntity::class,
        AlbumEntity::class,
        ArtistEntity::class,
        PlaylistEntity::class,            // 新增
        PlaylistTrackCrossRef::class,     // 新增
    ],
    version = 2,
    exportSchema = true,
    autoMigrations = [
        AutoMigration(from = 1, to = 2)
    ]
)
abstract class AppDatabase : RoomDatabase() {
    abstract fun trackDao(): TrackDao
    abstract fun albumDao(): AlbumDao
    abstract fun artistDao(): ArtistDao
    abstract fun playlistDao(): PlaylistDao   // 新增
}

3.11 修改 di/DatabaseModule.kt

添加：

1
2
3
// 提供播放列表 DAO
@Provides
fun providePlaylistDao(db: AppDatabase): PlaylistDao = db.playlistDao()

3.12 新建 ui/screen/PlaylistScreen.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
package io.kyonqi.musicplayer.ui.screen

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Add
import androidx.compose.material.icons.filled.PlaylistPlay
import androidx.compose.material3.AlertDialog
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.PlaylistDao
import io.kyonqi.musicplayer.data.entity.PlaylistEntity
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.stateIn
import kotlinx.coroutines.launch
import javax.inject.Inject

/**
 * 播放列表 ViewModel
 */
@HiltViewModel
class PlaylistViewModel @Inject constructor(
    private val playlistDao: PlaylistDao,
) : ViewModel() {

    val playlists = playlistDao.getAllPlaylists()
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())

    // 显示创建对话框
    private val _showCreateDialog = MutableStateFlow(false)
    val showCreateDialog = _showCreateDialog.asStateFlow()

    fun showCreateDialog() { _showCreateDialog.value = true }
    fun dismissCreateDialog() { _showCreateDialog.value = false }

    fun createPlaylist(name: String) {
        viewModelScope.launch {
            playlistDao.createPlaylist(PlaylistEntity(name = name))
            _showCreateDialog.value = false
        }
    }

    fun deletePlaylist(playlistId: Long) {
        viewModelScope.launch {
            playlistDao.deletePlaylist(playlistId)
        }
    }
}

/**
 * 播放列表页面
 */
@Composable
fun PlaylistScreen(
    onPlaylistClick: (Long) -> Unit,
    viewModel: PlaylistViewModel = hiltViewModel(),
) {
    val playlists by viewModel.playlists.collectAsStateWithLifecycle()
    val showDialog by viewModel.showCreateDialog.collectAsStateWithLifecycle()

    Column(modifier = Modifier.fillMaxSize()) {
        // 新建播放列表按钮
        ListItem(
            headlineContent = { Text("新建播放列表") },
            leadingContent = { Icon(Icons.Default.Add, null) },
            modifier = Modifier.clickable { viewModel.showCreateDialog() }
        )
        HorizontalDivider()

        // 播放列表
        LazyColumn {
            items(playlists, key = { it.playlistId }) { playlist ->
                ListItem(
                    headlineContent = { Text(playlist.name) },
                    leadingContent = { Icon(Icons.Default.PlaylistPlay, null) },
                    modifier = Modifier.clickable { onPlaylistClick(playlist.playlistId) }
                )
            }
        }
    }

    // 创建播放列表对话框
    if (showDialog) {
        CreatePlaylistDialog(
            onDismiss = { viewModel.dismissCreateDialog() },
            onCreate = { name -> viewModel.createPlaylist(name) }
        )
    }
}

/**
 * 新建播放列表对话框
 */
@Composable
private fun CreatePlaylistDialog(
    onDismiss: () -> Unit,
    onCreate: (String) -> Unit,
) {
    var name by remember { mutableStateOf("") }
    AlertDialog(
        onDismissRequest = onDismiss,
        title = { Text("新建播放列表") },
        text = {
            OutlinedTextField(
                value = name,
                onValueChange = { name = it },
                label = { Text("名称") },
                singleLine = true,
            )
        },
        confirmButton = {
            TextButton(
                onClick = { if (name.isNotBlank()) onCreate(name.trim()) },
                enabled = name.isNotBlank()
            ) { Text("创建") }
        },
        dismissButton = {
            TextButton(onClick = onDismiss) { Text("取消") }
        }
    )
}

3.13 新建 ui/screen/PlaylistDetailScreen.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
package io.kyonqi.musicplayer.ui.screen

import android.net.Uri
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.itemsIndexed
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ArrowBack
import androidx.compose.material.icons.filled.PlayArrow
import androidx.compose.material3.Card
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.FloatingActionButton
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.SavedStateHandle
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.PlaylistDao
import io.kyonqi.musicplayer.data.entity.TrackEntity
import io.kyonqi.musicplayer.data.mapper.toAudioFiles
import io.kyonqi.musicplayer.player.PlayerController
import io.kyonqi.musicplayer.ui.component.AlbumArt
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.stateIn
import kotlinx.coroutines.launch
import javax.inject.Inject

/**
 * 播放列表详情 ViewModel
 */
@HiltViewModel
class PlaylistDetailViewModel @Inject constructor(
    savedStateHandle: SavedStateHandle,
    private val playlistDao: PlaylistDao,
    private val player: PlayerController,
) : ViewModel() {

    private val playlistId: Long = savedStateHandle.get<Long>("playlistId") ?: 0L

    val tracks = playlistDao.getTracksForPlaylist(playlistId)
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())

    fun playAll() {
        val trackList = tracks.value
        if (trackList.isNotEmpty()) {
            player.setQueue(trackList.toAudioFiles(), 0)
        }
    }

    fun playAt(index: Int) {
        val trackList = tracks.value
        if (index in trackList.indices) {
            player.setQueue(trackList.toAudioFiles(), index)
        }
    }

    fun removeTrack(trackId: Long) {
        viewModelScope.launch {
            playlistDao.removeTrackFromPlaylist(playlistId, trackId)
        }
    }
}

/**
 * 播放列表详情页面
 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun PlaylistDetailScreen(
    onBack: () -> Unit,
    viewModel: PlaylistDetailViewModel = hiltViewModel(),
) {
    val tracks by viewModel.tracks.collectAsStateWithLifecycle()

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text("播放列表") },
                navigationIcon = {
                    IconButton(onClick = onBack) {
                        Icon(Icons.AutoMirrored.Filled.ArrowBack, "返回")
                    }
                }
            )
        },
        floatingActionButton = {
            if (tracks.isNotEmpty()) {
                FloatingActionButton(onClick = { viewModel.playAll() }) {
                    Icon(Icons.Default.PlayArrow, "全部播放")
                }
            }
        }
    ) { padding ->
        if (tracks.isEmpty()) {
            Box(
                modifier = Modifier.fillMaxSize().padding(padding),
                contentAlignment = Alignment.Center
            ) {
                Text("播放列表为空", style = MaterialTheme.typography.bodyLarge)
            }
        } else {
            LazyColumn(modifier = Modifier.fillMaxSize().padding(padding)) {
                itemsIndexed(tracks) { index, track ->
                    PlaylistTrackItem(
                        track = track,
                        onClick = { viewModel.playAt(index) }
                    )
                }
            }
        }
    }
}

/**
 * 播放列表歌曲项
 */
@Composable
private fun PlaylistTrackItem(track: TrackEntity, onClick: () -> Unit) {
    ListItem(
        headlineContent = {
            Text(track.title, maxLines = 1, overflow = TextOverflow.Ellipsis)
        },
        supportingContent = {
            Text("${track.artist} · ${formatDuration(track.durationMs)}")
        },
        leadingContent = {
            Card(modifier = Modifier.size(48.dp)) {
                AlbumArt(uri = Uri.parse(track.uri), size = 48.dp)
            }
        },
        modifier = Modifier.clickable(onClick = onClick)
    )
}

private fun formatDuration(ms: Long): String {
    val totalSeconds = ms / 1000
    return "%d:%02d".format(totalSeconds / 60, totalSeconds % 60)
}

Week 4：打磨

4.1 修改 ui/component/MiniPlayer.kt

  1. MusicNote 图标替换为 AlbumArt：

    1
    2
    3
    Card(modifier = Modifier.size(40.dp)) {
        AlbumArt(uri = track.uri, size = 40.dp)
    }

  2. 播放/暂停按钮后添加下一首按钮：

    1
    2
    3
    IconButton(onClick = { viewModel.next() }) {
        Icon(Icons.Default.SkipNext, contentDescription = "下一首")
    }

  3. ViewModel 添加：

    1
    fun next() = player.next()

4.2 新建 ui/screen/SearchScreen.kt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
package io.kyonqi.musicplayer.ui.screen

import android.net.Uri
import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.foundation.lazy.itemsIndexed
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ArrowBack
import androidx.compose.material3.Card
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.hilt.navigation.compose.hiltViewModel
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import dagger.hilt.android.lifecycle.HiltViewModel
import io.kyonqi.musicplayer.data.dao.AlbumDao
import io.kyonqi.musicplayer.data.dao.ArtistDao
import io.kyonqi.musicplayer.data.dao.TrackDao
import io.kyonqi.musicplayer.data.entity.AlbumEntity
import io.kyonqi.musicplayer.data.entity.ArtistEntity
import io.kyonqi.musicplayer.data.entity.TrackEntity
import io.kyonqi.musicplayer.data.mapper.toAudioFiles
import io.kyonqi.musicplayer.player.PlayerController
import io.kyonqi.musicplayer.ui.component.AlbumArt
import kotlinx.coroutines.FlowPreview
import kotlinx.coroutines.async
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.collectLatest
import kotlinx.coroutines.flow.debounce
import kotlinx.coroutines.flow.distinctUntilChanged
import kotlinx.coroutines.flow.first
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch
import javax.inject.Inject

/**
 * 搜索结果状态
 */
data class SearchState(
    val query: String = "",
    val tracks: List<TrackEntity> = emptyList(),
    val albums: List<AlbumEntity> = emptyList(),
    val artists: List<ArtistEntity> = emptyList(),
)

/**
 * 搜索 ViewModel
 */
@OptIn(FlowPreview::class)
@HiltViewModel
class SearchViewModel @Inject constructor(
    private val trackDao: TrackDao,
    private val albumDao: AlbumDao,
    private val artistDao: ArtistDao,
    private val player: PlayerController,
) : ViewModel() {

    private val _state = MutableStateFlow(SearchState())
    val state: StateFlow<SearchState> = _state.asStateFlow()

    // 搜索查询（带防抖）
    private val _queryFlow = MutableStateFlow("")

    init {
        viewModelScope.launch {
            _queryFlow
                .debounce(300)
                .distinctUntilChanged()
                .collectLatest { query ->
                    if (query.isBlank()) {
                        _state.value = SearchState()
                        return@collectLatest
                    }
                    // 并行搜索歌曲、专辑、艺术家
                    coroutineScope {
                        val tracksDeferred = async {
                            trackDao.searchTracks(query).first()
                        }
                        val albumsDeferred = async {
                            albumDao.searchAlbums(query).first()
                        }
                        val artistsDeferred = async {
                            artistDao.searchArtists(query).first()
                        }
                        _state.value = SearchState(
                            query = query,
                            tracks = tracksDeferred.await(),
                            albums = albumsDeferred.await(),
                            artists = artistsDeferred.await(),
                        )
                    }
                }
        }
    }

    fun updateQuery(query: String) {
        _queryFlow.value = query
        _state.update { it.copy(query = query) }
    }

    fun playTrack(tracks: List<TrackEntity>, index: Int) {
        if (index in tracks.indices) {
            player.setQueue(tracks.toAudioFiles(), index)
        }
    }
}

/**
 * 搜索页面
 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun SearchScreen(
    onBack: () -> Unit,
    onAlbumClick: (Long) -> Unit,
    onArtistClick: (Long) -> Unit,
    viewModel: SearchViewModel = hiltViewModel(),
) {
    val state by viewModel.state.collectAsStateWithLifecycle()

    Scaffold(
        topBar = {
            TopAppBar(
                title = {
                    OutlinedTextField(
                        value = state.query,
                        onValueChange = { viewModel.updateQuery(it) },
                        placeholder = { Text("搜索歌曲、专辑、艺术家...") },
                        singleLine = true,
                        modifier = Modifier.fillMaxWidth(),
                    )
                },
                navigationIcon = {
                    IconButton(onClick = onBack) {
                        Icon(Icons.AutoMirrored.Filled.ArrowBack, "返回")
                    }
                }
            )
        }
    ) { padding ->
        if (state.query.isBlank()) {
            Box(
                modifier = Modifier.fillMaxSize().padding(padding),
                contentAlignment = Alignment.Center
            ) {
                Text("输入关键词开始搜索", style = MaterialTheme.typography.bodyLarge)
            }
        } else {
            LazyColumn(modifier = Modifier.fillMaxSize().padding(padding)) {
                // 歌曲结果
                if (state.tracks.isNotEmpty()) {
                    item {
                        Text(
                            "歌曲 (${state.tracks.size})",
                            style = MaterialTheme.typography.titleMedium,
                            modifier = Modifier.padding(16.dp)
                        )
                    }
                    itemsIndexed(state.tracks.take(5)) { index, track ->
                        SongListItem(
                            track = track,
                            onClick = { viewModel.playTrack(state.tracks, index) }
                        )
                    }
                }

                // 专辑结果
                if (state.albums.isNotEmpty()) {
                    item {
                        Text(
                            "专辑 (${state.albums.size})",
                            style = MaterialTheme.typography.titleMedium,
                            modifier = Modifier.padding(16.dp)
                        )
                    }
                    items(state.albums.take(5)) { album ->
                        ListItem(
                            headlineContent = { Text(album.name) },
                            supportingContent = { Text(album.artist) },
                            leadingContent = {
                                Card(modifier = Modifier.size(48.dp)) {
                                    AlbumArt(
                                        uri = album.coverUri.takeIf { it.isNotEmpty() }?.let { Uri.parse(it) },
                                        size = 48.dp
                                    )
                                }
                            },
                            modifier = Modifier.clickable { onAlbumClick(album.albumId) }
                        )
                    }
                }

                // 艺术家结果
                if (state.artists.isNotEmpty()) {
                    item {
                        Text(
                            "艺术家 (${state.artists.size})",
                            style = MaterialTheme.typography.titleMedium,
                            modifier = Modifier.padding(16.dp)
                        )
                    }
                    items(state.artists.take(5)) { artist ->
                        ListItem(
                            headlineContent = { Text(artist.name) },
                            supportingContent = {
                                Text("${artist.albumCount} 张专辑 · ${artist.trackCount} 首歌曲")
                            },
                            modifier = Modifier.clickable { onArtistClick(artist.artistId) }
                        )
                    }
                }

                // 无结果
                if (state.tracks.isEmpty() && state.albums.isEmpty() && state.artists.isEmpty()) {
                    item {
                        Box(
                            modifier = Modifier.fillMaxWidth().padding(32.dp),
                            contentAlignment = Alignment.Center
                        ) {
                            Text("未找到相关结果", style = MaterialTheme.typography.bodyLarge)
                        }
                    }
                }
            }
        }
    }
}

文件清单总览

新建 (27 个文件)

周 文件路径（相对 io/kyonqi/musicplayer/）
1 data/entity/TrackEntity.kt
1 data/entity/AlbumEntity.kt
1 data/entity/ArtistEntity.kt
1 data/dao/TrackDao.kt
1 data/dao/AlbumDao.kt
1 data/dao/ArtistDao.kt
1 data/db/AppDatabase.kt
1 data/mapper/EntityMapper.kt
1 di/DatabaseModule.kt
1 scanner/MetadataReader.kt
1 scanner/LibraryScanner.kt
2 ui/component/AlbumArt.kt
2 ui/screen/LibraryScreen.kt
2 ui/screen/SongListScreen.kt
2 ui/screen/AlbumListScreen.kt
2 ui/screen/AlbumDetailScreen.kt
2 ui/screen/ArtistListScreen.kt
2 ui/screen/ArtistDetailScreen.kt
2 ui/screen/FolderBrowserScreen.kt
3 player/RepeatMode.kt
3 ui/screen/QueueScreen.kt
3 data/entity/PlaylistEntity.kt
3 data/entity/PlaylistTrackCrossRef.kt
3 data/dao/PlaylistDao.kt
3 ui/screen/PlaylistScreen.kt
3 ui/screen/PlaylistDetailScreen.kt
4 ui/screen/SearchScreen.kt

修改 (10 个文件)

周 文件路径 修改内容
1 gradle/libs.versions.toml +Room 版本和库
1 app/build.gradle.kts +Room 依赖 + schema export
2 ui/navigation/AppNavigation.kt 起始路由→library, +所有新路由
3 player/PlaybackState.kt +repeatMode, +shuffleEnabled
3 player/PlayerController.kt +toggleRepeatMode(), +toggleShuffle()
3 player/ExoPlayerController.kt 实现 repeat/shuffle
3 ui/screen/NowPlayingScreen.kt +封面+循环/随机/队列按钮
3 data/db/AppDatabase.kt version 2, +Playlist entities, +autoMigration
3 di/DatabaseModule.kt +PlaylistDao provider
4 ui/component/MiniPlayer.kt AlbumArt + 下一首按钮

废弃 (1 个文件)

文件路径 说明
ui/screen/FileBrowseScreen.kt 被 LibraryScreen 替代，不再路由

验证方式

每周完成后在模拟器上验证：

Week 1: 启动 app → 权限授予 → Logcat 确认 LibraryScanner 完成扫描 → 通过 App Inspection (Database Inspector) 确认 Room 表有数据

Week 2: 启动 app → 看到 LibraryScreen 4 个 Tab → 切换歌曲/专辑/艺术家/文件夹 → 专辑详情/艺术家详情能进入 → 封面显示

Week 3: 播放歌曲 → 循环/随机按钮状态切换 → 打开队列页 → 点击队列切歌 → 创建播放列表 → 添加歌曲

Week 4: MiniPlayer 显示封面+下一首 → 搜索能找到歌曲/专辑/艺术家 → 刷新按钮触发增量扫描

关键架构决策

  1. Entity vs Domain 模型分离：TrackEntity 是数据库表示，AudioFile 保持为 UI/播放器模型，通过 EntityMapper 桥接。避免 Room 注解泄漏到播放器层。

  2. 专辑标识：使用 (name, artist) 组合标识专辑，而非 MediaStore album ID（重新扫描后可能变化）。AlbumEntity.albumId 是 Room 自动生成的主键，用于导航路由。

  3. Tab 实现：4 个 Tab（歌曲/专辑/艺术家/文件夹）作为 LibraryScreen 内部的 composable 切换，不是独立的 NavHost 路由。仅详情页（AlbumDetail/ArtistDetail）是导航路由。

  4. 播放列表入口：从 LibraryScreen 的 TopAppBar 菜单或独立入口进入，保持 4-Tab 布局不变。

  5. 扫描策略：全量扫描清库重建，增量扫描对比 URI 差异。分批插入（每 50 条）提高性能。

说些什么吧！

beaudar