课堂签到 API

1. 手动创建签到场次

POST /api/v1/checkin-sessions

Body:

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

说明：

• 任课教师或 superadmin/secretary/assistant 可调用

• 每次调用只会针对一个 CourseOccurrence 创建一条 CheckinSession

• 同一个 occurrence 重复创建不会生成重复数据；接口会返回已有场次，并标记 created=false

响应示例：

{
  "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. 签到场次列表

GET /api/v1/checkin-sessions

Query（可选）：

• course_id

• classroom_id

• status

• date（单日）

• start_date / end_date

权限：

• superadmin/secretary/assistant：查看所有场次

• 教师：仅查看自己所教课程的场次

3. 获取今日签到场次

GET /api/v1/checkin-sessions/daily

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

4. 开启签到场次

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

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

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

5. 获取点名册

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

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

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

响应：

{
  "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. 实时更新学生签到状态

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

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

Body:

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

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

7. 签到记录列表

GET /api/v1/checkin-records

Query（可选）：

• session_id

• student_id

• status

权限：

• superadmin/secretary/assistant：查看所有记录

• 教师：仅查看自己所教课程的签到记录

• 学生：仅查看自己的签到记录

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

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

Query:

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

权限：学生角色。

响应：

{
  "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. 教师手动签到

POST /api/v1/checkin-records/manual

Body:

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

说明：

• 仅任课教师或 superadmin/secretary/assistant 可调用

• status 支持 present/late/absent/leave