# 星课表需求文档 **产品名称:** 星课表 **工程名称:** 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. 界面文案为简体中文。