FEAT: Code for crud completed

main.py

@@ -4,25 +4,51 @@ from datetime import datetime
 from fastapi.middleware.cors import CORSMiddleware
 import uvicorn
 from contextlib import asynccontextmanager
+import os
+from fastapi import FastAPI
+from sqlmodel import Session
+from starlette.middleware.cors import CORSMiddleware
+
 
 # Correctly import the database table creation function
-from src.database import create_db_and_tables
+from src.database import create_db_and_tables, engine
 # Import all the necessary routers for the application
 from src.routers import students, devices, clearance, token, users, admin
+from src.crud import users as user_crud
+from src.models import UserCreate, Role
 
 @asynccontextmanager
-async def lifespan(app_instance: FastAPI):
-    """
-    Handles application startup and shutdown events.
-    - On startup, it ensures that all necessary database tables are created.
-    - On shutdown, it can be used for cleanup tasks.
-    """
-    print("Application startup: Initializing...")
-    # Correctly call the function to create database tables
+async def lifespan(app: FastAPI):
+    # On startup
+    print("Starting up...")
     create_db_and_tables()
-    print("Application startup: Database tables checked/created.")
+    
+    # --- Create first superuser ---
+    # This runs only on startup. It checks if an admin exists and creates one if not.
+    # It's best practice to get credentials from environment variables for security.
+    with Session(engine) as session:
+        initial_username = os.getenv("INITIAL_ADMIN_USERNAME", "admin")
+        
+        # Check if the user already exists
+        user = user_crud.get_user_by_username(session, username=initial_username)
+        if not user:
+            print("Initial admin user not found, creating one...")
+            initial_user = UserCreate(
+                username=initial_username,
+                email=os.getenv("INITIAL_ADMIN_EMAIL", "admin@example.com"),
+                full_name="Initial Admin",
+                password=os.getenv("INITIAL_ADMIN_PASSWORD", "changethispassword"),
+                role=Role.ADMIN
+            )
+            user_crud.create_user(db=session, user=initial_user)
+            print("Initial admin user created successfully.")
+        else:
+            print("Initial admin user already exists.")
+
     yield
-    print("Application shutdown: Cleaning up.")
+    # On shutdown
+    print("Shutting down...")
+
 
 
 # Initialize the FastAPI application instance with metadata for documentation

src/auth.py

@@ -1,17 +1,16 @@
-from fastapi import Depends, HTTPException, status
+from fastapi import Depends, HTTPException, status, Security
 from fastapi.security import APIKeyHeader, OAuth2PasswordBearer
 from jose import JWTError, jwt
 from sqlmodel import Session, select
 from typing import List, Optional
-from typing import List, Optional
 from datetime import datetime, timedelta
 
-
 from src.config import settings
 from src.database import get_session
 from src.crud import users as user_crud
 from src.crud import devices as device_crud
 from src.models import User, Role, Device
+from src.crud.utils import verify_password, hash_password
 
 # --- Configuration ---
 oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
@@ -28,13 +27,6 @@ def create_access_token(data: dict, expires_delta: Optional[timedelta] = None):
     encoded_jwt = jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
     return encoded_jwt
 
-# --- Password Hashing ---
-def verify_password(plain_password: str, hashed_password: str) -> bool:
-    return settings.PWD_CONTEXT.verify(plain_password, hashed_password)
-
-def hash_password(password: str) -> str:
-    return settings.PWD_CONTEXT.hash(password)
-
 # --- User Authentication ---
 def authenticate_user(db: Session, username: str, password: str):
     """Authenticate user by username and password."""
@@ -47,20 +39,20 @@ def authenticate_user(db: Session, username: str, password: str):
 
 # --- Dependency for API Key Authentication ---
 
