#自动任务与调休

自动任务用于处理调休、作息表变更、课程表调整、客户端配置切换等需要按条件自动生效和恢复的场景。所有自动任务在管理端配置，服务端在客户端请求配置时按条件动态应用。

#任务与条目

一条自动任务由两部分组成：

• 任务级信息：名称、类型、生效域、优先级、启用状态。
• 若干条目：每个条目 = 一条生效条件 + 一份内容。

同一个任务内的条目共享类型、生效域和优先级，因此：

#六种任务类型

管理端新增任务时的类型下拉（六种类型一目了然）：

#五种生效条件

任务状态（待生效 / 生效中 / 已过期）由服务端按任务内所有条目的生效区间合并判断；任务被停用时不参与课表解析。

#课程表的每周轮换

「课程表调整」任务的轮换有两种配置方式：

• 整周轮换：「轮换表」视图按「每 N 周的第 X 周」配置一整周的课表（例如单周课表 / 双周课表）。
• 逐节轮换：「逐节轮换」视图让每一节有自己的轮换周期（第一节两周一换、第十节三周一换互不影响）。保存时按天取各节周期的最小公倍数展开为「每周轮换」条目，服务端命中某一条后整张覆盖当天课表，最终结果与逐节设定的每周科目完全一致。

课表配置里已经用「多周轮换」写好的格子，可以在逐节轮换视图中用「从班级课表导入」直接转换，无需重新录入，也不会改动原课表。参见课表配置。

#生效域

生效域（scope）决定自动任务应用于哪些班级。生效域采用三级层次结构：

• 学校级（如 39）：对整个学校的所有班级生效。
• 年级级（如 39/2023）：对特定年级（即入学年份为 2023 年的年级）的所有班级生效。
• 班级级（如 39/2023/1）：仅对指定的单个班级生效。

管理端在创建任务时提供多选下拉（按学校/年级/班级三级选项），所选级别决定生效范围。系统会对生效域进行规范化处理，在任务列表中显示生效域的可读描述。

#优先级排序

自动任务列表按以下规则排序：

1. 状态优先：生效中的任务排在最前，其次为待生效任务，最后为已过期任务。
2. 优先级降序：同一状态的任务中，优先级数值越大的排在越前面。

多个任务同时生效且存在冲突时，先按优先级、再按生效域的具体程度（班级 > 年级 > 学校 > 全部）决定谁生效。

#客户端配置任务

「客户端配置」类型的任务不会改变课表内容，而是按条件覆盖桌面端的本地设置：

每个配置项有三种状态：不变（不覆盖，跟随用户本地设置）、开启、关闭。

服务端只按生效域把规则下发给客户端，具体的时刻判定（每周第几周、第几节课上课/下课、cron）由客户端本地完成，因此客户端离线一段时间后再上线，状态也会自动对齐。没有任何规则生效时，客户端恢复用户自己的本地设置。

课表类任务（作息表 / 课程表 / 全部调整）若使用「单日」「日期范围」「cron」等可能在同一周内改变的条件，服务端会把「预测下一次更新时间」写进课表版本串（第三段），边缘缓存据此设置动态 TTL——到期自动回源刷新，cron 命中点也会触发当天重取。注意 304 校验只看数据版本与周次（第三段不参与），因此纯时间翻转的规则变化以「边缘缓存到期 / 数据写入 / 周次变化」为准生效；需要立即看到最新数据时，用客户端托盘的「更新课表」强制回源。

#状态管理

每项自动任务具有三种生命周期状态：

• 待生效（状态标记为黄色）：当前日期尚未到达任务条目的生效区间。
• 生效中（状态标记为绿色）：当前日期落在任务内某个条目的生效区间内。
• 已过期（状态标记为红色）：任务内所有条目的生效区间都已经结束。

任务被停用（关闭「启用」开关）时列表显示「已停用」，它不会参与课表解析，但仍保留配置便于日后启用。

#已过期任务的清理

• 手动清理：自动任务列表页右上角的「清理已过期」按钮，一键删除所有「已过期」且未停用的任务，点击后需二次密码确认，并提示清理条数。
• 自动清理：服务端配置 [autorun] auto_clean = true 时，启动清理一次，运行期间按 24 小时间隔顺带触发（默认关闭，详见配置说明）。
• 停用的任务永远不会被清理：其显示状态可能是「已停用」但底层状态为「已过期」，自动清理只删「已过期且未停用」的记录，避免误删你想保留的配置。

#调休数据

调休任务（类型 0）涉及节假日与工作日的双向转换。系统提供以下查询方式：

#节假日与工作日双向查询

管理端在配置调休任务时，提供两个方向的查询接口：

• 根据节假日查工作日：输入一个节假日期，系统返回该日期对应的补班日（工作日），帮助确定需要上课的日期。
• 根据工作日查休息日：输入一个应上班但因调休变为休息日的日期，系统返回对应的休息说明。

两种查询均通过服务端 API 实时返回结果。

#全年调休批量导入

管理端提供全年调休批量导入功能。操作方法：

1. 进入“实用工具”页面，点击“打开调休导入”。
2. 选择目标年份，系统自动调用 API 获取该年份的全部节假日与工作日对应关系。
3. 系统创建一个名为「<年份> 年调休」的任务，每个节假日→工作日对应关系是任务内的一条条目。

批量导入适用于学期初一次性配置全年的调休安排。

#自动填充课程模板

在配置"课程表调整"或"全部调整"类型任务的条目内容时，系统提供自动填充课程模板功能。点击"自动填充"按钮后：

• 系统获取生效域内所有班级在目标工作日（星期几）的现有课表作为模板。
• 若多个班级的课表一致，直接填充；不一致时取出现次数最多的那一份模板。
• 如果不同班级的课表节数不一致，弹出冲突提示框，列出差异详情。

自动填充可减少手动录入课表的工作量。

#冲突检测

系统在保存任务前执行基本的冲突检测：

• 生效域冲突：当多个任务覆盖同一个班级且生效条件重叠时，系统不会自动阻止，但会在客户端渲染时按优先级与作用域具体度选取生效的配置。建议在创建任务前检查已有任务列表，避免意外覆盖。
• 课表节数冲突：在使用自动填充功能时，如果多个班级的课表节数不同，系统会提示冲突。此时需要手动选择其中一个班级的课表作为模板，或逐班单独创建任务。

冲突检测提供信息供操作者判断。复杂的多班级场景，建议逐班创建独立任务。