feat(panel-admin): full CRUD User resource com informação agregada de perfil, gamificação, atividade e moderação

[stherzada]

Context

Não existe UserResource no painel admin. Staff/moderação precisa de uma tela única pra ver e editar um membro por inteiro — hoje os dados de identidade, perfil profissional, gamificação, atividade e moderação estão espalhados entre Character, ExternalIdentity, Profile, Address e ModerationCase.

Esta issue entrega List, Edit e View para os dados que fazem sentido serem editados pelo admin, mantendo como seções agregadas somente-leitura os dados que vêm de outros domínios — respeitando a fronteira presentation/core. Create fica fora de escopo (o fluxo de conta é via OAuth, que deve ser o caminho único e universal de ingresso; criação manual fere esse gate e, como fallback, seria admitir débito técnico).

Onde

app-modules/panel-admin/src/Filament/Resources/Users/

(seguir o padrão em pastas de ExternalIdentities/:
UserResource.php + Schemas/UserForm.php + Schemas/UserInfolist.php + Tables/UsersTable.php + Pages/{List,Edit,View}User.php + RelationManagers/).
Sem CreateUser.php (Create fora de escopo).

Escopo — editável

• Identidade (users): username, name, email, is_donator.
• Perfil (user_profiles): nickname, headline, about, birthdate, seniority_level, years_experience, available_for_proposals, start_availability, expected_salary_min/max, social_links, preferences (remoto/relocação/tipo de contrato/deficiência).
• Skills: RelationManager sobre skills() (pivot proficiency + years_experience).
• Experiências: RelationManager sobre workExperiences().
• Endereço: país/estado/cidade (address()).

Motivação: correção de dado errado informado pelo membro (sobretudo campos únicos/imutáveis), sempre com análise por trás — alternativa auditável ao acesso direto ao banco.

Escopo — agregado / somente leitura

• Gamificação (Character): level, XP, reputação, wallet, badges. Somente leitura — ajuste manual de wallet/XP fere a economia do ecossistema e dá permissibilidade demais ao admin (valores derivados).
• Atividade (ExternalIdentity/DiscordMember→DiscordRole): conexões (Discord/GitHub/Twitch/devto), contagem de mensagens, horas de voice, roles do Discord.
• Moderação (ModerationCase): casos como autor/assignee, suspended_until/banned_at.

Ações

• Soft delete (default): ação de exclusão padrão faz soft delete, impedindo recadastro com os mesmos acessos (não impede criar outra conta). Alinha com a moderação existente: "Ban" ≈ soft delete; "Suspend" ≠ delete (restringe ações por X período).
• Hard delete (restrito): exclusão física existe por compliance/lei (inegociável), mas nunca é o default — ação distinta, gated por permissão específica de compliance, com confirmação explícita.

Detalhes de implementação

• Model do resource = User::class.
• Delete: habilitar SoftDeletes no fluxo do Resource; ação padrão faz soft delete, hard delete é ação separada gated por permissão de compliance.
• Autorização: definir Policy (ou Filament Shield) para o UserResource. Edit e Delete (soft) → apenas staff; hard delete → permissão de compliance específica (subconjunto ainda mais restrito); View → pode ser mais amplo (ex.: recrutadores, captains de squad), com a seção de Moderação e demais dados sensíveis ocultos para esses papéis. Campos sensíveis (email, is_donator) só editáveis por staff. "Staff" sozinho não basta como critério da tela inteira — a diferença de permissíveis por seção precisa ser explícita.
• Tabela (index): username, name, seniority_level, available_for_proposals, cidade, level; ->searchable() em username/name/email; ->paginated([25,50,100]); SelectFilter de seniority; TernaryFilter de available_for_proposals.
• Registrar em PanelAdminServiceProvider::register() e adicionar ...UserResource::getNavigationItems() em defaultNavigation().
• Seções agregadas: ler via relacionamento (character(), providers(), caso por author/assignee) — sem duplicar lógica de escrita desses domínios dentro do panel-admin.

Critérios de aceite (Gherkin)

• Listagem: dado que sou staff, quando acesso Admin ▸ Usuários, então vejo tabela buscável por name/username/email com level e status (ativo/suspenso/banido/donator).
• Editar: dado que abro um usuário, quando altero campos de identidade/perfil/endereço e salvo, então os dados persistem corretamente (inclusive preferences e social_links).
• Visualizar agregado: dado que estou na tela do usuário, então vejo Gamificação/Atividade/Moderação preenchidas via relacionamento, e nenhum campo dessas seções é editável por aqui.
• Edge case — sem Character/Profile: dado um usuário sem Character ou sem user_profiles, quando abro a tela, então as seções correspondentes mostram estado vazio em vez de quebrar (usar Profile::ensureExists). Obs.: as 3 formas de acesso atuais (OAuth) já criam ao menos o user_profile, então esse estado é majoritariamente defensivo.
• Soft delete é o default: dado que sou staff, quando excluo pela ação padrão, então o usuário é soft-deleted e não consegue se recadastrar com os mesmos acessos.
• Hard delete é restrito: dado que não tenho a permissão de compliance, então a ação não aparece; dado que tenho, quando a executo, então preciso confirmar explicitamente antes da exclusão física.
• Autorização: dado um usuário sem policy adequada, então não consegue editar (staff-only) nem — quando não autorizado — ver o Resource; papéis de View sem permissão de moderação não veem a seção de Moderação.
• Resource aparece na sidebar do /admin.