-def get_api_key(
-    key: str = Depends(api_key_header), db: Session = Depends(get_session)
-) -> Device:
-    """
-    Dependency to validate the API key from the x-api-key header.
-    Ensures the device is registered in the database.
-    """
-    db_device = device_crud.get_device_by_api_key(db, api_key=key)
-    if not db_device:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Invalid or missing API Key",
-        )
-    return db_device
+# def get_api_key(
+#     key: str = Depends(api_key_header), db: Session = Depends(get_session)
+# ) -> Device:
+#     """
+#     Dependency to validate the API key from the x-api-key header.
+#     Ensures the device is registered in the database.
+#     """
+#     db_device = device_crud.get_device_by_api_key(db, api_key=key)
+#     if not db_device:
+#         raise HTTPException(
+#             status_code=status.HTTP_401_UNAUTHORIZED,
+#             detail="Invalid or missing API Key",
+#         )
+#     return db_device
 
 
 # --- Dependency for User Authentication and Authorization ---
@@ -98,3 +90,20 @@ def get_current_active_user(required_roles: List[Role] = None):
         return user
 
     return dependency
+
+async def get_api_key(api_key: str = Security(api_key_header), db: Session = Depends(get_session)):
+    """Validate device API key."""
+    if not api_key:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="API key required"
+        )
+    
+    device = device_crud.get_device_by_api_key(db, api_key=api_key)
+    if not device or not device.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or inactive API key"
+        )
+    
+    return api_key

src/crud/clearance.py

@@ -1,7 +1,6 @@
 from sqlmodel import Session, select
 from typing import List, Optional
-
-from src.models import Student, ClearanceStatus, ClearanceUpdate, Department, ClearanceProcess
+from src.models import ClearanceStatus, Student, ClearanceUpdate, ClearanceStatusEnum
 
 def get_clearance_status_for_student(db: Session, student: Student) -> List[ClearanceStatus]:
     """
@@ -9,37 +8,38 @@ def get_clearance_status_for_student(db: Session, student: Student) -> List[Clea
     """
     return student.clearance_statuses
 
-def update_clearance_status(db: Session, clearance_update: ClearanceUpdate) -> Optional[ClearanceStatus]:
+def update_clearance_status(db: Session, update_data: ClearanceUpdate) -> ClearanceStatus | None:
     """
-    Updates the clearance status for a student in a specific department.
-
-    This function performs a direct lookup on the ClearanceStatus table, which is
-    more efficient than fetching the student and iterating through their statuses.
+    Updates the clearance status for a specific student and department.
     """
-    # First, find the student to ensure they exist.
-    student = db.exec(select(Student).where(Student.matric_no == clearance_update.matric_no)).first()
+    # Find the student first
+    student_statement = select(Student).where(Student.matric_no == update_data.matric_no)
+    student = db.exec(student_statement).first()
     if not student:
         return None # Student not found
 
