# ScheduleManagement

**Repository Path**: tjuwangli/ScheduleManagement

## Basic Information

- **Project Name**: ScheduleManagement
- **Description**: 教师教学日程管理系统
核心功能为：
1.日程管理
2.智能音量引擎
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-27
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 教师教学日程智能管理系统（Android 原生）

一个面向教师场景的 Android 日程管理应用，支持课程/会议日程管理、冲突检测、按周重复添加，以及到点自动切换静音并在结束后恢复音量。

基于 **Kotlin + MVVM + Jetpack Compose + Room + AlarmManager** 构建。

---

## 项目定位

这个项目主要有两个核心功能：

1. **日程管理**：快速创建、编辑、删除教师日程，并自动检查时间冲突。
2. **系统联动**：在上课前自动静音、下课后自动恢复，尽量降低人工操作成本。

如果你只是想要一个可直接运行的示例，或者想研究 Android 后台闹钟、前台服务、音量控制、Room 状态管理，可以从这个项目入手。

---

## 功能概览

- 日程管理
  - 新增日程（课程/会议名称、开始时间、结束时间、地点）
  - 编辑日程（长按卡片 -> 编辑）
  - 删除日程（长按卡片 -> 删除）
- 冲突检测
  - 新增、编辑、批量添加时自动校验时间重叠
- 按周重复添加
  - 单周、双周、自定义周数
  - 单周/双周支持手动设置“重复到第几周（1-20）”
- 智能音量引擎
  - 课前自动切换静音
  - 课后自动恢复铃声 / 通知 / 媒体音量与原始模式
  - 双闹钟补偿 + 失败重试，提升成功率
- 后台可用性自检
  - 检查并引导授权：勿扰访问、精确闹钟、忽略电池优化、通知权限
- 调试与可观测性
  - 调试日志页面，查看 API 调用与关键执行记录
  - 问题排查时可快速定位到调度和业务调用链路
- 导航结构
  - 左侧菜单：日程总览 / 新增日程 / 后台可用性自检 / 调试日志

> 说明：当前版本聚焦日程核心管理，不再包含教师实体管理页面。

---

## 技术栈

- 语言：Kotlin
- 架构：MVVM
- UI：Jetpack Compose + Material 3
- 本地数据库：Room
- 后台执行：AlarmManager + BroadcastReceiver + Foreground Service
- 日志：Timber + 内置调试日志面板
- 测试：JVM 单元测试

---

## 核心能力说明

### 1. 精准触发策略

针对每条日程会注册：

1. **静音主闹钟**：开始前 2 分钟
2. **静音补偿闹钟**：开始前 30 秒
3. **恢复闹钟**：结束时

如果执行失败，会进行最多 2 次延迟重试，间隔 20 秒。

### 2. 执行链路

一次到点执行的大致路径如下：

```text
AlarmManager -> BroadcastReceiver -> ForegroundService -> 轻量数据库查询 -> AudioManager 执行 -> 状态回写
```

这条链路已经针对触发时的数据库读取做了轻量化处理，目标是在不牺牲稳定性的前提下减少执行延迟。

### 3. 延迟优化思路

当前版本的优化重点是：

- 触发时只读取必要字段，避免整条实体加载
- 用统一的轻量查询替代“先查状态、再查实体”的双查询模式
- 把权限校验前置到设置页，而不是等到触发时再处理
- 保持精确闹钟、补偿闹钟和失败重试机制不变

---

## 对外 API 设计

为了让其他人更容易复用核心能力，项目新增了稳定的业务 API 层：

- `ScheduleManagementApi`

它将外部常用能力收敛为统一入口：

- `observeSchedules()`
- `addSchedule(...)`
- `addScheduleBatch(...)`
- `updateSchedule(...)`
- `deleteSchedule(...)`
- `rescheduleAllFuture()`

### 标准化业务结果

业务调用统一返回标准结果类型，便于外部调用方稳定处理：

- `Success`
- `PermissionDenied`
- `Conflict`
- `InvalidInput`
- `Failure`

这样 UI、日志、后续 SDK 化扩展都可以基于同一套结果模型处理，而不是散落着使用 `Boolean` 或 `Exception`。

---

## 运行截图

> - 首页 / 日程总览
> - 新增或编辑日程页面
> - 后台可用性自检页面
> - 调试日志页面

[首页截图](images/home.png)
[新增日程截图](images/add-schedule.png)
[后台可用性自检截图](images/permission-check.png)
[调试日志截图](images/debug-log.png)

---

## 快速开始

### 环境要求

- Android Studio：建议使用较新的稳定版
- Kotlin：与项目当前配置保持一致
- Android 设备：建议 Android 8.0 及以上

### 启动步骤

1. 克隆仓库
2. 使用 Android Studio 打开项目
3. 执行 Gradle Sync
4. 连接真机或选择模拟器
5. 运行 `app`

### 首次验证建议

1. 打开“后台可用性自检”
2. 按提示开启所需权限
3. 新增一条开始时间为“当前时间 + 3~5 分钟”的日程
4. 等待静音 / 恢复动作触发，观察日志与系统音量变化

---

## 权限说明

应用依赖以下系统权限：

- `ACCESS_NOTIFICATION_POLICY`：用于控制勿扰 / 静音相关能力
- `SCHEDULE_EXACT_ALARM`：用于尽量精准地触发日程闹钟
- `REQUEST_IGNORE_BATTERY_OPTIMIZATIONS`：用于降低后台被系统限制的概率
- `RECEIVE_BOOT_COMPLETED`：用于开机后重建闹钟
- `FOREGROUND_SERVICE` / `FOREGROUND_SERVICE_DATA_SYNC`：用于执行阶段保持前台运行
- `POST_NOTIFICATIONS`：用于通知展示与系统提示

