#管理后台操作指南

本文档涵盖 AstraSchedule Web 管理后台（NaiveClassSchedule）的所有页面功能与操作说明。管理后台基于 Vue3 + NaiveUI 构建，通过侧边栏菜单可导航到各个功能页面。

#通用约定

身份认证：所有涉及修改、新增、删除的操作均需通过 BasicAuth 密码验证。用户名为 ElectronClassSchedule，密码由服务端配置文件指定。密码错误将返回 401 提示"你寻思寻思这密码它对吗？"。

提交前预览：课表配置、科目管理、通用设置等页面在提交按钮下方均提供 JSON 预览卡片，便于在提交前检查即将发送的数据。

菜单结构：管理后台的左侧菜单由后端 /web/menu 接口动态生成，依据数据库中的学校-年级-班级层级树自动组织。新添加的班级会自动出现在菜单中。

#仪表盘（首页）

路径：/

仪表盘是进入管理后台后的默认首页，提供系统实时运行状态概览。页面每 1 秒自动轮询后端 /web/statistic 接口刷新数据。

#今日统计

顶部卡片展示三项核心指标：

• 天气上游 API 响应错误：当日调用和风天气 API 返回错误的总次数。数值偏高说明天气服务可能出现异常或 API 配额不足。
• WebSocket 异常断连：当日所有客户端 WebSocket 异常断开的总次数。
• 正在连接的客户端数量：当前保持 WebSocket 连接的客户端总数。

#各班详情

下方表格展示每个班级的实时连接状态：

表格支持按班级名称、连接状态、异常断连次数排序。

#课表配置

路径：/config/:school/:grade/:cls/schedule

配置指定班级每周七天的课程安排。页面进入后自动加载该班级的现有课表、可用科目列表、可用作息表列表。

#顶部信息栏

显示当前操作的学校、年级、班级，确认操作目标无误。

#配置表单

表单主体为七个可折叠面板，分别对应周日到周六。提供"全部展开"和"全部折叠"快捷按钮。

每个面板包含两部分：

课程安排：按所选作息表的节次数动态生成行数，每行为一个科目选择器。课程节数由该天所选作息表的 need 值决定（need 表示最大课程序号，节次数为 need + 1）。例如作息表最大课程序号为 7，则该天显示 8 行（第 1 节到第 8 节）。

• 科目下拉选项来源于该年级的科目管理配置（缩写格式，如"语""数""英"）。
• 每节支持选择多个科目（如"语/数"表示两节连堂），使用 NaiveUI 的多选标签模式。

作息表选择：从该年级已配置的作息表模板中选择当天使用的作息表（如"常日""周五"等）。切换作息表后，上方课程安排的行数会自动更新。

#提交

点击"提交"按钮后弹出密码确认弹窗，输入正确密码后通过 BasicAuth 将 JSON 数据 PUT 到后端。提交成功提示"服务端说行"。

#提交前预览

页面底部 JSON 预览区域实时展示即将提交的完整数据结构，包含 daily_class 数组，每个元素包含 Chinese、English、classList（课程数组）、timetable（作息表名称）。

#通用设置

路径：/config/:school/:grade/:cls/settings

配置指定班级的显示行为和外观参数。页面加载时自动获取当前配置并回填表单。

#倒计时目标

两种模式通过按钮切换：

• 隐藏模式：不显示倒计时。
• 日期模式：选择目标日期（如期末考试日期），客户端将据此计算并显示倒计时天数。

#周显示

开关控制客户端是否显示当前周数（如"第 15 周"）。

#横幅文本

设置客户端顶部横幅区域的文本内容。留空则不显示横幅。可用于展示学校通知、考试倒计时提示等。

#天气预警

控制天气预警信息在客户端上的显示行为：

• 存在预警时替代横幅文本：开启后，当系统检测到天气预警信息，将用预警内容替换上方横幅文本。适用于需要优先展示极端天气通知的场景。
• 是否使用简略的预警信息：开启后使用简短描述（如"江苏省气象台发布大雾黄色预警"），关闭则显示完整预警内容（含详细时间、区域等）。

#天气温度颜色配置

控制客户端上温度显示的颜色方案：

• 启用颜色渐变：关闭时为离散色块模式（温度落入哪个区间就用该区间的颜色），开启时为渐变色模式（在相邻端点间线性过渡）。

端点列表支持动态增删，每个端点包含：

