SleepIn

简体中文

English

简体中文

English

外观

常见开发问题与排障指南

约 1280 字大约 4 分钟

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/3.business/3.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/2.architecture/5.widget-workmanager.md

7. CSV 导入问题

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

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

Q7: 作息表 CSV 在编辑页导入失败

  • 现象：已有作息表编辑页点击导入或调用导入逻辑后提示不支持。
  • 常见原因：当前策略只允许“新建作息表”场景导入。
  • 排查步骤：
    1. 确认当前 scheduleId 是否为空（新建态）。
    2. 检查 UI 是否按 isEditMode 显示正确按钮分支。
    3. 参考文档：docs/SleepIn-Docs/docs/dev/3.business/4.csv-integration.md

Q8: 作息表 CSV 报“只能导入一个作息表”

  • 现象：导入时出现“CSV must contain exactly one schedule name”。
  • 常见原因：同一个 CSV 文件内出现多个不同的作息表名称。
  • 排查步骤：
    1. 检查 作息表名称/ScheduleName 列是否全表一致。
    2. 检查是否混入了另一份作息表数据。
    3. 参考文档：docs/SleepIn-Docs/docs/dev/3.business/4.csv-integration.md

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

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

9. 上课提醒与通知权限问题

Q9: 已开启上课提醒，但没有弹出通知权限授权框

  • 现象：Android 13+ 设备中，设置页开启提醒后，系统没有弹出“允许通知”对话框。
  • 常见原因：
    1. 当前系统不是 Android 13+（低版本不会弹该权限框）。
    2. 用户未开启上课提醒开关，权限请求条件未命中。
    3. 用户曾拒绝且选择“不再询问”，系统不再自动弹窗。
  • 排查步骤：
    1. 确认系统版本（Build.VERSION.SDK_INT >= 33）。
    2. 确认设置中已开启“上课提醒”。
    3. 检查 MainActivity.kt 是否触发 RequestPermission(POST_NOTIFICATIONS)。
    4. 若曾“拒绝且不再询问”，到系统应用通知设置手动开启。
    5. 参考文档：docs/SleepIn-Docs/docs/dev/4.feature/2.class-reminder.md

Q10: 已开启提醒且已授权，但课前没有收到通知

  • 常见原因：
    1. 当前不在学期进行中（开学前/学期结束后）。
    2. 当天没有符合周次规则的课程（WeekType 过滤后为空）。
    3. 当前时间不在“课前 N 分钟到开课前”的提醒窗口。
    4. 同一节课通知已被去重逻辑记录。
  • 排查步骤：
    1. 检查 CourseReminderWorker 中学期周次判定与课程筛选结果。
    2. 检查 reminderMinutes 与课程节次时间映射是否正确。
    3. 检查应用内上课提醒开关与系统通知开关是否都开启。
    4. 参考文档：docs/SleepIn-Docs/docs/dev/4.feature/2.class-reminder.md

更新日志

2026/5/18 12:59
查看所有更新日志
  • 2a526-docs(readme): update screenshot layout于

版权归属：Kurosu-Ti01

许可证：署名-非商业性 4.0 国际 (CC-BY-NC-4.0)