Cobertura de teste

• Save do profile (seguir os testes existentes do módulo profile).
• RelationManager de Skills: attach/detach e edição do pivot (proficiency, years_experience).
• RelationManager de Experiências: create/edit/delete.
• Estado vazio das seções agregadas (Gamificação/Atividade/Moderação) para usuário sem Character/Profile — garantir que a tela não quebra.
• Soft delete: exclusão padrão marca deleted_at e bloqueia recadastro com os mesmos acessos.
• Hard delete: indisponível sem permissão de compliance; disponível e efetivo (com confirmação) com a permissão.
• Concessão de badge: bloqueada sem evento atrelado; concede via action do domínio quando há evento.
• Autorização: usuário sem policy adequada não deve conseguir editar (ou nem ver) o Resource; papel de View sem permissão de moderação não enxerga a seção de Moderação.

[stherzada]

Open questions (para triagem)

• Create: o fluxo normal de conta é via OAuth — faz sentido o admin criar usuário manualmente aqui, ou "Create" fica disponível sem caso de uso real por ora?
• Delete: exclusão física do usuário, ou essa ação deve ficar restrita às ferramentas de moderação já existentes (ban/suspend no ModerationCaseResource)?
• Gamificação: wallet/badges ficam só exibidos, ou o admin deve poder ajustar wallet/conceder badge diretamente por aqui (ação separada, não edição direta de XP/level, que são valores derivados)?
• Fronteira core: confirmar se profile(): HasOne no User é aceitável ou se deve ser resolvido só dentro do panel-admin.
• Policy: quem além de "staff" pode acessar este Resource, e há diferença de permissão entre seções?

FInalizado, badges e conceções para tal virá num segundo momento.

[arthurbazzz]

Hoje no momento de anexar a imagem tanto para foto de perfil ou para capa não existe uma opção de redimensionar para o tamanho do banner. Isso acaba dando um problema se a imagem for diferente da proporção / tamanho acaba ou ficando achatada ou fora do layout.

Outro ponto é relacionado a sincronização, por exemplo:
Se eu tenho uma conta criada pelo discord, posteriormente criar uma conta utlizando o github.
E nesta do github fazer a conexão com a conta no discord já existente, aparece uma opção para mesclar as duas contas, entretanto que no momento da mesclagem não informa qual conta vai ser sobreposta, poderia ter uma opção de selecionar ou algum informativo sobre.

[stherzada]

@arthurbazzz Ótimo ponto, mas acredito que no momento isso entre mais como bug, do que algo desse contexto aqui. Mas, irei abrir uma nova task relacionada a isso, e ela já pode ser atuada :)

[YuriSouzaDev]

Respondendo as questões em aberto:

• Create: Não vejo por que seria necessário um admin criar um usuário, o que traria? Criar um usuário que é de fora da comunidade, invès dele mesmo se cadastrar logando de algumas das formas possíveis?
• Delete: a exclusão deve ser via soft delete, impossibilitando usuarios de se recadastrar novamente usando os mesmos acessos. Mas não impede dele criar outra conta e acessar novamente.
• Gamificação: admins não devem fazer esse tipo de alteração, pois deixa aberto para futuras edições. Há não ser que tenha um log bem construido e que ai sim não possa ser apagado para auditorias.
  Fronteira core: Este ulimo não entendi.

Pontos que fiquei na dúvida:

• Ainda fico na dúvida no por que um admin poderia editar os dados de um usuário? Tem algum caso de uso já em mente?
• No caso do Edge case de um usuário sem Character ou sem user_profiles, que tipo de usuário seria esse?

[stherzada]

• Pontos da dúvida

Create: Não vejo por que seria necessário um admin criar um usuário, o que traria? Criar um usuário que é de fora da comunidade, invès dele mesmo se cadastrar logando de algumas das formas possíveis?

Penso muito de ser um fallback do que usado em si, se deu tudo errado é o famoso "temos essa opção ainda"

Ainda fico na dúvida no por que um admin poderia editar os dados de um usuário? Tem algum caso de uso já em mente?

Penso muito no caso de quando usuário erra a informação, principalmente se for uma informação única e imutavel, exemplo um CPF (não é o caso aqui), por incrível que pareça é bem comum disso rolar e tendo essa permissão e obviamente uma ánalise por trás, já ajudaria ao invés de tem que ir direto em um banco e etc.

No caso do Edge case de um usuário sem Character ou sem user_profiles, que tipo de usuário seria esse?

Seria um usuário sem conta nenhuma tentando esse acesso, vai ser mostrado algo vazio e etc;

Sobre fronteiracore

A pergunta que eu faria antes de codar: "esse relacionamento seria útil pra algum outro módulo além do panel-admin?"

