All changes commit

src/config.py

@@ -0,0 +1,15 @@
+from pydantic_settings import BaseSettings
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+class Settings(BaseSettings):
+    POSTGRES_URI: str
+    JWT_SECRET_KEY: str = os.getenv("JWT_SECRET_KEY", "default_secret_key")
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
+    
+    class Config:
+        env_file = ".env"
+
+settings = Settings()

src/crud/__init__.py

@@ -0,0 +1,42 @@
+"""
+CRUD Package Initializer
+
+This file makes the 'crud' directory a Python package and imports all the
+public CRUD functions from the submodules. This allows you to import any
+CRUD function directly from `src.crud` instead of the specific submodule,
+keeping the router imports clean.
+"""
+
+from .students import (
+    create_student,
+    get_all_students,
+    get_student_by_student_id,
+    get_student_by_tag_id,
+    update_student_tag_id,
+    delete_student,
+)
+from .users import (
+    create_user,
+    get_user_by_username,
+    get_user_by_tag_id,
+    update_user_tag_id,
+    get_user_by_id,
+    delete_user,
+)
+from .devices import (
+    get_device_by_id_str,
+    get_device_by_api_key,
+    create_device_log,
+    update_device_last_seen,
+    delete_device,
+)
+from .clearance import (
+    get_clearance_statuses_by_student_id,
+    update_clearance_status,
+    delete_clearance_status, # <-- Added the new delete function
+)
+from .tag_linking import (
+    create_pending_tag_link,
+    get_pending_link_by_device,
+    delete_pending_link,
+)

src/crud/clearance.py

@@ -0,0 +1,77 @@
+"""
+CRUD operations for student Clearance Statuses.
+"""
+from sqlalchemy.orm import Session
+from fastapi import HTTPException, status
+
+from src import models
+
+def get_clearance_statuses_by_student_id(db: Session, student_id: str) -> list[models.ClearanceStatus]:
+    """
+    Fetches all existing clearance status records for a given student.
+    """
+    return db.query(models.ClearanceStatus).filter(models.ClearanceStatus.student_id == student_id).all()
+
+def update_clearance_status(
+    db: Session,
+    student_id: str,
+    department: models.ClearanceDepartment,
+    new_status: models.ClearanceStatusEnum,
+    remarks: str,
+    cleared_by_user_id: int
+) -> models.ClearanceStatus:
+    """
+    Updates or creates a clearance status for a student in a specific department.
+    """
+    student = db.query(models.Student).filter(models.Student.student_id == student_id).first()
+    if not student:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Student with ID '{student_id}' not found."
+        )
+
+    existing_status = db.query(models.ClearanceStatus).filter(
+        models.ClearanceStatus.student_id == student_id,
+        models.ClearanceStatus.department == department
+    ).first()
+
+    if existing_status:
+        existing_status.status = new_status
+        existing_status.remarks = remarks
+        existing_status.cleared_by = cleared_by_user_id
+        db_status = existing_status
+    else:
+        db_status = models.ClearanceStatus(
+            student_id=student_id,
+            department=department,
+            status=new_status,
+            remarks=remarks,
+            cleared_by=cleared_by_user_id
+        )
+        db.add(db_status)
+
+    db.commit()
+    db.refresh(db_status)
+    return db_status
+
+def delete_clearance_status(
+    db: Session,
+    student_id: str,
+    department: models.ClearanceDepartment
+) -> models.ClearanceStatus | None:
+    """
+    Deletes a specific clearance status record for a student.
+
+    This effectively resets the status for that department to the default state.
+    Returns the deleted object if found, otherwise returns None.
+    """
+    status_to_delete = db.query(models.ClearanceStatus).filter(
+        models.ClearanceStatus.student_id == student_id,
+        models.ClearanceStatus.department == department
+    ).first()
+
+    if status_to_delete:
+        db.delete(status_to_delete)
+        db.commit()
+
+    return status_to_delete

src/crud/devices.py

@@ -0,0 +1,52 @@
+"""
+CRUD operations for Devices and Device Logs.
+"""
+from sqlalchemy.orm import Session
+from datetime import datetime
+from fastapi import HTTPException, status
+
+from src import models
+
+def get_device_by_id_str(db: Session, device_id: str) -> models.Device | None:
+    """Fetches a device by its public device_id string."""
+    return db.query(models.Device).filter(models.Device.device_id == device_id).first()
+
+def get_device_by_api_key(db: Session, api_key: str) -> models.Device | None:
+    """Fetches a device by its unique API key for authentication."""
+    return db.query(models.Device).filter(models.Device.api_key == api_key).first()
+
+def update_device_last_seen(db: Session, device_id: int):
+    """Updates the last_seen timestamp for a device."""
+    db.query(models.Device).filter(models.Device.id == device_id).update({"last_seen": datetime.utcnow()})
+    db.commit()
+
+def create_device_log(db: Session, log_data: dict):
+    """Creates a new log entry for a device action."""
+    new_log = models.DeviceLog(**log_data)
+    db.add(new_log)
+    db.commit()
+    db.refresh(new_log)
+    return new_log
+
+def delete_device(db: Session, device_id_str: str) -> models.Device:
+    """
+    Deletes a device and all of its associated records (logs, pending links).
+    """
+    device_to_delete = get_device_by_id_str(db, device_id_str)
+    if not device_to_delete:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Device with ID '{device_id_str}' not found."
+        )
+    
+    device_pk_id = device_to_delete.id
+
+    # Delete all dependent records first to maintain foreign key integrity
+    db.query(models.DeviceLog).filter(models.DeviceLog.device_fk_id == device_pk_id).delete(synchronize_session=False)
+    db.query(models.PendingTagLink).filter(models.PendingTagLink.device_id_fk == device_pk_id).delete(synchronize_session=False)
+
+    # Now delete the device itself
+    db.delete(device_to_delete)
+    db.commit()
+
+    return device_to_delete

src/crud/students.py

@@ -0,0 +1,79 @@
+"""
+CRUD operations for Students.
+"""
+from sqlalchemy.orm import Session
+from fastapi import HTTPException, status
+
+from src import models
+
+def get_student_by_student_id(db: Session, student_id: str) -> models.Student | None:
+    """Fetches a student by their unique student ID."""
+    return db.query(models.Student).filter(models.Student.student_id == student_id).first()
+
+def get_student_by_tag_id(db: Session, tag_id: str) -> models.Student | None:
+    """Fetches a student by their RFID tag ID."""
+    return db.query(models.Student).filter(models.Student.tag_id == tag_id).first()
+
+def get_all_students(db: Session, skip: int = 0, limit: int = 100) -> list[models.Student]:
+    """Fetches all students with pagination."""
+    return db.query(models.Student).offset(skip).limit(limit).all()
+
+def create_student(db: Session, student: models.StudentCreate) -> models.Student:
+    """Creates a new student in the database."""
+    db_student = get_student_by_student_id(db, student.student_id)
+    if db_student:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Student with ID '{student.student_id}' already exists."
+        )
+    
+    new_student = models.Student(**student.model_dump())
+    db.add(new_student)
+    db.commit()
+    db.refresh(new_student)
+    return new_student
+
+def update_student_tag_id(db: Session, student_id: str, tag_id: str) -> models.Student:
+    """Updates the RFID tag ID for a specific student."""
+    db_student = get_student_by_student_id(db, student_id)
+    if not db_student:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Student not found")
+    
+    existing_tag_user = get_student_by_tag_id(db, tag_id)
+    if existing_tag_user and existing_tag_user.student_id != student_id:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Tag ID '{tag_id}' is already assigned to another student."
+        )
+
+    db_student.tag_id = tag_id
+    db.commit()
+    db.refresh(db_student)
+    return db_student
+
+def delete_student(db: Session, student_id: str) -> models.Student:
+    """
+    Deletes a student and all of their associated clearance records.
+    
+    This function first finds the student, then deletes all related rows in the
+    'clearance_statuses' table before finally deleting the student record
+    to maintain database integrity.
+    """
+    student_to_delete = get_student_by_student_id(db, student_id)
+    if not student_to_delete:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Student with ID '{student_id}' not found."
+        )
+
+    # First, delete all associated clearance statuses for this student.
+    # This is crucial to prevent foreign key constraint violations.
+    db.query(models.ClearanceStatus).filter(
+        models.ClearanceStatus.student_id == student_id
+    ).delete(synchronize_session=False)
+
+    # Now, delete the student record itself.
+    db.delete(student_to_delete)
+    db.commit()
+    
+    return student_to_delete

src/crud/tag_linking.py

