feat: add audit log table and integration with admin/tree endpoints

Creates AuditLog model with JSONB details column for tracking admin
actions. Integrates log_audit() helper into admin endpoints (role
change, team admin toggle, deactivate, activate) and tree delete.
IP address column reserved for future Railway proxy header support.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

backend/app/api/endpoints/admin.py

@@ -5,6 +5,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import select, func
 
 from app.core.database import get_db
+from app.core.audit import log_audit
 from app.models.user import User
 from app.schemas.user import UserResponse, RoleUpdate, TeamAdminUpdate
 from app.api.deps import require_admin
@@ -81,7 +82,10 @@ async def update_user_role(
             detail="Cannot change your own role"
         )
 
+    old_role = user.role
     user.role = role_data.role
+    await log_audit(db, current_user.id, "user.role_change", "user", user.id,
+                    {"old_role": old_role, "new_role": role_data.role})
     await db.commit()
     await db.refresh(user)
     return user
@@ -111,6 +115,8 @@ async def toggle_team_admin(
         )
 
     user.is_team_admin = data.is_team_admin
+    await log_audit(db, current_user.id, "user.team_admin_toggle", "user", user.id,
+                    {"is_team_admin": data.is_team_admin})
     await db.commit()
     await db.refresh(user)
     return user
@@ -139,6 +145,7 @@ async def deactivate_user(
         )
 
     user.is_active = False
+    await log_audit(db, current_user.id, "user.deactivate", "user", user.id)
     await db.commit()
     await db.refresh(user)
     return user
@@ -161,6 +168,7 @@ async def activate_user(
         )
 
     user.is_active = True
+    await log_audit(db, current_user.id, "user.activate", "user", user.id)
     await db.commit()
     await db.refresh(user)
     return user

backend/app/api/endpoints/trees.py

@@ -14,6 +14,7 @@ from app.models.folder import UserFolder
 from app.schemas.tree import TreeCreate, TreeUpdate, TreeResponse, TreeListResponse, CategoryInfo
 from app.api.deps import get_current_active_user, require_engineer_or_admin, require_admin
 from app.core.permissions import can_edit_tree, can_access_tree
+from app.core.audit import log_audit
 
 router = APIRouter(prefix="/trees", tags=["trees"])
 
@@ -518,5 +519,7 @@ async def delete_tree(
         )
 
     tree.is_active = False
+    await log_audit(db, current_user.id, "tree.delete", "tree", tree.id,
+                    {"tree_name": tree.name})
     await db.commit()
     return None

backend/app/core/audit.py

@@ -0,0 +1,24 @@
+"""Centralized audit logging for admin and destructive actions."""
+from uuid import UUID
+from typing import Optional
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.models.audit_log import AuditLog
+
+
+async def log_audit(
+    db: AsyncSession,
+    user_id: UUID,
+    action: str,
+    resource_type: str,
+    resource_id: Optional[UUID] = None,
+    details: Optional[dict] = None,
+) -> None:
+    """Record an audit log entry. Does not commit — piggybacks on the caller's commit."""
+    entry = AuditLog(
+        user_id=user_id,
+        action=action,
+        resource_type=resource_type,
+        resource_id=resource_id,
+        details=details,
+    )
+    db.add(entry)

backend/app/models/__init__.py

@@ -10,6 +10,7 @@ from .folder import UserFolder, user_folder_trees
 from .step_category import StepCategory
 from .step_library import StepLibrary, StepRating, StepUsageLog
 from .refresh_token import RefreshToken
+from .audit_log import AuditLog
 
 __all__ = [
     "User",
@@ -28,4 +29,5 @@ __all__ = [
     "StepRating",
     "StepUsageLog",
     "RefreshToken",
+    "AuditLog",
 ]

backend/app/models/audit_log.py

@@ -0,0 +1,35 @@
+import uuid
+from datetime import datetime, timezone
+from typing import Optional
+from sqlalchemy import String, DateTime, ForeignKey
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+from app.core.database import Base
+
+
+class AuditLog(Base):
+    __tablename__ = "audit_logs"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        default=uuid.uuid4
+    )
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id"),
+        nullable=False,
+        index=True
+    )
+    action: Mapped[str] = mapped_column(String(50), nullable=False, index=True)
+    resource_type: Mapped[str] = mapped_column(String(50), nullable=False, index=True)
+    resource_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        nullable=True
+    )
+    details: Mapped[Optional[dict]] = mapped_column(JSONB, nullable=True)
+    ip_address: Mapped[Optional[str]] = mapped_column(String(45), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc)
+    )