班牌设备 API

1. 班牌设备激活（公开，一次性激活码）

当前安卓班牌先扫码获取激活码，再通过本接口换取长期设备 token。

POST /api/v1/signage/activate
Content-Type: application/json

Request body:

• activation_code：一次性激活码

• device_name：可选，设备名称

• app_version：可选，班牌版本号

• install_id：可选，设备安装标识

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "token": "device_token_here",
    "device": {
      "id": 1,
      "device_code": "SIG-ABC123456789",
      "device_label": "",
      "building": "5A",
      "room_number": "203",
      "capacity": 60,
      "status": "available",
      "signage_enabled": true,
      "signage_title": "5A203",
      "signage_subtitle": "Digital Signage",
      "signage_config": {
        "announcements": [
          {
            "label": "Notice",
            "text": "Please keep the classroom clean.",
            "type": "warn"
          }
        ]
      }
    }
  }
}

说明：

• 激活码是一次性的，并且有过期时间。

• 后端只保存 token 哈希；明文 token 只在激活成功时返回一次。

• 设备后续必须使用 Authorization: Bearer <token> 访问班牌接口。

2. 当前班牌设备信息（设备鉴权）

GET /api/v1/signage/device
Authorization: Bearer <device_token>

返回当前 token 绑定教室的班牌配置。班牌设备不需要再传 classroom_id。

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "device_code": "SIG-ABC123456789",
    "device_label": "",
    "building": "5A",
    "room_number": "203",
    "capacity": 60,
    "status": "available",
    "signage_enabled": true,
    "signage_title": "5A203",
    "signage_subtitle": "Digital Signage",
    "signage_config": {
      "announcements": [
        {
          "label": "Info",
          "text": "Device is connected.",
          "type": "info"
        }
      ]
    }
  }
}

3. 当前班牌设备课表（设备鉴权）

GET /api/v1/signage/device/schedule
Authorization: Bearer <device_token>

Query:

• start_date（yyyy-mm-dd）

• end_date（yyyy-mm-dd）

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "start_time": "2026-02-04T08:00:00+08:00",
        "end_time": "2026-02-04T09:40:00+08:00",
        "course_id": 12,
        "course_name": "Calculus",
        "course_code": "MATH101",
        "teacher_name": "张三",
        "class_name": "计科2024",
        "sections": [1, 2],
        "source": "course"
      }
    ]
  }
}

说明：

• 后端根据设备 token 反查 SignageDevice.classroom_id。

• 当前班牌端只展示课程系统生成的课表，不合并人工借用。

4. 生成班牌激活码（管理员）

POST /api/v1/signage/classrooms/{id}/activation-code
Authorization: Bearer <user_access_token>
Content-Type: application/json

Request body（可选）：

• expires_in_minutes：激活码有效期，默认 10 分钟，最大 1440 分钟

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "activation_code": "one_time_code_here",
    "expires_at": "2026-04-02T12:00:00+08:00",
    "device_code": "SIG-ABC123456789",
    "qr_payload": {
      "v": 1,
      "base_url": "https://example.com/api/v1/",
      "activation_code": "one_time_code_here"
    }
  }
}

说明：

• 当前实现要求管理员先为某个教室生成激活码，再由安卓班牌扫码绑定。

• 返回的 qr_payload 可直接编码成二维码。

5. 管理侧班牌配置接口（管理员）

以下接口用于管理端查看或控制某个教室的班牌设备：

GET  /api/v1/signage/classrooms/{id}
GET  /api/v1/signage/classrooms/{id}/schedule
POST /api/v1/signage/classrooms/{id}/revoke-token

特别注意：

• 这些接口已不再是班牌设备公开接口。

• 当前安卓班牌不应再直接调用 /signage/classrooms/{id} 或其 /schedule。

• revoke-token 执行后，已绑定设备的旧 token 会立刻失效，设备需要重新扫码绑定。