Skip to content

CLASSROOM_REFACTORING_GUIDE.md

Latest commit

 

History

History
168 lines (133 loc) · 4.56 KB

CLASSROOM_REFACTORING_GUIDE.md

File metadata and controls

168 lines (133 loc) · 4.56 KB

Classroom Management Refactoring Guide

Overview

This document outlines the refactoring changes made to the classroom management functionality to improve code organization, maintainability, and type safety.

Changes Made

1. New Service Layer

  • File: app/services/classroom_service.py
  • Purpose: Centralized business logic for classroom operations
  • Benefits: Separation of concerns, reusability, easier testing

2. Dedicated Router

  • File: app/api/classrooms.py
  • Purpose: HTTP endpoint handling for classroom operations
  • Benefits: Cleaner main.py, better organization

3. Request/Response Models

  • File: app/schemas/classroom.py
  • Purpose: Type-safe request/response validation
  • Benefits: Better API documentation, input validation, consistent responses

4. Enhanced Error Handling

  • Improvements: Better error messages, proper HTTP status codes, input validation
  • Benefits: More reliable API, better debugging experience

Migration Guide

Old Endpoints (to be deprecated)

# Old endpoints in main.py
POST /add_or_update/room/
DELETE /delete/room/
GET /get/rooms/

New Endpoints

# New endpoints with form data (backward compatible)
POST /classrooms/add_or_update/
DELETE /classrooms/delete/
GET /classrooms/get/

# New endpoints with JSON body (recommended)
POST /classrooms/add_or_update/json/
DELETE /classrooms/delete/json/
GET /classrooms/all/

Response Format Changes

Old Format

{
  "message": "Device added to existing robot_id"
}

New Format

{
  "message": "Device added to existing robot_id",
  "success": true
}

Code Migration Examples

Before (using old endpoints)

# Client code
response = await client.post("/add_or_update/room/", data={
    "robot_id": "robot1",
    "device_id": "device1", 
    "room_name": "Classroom A"
})

After (using new endpoints)

# Option 1: Form data (backward compatible)
response = await client.post("/classrooms/add_or_update/", data={
    "robot_id": "robot1",
    "device_id": "device1",
    "classroom_name": "Classroom A"
})

# Option 2: JSON body (recommended)
response = await client.post("/classrooms/add_or_update/json/", json={
    "robot_id": "robot1",
    "device_id": "device1",
    "classroom_name": "Classroom A"
})

Implementation Steps

1. Update main.py

# Add this import
from app.api.classrooms import router as classrooms_router

# Add this line after other router includes
app.include_router(classrooms_router)

# Remove the old room endpoints (lines 738-816)

2. Update Dependencies

# Add to requirements.txt if not already present
pydantic>=2.0.0

3. Update Client Code

  • Replace old endpoint URLs with new ones
  • Update response handling to check success field
  • Consider using JSON endpoints for better type safety

Benefits of Refactoring

  1. Better Organization: Room logic is now in dedicated files
  2. Type Safety: Pydantic models ensure data validation
  3. Consistent Responses: All endpoints return structured responses
  4. Better Error Handling: More specific error messages and status codes
  5. Easier Testing: Service layer can be tested independently
  6. API Documentation: Better OpenAPI documentation with schemas
  7. Maintainability: Easier to modify and extend room functionality

Backward Compatibility

The old endpoints will continue to work during the transition period. However, they should be deprecated and eventually removed in favor of the new endpoints.

Testing

Unit Tests

# Test the service layer
async def test_add_classroom():
    classroom_service = ClassroomService(mock_db)
    result = await classroom_service.add_or_update_classroom("robot1", "device1", "Classroom A")
    assert result.success == True
    assert "added" in result.message.lower()

Integration Tests

# Test the API endpoints
async def test_add_classroom_endpoint():
    response = await client.post("/classrooms/add_or_update/json/", json={
        "robot_id": "robot1",
        "device_id": "device1",
        "classroom_name": "Classroom A"
    })
    assert response.status_code == 200
    assert response.json()["success"] == True

Future Enhancements

  1. Caching: Add Redis caching for frequently accessed classroom data
  2. Pagination: Add pagination for large classroom lists
  3. Search: Add search functionality for classrooms
  4. Audit Logging: Track classroom changes for compliance
  5. Bulk Operations: Add endpoints for bulk classroom operations