Problem 1: Add role_id support to user_service create/update/_user_to_dict

app/services/user_service.py

@@ -69,15 +69,21 @@ class UserService:
         name: str,
         password: str,
         role: str = "viewer",
+        role_id: uuid.UUID | None = None,
         is_active: bool = True,
     ) -> User:
-        """Create a new user in a tenant."""
+        """Create a new user in a tenant.
+
+        If role_id is provided it links the user to a custom Role record.
+        The legacy ``role`` string is kept for backward compatibility.
+        """
         user = User(
             tenant_id=tenant_id,
             email=email,
             name=name,
             password_hash=hash_password(password),
             role=role,
+            role_id=role_id,
             is_active=is_active,
             preferences={},
         )
@@ -102,9 +108,15 @@ class UserService:
         user_id: uuid.UUID,
         name: str | None = None,
         role: str | None = None,
+        role_id: uuid.UUID | None = None,
         is_active: bool | None = None,
     ) -> User | None:
-        """Update a user."""
+        """Update a user.
+
+        ``role_id`` accepts a UUID to link a custom Role, or None to leave
+        the existing value unchanged.  Pass ``role_id`` explicitly as None
+        combined with the sentinel logic below to clear it.
+        """
         q = select(User).where(User.id == user_id, User.tenant_id == tenant_id)
         result = await db.execute(q)
         user = result.scalar_one_or_none()
@@ -115,6 +127,8 @@ class UserService:
             user.name = name
         if role is not None:
             user.role = role
+        if role_id is not None:
+            user.role_id = role_id
         if is_active is not None:
             user.is_active = is_active
 
@@ -145,6 +159,7 @@ class UserService:
             "email": user.email,
             "name": user.name,
             "role": user.role,
+            "role_id": str(user.role_id) if user.role_id else None,
             "is_active": user.is_active,
             "tenant_id": str(user.tenant_id),
         }