# Dawn-Course

**Repository Path**: YeMiao_cats/Dawn-Course

## Basic Information

- **Project Name**: Dawn-Course
- **Description**: 一个免费、轻量的开源课程表app
- **Primary Language**: Kotlin
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: https://github.com/HF-CYGG/Dawn-Course
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-01-31
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Android, Kotlin, Open-source, Material-design

## README

# Dawn Course（破晓课程表）

> 免费、开源（GPL-3.0）、无广告、本地优先的 Android 课程表应用  
> 专注离线可用、数据可迁移与长期可维护的现代 Android 工程实践（Kotlin + Compose + Clean Architecture）

## 项目定位

破晓课程表（Dawn Course）是一款面向学生日常使用的课程表应用，提供从教务系统导入、课程管理、提醒与个性化显示等核心能力。项目坚持“用户数据主权”与“本地优先”原则：在不强制云账号的前提下，尽可能做到离线可用、可备份、可迁移。

## 核心原则

本项目严格遵循以下原则：

1. **永久免费 & 开源**：遵循 GPL-3.0 协议。
2. **零干扰**：无广告、无会员强绑定、无非必要推送。
3. **本地优先**：核心功能离线可用，不强制依赖云端服务。
4. **可迁移**：提供多种导入方式，并支持备份与还原能力。
5. **可维护**：以可测试性、可替换性、长期维护为第一优先级。

## 主要功能

### 课程与展示

- 周视图 / 日视图课表展示，支持滑动切换
- 课程信息管理：名称、地点、教师、颜色等
- 多学期管理与切换
- 动态壁纸背景：支持高斯模糊与亮度调节
- Material You（Material 3）动态取色
- 桌面小组件（Jetpack Glance）：日/周视图组件，适配系统主题

### 智能导入与更新

- 教务系统导入：适配新正方、强智、青果等主流系统（WebView + JS 解析）
- ICS 文件导入：支持标准日历格式（.ics）
- 覆盖导入机制：导入时清理旧数据，避免混淆
- 脚本云同步：导入/自动更新脚本支持从云端拉取，并具备本地缓存与内置 Assets 兜底

### 同步与备份（本地优先）

- 本地备份与还原：支持导出/导入备份文件，并在还原前展示备份预览信息
- WebDAV 同步（可选）：用于跨设备备份文件上传/下载，支持自动同步策略

### 贴心提醒与维护

- 上课提醒
- 自动静音/免打扰策略（按设置联动）
- 应用内更新检查与提示

## 快速开始（开发者）

### 环境要求

- **JDK**：17+
- **Android Studio**：Hedgehog / Iguana 或更新版本
- **Android SDK**：API 34（Compile SDK）

### 构建步骤

1. 克隆仓库：

   ```bash
   git clone https://github.com/HF-CYGG/DawnCourse.git
   ```

2. 用 Android Studio 打开项目根目录，等待 Gradle Sync 完成
3. 连接真机或启动模拟器
4. 运行 `app` 模块

可选（推荐）：安装 Git 钩子以确保提交前自动执行质量检查：

```bash
./gradlew installGitHooks
```

## 技术栈与版本

以下版本信息以仓库默认配置为准；完整依赖以 `gradle/libs.versions.toml` 为最终来源。

- **语言**：Kotlin 1.9.23
- **UI**：Jetpack Compose（Material 3，BOM 2024.02.00）
- **架构**：MVVM + Clean Architecture（App / Domain / Data / UI 分层）
- **依赖注入**：Hilt 2.51
- **异步**：Coroutines + Flow
- **数据库**：Room 2.6.1（可选 SQLCipher 加密）
- **网络**：Retrofit + OkHttp
- **图片加载**：Coil
- **导航**：Navigation Compose
- **小组件**：Jetpack Glance 1.1.1
- **脚本引擎**：QuickJS
- **后台任务**：WorkManager

## 项目结构

项目采用多模块结构，强调边界清晰与依赖方向可控：

```text
DawnCourse/
├── app/                # 壳工程：Application 初始化 / DI / 导航
├── core/               # 核心层
│   ├── data/           # 数据层：Repository 实现 / DB / DataStore / Sync
│   ├── domain/         # 领域层：UseCase / Model（纯 Kotlin，可测试）
│   └── ui/             # 通用 UI：主题 / 组件
├── feature/            # 功能层：导入/课表/设置/小组件/更新等（相互解耦）
└── server/             # 静态资源服务（用于提供云端脚本下载等）
```

### 分层依赖（强制）

- UI → ViewModel → UseCase → Repository → DataSource
- feature 模块之间不直接依赖
- UI 不直接访问 DAO
- ViewModel 不持有 Android Context

## 脚本体系（导入相关）

导入与自动更新依赖一组可独立演进的 JavaScript 脚本，用于 WebView 交互与 HTML 提取/解析：

- 内置脚本（兜底）：`app/src/main/assets/js/`
- 云端脚本（可更新）：`server/html/scripts/js/`
- 获取策略：云端 → 本地缓存 → Assets 兜底（保证离线可用与可控升级）

如需贡献新的教务系统脚本，请参考：

- [教务系统解析脚本开发指南](parser_contribution_guide.md)

## 常见问题（FAQ）

- **为什么强调本地优先？**  
  因为课程数据属于用户个人数据资产，应当离线可用、可迁移、可备份，并尽量避免强绑定云账号。
- **WebDAV 是必须的吗？**  
  不是。WebDAV 同步是可选能力，用于跨设备备份文件的上传/下载，不影响核心功能离线使用。

## 贡献指南

欢迎提交 Issue 与 Pull Request。

- 反馈 Bug：请提交 Issue，并尽量附带复现步骤、设备信息与日志
- 功能建议：请提交 Issue 说明使用场景与期望行为
- 代码规范：
  - 保持代码整洁，通过必要的构建与静态检查
  - 关键逻辑请添加中文注释
  - 遵守模块边界与依赖方向

## 开源协议

本项目采用 [GNU General Public License v3.0 (GPL-3.0)](LICENSE) 开源协议。