-    # Directly query for the specific clearance status record.
-    statement = select(ClearanceStatus).where(
+    # Now find the specific clearance status record for that student
+    status_statement = select(ClearanceStatus).where(
         ClearanceStatus.student_id == student.id,
-        ClearanceStatus.department == clearance_update.department
+        ClearanceStatus.department == update_data.department
     )
-    status_to_update = db.exec(statement).first()
+    clearance_record = db.exec(status_statement).first()
 
-    if not status_to_update:
-        # This case should theoretically not happen if students are created correctly,
-        # but it's a good safeguard.
+    if not clearance_record:
+        # This case should ideally not happen if students are created correctly
         return None 
 
-    # Update the status and commit the change.
-    status_to_update.status = clearance_update.status
-    db.add(status_to_update)
-    db.commit()
-    db.refresh(status_to_update)
+    # Update the status and remarks
+    clearance_record.status = update_data.status
+    if update_data.remarks is not None:
+        clearance_record.remarks = update_data.remarks
     
-    return status_to_update
+    db.add(clearance_record)
+    db.commit()
+    db.refresh(clearance_record)
+
+    return clearance_record
+
 
 def is_student_fully_cleared(db: Session, matric_no: str) -> bool:
     """
@@ -51,7 +51,7 @@ def is_student_fully_cleared(db: Session, matric_no: str) -> bool:
 
     # Check if any of the student's clearance statuses are NOT 'approved'.
     for status in student.clearance_statuses:
-        if status.status != ClearanceProcess.APPROVED:
+        if status.status != ClearanceStatusEnum.APPROVED:
             return False
             
     # If the loop completes without returning, all statuses are approved.

src/crud/devices.py

@@ -20,7 +20,8 @@ def create_device(db: Session, device: DeviceCreate) -> Optional[Device]:
     
     db_device = Device(
         device_name=device.device_name,
-        department=device.department,
+        location=device.location,  # ADD THIS
+        department=device.department,  # ADD THIS
         api_key=api_key,
         is_active=True
     )
@@ -30,6 +31,10 @@ def create_device(db: Session, device: DeviceCreate) -> Optional[Device]:
     db.refresh(db_device)
     return db_device
 
+def get_device_by_id(db: Session, device_id: int) -> Optional[Device]:
+    """Retrieves a device by its primary key ID."""
+    return db.get(Device, device_id)
+
 def get_device_by_api_key(db: Session, api_key: str) -> Optional[Device]:
     """Retrieves an active device by its API key."""
     statement = select(Device).where(Device.api_key == api_key, Device.is_active == True)

src/crud/students.py

@@ -1,9 +1,10 @@
 from sqlmodel import Session, select
 from typing import List, Optional
 
-from src.models import Student, StudentCreate, StudentUpdate, RFIDTag, ClearanceStatus, Department, ClearanceProcess
-from src.auth import hash_password
-
+from src.models import (
+    Student, StudentCreate, StudentUpdate, User, Role, ClearanceStatus, ClearanceDepartment, RFIDTag
+)
+from src.crud import users as user_crud
 # --- Read Operations ---
 
 def get_student_by_id(db: Session, student_id: int) -> Optional[Student]:
@@ -15,84 +16,81 @@ def get_student_by_matric_no(db: Session, matric_no: str) -> Optional[Student]:
     return db.exec(select(Student).where(Student.matric_no == matric_no)).first()
 
 def get_student_by_tag_id(db: Session, tag_id: str) -> Optional[Student]:
-    """Retrieves a student by their linked RFID tag ID."""
-    statement = select(Student).join(RFIDTag).where(RFIDTag.tag_id == tag_id)
-    return db.exec(statement).first()
+    """Get student by RFID tag ID."""
+    from src.models import RFIDTag
+    tag = db.exec(select(RFIDTag).where(RFIDTag.tag_id == tag_id)).first()
+    if tag and tag.student_id:
+        return db.exec(select(Student).where(Student.id == tag.student_id)).first()
+    return None
 
 def get_all_students(db: Session, skip: int = 0, limit: int = 100) -> List[Student]:
     """Retrieves a paginated list of all students."""
     return db.exec(select(Student).offset(skip).limit(limit)).all()
 
 # --- Write Operations ---
-
-def create_student(db: Session, student: StudentCreate) -> Student:
+def create_student(db: Session, student_data: StudentCreate) -> Student:
     """
-    Creates a new student and initializes their clearance statuses.
-
-    This is a critical business logic function. When a student is created,
-    this function automatically creates a 'pending' clearance record for every
-    department defined in the `Department` enum.
+    Creates a new student along with their associated user account for login
+    and initializes their clearance statuses.
     """
-    hashed_pass = hash_password(student.password)
-    db_student = Student(
-        matric_no=student.matric_no,
-        full_name=student.full_name,
-        email=student.email,
-        hashed_password=hashed_pass,
-        # Department will be set from the StudentCreate model
-        department=student.department 
+    # 1. Create the associated User account for the student to log in
+    # The student's username is their matriculation number.
+    user_for_student = user_crud.UserCreate(
+        username=student_data.matric_no,
+        password=student_data.password,
+        email=student_data.email,
+        full_name=student_data.full_name,
+        role=Role.STUDENT
     )
-    
-    # --- Auto-populate clearance statuses ---
-    initial_statuses = []
-    for dept in Department:
-        status = ClearanceStatus(
-            department=dept,
-            status=ClearanceProcess.PENDING
-        )
-        initial_statuses.append(status)
-    
-    db_student.clearance_statuses = initial_statuses
-    # --- End of auto-population ---
+    # This might raise an exception if username/email exists, which is good.
+    db_user = user_crud.create_user(db, user=user_for_student)
 
+    # 2. Create the Student profile
+    db_student = Student(
+        full_name=student_data.full_name,
+        matric_no=student_data.matric_no,
+        email=student_data.email,
+        department=student_data.department,
+        # Note: The User linkage is handled via the RFID tag linking process
+    )
     db.add(db_student)
     db.commit()
     db.refresh(db_student)
-    return db_student
-
-def update_student(db: Session, student_id: int, student_update: StudentUpdate) -> Optional[Student]:
-    """
-    Updates a student's information.
-    If a new password is provided, it will be hashed.
-    """
-    db_student = db.get(Student, student_id)
-    if not db_student:
-        return None
-
-    update_data = student_update.model_dump(exclude_unset=True)
-    
-    if "password" in update_data:
-        update_data["hashed_password"] = hash_password(update_data.pop("password"))
 
-    for key, value in update_data.items():
-        setattr(db_student, key, value)
+    # 3. Initialize all clearance statuses for the new student
+    for dept in ClearanceDepartment:
+        status = ClearanceStatus(student_id=db_student.id, department=dept)
+        db.add(status)
     
-    db.add(db_student)
     db.commit()
     db.refresh(db_student)
+    
     return db_student
 
-def delete_student(db: Session, student_id: int) -> Optional[Student]:
-    """
+def update_student(db: Session, student: Student, updates: StudentUpdate) -> Student:
+    """Updates a student's profile information."""
+    student = get_student_by_id(db, student_id=student.id)
+    if not student:
+        return None
+    
+    update_data = updates.model_dump(exclude_unset=True)
+    student.sqlmodel_update(update_data)
+    db.add(student)
+    db.commit()
+    db.refresh(student)
+    return student
 
-    Deletes a student from the database.
-    All associated clearance statuses and the linked RFID tag will also be 
-    deleted automatically due to the cascade settings in the data models.
-    """
-    db_student = db.get(Student, student_id)
-    if not db_student:
+def delete_student(db: Session, student_id: int) -> Student | None:
+    """Deletes a student and their associated clearance records."""
+    student_to_delete = db.get(Student, student_id)
+    if not student_to_delete:
         return None
     
-    db.delete(db_student)
+    # Also delete the associated user account
+    user_to_delete = user_crud.get_user_by_username(db, username=student_to_delete.matric_no)
+    if user_to_delete:
+        db.delete(user_to_delete)
+
+    db.delete(student_to_delete)
     db.commit()
-    return db_student
+    return student_to_delete

src/crud/users.py

@@ -2,7 +2,7 @@ from sqlmodel import Session, select
 from typing import List, Optional
 
 from src.models import User, UserCreate, UserUpdate, RFIDTag
-from src.auth import hash_password
+from src.crud.utils import hash_password
 
 # --- Read Operations ---
 
@@ -19,67 +19,58 @@ def get_user_by_email(db: Session, email: str) -> Optional[User]:
     return db.exec(select(User).where(User.email == email)).first()
 
 def get_user_by_tag_id(db: Session, tag_id: str) -> Optional[User]:
-    """Retrieves a user by their linked RFID tag ID."""
-    statement = select(User).join(RFIDTag).where(RFIDTag.tag_id == tag_id)
-    return db.exec(statement).first()
+    """Get user by RFID tag ID."""
+    from src.models import RFIDTag
+    tag = db.exec(select(RFIDTag).where(RFIDTag.tag_id == tag_id)).first()
+    if tag and tag.user_id:
+        return db.exec(select(User).where(User.id == tag.user_id)).first()
+    return None
 
 def get_all_users(db: Session, skip: int = 0, limit: int = 100) -> List[User]:
     """Retrieves a paginated list of all users."""
     return db.exec(select(User).offset(skip).limit(limit)).all()
 
-# --- Write Operations ---
-
 def create_user(db: Session, user: UserCreate) -> User:
-    """
-    Creates a new user.
-    - Hashes the password before saving.
-    - The router should handle checks for existing username/email to provide clean HTTP errors.
-    """
-    hashed_pass = hash_password(user.password)
+    """Creates a new user and hashes their password."""
+    hashed_password = hash_password(user.password)
     db_user = User(
         username=user.username,
+        hashed_password=hashed_password,
         email=user.email,
         full_name=user.full_name,
-        hashed_password=hashed_pass,
-        role=user.role
+        role=user.role,
+        department=user.department
     )
     db.add(db_user)
     db.commit()
     db.refresh(db_user)
     return db_user
 
-def update_user(db: Session, user_id: int, user_update: UserUpdate) -> Optional[User]:
-    """
-    Updates a user's information.
-    - If a new password is provided, it will be hashed.
-    """
-    db_user = db.get(User, user_id)
-    if not db_user:
+def update_user(db: Session, user: User, updates: UserUpdate) -> User:
+    """Updates a user's information."""
+    user = get_user_by_id(db, user_id=user.id)
+    if not user:
         return None
-
-    update_data = user_update.model_dump(exclude_unset=True)
     
-    # Hash password if it's being updated
+    update_data = updates.model_dump(exclude_unset=True)
+    
     if "password" in update_data:
+        # Hash the new password if it's being updated
         update_data["hashed_password"] = hash_password(update_data.pop("password"))
-
-    for key, value in update_data.items():
-        setattr(db_user, key, value)
     
-    db.add(db_user)
+    user.sqlmodel_update(update_data)
+    
+    db.add(user)
     db.commit()
-    db.refresh(db_user)
-    return db_user
+    db.refresh(user)
+    return user
 
-def delete_user(db: Session, user_id: int) -> Optional[User]:
-    """
-    Deletes a user from the database.
-    The linked RFID tag will also be deleted due to cascade settings.
-    """
-    db_user = db.get(User, user_id)
-    if not db_user:
+def delete_user(db: Session, user_id: int) -> User | None:
+    """Deletes a user by their ID."""
+    user_to_delete = db.get(User, user_id)
+    if not user_to_delete:
         return None
-    
-    db.delete(db_user)
+    db.delete(user_to_delete)
     db.commit()
-    return db_user
+    # The user object is no longer valid after deletion, so we return the in-memory object
+    return user_to_delete

src/crud/utils.py

@@ -1,14 +1,11 @@
 """
 Utility functions for CRUD operations.
 """
-import bcrypt
+from src.config import settings
 
-def hash_password(password: str) -> str:
-    """Hashes a password using bcrypt."""
-    return bcrypt.hashpw(password.encode('utf-8'), bcrypt.gensalt()).decode('utf-8')
+# --- Password Hashing ---
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    return settings.PWD_CONTEXT.verify(plain_password, hashed_password)
 
-def verify_password(plain_password: str, hashed_password_str: str) -> bool:
-    """Verifies a plain password against a hashed password."""
-    if not plain_password or not hashed_password_str:
-        return False
-    return bcrypt.checkpw(plain_password.encode('utf-8'), hashed_password_str.encode('utf-8'))
+def hash_password(password: str) -> str:
+    return settings.PWD_CONTEXT.hash(password)

src/models.py

@@ -70,6 +70,7 @@ class Device(SQLModel, table=True):
     device_name: str = Field(unique=True, index=True)
     api_key: str = Field(unique=True, index=True)
     location: str
+    department: Department  # ADD THIS - referenced in devices.py CRUD
     is_active: bool = Field(default=True)
 
 # --- Pydantic Models for API Operations ---
@@ -156,10 +157,10 @@ class RFIDScanRequest(SQLModel):
     tag_id: str
 
 class RFIDStatusResponse(SQLModel):
-    status: str
+    status: str  # "found" or "unregistered"  # "found" or "unregistered"
     full_name: Optional[str] = None
-    message: Optional[str] = None
-    clearance: Optional[str] = None
+    entity_type: Optional[str] = None  # "Student", "Admin", "Staff"None  # "Student", "Admin", "Staff"
+    clearance_status: Optional[str] = None  # "Fully Cleared", "Pending Clearance", "N/A" = None  # "Fully Cleared", "Pending Clearance", "N/A"
 
 class TagScan(SQLModel):
     tag_id: str
@@ -168,10 +169,12 @@ class TagScan(SQLModel):
 class DeviceCreate(SQLModel):
     device_name: str
     location: str
+    department: Department  # ADD THIS
 
 class DeviceRead(SQLModel):
     id: int
     device_name: str
     api_key: str
     location: str
+    department: Department  # ADD THIS
     is_active: bool

src/routers/admin.py

@@ -1,63 +1,94 @@
 from fastapi import APIRouter, Depends, HTTPException, status, Query
-from sqlmodel import Session
+from sqlmodel import Session, SQLModel
 from typing import List, Optional, Dict
 
 from src.database import get_session
-from src.auth import get_current_active_user
+from src.auth import get_current_active_user, get_api_key
 from src.models import (
     User, UserCreate, UserRead, UserUpdate, Role,
-    Student, StudentCreate, StudentRead, StudentUpdate, StudentReadWithClearance,
-    TagLink, RFIDTagRead, TagScan,
-    Device, DeviceCreate, DeviceRead
+    Student, StudentCreate, StudentReadWithClearance, StudentUpdate, StudentRead,
+    TagLink, RFIDTagRead, Device, DeviceCreate, DeviceRead, TagScan
 )
 from src.crud import users as user_crud
 from src.crud import students as student_crud
 from src.crud import tag_linking as tag_crud
 from src.crud import devices as device_crud
 
-# In-memory storage for last scanned tags by an admin.
-# Key: admin user ID, Value: last scanned tag ID.
-# This is simple and effective for a non-distributed system.
+# --- New State Management for Secure Admin Scanning ---
+
+# Maps a device's API key to the admin user ID who activated it.
+# This "activates" a scanner for a specific admin.
+activated_scanners: Dict[str, int] = {} 
+
+# Stores the last tag scanned by a device, keyed by the admin ID who was waiting.
 admin_scanned_tags: Dict[int, str] = {}
 
-# Define the router.
-# It's accessible to both Admins and Staff, providing a unified management panel.
+
+# Define the main administrative router
 router = APIRouter(
     prefix="/admin",
     tags=["Administration"],
     dependencies=[Depends(get_current_active_user(required_roles=[Role.ADMIN, Role.STAFF]))],
 )
 
-# --- Admin Tag Scanning for Web UI ---
+# --- New Secure Scanning Workflow ---
 
-@router.post("/tags/scan", status_code=status.HTTP_204_NO_CONTENT)
-def report_scanned_tag(
-    scan_data: TagScan,
+class ActivationRequest(SQLModel):
+    device_id: int
+
+@router.post("/scanners/activate", status_code=status.HTTP_204_NO_CONTENT)
+def activate_admin_scanner(
+    activation: ActivationRequest,
+    db: Session = Depends(get_session),
     current_user: User = Depends(get_current_active_user(required_roles=[Role.ADMIN, Role.STAFF]))
 ):
     """
-    (Admin & Staff) Endpoint for the admin's desk RFID reader to report a scanned tag.
-    The backend stores this tag ID temporarily against the admin's user ID.
+    STEP 1 (Browser): Admin clicks "Scan Card" in the UI.
+    The browser calls this endpoint to 'arm' their designated desk scanner.
+    """
+    device = device_crud.get_device_by_id(db, device_id=activation.device_id)
+    if not device:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Device not found.")
+    
+    # Map the device's API key to the currently logged-in admin's ID.
+    activated_scanners[device.api_key] = current_user.id
+    return
+
+
+@router.post("/scanners/scan", status_code=status.HTTP_204_NO_CONTENT)
+def receive_scan_from_activated_device(
+    scan_data: TagScan,
+    api_key: str = Depends(get_api_key) # Device authenticates with its API Key
+):
+    """
+    STEP 2 (Device): The ESP32 device sends the scanned tag to this endpoint.
+    This endpoint is protected by the device's API Key.
     """
-    admin_scanned_tags[current_user.id] = scan_data.tag_id
+    # Check if this device was activated by an admin.
+    admin_id = activated_scanners.pop(api_key, None)
+    if admin_id is None:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="This scanner has not been activated for a scan.")
+
+    # Store the scanned tag against the admin who was waiting for it.
+    admin_scanned_tags[admin_id] = scan_data.tag_id
     return
 
-@router.get("/tags/scan", response_model=TagScan)
-def retrieve_scanned_tag(
+@router.get("/scanners/retrieve", response_model=TagScan)
+def retrieve_scanned_tag_for_ui(
     current_user: User = Depends(get_current_active_user(required_roles=[Role.ADMIN, Role.STAFF]))
 ):
     """
-    (Admin & Staff) Endpoint for the admin's web portal to retrieve the last scanned tag.
-    The tag is removed after being retrieved to prevent re-use.
+    STEP 3 (Browser): The browser polls this endpoint to get the tag ID
+    that the device reported in STEP 2.
     """
     tag_id = admin_scanned_tags.pop(current_user.id, None)
     if not tag_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="No tag has been scanned recently.")
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="No tag has been scanned by the activated device yet.")
     return TagScan(tag_id=tag_id)
 
 