@@ -0,0 +1,43 @@
+"""
+CRUD operations for the PendingTagLink model.
+"""
+from sqlalchemy.orm import Session
+from datetime import datetime
+
+from src import models
+
+def create_pending_tag_link(db: Session, link_details: models.PrepareTagLinkRequest, initiated_by_id: int, expires_at: datetime) -> models.PendingTagLink:
+    """Creates a new pending tag link request in the database."""
+    
+    device = db.query(models.Device).filter(models.Device.device_id == link_details.device_identifier).first()
+    if not device:
+        # This check should ideally be in the router, but adding here as a safeguard
+        return None
+
+    new_link = models.PendingTagLink(
+        device_id_fk=device.id,
+        target_user_type=link_details.target_user_type,
+        target_identifier=link_details.target_identifier,
+        initiated_by_user_id=initiated_by_id,
+        expires_at=expires_at,
+    )
+    db.add(new_link)
+    db.commit()
+    db.refresh(new_link)
+    return new_link
+
+def get_pending_link_by_device(db: Session, device_id: int) -> models.PendingTagLink | None:
+    """
+    Fetches the active (non-expired) pending tag link for a specific device.
+    """
+    return db.query(models.PendingTagLink).filter(
+        models.PendingTagLink.device_id_fk == device_id,
+        models.PendingTagLink.expires_at > datetime.utcnow()
+    ).first()
+
+def delete_pending_link(db: Session, link_id: int):
+    """Deletes a pending link, typically after it has been used."""
+    link_to_delete = db.query(models.PendingTagLink).filter(models.PendingTagLink.id == link_id).first()
+    if link_to_delete:
+        db.delete(link_to_delete)
+        db.commit()

src/crud/users.py

@@ -0,0 +1,93 @@
+"""
+CRUD operations for Users (Admins, Staff).
+"""
+from sqlalchemy.orm import Session
+from fastapi import HTTPException, status
+
+from src import models
+from src.auth import get_password_hash # Assuming this is in your auth file
+
+def get_user_by_id(db: Session, user_id: int) -> models.User | None:
+    """Fetches a user by their primary key ID."""
+    return db.query(models.User).filter(models.User.id == user_id).first()
+
+def get_user_by_username(db: Session, username: str) -> models.User | None:
+    """Fetches a user by their unique username."""
+    return db.query(models.User).filter(models.User.username == username).first()
+
+def get_user_by_tag_id(db: Session, tag_id: str) -> models.User | None:
+    """Fetches a user by their RFID tag ID."""
+    return db.query(models.User).filter(models.User.tag_id == tag_id).first()
+
+def create_user(db: Session, user: models.UserCreate) -> models.User:
+    """Creates a new user in the database."""
+    if get_user_by_username(db, user.username):
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Username '{user.username}' is already registered."
+        )
+    hashed_password = get_password_hash(user.password)
+    new_user = models.User(
+        username=user.username,
+        hashed_password=hashed_password,
+        role=user.role,
+        department=user.department,
+        tag_id=user.tag_id
+    )
+    db.add(new_user)
+    db.commit()
+    db.refresh(new_user)
+    return new_user
+
+def update_user_tag_id(db: Session, username: str, tag_id: str) -> models.User:
+    """Updates the RFID tag ID for a specific user."""
+    db_user = get_user_by_username(db, username)
+    if not db_user:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+
+    existing_tag_user = get_user_by_tag_id(db, tag_id)
+    if existing_tag_user and existing_tag_user.username != username:
+         raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Tag ID '{tag_id}' is already assigned to another user."
+        )
+    
+    db_user.tag_id = tag_id
+    db.commit()
+    db.refresh(db_user)
+    return db_user
+
+def delete_user(db: Session, username_to_delete: str, current_admin: models.User) -> models.User:
+    """
+    Deletes a user, ensuring an admin cannot delete themselves or the last admin.
+    """
+    if username_to_delete == current_admin.username:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Admins cannot delete their own account."
+        )
+
+    user_to_delete = get_user_by_username(db, username_to_delete)
+    if not user_to_delete:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"User '{username_to_delete}' not found."
+        )
+
+    # Prevent deleting the last admin account
+    if user_to_delete.role == models.UserRole.ADMIN:
+        admin_count = db.query(models.User).filter(models.User.role == models.UserRole.ADMIN).count()
+        if admin_count <= 1:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Cannot delete the last remaining admin account."
+            )
+
+    # Handle dependencies: set foreign keys to NULL where a user is referenced
+    db.query(models.ClearanceStatus).filter(models.ClearanceStatus.cleared_by == user_to_delete.id).update({"cleared_by": None})
+    db.query(models.PendingTagLink).filter(models.PendingTagLink.initiated_by_user_id == user_to_delete.id).delete()
+
+    db.delete(user_to_delete)
+    db.commit()
+    
+    return user_to_delete

src/models.py

@@ -1,234 +1,165 @@
-from pydantic import BaseModel, Field, EmailStr
-from typing import List, Optional, Dict
-from sqlalchemy import Column, Integer, String, Boolean, DateTime, ForeignKey, Enum as SQLAlchemyEnum
-from sqlalchemy.orm import relationship
-from sqlalchemy.ext.declarative import declarative_base
-from datetime import datetime, timedelta
-import enum
-import os
+"""
+Pydantic Models for data validation and serialization.
+SQLAlchemy Models for database table definitions.
+"""
+from pydantic import BaseModel, Field
+from typing import List, Optional, Union
+from enum import Enum
+
+from sqlalchemy import (
+    Boolean, Column, ForeignKey, Integer, String,
+    create_engine, Enum as SQLAlchemyEnum
+)
+from sqlalchemy.orm import relationship, sessionmaker, declarative_base
+
+# ==============================================================================
+# Database (SQLAlchemy) Models
+# ==============================================================================
 
 Base = declarative_base()
 
-JWT_SECRET_KEY = os.getenv("JWT_SECRET_KEY", "your-default-secret-key-for-dev-only-CHANGE-ME")
-if JWT_SECRET_KEY == "your-default-secret-key-for-dev-only-CHANGE-ME":
-    print("WARNING: Using default JWT_SECRET_KEY. Please set a strong JWT_SECRET_KEY environment variable for production.")
-
-# Enums - Values are now ALL CAPS to match the PostgreSQL ENUM type labels, based on testing.
-class UserRole(str, enum.Enum):
-    STUDENT = "student"
-    STAFF = "staff"
-    ADMIN = "admin"
-
-class ClearanceStatusEnum(str, enum.Enum):
-    COMPLETED = "COMPLETED"
-    NOT_COMPLETED = "NOT_COMPLETED"
-    PENDING = "PENDING"
-
-class ClearanceDepartment(str, enum.Enum):
-    DEPARTMENTAL = "DEPARTMENTAL"
-    LIBRARY = "LIBRARY"
-    BURSARY = "BURSARY"
-    ALUMNI = "ALUMNI"
-
-class TargetUserType(str, enum.Enum):
-    # Corrected to ALL CAPS to match other enums and likely DB schema
-    STUDENT = "STUDENT"
-    STAFF_ADMIN = "STAFF_ADMIN"
-
-class OverallClearanceStatusEnum(str, enum.Enum):
-    COMPLETED = "COMPLETED"
-    PENDING = "PENDING"
-
-# Helper for SQLAlchemyEnum to ensure values are used
-def enum_values_callable(obj):
-    return [e.value for e in obj]
+class User(Base):
+    """Database model for Users (Admins, Staff)."""
+    __tablename__ = "users"
+    id = Column(Integer, primary_key=True, index=True)
+    username = Column(String, unique=True, index=True, nullable=False)
+    hashed_password = Column(String, nullable=False)
+    name = Column(String, nullable=False)
+    role = Column(String, default="staff")
+    is_active = Column(Boolean, default=True)
+    tag_id = Column(String, unique=True, index=True, nullable=True)
 
-# --- ORM Model Definitions ---
 
 class Student(Base):
+    """Database model for Students."""
     __tablename__ = "students"
     id = Column(Integer, primary_key=True, index=True)
     student_id = Column(String, unique=True, index=True, nullable=False)
     name = Column(String, nullable=False)
-    email = Column(String, unique=True, index=True, nullable=True)
     department = Column(String, nullable=False)
     tag_id = Column(String, unique=True, index=True, nullable=True)
-    created_at = Column(DateTime, default=datetime.utcnow)
-    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
 
-class User(Base):
-    __tablename__ = "users"
-    id = Column(Integer, primary_key=True, index=True)
-    username = Column(String, unique=True, index=True, nullable=False)
-    hashed_password = Column(String, nullable=False)
-    role = Column(SQLAlchemyEnum(UserRole, name="userrole", create_type=False, values_callable=enum_values_callable), default=UserRole.STAFF, nullable=False)
-    department = Column(SQLAlchemyEnum(ClearanceDepartment, name="clearancedepartment", create_type=False, values_callable=enum_values_callable), nullable=True)
-    tag_id = Column(String, unique=True, index=True, nullable=True)
-    is_active = Column(Boolean, default=True)
-    created_at = Column(DateTime, default=datetime.utcnow)
-    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    clearance_statuses = relationship("ClearanceStatus", back_populates="student")
+
 
 class ClearanceStatus(Base):
+    """Database model for individual clearance items for a student."""
     __tablename__ = "clearance_statuses"
