Skip to main content

TDD — API Perfil de usuário

Status​

Implementado

Contexto​

Carga e atualização do perfil do usuário autenticado. Usado pela Home (carga inicial) e pelo ProfileDialog (refresh, update).

Contratos​

GET myProfileHttp

  • Headers: Authorization: Bearer <idToken>
  • Response: objeto UserProfile (id, name, email, status, roleAssignments, etc.)

POST userGatewayHttp (ações de perfil)

  • USER_GET — idêntico ao myProfileHttp
  • USER_PROFILE_UPDATE — atualizar dados
  • USER_PREFERENCES_UPDATE — preferências
  • USER_ACTIVE_ROLE_SET — cargo ativo (payload pode enviar roleId ou descrição; no BD persiste apenas roleId)
  • USER_ROLES_AVAILABLE_LIST — catálogo eligível

Persistência de papéis: No BD, active_role e primary_role devem guardar apenas o roleId (identificador do cargo no catálogo). A descrição do cargo (ex.: "Professor da EBD") é usada somente para apresentação em tela; o backend resolve valor enviado (id ou descrição) para roleId antes de persistir.

Interface de Usuário (UI)​

O perfil não tem tela própria — é carregado em background e exibido no header da Home (avatar, nome) e no ProfileDialog (todas as abas). Componentes que dependem do perfil:

  • Avatar e nome no header da Home
  • Conteúdo completo do ProfileDialog (dados, papéis, mensagens, preferências)
  • Badge de status na Home ("Consultando perfil...", status da conta)

Observação: O perfil é carregado na abertura da Home; o dialog usa os dados já em memória e pode disparar refresh ao salvar.

Fluxo​

  1. Home: loadProfile() → GET myProfileHttp (ou USER_GET)
  2. ProfileDialog: refresh → USER_GET
  3. ProfileDialog: salvar → USER_PROFILE_UPDATE

Verificação e ajuste mínimo ao abrir o perfil​

Ao servir o perfil (USER_GET / myProfileHttp), o backend verifica se ele atende aos requisitos mínimos para ser manipulado pela interface. Caso não atenda, aplica um ajuste mínimo antes de devolver a resposta.

Requisitos mínimos​

  • role_assignments não vazio
  • active_role (ou primary_role) presente e contido em role_assignments com status APPROVED

Ajuste mínimo (automático)​

Se o perfil não atender:

  1. Obtém o papel de nível hierárquico mínimo do catálogo do ministério (ex.: VISITOR / VISITANTE).
  2. Define primary_role, active_role e role_assignments com um único assignment aprovado para esse papel.
  3. Limpa role_requests.
  4. Atualiza person.roleAssignments e person.updatedAt quando existir person.
  5. Persiste e retorna o perfil já corrigido.

Assim, ao abrir a Home ou o ProfileDialog, perfis com role_assignments vazio ou cargo ativo inválido passam a ser corrigidos na própria leitura, permitindo uso da interface sem rodar script manual.

Código: ProcessUserActionUseCase.meetsMinimumProfileRequirements, ensureProfileMinimumForInterface, chamados em handleUserGet.

Código de referência​

  • frontend/lib/application/services/user_profile_service.dart
  • frontend/lib/infrastructure/profile/backend_http_profile_repository.dart
  • backend/functions/src/interfaces/http/my-profile-http-controller.ts
  • backend/functions/src/application/use-cases/process-user-action.ts

Recuperação de perfil bloqueado (script manual)​

Quando a interface (ProfileDialog) impede a atualização por inconsistências no perfil e o ajuste automático ao abrir o perfil não for suficiente (ex.: usuário ainda não abriu o app após a correção), usar o script ou os comandos abaixo.

Causas comuns que bloqueiam a UI​

CausaVerificação
primary_role ou active_role inválidos (fora do catálogo)Ler doc em platform/ministrys/{ministryId}/data/users/{email}
role_assignments vazios ou com roleId inexistenteComparar com platform/.../user_roles/catalog
role_requests pendentes que travam escolha de cargo—
Validação frontend (nome < 10 chars, telefone vazio)Corrigir via script ou UI após ajuste de roles
unit_id ou organization_node inválidosVerificar se igreja existe em platform/.../data/churchs

Comandos de debug para inspecionar​

/db read --path platform/ministrys/ebdbe.com.br/data/users --documentId <email>

Ver: scripts/DEBUG-COMANDOS-PERFIL-USUARIO.md

Rotina de correção​

Executar o script para ajustar ao nível mínimo (ex.: VISITOR):

cd backend/functions
npm run fix-profile-minimum-level -- <email> [ministryId]

O script:

  • Define primary_role, active_role e role_assignments ao papel de menor hierarquia do catálogo
  • Limpa role_requests
  • Preserva demais campos do documento (merge)
Last updated on