ManyCourse UI 底层开发指南（架构 / 状态 / 渲染 / 性能）

2.1 状态层#

规则：

• 跨页面共享的状态放单例（MainTabStore / UiSettings / Repository），不要塞进某个 Fragment。
• 派生值用 derivedStateOf 包住，只有当结果变化时才向下游传播失效（见 §5 R8 的实测收益）。
• 不要新增”能推导出来的状态”（例如”今天的课”由仓库实时算，见 CourseRepository.todayCourseCount）。

2.2 令牌层（改样式只改这里）#

文件：ui/theme/GlassTokens.kt

1
GlassMode  { Gaussian（默认）, Liquid }        // 设置页可切，持久化
2
GlassLevel { Bar, Panel }                      // Bar=页头/底栏；Panel=弹窗/表单
3
GlassEdge  { None, Top, Bottom }               // 分隔线画在哪一侧（None=完全不画）
4
GlassTokens                                    // 所有颜色/圆角/阴影/模糊半径的唯一来源
5
LocalGlassTokens / LocalGlassMode              // 由 ManyCourseTheme 提供

ManyCourseTheme 里依据 UiSettings.glassMode × isSystemInDarkTheme() 算出一份 GlassTokens 注入组合树，切换模式无需重启，所有组件自动重组。

令牌取值（浅色 / 深色）：

新增样式差异时，先加令牌，再在 glassOverlays 里消费；不要在组件里写 if (mode == Liquid)。

2.3 渲染层#

文件：ui/components/LiquidGlass.kt

2.4 组件层#

约定：新玻璃组件必须走令牌 + glassOverlays，不要自己写一套背景/描边。

2.5 动效层#

尊重系统设置：Motion.enabled()（= ValueAnimator.areAnimatorsEnabled()）为 false 时不挂动画/不设过渡。Compose 动画本身也跟随系统动画缩放。

2.6 适配层#

4.1 新增一个页面（Tab）#

1. 新建 XxxFragment：照抄 SelfFragment 结构（hazeSource 背景 + GlassHeader + 内容 Box（横向安全区）+ GlassBottomNav + 浮层），TAB_INDEX 取 0/1/2。
2. ManyCourseMain 的 tabFragments 与 TAB_* 常量同步加。
3. GlassBottomNav 的 items 列表加一项（图标放 AppIcons）。
4. 页面内容用 GlassCard 包卡片；文字用 MaterialTheme.colorScheme 角色色。

4.2 新增/调整样式#

只改 ui/theme/GlassTokens.kt：加字段 → 在 glassTokens(mode, dark) 两处（Gaussian / Liquid）都给值 → 在 glassOverlays 或组件里消费。

⚠️ 同步更新 app/src/test/java/com/tof/manycourse/GlassTokensTest.kt 的区间断言（该测试会拦住”面板比卡片还透""输入框和面板同色”这类退化）。

4.3 新增浮层（对话框/表单）#

1
@Composable
2
fun XxxDialog(visible: Boolean, onDismiss: () -> Unit) {
3
    GlassOverlay(visible = visible, onDismissRequest = onDismiss) {
4
        GlassPanel(cornerRadius = 24, modifier = Modifier.fillMaxWidth()) { /* 表单 */ }
5
    }
6
}

• 调用方常驻组合它（visible 控制），否则没有退出动画
• 表单状态在 LaunchedEffect(visible) { if (visible) { /* 重置 */ } } 里重置
• 面板内部不要用实时模糊（R3）

4.4 接入真实后端数据#

现有：api/HttpMethod.kt（OkHttp + JSON，同步 execute()）、gr_api/GRClassAPI.kt（loginSystem(account, password, url)），目前未被 UI 调用。数据都来自内存仓库。

接法建议（保持 UI 不变）：

1. 把 CourseRepository 的 courses: SnapshotStateList<Course> 保留为唯一 UI 数据源，网络层只负责填充它（courses.clear(); courses.addAll(remote)）→ 所有页面自动刷新。
2. 网络调用放 viewModelScope/Dispatchers.IO，不要在组合/主线程直接 execute()。
3. 增加三态（加载中 / 空 / 错误）时，用现有的静态玻璃组件包一层，例如空态参考 CalendarScreen 的”当日无课”卡片。
4. 登录成功后除 startActivity 外，把账号态放进单例（参考 UiSettings），供后续接口鉴权。
5. 字段口径见本文姊妹篇第 2 章（weekday 1=周一、节次 1~10 等）。

6.1 视觉改动的验收手法（无 UI 自动化也能客观验证）#

1. uiautomator dump：拿控件精确 bounds（adb shell uiautomator dump /sdcard/u.xml + adb pull），用于判断间距/内缩/贴边。
2. 逐像素剖面：adb exec-out screencap -p 存图后，用脚本沿 x 或 y 逐像素输出 RGB/亮度，找”台阶”与”暗带”。
   • 例：页头下边界 1px 细扫，可判断有没有分隔线残留
   • 例：y=0..6 细扫，可判断系统是否在物理顶边画了东西
3. aapt2 dump badging：验证多语言资源（应用名等）与图标是否按 locale 打包正确。
4. 临时调试技巧（用完必须还原）：把 ManyCourseMain 临时设为 exported="true" 以便直接启动主界面取图；把 showAddCourse 初值临时设为 true 以便打开浮层取图。

6.2 工具陷阱（重要）#

• 不要用 PowerShell 的 Set-Content/Out-File 改源码：该环境按 ANSI 落盘，会把含中文的 UTF-8 源文件写成无效 UTF-8（本次已因此损坏并重建 5 个文件）。改文件用 IDE/编辑器。
• MIUI 设备禁止 shell 注入输入：adb shell input tap/keyevent/text 报 SecurityException: INJECT_EVENTS，因此无法用 adb 驱动 UI；交互验证要么走插桩测试，要么靠上面的像素/层级手法。
• MIUI 可能拒绝安装测试 APK：INSTALL_FAILED_USER_RESTRICTED（需在开发者选项里打开”通过 USB 安装应用”），此时 am instrument 无法运行。
• 无线调试的 ddmlib 不稳：connectedAndroidTest 可能报 Unknown API Level / ShellCommandUnresponsiveException，改用上面的 adb install + am instrument 手动路径。

A.1 Course 课程模型#

A.2 节次-时间对照表#

A.3 Profile 个人信息#

A.4 后端 JSON 示例#

1
{
2
  "id": 1024,
3
  "name": "高等数学",
4
  "teacher": "王建国",
5
  "room": "教学楼 A-101",
6
  "weekday": 1,
7
  "startPeriod": 1,
8
  "periodCount": 2
9
}

如需支持单双周、调课等高级场景，建议扩展：

1
{
2
  "weeks": [1, 2, 3, 4, 5, 6, 7, 8],
3
  "weekType": "ALL"
4
}

weekType 取值："ALL"（全周）、"ODD"（单周）、"EVEN"（双周）。

A.5 后端接入要点#

接入原则：

• CourseRepository.courses（SnapshotStateList<Course>）是唯一 UI 数据源，网络层只负责 clear() + addAll()
• 网络调用放 Dispatchers.IO，不在主线程/组合内 execute()
• 项目已引入 okhttp 5.5.0 + logging-interceptor，可直接使用
• 离线兜底建议先接 Room 或 SharedPreferences 做本地缓存
• weekday=1 是周一、weekday=7 是周日，后端接口务必保持一致