-    id = Column(Integer, primary_key=True, autoincrement=True, index=True)
-    student_id = Column(String, ForeignKey("students.student_id"), index=True, nullable=False)
-    department = Column(SQLAlchemyEnum(ClearanceDepartment, name="clearancedepartment", create_type=False, values_callable=enum_values_callable), index=True, nullable=False)
-    status = Column(SQLAlchemyEnum(ClearanceStatusEnum, name="clearancestatusenum", create_type=False, values_callable=enum_values_callable), default=ClearanceStatusEnum.NOT_COMPLETED, nullable=False)
-    remarks = Column(String, nullable=True)
-    cleared_by = Column(Integer, ForeignKey("users.id"), nullable=True)
-    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
-    created_at = Column(DateTime, default=datetime.utcnow)
+    id = Column(Integer, primary_key=True, index=True)
+    student_id = Column(String, ForeignKey("students.student_id"), nullable=False)
+    department = Column(String, nullable=False)
+    status = Column(String, default="PENDING")
+    
+    student = relationship("Student", back_populates="clearance_statuses")
+
+
+class UserTypeEnum(str, Enum):
+    """Enum for user types."""
+    STUDENT = "student"
+    USER = "user"
+
 
 class Device(Base):
+    """Database model for RFID reader devices."""
     __tablename__ = "devices"
-    id = Column(Integer, primary_key=True, index=True, autoincrement=True)
-    name = Column(String, index=True, nullable=True)
-    device_id = Column(String, unique=True, index=True, nullable=True)
+    id = Column(Integer, primary_key=True, index=True)
+    device_id_str = Column(String, unique=True, index=True, nullable=False)
     location = Column(String, nullable=True)
-    api_key = Column(String, unique=True, index=True, nullable=False)
-    is_active = Column(Boolean, default=True)
-    description = Column(String, nullable=True)
-    created_at = Column(DateTime, default=datetime.utcnow)
-    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
-    last_seen = Column(DateTime, nullable=True)
-
-class PendingTagLink(Base):
-    __tablename__ = "pending_tag_links"
-    id = Column(Integer, primary_key=True, index=True, autoincrement=True)
-    device_id_fk = Column(Integer, ForeignKey("devices.id"), index=True, nullable=False, name="device_id")
-    # ** FIX: Correctly define the column using SQLAlchemyEnum **
-    target_user_type = Column(SQLAlchemyEnum(TargetUserType, name="targetusertype", create_type=False, values_callable=enum_values_callable), nullable=False)
-    target_identifier = Column(String, nullable=False)
-    initiated_by_user_id = Column(Integer, ForeignKey("users.id"), nullable=False)
-    created_at = Column(DateTime, default=datetime.utcnow)
-    expires_at = Column(DateTime, nullable=False)
-
-class DeviceLog(Base):
-    __tablename__ = "device_logs"
-    id = Column(Integer, primary_key=True, index=True, autoincrement=True)
-    device_fk_id = Column(Integer, ForeignKey("devices.id"), index=True, nullable=True, name="device_id")
-    actual_device_id_str = Column(String, index=True, nullable=True)
-    tag_id_scanned = Column(String, index=True, nullable=True)
-    user_type = Column(String, nullable=True)
-    action = Column(String, nullable=False)
-    timestamp = Column(DateTime, default=datetime.utcnow, nullable=False)
-
-# --- Pydantic Models ---
-
-class StudentCreate(BaseModel):
-    student_id: str
-    name: str
-    email: Optional[EmailStr] = None
-    department: str
-    tag_id: Optional[str] = None
+    # Fields to temporarily link a device to a user for tag registration
+    link_for_user_id = Column(String, nullable=True)
+    link_for_user_type = Column(SQLAlchemyEnum(UserTypeEnum), nullable=True)
 
-class StudentResponse(BaseModel):
-    id: int
-    student_id: str
-    name: str
-    email: Optional[EmailStr] = None
-    department: str
-    tag_id: Optional[str] = None
-    created_at: datetime
-    updated_at: datetime
-    class Config: from_attributes = True
+# ==============================================================================
+# API (Pydantic) Models
+# ==============================================================================
 
+# --- User and Auth Models ---
 class UserBase(BaseModel):
     username: str
-    role: UserRole
-    department: Optional[ClearanceDepartment] = None
-    tag_id: Optional[str] = None
-    is_active: Optional[bool] = True
+    name: str
 
 class UserCreate(UserBase):
     password: str
+    role: str = "staff"
 
-class UserResponse(BaseModel):
+class UserResponse(UserBase):
     id: int
-    username: str
-    role: UserRole
-    department: Optional[ClearanceDepartment] = None
-    tag_id: Optional[str] = None
     is_active: bool
-    created_at: datetime
-    updated_at: datetime
-    class Config: from_attributes = True
+    role: str
+    tag_id: Optional[str] = None
+    
+    class Config:
+        from_attributes = True
 
-class ClearanceStatusCreate(BaseModel):
-    student_id: str
-    department: ClearanceDepartment
-    status: ClearanceStatusEnum
-    remarks: Optional[str] = None
+class Token(BaseModel):
+    access_token: str
+    token_type: str
 
-class ClearanceStatusItem(BaseModel):
-    department: ClearanceDepartment
-    status: ClearanceStatusEnum
-    remarks: Optional[str] = None
-    updated_at: datetime
-    class Config: from_attributes = True
+class TokenData(BaseModel):
+    username: Optional[str] = None
+
+
+# --- Student and Clearance Models ---
+class StudentBase(BaseModel):
+    student_id: str = Field(..., example="CST/18/123")
+    name: str = Field(..., example="John Doe")
+    department: str = Field(..., example="Computer Science")
 
-class ClearanceStatusResponse(BaseModel):
+class StudentCreate(StudentBase):
+    pass
+
+class StudentResponse(StudentBase):
     id: int
-    student_id: str
-    department: ClearanceDepartment
+    tag_id: Optional[str] = None
+    
+    class Config:
+        from_attributes = True
+
+class ClearanceStatusEnum(str, Enum):
+    PENDING = "PENDING"
+    COMPLETED = "COMPLETED"
+    REJECTED = "REJECTED"
+
+class OverallClearanceStatusEnum(str, Enum):
+    PENDING = "PENDING"
+    COMPLETED = "COMPLETED"
+
+class ClearanceStatusItem(BaseModel):
+    department: str
     status: ClearanceStatusEnum
-    remarks: Optional[str] = None
-    cleared_by: Optional[int] = None
-    updated_at: datetime
-    created_at: datetime
-    class Config: from_attributes = True
+    
+    class Config:
+        from_attributes = True
 
 class ClearanceDetail(BaseModel):
     student_id: str
     name: str
     department: str
-    clearance_items: List[ClearanceStatusItem]
     overall_status: OverallClearanceStatusEnum
-    class Config: from_attributes = True
-
-class DeviceRegister(BaseModel):
-    device_id: str
-    location: str
-
-class DeviceCreateAdmin(BaseModel):
-    name: str
-    description: Optional[str] = None
-    device_id: Optional[str] = None
-    location: Optional[str] = None
-
-class DeviceResponse(BaseModel):
-    id: int
-    name: Optional[str] = None
-    device_id: Optional[str] = None
-    location: Optional[str] = None
-    api_key: str
-    is_active: bool
-    description: Optional[str] = None
-    created_at: datetime
-    updated_at: datetime
-    last_seen: Optional[datetime] = None
-    class Config: from_attributes = True
-
-class TagScan(BaseModel):
-    device_id: str
-    tag_id: str
-    timestamp: Optional[datetime] = Field(default_factory=datetime.utcnow)
+    clearance_items: List[ClearanceStatusItem]
 
-class Token(BaseModel):
-    access_token: str
-    token_type: str
+class ClearanceStatusUpdate(BaseModel):
+    department: str
+    status: ClearanceStatusEnum
 
-class TokenData(BaseModel):
-    username: Optional[str] = None
-    role: Optional[UserRole] = None
 
+# --- Tag and Device Models ---
 class TagLinkRequest(BaseModel):
-    tag_id: str
-
-class PrepareTagLinkRequest(BaseModel):
-    device_identifier: str
-    target_user_type: TargetUserType
-    target_identifier: str
-
-class ScannedTagSubmit(BaseModel):
-    scanned_tag_id: str
+    tag_id: str = Field(..., example="A1B2C3D4")
+    
+class PrepareDeviceRequest(BaseModel):
+    device_id_str: str = Field(..., example="RFID-READER-01")
+    user_id_str: str # Can be student_id or username
+    user_type: UserTypeEnum
+
+# --- New RFID Models ---
+class RfidScanRequest(BaseModel):
+    """Request body for the unified RFID scan endpoint."""
+    tag_id: str = Field(..., description="The ID scanned from the RFID tag.", example="A1B2C3D4")
+    device_id: str = Field(..., description="The unique identifier of the RFID reader device.", example="RFID-READER-01")
+
+class RfidLinkSuccessResponse(BaseModel):
+    """Success response when a tag is linked."""
+    message: str = "Tag linked successfully."
+    user_id: str
+    user_type: UserTypeEnum

src/routers/admin.py

@@ -1,109 +1,83 @@
+"""
+Admin-only endpoints for managing system-wide operations like tag linking
+and deleting core resources like users and devices.
+"""
 from fastapi import APIRouter, Depends, HTTPException, status
-from sqlalchemy.orm import Session as SQLAlchemySessionType
-from typing import List, Optional, Dict
+from fastapi.concurrency import run_in_threadpool
+from sqlalchemy.orm import Session
+from datetime import datetime, timedelta
 
