# 班牌设备 API

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

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

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

Request body:

- `activation_code`：一次性激活码
- `device_name`：可选，设备名称
- `app_version`：可选，班牌版本号
- `install_id`：可选，设备安装标识

Response

```json
{
  "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. 当前班牌设备信息（设备鉴权）

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

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

Response

```json
{
  "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. 当前班牌设备课表（设备鉴权）

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

Query:

- `start_date`（yyyy-mm-dd）
- `end_date`（yyyy-mm-dd）

Response

```json
{
  "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. 生成班牌激活码（管理员）

```bash
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

```json
{
  "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. 管理侧班牌配置接口（管理员）

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

```bash
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 会立刻失效，设备需要重新扫码绑定。