• 温度阈值 (C)：该端点的温度分界值，范围为 -50 到 100。
• 对应颜色：六位十六进制颜色选择器。

默认端点配置为：20C（浅蓝）、30C（绿）、36C（橙）、100C（红）。可根据当地气候自定义调整。

#CSS 变量样式

键值对形式自定义客户端 CSS 变量，支持动态添加/删除条目。每行包含变量名（如 --center-font-size）和变量值（如 30px）。客户端将通过 document.documentElement.style.setProperty() 应用这些变量，实现高度灵活的界面定制。

#提交前预览

底部 JSON 预览区域实时展示完整的配置数据结构。

#科目管理

路径：/config/:school/:grade/subjects

管理指定年级的所有科目名称及其缩写映射。这是整个课表系统的基础数据，课表配置和自动任务中的科目选择均依赖此处的科目列表。

#配置表单

动态行列表，每行包含：

• 缩写：课程简称，通常是单个汉字（如"语""数""英""物""化"）。此值用于客户端课表显示和科目选择器选项。
• 全写：课程全称（如"语文""数学""英语""物理""化学"）。用于自动任务等需要完整名称的场景。

每行右侧有"删除"按钮，底部有"增加"按钮可新增空白行。

#提交

与课表配置相同，点击提交后弹出密码确认弹窗。提交数据为 abbr 和 fullName 两个数组的对应关系（JSON 对象）。

#作息表管理

路径：/config/:school/:grade/timetable

管理指定年级的作息时间表模板。作息表决定了每天的节次数量、每节课的时间段、以及课间/自习等非课程时间段的显示内容。

#开学日期

使用日期选择器设置本学期的开学日期。后端根据此日期计算当前是第几周，用于自动任务中的周次判断。

#作息表模板列表

支持动态增删多个作息模板（如"常日""周五""考试日"等），使用可折叠面板管理。提供"全部展开"/"全部折叠"快捷按钮。

每个作息模板包含：

• 作息名称：唯一标识该模板（如"常日"）。注意：课表配置中"常日"为默认作息表名称。
• Divider（分隔符）：逗号分隔的课程序号列表（如 0,4,7）。指示客户端在哪些课程序号后显示分隔线，用于区分上午/下午/晚自习等时段。从 0 开始计数。
• 时间段列表：按开始时间自动排序的段落数组，每段包含：
  • 开始时间：手动输入（格式 HH:MM），结束时间自动计算（下一段的开始时间减 1 分钟，末段自动为 23:59）。
  • 值类型：二选一 —— 文本：显示自定义文字标签（如"早自习""课间""放学"）；课程序号：自动按顺序编号（0, 1, 2...），对应课程表上的第 N 节课。
  • 每个段落支持上方插入、下方插入、删除操作。

#自动校验

系统在编辑过程中自动执行以下校验和修正：

• 首段开始时间非 00:00 时自动纠正。
• 各段开始时间必须严格递增，否则无法提交。
• 课程序号自动从 0 开始连续编号。

#提交

与课表配置类似，点击提交后弹出密码输入弹窗。提交数据包含 timetable（作息段时间映射）、divider（分隔符配置）、start（开学日期 YYYY-MM-DD 格式）。

#自动任务

路径：/autorun

管理系统中的定时自动化任务，支持调休、作息表切换、课表调整、综合调整四种类型。任务列表按状态排序：生效中 > 待生效 > 已过期，生效中内部按优先级降序排列。

#列表页面

表格展示所有自动任务，包含以下列：

右上角提供"新增"和"刷新"按钮。

#新增/编辑页面

路径：/autorun/add 或 /autorun/edit/:id

#基本字段

• 类型：下拉选择四种任务类型之一。
• 生效域：多选树形选择器，支持选择学校、年级、班级三级粒度。选择上级节点会包含其所有下级。
• 优先级：数字输入，决定当多个任务同时生效时的执行顺序。

#调休任务（COMPENSATION）

配置节假日调休关系：

• 工作日 (date)：被调为上课的周末日期。
• 节假日 (useDate)：放假的节假日期。
• 辅助按钮：
  • "导入全年调休"：跳转到调休导入页面。
  • "由节假日反推工作日"：输入节假日日期后自动查询对应的工作日。
  • "由工作日反推节假日"：输入工作日日期后自动查询对应的节假日。

#作息表调整（TIMETABLE）

配置指定日期使用的作息表：