-from src import crud, models # crud functions are now sync ORM
+from src import crud, models
+from src.auth import get_current_active_admin_user, get_current_active_user
 from src.database import get_db
-from src.auth import (
-    get_current_active_admin_user_from_token, # Returns ORM User model (Token-based)
-)
-from fastapi.concurrency import run_in_threadpool 
 
 router = APIRouter(
     prefix="/api/admin",
-    tags=["admin"],
-    dependencies=[Depends(get_current_active_admin_user_from_token)]
+    tags=["Admin"],
+    dependencies=[Depends(get_current_active_admin_user)]
 )
 
-# --- Device Management Endpoints (Synchronous ORM) ---
-@router.post("/devices/", response_model=models.DeviceResponse, status_code=status.HTTP_201_CREATED)
-def register_new_device_admin( # Endpoint is synchronous
-    device_data: models.DeviceCreateAdmin,
-    db: SQLAlchemySessionType = Depends(get_db),
-    current_admin_orm: models.User = Depends(get_current_active_admin_user_from_token) # For logging who did it
+@router.post("/prepare-tag-link", status_code=status.HTTP_202_ACCEPTED, response_model=dict)
+async def prepare_device_for_tag_linking(
+    request: models.PrepareTagLinkRequest,
+    current_user: models.User = Depends(get_current_active_user),
+    db: Session = Depends(get_db)
 ):
     """
-    Admin registers a new ESP32/RFID reader device. Uses ORM.
+    Admin: Initiates a request to link a tag. This creates a temporary,
+    expiring 'PendingTagLink' record for a device.
     """
-    print(f"Admin '{current_admin_orm.username}' creating device: {device_data.name}")
-    try:
-        created_device_orm = crud.create_device(db=db, device_data=device_data)
-    except HTTPException as e:
-        raise e
-    return created_device_orm # Pydantic converts from ORM model
+    device = await run_in_threadpool(crud.get_device_by_id_str, db, request.device_identifier)
+    if not device or not device.is_active:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Device not found or is inactive.")
+    
+    if request.target_user_type == models.TargetUserType.STUDENT:
+        target = await run_in_threadpool(crud.get_student_by_student_id, db, request.target_identifier)
+    else:
+        target = await run_in_threadpool(crud.get_user_by_username, db, request.target_identifier)
+    
+    if not target:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"{request.target_user_type.value} '{request.target_identifier}' not found."
+        )
 
-@router.get("/devices/", response_model=List[models.DeviceResponse])
-def list_all_devices_admin( # Endpoint is synchronous
-    skip: int = 0,
-    limit: int = 100,
-    db: SQLAlchemySessionType = Depends(get_db)
-):
-    """
-    Admin lists all registered devices. Uses ORM.
-    """
-    devices_orm_list = crud.get_all_devices(db, skip=skip, limit=limit)
-    return devices_orm_list
+    expiry_time = datetime.utcnow() + timedelta(minutes=2)
+    await run_in_threadpool(
+        crud.create_pending_tag_link, db, request, current_user.id, expiry_time
+    )
+    return {
+        "message": "Device is ready to link tag.",
+        "device_id": device.device_id,
+        "target": request.target_identifier,
+        "expires_at": expiry_time.isoformat()
+    }
 
-@router.get("/devices/{device_pk_id}", response_model=models.DeviceResponse)
-def get_device_details_admin( # Endpoint is synchronous
-    device_pk_id: int,
-    db: SQLAlchemySessionType = Depends(get_db)
+@router.delete("/users/{username}", status_code=status.HTTP_200_OK, response_model=dict)
+async def delete_user_endpoint(
+    username: str,
+    db: Session = Depends(get_db),
+    current_admin: models.User = Depends(get_current_active_admin_user)
 ):
     """
-    Admin gets details of a specific device by its Primary Key. Uses ORM.
+    Admin: Permanently deletes a user (staff or other admin).
     """
-    # crud.get_device_by_pk is now sync ORM
-    db_device_orm = crud.get_device_by_pk(db, device_pk=device_pk_id)
-    if db_device_orm is None:
-        raise HTTPException(status_code=404, detail="Device not found")
-    return db_device_orm
+    try:
+        deleted_user = await run_in_threadpool(crud.delete_user, db, username, current_admin)
+        return {"message": "User deleted successfully", "username": deleted_user.username}
+    except HTTPException as e:
+        raise e
 
-# --- Tag Linking Preparation Endpoint (Synchronous ORM) ---
-@router.post("/prepare-device-tag-link", status_code=status.HTTP_202_ACCEPTED, response_model=Dict)
-def prepare_device_for_tag_linking_admin( # Endpoint is synchronous
-    request_payload: models.PrepareTagLinkRequest,
-    db: SQLAlchemySessionType = Depends(get_db),
-    current_admin_orm: models.User = Depends(get_current_active_admin_user_from_token)
+@router.delete("/devices/{device_id_str}", status_code=status.HTTP_200_OK, response_model=dict)
+async def delete_device_endpoint(
+    device_id_str: str,
+    db: Session = Depends(get_db)
 ):
     """
-    Admin prepares a device for tag linking. Uses synchronous ORM.
+    Admin: Permanently deletes a registered RFID device and all its logs.
     """
-    device_identifier_val = request_payload.device_identifier
-    device_orm_instance: Optional[models.Device] = None
-
-    try: 
-        device_pk = int(device_identifier_val)
-        device_orm_instance = crud.get_device_by_pk(db, device_pk)
-    except ValueError: # If not an int, assume it's the hardware string ID
-        device_orm_instance = crud.get_device_by_hardware_id(db, device_identifier_val)
-
-    if not device_orm_instance:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Device with identifier '{device_identifier_val}' not found.")
-    if not device_orm_instance.is_active: # Check if device is active
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"Device '{device_orm_instance.name or device_orm_instance.device_id}' is not active.")
-
-    device_pk_for_link = device_orm_instance.id
-    admin_user_pk = current_admin_orm.id # User's primary key
-
     try:
-        pending_link_orm = crud.create_pending_tag_link(
-            db=db,
-            device_pk=device_pk_for_link,
-            target_user_type=request_payload.target_user_type,
-            target_identifier=request_payload.target_identifier,
-            initiated_by_user_pk=admin_user_pk, # Pass admin's PK
-            expires_in_minutes=5
-        )
-        
-        device_display_name = device_orm_instance.name or device_orm_instance.device_id or f"PK:{device_pk_for_link}"
-        return {
-            "message": f"Device '{device_display_name}' is now ready to scan a tag for {request_payload.target_user_type.value} '{request_payload.target_identifier}'. Tag scan must occur within 5 minutes.",
-            "pending_link_id": pending_link_orm.id,
-            "expires_at": pending_link_orm.expires_at.isoformat()
-        }
-    except HTTPException as e: # Catch known exceptions from CRUD (e.g., 409 if device busy)
+        deleted_device = await run_in_threadpool(crud.delete_device, db, device_id_str)
+        return {"message": "Device deleted successfully", "device_id": deleted_device.device_id}
+    except HTTPException as e:
         raise e
-    except Exception as e:
-        print(f"Unexpected error in prepare_device_for_tag_linking_admin: {e}")
-        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"An unexpected error occurred: {str(e)}")
-

src/routers/clearance.py

@@ -1,100 +1,68 @@
-from fastapi import APIRouter, HTTPException, status, Depends
+"""
+Router for staff and admin clearance operations.
+"""
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
 from fastapi.concurrency import run_in_threadpool
-from sqlalchemy.orm import Session as SQLAlchemySessionType
-from typing import List, Optional # For type hinting
 
 from src import crud, models
-from src.auth import (
-    get_current_staff_or_admin_via_tag, # Returns ORM User model (Tag-based)
-    get_current_student_via_tag,        # Returns ORM Student model (Tag-based)
-    verify_department_access            # Sync utility function
-)
 from src.database import get_db
+from src.auth import get_current_active_staff_user
+from src.utils import format_student_clearance_details
 
 router = APIRouter(
     prefix="/api/clearance",
-    tags=["clearance"],
+    tags=["Clearance"],
+    dependencies=[Depends(get_current_active_staff_user)]
 )
 
-@router.post("/", response_model=models.ClearanceStatusResponse)
-async def update_clearance_status_endpoint( # Async endpoint
-    status_data: models.ClearanceStatusCreate,
-    db: SQLAlchemySessionType = Depends(get_db),
-    # current_user_orm is User ORM model (staff/admin) via Tag-based auth
-    current_user_orm: models.User = Depends(get_current_staff_or_admin_via_tag)
+class ClearanceUpdatePayload(models.BaseModel):
+    status: models.ClearanceStatusEnum
+    remarks: str | None = None
+
+@router.put("/{student_id_str}", response_model=models.ClearanceDetail)
+async def update_student_clearance(
+    student_id_str: str,
+    payload: ClearanceUpdatePayload,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_active_staff_user)
 ):
     """
-    Staff/Admin creates or updates a student's clearance status. Uses ORM.
+    Staff/Admin: Update a student's clearance status for their department.
     """
