# Moodify Music 2.0 工程日志

## 1. 发布身份

- 产品：Moodify Music Android
- 版本：2.0.0
- versionCode：20
- 固定日期：2026-08-15
- 发布性质：内部体验固定版
- 应用包名：`com.moodify.app`
- 最低 Android：API 26
- 目标 Android：API 36
- 源码基线：Git `09bac4c6d72cb979ee2491e064b0a84f247ab661`
- 构建说明：由上述 Git 基线及 2026-08-15 工作区中的 Moodify 2.0 Android 变更构建。

Moodify 2.0 将公开 App 收敛为一个以 Play 为中心的聆听产品。听觉分析、生产处理和复杂工程能力继续保留在云端、核心包或 Auditory Intervention Laboratory 中，不在移动播放界面暴露第二套权威流程。

## 2. 2.0 相对 1.0 的核心变化

### 2.1 产品结构

1. App 主流程从多功能工作台收敛为单一 Play 体验。
2. 主界面使用全屏纵向播放器，上下滑动直接切换公共曲库歌曲。
3. 左侧抽屉只保留三个私人子界面：歌单、收藏、个人主页。
4. 生产、分析、版权、协作和上传等复杂界面不再占据公开播放器主流程；相关历史实现保留在 Ear Workbench 或云端边界内。

### 2.2 视觉与品牌

1. 统一为夜间聆听导向的深色视觉：黑色/深夜蓝背景、紫蓝渐变、唱片意象。
2. 启动页采用 Moodify 自有波形 Logo 和“好听的音乐，由 AI 创作”品牌表达。
3. 桌面图标更换为深色版，适配夜间场景。
4. 锁屏媒体卡片提供独立浅色 Moodify 图稿，由 MIUI/Android 根据媒体图稿生成卡片配色。
5. 播放页移除专辑编号、创作者和多余说明，仅保留歌名及必要控制。

### 2.3 云端公共曲库

1. 播放内容从每次本地导入改为连接 Moodify 云端公共曲库。
2. App 通过公开 Music API 获取可播放曲目，音频通过 HTTPS 与 HTTP Range 传输。
3. 本地保留曲库元数据缓存；网络暂时不可用时可使用已缓存目录信息。
4. 公共曲库队列与用户私人歌单严格分离：播放过歌曲不会自动进入歌单。

### 2.4 播放内核与连续切歌

1. Media3 ExoPlayer 从逐首重新装载升级为完整播放列表，由同一播放器实例管理队列。
2. 首次进入等待用户点击 Play；开始播放后，上下切歌保持连续播放。
3. 用户主动暂停后，再切歌仍保持暂停，不擅自恢复播放。
4. 播放按钮显示稳定的“用户播放意图”，不再因缓冲瞬态闪烁。
5. 切歌触发从“页面完全停稳后”提前到“手势目标确定时”，降低手势确认延迟。
6. 内存前向缓冲提高，保留少量后向缓冲，降低快速切换与返回时的重新加载。

### 2.5 十首歌曲磁盘缓存

1. 新增 Moodify 播放磁盘缓存，不把十首音频全部放入运行内存。
2. 后台预取接下来最多 10 首歌曲的起播数据，每首先取约 2 MB。
3. 播放过程中继续写入已消费音频数据，重复播放优先命中本地缓存。
4. 磁盘缓存总上限为 512 MB，使用 LRU 自动淘汰最久未使用内容。
5. 缓存异常时自动回退网络，不阻断播放主流程。
6. 缓存位于 Android App Cache，用户清理缓存或系统空间回收时允许被删除。

### 2.6 私人收藏与歌单

1. 播放按钮与收藏按钮旁新增“＋”入口。
2. 用户可以把当前歌曲加入已有歌单。
3. 用户可以现场创建新歌单并立即加入当前歌曲。
4. 同一首歌曲不会重复加入同一歌单。
5. 歌单和收藏改为独立本地持久化数据，App 重启后继续保留。
6. 歌单页面只展示用户主动创建的私人集合，不再错误展示整个播放队列。

### 2.7 手势导航

1. 从屏幕左侧边缘向内滑：打开左侧抽屉。
2. 从屏幕右侧边缘向内滑：返回 Play。
3. 屏幕中间横向触摸不触发页面导航，降低误操作。
4. 子界面返回 Play 加入定向滑动和淡入过渡，减少瞬间跳转感。
5. 系统返回键继续作为系统级和无障碍兜底，不在界面增加多余按钮。

### 2.8 后台与锁屏播放

1. 保留 MediaSession、前台播放服务、通知栏控制和后台续播。
2. 锁屏媒体会话识别完整歌曲队列。
3. 锁屏提供上一首、播放/暂停、下一首控制。
4. 锁屏、通知栏和 App 内上下切歌共享同一 Media3 播放状态。
5. 锁屏卡片的最终圆角、透明度和控件排列由 Android/MIUI 系统决定。

## 3. 数据与权限边界

- 公共曲库是云端内容池；私人歌单和收藏由用户主动产生。
- App 不直接连接 PolarDB，也不持有内部服务密钥。
- 移动端不运行 MAMSE 全套实验分析，不把实验性判断包装为生产事实。
- 2.0 的本地缓存仅用于播放性能，不改变云端歌曲资产的权威身份。

## 4. 验证记录

### 自动验证

- `:app:testDebugUnitTest`：通过。
- `:app:assembleDebug`：通过。
- APK 签名验证：通过。
- 1.0 与 2.0 签名证书一致，可覆盖安装并保留 App 数据。

### 小米真机验证

- 设备：Xiaomi M2102J2SC（thyme）。
- ADB 覆盖安装：成功。
- App 启动：成功，`com.moodify.app/.MainActivity` 为前台 Activity。
- 版本：`versionName=2.0.0`，`versionCode=20`。
- MediaSession：识别 5 首测试歌曲完整队列。
- 本地播放缓存：真机目录已建立并开始写入。

## 5. 已知边界

1. 本发布包使用 Android Debug 证书，定位为内部体验固定版，不是应用商店生产签名包。
2. 首次播放某首歌曲仍受网络、DNS、TLS、服务器首包和 WAV 文件体积影响；十首起播缓存会降低后续切歌延迟，但不承诺所有网络条件下绝对零延迟。
3. 私人歌单和收藏当前保存在设备本地，尚未进行账号云同步。
4. Android/MIUI 负责锁屏媒体卡片最终布局，App 只提供队列、控制命令、标题与浅色品牌图稿。
5. 系统或用户清理 App 缓存后，歌曲缓存会重新建立；私人歌单和收藏不存放在 Cache 目录。

## 6. 安装、升级与回滚

### 从 1.0 升级

直接安装 2.0 APK 即可。包名和签名一致，正常覆盖安装会保留已有 App 数据。

### 回滚到 1.0

Android 默认阻止从更高 versionCode 降级。内部调试设备可使用 ADB 的允许降级选项；如卸载 2.0 后安装 1.0，本地歌单、收藏和连接数据可能丢失。回滚前应先保留必要数据。

## 7. 生命周期结论

Moodify Music 1.0 建立了 Android 云端播放和发布基线；2.0 完成了面向夜间专注聆听的产品收敛，并建立公共曲库、私人歌单、连续手势播放、锁屏队列和有限磁盘缓存的一体化 Play 主线。此版本作为独立发布物封存，不覆盖 1.0。
