feat: implement user administration with role-based access and audit logging

- Add UserRole enum (comercial, juridico, financeiro, rh, pj, super_admin)
- Add AuditLog model for tracking user management actions
- Update CRUD operations for role-based user creation/update
- Add get_current_user_manager dependency for role-based access control
- Update API routes: create, update, delete users with audit logging
- Only Super Admin can delete another Super Admin
- Password optional on user creation (passwordless flow)
- Add Alembic migration for role column and auditlog table
- Update frontend: role select dropdown in AddUser/EditUser forms
- Update frontend: show role labels in user table columns
- Update frontend: role-based sidebar and admin page access

Co-Authored-By: daniel.resgate <daniel.rider69@gmail.com>

Author: devin-ai-integration[bot]

backend/app/alembic/versions/c3d4e5f6g7h8_add_user_role_and_audit_log.py

@@ -0,0 +1,62 @@
+"""Add user role column and audit_log table
+
+Revision ID: c3d4e5f6g7h8
+Revises: b2c3d4e5f6g7
+Create Date: 2026-03-27 15:00:00.000000
+
+"""
+import sqlalchemy as sa
+import sqlmodel.sql.sqltypes
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "c3d4e5f6g7h8"
+down_revision = "b2c3d4e5f6g7"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # Add role column to user table with default 'comercial'
+    op.add_column(
+        "user",
+        sa.Column(
+            "role",
+            sqlmodel.sql.sqltypes.AutoString(),
+            nullable=False,
+            server_default="comercial",
+        ),
+    )
+
+    # Migrate existing superusers to super_admin role
+    op.execute(
+        "UPDATE \"user\" SET role = 'super_admin' WHERE is_superuser = true"
+    )
+
+    # Create auditlog table
+    op.create_table(
+        "auditlog",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column(
+            "action",
+            sqlmodel.sql.sqltypes.AutoString(),
+            nullable=False,
+        ),
+        sa.Column("target_user_id", sa.Uuid(), nullable=False),
+        sa.Column("performed_by_id", sa.Uuid(), nullable=False),
+        sa.Column(
+            "changes",
+            sqlmodel.sql.sqltypes.AutoString(length=2000),
+            nullable=False,
+            server_default="",
+        ),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=True),
+        sa.ForeignKeyConstraint(["target_user_id"], ["user.id"]),
+        sa.ForeignKeyConstraint(["performed_by_id"], ["user.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+
+def downgrade():
+    op.drop_table("auditlog")
+    op.drop_column("user", "role")

backend/app/api/deps.py

@@ -11,7 +11,7 @@
 from app.core import security
 from app.core.config import settings
 from app.core.db import engine
-from app.models import TokenPayload, User
+from app.models import USER_MANAGER_ROLES, TokenPayload, User
 
 reusable_oauth2 = OAuth2PasswordBearer(
     tokenUrl=f"{settings.API_V1_STR}/login/access-token"
@@ -55,3 +55,12 @@ def get_current_active_superuser(current_user: CurrentUser) -> User:
             status_code=403, detail="The user doesn't have enough privileges"
         )
     return current_user
+
+
+def get_current_user_manager(current_user: CurrentUser) -> User:
+    if current_user.role not in USER_MANAGER_ROLES:
+        raise HTTPException(
+            status_code=403,
+            detail="The user doesn't have enough privileges to manage users",
+        )
+    return current_user

backend/app/api/routes/users.py

@@ -8,18 +8,21 @@
 from app.api.deps import (
     CurrentUser,
     SessionDep,
-    get_current_active_superuser,
+    get_current_user_manager,
 )
 from app.core.config import settings
 from app.core.security import get_password_hash, verify_password
 from app.models import (
+    AuditAction,
+    AuditLogsPublic,
     Item,
     Message,
     UpdatePassword,
     User,
     UserCreate,
     UserPublic,
     UserRegister,
+    UserRole,
     UsersPublic,
     UserUpdate,
     UserUpdateMe,
@@ -31,7 +34,7 @@
 
 @router.get(
     "/",
-    dependencies=[Depends(get_current_active_superuser)],
+    dependencies=[Depends(get_current_user_manager)],
     response_model=UsersPublic,
 )
 def read_users(session: SessionDep, skip: int = 0, limit: int = 100) -> Any:
@@ -51,11 +54,16 @@ def read_users(session: SessionDep, skip: int = 0, limit: int = 100) -> Any:
 
 
 @router.post(
-    "/", dependencies=[Depends(get_current_active_superuser)], response_model=UserPublic
+    "/",
+    dependencies=[Depends(get_current_user_manager)],
+    response_model=UserPublic,
 )
-def create_user(*, session: SessionDep, user_in: UserCreate) -> Any:
+def create_user(
+    *, session: SessionDep, user_in: UserCreate, current_user: CurrentUser
+) -> Any:
     """
-    Create new user.
+    Create new user. Requires email and role at minimum.
+    Password is optional (generated automatically for passwordless flow).
     """
     user = crud.get_user_by_email(session=session, email=user_in.email)
     if user:
@@ -67,13 +75,23 @@ def create_user(*, session: SessionDep, user_in: UserCreate) -> Any:
     user = crud.create_user(session=session, user_create=user_in)
     if settings.emails_enabled and user_in.email:
         email_data = generate_new_account_email(
-            email_to=user_in.email, username=user_in.email, password=user_in.password
+            email_to=user_in.email,
+            username=user_in.email,
+            password=user_in.password or "",
         )
         send_email(
             email_to=user_in.email,
             subject=email_data.subject,
             html_content=email_data.html_content,
         )
+
+    crud.create_audit_log(
+        session=session,
+        action=AuditAction.created,
+        target_user_id=user.id,
+        performed_by_id=current_user.id,
+        changes=f"User created with role={user_in.role.value}",
+    )
     return user
 
 
@@ -158,6 +176,19 @@ def register_user(session: SessionDep, user_in: UserRegister) -> Any:
     return user
 
 
+@router.get(
+    "/audit-log",
+    dependencies=[Depends(get_current_user_manager)],
+    response_model=AuditLogsPublic,
+)
+def read_audit_logs(session: SessionDep, skip: int = 0, limit: int = 100) -> Any:
+    """
+    Retrieve user audit logs.
+    """
+    logs, count = crud.get_audit_logs(session=session, skip=skip, limit=limit)
+    return AuditLogsPublic(data=logs, count=count)
+
+
 @router.get("/{user_id}", response_model=UserPublic)
 def read_user_by_id(
     user_id: uuid.UUID, session: SessionDep, current_user: CurrentUser
@@ -180,17 +211,18 @@ def read_user_by_id(
 
 @router.patch(
     "/{user_id}",
-    dependencies=[Depends(get_current_active_superuser)],
+    dependencies=[Depends(get_current_user_manager)],
     response_model=UserPublic,
 )
 def update_user(
     *,
     session: SessionDep,
     user_id: uuid.UUID,
     user_in: UserUpdate,
+    current_user: CurrentUser,
 ) -> Any:
     """
-    Update a user.
+    Update a user (role, active status, etc.).
     """
 
     db_user = session.get(User, user_id)
@@ -206,16 +238,49 @@ def update_user(
                 status_code=409, detail="User with this email already exists"
             )
 
+    changes_parts = []
+    user_data = user_in.model_dump(exclude_unset=True)
+    if "role" in user_data and user_data["role"] is not None:
+        changes_parts.append(f"role: {db_user.role.value} -> {user_data['role']}")
+    if "is_active" in user_data and user_data["is_active"] is not None:
+        changes_parts.append(
+            f"is_active: {db_user.is_active} -> {user_data['is_active']}"
+        )
+    if "email" in user_data and user_data["email"] is not None:
+        changes_parts.append(f"email: {db_user.email} -> {user_data['email']}")
+    if "full_name" in user_data:
+        changes_parts.append(
+            f"full_name: {db_user.full_name} -> {user_data['full_name']}"
+        )
+
+    is_deactivation = (
+        "is_active" in user_data
+        and user_data["is_active"] is False
+        and db_user.is_active is True
+    )
+
     db_user = crud.update_user(session=session, db_user=db_user, user_in=user_in)
+
+    audit_action = AuditAction.deactivated if is_deactivation else AuditAction.updated
+    crud.create_audit_log(
+        session=session,
+        action=audit_action,
+        target_user_id=db_user.id,
+        performed_by_id=current_user.id,
+        changes="; ".join(changes_parts) if changes_parts else "No changes",
+    )
     return db_user
 
 
-@router.delete("/{user_id}", dependencies=[Depends(get_current_active_superuser)])
+@router.delete(
+    "/{user_id}",
+    dependencies=[Depends(get_current_user_manager)],
+)
 def delete_user(
     session: SessionDep, current_user: CurrentUser, user_id: uuid.UUID
 ) -> Message:
     """
-    Delete a user.
+    Delete a user. Only a Super Admin can delete another Super Admin.
     """
     user = session.get(User, user_id)
     if not user:
@@ -224,6 +289,11 @@ def delete_user(
         raise HTTPException(
             status_code=403, detail="Super users are not allowed to delete themselves"
         )
+    if user.role == UserRole.super_admin and current_user.role != UserRole.super_admin:
+        raise HTTPException(
+            status_code=403,
+            detail="Only a Super Admin can delete another Super Admin",
+        )
     statement = delete(Item).where(col(Item.owner_id) == user_id)
     session.exec(statement)
     session.delete(user)

backend/app/core/db.py

@@ -2,7 +2,7 @@
 
 from app import crud
 from app.core.config import settings
-from app.models import User, UserCreate
+from app.models import User, UserCreate, UserRole
 
 engine = create_engine(str(settings.SQLALCHEMY_DATABASE_URI))
 
@@ -28,6 +28,6 @@ def init_db(session: Session) -> None:
         user_in = UserCreate(
             email=settings.FIRST_SUPERUSER,
             password=settings.FIRST_SUPERUSER_PASSWORD,
-            is_superuser=True,
+            role=UserRole.super_admin,
         )
         user = crud.create_user(session=session, user_create=user_in)

backend/app/crud.py

@@ -1,10 +1,14 @@
+import secrets
 import uuid
 from typing import Any
 
-from sqlmodel import Session, select
+from sqlmodel import Session, col, func, select
 
 from app.core.security import get_password_hash, verify_password
 from app.models import (
+    AuditAction,
+    AuditLog,
+    AuditLogPublic,
     Company,
     CompanyCreate,
     CompanyInvite,
@@ -14,13 +18,25 @@
     ItemCreate,
     User,
     UserCreate,
+    UserRole,
     UserUpdate,
 )
 
 
 def create_user(*, session: Session, user_create: UserCreate) -> User:
+    password = user_create.password or secrets.token_urlsafe(32)
+    is_superuser = (
+        user_create.role == UserRole.super_admin
+        if hasattr(user_create, "role")
+        else False
+    )
     db_obj = User.model_validate(
-        user_create, update={"hashed_password": get_password_hash(user_create.password)}
+        user_create,
+        update={
+            "hashed_password": get_password_hash(password),
+            "is_superuser": is_superuser,
+            "is_active": True,
+        },
     )
     session.add(db_obj)
     session.commit()
@@ -35,6 +51,8 @@ def update_user(*, session: Session, db_user: User, user_in: UserUpdate) -> Any:
         password = user_data["password"]
         hashed_password = get_password_hash(password)
         extra_data["hashed_password"] = hashed_password
+    if "role" in user_data and user_data["role"] is not None:
+        extra_data["is_superuser"] = user_data["role"] == UserRole.super_admin
     db_user.sqlmodel_update(user_data, update=extra_data)
     session.add(db_user)
     session.commit()
@@ -145,3 +163,56 @@ def complete_company_registration(
     session.commit()
     session.refresh(company)
     return company
+
+
+def create_audit_log(
+    *,
+    session: Session,
+    action: AuditAction,
+    target_user_id: uuid.UUID,
+    performed_by_id: uuid.UUID,
+    changes: str = "",
+) -> AuditLog:
+    db_log = AuditLog(
+        action=action,
+        target_user_id=target_user_id,
+        performed_by_id=performed_by_id,
+        changes=changes,
+    )
+    session.add(db_log)
+    session.commit()
+    session.refresh(db_log)
+    return db_log
+
+
+def get_audit_logs(
+    *, session: Session, skip: int = 0, limit: int = 100
+) -> tuple[list[AuditLogPublic], int]:
+    count_statement = select(func.count()).select_from(AuditLog)
+    count = session.exec(count_statement).one()
+
+    statement = (
+        select(AuditLog)
+        .order_by(col(AuditLog.created_at).desc())
+        .offset(skip)
+        .limit(limit)
+    )
+    logs = session.exec(statement).all()
+
+    result = []
+    for log in logs:
+        target = session.get(User, log.target_user_id)
+        performer = session.get(User, log.performed_by_id)
+        result.append(
+            AuditLogPublic(
+                id=log.id,
+                action=log.action,
+                target_user_id=log.target_user_id,
+                performed_by_id=log.performed_by_id,
+                changes=log.changes,
+                created_at=log.created_at,
+                target_user_email=target.email if target else None,
+                performed_by_email=performer.email if performer else None,
+            )
+        )
+    return result, count