-    # crud.get_student_by_student_id is sync
-    student_orm = await run_in_threadpool(crud.get_student_by_student_id, db, status_data.student_id)
-    if not student_orm:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Student not found")
-
-    # verify_department_access is sync
-    # status_data.department is ClearanceDepartment enum from Pydantic
-    if not verify_department_access(current_user_orm.role, current_user_orm.department, status_data.department):
-        raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail=f"User '{current_user_orm.username}' does not have permission to update clearance for the {status_data.department.value} department."
-        )
-    
-    cleared_by_user_pk = current_user_orm.id # User's primary key
-
-    try:
-        # crud.create_or_update_clearance_status is sync, returns ORM model
-        updated_status_orm = await run_in_threadpool(
-            crud.create_or_update_clearance_status, db, status_data, cleared_by_user_pk
-        )
-    except HTTPException as e: # Catch known errors from CRUD
-        raise e
-    return updated_status_orm # Pydantic converts from ORM model
-
-
-# Helper for student's own clearance view (similar to one in students.py/devices.py)
-async def _format_my_clearance_response(
-    db: SQLAlchemySessionType,
-    student_orm: models.Student # Expect Student ORM model
-) -> models.ClearanceDetail:
-    
-    statuses_orm_list = await run_in_threadpool(crud.get_clearance_statuses_by_student_id, db, student_orm.student_id)
-    
-    clearance_items_models: List[models.ClearanceStatusItem] = []
-    overall_status_val = models.OverallClearanceStatusEnum.COMPLETED
+    if not current_user.department:
+        raise HTTPException(status_code=403, detail="Your user account is not assigned to a clearable department.")
 
