refactor: add docstrings to test fixtures and perform comprehensive codebase-wide hardening and schema updates

Author: codewithme-py

None

@@ -19,18 +19,71 @@
 
 
 class AdminAccessMixin(ModelView):
+    """
+    Mixin that restricts access to admin model views to ADMIN users only.
+
+    Provides ``is_accessible`` and ``is_visible`` checks that ensure only
+    users with the ``ADMIN`` role can view and interact with the model
+    in the SQLAdmin panel.
+    """
+
     def is_accessible(self, request: Request) -> bool:
+        """
+        Check whether the current user has ADMIN role for access control.
+
+        Args:
+            request: The incoming HTTP request with user information attached
+                to ``request.state``.
+
+        Returns:
+            ``True`` if the authenticated user has the ``ADMIN`` role;
+            ``False`` otherwise.
+        """
         user = getattr(request.state, 'user', None)
         return user is not None and user.role == UserRole.ADMIN
 
     def is_visible(self, request: Request) -> bool:
+        """
+        Check whether the current user has ADMIN role for menu visibility.
+
+        Args:
+            request: The incoming HTTP request with user information attached
+                to ``request.state``.
+
+        Returns:
+            ``True`` if the authenticated user has the ``ADMIN`` role;
+            ``False`` otherwise.
+        """
         user = getattr(request.state, 'user', None)
         return user is not None and user.role == UserRole.ADMIN
 
 
 class AdminPanelFormatter:
+    """
+    Utility class providing formatter methods for displaying data in the admin panel.
+
+    Each static method produces HTML markup (via ``Markup``) suitable for
+    use as a SQLAdmin column formatter, rendering badges, links, and
+    styled status indicators.
+    """
+
     @staticmethod
     def status_formatter(model: Any, name: Any) -> Any:
+        """
+        Render a status field value as a colored Bootstrap badge.
+
+        Maps common status and role values to appropriate Bootstrap badge
+        colors (e.g., ``ACTIVE`` to green, ``CANCELLED`` to red).
+
+        Args:
+            model: The SQLAlchemy model instance being formatted.
+            name: The attribute name to read from the model (e.g., ``status``,
+                ``role``, ``target_role``).
+
+        Returns:
+            A ``Markup`` string containing the HTML badge, or the raw
+            attribute value if the name is not a recognized status field.
+        """
         status_colors = {
             'ACTIVE': 'success',
             'PENDING': 'warning',
@@ -56,27 +109,76 @@ def status_formatter(model: Any, name: Any) -> Any:
 
     @staticmethod
     def user_link_formatter(model: Any, name: Any) -> Any:
+        """
+        Render a user ID as a clickable link to the user detail page.
+
+        Args:
+            model: The SQLAlchemy model instance being formatted.
+            name: The attribute name holding the user ID.
+
+        Returns:
+            A ``Markup`` anchor tag linking to ``/admin/user/details/<id>``,
+            or ``'N/A'`` if the user ID is empty.
+        """
         user_id = getattr(model, name)
         if not user_id:
             return 'N/A'
         return Markup(f'<a href="/admin/user/details/{user_id}">{user_id}</a>')
 
     @staticmethod
     def product_link_formatter(model: Any, name: Any) -> Any:
+        """
+        Render a product ID as a clickable link to the product detail page.
+
+        Args:
+            model: The SQLAlchemy model instance being formatted.
+            name: The attribute name holding the product ID.
+
+        Returns:
+            A ``Markup`` anchor tag linking to ``/admin/product/details/<id>``,
+            or ``'N/A'`` if the product ID is empty.
+        """
         product_id = getattr(model, name)
         if not product_id:
             return 'N/A'
         return Markup(f'<a href="/admin/product/details/{product_id}">{product_id}</a>')
 
     @staticmethod
     def order_link_formatter(model: Any, name: Any) -> Any:
+        """
+        Render an order ID as a clickable link to the order detail page.
+
+        Args:
+            model: The SQLAlchemy model instance being formatted.
+            name: The attribute name holding the order ID.
+
+        Returns:
+            A ``Markup`` anchor tag linking to ``/admin/order/details/<id>``,
+            or ``'N/A'`` if the order ID is empty.
+        """
         order_id = getattr(model, name)
         if not order_id:
             return 'N/A'
         return Markup(f'<a href="/admin/order/details/{order_id}">{order_id}</a>')
 
     @staticmethod
     def docs_link_formatter(model: Any, name: Any) -> Any:
+        """
+        Render verification document keys as clickable links for viewing.
+
+        Generates a comma-separated list of anchor tags, each linking to
+        a verification document endpoint keyed by document type.
+
+        Args:
+            model: The SQLAlchemy model instance being formatted (must have
+                an ``id`` attribute).
+            name: The attribute name holding the document data as a dict
+                mapping document types to URLs or values.
+
+        Returns:
+            A ``Markup`` string of comma-separated links, or ``'No docs'``
+            if the document data is empty.
+        """
         docs = getattr(model, name)
         if not docs:
             return 'No docs'
@@ -91,6 +193,14 @@ def docs_link_formatter(model: Any, name: Any) -> Any:
 
 
 class VerificationRequestAdmin(AdminAccessMixin, model=VerificationRequest):
+    """
+    Admin panel view for managing user verification requests.
+
+    Allows admins with ``ADMIN`` role to view, approve, or reject user
+    verification requests. Approving a request automatically upgrades
+    the user's role to the requested target role.
+    """
+
     column_list = [
         VerificationRequest.id,
         VerificationRequest.user_id,
@@ -121,6 +231,20 @@ class VerificationRequestAdmin(AdminAccessMixin, model=VerificationRequest):
     async def on_model_change(
         self, data: dict, model: Any, is_created: bool, request: Request
     ) -> None:
+        """
+        Handle post-save logic for verification request updates.
+
+        When a verification request status is changed to ``APPROVED``, this
+        hook automatically updates the associated user's role to the
+        requested target role and marks the user as verified.
+
+        Args:
+            data: Dictionary of form field values being saved.
+            model: The ``VerificationRequest`` model instance being updated.
+            is_created: ``True`` if this is a new record creation; ``False``
+                for updates.
+            request: The incoming HTTP request.
+        """
         if not is_created and data.get('status') == VerificationStatus.APPROVED:
             async with async_session_factory() as session:
                 result = await session.execute(
@@ -133,6 +257,13 @@ async def on_model_change(
 
 
 class UserAdmin(ModelView, model=User):
+    """
+    Admin panel view for managing user accounts.
+
+    Supports both ``ADMIN`` and ``MODERATOR`` roles. Moderators can view
+    users but cannot create, edit, or delete records.
+    """
+
     column_list = [User.id, User.email, User.role, User.is_active]
     column_searchable_list = [User.id, User.email]
     can_delete = False
@@ -142,6 +273,20 @@ class UserAdmin(ModelView, model=User):
     column_default_sort = [('created_at', True)]
 
     def is_accessible(self, request: Request) -> bool:
+        """
+        Check whether the requesting user can access this admin view.
+
+        Allows both ``ADMIN`` and ``MODERATOR`` roles. Moderators are
+        restricted from create, edit, and delete operations.
+
+        Args:
+            request: The incoming HTTP request with user information and
+                route details.
+
+        Returns:
+            ``True`` if the user has an allowed role and the requested
+                operation is permitted; ``False`` otherwise.
+        """
         user = getattr(request.state, 'user', None)
         if not user:
             return False
@@ -163,6 +308,14 @@ def is_accessible(self, request: Request) -> bool:
 
 
 class ProductAdmin(ModelView, model=Product):
+    """
+    Admin panel view for managing product listings.
+
+    Allows admins to view product details, update moderation status,
+    assign moderators, and add moderation comments. Creation and
+    deletion are disabled.
+    """
+
     column_list = [
         Product.id,
         Product.name,
@@ -199,6 +352,13 @@ class ProductAdmin(ModelView, model=Product):
 
 
 class OrderAdmin(ModelView, model=Order):
+    """
+    Admin panel view for viewing customer orders.
+
+    Provides read-only access to order records with formatted status
+    badges and user links. Creation, editing, and deletion are disabled.
+    """
+
     column_list = [
         Order.id,
         Order.user_id,
@@ -220,6 +380,13 @@ class OrderAdmin(ModelView, model=Order):
 
 
 class ReservationAdmin(ModelView, model=Reservation):
+    """
+    Admin panel view for viewing product reservations.
+
+    Displays reservation details including product, user, quantity, and
+    expiration time. All mutations (create, edit, delete) are disabled.
+    """
+
     column_list = [
         Reservation.id,
         Reservation.product_id,
@@ -246,6 +413,13 @@ class ReservationAdmin(ModelView, model=Reservation):
 
 
 class AuditLogAdmin(AdminAccessMixin, model=AuditLog):
+    """
+    Admin panel view for viewing audit log entries.
+
+    Provides read-only access to the audit trail, showing all recorded
+    actions, target objects, and actors. Restricted to ``ADMIN`` role.
+    """
+
     column_list = [
         AuditLog.id,
         AuditLog.target_type,
@@ -269,6 +443,13 @@ class AuditLogAdmin(AdminAccessMixin, model=AuditLog):
 
 
 class APIKeyB2BPartnerAdmin(AdminAccessMixin, model=APIKeyB2BPartner):
+    """
+    Admin panel view for managing B2B partner API keys.
+
+    Displays API key records with user associations, key names, and
+    prefixes. Restricted to ``ADMIN`` role. Deletion is disabled.
+    """
+
     column_list = [
         APIKeyB2BPartner.id,
         APIKeyB2BPartner.user_id,
@@ -289,6 +470,16 @@ class APIKeyB2BPartnerAdmin(AdminAccessMixin, model=APIKeyB2BPartner):
 
 
 def register_admin_views(admin: Any) -> None:
+    """
+    Register all admin model views with the SQLAdmin instance.
+
+    Adds each admin view class (users, products, orders, reservations,
+    audit logs, API keys, and verification requests) to the provided
+    admin object.
+
+    Args:
+        admin: The SQLAdmin ``Admin`` instance to register views with.
+    """
     admin.add_view(UserAdmin)
     admin.add_view(ProductAdmin)
     admin.add_view(OrderAdmin)

app/core/admin/admin.py

@@ -11,7 +11,30 @@
 
 
 class AdminAuth(AuthenticationBackend):
+    """
+    Authentication backend for the SQLAdmin panel using session-based login.
+
+    Handles login, logout, and authentication for admin panel users. Only
+    users with the ADMIN or MODERATOR role are granted access.
+    """
+
     async def login(self, request: Request) -> bool:
+        """
+        Authenticate an admin user via email and password from a form.
+
+        Extracts the username (email) and password fields from the
+        submitted form, validates the credentials, and checks that the user
+        has an admin or moderator role. On success, stores the user ID in
+        the session.
+
+        Args:
+            request: The incoming Starlette request containing form data with
+                username and password fields.
+
+        Returns:
+            True if authentication succeeds and the user has the
+            required role; False otherwise.
+        """
         user_data = await request.form()
         email = user_data.get('username')
         password = user_data.get('password')
@@ -32,10 +55,34 @@ async def login(self, request: Request) -> bool:
                 return False
 
     async def logout(self, request: Request) -> bool:
+        """
+        Log out the current admin user by clearing the session.
+
+        Args:
+            request: The incoming Starlette request with an active session.
+
+        Returns:
+            Always returns True after clearing the session.
+        """
         request.session.clear()
         return True
 
     async def authenticate(self, request: Request) -> bool:
+        """
+        Verify that the current session holds a valid admin or moderator user.
+
+        Looks up the user ID stored in the session under the token key
+        and checks that the corresponding user exists and has either the
+        ADMIN or MODERATOR role. The authenticated user is attached
+        to request.state for downstream use.
+
+        Args:
+            request: The incoming Starlette request with a session.
+
+        Returns:
+            True if a valid admin/moderator user is authenticated;
+            False if the session is empty or the user is invalid.
+        """
         token = request.session.get('token')
         if not token:
             return False