-# --- Student Management (Admin + Staff) ---
-
+# --- All other administrative endpoints remain the same ---
+# ... (Student Management, User Management, etc.) ...
 @router.post("/students/", response_model=StudentReadWithClearance, status_code=status.HTTP_201_CREATED)
 def create_student(student: StudentCreate, db: Session = Depends(get_session)):
     """(Admin & Staff) Creates a new student and initializes their clearance status."""
@@ -128,7 +159,10 @@ def unlink_rfid_tag(tag_id: str, db: Session = Depends(get_session)):
     """(Admin & Staff) Unlinks an RFID tag, making it available again."""
     deleted_tag = tag_crud.unlink_tag(db, tag_id)
     if not deleted_tag:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="RFID Tag not found.")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="RFID Tag not found."
+        )
     return deleted_tag
 
 
@@ -142,12 +176,18 @@ def require_super_admin(current_user: User = Depends(get_current_active_user()))
             detail="This action requires Super Admin privileges."
         )
 
-@router.post("/users/", response_model=UserRead, status_code=status.HTTP_201_CREATED, dependencies=[Depends(require_super_admin)])
-def create_user(user: UserCreate, db: Session = Depends(get_session)):
-    """(Super Admin Only) Creates a new user (Staff or Admin)."""
-    db_user = user_crud.get_user_by_username(db, username=user.username)
-    if db_user:
-        raise HTTPException(status_code=400, detail="Username already registered")
+@router.post(
+    "/users/",
+    response_model=UserRead,
+    status_code=status.HTTP_201_CREATED,
+    dependencies=[Depends(get_current_active_user(required_roles=[Role.ADMIN]))]
+)
+def create_user_as_admin(user: UserCreate, db: Session = Depends(get_session)):
+    """(Super Admin Only) Creates a new user (admin or staff)."""
+    if user_crud.get_user_by_username(db, username=user.username):
+        raise HTTPException(status_code=400, detail="Username already registered.")
+    if user_crud.get_user_by_email(db, email=user.email):
+        raise HTTPException(status_code=400, detail="Email already registered.")
     return user_crud.create_user(db=db, user=user)
 
 @router.get("/users/", response_model=List[UserRead], dependencies=[Depends(require_super_admin)])