-    if not statuses_orm_list:
-        overall_status_val = models.OverallClearanceStatusEnum.PENDING
-    
-    for status_orm in statuses_orm_list:
-        item = models.ClearanceStatusItem(
-            department=status_orm.department,
-            status=status_orm.status,
-            remarks=status_orm.remarks,
-            updated_at=status_orm.updated_at
-        )
-        clearance_items_models.append(item)
-        if item.status != models.ClearanceStatusEnum.COMPLETED:
-            overall_status_val = models.OverallClearanceStatusEnum.PENDING
-            
-    if not statuses_orm_list and overall_status_val == models.OverallClearanceStatusEnum.COMPLETED:
-         overall_status_val = models.OverallClearanceStatusEnum.PENDING
-
-    return models.ClearanceDetail(
-        student_id=student_orm.student_id,
-        name=student_orm.name,
-        department=student_orm.department,
-        clearance_items=clearance_items_models,
-        overall_status=overall_status_val
+    await run_in_threadpool(
+        crud.update_clearance_status, db, student_id_str, current_user.department, payload.status, payload.remarks, current_user.id
     )
+    
+    student_orm = await run_in_threadpool(crud.get_student_by_student_id, db, student_id_str)
+    return await format_student_clearance_details(db, student_orm)
 
-@router.get("/me", response_model=models.ClearanceDetail)
-async def get_my_clearance_status( # Async endpoint
-    # current_student_orm is Student ORM model via Tag-based auth
-    current_student_orm: models.Student = Depends(get_current_student_via_tag),
-    db: SQLAlchemySessionType = Depends(get_db)
+@router.delete("/{student_id_str}/{department_str}", response_model=models.ClearanceDetail)
+async def reset_student_clearance(
+    student_id_str: str,
+    department_str: str,
+    db: Session = Depends(get_db),
+    current_user: models.User = Depends(get_current_active_staff_user)
 ):
     """
-    Student retrieves their own complete clearance status via RFID Tag. Uses ORM.
+    Staff/Admin: Reset a student's clearance status for a department.
+    Admins can reset for any department; staff only for their own.
     """
-    return await _format_my_clearance_response(db, current_student_orm)
+    try:
+        target_department = models.ClearanceDepartment(department_str.upper())
+    except ValueError:
+        raise HTTPException(status_code=400, detail=f"'{department_str}' is not a valid department.")
+
+    if current_user.role != models.UserRole.ADMIN and current_user.department != target_department:
+        raise HTTPException(status_code=403, detail=f"You can only reset clearance for your own department.")
 
+    await run_in_threadpool(crud.delete_clearance_status, db, student_id_str, target_department)
+    
+    student_orm = await run_in_threadpool(crud.get_student_by_student_id, db, student_id_str)
+    if not student_orm:
+         raise HTTPException(status_code=404, detail="Student not found.")
+         
+    return await format_student_clearance_details(db, student_orm)

src/routers/devices.py

@@ -1,211 +1,73 @@
-from fastapi import APIRouter, HTTPException, Depends, status, Header
+"""
+Router for device interactions, specifically for submitting a scanned tag.
+This endpoint is intended to be called by the physical RFID reader device.
+"""
+from fastapi import APIRouter, Depends, HTTPException, status, Header
 from fastapi.concurrency import run_in_threadpool
-from sqlalchemy.orm import Session as SQLAlchemySessionType
-from typing import Dict, Any, List, Optional # Added List for _format_clearance_for_scan_response
+from sqlalchemy.orm import Session
+from typing import Union
 
 from src import crud, models
 from src.database import get_db
-from src.auth import get_verified_device # Returns ORM Device model
+from src.utils import format_student_clearance_details
 
-router = APIRouter(
-    prefix="/api", # Keep common prefix or change to /api/devices if preferred
-    tags=["devices"],
-)
-
-@router.post("/devices/register", response_model=models.DeviceResponse)
-async def register_device_endpoint( # Async endpoint
-    device_data: models.DeviceRegister, # Pydantic model from ESP32
-    db: SQLAlchemySessionType = Depends(get_db)
-):
-    """
-    ESP32 devices self-register or re-register. Uses ORM.
-    """
-    # crud.register_device_esp is sync, call with run_in_threadpool
-    try:
-        registered_device_orm = await run_in_threadpool(crud.register_device_esp, db, device_data)
-    except HTTPException as e: # Catch HTTPExceptions raised by CRUD (e.g., device already exists)
-        raise e
-    return registered_device_orm # Pydantic DeviceResponse converts from ORM model
-
-
-# Helper for formatting scan response (moved to be more specific to this router's needs)
-async def _format_clearance_for_device_scan(
-    db: SQLAlchemySessionType, # Pass db session for sync crud calls
-    student_orm: models.Student # Expect Student ORM model
-) -> models.ClearanceDetail:
-    """Helper to format clearance details for the /scan endpoint response using ORM."""
-    
-    # crud.get_clearance_statuses_by_student_id is sync, needs run_in_threadpool
-    statuses_orm_list = await run_in_threadpool(crud.get_clearance_statuses_by_student_id, db, student_orm.student_id)
-    
-    clearance_items_models: List[models.ClearanceStatusItem] = []
-    overall_status_val = models.OverallClearanceStatusEnum.COMPLETED
-
-    if not statuses_orm_list:
-        overall_status_val = models.OverallClearanceStatusEnum.PENDING
-    
-    for status_orm in statuses_orm_list:
-        item = models.ClearanceStatusItem(
-            department=status_orm.department, # Already enum from ORM
-            status=status_orm.status,       # Already enum from ORM
-            remarks=status_orm.remarks,
-            updated_at=status_orm.updated_at
-        )
-        clearance_items_models.append(item)
-        if item.status != models.ClearanceStatusEnum.COMPLETED:
-            overall_status_val = models.OverallClearanceStatusEnum.PENDING
-            
-    if not statuses_orm_list and overall_status_val == models.OverallClearanceStatusEnum.COMPLETED:
-         overall_status_val = models.OverallClearanceStatusEnum.PENDING
-
-    return models.ClearanceDetail(
-        student_id=student_orm.student_id,
-        name=student_orm.name,
-        department=student_orm.department,
-        clearance_items=clearance_items_models,
-        overall_status=overall_status_val
-    )
-
-@router.post("/scan", response_model=models.ClearanceDetail)
-async def scan_tag_endpoint( # Async endpoint
-    scan_data: models.TagScan, # Contains device_id (hardware_id) and tag_id
-    verified_device_orm: models.Device = Depends(get_verified_device), # Returns ORM Device model
-    db: SQLAlchemySessionType = Depends(get_db)
-):
-    """
-    Device scans a tag. Verifies device, logs scan, gets student clearance. ORM-based.
-    """
-    if verified_device_orm.device_id != scan_data.device_id: # Compare hardware IDs
-        # This might indicate a misconfiguration or an attempt to spoof.
-        # Log this with verified_device_orm.id and scan_data.device_id
-        await run_in_threadpool(
-            crud.create_device_log, db, verified_device_orm.id, "scan_error_device_id_mismatch",
-            scanned_tag_id=scan_data.tag_id, actual_device_id_str=scan_data.device_id
-        )
+async def get_authenticated_device(x_api_key: str = Header(...), db: Session = Depends(get_db)) -> models.Device:
+    """Dependency to authenticate a device by its API key."""
+    device = await run_in_threadpool(crud.get_device_by_api_key, db, x_api_key)
+    if not device or not device.is_active:
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="Device identity mismatch. API key valid, but payload device_id differs."
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid API Key or Inactive Device",
         )
+    return device
 
-    device_pk = verified_device_orm.id
-    device_hw_id = verified_device_orm.device_id # ESP32's hardware ID (string)
-
-    # Update last seen (sync crud)
-    await run_in_threadpool(crud.update_device_last_seen, db, device_pk)
-    
-    # Check if tag belongs to a student
-    student_orm = await run_in_threadpool(crud.get_student_by_tag_id, db, scan_data.tag_id)
-
-    if student_orm:
-        await run_in_threadpool(
-            crud.create_device_log, db, device_pk, "scan_student_clearance",
-            scanned_tag_id=scan_data.tag_id, user_type=models.UserRole.STUDENT.value, actual_device_id_str=device_hw_id
-        )
-        return await _format_clearance_for_device_scan(db, student_orm)
-    else:
-        # Check if tag belongs to staff/admin (not for clearance check, but for logging)
-        user_orm = await run_in_threadpool(crud.get_user_by_tag_id, db, scan_data.tag_id)
-        user_type_log = models.UserRole.ADMIN.value if user_orm and user_orm.role == models.UserRole.ADMIN else \
-                        models.UserRole.STAFF.value if user_orm and user_orm.role == models.UserRole.STAFF else \
-                        "unknown_user_tag"
-        
-        await run_in_threadpool(
-             crud.create_device_log, db, device_pk, f"scan_failed_not_student_tag ({user_type_log})",
-             scanned_tag_id=scan_data.tag_id, user_type=user_type_log, actual_device_id_str=device_hw_id
-        )
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Tag does not belong to a registered student for clearance check.")
-
+router = APIRouter(
+    prefix="/api/devices",
+    tags=["Devices"],
+    dependencies=[Depends(get_authenticated_device)]
+)
 
-@router.post("/devices/submit-scanned-tag", response_model=Dict) # Return a success message dict
-async def submit_scanned_tag_endpoint( # Async endpoint
-    payload: models.ScannedTagSubmit, # Contains scanned_tag_id
-    verified_device_orm: models.Device = Depends(get_verified_device), # Returns ORM Device model
-    db: SQLAlchemySessionType = Depends(get_db)
+@router.post(
+    "/submit-tag",
+    response_model=Union[models.ClearanceDetail, models.UserResponse, dict],
+    summary="Endpoint for RFID devices to submit a scanned tag ID."
+)
+async def device_submit_scanned_tag(
+    scanned_tag: models.ScannedTagSubmit,
+    device: models.Device = Depends(get_authenticated_device),
+    db: Session = Depends(get_db)
 ):
     """
-    Device submits a scanned tag to complete a pending link. ORM-based.
+    Handles a tag submission from an authenticated RFID device.
+    It can either link a tag if a pending link exists or fetch user details.
     """
-    device_pk = verified_device_orm.id
-    device_hw_id = verified_device_orm.device_id # ESP32's hardware ID (string)
-
-    # crud.get_active_pending_tag_link_by_device_pk is sync
-    pending_link_orm = await run_in_threadpool(crud.get_active_pending_tag_link_by_device_pk, db, device_pk)
-
-    if not pending_link_orm:
-        await run_in_threadpool(
-            crud.create_device_log, db, device_pk, "submit_tag_failed_no_pending",
-            scanned_tag_id=payload.scanned_tag_id, actual_device_id_str=device_hw_id
-        )
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="No active tag linking process for this device.")
-
-    # Check tag uniqueness (crud.check_tag_id_globally_unique_for_target is sync and raises HTTPException)
-    try:
-        await run_in_threadpool(
-            crud.check_tag_id_globally_unique_for_target,
-            db,
-            payload.scanned_tag_id,
-            pending_link_orm.target_user_type, # Pass the TargetUserType enum
-            # PK of the target entity (student.id or user.id) is NOT known here yet.
-            # The check_tag_id_globally_unique_for_target needs to be careful if target_pk is None
-            # or fetch the target's PK if the identifier is unique (student_id/username).
-            # For now, pass None for target_pk, meaning it checks against ALL existing.
-            # This is safer. If target was already assigned this tag, it should have been caught
-            # during prepare_tag_link.
-            None 
-        )
-    except HTTPException as e_tag_conflict: # Specifically catch tag conflict from the check
-        await run_in_threadpool(crud.delete_pending_tag_link, db, pending_link_orm.id) # Cancel link
-        await run_in_threadpool(
-            crud.create_device_log, db, device_pk, "submit_tag_failed_tag_conflict",
-            scanned_tag_id=payload.scanned_tag_id, actual_device_id_str=device_hw_id
-        )
-        raise e_tag_conflict # Re-raise the 409
-
-    linked_identifier_val: Optional[str] = None
-    try:
-        if pending_link_orm.target_user_type == models.TargetUserType.STUDENT:
-            # crud.update_student_tag_id is sync
-            updated_student_orm = await run_in_threadpool(
-                crud.update_student_tag_id, db, pending_link_orm.target_identifier, payload.scanned_tag_id
-            )
-            linked_identifier_val = updated_student_orm.student_id
-        elif pending_link_orm.target_user_type == models.TargetUserType.STAFF_ADMIN:
-            # crud.update_user_tag_id is sync
-            updated_user_orm = await run_in_threadpool(
-                crud.update_user_tag_id, db, pending_link_orm.target_identifier, payload.scanned_tag_id
-            )
-            linked_identifier_val = updated_user_orm.username
+    tag_id = scanned_tag.scanned_tag_id
+    pending_link = await run_in_threadpool(crud.get_pending_link_by_device, db, device.id)
+
+    if pending_link:
+        # Registration Mode
+        target_type, target_id = pending_link.target_user_type, pending_link.target_identifier
+        try:
+            if target_type == models.TargetUserType.STUDENT:
+                await run_in_threadpool(crud.update_student_tag_id, db, target_id, tag_id)
+            else:
+                await run_in_threadpool(crud.update_user_tag_id, db, target_id, tag_id)
+        finally:
+            await run_in_threadpool(crud.delete_pending_link, db, pending_link.id)
         
-        # Delete the processed pending link (sync crud)
-        await run_in_threadpool(crud.delete_pending_tag_link, db, pending_link_orm.id)
+        await run_in_threadpool(crud.create_device_log, db, {"device_fk_id": device.id, "tag_id_scanned": tag_id, "action": f"TAG_LINK_SUCCESS: {target_type.value} {target_id}"})
+        return {"message": "Tag linked successfully", "user_id": target_id, "user_type": target_type}
+    else:
+        # Fetching Mode
+        student = await run_in_threadpool(crud.get_student_by_tag_id, db, tag_id)
+        if student:
+            await run_in_threadpool(crud.create_device_log, db, {"device_fk_id": device.id, "tag_id_scanned": tag_id, "action": f"FETCH_SUCCESS: Student {student.student_id}"})
+            return await format_student_clearance_details(db, student)
+
+        user = await run_in_threadpool(crud.get_user_by_tag_id, db, tag_id)
+        if user:
+            await run_in_threadpool(crud.create_device_log, db, {"device_fk_id": device.id, "tag_id_scanned": tag_id, "action": f"FETCH_SUCCESS: User {user.username}"})
+            return models.UserResponse.from_orm(user)
         
-        # Log success (sync crud)
-        await run_in_threadpool(crud.update_device_last_seen, db, device_pk)
-        await run_in_threadpool(
-            crud.create_device_log, db, device_pk,
-            f"tag_linked_to_{pending_link_orm.target_user_type.value}:{linked_identifier_val}",
-            scanned_tag_id=payload.scanned_tag_id, actual_device_id_str=device_hw_id
-        )
-
-        return {
-            "message": f"Tag ID '{payload.scanned_tag_id}' successfully linked to {pending_link_orm.target_user_type.value} '{linked_identifier_val}'.",
-            "device_id": device_hw_id,
-            "tag_id": payload.scanned_tag_id,
-        }
-    except HTTPException as e_update: # Catch errors from update_..._tag_id
-        # If update fails (e.g. target not found, though checked in prepare), log and raise
-        await run_in_threadpool(
-            crud.create_device_log, db, device_pk, f"submit_tag_failed_update_error: {e_update.detail}",
-            scanned_tag_id=payload.scanned_tag_id, actual_device_id_str=device_hw_id
-        )
-        # Consider if pending link should be deleted on update failure.
-        # It might be better to leave it for investigation if it wasn't a tag conflict.
-        raise e_update
-    except Exception as e_generic:
-        print(f"Unexpected error during submit_scanned_tag: {e_generic}")
-        await run_in_threadpool(
-            crud.create_device_log, db, device_pk, "submit_tag_failed_unexpected_error",
-            scanned_tag_id=payload.scanned_tag_id, actual_device_id_str=device_hw_id
-        )
-        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="An unexpected error occurred linking the tag.")
-
+        await run_in_threadpool(crud.create_device_log, db, {"device_fk_id": device.id, "tag_id_scanned": tag_id, "action": "FETCH_FAIL: Tag not found"})
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Tag ID '{tag_id}' not found.")

src/routers/rfid.py

