# 课堂签到 API

## 1. 手动创建签到场次

```bash
POST /api/v1/checkin-sessions
```

Body:

```json
{
  "occurrence_id": 345,
  "remark": "课前创建"
}
```

说明：

- 任课教师或 `superadmin/secretary/assistant` 可调用
- 每次调用只会针对一个 `CourseOccurrence` 创建一条 `CheckinSession`
- 同一个 `occurrence` 重复创建不会生成重复数据；接口会返回已有场次，并标记 `created=false`

响应示例：

```json
{
  "code": 0,
  "message": "checkin session created",
  "data": {
    "created": true,
    "session": {
      "id": 101,
      "course_id": 12,
      "occurrence_id": 345,
      "session_date": "2026-03-09",
      "sections": [1, 2],
      "status": "draft"
    }
  }
}
```

## 2. 签到场次列表

```bash
GET /api/v1/checkin-sessions
```

Query（可选）：
- course_id
- classroom_id
- status
- date（单日）
- start_date / end_date

权限：

- `superadmin/secretary/assistant`：查看所有场次
- 教师：仅查看自己所教课程的场次

## 3. 获取今日签到场次

```bash
GET /api/v1/checkin-sessions/daily
```

说明：返回今日的课程及签到状态，权限同列表接口。

## 4. 开启签到场次

```bash
POST /api/v1/checkin-sessions/{id}/open
```

权限：任课教师或 `superadmin/secretary/assistant`。

说明：将场次状态从 `draft` 改为 `open`，允许学生签到。

## 5. 获取点名册

获取某场次的班级学生名单及其签到状态。

```bash
GET /api/v1/checkin-sessions/{id}/roster
```

权限：任课教师或 `superadmin/secretary/assistant`。

响应：

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "session": { ... },
    "roster": [
      {
        "student_id": 2001,
        "full_name": "张三",
        "user_code": "2024123456",
        "user_code_last4": "3456",
        "student_class": "计科2024",
        "status": "present",
        "checkin_time": "2026-03-09T08:05:00+08:00",
        "remark": "",
        "record_id": 101
      }
    ]
  }
}
```

## 6. 实时更新学生签到状态

```bash
POST /api/v1/checkin-sessions/{id}/toggle-status
```

权限：任课教师或 `superadmin/secretary/assistant`。

Body:

```json
{
  "student_id": 2001,
  "status": "present",
  "remark": ""
}
```

说明：`status` 支持 `present/late/absent/leave`。

## 7. 签到记录列表

```bash
GET /api/v1/checkin-records
```

Query（可选）：
- session_id
- student_id
- status

权限：

- `superadmin/secretary/assistant`：查看所有记录
- 教师：仅查看自己所教课程的签到记录
- 学生：仅查看自己的签到记录

## 8. 学生查看当日课程及签到状态

```bash
GET /api/v1/checkin-records/my-schedule
```

Query:

- `date`（必填，格式 `YYYY-MM-DD`）

权限：学生角色。

响应：

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "date": "2026-03-09",
    "courses": [
      {
        "session_id": 101,
        "course_name": "Calculus",
        "course_code": "MATH101",
        "classroom": "5A C317",
        "sections": [1, 2],
        "status": "present",
        "checkin_time": "2026-03-09T08:05:00+08:00",
        "session_status": "open"
      }
    ]
  }
}
```

## 9. 教师手动签到

```bash
POST /api/v1/checkin-records/manual
```

Body:

```json
{
  "session_id": 101,
  "student_id": 2001,
  "status": "present",
  "remark": "" 
}
```

说明：
- 仅任课教师或 `superadmin/secretary/assistant` 可调用
- `status` 支持 `present/late/absent/leave`