zijunchiang
08b5b438b9
- 凭据条目拆分为 Gitea(代码主仓库) / Gitee(仅发布 Release) 两条 - 明确 ~/.git-credentials-gitee(600) 由 credential.https://gitee.com.helper 引用， 只用于 API 建 Release/传附件，不得用于推送源码（规则 2） - 纯文档改动，版本号保持 1.4.0
269 lines
22 KiB
Markdown
269 lines
22 KiB
Markdown
# 麦动 KTV — 项目开发约定
|
||
|
||
> 本文件供后续开发（含 AI 助手会话）遵循，优先级高于默认习惯。
|
||
|
||
## 一、代码同步与发布策略（2026-09-14 更新）
|
||
|
||
**代码主仓库：Gitea `https://gitea.kasugano.cn/zijunchiang/maidong-ktv`**
|
||
|
||
| 远端 | 地址 | 用途 |
|
||
|---|---|---|
|
||
| `origin` | `https://gitea.kasugano.cn/zijunchiang/maidong-ktv.git` | ✅ 代码主仓库，**唯一的代码同步目标** |
|
||
| `gitee` | `https://gitee.com/zijunchiang/maidong-ktv.git` | 📦 **不推代码**，只用于发布 Release；仓库内只保留 README 文档 + Releases 附件 |
|
||
|
||
### 四条硬性规则
|
||
|
||
1. **推送失败只重试 3 次**：Gitea 不可用（网络不通／服务器故障／返回非 200）时，最多重试 **3 次**
|
||
（间隔约 60s）。3 次仍失败就**停止重试**，改动保留为本地 commit，**留到下次一起同步**
|
||
（不要无限重试、不要为了"推上去"而改推 Gitee）。恢复同步时直接 `git push origin master`
|
||
把积压的 commit 一并推上即可。
|
||
2. **Gitee 不再同步代码，只发布版本**：Gitee 仓库保持「仅 README 文档 + Releases 附件」状态，
|
||
**禁止推送源码**（`pre-push` 钩子会拦截 `gitee.com`）。Gitee 上只做一件事：创建 Release 并上传 APK 附件。
|
||
3. **每次更新版本号 +1**：完成一次修改就把版本号递增（`versionName` 与 `versionCode` 同步递增），
|
||
例如 `1.3.0` → `1.3.1` → `1.3.2`。不要在同一个版本号下反复改动交付。
|
||
4. **发布是手动操作**：**未收到明确的「发布新版本」指令时，默认只在本地打包测试**——
|
||
产物按内部测试约定命名 `maidong-ktv-<版本>-<改动说明>-双ABI-release.apk`，
|
||
**不创建 Release、不上传附件、不推送 tag、不在 Gitee 建 Release**。
|
||
只有收到发布指令后，才按「发布新版本」小节在 Gitea（以及需要的 Gitee）建 Release。
|
||
> ⚠️ **不要混淆"交付"与"发布"**：向 Gitea `git push origin master` 同步代码（规则 1）、
|
||
> 本地构建/签名出 `*-release.apk`（规则 4 前半段）**都不算发布**，不需要、也不得顺带
|
||
> 建 Release / 打 tag / 传附件。发布动作只有三个：建 Release、打 tag、上传附件；
|
||
> 三者的触发条件只有一个 —— **收到明确的人工发布指令**。若不确定是否已发布，
|
||
> 用 `GET /repos/{owner}/{repo}/releases` 与 `/tags` 核对，不要凭"打过包"推断。
|
||
|
||
- 凭据：
|
||
- **Gitea**（代码主仓库）：访问令牌 `dsh-sync-20260926`（2026-09-26 数据迁移后重建；可在 Gitea
|
||
「设置 → 应用 → 访问令牌」随时吊销），存放于 `~/.git-credentials-gitea`（权限 600），
|
||
由本仓库级 `credential.helper` 引用；
|
||
- **Gitee**（仅发布 Release，按规则 2 不推代码）：访问令牌存放于 `~/.git-credentials-gitee`
|
||
（权限 600），由全局 `credential.https://gitee.com.helper` 引用；**只用于 API 建 Release /
|
||
传附件**，不得用于推送源码。
|
||
- 账号密码不写入仓库配置。
|
||
|
||
### 推送方式
|
||
|
||
```bash
|
||
cd /home/zijun/dsh_data/maidongktv/maidong-ktv
|
||
git push origin master # origin = Gitea（唯一的代码同步目标）
|
||
```
|
||
|
||
> Gitee 不参与代码同步；确需回推文档时用 `git push --no-verify gitee master`，
|
||
> 但按规则 2 正常情况下不应执行。
|
||
|
||
### 运行时端点（已全部迁移到 Gitea）
|
||
|
||
App 内部两处端点已指向 Gitea（随本版 APK 生效）：
|
||
|
||
- `AppUpdateManager.kt`：`gitea.kasugano.cn/api/v1/repos/zijunchiang/maidong-ktv/releases/latest`（App 内检查更新）
|
||
- `KtvJsBridge.kt`：`gitea.kasugano.cn/zijunchiang/maidong-ktv/raw/branch/master/app/src/main/assets/mobile/ktv_api.js`（JS 热更新）
|
||
|
||
> 注意：Gitea 的 raw 规范路径是 `/raw/branch/<分支>/<文件>`；`/raw/<分支>/<文件>` 会 303 跳转。
|
||
> Gitea 的 raw 与 release 下载对**无 User-Agent** 的请求同样放行（App 裸 socket 可直连）。
|
||
|
||
### 发布新版本（Gitea Release）
|
||
|
||
```bash
|
||
TOKEN=$(sed -E 's|https://zijunchiang:([^@]+)@.*|\1|' ~/.git-credentials-gitea)
|
||
|
||
# 1) 创建 Release（tag 需高于当前 versionName 才会提示更新）
|
||
curl -X POST -u "zijunchiang:$TOKEN" -H "Content-Type: application/json" \
|
||
-d '{"tag_name":"v1.2.6","name":"麦动KTV V1.2.6","body":"更新说明","target_commitish":"master"}' \
|
||
https://gitea.kasugano.cn/api/v1/repos/zijunchiang/maidong-ktv/releases
|
||
|
||
# 2) 上传 APK 附件（用返回的 release id；附件名必须 ASCII）
|
||
curl -X POST -u "zijunchiang:$TOKEN" \
|
||
-F "attachment=@麦动KTV-V1.2.6-release.apk" \
|
||
"https://gitea.kasugano.cn/api/v1/repos/zijunchiang/maidong-ktv/releases/<id>/assets?name=maidong-ktv-V1.2.6-release.apk"
|
||
```
|
||
|
||
> ⚠️ **附件文件名必须为 ASCII**：Gitea 1.27 的规范下载路径
|
||
> `/releases/download/<tag>/<文件名>` 对非 ASCII 文件名返回 404（`/attachments/<uuid>` 直链虽可用，
|
||
> 但 `releases/latest` API 返回的是规范路径）。因此 Gitea 上的附件用
|
||
> `maidong-ktv-V1.2.x-release.apk` 这类 ASCII 名；本地留存的发布包仍可命名
|
||
> `麦动KTV-V1.2.x-release.apk`。
|
||
>
|
||
> 上传 22MB APK 约需 70s，注意命令超时设置。
|
||
|
||
## 二、构建与产物
|
||
|
||
### 构建（release，双 ABI）
|
||
|
||
```bash
|
||
cd /home/zijun/dsh_data/maidongktv/maidong-ktv
|
||
. /home/zijun/dsh_data/maidongktv/env.sh # 导入 JAVA_HOME / ANDROID_HOME / PATH
|
||
./gradlew assembleRelease
|
||
```
|
||
|
||
产物：`app/build/outputs/apk/release/app-release.apk`（已由 `app/build.gradle` 的 signingConfig 签名）
|
||
|
||
### 本机工具链（2026-09-26 数据迁移后重建）
|
||
|
||
数据迁移后的本机是**纯净环境且当前用户无 sudo**，因此工具链全部装在用户态，
|
||
不要再用系统路径（`/usr/lib/jvm/...` 不存在）。统一入口：
|
||
|
||
```bash
|
||
. /home/zijun/dsh_data/maidongktv/env.sh # 已加入 ~/.bashrc，新开 shell 自动生效
|
||
```
|
||
|
||
| 组件 | 路径 | 来源 |
|
||
|---|---|---|
|
||
| JDK 17 | `/home/zijun/tools/jdk-17`（Temurin 17.0.20.1） | Adoptium tarball 解包 |
|
||
| git | `/home/zijun/tools/bin/git`（包装脚本 → `/home/zijun/tools/gitroot/usr/bin/git`） | `apt-get download git` + `dpkg -x` |
|
||
| Android SDK | `/home/zijun/Android/Sdk`（与 `local.properties` 的 `sdk.dir` 一致） | `cmdline-tools` + `sdkmanager` |
|
||
| 已装 SDK 包 | `platforms;android-35`、`build-tools;34.0.0`、`build-tools;36.0.0`、`platform-tools` | sdkmanager |
|
||
| 签名密钥 | `/home/zijun/dsh_data/maidongktv/ktv_keystore.jks`（仓库外，勿入库） | 数据迁移 |
|
||
|
||
- `git` 包装脚本是必需的：deb 内 git 的编译期 `exec-path` 写死为 `/usr/lib/git-core`
|
||
（无 root 无法创建），包装脚本显式设置 `GIT_EXEC_PATH`/`GIT_TEMPLATE_DIR` 后才找得到
|
||
`git-remote-https` 等子命令。
|
||
- 迁移会把仓库文件权限改成 744（git 记为 1288 个纯 mode change、0 行内容变化）。
|
||
遇到大量 `mode change 100644 => 100755` 时，按索引恢复权限即可，不要当成内容改动：
|
||
`git ls-files -s -z | ... chmod`（或临时 `git config core.fileMode false`）。
|
||
|
||
### 签名与校验（单独签名/改名时）
|
||
|
||
```bash
|
||
BT=/home/zijun/Android/Sdk/build-tools/36.0.0
|
||
$BT/apksigner sign --ks /home/zijun/dsh_data/maidongktv/ktv_keystore.jks \
|
||
--ks-key-alias ktv --ks-pass pass:123456 --key-pass pass:123456 \
|
||
--out 目标名.apk app/build/outputs/apk/release/app-release.apk
|
||
$BT/apksigner verify 目标名.apk
|
||
```
|
||
|
||
- 密钥：`/home/zijun/dsh_data/maidongktv/ktv_keystore.jks`（仓库外，勿入库）
|
||
- APK 命名约定：`麦动KTV-V<版本号>-release.apk`（对外发布）/ `maidong-ktv-<版本>-<改动说明>-双ABI-release.apk`（内部测试）
|
||
|
||
### 版本号
|
||
|
||
- `app/build.gradle`：`versionName "1.4.0"` / `versionCode 16`
|
||
- App 内显示统一用纯版本号（不加 `(versionCode)` 括号）
|
||
|
||
## 三、关键实现约束（避免踩坑）
|
||
|
||
- **歌曲源**：`app/src/main/assets/mobile/ktv_api.js` 的 `CONFIG.HOSTS`（多源自动排序，失败源沉底）
|
||
- **JS 热更新**：改动 `ktv_api.js` 必须同步提升 `KTV_BRIDGE_API: N` 标记（JS 与 `KtvJsBridge.kt` 两处校验），否则设备仍用缓存旧脚本
|
||
- **曲库**：只走官方 Muse 同步（`MuseDbSync`），不再依赖代码仓库数据库文件
|
||
- **曲库同步时效**：默认 **30 天**（`DatabaseBootstrapper.SYNC_TTL_DAYS`）。未到期启动**不联网**、直接用本地曲库；到期后才查询服务器版本，有更新才下载。时效起点记录在 `db_sync_at.txt`，由 `DatabaseBootstrapper.markSynced()` 写入（下载成功或校验为最新时）。设置页「曲库 → 更新」为手动强制检查（绕过时效，仅在服务器版本更新时下载）
|
||
- **麦克风**：`MicActivator` 常驻占用输入通道（TV/投影需占用后才有演唱声音输出），外接设备热插拔会自动重建
|
||
- **设备 MAC**：统一由 `DeviceMac` 解析**当前在用网卡**的硬件地址（12 位小写十六进制）。优先
|
||
`wlan*`/`eth*`/`en*`，忽略虚拟/蜂窝/VPN 接口；Android 6 起 `WifiInfo.getMacAddress()` 恒为
|
||
`02:00:00:00:00:00`，因此直接读 `NetworkInterface.getHardwareAddress()`；读出 `02:00:00:00:00:00`
|
||
或全 0 视为无效。读取失败回退 `DeviceMac.FALLBACK_MAC`（历史抓包值），保证身份永不为空。
|
||
结果按进程缓存，网络切换时由 `remoteNetworkMonitor` 调用 `DeviceMac.refresh()` 重解析。
|
||
消费方：`KtvJsBridge.DEVICE_MAC`（JS 端 `mac`）、whoami 心跳的 `_mac`/`androidid`/`_cid`
|
||
（抓包时三者同值，保持一致）
|
||
- **播放信息实时刷新**：`refreshNowPlayingLabels()` 是播放界面左上角「当前播放 / 下一首」、首页播放条、
|
||
旧版播放区与顶部状态栏的**唯一**刷新入口，只在文本变化时写 View；已挂到 `lyricTicker`（500ms）上，
|
||
因此队列变化（本地点歌 / 扫码点歌 / 自动切歌）最迟 500ms 内必然同步。新增播放信息展示时请复用它，
|
||
不要另起刷新路径
|
||
- **远程日志**：接入 GlogCenter 集中式日志（HTTP 接口，单条 JSON）。**域名属敏感信息，不得写入任何文档**
|
||
（端点常量见代码 `MiliLog.ENDPOINT`，需要时查代码，勿在 README/AGENTS 中记录域名）。字段：
|
||
`system`/`date`/`text`/`servername`/`serverip`/`clientip`/`loglevel`/`traceid`/`user`；`date` 必须为
|
||
`yyyy-MM-dd HH:mm:ss.SSS`，否则按时间检索异常。其中 `serverip` = **主机 IP**（公网出口 IP，
|
||
由 `MiliLog.PUBLIC_IP_URL` 查询，结果缓存 5 分钟、失败 1 分钟后重试，查询在独立后台线程，
|
||
绝不在主线程发起），`clientip` = **客户端 IP**（设备当前网卡获取到的局域网 IP，由
|
||
`MiliLog.updateDeviceContext(ip = ...)` 注入，网络变化时自动刷新并顺带复核公网 IP）。
|
||
客户端为 `MiliLog`（有界队列 + 后台线程 + 失败重试），调用点 `MiliLog.info/notice/warn/error`
|
||
保持不变。启动上报（`reportDeviceBootInfo()`）只采集这 10 项：包名、版本号、安装时间、品牌、型号、
|
||
设备名、Android 版本、CPU 架构、内核版本、屏幕分辨率
|
||
- **网络状态与断网恢复**：`KtvNetworkMonitor`（object，走 `ConnectivityManager` 回调、不轮询）
|
||
维护全局 `online`；`MainActivity.onNetworkStateChanged()` 负责：
|
||
- 断网 → 播放页右上角 `fullScreenNetworkBadge` 显示「网络未连接」（在全屏控制层 header 内、
|
||
标题右侧，不遮挡右上角二维码）；
|
||
- 恢复 → `refreshNetworkState()`：重解析网卡 MAC + 日志上下文、**重建歌曲源会话**、
|
||
复位 `Eac19WindowGuard`、重启本地点歌服务并刷新二维码、自动重试断网期间失败的下载（最多 8 首）。
|
||
换网/换 IP 时 `remoteNetworkMonitor` 走同一个 `refreshNetworkState()`（静默，不弹提示）。
|
||
⚠️ **「断网重连后再也下载不了、日志却显示歌曲源获取成功」的根因**：
|
||
`SongApiClient.clearTokenCache()` 原本是**空实现**，JS 侧 `window.api.tokens` 与
|
||
`_apiInitPromise` 会被一直复用；而歌曲源按「出口 IP + device」识别、试用窗口也记在出口 IP 上，
|
||
断网/重连（尤其换出口 IP）后旧 token 已失效 —— 取址这一步看起来成功，真正下载却 403/失败。
|
||
现在 `clearTokenCache()` 会真正下发 `KtvJsBridge.resetApiSession()`
|
||
（置空 `window.api` 与 `_apiInitPromise`，下次取址重新构造 API 实例、回到默认源顺序并重新登录）。
|
||
下载层的网络类失败由 `SongOkDownloadManager` 结合 `KtvNetworkMonitor.online` 与异常类型/HTTP 0
|
||
判定并记入 `networkFailed`，网络恢复后由 `retryNetworkFailed()` 自动重试（手动取消的不入集合）。
|
||
⚠️ 顺带修掉一个隐患：离线时 `localIp()` 为空，原 `remoteNetworkMonitor` 会每 5s 误判「IP 变化」
|
||
而反复重启本地点歌服务（并连带触发刷新）；现已加空值短路，离线只等网络回调。
|
||
- **播放界面右上角二维码**：跟随全屏控制层一起出现/隐藏 —— 在
|
||
`setFullScreenChromeVisible()` 里同步 `fullScreenQrOverlay` 的可见性，`updateFullScreenQrOverlay()`
|
||
新建时按 `fullScreenChromeVisible` 初始化。**不要**再按「手机是否在点歌」自动隐藏
|
||
（原 `qrAutoHideMonitor` 已删除，扫码弹窗里的对应提示文案也一并删除）
|
||
- **远程页面滑杆(触控)**：`<input type="range">` **绝不能被 `<label>` 包裹** —— label 会把
|
||
内部任意位置的点击转发给 range，表现为"点轨道/点文字就跳值"。行容器用 `<div class="audio-row">`
|
||
/ `<div class="eq-band">`；CSS 选择器也随之用类选择器而不是标签选择器。
|
||
另外滑杆元素本身高度设 32px（触控目标够大），视觉细轨道由
|
||
`::-webkit-slider-runnable-track` / `::-moz-range-track` 绘制，滑块 22px + 5px 边框。
|
||
`attachThumbOnlyDrag()` 仍作为第二道防线（命中滑块才放行原生拖动，容差按 32px 滑块算）
|
||
- **远程搜索性能**：曲库 DB 有 **67 万首 / 约 1GB**（`muse.db`），搜索是 I/O 密集操作。
|
||
实测（同一台机器直连该 DB，`rec_score` 复合索引齐全）：
|
||
- 中文 `name_trim LIKE '%kw%'`：热态 **2~280ms**（走 `idx_rec_score` 顺序扫描 + 早停，无临时排序）
|
||
- 拼音 `name_cap/name_full GLOB 'kw*'`：热态 **0.2~150ms**（前缀范围扫描 + 临时 B-tree 排序；
|
||
`A*` 这类高频前缀会扫很多行），冷态（首次读 1GB 文件）可达 **1~15s**
|
||
- 歌手检索（`EXISTS` + singers LIKE）：热态 **34~70ms**
|
||
结论与对策：**瓶颈在冷态 I/O 与重复查询**，因此
|
||
1) 设备端加 `remoteSearchCache`（LRU 24 条 = 最近 4 个查询 × 6 页，TTL 60s，曲库刷新时清空），
|
||
同一「类型+关键词+页码」直接复用 JSON，翻页与重复搜索不再查库；
|
||
2) 手机端：搜索请求用 `AbortController` 取消旧请求、同关键词不重复请求、
|
||
首页返回后**预热第 2 页**（把设备缓存捂热）、搜索期间暂停 1s 的状态轮询避免抢 I/O。
|
||
⚠️ 不要试图用「一次多取几页」来省请求：实测 `LIMIT 201` 的代价远高于 `LIMIT 21`
|
||
（`name_full GLOB` 301 行 6.2s vs 21 行 0.7s，冷态），会把体验做得更差
|
||
- **焦点填充与「纯色遮罩层」**：`TvFocusStyler.install()` 会把背景整体换成**不透明**红→橙渐变，
|
||
作为遥控器焦点/按下的反馈（`prepareTvFocusableTree(window.decorView)` 与对话框的
|
||
`installTree(decorView)` 会遍历整棵树施加）。按钮/Tab/卡片/list 行需要这个反馈；但
|
||
**大面积展示型表面绝不能加** —— 否则触摸一次（`state_pressed`）就用纯色盖住整屏内容。
|
||
已排除的表面：播放画面宿主（`home_player_container` / `player_container`）、视频层
|
||
（`persistentVideo`）、播放触摸层（`playerTouchOverlay`）、全屏播放容器（`R.id.container`）、
|
||
启动加载遮罩（`databaseLoadingOverlay`）、手机点歌二维码浮层、全屏音量面板。
|
||
**新增此类铺满/覆盖播放画面的 View 时，必须调用 `TvFocusStyler.suppressFill(view)`**
|
||
- **音量默认值**：`KtvStore.DEFAULT_MUSIC_VOLUME`（当前 85%）是唯一来源，
|
||
`KtvStore` 默认值与 `optInt` 兜底、`MainActivity.musicVolume` 初值、调音弹窗「默认」按钮
|
||
都引用它；远程页面 `assets/mobile/{index.html,app.js}` 的默认值需手工跟改
|
||
- **音量控制（只控 App 输出，不动系统音量）**：`musicVolume`(0-100) 是 **App 内部输出音量**，
|
||
统一在 `applyPlaybackMode()` 内按线性系数施加到播放器（`KtvVideoView.setPlaybackVolume` /
|
||
`selectAudioChannel`）与副音轨播放器（`vocalPlayer` / `embeddedVocalEngine`）。
|
||
**严禁调用 `AudioManager.setStreamVolume` / `adjustStreamVolume` 修改系统音量**。
|
||
入口只有两处，且都必须收敛到 `applyPlaybackMode()`：**「调音」弹窗**（`showTuningDialog()`，
|
||
播放界面与主界面右上角共用同一个弹窗）的音量横向控制杆、远程控制-音乐音量
|
||
（`remoteAudio()` 的 `musicVolume`）。**声音设置弹窗里不再有音量滑杆与均衡器入口**
|
||
（避免同一功能两套入口），它只保留「切到点播歌曲时音量/原伴唱」这类策略选择。曲线是纯衰减（100% 即 unity gain），不做系统级增益；
|
||
设备最终响度仍取决于系统音量，App 不再替用户改动它
|
||
- **音频均衡器**：内核 `KtvEqualizer`（参考开源项目 OpenEQ，`Turbofan3360/OpenEQ`，GPL-3.0 的
|
||
`EQUtils.kt`）——直接用系统 `android.media.audiofx.Equalizer`，**按设备真实频段数与增益范围自适应**
|
||
（频段是动态生成的，不要写死 5 段）。默认把 EQ 挂到**实际播放会话**：
|
||
`player.audioSessionId()` / `vocalPlayer.audioSessionId` / `embeddedVocalEngine.audioSessionId()`
|
||
（IJK 的原生 `IjkMediaPlayer_getAudioSessionId` 返回真实 AudioTrack 会话）。会话会随歌曲变化，
|
||
因此由 500ms 的 `lyricTicker` → `syncEqualizerSessions()` 周期对齐，消失的会话延迟 3s 释放。
|
||
`globalMix`（会话 0）是设备不支持按会话挂载时的显式开关，会影响本机所有声音，默认关闭。
|
||
均衡器已并入**「调音」弹窗**（`showTuningDialog()`，自上而下：音量横向杆 → 均衡器开关 →
|
||
预设 → EQ 频段横向杆，每个频段一行：频率 | 滑杆 | 增益），主界面右上角与播放界面「调音」
|
||
是同一个弹窗；另有远程点歌页面「均衡器」卡片（`PATCH /api/v1/player/equalizer`，状态随
|
||
`GET /api/v1/state` 的 `equalizer` 字段下发）。预设：App 内为「自定义/流行/摇滚/舞曲」
|
||
（`appPresetNames()`，手动改频段即转「自定义」并自动保存），远程页面额外保留「标准」
|
||
供「恢复标准」使用。设置持久化在 `KtvStore.eq*`；
|
||
**刻度固定 30 档**（`eqSliderSteps`），步进由设备增益范围均分，保证 0 dB 一定可选中。
|
||
音量与频段共用自绘控件 `EqSlider`（横向），已 `suppressFill` 并自绘焦点/调节描边。
|
||
⚠️ **它的交互是刻意定制的，不要换回 SeekBar**：
|
||
- **遥控**：焦点在控件上时方向键**不**改数值（先让焦点在控件间移动）；按**确认键进入调节态**
|
||
（描边变亮变粗）后方向键才调值，**再按确认键退出**调节态；调节态下 BACK 只退出调节态、
|
||
不关弹窗；失焦自动退出。这是"需按确认键才可调节控件点、同理按确认键退出控制"的实现。
|
||
- **触控**：必须按住滑块（控件点）才拖动，点轨道空白不跳值（`hitsThumb` 命中判断，
|
||
容差 `thumbTouchSlop`）。远程点歌页面同规则，见 `attachThumbOnlyDrag()`（app.js，对
|
||
`input[type=range]` 做指针命中判断，未命中则 preventDefault）
|
||
- **公放随机清单**：`RandomPlayQueue`（纯内存单例）——随机续播不再「每次现随机挑一首」，
|
||
而是一次性生成打乱顺序的临时清单，一轮内不重复；播完一首 `markFinished` +1；
|
||
`next()` 每次都重新比对曲库，**自动吸纳新增歌曲**、剔除已删除歌曲；一轮播完自动开新一轮。
|
||
**不显示**（界面不展示）、**不关联已点清单**（`orderQueue` 完全独立，随机歌曲不入队）、
|
||
**App 退出即清理**（`onDestroy` 里 `isFinishing` 时 `clear()`，不落盘）
|
||
- **弹窗分辨率自适应**：TV/投影/盒子的分辨率与 density 差异很大（1280x720、1920x1080，
|
||
density 1.0~2.5），固定 dp 尺寸在矮屏上会被屏幕裁切。统一用 `fitDialogToScreen(dialog, scroll,
|
||
content, preferredWidthDp, …)`：宽度取 `min(preferredWidthDp, 屏幕宽*0.94)`，高度把内容所在的
|
||
ScrollView 限制为 `屏幕高*0.92 - 弹窗标题/按钮框架(chromeDp)` —— **不要再用 `WRAP_CONTENT` 作为
|
||
弹窗高度**。内容高度由「屏幕预算 - 固定区高度」反推（调音弹窗的 EQ 频段区就是这样自适应），
|
||
预算不足时弹窗内滚动而不是被裁掉。已应用：调音弹窗、扫码点歌弹窗、声音设置弹窗。
|
||
新增/改动弹窗时请复用该 helper，别再写死 `setLayout(w, WRAP_CONTENT)`。
|
||
⚠️ **文字行必须 wrap_content**：`label()` 自带 6dp 上下内边距，固定矮行（曾用 18/28/42dp）
|
||
会把文字裁掉 —— 这是"文字显示不全"的根因。做法是「文字行 wrap_content + 只有无文字区域
|
||
才用计算高度」：调音弹窗里唯一可伸缩的是 EQ 频段区，采用**两遍 fit**（先 `panel.measure()`
|
||
实测内容高度，超出预算就把频段区减掉，再调 `fitDialogToScreen`），这样收缩的永远是频段区
|
||
而不是文字；频段区下限 dp(96)，再放不下才滚动。大字体(系统字体缩放)同理自动兜住
|
||
- **仓库可见性**：Gitea 仓库保持 **public**（若后续把 App 更新/热更新端点迁到 Gitea，非 public 会导致 403）
|