### 如果权限未开启

- 部分日程可能无法按时触发
- 静音 / 恢复能力可能受限
- 应用会尽量给出引导，但无法完全绕过系统限制

---

## 目录结构

```text
app/src/main/java/com/example/schedulemanagement
├─ core
│  ├─ alarm
│  │  ├─ AlarmScheduler.kt
│  │  ├─ ScheduleAlarmReceiver.kt
│  │  └─ RescheduleReceiver.kt
│  ├─ api
│  │  ├─ ScheduleManagementApi.kt
│  │  ├─ ScheduleOperationExceptions.kt
│  │  ├─ ScheduleOperationResult.kt
│  │  └─ ScheduleResultMapper.kt
│  ├─ audio
│  │  └─ AudioHelper.kt
│  └─ debug
│     └─ DebugEventLog.kt
├─ data
│  ├─ db
│  │  ├─ AppDatabase.kt
│  │  ├─ converter/DateConverters.kt
│  │  ├─ dao/ScheduleAlarmState.kt
│  │  ├─ dao/ScheduleDao.kt
│  │  └─ entity/ScheduleEntity.kt
│  └─ repository/ScheduleRepository.kt
├─ service
│  ├─ ScheduleAlarmActionService.kt
│  └─ ScheduleForegroundService.kt
├─ ui
│  ├─ screen/home/MainScreen.kt
│  ├─ theme/{Color,Theme,Type}.kt
│  └─ viewmodel/MainViewModel.kt
├─ MainActivity.kt
└─ ScheduleManagementApp.kt
```

---

## 核心代码位置

- **应用入口与日志初始化**：`app/src/main/java/com/example/schedulemanagement/ScheduleManagementApp.kt`
- **主界面与汉堡菜单导航**：`app/src/main/java/com/example/schedulemanagement/ui/screen/home/MainScreen.kt`
- **页面状态与日程编辑逻辑**：`app/src/main/java/com/example/schedulemanagement/ui/viewmodel/MainViewModel.kt`
- **Activity 入口与 API / ViewModel 装配**：`app/src/main/java/com/example/schedulemanagement/MainActivity.kt`
- **稳定业务 API 层**：`app/src/main/java/com/example/schedulemanagement/core/api/ScheduleManagementApi.kt`
- **标准化结果类型**：`app/src/main/java/com/example/schedulemanagement/core/api/ScheduleOperationResult.kt`
- **结果映射与异常归一化**：`app/src/main/java/com/example/schedulemanagement/core/api/ScheduleResultMapper.kt`
- **日程调度、主/备静音、恢复闹钟、重试、权限能力判断**：`app/src/main/java/com/example/schedulemanagement/core/alarm/AlarmScheduler.kt`
- **闹钟广播转发到前台服务**：`app/src/main/java/com/example/schedulemanagement/core/alarm/ScheduleAlarmReceiver.kt`
- **系统时间变化 / 开机后重建闹钟**：`app/src/main/java/com/example/schedulemanagement/core/alarm/RescheduleReceiver.kt`
- **静音与恢复的真正执行、阶段日志、延迟统计**：`app/src/main/java/com/example/schedulemanagement/service/ScheduleAlarmActionService.kt`
- **前台保活服务**：`app/src/main/java/com/example/schedulemanagement/service/ScheduleForegroundService.kt`
- **勿扰 / 音量 / 恢复能力封装**：`app/src/main/java/com/example/schedulemanagement/core/audio/AudioHelper.kt`
- **调试日志中心**：`app/src/main/java/com/example/schedulemanagement/core/debug/DebugEventLog.kt`
- **Room 数据访问与状态写回**：`app/src/main/java/com/example/schedulemanagement/data/db/dao/ScheduleDao.kt`
- **轻量状态投影**：`app/src/main/java/com/example/schedulemanagement/data/db/dao/ScheduleAlarmState.kt`

---

## 调试与排障

### 调试日志页面

应用内新增了“调试日志”页，用于查看：

- API 层调用
- 调度行为
- 关键执行记录

如果你想排查“为什么没触发 / 为什么没恢复 / 为什么保存失败”，先看这里通常最直接。

### 建议排查顺序

1. 查看后台可用性自检是否全部通过
2. 查看调试日志是否有 API / 调度异常
3. 检查系统是否限制了后台自启动或电池优化
4. 查看精确闹钟权限是否可用

---

## 测试说明

项目已经包含可直接运行的 JVM 单元测试，主要覆盖：

- 闹钟动作执行时间线的阶段记录与耗时统计
- 业务结果映射：`PermissionDenied / Conflict / InvalidInput / Success`

建议你后续继续补充以下测试：

- `ScheduleRepository` 的冲突判断
- 重复周次生成逻辑
- 更完整的 API 错误映射

---

## 运行说明

1. Gradle Sync
2. 运行 `app` 到 Android 8.0+ 设备
3. 优先开启：
   - 勿扰访问
   - 精确闹钟
   - 忽略电池优化
4. 新增一条“开始时间 = 当前 + 3~5 分钟”的日程进行验证

---

## 兼容性说明

Android 厂商系统对后台调度限制较多，无法保证绝对零误差触发。当前版本通过“主闹钟 + 补偿闹钟 + 失败重试”方案，尽量降低漏触发概率。

如果你在某些机型上遇到触发偏差，通常优先检查：

- 精确闹钟权限是否开启
- 电池优化是否已忽略
- 勿扰权限是否可用
- 系统是否限制后台自启动