@@ -0,0 +1,83 @@
+"""
+Router for handling all RFID interactions.
+"""
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.concurrency import run_in_threadpool
+from sqlalchemy.orm import Session
+from typing import Union
+
+from src import crud, models
+from src.database import get_db
+from src.utils import format_student_clearance_details # Using a utility for DRY code
+
+router = APIRouter(
+    prefix="/api/rfid",
+    tags=["RFID"],
+)
+
+@router.post(
+    "/scan",
+    response_model=Union[models.ClearanceDetail, models.RfidLinkSuccessResponse, models.UserResponse],
+    summary="Unified endpoint for all RFID tag scans."
+)
+async def handle_rfid_scan(
+    scan_data: models.RfidScanRequest,
+    db: Session = Depends(get_db),
+):
+    """
+    This endpoint intelligently handles an RFID tag scan.
+
+    - **Registration Mode**: If an admin has prepared the device to link a tag
+      to a user, this endpoint will perform the link and return a success message.
+    
+    - **Fetching Mode**: If the device is not in registration mode, this endpoint
+      will look up the user/student by the tag ID and return their details
+      (e.g., clearance status for a student).
+    """
+    # 1. Get the device that sent the scan
+    device = await run_in_threadpool(crud.get_device_by_id, db, scan_data.device_id)
+    if not device:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Device with ID '{scan_data.device_id}' not found."
+        )
+
+    # 2. Check if the device is in "Registration Mode"
+    if device.link_for_user_id and device.link_for_user_type:
+        user_id_to_link = device.link_for_user_id
+        user_type_to_link = device.link_for_user_type
+
+        # Link the tag based on the user type
+        if user_type_to_link == models.UserTypeEnum.STUDENT:
+            await run_in_threadpool(crud.update_student_tag_id, db, user_id_to_link, scan_data.tag_id)
+        elif user_type_to_link == models.UserTypeEnum.USER:
+            await run_in_threadpool(crud.update_user_tag_id, db, user_id_to_link, scan_data.tag_id)
+        
+        # Clear the registration mode from the device
+        await run_in_threadpool(crud.clear_device_link_for_user, db, device.device_id_str)
+        
+        return models.RfidLinkSuccessResponse(
+            user_id=user_id_to_link,
+            user_type=user_type_to_link
+        )
+        
+    # 3. If not in registration mode, it's "Fetching Mode"
+    else:
+        # First, check if the tag belongs to a student
+        student = await run_in_threadpool(crud.get_student_by_tag_id, db, scan_data.tag_id)
+        if student:
+            # If a student is found, format and return their full clearance details
+            return await format_student_clearance_details(db, student)
+
+        # If not a student, check if it belongs to other users (staff/admin)
+        user = await run_in_threadpool(crud.get_user_by_tag_id, db, scan_data.tag_id)
+        if user:
+            # For a staff/admin, just return their basic profile info
+            return models.UserResponse.from_orm(user)
+        
+        # If the tag is not found anywhere, raise an error
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Tag ID '{scan_data.tag_id}' is not associated with any user."
+        )
+

src/routers/students.py

@@ -1,109 +1,65 @@
+"""
+Router for all CRUD operations related to students.
+"""
 from fastapi import APIRouter, HTTPException, status, Depends
 from fastapi.concurrency import run_in_threadpool
 from sqlalchemy.orm import Session as SQLAlchemySessionType
-from typing import List, Dict, Any # For type hinting
+from typing import List
 
 from src import crud, models
-from src.auth import get_current_active_admin_user_from_token # Returns ORM User
+from src.auth import get_current_active_admin_user
 from src.database import get_db
+from src.utils import format_student_clearance_details
 
 router = APIRouter(
     prefix="/api/students",
-    tags=["students"],
-    # All student management routes require an active admin (token-based)
-    dependencies=[Depends(get_current_active_admin_user_from_token)]
+    tags=["Students"],
+    dependencies=[Depends(get_current_active_admin_user)]
 )
 
-# Helper function to format clearance details for student endpoints
-# This is very similar to the one in devices.py, consider consolidating to a utils.py
-async def _format_student_clearance_details_response(
-    db: SQLAlchemySessionType,
-    student_orm: models.Student
-) -> models.ClearanceDetail:
-    
-    statuses_orm_list = await run_in_threadpool(crud.get_clearance_statuses_by_student_id, db, student_orm.student_id)
-    
-    clearance_items_models: List[models.ClearanceStatusItem] = []
-    overall_status_val = models.OverallClearanceStatusEnum.COMPLETED
-
-    if not statuses_orm_list:
-        overall_status_val = models.OverallClearanceStatusEnum.PENDING
-    
-    for status_orm in statuses_orm_list:
-        item = models.ClearanceStatusItem(
-            department=status_orm.department,
-            status=status_orm.status,
-            remarks=status_orm.remarks,
-            updated_at=status_orm.updated_at
-        )
-        clearance_items_models.append(item)
-        if item.status != models.ClearanceStatusEnum.COMPLETED:
-            overall_status_val = models.OverallClearanceStatusEnum.PENDING
-            
-    if not statuses_orm_list and overall_status_val == models.OverallClearanceStatusEnum.COMPLETED:
-         overall_status_val = models.OverallClearanceStatusEnum.PENDING
-
-    return models.ClearanceDetail(
-        student_id=student_orm.student_id,
-        name=student_orm.name,
-        department=student_orm.department,
-        clearance_items=clearance_items_models,
-        overall_status=overall_status_val
-    )
-
 @router.post("/", response_model=models.StudentResponse, status_code=status.HTTP_201_CREATED)
