[FOSSOVERFLOW-25] feat: Implement Room Status & Details APIs

[amaydixit11]

Description

After introducing a dedicated rooms table/collection, we need APIs to fetch room-related information such as availability, occupancy, and linked events.

These APIs will power the room booking UI, availability checks, and future analytics.

⚠️ Note: This issue must be implemented only after #230 is completed, i.e. after the Rooms collection/table is added to the database.

---

Prerequisite

• Rooms collection/schema must be implemented
• Room IDs should be standardized

---

Required APIs

1. Get All Rooms

Endpoint

GET /room

Response Format (Example)

[
  {
    "room_id": "SCITECH_101",
    "location": "SciTech Building, Floor 1",
    "status": "occupied",
    "current_event": "EVENT_12345",
    "occupied_until": "2026-02-18T16:00:00Z",
    "allowed_roles": ["scitech_core", "gensec_scitech"]
  },
  {
    "room_id": "AUDITORIUM",
    "location": "Main Building",
    "status": "vacant",
    "current_event": null,
    "occupied_until": null,
    "allowed_roles": ["all"]
  }
]

Behavior

• Returns all rooms

• Indicates whether each room is:

  • vacant
  • occupied

• If occupied:

  • Return event_id
  • Return occupancy duration (if available)

---

2. Get Room by ID

Endpoint

GET /room/:room_id

Response Format (Example)

{
  "room_id": "SCITECH_101",
  "location": "SciTech Building, Floor 1",
  "status": "occupied",
  "current_event": "EVENT_12345",
  "schedule": {
    "start": "2026-02-18T14:00:00Z",
    "end": "2026-02-18T16:00:00Z"
  },
  "allowed_roles": ["scitech_core", "gensec_scitech"],
  "metadata": {
    "capacity": 60,
    "has_projector": true
  }
}

---

Backend Requirements

• Create room-controller/service
• Query ongoing events to detect occupancy
• Map rooms ↔ active bookings/events
• Optimize queries for real-time status
• Add proper error handling (404, 500, etc.)

---

Integration Logic

• A room is considered occupied if:

  • Current time ∈ any active booking/event interval

• Event lookup must include:

  • Public events
  • Private bookings

---

Acceptance Criteria

• GET /room returns all rooms with live status
• GET /room/:room_id returns detailed info
• Occupancy detection is accurate
• Works with public + private bookings
• API is performant and secure