Classroom borrowing workflow API

1. Create a borrowing request

All authenticated users can apply:

student -> counselor

chinese_teacher -> assistant

foreign_teacher -> assistant

POST /api/v1/borrow

Body:

{
  "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"
}

Notes:

  • applicant_id / applicant_code are available only to superadmin, secretary, and assistant for submitting an application on behalf of another user. The field is ignored for ordinary users.

Business rules:

  • Time limits depend on is_urgent and applicant role:

    • assistant / superadmin: no time limit.

    • student: may apply only for the next 1 to 7 days.

    • chinese_teacher / foreign_teacher / counselor / secretary: may apply only at least 1 day in advance.

    • is_urgent=true: may select only the current day.

  • Time conflicts:

    • Conflict with an existing manual borrowing: time conflict with existing borrow application.

    • Conflict with the course schedule: time conflict with course schedule.

2. Borrowing request list (role-based)

GET /api/v1/borrow

Query:

  • status

  • applicant

  • mine (optional; when true/1, return only the current user’s applications)

  • source_type (optional; manual / course)

  • review_level (optional; first_review / second_review)

  • activity_type (optional; student_activity / teaching_activity)

  • page, page_size (also supports size)

3. Application details

GET /api/v1/borrow/{id}

4. Review an application

Permissions:

Role

Review scope

counselor

First review for student activities (reviewer_role=counselor)

secretary

First review for teaching activities (reviewer_role=secretary)

assistant

Second review for all applications

superadmin

All applications; may skip the workflow and approve directly

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

Body:

{
  "action": "approve",
  "remark": "Approved",
  "forward_to": "superadmin"
}

  • action: approve / reject / forward

  • forward_to: required only when action=forward

Automatically triggered by the system:

  • WeChat notification for Chinese teachers and students.

  • Email notification for foreign teachers.

Notes:

  • When the application is in first_review, action=approve moves it to second_review; its status remains pending.

  • When the application is in second_review, action=approve finally sets it to approved.

  • superadmin may skip the first-review and second-review workflow and approve directly.

  • assistant / superadmin may review their own applications. Other roles may not review their own applications.

5. Applicant cancels an application

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

Restrictions:

  • Only the applicant may cancel the application.

  • Cancellation is not allowed within 6 hours before the borrowing start time.

6. Reschedule a course borrowing (applicant or admin)

Only records with source_type=course and status=approved can be rescheduled. The original record is cancelled (cancelled), and a new course record is created and directly approved.

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

Body:

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

Permission: the applicant, or superadmin/secretary/assistant.