# NextClass

**Repository Path**: dcesama/next-class

## Basic Information

- **Project Name**: NextClass
- **Description**: No description available
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-09
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NextClass / 下节课

面向学生的轻量课表提醒工具（Android）。支持手机端离线识别 Excel 课表，并联动系统日历提醒。

## 在线体验

> 直接下载安装包（已签名，Android 7.0+）：[下载 NextClass-1.0.apk](https://gitee.com/dcesama/next-class/releases/download/v1.0.0/NextClass-1.0.apk)

## 运行截图

<table>
  <tr>
    <td><img src="img/Screenshot_2026-09-09-18-00-41-728_top.dcesama.nextclass-edit.jpg" width="240"></td>
    <td><img src="img/Screenshot_2026-09-09-18-00-55-285_top.dcesama.nextclass.jpg" width="240"></td>
    <td><img src="img/Screenshot_2026-09-09-18-01-02-094_top.dcesama.nextclass.jpg" width="240"></td>
  </tr>
  <tr>
    <td><img src="img/Screenshot_2026-09-09-18-01-12-531_top.dcesama.nextclass.jpg" width="240"></td>
    <td><img src="img/Screenshot_2026-09-09-18-01-18-169_top.dcesama.nextclass-edit.jpg" width="240"></td>
  </tr>
</table>

## 特性

- **Excel 自动导入**：手机直接选择 `.xlsx` / `.xls`，自动识别课程、星期、时间、周次，无需在电脑上转换；App 全程纯本地运行。
- **系统日历提醒**：课程写入手机原生日历（`CalendarContract`），上课前按设定时间提前提醒；集成 Android `WorkManager`，每周自动滚动同步，长期不打开 App 也不会断档。
- **本地 / 粘贴 JSON 导入**：支持选择本地 `schedule.json` 文件，也支持直接把 JSON 粘贴进 App 导入（网络不便时同样可用），并内置示例数据一键体验。
- **周视图**：1-16 周可滑动切换，本周课程按周次正确过滤（不会出现“幽灵课”），自动定位到今天并高亮。
- **课程详情**：点击卡片查看课程信息、压缩周次显示（`1-16 周 / 单周 / 双周`）、本周是否有课的说明；支持一键复制教室、跳转系统日历查看对应日程。
- 课程与日历同步完全遵循“Room 本地库为唯一数据源，系统日历仅作为提醒执行器”的架构。

## 架构

在原有 JSON 导入流程上增加手机端 Excel 识别：

```
Excel / JSON 文件或粘贴 JSON → 离线识别与校验 → Room 事务替换课表 → 系统日历提醒
可选 PC 工具：XLSX → schedule.json
```

目录结构：

```
app/        Android 端（Kotlin + Jetpack Compose + Room + DataStore + WorkManager）
tools/      PC 端课表转换工具（Python，XLS → schedule.json）
开发文档.md  产品技术开发文档 V1.0（接口契约 / 数据流的权威定义）
```

## 快速开始

### 1. 准备 Excel 课表（也可使用 JSON）

把 `.xlsx` 或 `.xls` 文件传到手机，即可直接导入。支持两种布局：

- 横向周课表：表头包含至少三列“周一、周二、周三……”（也支持“星期一”及 Mon 等英文名称），左侧填写时间或节次。课程单元格逐行填写课程名、教师、教室、周次；同一格多门课以空行分隔。
- 课程明细表：每行一条课程，表头为“课程名称、星期、时间、周次、教师、教室”；可用“开始时间、结束时间”替代“时间”，也可填写“节次”。教师、教室和周次可以省略。

识别规则：

- 读取第一个包含可识别课表表头的工作表，不混合不同学生的工作表。
- 支持纵向合并的课程单元格，按首尾行时间计算时段，只导入一次。跨多个星期的课程合并格需先拆分。
- 周次支持 `1-16周`、`1-8,10-16周`、`单周`、`1-16周(双)`，限 1-16 周；缺省为每周。教师、教室缺省为“待定”。
- 优先使用 `08:20-09:55` 等明确起止时间。仅有节次时使用项目默认作息（见导入页面）；学校作息不同时请补充明确时间。不能识别时间时拒绝导入。
- Excel 原文件最多 16 MB，解压内容最多 32 MB，每张表最多 5000 行、128 列。不支持加密文件、图片课表或任意教务模板；课程错误提示包含工作表和行号。
- 成功后替换当前课表；解析失败不修改原课表。导入后核对时间并设置“开学周一日期”。

如需继续使用电脑端转换工具（可选）：

```bash
cd tools
pip install -r requirements.txt
python xls_to_schedule.py 课表.xlsx -o schedule.json --student 张三
```

支持合并单元格、单/双周、`1-16 周` 等常见格式的自动解析，并允许交互式补录“课本/备注”。详见 [tools/README.md](tools/README.md)。

### 2. 导入（Android 端）

在 App 的「导入」页：

- **选择文件**：选择 Excel 或 JSON 文件，自动识别并导入；或
- **粘贴 JSON**：直接把文件内容粘贴进文本框导入（无网络时优先推荐）。

### 3. 设置与提醒

- 「设置 → 开学周一日期」：选择本学期开学第一周的周一（默认取本周周一），用于计算第几周。
- 「设置 → 提醒时间」：选择课前提前提醒分钟数。
- 「设置 → 同步到日历」：授权日历写入权限后写入“本周 + 未来两周”的日程；之后每周自动滚动更新。

## 开发

环境：JDK 17+、Android SDK（compileSdk 37, minSdk 24）。

```bash
gradlew :app:assembleDebug          # 构建 debug APK
gradlew :app:assembleRelease        # 构建 release（R8 压缩）
gradlew :app:testDebugUnitTest      # 运行单元测试
```

注意：本项目使用 AGP 9 内建 Kotlin，需在 `gradle.properties` 保留 `android.disallowKotlinSourceSets=false`；并已关闭工具链自动下载（`org.gradle.java.installations.auto-download=false`），避免网络不佳时构建卡住。

## 数据契约（schedule.json）

```json
{
  "semester": "2026-2027-1",
  "studentName": "张三",
  "generatedAt": "2026-09-09T12:00:00",
  "courses": [
    {
      "id": "c0001",
      "name": "高等数学",
      "teacher": "张老师",
      "classroom": "教一101",
      "book": "",
      "dayOfWeek": 1,
      "startMinuteOfDay": 500,
      "endMinuteOfDay": 595,
      "applicableWeeks": [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16]
    }
  ]
}
```

- 时间使用“基于当日的分钟偏移”（如 08:20 = 500），禁止传输时间字符串，避免时区/解析问题；
- JSON 中的周次使用已展开的整数数组（`1-16`）；Excel 导入时由手机端展开单双周和周次区间。