• 调整日期：选择需要调整的日期。
• 作息表：选择该日期使用的作息表模板。选项通过生效域中所有年级的作息表交集动态计算，确保所选作息表对所有生效域内的班级都可用。如未选择具体年级/班级作为生效域，则无可用选项。

#课程表调整（SCHEDULE）

配置指定日期的课程安排：

• 对应日期：选择需要调整的日期。
• 自动填充：根据所选日期和生效域内的班级自动获取当天的课程模板。系统会检测各班作息表节次数是否一致，不一致则弹出冲突提示，一致则随机选取一个班级的模板填充。
• 课程表：按节次显示科目选择器。节次数通过已检测到的作息表自动确定（休息日时显示"检测到休息日，无需填写课程"）。

#全部调整（ALL）

同时调整作息表和课程表：

• 作息表（ALL 专用）：从生效域所属年级的作息表中选择。
• 对应日期：与课程表调整相同，支持自动填充。
• 课程表：同上。

#倒数日

路径：/countdown

管理客户端显示的倒数日/纪念日配置。每个倒数日配置包含生效域和多条日程项。

#列表页面

表格展示所有倒数日配置，顶部搜索框支持按 ID、日程名称、日期筛选。

#新增/编辑页面

路径：/countdown/add 或 /countdown/edit/:id

• 生效域：多选树形选择器。
• 日程列表：动态增删的日程条目，每条包含：
  • 名称：倒数日名称（如"期末考试""高考"）。
  • 日期：日期选择器（格式 YYYY-MM-DD）。
  • 优先级：数字，多条日程同时显示时的排序依据。

提交时验证：生效域不能为空，至少填写一条完整日程（名称和日期均不为空），日期格式必须为 YYYY-MM-DD。

#实用工具

路径：/tools

提供配置迁移和数据备份相关的辅助功能。

#配置复制

将来源班级的完整配置（科目、作息、课表、通用设置）复制到目标班级。目标班级存在同名配置时将被覆盖。

• 来源：选择学校（下拉）、年级（级联下拉）、班级（级联下拉）。
• 目标：手动输入学校、年级、班级名称（支持创建新班级）。
• 来源与目标不能完全相同。
• 点击"复制配置"后弹出密码确认弹窗，确认后执行复制。

适用于：同一年级多个班级课表相似时，先配好一个班级再复制到其他班级。

#系统备份/还原

完整导出/导入数据库配置，用于跨数据库类型迁移（如 MySQL 转 SQLite）。

• 导出备份：点击后弹出密码确认弹窗，确认后下载 JSON 文件。文件名自动包含时间戳（astra-full-backup-YYYYMMDD-HHmmss.json）。
• 导入还原：选择备份 JSON 文件后，选择导入模式：
  • 覆盖：遇到已存在的数据时覆盖更新。
  • 跳过：遇到已存在的数据时保留原数据不覆盖。
• 点击"导入还原"后弹出密码确认弹窗。导入成功后建议刷新页面检查配置。

#调休导入

快捷入口，点击"打开调休导入"跳转至调休导入页面。

#调休导入

路径：/tools/compensation-import

批量导入全年的调休数据，逐条创建自动任务。

#操作步骤

1. 年份：选择要导入的调休数据年份（如 2025）。
2. 生效域：多选树形选择器，指定调休任务的作用范围。
3. 使用 ALL：
   • 是（推荐）：使用 ALL 作为生效域，调休任务对所有班级生效。
   • 否：使用上方选择的生效域。
4. 点击"开始导入"，弹出密码确认弹窗。
5. 输入密码后，系统从服务端获取该年份的调假日历数据，按 workday 为 date、holiday 为 useDate 逐条创建调休任务。导入过程中如遇密码错误立即终止。

导入完成后显示成功/失败条数统计。

#菜单导航说明

管理后台的左侧菜单完全由后端 /web/menu 接口动态生成，根据数据库中配置的学校-年级-班级层级结构自动组织。菜单层级示例如下：

仪表盘
课表配置
  > 某中学
    > 高一年级
      > 1 班 - 课表
      > 1 班 - 设置
      > 2 班 - 课表
      > 2 班 - 设置
科目管理
  > 某中学
    > 高一年级 - 科目
    > 高一年级 - 作息
自动任务
倒数日
实用工具
调休导入

新增班级后，刷新页面即可在菜单中看到新的配置入口。班级的"课表"和"设置"分别对应课表配置页面和通用设置页面。