src/routers/rfid.py

@@ -4,7 +4,7 @@ from sqlmodel import Session
 
 from src.database import get_session
 from src.auth import get_api_key
-from src.models import RFIDStatusResponse, RFIDScanRequest
+from src.models import RFIDStatusResponse, RFIDScanRequest, ClearanceStatusEnum
 from src.crud import students as student_crud
 from src.crud import users as user_crud
 
@@ -28,9 +28,10 @@ def check_rfid_status(
     # 1. Check if the tag belongs to a student
     student = student_crud.get_student_by_tag_id(db, tag_id=tag_id)
     if student:
-        # Check overall clearance status
+        # Check overall clearance status using proper enum comparison
         is_cleared = all(
-            status.status == "approved" for status in student.clearance_statuses
+            clearance.status == ClearanceStatusEnum.APPROVED 
+            for clearance in student.clearance_statuses
         )
         clearance_status_str = "Fully Cleared" if is_cleared else "Pending Clearance"
         
@@ -47,7 +48,7 @@ def check_rfid_status(
         return RFIDStatusResponse(
             status="found",
             full_name=user.full_name,
-            entity_type=user.role.value, # e.g. "Admin" or "Staff"
+            entity_type=user.role.value.title(),  # "Admin" or "Staff"
             clearance_status="N/A",
         )
 

src/routers/students.py

@@ -1,29 +1,36 @@
 from fastapi import APIRouter, Depends, HTTPException, status
-from sqlmodel import Session
+from sqlmodel import Session, SQLModel
 
-from src.database import get_session
 from src.auth import get_current_active_user
-from src.models import Student, StudentReadWithClearance
+from src.database import get_session
+from src.models import StudentReadWithClearance
+
+# This is the new request body model for the POST request.
+class StudentLookupRequest(SQLModel):
+    matric_no: str
 
 router = APIRouter(
     prefix="/students",
     tags=["Students"],
+    # This endpoint still requires a user to be logged in.
+    dependencies=[Depends(get_current_active_user)]
 )
 
-@router.get("/me", response_model=StudentReadWithClearance)
-def read_student_me(
-    # This dependency ensures the user is an authenticated student
-    # and injects their database object into the 'current_student' parameter.
-    current_student: Student = Depends(get_current_active_user)
+@router.post("/lookup", response_model=StudentReadWithClearance)
+def lookup_student_by_matric_no(
+    request: StudentLookupRequest,
+    db: Session = Depends(get_session)
 ):
     """
-    Endpoint for a logged-in student to retrieve their own profile
-    and clearance information. The user is identified via their JWT token.
+    Endpoint for a logged-in user to retrieve a student's profile
+    and clearance information by providing their matriculation number.
     """
-    # Because the dependency returns the full student object, we can just return it.
-    # No need for another database call.
-    if not current_student:
-         # This should not happen if the dependency is set up correctly
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Student not found")
-    return current_student
+    student = student_crud.get_student_by_matric_no(db=db, matric_no=request.matric_no)
 
+    if not student:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, 
+            detail="Student with the provided matriculation number not found."
+        )
+    
+    return student

src/routers/token.py

@@ -34,8 +34,9 @@ async def login_for_access_token(
         
     # Create the JWT token
     access_token_expires = timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    # FIX: Use username instead of email
     access_token = create_access_token(
-        data={"sub": user.email}, expires_delta=access_token_expires
+        data={"sub": user.username}, expires_delta=access_token_expires  # CHANGED from user.email
     )
     
     return {"access_token": access_token, "token_type": "bearer"}