239 lines
14 KiB
Markdown
239 lines
14 KiB
Markdown
# LumaPlayer 项目交接说明（移交下一 AI 开发者）
|
||
|
||
> 本文档是给下一位接手本项目的 AI 开发者/工程师的交接说明，请在动手前完整阅读。
|
||
> 交接时间：2026-08-28 ｜ 工作目录：`F:\lumaplayerAPP\lumaplayer` ｜ Git 分支：`master`
|
||
|
||
---
|
||
|
||
## 1. 项目是什么
|
||
|
||
**LumaPlayer** 是一款 Android（Kotlin + Jetpack Compose）的 **Emby 媒体库客户端**：
|
||
|
||
- 用户可添加 / 管理多个 Emby 服务器（支持 HTTP / HTTPS、登录认证、API Key）。
|
||
- 浏览媒体库（电影 / 剧集）、查看媒体详情、在线流媒体播放（Media3 ExoPlayer，支持 HLS）。
|
||
- 支持搜索、收藏、播放记录、图标库管理、主题 / 语言 / 玻璃风格设置等。
|
||
- UI 主打「液态玻璃 / 毛玻璃」设计风格，采用 Kyant0 Backdrop + 自定义降级玻璃。
|
||
|
||
目前处于**可构建、可运行**状态（Debug / Lint / Unit 通过，API 35 模拟器已回归），但**仍有未提交的工作区改动**（见第 6 节）。
|
||
|
||
---
|
||
|
||
## 2. 技术栈与版本
|
||
|
||
| 项 | 值 |
|
||
| --- | --- |
|
||
| 语言 | Kotlin + 少量 Java（Room 实体 / DAO） |
|
||
| UI | Jetpack Compose（Material 3） |
|
||
| 视频播放 | AndroidX Media3 ExoPlayer 1.5.1（+ HLS） |
|
||
| 网络 | Retrofit 2.11.0 + OkHttp 4.12.0 + Gson |
|
||
| 本地存储 | Room 2.8.4（数据库名 `emby_player.db`，当前 version 6） |
|
||
| 导航 | Navigation Compose 2.10.0 |
|
||
| 图片 | Coil 2.7.0 + Palette |
|
||
| 玻璃 / 液态 | `io.github.kyant0:backdrop:2.0.1`、`io.github.kyant0:shapes:1.2.1`、`top.yukonga.miuix.kmp:miuix-ui:0.9.4-rc01` |
|
||
| Gradle | 9.5.0（wrapper） |
|
||
| AGP | `com.android.application` 9.0.1 |
|
||
| Kotlin | 2.3.20（`org.jetbrains.kotlin.plugin.compose`） |
|
||
| compileSdk / targetSdk / minSdk | 35 / 35 / 24 |
|
||
| Java 兼容 | VERSION_21 |
|
||
|
||
> 仓库镜像源：`settings.gradle.kts` 使用阿里云镜像 + google() + mavenCentral()；Gradle 发行版走腾讯云镜像（`gradle-wrapper.properties`）。
|
||
|
||
---
|
||
|
||
## 3. 目录结构
|
||
|
||
```
|
||
lumaplayer/
|
||
├── settings.gradle.kts / build.gradle.kts / gradle.properties / local.properties
|
||
├── gradle/
|
||
│ ├── libs.versions.toml # 版本目录（当前只有少量条目）
|
||
│ ├── gradle-daemon-jvm.properties
|
||
│ └── wrapper/ # Gradle 9.5.0 wrapper（腾讯镜像）
|
||
├── memory/ # 项目记忆库（重要！见第 7 节）
|
||
│ ├── MEMORY.md # 记忆索引
|
||
│ ├── projects.md # 项目状态 / 变更历史
|
||
│ ├── 2026-08-2x.md # 每日变更记录
|
||
│ ├── lessons.md # 踩坑教训（必读）
|
||
│ └── infra.md # 基础设施速查
|
||
└── app/src/main/
|
||
├── AndroidManifest.xml
|
||
├── java/com/example/myapplication/data/ # Room 实体/DAO（Java）
|
||
│ ├── AppDatabase.java # DB 版本 6，含 1→6 迁移
|
||
│ ├── ServerEntity.java / ServerDao.java
|
||
│ └── IconLibraryEntity.java / IconLibraryDao.java
|
||
├── kotlin/com/example/myapplication/
|
||
│ ├── MainActivity.kt # 启动入口，初始化主题/语言/Repository
|
||
│ ├── MainApp.kt # 根 Composable，玻璃 Backdrop 源层 + 底栏 + NavHost
|
||
│ ├── data/ # Emby API 与业务数据层
|
||
│ │ ├── EmbyApiModels.kt / EmbyApiService.kt / EmbyRepository.kt
|
||
│ │ ├── EmbyServer.kt # EmbyServer 模型（fullUrl 拼装逻辑）
|
||
│ │ ├── ServerRepository.kt / IconLibrary.kt
|
||
│ ├── navigation/
|
||
│ │ ├── AppRoute.kt # 路由定义（sealed interface）
|
||
│ │ ├── AppNavHost.kt # 导航宿主 + 各目的地 Composable
|
||
│ │ └── NavigationTransitions.kt
|
||
│ ├── screens/ # 各页面
|
||
│ │ ├── HomeScreen.kt / LibraryScreen.kt / RecordsScreen.kt
|
||
│ │ ├── SearchScreen.kt / MediaDetailScreen.kt / VideoPlayerScreen.kt
|
||
│ │ ├── SettingsScreen.kt / SettingsChildScreens.kt
|
||
│ │ └── library/IconLibraryManagerScreen.kt
|
||
│ └── ui/
|
||
│ ├── AppTheme.kt # 主题 / 玻璃模式（Liquid/Frosted）全局状态与持久化
|
||
│ ├── AppLanguage.kt / AppBottomBar.kt / ImmersiveBackground.kt
|
||
│ ├── LiquidGlass.kt # 玻璃控件组件库（对话框、表单、菜单等）
|
||
│ ├── design/ # 设计系统
|
||
│ │ ├── LumaDesignSystem.kt # 颜色/令牌/GlassSpec/LumaGlassRuntime/rememberLumaLayerBackdrop
|
||
│ │ ├── LumaComponents.kt # 公共组件（加载/空态/按钮/分段等）
|
||
│ │ └── LumaIcons.kt
|
||
│ └── liquidglass/ # 液态底栏专有实现
|
||
│ ├── LiquidBottomTabs.kt / LiquidBottomTab.kt
|
||
│ └── DampedDragAnimation.kt / DragGestureInspector.kt / InteractiveHighlight.kt
|
||
└── res/
|
||
├── drawable/ # aurora_* 图标子集（大量 XML selector）
|
||
├── values/strings.xml（中文）、values-en/strings.xml（英文） # 双语
|
||
└── mipmap-*/ 图标
|
||
```
|
||
|
||
> 注意：应用包名/命名空间仍是默认的 `com.example.myapplication`，尚未改名为 `com.luma.player` 之类。是否改名属可选优化，改动会涉及 namespace、applicationId、Manifest、Room 相关路径。
|
||
|
||
---
|
||
|
||
## 4. 核心架构
|
||
|
||
### 4.1 数据层（`data/`）
|
||
|
||
- **Room 数据库 `emby_player.db`**：表 `servers` 与 `icon_libraries`。
|
||
- 版本 **6**，定义了 1→2、2→3、3→4、4→5、5→6 的迁移（见 `AppDatabase.java`）。
|
||
- `ServerEntity`（Java）字段：id、name、protocol、host、basePath、port、username、password、note、accessToken、userId、iconUrl、isSelected。
|
||
- protocol（http/https）是 5→6 迁移新增的**可空列**，模型中读取时兜底为 `https`。
|
||
- **Emby 业务层都由 `EmbyRepository`（object 单例）** 承载，主要能力：
|
||
- 认证：`AuthenticateByName`（用户名密码换 token）。
|
||
- 媒体库：`Library/MediaFolders`、`Users/{userId}/Items`、`Items/{itemId}/PlaybackInfo` 等。
|
||
- 图片 URL 拼装：`buildImageUrl` / `buildBackdropUrl` / `buildEpisodeImageUrl` / `buildPersonImageUrl`。
|
||
- 在线检测：`checkOnline`（`System/Info/Public`）。
|
||
- **播放进度回报**：内部用 `Channel` 串行队列 + 工作协程，把 开始 / 进度 / 停止 事件按 Emby Playback Check-in 约定上报；进度按 10 秒或位置变化阈值上报。
|
||
- `EmbyServer.fullUrl`：统一负责协议、端口、basePath 的拼接与 `http://`/`https://` 前缀去重。
|
||
|
||
### 4.2 导航（`navigation/`）
|
||
|
||
- `AppRoute`（sealed interface）定义路由：
|
||
- 根 Tab：`home`、`records`、`library`、`settings`、`search`。
|
||
- 子页：`detail/{serverId}/{itemId}`、`player/{serverId}/{itemId}/{seriesId}/{seasonId}`、`library/icons`、`settings/cache`、`settings/about`、`library/add-server`。
|
||
- `AppNavHost.kt` 承载各目的地 Composable；根 Tab 用 `popUpTo + launchSingleTop + saveState/restoreState` 切换。
|
||
- 细节页 / 播放器用 `launchSingleTop` 防止重复入栈。
|
||
- `rootTabIndex` / `isRootRoute` 判断当前是否根 Tab。
|
||
|
||
### 4.3 UI / 玻璃系统（重点，历史坑多）
|
||
|
||
- **玻璃模式**（`AppTheme.kt`）：`GlassMode.Liquid`（液态）/ `GlassMode.Frosted`（毛玻璃），用户手动在设置页选择，写入 SharedPreferences `app_settings` 持久化。
|
||
- **运行时判定**（`LumaDesignSystem.kt` 中的 `LumaGlassRuntime`）：
|
||
- `isBackdropSafe = SDK_INT >= S`（API 31+）。
|
||
- `useNativeBackdrop = glassMode == Liquid && isBackdropSafe`：API 31+ 且液态模式才走 Kyant `rememberLayerBackdrop`；否则返回 `null`（用渐变毛玻璃降级）。
|
||
- `rememberLumaLayerBackdrop()` 用 `key(AppTheme.glassMode)` 包裹，确保模式切换时刷新 Backdrop 与 GlassSpec 缓存。
|
||
- **关键渲染原则（务必遵守，否则会 RenderThread SIGSEGV 崩溃）**：
|
||
1. `layerBackdrop`（源层）与使用 `drawBackdrop` 的玻璃控件必须是**同一棵树下的兄弟层**，来源层只包底层内容（背景 / 视频 AndroidView），玻璃消费层在源层之外。
|
||
2. **禁止**在同一个 backdrop 捕获范围内再绘制使用同一 backdrop 的玻璃控件，会形成循环渲染 → RenderThread SIGSEGV。
|
||
3. **播放器不捕获 AndroidView**；页面捕获层只服务根 Tab / 底栏。
|
||
4. 弹出层 / 菜单必须用页面内部专属 source，不能直接消费包住整个页面的外层 source。
|
||
5. 降级玻璃的边缘高光要在 `drawContent()` 之前绘制，否则文字/图标会被高光洗白。
|
||
- **降级毛玻璃**：当 `useNativeBackdrop == false` 时，用 Compose 渐变 + tint/边框/圆角模拟玻璃（见 `LumaGlassLevel` / `GlassSpec`）。
|
||
- **设计系统**：`LumaColors`、`LumaShapes`、`LumaTypography`、`LumaMotion`、`LumaIcons` 等令牌；公共组件在 `LumaComponents.kt`（加载 / 空态 / 按钮 / 分段控件 / 输入框等）。
|
||
|
||
### 4.4 播放器（`screens/VideoPlayerScreen.kt`）
|
||
|
||
- 基于 Media3 ExoPlayer + `PlayerView`（AndroidView）。
|
||
- 支持：起播位置恢复、暂停/继续、进度拖拽、剧集/字幕菜单、全屏、播放进度回报（串行队列）。
|
||
- 当前工作区正在大改播放器 UI（见第 6 节）。
|
||
|
||
---
|
||
|
||
## 5. 构建与运行
|
||
|
||
```powershell
|
||
# 在项目根目录
|
||
.\gradlew.bat assembleDebug # Debug 构建
|
||
.\gradlew.bat lintDebug # 静态检查
|
||
.\gradlew.bat testDebugUnitTest # 单元测试
|
||
```
|
||
|
||
- Gradle 9.5.0 wrapper（腾讯镜像），AGP 9.0.1，Kotlin 2.3.20。
|
||
- SDK 路径在 `local.properties`（本机：`C:\Users\Administrator\AppData\Local\Android\Sdk`），该文件被 gitignore，不入库。
|
||
- `app/build.gradle.kts` 中有任务钩子：跳过 `AarMetadata` 相关 `check` 任务（`tasks.whenTaskAdded`）；`gradle.properties` 设 `android.aarMetadataCheck.enable=false`、`android.suppressUnsupportedCompileSdk=37.0`。
|
||
- 历史提交常在 `assembleDebug`、`lintDebug`、`testDebugUnitTest` 三者通过后收尾。真机 GPU 稳定性尚未充分验证（主要是 RenderThread）。
|
||
|
||
> 注意：`memory/infra.md` 里写的 JDK 路径是 macOS 路径（`/Applications/Android Studio.app/...`），那是历史环境信息，与当前 Windows 工作环境不一致，仅作参考。
|
||
|
||
---
|
||
|
||
## 6. 当前工作区状态（⚠️ 交接重点）
|
||
|
||
Git 分支 `master`，与 `origin/master` 同步。**存在 3 个文件未提交**：
|
||
|
||
| 文件 | 改动 |
|
||
| --- | --- |
|
||
| `app/build.gradle.kts` | 重新加入 `androidx.compose.material:material-icons-extended` 依赖 |
|
||
| `navigation/AppNavHost.kt` | `onPlaybackProgress` 回调签名简化：由外部传 `eventName` 改为内部根据 `paused` 自动映射为 `"Pause"` / `"TimeUpdate"` |
|
||
| `screens/VideoPlayerScreen.kt` | **大范围重构**（+518/-502）：播放器新增信号/电量/存储状态、连接状态监测、玻璃菜单、Material 图标等；改动与远端设计系统可能存在交互，**提交前务必重新编译 + 回归** |
|
||
|
||
> 最近 6 条提交：
|
||
> ```
|
||
> 07dc93c 收口玻璃交互与界面细节
|
||
> 8f59235 收敛玻璃边缘并清理图标库旧界面
|
||
> 594f47b 修复玻璃模式切换并统一设置组件
|
||
> dafac3e 取消液态玻璃安全门并收敛底栏绘制
|
||
> 485538f 收敛降级玻璃与页面状态恢复
|
||
> e76637c 完善降级玻璃界面并增加手动玻璃模式
|
||
> ```
|
||
|
||
**接手建议**：先 `git diff` 复核上述未提交改动是否完整、可编译，确认无误后再提交/推送；若与远端有冲突，按 `memory/lessons.md` 的三方合并经验处理（先暂存本地改动再合并，避免整文件覆盖）。
|
||
|
||
---
|
||
|
||
## 7. 项目记忆库（必读）
|
||
|
||
`memory/` 目录记录了完整开发历史与踩坑经验，**接手前建议通读**：
|
||
|
||
- `MEMORY.md` — 项目记忆索引、当前实现概览、稳定性策略。
|
||
- `projects.md` — 逐日项目状态与变更历史。
|
||
- `2026-08-26.md` / `2026-08-27.md` / `2026-08-28.md` — 每日详细变更与教训。
|
||
- `lessons.md` — **踩坑教训集（重点）**，尤其是 RenderThread SIGSEGV 的玻璃渲染约束、Room 迁移可空性、Emby 播放回报、导航状态等。
|
||
- `infra.md` — Git 远端地址等。
|
||
|
||
---
|
||
|
||
## 8. 已知要点 / 注意事项（给下一位开发）
|
||
|
||
### Git
|
||
- 远端：`https://git.leee.xin/beyond/lumaplayer.git`（origin，分支 master）。认证信息不要写入远端配置。
|
||
- 本地 `memory/` 保留本地参考素材（未跟踪，不随源码提交），删除前务必确认无引用。
|
||
- 清理遗留实现前，一律用全仓库引用检索确认目标未被活动页面使用。
|
||
|
||
### 玻璃渲染（崩溃风险最高）
|
||
- 任何修改涉及 `layerBackdrop` / `drawBackdrop` / 弹窗 / 菜单 / 播放器，都要遵守第 4.3 节原则，否则可能 RenderThread SIGSEGV。
|
||
- 玻璃模式是全局 Compose 状态，涉及 Backdrop / GlassSpec 缓存时必须把 `AppTheme.glassMode` 纳入 `remember` 的 key。
|
||
- 模拟器不一定用标准指纹，`isBackdropSafe` 已简化为只看 API 级别；真机 GPU 的液态玻璃稳定性仍需单独验证。
|
||
|
||
### Room
|
||
- 改 `ServerEntity` / 新增列时，迁移列定义必须与 Room 的 `notNull` 预期一致（参考 `protocol` 可空列的教训），否则旧库启动会崩。
|
||
|
||
### 播放回报
|
||
- 必须沿用 PlaybackInfo 返回的 `PlaySessionId` / `MediaSourceId`，开始/进度/停止事件串行化；回报协程不要绑到播放器 Composable 生命周期（返回页面会丢停止事件）。
|
||
|
||
### 无障碍 / 触控
|
||
- `BasicTextField` 的 `decorationBox` 无论是否为空都必须调用 `inner()`，否则破坏焦点/光标。
|
||
- 交互目标尽量 ≥ 48dp 触控范围。
|
||
|
||
---
|
||
|
||
## 9. 可能的后续方向（非必须，供参考）
|
||
|
||
若产品方向需要，可考虑：
|
||
- 包名/命名空间从 `com.example.myapplication` 规范命名。
|
||
- 真机 GPU 上逐一验证液态玻璃（RenderThread 稳定性）。
|
||
- 补充更完整的单元测试覆盖（目前测试较少）。
|
||
- 是否支持 Jellyfin（API 兼容）等，属于需求决策，需与产品确认，勿自行扩展。
|
||
|
||
---
|
||
|
||
*本文档基于 `memory/`、源码与 Git 状态整理生成，供下一位 AI 开发者快速上手。动手前请先确认第 6 节未提交改动。*
|