Merge pull request #8 from EluminiIT/devin/1774626691-admin-users-roles

* 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>

* fix: address Devin Review - privilege escalation guards, read_user_by_id role check, AuditLogPublic type

- Add privilege escalation check in create_user: only Super Admin can create Super Admin
- Add privilege escalation checks in update_user: only Super Admin can modify/promote to Super Admin
- Fix read_user_by_id to use role-based check instead of is_superuser
- Add target_user_email and performed_by_email fields to frontend AuditLogPublic type

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

* fix: remove password fields from Edit User dialog

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

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: daniel.resgate <daniel.rider69@gmail.com>

Author: DanielResgateTI

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,12 +54,27 @@ 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).
     """
+    # Only Super Admin can create another Super Admin
+    if (
+        user_in.role == UserRole.super_admin
+        and current_user.role != UserRole.super_admin
+    ):
+        raise HTTPException(
+            status_code=403,
+            detail="Only a Super Admin can create another Super Admin",
+        )
+
     user = crud.get_user_by_email(session=session, email=user_in.email)
     if user:
         raise HTTPException(
@@ -67,13 +85,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 +186,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
@@ -168,7 +209,13 @@ def read_user_by_id(
     user = session.get(User, user_id)
     if user == current_user:
         return user
-    if not current_user.is_superuser:
+    if not current_user.role or current_user.role not in [
+        UserRole.comercial,
+        UserRole.juridico,
+        UserRole.financeiro,
+        UserRole.rh,
+        UserRole.super_admin,
+    ]:
         raise HTTPException(
             status_code=403,
             detail="The user doesn't have enough privileges",
@@ -180,17 +227,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)
@@ -199,23 +247,74 @@ def update_user(
             status_code=404,
             detail="The user with this id does not exist in the system",
         )
+    # Only Super Admin can modify a Super Admin user
+    if (
+        db_user.role == UserRole.super_admin
+        and current_user.role != UserRole.super_admin
+    ):
+        raise HTTPException(
+            status_code=403,
+            detail="Only a Super Admin can modify another Super Admin",
+        )
+    # Only Super Admin can assign the Super Admin role
+    if (
+        user_in.role == UserRole.super_admin
+        and current_user.role != UserRole.super_admin
+    ):
+        raise HTTPException(
+            status_code=403,
+            detail="Only a Super Admin can assign the Super Admin role",
+        )
     if user_in.email:
         existing_user = crud.get_user_by_email(session=session, email=user_in.email)
         if existing_user and existing_user.id != user_id:
             raise HTTPException(
                 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 +323,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)