Files
2026-09-20 13:33:09 +08:00

198 lines
8.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 星课表需求文档
**产品名称:** 星课表
**工程名称:** starschedule
**平台:** Android 8.0(API 26)及以上
**界面语言:** 简体中文(不提供多语言切换)
**当前版本:** 1.0.0
配套文档:[用户使用说明](用户使用说明.md)、[架构设计](架构设计.md)、[开发文档](开发文档.md)。
## 1. 背景与目标
高校师生需要一份能长期使用的课表:看今天上什么、看本周怎么排、能从学校教务把课导进来、能改课、能提醒。
星课表由拾光课程表精简而来,目标是:
1. 把课表相关的核心能力做完整、做稳定。
2. 教务导入只适配 **正方教务**,不再维护多学校适配仓库。
3. 去掉 iOS / 桌面、多语言、开源许可证页、贡献者页、系统日历同步等与核心课表无关的能力。
4. 仅提供中文界面,降低维护成本。
## 2. 用户与使用场景
| 角色 | 典型场景 |
|---|---|
| 本科 / 专科学生 | 从正方教务导入本学期课表,日常看今日课表和周课表 |
| 研究生 / 教师 | 手动维护多份课表,或导入后微调 |
| 需要提醒的用户 | 上课前提醒,上课时自动勿扰或静音 |
| 换机用户 | 用 JSON / ZIP / WebDAV 备份恢复 |
不作为目标的能力:其他教务系统(超星、强智、青果等)一键导入、多语言、iOS / 桌面客户端。
## 3. 范围
### 3.1 包含
- 今日课表、周课表
- 多课表、课程增删改、按名称管理课程
- 自定义节次时间、学期起止、周末显示
- 课表网格样式与应用主题
- 上课提醒、上课自动勿扰 / 静音、节假日跳过
- 正方教务导入
- JSON 课程文件导入导出、ICS 导出
- 本地 ZIP 备份与 WebDAV 云备份
- 调课、按周次 / 日期批量删除
- Android 桌面小组件(4 种规格)
### 3.2 不包含
- 非正方教务适配、学校列表、远程适配仓库
- 系统日历写入同步
- iOS、桌面端
- 英文 / 繁体界面与语言切换
- 应用内检查更新、开源许可证页、贡献者列表、开发者模式 UI
## 4. 功能需求
### 4.1 课表浏览
**FR-01 今日课表**
按当天日期展示课程。未设置开学日期时提示设置;假期中显示距开学天数;学期结束后显示已过天数。可查看地点、教师、备注。
**FR-02 周课表**
按周展示网格。支持左右滑切换周次、选择周次、切换当前课表。可显示非本周课程(半透明显示)。点击课程块查看详情,可进入编辑。支持把课程“挂起”后放到另一格。
**FR-03 启动页**
用户可选择启动进入周课表或今日课表。底部三个一级入口:今日课表、课表、我的。
### 4.2 课表与课程管理
**FR-04 多课表**
可添加、重命名、删除、切换课表。至少保留一份课表,不能删光。每份课表有独立的课程、节次和学期配置。
**FR-05 添加 / 编辑课程**
必填课程名称。可选教师、地点、备注。上课时间支持:
- 节次模式:星期 + 开始/结束节次 + 周次
- 自定义时间:星期 + `HH:mm` 起止 + 周次
周次支持单周、双周、连续区间。同名课程尽量使用同一颜色。备注长度限制 300 字。
**FR-06 课程管理**
按课程名称列出当前课表全部课程,可进入实例列表批量删除或新增同名课程。
### 4.3 学期与作息
**FR-07 学期配置(按课表)**
- 开学日期:学期第一周所参考的周一(或用户设定的每周起始日)
- 总周数,默认 20
- 当前周数可手动改,会反推开学日期
- 每周起始日:周一或周日
- 是否显示周末
**FR-08 节次时间**
可增删改每节课的开始/结束时间及别名。可设置默认课时长与课间休息,用于新增节次。节次编号从 1 连续递增,时间不得重叠。新建课表带 13 节默认作息(08:00 起,详见数据模型)。正方导入不覆盖节次表。
### 4.4 导入导出
**FR-09 正方教务导入**
用户在内置 WebView 中打开正方登录页,进入「学生课表查询」并查出课表后,选择目标课表,执行内置脚本抓取并写入。覆盖目标课表已有课程。只适配正方 HTML 课表(列表视图与网格视图),依赖页面 jQuery。
**FR-10 JSON 导入导出**
导入 JSON 课程文件到指定课表(覆盖该表课程,并可带时间段与学期配置)。导出当前或指定课表为 JSON,文件名形如 `starschedule_<时间戳>.json`。
**FR-11 ICS 导出**
按学期实例展开课程,生成 `.ics`,可设置提前提醒分钟数。
### 4.5 备份
**FR-12 本地 ZIP**
将全部课表与样式打包为 ZIP,可恢复覆盖本地数据。
**FR-13 WebDAV**
可配置服务器地址、账号、密码、远端目录。密码加密存储。备份上传到配置目录下的 Backup 文件夹,也可从云端恢复。
备份协议版本过新时拒绝恢复,提示升级应用。
### 4.6 提醒与自动化
**FR-14 上课提醒**
可开关。提前提醒分钟数由用户输入(默认 15)。使用精确闹钟,数据来自近 7 天已展开的 Widget 库。Android 13+ 需要通知权限。ICS 导出的提醒可选 1–60 分钟。
**FR-15 上课自动模式**
依赖提醒开启。可选关闭、勿扰、静音。勿扰需要系统「勿扰模式」权限。
**FR-16 跳过日期**
可从节假日接口更新跳过日期,可查看、清空。被跳过日期不提醒、小组件标记跳过。接口来源为 `https://timor.tech/api/holiday/year`,不保证稳定。
**FR-17 穿戴设备兼容**
可关闭实时通知属性,以便部分手环同步软件抓取通知。
### 4.7 个性化
**FR-18 课表样式**
格子高度、侧栏宽度、表头高度、圆角、内外边距、透明度、文字缩放、对齐、边框(无/实线/虚线)、隐藏地点/教师/节次时间/日期/网格线、课程块开始时间、地点前 `@`、页面文字色、课程文字色、浅色/深色颜色池、课表背景图、节次模式或 24 小时时间轴模式。可恢复默认。
**FR-19 应用主题**
跟随系统 / 浅色 / 深色。Android 12+ 可开动态取色。可自定义浅色、深色主色种子。
### 4.8 快捷操作
**FR-20 调课**
将某日课程合并到另一日、覆盖另一日、或与另一日交换。两日不能相同。需已设开学日期。
**FR-21 快速删除**
按周次+星期,或按具体日期,批量从课表中移除课程实例(不删课程名称本身的基础信息以外的实例记录)。
### 4.9 桌面小组件
**FR-22** 四种原生小组件:
| 名称 | 规格 | 内容 |
|---|---|---|
| 超小课程2x1 | 2x1 | 当前/下一节课 |
| 紧凑课程2x2 | 2x2 | 今日剩余或明日预告 |
| 近日课程4x2 | 4x2 | 今天 + 明天 |
| 垂直列表课表4xN | 4xN | 列表展示今日或明日 |
小组件数据来自独立 Widget 库,由主库同步未来 7 天实例,不在小组件进程里算完整课表。
## 5. 非功能需求
| 编号 | 要求 |
|---|---|
| NFR-01 | 最低 Android 8.0;编译 SDK / 目标 SDK 37 |
| NFR-02 | 界面仅简体中文,资源 locale 限制为 `zh` / `zh-rCN` |
| NFR-03 | 课表、设置读写在本地完成;正方导入与 WebDAV、节假日更新需要网络 |
| NFR-04 | WebDAV 密码使用平台加密存储,不以明文写入 DataStore |
| NFR-05 | 导入正方时覆盖所选课表课程,需用户先选目标课表 |
| NFR-06 | Release 开启 minify 与 shrinkResources |
| NFR-07 | 按 ABI 分包:`armeabi-v7a`、`arm64-v8a`、`x86_64` |
| NFR-08 | 不提供账号体系,数据全在本机(及用户配置的 WebDAV) |
## 6. 权限
| 权限 | 用途 |
|---|---|
| INTERNET / ACCESS_NETWORK_STATE | 正方网页、WebDAV、节假日接口 |
| SCHEDULE_EXACT_ALARM | 上课提醒 |
| POST_NOTIFICATIONS | 通知 |
| ACCESS_NOTIFICATION_POLICY | 上课勿扰 |
| RECEIVE_BOOT_COMPLETED | 重启后恢复提醒调度 |
| POST_PROMOTED_NOTIFICATIONS | 实时通知相关 |
不申请读写系统日历。权限与数据去向见 [隐私与数据](隐私与数据.md)。
## 7. 验收要点
1. 新安装可创建课表、添加课程,今日课表与周课表显示正确。
2. 设置开学日期后,当前周数与日期对齐正确;改当前周会改开学日期。
3. 正方课表查询页(列表或网格)可导入课程到指定课表。
4. JSON 导出后再导入,课程、周次、时间段、学期配置可恢复。
5. 本地 ZIP 备份恢复后,多课表与样式仍在。
6. 开启提醒后,在提前提醒时间能收到通知(需授予精确闹钟与通知权限)。
7. 应用内无语言切换入口,无学校列表、无适配仓库更新入口。
8. 界面文案为简体中文。