津贴相关 API

津贴相关接口统一前缀为 /api/v1/allowance，用于校历（节假日）数据读写与坐班签到统计。

获取校历

GET /api/v1/allowance/get_calendar?year={year}

获取指定年份的节假日（含离校、返校、课表修改、备注）数据，用于生成日历。

请求参数（query）

参数	类型	必填	说明
year	int	✅	年份

响应示例

{
  "holiday": {
    "01-01": {
      "year": 2026,
      "month_day": "01-01",
      "holiday": true,
      "leave_school": false,
      "return_school": false,
      "schedule_modification": null,
      "remark": "元旦",
      "date": "2026-01-01"
    }
  }
}

返回的 holiday 为以「月-日」（MM-DD）为键、记录为值的对象；每条记录额外附带 date 字段（YYYY-MM-DD 格式）。

修改假期

PUT /api/v1/allowance/update_holiday

修改假期表中的某一天记录；若该天不存在则新增一条。支持部分更新，缺省的字段保持原值。

请求参数（JSON）

字段	类型	必填	说明
year	int	✅	年份
month_day	string	✅	月日，MM-DD 格式
leave_school	bool	❌	是否离校
return_school	bool	❌	是否返校
schedule_modification	object	❌	课表修改（任意 JSON，传 {} 表示清空）
remark	string	❌	备注

请求示例

{
  "year": 2026,
  "month_day": "09-01",
  "leave_school": true,
  "return_school": false,
  "schedule_modification": {},
  "remark": "开学离校"
}

响应示例

返回修改后的完整记录（含拼接的 date 字段）：

{
  "year": 2026,
  "month_day": "09-01",
  "holiday": false,
  "leave_school": true,
  "return_school": false,
  "schedule_modification": {},
  "remark": "开学离校",
  "date": "2026-09-01"
}

校验失败（如字段非法）时返回 422。

签到统计

POST /api/v1/allowance/attendance_statistics

上传坐班签到表，结合假期表统计有效坐班次数并生成统计 Excel。

请求参数（form-data）

参数	类型	必填	说明
sheet	file	✅	坐班签到表 Excel 文件

签到表结构

• 第 1 行为表头（姓名、部门、各日期列，如 周一 26-03-09）。
• 每位教师占 6 行：上午签到/签退、下午签到/签退、晚上签到/签退。

输出

统计结果保存到 output/津贴/坐班签到统计/ 目录。

响应示例

{
  "output_path": [
    "D:\\EduAssist\\output\\津贴\\坐班签到统计\\签到统计.xlsx",
    "D:\\EduAssist\\output\\津贴\\坐班签到统计\\教师明细.xlsx"
  ]
}