# 课程 API

## 1. 课程列表（登录可用）

```bash
GET /api/v1/courses
```

Query（可选）：

- teacher_id：教师查询自己的课程
- class_name：学生按班级查询课程

返回：课程基础信息 + `sessions`（包含 `weekday`、`sections`、`week_list` 等字段）。

说明：

- `sessions.weekday` 为字符串枚举：`MONDAY`、`TUESDAY`、`WEDNESDAY`、`THURSDAY`、`FRIDAY`、`SATURDAY`、`SUNDAY`
- `sessions.week_list` 为学期周次列表，与导入/导出的 `起止周` 语义一致，不使用相对课程 `start_date` 的内部周序
- Web / 小程序等 API 调用方应基于该枚举值做判断，不应依赖后端内部数据库的整数编码
- 不提供旧 `0-6` 整数 weekday 协议兼容

## 2. 导入课程表 Excel（superadmin / secretary）

```bash
POST /api/v1/courses/import
Content-Type: multipart/form-data
```

字段：

- file：Excel 文件（`.xlsx`/`.xls`）
- semester_start_date：学期开始日期（`YYYY-MM-DD`）

说明：

- 权限：仅 `superadmin` / `secretary`
- 文件格式：`.xlsx` / `.xls`，最大 50MB
- 模板由后端生成，字段顺序为：`课程名称`、`教师姓名`、`星期`、`节次`、`起止周`、`备注`、`上课教室`、`行政班`、`年级`、`教学楼`、`教室类型`、`楼层`、`课程序号`、`课程代码`、`行政班个数`、`教师工号`、`教室人数`
- Excel 中 `星期` 列沿用教务系统导入格式：`1-7`（`1=周一`，`7=周日`），也支持 `周一` / `星期一` 等中文写法
- 导入模板必须包含 `课程序号` 列，缺失会直接报错
- 导入筛选规则：
  - `行政班` 包含 `UC`（大小写不敏感）的记录直接导入
  - 其他记录仅导入 `五号教学楼` 2/3 楼教室
- 体育课特殊处理：`行政班` 包含 `UC` 且课程名称包含 `体育` 时，允许不关联教师和教室，直接导入课程记录
- `教室人数` 和 `上课人数` 都可用于导入课程人数
- `备注` / `remark` 列会写入后端课程备注
- 错误列表最多返回 100 条，超过时 `error_report_available = true`

下载导入模板：

```bash
GET /api/v1/courses/import-template/
```

- 模板由后端生成
- `上课教室` 使用完整教室字符串，例如 `五号教学楼C317`

返回（示例）：

```json
{
  "code": 0,
  "message": "导入完成：成功 85 条，跳过 10 条",
  "data": {
    "total_rows": 100,
    "processed": 85,
    "skipped": 10,
    "created": 50,
    "updated": 35,
    "failed": 5,
    "errors": [],
    "error_rows": [],
    "error_count": 5,
    "error_report_available": false,
    "details_truncated": false
  }
}
```

## 3. 导出课程表（superadmin / secretary）

```bash
GET /api/v1/courses/export
```

Query（可选）：

- `classroom_id`：按教室过滤

返回：Excel 文件下载，`起止周` 按学期周次导出。

## 4. 课程调课

将某个课程时段调整到新的时间/教室。

```bash
POST /api/v1/courses/sessions/{session_id}/reschedule
```

权限：课程教师本人，或 `superadmin` / `secretary` / `assistant`。

Body:

```json
{
  "classroom_id": 121,
  "start_time": "2026-01-20T08:00:00+08:00",
  "end_time": "2026-01-20T09:50:00+08:00"
}
```

说明：

- 调课日期必须在课程有效期内（`start_date` 到 `end_date`）
- 返回值中的 `target_week` 为学期周次
- 所选时间段需能匹配到标准节次
- 不支持跨天调课

响应：

```json
{
  "code": 0,
  "message": "调课提交成功",
  "data": {
    "session_id": 123,
    "target_session_id": 456,
    "target_week": 5,
    "occurrence_id": 789
  }
}
```