lumaplayer/memory/lessons.md

教训

• 中：本地目录原先没有 .git，不能直接 pull；应先获取远端历史，以共同基线做三方合并。
• 中：合并后需编译检查跨文件 API；本次发现并修复资源别名、Backdrop 导入及底部导航 mainTabs 缺失问题。
• 低：远端 URL 不保留账号密码，认证信息只用于本次读取。
• 高：Kyant0 Backdrop 的 layerBackdrop 捕获范围内不能再直接绘制使用同一 backdrop 的玻璃控件，否则可能形成循环渲染并在 RenderThread 触发 SIGSEGV；页面源层与玻璃控件必须分离，视频源层只包 AndroidView。
• 中：远端提交与本地大范围未提交 UI 改动并行时，先暂存本地改动、合并远端非冲突文件，再恢复本地改动并手动吸收远端业务行为，避免整文件覆盖。
• 高：Backdrop 的来源层与消费玻璃必须是同级兄弟层；菜单外部手势层也必须位于菜单内容下方，否则打开手势会误触发关闭。
• 中：Backdrop 的玻璃效果是否明显取决于来源内容；纯白卡片上无法显示明显折射，需依靠仓库的高光、阴影和 lens 边缘表现，不能用普通白色背景冒充。
• 高：Root Overlay 若直接消费外层页面 layerBackdrop，外层 source 会把 Overlay 再捕获形成 RenderNode 循环；必须为局部页面建立只包裹底层内容的 source，并让 Overlay 作为兄弟 consumer。
• 高：Room 实体由 Java 可空字段映射时，迁移列定义必须与 Room 的 notNull 预期一致；新增 protocol 使用可空列并在模型读取时回退 HTTPS，否则旧数据库启动会因迁移校验失败崩溃。
• 低：Compose 非 Composable 回调中不能直接调用 stringResource；需在 Composable 作用域先缓存文案，再传入回调。
• 低：全量 lintDebug 在当前环境分析阶段长时间无输出且无报告；最终以 assembleDebug、git diff --check、资源键和关键残留静态检查收尾。
• 高：本地 AndroidLiquidGlass-kmp 的 lens 和高光默认样式会创建 Android 13 AGSL RuntimeShader；出现 RenderThread SIGSEGV 时不能只改 Kotlin 异常处理，应移除 RuntimeShader/折射链并以 Backdrop blur、vibrancy、Plain highlight 和 Compose 渐变降级。
• 高：根 layerBackdrop 不应包住播放器等原生 View；子页面应避免把同一个 source 同时作为父捕获层和子消费层，否则即使没有 AGSL 也可能形成 RenderNode 循环。
• 高：Android Emulator 的 Kyant RenderEffect/GraphicsLayer 采样可能直接在 RenderThread 触发 SIGSEGV，Kotlin 异常无法兜底；应按运行环境在进入 drawBackdrop/layerBackdrop 前降级，且播放器永不捕获 AndroidView。
• 高：仅跳过 drawBackdrop 仍可能提前创建 rememberGraphicsLayer；Backdrop 来源应在不安全设备上直接返回 null，源层和消费层都不能挂载。
• 高：模拟器不一定使用标准 sdk_gphone 指纹，RenderThread 防护还应检查 x86 ABI、board 和 emu 设备名；详情页绘制回调中的 Compose 状态也必须提前快照。
• 中：Emby 播放回报必须沿用 PlaybackInfo 返回的 PlaySessionId/MediaSourceId，并将开始、进度、停止事件串行化；把回报协程绑定到播放器 Composable 生命周期会在返回页面时丢失停止事件。
• 高：液态玻璃不能以“API 版本高”作为唯一启用条件；Kyant Backdrop 还需通过设备安全门和运行帧率门控，低帧率/不安全 GPU 必须在创建 LayerBackdrop 前降级，避免 RenderThread 崩溃。
• 高：玻璃模式已改为用户手动选择，不能再用 Choreographer 帧率变化自动切换；但模拟器/低版本仍必须在创建 Kyant LayerBackdrop 前保留硬件安全门，避免 RenderThread SIGSEGV。
• 中：降级玻璃的边缘高光应在 drawContent() 之前绘制；否则公共玻璃容器中的文字和图标会被高光层洗白。
• 高：用户明确要求真实液态玻璃时，不能继续保留设备/模拟器安全门；当前仅保留 API 31+ 能力判断，底栏原生 Backdrop 必须先绘制容器与选中胶囊，再绘制清晰图标/文字，避免内容被二次采样覆盖。该取舍需在实体机 GPU 上继续验证 RenderThread 稳定性。
• 中：玻璃模式是全局 Compose 状态；涉及 rememberLayerBackdrop 或玻璃规格的缓存必须把 AppTheme.glassMode 纳入重建边界，否则设置副标题会变但材质不变。
• 低：清理页面遗留实现前必须用全仓库引用检索确认；私有且无调用的旧 UI 可以删除，活动页面保留原数据/弹窗实现。
• 低：BasicTextField 的 decorationBox 无论是否为空都必须调用 inner()；占位文案应与真实输入内容叠放，否则会破坏焦点和光标绘制。