Skip to content

Auto cadastro Create Account

Jump to bottom
Manager Technical Documenter edited this page Aug 19, 2026 · 1 revision

Auto-cadastro (Create Account)

Documentação técnica do fluxo público de auto-cadastro inicial de usuários no ecossistema Controle Online.

Issue de origem: api-community#5

Objetivo

Permitir que o front-end (ui-login e app) realize o cadastro inicial de pessoa + usuário sem autenticação prévia, com verificação de e-mail posterior.

Repositórios envolvidos

Módulo Papel no fluxo
api-platform-people Endpoint canônico POST /create-account, orquestração via AccountRegistrationService
api-platform-users Criação do User (UserService::createUser), hash de senha, verificação de conta
api-community Gateway: access_control libera as rotas públicas; agrega submódulos
ui-login UI de “Criar conta” (MANAGER/SHOP → formulário; demais → QR Code)

Endpoint público

Método URI Segurança Status de sucesso
POST /create-account PUBLIC_ACCESS 202

Configuração em api-platform-people (People ApiResource):

  • controller: ControleOnline\Controller\CreateAccountAction
  • deserialize: false / read: false / output: false
  • resposta de sucesso: JSON { "success": true, "message": "Cadastro criado com sucesso. Confira seu e-mail para ativar a conta." }

No gateway api-community (config/packages/security.yaml), as rotas públicas incluem:

- { path: ^/create-account, roles: PUBLIC_ACCESS }
- { path: ^/users/create-account$, roles: PUBLIC_ACCESS }

A rota legada /users/create-account permanece liberada no access control para compatibilidade com clientes antigos; a implementação canônica atual é POST /create-account no módulo people.

Payload esperado

Corpo JSON (estrutura principal):

{
  "people": {
    "name": "Nome completo",
    "alias": "Apelido ou nome fantasia",
    "email": "usuario@exemplo.com",
    "phone": {
      "ddi": "55",
      "ddd": "11",
      "phone": "987654321"
    },
    "document": null,
    "user": {
      "user": "usuario@exemplo.com",
      "password": "senha-secreta"
    }
  },
  "company": {
    "name": "Empresa opcional",
    "document": null,
    "email": null
  }
}

Campos obrigatórios (people)

Campo Descrição
name Nome da pessoa
alias Alias / nome de exibição
email E-mail (também usado no envio de verificação)
phone.ddi Código do país (somente dígitos)
phone.ddd DDD (somente dígitos)
phone.phone Número local (somente dígitos; se vier com DDD prefixado, o service normaliza)

Usuário (people.user)

Quando presente:

Campo Descrição
user Username (tipicamente o e-mail)
password Senha em texto; o backend aplica hash via UserPasswordHasherInterface

Sem people.user.user / people.user.password o cadastro de pessoa pode seguir, mas a criação de login e o e-mail de verificação não são disparados.

Empresa (company) — opcional

Permite descobrir/criar pessoa jurídica e vínculos no mesmo fluxo. Campos típicos: document, email, telefone, nome.

Fluxo interno (resumo)

sequenceDiagram
  participant FE as Front (ui-login)
  participant GW as api-community
  participant P as api-platform-people
  participant U as api-platform-users

  FE->>GW: POST /create-account (JSON)
  GW->>P: CreateAccountAction
  P->>P: AccountRegistrationService.registerFromPayload
  P->>P: PeopleService.discoveryPeople (pessoa)
  opt company no payload
    P->>P: discoveryPeople (empresa) + links
  end
  opt people.user presente
    P->>U: UserService.createUser
    P->>P: AccountVerificationService.sendVerification
  end
  P-->>FE: 202 success + mensagem de e-mail
Loading

Passos principais em AccountRegistrationService:

  1. Valida people e telefone.
  2. Detecta se é o primeiro usuário do tenant (User count = 0) — nesse caso o vínculo com a empresa principal pode ser owner.
  3. PeopleService::discoveryPeople (documento/e-mail/telefone/nome) + aplicação de name/alias.
  4. Se houver company, descobre/cria empresa e links.
  5. Se houver people.user, cria User e envia verificação de conta.
  6. Transação Doctrine: commit ou rollback em qualquer falha.

Segurança e limites

  • Endpoint público (PUBLIC_ACCESS): não exige token.
  • Não expor credenciais, API keys ou dados de terceiros na resposta de sucesso (apenas mensagem genérica).
  • Username é único (users.user_name); e-mail/telefone entram na descoberta de pessoa — duplicidade pode reutilizar pessoa existente conforme regras de discoveryPeople.
  • Criação administrativa de usuário em /users (ApiResource) continua protegida por ROLE_CLIENT e não substitui o auto-cadastro público.
  • Roles do usuário não são persistidos no User; vêm de people_link em runtime (PeopleRoleService).

Integração front-end

No ui-login:

  • Rota de create-account e store auth/actions consomem o endpoint público.
  • Comportamento de produto (comentário em #5): se o contexto for MANAGER ou SHOP, exibe formulário de cadastro; caso contrário, pode exibir QR Code (fluxo alternativo de onboarding).

O que este módulo não faz

  • Não implementa tela de login (isso é ui-login + POST /token).
  • Não gerencia recuperação de senha (password_recoveries / recovery_accesses — fluxos separados, também públicos).
  • Não decide regras de CRM/POS/SHOP além do vínculo people/company no cadastro inicial.

Referências de código

Artefato Local
Action api-platform-people → src/Controller/CreateAccountAction.php
Service api-platform-people → src/Service/AccountRegistrationService.php
ApiResource api-platform-people → src/Entity/People.php (uriTemplate: /create-account)
User create api-platform-users → src/Service/UserService.php (createUser)
Access control api-community → config/packages/security.yaml

Links relacionados

Clone this wiki locally