TDD — Gateway de operações de usuário

Status

Implementado

Contexto

Endpoint único userGatewayHttp (POST) para operações de perfil, papéis e mensagens. Usado por ProfileDialog, RoleCatalogService e outros. Ver ADR-0014.

Interface de Usuário (UI)

O gateway não tem tela própria — é consumido por componentes da aplicação:

• ProfileDialog — USER_GET, USER_PROFILE_UPDATE, USER_PREFERENCES_UPDATE, USER_ACTIVE_ROLE_SET, USER_ROLES_AVAILABLE_LIST, USER_ROLE_REQUEST, USER_ROLE_REQUESTS_PENDING, USER_MESSAGES_LIST
• RegisterPage / HomePage auto-registro — USER_SELF_REGISTER
• Admin/gestão — USER_CHANGE_STATUS (com meta.reason)
• Debug (Firestore Command) — pode injetar comandos que acionam o gateway

Observação: Cada ação corresponde a uma operação visível em uma tela; erros retornados são exibidos em SnackBar ou inline conforme o componente.

Contratos

POST userGatewayHttp

• Headers: Authorization: Bearer <idToken>
• Body: { version: "v1", action: string, payload: object, meta: { requestId, targetMinistryId?, reason? } }
• Response: { ok: boolean, action: string, data: object|null, audit: object, error?: { code, message, details? } }

Payloads por ação

Action	Payload
USER_GET	{}
USER_PROFILE_UPDATE	{ name?, aliasName?, phone?, unitId?, avatarImage?, avatarUrl? }
USER_PREFERENCES_UPDATE	{ preferences: { appearance?: { skin? }, notifications?, usage? } }
USER_ACTIVE_ROLE_SET	{ roleId: string }
USER_ROLES_AVAILABLE_LIST	{ unitId?, fullCatalog?: boolean }
USER_ROLE_REQUEST	{ roleId, unitId?, reason? }
USER_ROLE_REQUEST_DELETE	{ requestId }
USER_ROLE_REQUEST_APPROVE	{ requestId, reason? }
USER_ROLE_REQUEST_REJECT	{ requestId, reason? }
USER_ROLE_REQUESTS_PENDING	{ unitId? }
USER_SELF_REGISTER	{ name?, unitId?, ministryId? }
USER_MESSAGES_LIST	{}
USER_CHANGE_STATUS	{ targetUserId, toStatus, reason } (sensível; exige meta.reason)

Fluxo (pipeline)

1. Autenticar solicitante
2. Resolver tenant por domínio
3. Validar escopo
4. Autorizar ação por papel
5. Validar payload
6. Executar use case
7. Auditoria
8. Retornar resposta

Código de referência

• backend/functions/src/interfaces/http/user-gateway-http-controller.ts
• backend/functions/src/application/use-cases/process-user-action.ts
• ADR-0014