SleepIn

简体中文

English

简体中文

English

外观

常见开发问题与排障指南

约 722 字大约 2 分钟

2026-03-20

1. 背景与目标

这篇文档用于快速定位“跑不起来、刷不出来、更新不生效”这类高频问题。

建议使用方式：先按问题类别定位，再按“现象 -> 原因 -> 排查步骤”执行。

2. 排障入口（先看树）

相关文件
├─ gradle/libs.versions.toml                     # 依赖版本与兼容约束
├─ app/src/main/java/com/kurosu/sleepin/data/local/SleepInDatabase.kt
├─ app/src/main/java/com/kurosu/sleepin/ui/screen/
├─ app/src/main/java/com/kurosu/sleepin/widget/
└─ docs/SleepIn-Docs/docs/dev/
   ├─ build-debug-windows.md
   ├─ data-model-room.md
   ├─ ui-viewmodel-compose.md
   └─ widget-workmanager.md

3. 构建与依赖问题

Q1: Duplicate class found 或 Cannot resolve ...

  • 现象：.\gradlew assembleDebug 失败，出现类冲突或符号无法解析。
  • 常见原因：新增依赖和现有 Compose/Kotlin/KSP 版本不兼容。
  • 排查步骤：
    1. 检查 gradle/libs.versions.toml 的相关版本是否成套兼容。
    2. 执行 .\gradlew clean 后重试构建。
    3. 对照 build-debug-windows.md 的基础环境确认 JDK 与 SDK 版本。

4. Room 与数据库问题

Q2: Room cannot verify the data integrity

  • 现象：修改 Entity 后 App 启动崩溃。
  • 常见原因：数据库结构变化但版本与迁移策略未同步。
  • 排查步骤：
    1. 检查 SleepInDatabase.kt 中 @Database(version = ...)。
    2. 开发阶段若允许清库，确认当前是否走了 destructive migration 策略。
    3. 检查 app/schemas/com.kurosu.sleepin.data.local.SleepInDatabase 是否与改动一致。

5. UI 状态与 Compose 问题

Q3: 数据已经写入，但界面不刷新

  • 现象：数据库已有新数据，页面仍显示旧内容。
  • 常见原因：ViewModel 只做一次性查询，未持续收集 Flow。
  • 排查步骤：
    1. 检查 Repository 是否暴露 Flow。
    2. 检查 ViewModel 是否把流映射为 StateFlow 并持续收集。
    3. 检查 Screen 是否使用 collectAsStateWithLifecycle()。
    4. 参考文档：docs/SleepIn-Docs/docs/dev/ui-viewmodel-compose.md

Q4: 页面重复弹窗/重复导航

  • 常见原因：把副作用写在 Composable 主体，而非事件流中。
  • 修复建议：使用 SharedFlow + LaunchedEffect 处理一次性事件。

6. Widget 刷新问题

Q5: 小组件修改后没有更新

  • 现象：改了 Widget UI 代码但桌面显示不变。
  • 常见原因：没有触发刷新任务，或系统缓存了旧视图。
  • 排查步骤：
    1. 检查是否调用 WidgetRefreshScheduler.requestImmediateUpdate(context)。
    2. 检查 WidgetRefreshWorker 是否持续重试。
    3. 手动移除并重新添加小组件，排除 Launcher 缓存影响。
    4. 参考文档：docs/SleepIn-Docs/docs/dev/widget-workmanager.md

7. CSV 导入问题

Q6: 导入成功提示但无课程

  • 常见原因：CSV 行被解析器判定为非法并写入错误列表。
  • 排查步骤：
    1. 查看导入报告中的行级错误信息。
    2. 核对星期、节次、周次格式是否符合项目规则。
    3. 参考文档：docs/SleepIn-Docs/docs/dev/business/csv-integration.md

8. 通用排障顺序（建议）

  1. 先复现并记录最早报错日志。
  2. 再定位所属层（构建、Data、Domain、UI、Widget、CSV）。
  3. 再回到对应文档章节按步骤排查。
  4. 最后补充测试或最小复现，避免同类问题再次出现。