-async def create_student_endpoint( # Async endpoint
+async def create_student_endpoint(
     student_data: models.StudentCreate,
     db: SQLAlchemySessionType = Depends(get_db),
-    # current_admin_orm: models.User = Depends(get_current_active_admin_user_from_token) # For logging
 ):
-    """Admin creates a new student. Uses ORM."""
+    """Admin: Create a new student."""
     try:
-        # crud.create_student is sync, handles checks and returns ORM model
         created_student_orm = await run_in_threadpool(crud.create_student, db, student_data)
-    except HTTPException as e: # Catch known exceptions from CRUD (e.g., student_id exists)
+        return created_student_orm
+    except HTTPException as e:
         raise e
-    return created_student_orm # Pydantic converts from ORM model
 
 @router.get("/", response_model=List[models.StudentResponse])
-async def get_students_endpoint( # Async endpoint
+async def get_students_endpoint(
     skip: int = 0,
     limit: int = 100,
     db: SQLAlchemySessionType = Depends(get_db),
-    # current_admin_orm: models.User = Depends(get_current_active_admin_user_from_token)
 ):
-    """Admin gets all students. Uses ORM."""
-    # crud.get_all_students is sync
+    """Admin: Get a list of all students."""
     students_orm_list = await run_in_threadpool(crud.get_all_students, db, skip, limit)
-    return students_orm_list # Pydantic converts list of ORM models
+    return students_orm_list
 
 @router.get("/{student_id_str}", response_model=models.ClearanceDetail)
-async def get_student_clearance_endpoint( # Async endpoint
+async def get_student_clearance_endpoint(
     student_id_str: str,
     db: SQLAlchemySessionType = Depends(get_db),
-    # current_admin_orm: models.User = Depends(get_current_active_admin_user_from_token)
 ):
-    """Admin gets clearance details for a specific student. Uses ORM."""
-    # crud.get_student_by_student_id is sync
+    """Admin: Get detailed clearance status for a specific student."""
     student_orm = await run_in_threadpool(crud.get_student_by_student_id, db, student_id_str)
     if not student_orm:
         raise HTTPException(status_code=404, detail="Student not found")
-    return await _format_student_clearance_details_response(db, student_orm)
+    return await format_student_clearance_details(db, student_orm)
 
-@router.put("/{student_id_str}/link-tag", response_model=models.StudentResponse)
-async def link_student_tag_endpoint( # Async endpoint
+@router.delete("/{student_id_str}", status_code=status.HTTP_200_OK, response_model=dict)
+async def delete_student_endpoint(
     student_id_str: str,
-    tag_link_request: models.TagLinkRequest,
     db: SQLAlchemySessionType = Depends(get_db),
-    # current_admin_orm: models.User = Depends(get_current_active_admin_user_from_token)
 ):
-    """Admin links or updates RFID tag for a student. Uses ORM."""
+    """
+    Admin: Permanently deletes a student and all associated records.
+    """
     try:
-        # crud.update_student_tag_id is sync, handles checks
-        updated_student_orm = await run_in_threadpool(crud.update_student_tag_id, db, student_id_str, tag_link_request.tag_id)
-    except HTTPException as e: # Catch known errors from CRUD
+        deleted_student = await run_in_threadpool(crud.delete_student, db, student_id_str)
+        return {"message": "Student deleted successfully", "student_id": deleted_student.student_id}
+    except HTTPException as e:
         raise e
-    except Exception as e_generic:
-        print(f"Unexpected error in link_student_tag_endpoint: {e_generic}")
-        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="An unexpected error occurred.")
-    return updated_student_orm

src/routers/token.py

@@ -1,62 +1,44 @@
+"""
+Router for handling user authentication and issuing JWT tokens.
+"""
 from fastapi import APIRouter, Depends, HTTPException, status
 from fastapi.security import OAuth2PasswordRequestForm
-from fastapi.concurrency import run_in_threadpool # To call sync CRUD in async endpoint
-from sqlalchemy.orm import Session as SQLAlchemySessionType
+from sqlalchemy.orm import Session
+from datetime import timedelta
 
-from src import crud, models # crud now contains sync ORM functions
-from src.auth import create_access_token, get_current_active_user  # JWT creation is sync
-from src.database import get_db # Dependency for SQLAlchemy session
+from src import models
+from src.database import get_db
+from src.auth import authenticate_user, create_access_token
+from src.config import settings
 
 router = APIRouter(
-    prefix="/api/token",
-    tags=["authentication"],
+    prefix="/api",
+    tags=["Authentication"]
 )
 
-@router.post("/login", response_model=models.Token)
-async def login_for_access_token( # Endpoint remains async
+@router.post("/token", response_model=models.Token)
+async def login_for_access_token(
     form_data: OAuth2PasswordRequestForm = Depends(),
-    db: SQLAlchemySessionType = Depends(get_db)
+    db: Session = Depends(get_db)
 ):
     """
-    Provides an access token for an authenticated staff or admin user.
-    Requires username and password. Uses ORM.
-    """
-    # crud.get_user_by_username is now sync, call with run_in_threadpool
-    user = await run_in_threadpool(crud.get_user_by_username, db, form_data.username)
+    Provides a JWT token for authenticated users.
     
+    This is the primary login endpoint. It takes a username and password
+    and returns an access token if the credentials are valid.
+    """
+    user = await authenticate_user(db, form_data.username, form_data.password)
     if not user:
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
             detail="Incorrect username or password",
             headers={"WWW-Authenticate": "Bearer"},
         )
-
-    # crud.verify_password is sync
-    is_password_valid = await run_in_threadpool(crud.verify_password, form_data.password, user.hashed_password)
-    if not is_password_valid:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Incorrect username or password",
-            headers={"WWW-Authenticate": "Bearer"},
-        )
-
-    if not user.is_active:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Inactive user")
-        
-    access_token = create_access_token( # create_access_token is sync
-        data={"sub": user.username, "role": user.role.value} # user.role is UserRole enum
+    
+    access_token_expires = timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    access_token = create_access_token(
+        data={"sub": user.username, "role": user.role.value},
+        expires_delta=access_token_expires
     )
+    
     return {"access_token": access_token, "token_type": "bearer"}
-
-
-@router.get("/users/me", response_model=models.UserResponse, summary="Get current authenticated user details")
-async def read_users_me(
-    current_user_orm: models.User = Depends(get_current_active_user) # Depends on token auth
-):
-    """
-    Returns the details of the currently authenticated user (via token).
-    The user object is already an ORM model instance.
-    Pydantic's UserResponse will convert it using from_attributes=True.
-    """
-    return current_user_orm
-

src/routers/users.py

@@ -1,74 +1,40 @@
+"""
+Router for managing users (staff, admins).
+"""
 from fastapi import APIRouter, Depends, HTTPException, status
-from fastapi.concurrency import run_in_threadpool
-from sqlalchemy.orm import Session as SQLAlchemySessionType
-from typing import List 
+from sqlalchemy.orm import Session
+from typing import List
 
 from src import crud, models
-from src.auth import get_current_active_admin_user_from_token # Returns ORM User
 from src.database import get_db
-from src.auth import get_current_active_user # Returns ORM User model
-
+from src.auth import get_current_active_user, get_current_active_admin_user
 
 router = APIRouter(
     prefix="/api/users",
-    tags=["users"],
+    tags=["Users"],
 )
 
-@router.post("/register", response_model=models.UserResponse, status_code=status.HTTP_201_CREATED)
-async def register_user( # Endpoint remains async
-    user_data: models.UserCreate,
-    db: SQLAlchemySessionType = Depends(get_db),
-   ):
+@router.post("/", response_model=models.UserResponse, status_code=status.HTTP_201_CREATED, dependencies=[Depends(get_current_active_admin_user)])
+async def create_new_user(user: models.UserCreate, db: Session = Depends(get_db)):
     """
-    Admin registers a new staff or admin user. Uses ORM.
+    Admin: Create a new user (staff or admin).
     """
-    # Role check (user_data.role is already UserRole enum from Pydantic)
-    if user_data.role not in [models.UserRole.STAFF, models.UserRole.ADMIN]:
-         raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"User role must be '{models.UserRole.STAFF.value}' or '{models.UserRole.ADMIN.value}'"
-        )
-    
-    # Check if username already exists  
     try:
-        created_user_orm = await run_in_threadpool(crud.create_user, db, user_data)
-    except HTTPException as e: # Catch HTTPExceptions raised by CRUD (e.g., username exists)
+        return await crud.create_user(db=db, user=user)
+    except HTTPException as e:
         raise e
-    
-    return created_user_orm # Pydantic UserResponse will convert from ORM model
 
-@router.put("/{username_str}/link-tag", response_model=models.UserResponse)
-async def link_user_tag_endpoint( # Endpoint remains async
-    username_str: str,
-    tag_link_request: models.TagLinkRequest,
-    db: SQLAlchemySessionType = Depends(get_db),
-    current_admin_orm: models.User = Depends(get_current_active_admin_user_from_token) # For logging, if needed
-):
+@router.get("/", response_model=List[models.UserResponse], dependencies=[Depends(get_current_active_admin_user)])
+async def read_users(skip: int = 0, limit: int = 100, db: Session = Depends(get_db)):
     """
-    Admin links or updates the RFID tag_id for a specific staff/admin user. Uses ORM.
+    Admin: Retrieve a list of all users.
     """
-    try:
-        # crud.update_user_tag_id is sync, call with run_in_threadpool
-        # It handles tag uniqueness and user existence checks.
-        updated_user_orm = await run_in_threadpool(crud.update_user_tag_id, db, username_str, tag_link_request.tag_id)
-    except HTTPException as e: # Catch HTTPExceptions from CRUD
-        raise e
-    except Exception as e:
-        # Generic error logging
-        print(f"Unexpected error in link_user_tag_endpoint: {e}")
-        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="An unexpected error occurred.")
-        
-    return updated_user_orm # Pydantic UserResponse will convert
+    users = await crud.get_all_users(db, skip=skip, limit=limit) # Assumes get_all_users exists in crud.users
+    return users
 
-@router.get("/", response_model=List[models.UserResponse])
-async def list_all_users( 
-    skip: int = 0,
-    limit: int = 100,
-    db: SQLAlchemySessionType = Depends(get_db),
-):
+@router.get("/me", response_model=models.UserResponse)
+async def read_users_me(current_user: models.User = Depends(get_current_active_user)):
     """
-    Admin lists all staff/admin users with pagination. Uses ORM.
+    Get profile information for the currently authenticated user.
     """
-    # crud.get_users is sync, call with run_in_threadpool
-    users_orm_list = await run_in_threadpool(crud.get_users, db, skip, limit)
-    return users_orm_list # Pydantic will convert the list of ORM User models
+    return current_user

src/utils.py

@@ -0,0 +1,51 @@
+from typing import List, Dict, Any
+from sqlalchemy.orm import Session as SQLAlchemySessionType
+from fastapi.concurrency import run_in_threadpool
+
+from src import crud, models
+
+async def format_student_clearance_details(
+    db: SQLAlchemySessionType,
+    student_orm: models.Student
+) -> models.ClearanceDetail:
+    """
+    Formats clearance details for a student.
+    
+    Args:
+        db (SQLAlchemySessionType): Database session.
+        student_orm (models.Student): ORM model of the student.
+    
+    Returns:
+        models.ClearanceDetail: Formatted clearance details.
+    """
+    statuses_orm_list = await run_in_threadpool(crud.get_clearance_statuses_by_student_id, db, student_orm.student_id)
+    
+    clearance_items_models: List[models.ClearanceStatusItem] = []
+    overall_status_val = models.OverallClearanceStatusEnum.COMPLETED
+
+    
+    if not statuses_orm_list:
+        overall_status_val = models.OverallClearanceStatusEnum.PENDING
+    
+    for status_orm in statuses_orm_list:
+        item = models.ClearanceStatusItem(
+            department=status_orm.department,
+            status=status_orm.status,
+            remarks=status_orm.remarks,
+            updated_at=status_orm.updated_at
+        )
+        clearance_items_models.append(item)
+        if item.status != models.ClearanceStatusEnum.COMPLETED:
+            overall_status_val = models.OverallClearanceStatusEnum.PENDING
+            
+    if not statuses_orm_list and overall_status_val == models.OverallClearanceStatusEnum.COMPLETED:
+         overall_status_val = models.OverallClearanceStatusEnum.PENDING
+
+    return models.ClearanceDetail(
+        student_id=student_orm.student_id,
+        name=student_orm.name,
+        department=student_orm.department,
+        clearance_items=clearance_items_models,
+        overall_status=overall_status_val
+    )
+