# 教室借用流程 API

## 1. 发起借用申请

所有登录用户均可申请：

student → counselor

chinese_teacher → assistant

foreign_teacher → assistant

```bash
POST /api/v1/borrow
```

Body

```json
{
  "classroom_id": 121,
  "start_time": "2025-04-12T09:00:00",
  "end_time": "2025-04-12T11:00:00",
  "reason": "Lecture",
  "expected_students": 30,
  "activity_type": "student_activity",
  "is_urgent": false,
  "applicant_id": 12,
  "applicant_code": "2024123456"
}
```

说明：

- `applicant_id` / `applicant_code` 仅 `superadmin`/`secretary`/`assistant` 可用，用于代用户提交申请；普通用户忽略该字段。

业务规则：

- 时间限制（与 `is_urgent`、申请人角色有关）：
  - `assistant` / `superadmin`：不受时间限制
  - `student`：仅允许申请未来 **+1 到 +7 天**
  - `chinese_teacher` / `foreign_teacher` / `counselor` / `secretary`：仅允许申请未来 **至少 +1 天**
  - `is_urgent=true`（加急）：只能选择 **当天**

- 时间冲突：
  - 与已有手动借用冲突：`time conflict with existing borrow application`
  - 与课程表冲突：`time conflict with course schedule`

## 2. 借用申请列表（按角色查看）

```bash
GET /api/v1/borrow
```

Query:

- status
- applicant
- mine（可选，`true/1` 时只看自己的申请）
- source_type（可选，`manual`/`course`）
- review_level（可选，`first_review`/`second_review`）
- activity_type（可选，`student_activity`/`teaching_activity`）
- page, page_size（兼容 size）

## 3. 申请详情

```bash
GET /api/v1/borrow/{id}
```

## 4. 审核申请

权限说明：

| 角色 | 可审批范围 |
|------|-----------|
| `counselor` | 学生活动一审（`reviewer_role=counselor`） |
| `secretary` | 教学活动一审（`reviewer_role=secretary`） |
| `assistant` | 所有申请二审 |
| `superadmin` | 所有申请，且可跳过流程直接批准 |

```bash
PUT /api/v1/borrow/{id}/review
```

Body

```json
{
  "action": "approve",
  "remark": "同意",
  "forward_to": "superadmin"
}
```

- `action`：`approve` / `reject` / `forward`
- `forward_to`：仅当 `action=forward` 时需要

系统自动触发：

- 微信推送（中方教师/学生）
- 邮件推送（外方教师）

说明：
- 当申请处于 `first_review`，`action=approve` 会将申请流转到 `second_review`（状态仍为 `pending`）
- 当申请处于 `second_review`，`action=approve` 才会最终 `approved`
- `superadmin` 可跳过一审/二审流程直接批准
- `assistant` / `superadmin` 允许自审自己的申请，其余角色禁止自审

## 5. 申请者主动取消

```bash
PUT /api/v1/borrow/{id}/cancel
```

限制：

- 仅允许申请人本人取消
- 距离借用开始时间不足 6 小时内不允许取消

## 6. 课程借用改期（申请人或管理员）

仅支持对 `source_type=course` 且 `status=approved` 的记录改期：原记录会被取消（`cancelled`），同时创建一条新的 `course` 记录并直接 `approved`。

```bash
POST /api/v1/borrow/{id}/reschedule
```

Body:

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

权限：申请人本人，或 `superadmin/secretary/assistant`。