Indicação para Grupo (Convite)

Resumo

Administradores de hospital ou do sistema podem convidar pessoas externas para se cadastrarem diretamente em seu grupo (hospital). O sistema gera tokens SHA-256 com validade de 7 dias, envia e-mail de convite via BuddyPress ou fallback wp_mail, e no cadastro via token o usuário é ativado automaticamente e adicionado ao grupo sem aprovação.

Fontes de evidência

• theme/functions/indication/class-indication-handler.php — handler principal (~580 linhas)
• theme/functions/indication/ajax.php — endpoints AJAX (~170 linhas)

Regras de negócio

Token de convite

• Gerado via wp_generate_password(32, false) — 32 caracteres alfanuméricos.
• Hash SHA-256 armazenado em WordPress transient (hsl_invite_{hash}).
• Validade: 7 dias (TOKEN_EXPIRATION = 604800 segundos).
• Uso único: Marcado como used = true após cadastro.
• Transient adicional por e-mail+grupo: hsl_invite_email_{md5(email_group_id)}.

Evidência: class-indication-handler.php — constantes e método generate_invitation_token().

Dados armazenados no token

{
  "email": "convidado@hospital.com",
  "group_id": 123,
  "inviter_id": 45,
  "hash": "sha256(...)",
  "created_at": 1700000000,
  "expires_at": 1700604800,
  "used": false
}

Validação do token (validate_token)

1. Verifica se transient existe.
2. Verifica se used === false.
3. Verifica se time() <= expires_at.
4. Enriquece com dados do grupo: group_name, city_name, state_name, hospital_cnes.

Evidência: class-indication-handler.php — método estático validate_token().

Permissões — Quem pode indicar

Condição	Pode indicar?
administrator	✅
Role administrador_site	✅
hospital_group_admin() do grupo	✅
Admin do grupo BP (groups_is_user_admin)	✅
Membro comum do grupo	❌
Não logado	❌

Evidência: class-indication-handler.php — método can_user_indicate().

Envio de e-mail

1. Primário: bp_send_email('invite_group_email', ...) com tokens BuddyPress:
   • group.name, group.url, inviter.name, registration.url
2. Fallback: wp_mail() com texto plain UTF-8 caso bp_send_email falhe.
3. URL do convite: {home_url}/cadastre-se/?invite_token={token}

O tipo de e-mail invite_group_email é registrado automaticamente na taxonomy bp-email-type do BuddyPress.

Evidência: class-indication-handler.php — métodos send_indication_email(), send_indication_email_fallback(), ensure_email_type_registered().

Endpoints AJAX

Action	Método	Auth	Descrição
hsl_indication_submit	POST	Logado	Envia indicações para lista de e-mails
hsl_indication_validate_token	GET/POST	nopriv	Valida token de convite (para preencher formulário)

Payload de submit

{
  "action": "hsl_indication_submit",
  "nonce": "...",
  "group_id": 123,
  "emails": "email1@test.com, email2@test.com"
}

Resposta de submit

{
  "success": true,
  "data": {
    "sent": ["email1@test.com"],
    "failed": [{"email": "invalido", "reason": "E-mail inválido."}],
    "already_member": ["email2@test.com"],
    "total_sent": 1,
    "total_failed": 1,
    "total_already": 1,
    "message": "1 indicação enviada com sucesso!",
    "already_message": "1 e-mail já é membro do grupo."
  }
}

Evidência: indication/ajax.php:13-31 e class-indication-handler.php — método process().

Fluxo completo

sequenceDiagram
    participant Admin as Admin do Hospital
    participant WP as WordPress
    participant IH as Indication_Handler
    participant Mail as E-mail
    participant Guest as Convidado
    participant RH as Registration_Handler

    Admin->>WP: POST hsl_indication_submit (group_id + emails)
    WP->>WP: check_ajax_referer('hsl_indication_nonce')
    WP->>IH: process({group_id, emails})
    IH->>IH: can_user_indicate() ✅

    loop Para cada email
        IH->>IH: Verifica se já é membro
        IH->>IH: generate_invitation_token()
        IH->>Mail: bp_send_email / wp_mail
    end
    IH-->>WP: {sent, failed, already_member}
    WP-->>Admin: Resultado

    Mail-->>Guest: E-mail com link /cadastre-se/?invite_token=XXX
    Guest->>WP: Acessa link
    WP->>IH: validate_token(XXX)
    IH-->>WP: {email, group_id, group_name, ...}
    WP-->>Guest: Formulário pré-preenchido

    Guest->>WP: POST hsl_registration_submit + invite_token
    WP->>RH: process() — detecta invite_token
    RH->>IH: validate_token() ✅
    RH->>RH: Força email/hospital do convite
    RH->>WP: Cria usuário
    RH->>IH: process_invited_registration()
    IH->>IH: mark_token_used()
    IH->>IH: activate_user() — BP ou WP direto
    IH->>WP: groups_join_group()
    WP-->>Guest: "Conta ativada! Já pode fazer login."

Frontend

• Script: assets/dist/project/js/indication.js
• CSS: assets/dist/project/css/indication.css
• Dados via wp_localize_script('hsl-indication', 'hslIndication', {...}):
  • ajaxUrl, nonce, groupId, messages
• Na página de cadastro com token, dados do convite são injetados em hslInvitation:
  • token, email, groupId, groupName, stateName, stateId, cityName, cityId

Evidência: indication/ajax.php — funções hsl_indication_enqueue_assets() e hsl_indication_enqueue_registration_data().

Segurança

• Nonce obrigatório para submit do admin.
• Token com hash SHA-256 (nunca armazena o token em texto plano).
• Token de uso único — invalidado após uso.
• E-mails são sanitizados com sanitize_email().
• Verificação de membro existente antes de enviar convite.