• Se sim → Opção A, adiciona no User, é uma melhoria de domínio legítima.
• Se não, é só pro form/infolist renderizarem mais fácil → Opção B, mantém isolado no panel-admin e deixa o User limpo.

@YuriSouzaDev

[YuriSouzaDev]

Penso muito no caso de quando usuário erra a informação, principalmente se for uma informação única e imutavel, exemplo um CPF (não é o caso aqui), por incrível que pareça é bem comum disso rolar e tendo essa permissão e obviamente uma ánalise por trás, já ajudaria ao invés de tem que ir direto em um banco e etc.

Neste ponto faz sentido, apenas para esse tipo de situação por conta da análise que citou.

Seria um usuário sem conta nenhuma tentando esse acesso, vai ser mostrado algo vazio e etc;

Hoje só temos 3 formas de acesso, que já cria ao menos o user_profile dele, nessa situação seria o caso do admin criar o usuario?

A pergunta que eu faria antes de codar: "esse relacionamento seria útil pra algum outro módulo além do panel-admin?"

• sim, pois poderia ser reaproveitado por outros modulos. Seria legitimo criar algo assim, mas ao mesmo tempo penso que poderia pensar em um case que ainda nem aconteceu e pode nem acontecer.

Falttou este anteriormente:

• Policy: No caso para recrutadores, poderia ter uma tela diferente. Pois eles precisam das mesmas informações que um admin, mas algumas não precisam ser mostradas como questão de moderação etc.

@stherzada

[guisaliba]

Open questions (para triagem)

* Create: o fluxo normal de conta é via OAuth — faz sentido o admin criar usuário manualmente aqui, ou "Create" fica disponível sem caso de uso real por ora?

* Delete: exclusão física do usuário, ou essa ação deve ficar restrita às ferramentas de moderação já existentes (ban/suspend no ModerationCaseResource)?

* Gamificação: wallet/badges ficam só exibidos, ou o admin deve poder ajustar wallet/conceder badge diretamente por aqui (ação separada, não edição direta de XP/level, que são valores derivados)?

* Fronteira core: confirmar se profile(): HasOne no User é aceitável ou se deve ser resolvido só dentro do panel-admin.

* Policy: quem além de "staff" pode acessar este Resource, e há diferença de permissão entre seções?

• Create: deveria ficar disponível sem caso de uso real por ora. Não vejo sentido um admin criar um usuário manualmente (fere o gate/mecanismo de entrada na plataforma que é por OAuth, e deveria ser o caminho único e universal de ingress na plataforma). Ainda que fosse fallback para ser utilizado em último caso, ter isso como workaround é admitir débito técnico. Se um User não consegue ser criado via OAuth, há algum bug/problema/instabilidade na plataforma que precisa ser corrigido.
• Delete: não concordo com exclusão física, apenas lógica (soft delete). Deveria ficar restrita às ferramentas de moderação já existentes. "Ban" agiria como soft delete de um usuário, passando por esse delete. "Suspend" não necessariamente, acredito que esta é mais sobre restringir ações de um User durante X período do que deletá-lo.
• Gamificação: a. permitir ajuste manual de wallet feriria a economia do ecossistema, além de dar muita permissibilidade para um admin; b. Conceder badge diretamente é justificável, ainda mais quando surgir a necessidade de criar badges especificas que não estarão atreladas a nenhum evento ou informação do Character, e precisariam ser adicionadas manualmente aos perfis (caso de uso comum na plataforma da GamersClub por exemplo).
• Policy: Edit e Delete deveriam estar condicionads somente à "staff". View, não necessariamente (e.g.: recrutadores, captains de uma Squad, etc. poderiam ter uma feature de busca de Users).

[stherzada]

@guisaliba Ótimos pontos levantados, sobre a questão do delete, acredito que tenhamos que pensar um pouco na LGPD, caso o usuário queira sua conta e dados não atrelados a plataforma, podemos concender esses direito.

sobre a questão do admin, curto da ideia de não mexer na wallet mas também curto a ideia de não conceder badge, de ser algo recebido legitimamente por conta de X evento e etc, dá a ideia de ser o famoso concedido pela real participação da pessoa sabe?

[guisaliba]

@stherzada de fato, um Delete físico precisa existir, acho que é uma ação inegociável justamente por questões de leis e compliance. Mas não deveria ser o caso de uso default, e sim o soft-delete.

Sobre as badges: se vamos atrelar toda badge à um evento, isso significa que qualquer evento da comunidade que deveria conceder uma badge, precisa de alguma forma passar pela plataforma. Nesse caso, para qualquer evento que não esteja diretamente ligado à plataforma, como garantir que as badges serão dadas aos membros que participaram dele?

OBS: Quando falo "qualquer evento", estou me referindo aos eventos fora do mundo digital (encontros, pubs, etc.), que entende-se a necessidade criação de uma badge (quais serão os critérios para está fora desse escopo). Isso é diferente de "um evento qualquer".

Proposta: gosto da ideia de permitir a concessão manual de badges, mas sem ferir o princípio de "se fulano tem essa badge, foi porque participou de tal evento". Por isso, acredito que o meio termo aqui seria permitir a criação manual, CONTANTO QUE haja um evento real atrelado à ela no momento de criação.