Gemed 2.1 — Documentação

01 - Definição v2.1

Leitura de 12 min

⬇ Baixar .md

Épico 1 — Núcleo de Identidade e Autenticação — Definição (v2.1)

Documentos deste épico: 01 - Definição (v2.1) · 02 - Especificação (v2.1) · Protótipo (Seção 3): pendente, ainda não produzido · 04 - Mapeamento de Banco de Dados (v2.1). Este épico faz parte do documento guarda-chuva Check-in de Usuários.

SEÇÃO 1 — DEFINIÇÃO

Objetivo

Autenticar o profissional já cadastrado no Gemed usando documento único (CPF no Brasil) + senha, controlar tentativas de login com bloqueio parametrizável, e oferecer um caminho de recuperação de senha sem depender de suporte técnico. É a fundação de acesso ao sistema — todo profissional, de qualquer épico deste conjunto, passa por este épico em algum momento do seu dia a dia.

Escopo

Dentro do escopo:

  • Tela de login com documento único e senha
  • Validação de credenciais do usuário (mecanismo de hash + salt)
  • Controle de tentativas de login com limite e bloqueio parametrizáveis
  • Fluxo de recuperação de senha via código de verificação (enviado por e-mail ou celular)
  • Redefinição de senha com critérios de complexidade parametrizáveis
  • Registro de histórico de senhas para política de não reutilização
  • Roteamento pós-autenticação conforme vínculos ativos e convite pendente (RN-CIU-009, RN-CIU-022)
  • Encerramento de sessão (logout)

Fora do escopo:

  • Criação da conta de usuário — auto-cadastro público (E2) ou criação pelo administrador via convite (E3)
  • Aceite de vínculo e convite (E3), seleção de clínica (E6), edição de dados do usuário (E4, a especificar)
  • Gestão de perfis de acesso (RBAC) e gestão de sessão/timeout por inatividade — tratadas no Contexto de Segurança, fora deste conjunto

Personas

  • Usuário autenticado — persona principal: profissional com conta ativa que precisa acessar o sistema no dia a dia, ou recuperar o acesso quando esquece a senha.

Workflow do Profissional

Este épico implementa o touchpoint “Profissional já tem conta e retorna ao sistema (a cada dia de trabalho)” do workflow transversal “Entrada do profissional no sistema”, documentado uma única vez no documento guarda-chuva (Seção 4.1) — não repetido aqui. Também fornece, para o E3, o campo convitesPendentes no endpoint de login (Seção 9.1/4.1 deste épico), consumido no touchpoint “Profissional foi convidado por uma clínica” (dono: E3).

Este épico documenta ainda um touchpoint próprio, não transversal (não atravessa outro épico — ver guarda-chuva, Seção 4.1, última linha):

  • Momento do workflow: profissional já tem conta, mas não consegue autenticar porque esqueceu a senha.
  • Necessidade do profissional: recuperar o acesso sem precisar acionar o suporte técnico.
  • O que a funcionalidade oferece: fluxo de recuperação em 2 etapas — solicitação por documento (código de verificação enviado por e-mail ou celular) e verificação do código com definição de nova senha.
  • Decisão de design justificada: a etapa de verificação exige reinformar o documento (dupla verificação), garantindo que quem redefine a senha é o mesmo que solicitou o código — evita que a posse do código sozinha baste para sequestrar o fluxo de recuperação.

Regras de Negócio

Este épico também aplica as regras transversais RN-CIU-005 (exclusão lógica), RN-CIU-006 (qualidade e histórico de senha), RN-CIU-007 (suporte multilíngue), RN-CIU-008 (comportamento de campos de input) e RN-CIU-022 (autenticação automática e roteamento pós-autenticação conforme convite pendente) — redação completa no documento guarda-chuva, Seção 5. O mecanismo de autenticação descrito na Seção 2 (Especificação) deste épico é o mesmo reutilizado pelo E2 ao final do wizard de auto-cadastro e pelo E3 ao final da tela de conclusão de cadastro por convite; o roteamento por vínculos da RN-CIU-009 abaixo só se aplica quando não há convite pendente (RN-CIU-022, E3/E6).

RN-CIU-001 — Documento único como chave de identificação

O usuário é identificado de forma unívoca pelo seu documento único. No Brasil, o CPF é a chave de identificação. Em outros países, o sistema deve adaptar para o documento local equivalente (passaporte, SSN, etc.). O documento é exclusivo — um mesmo documento não pode pertencer a dois usuários diferentes. O login é feito com o documento único + senha.

RN-CIU-009 — Autenticação

A autenticação valida documento único + senha. O sistema localiza o usuário pelo documento informado e valida a senha utilizando mecanismo de hash + salt (detalhado na Seção 2, “Mecanismo de autenticação”). Usuários excluídos logicamente são tratados como inexistentes — a autenticação falha com mensagem genérica, sem revelar que o usuário foi excluído.

Após autenticação bem-sucedida, o sistema primeiro verifica se existe convite pendente para o usuário (campo convitesPendentes na resposta do login, Seção 2 — RN-CIU-022, E3). Se existir, o profissional é direcionado para a tela de aceite do vínculo (E3), e a avaliação abaixo só ocorre depois do aceite. Se não existir, o sistema avalia a quantidade de clínicas acessíveis do usuário:

  1. Se possui acesso a exatamente 1 clínica — entra direto nela, carrega perfil de acesso e monta menu lateral. Direciona para o cockpit do profissional conforme seu tipo (médico → Central do Médico, enfermeira → cockpit da enfermagem, etc.). Se o tipo de profissional não tiver um cockpit específico definido, o sistema carrega apenas o perfil e o menu lateral, sem uma tela ativa.
  2. Se possui acesso a mais de 1 clínica — direciona para a tela de seleção de clínica (E6).
  3. Se possui 0 vínculos ativos (e portanto 0 clínicas acessíveis) — direciona para a página de Meu Perfil (E4) com banner informativo (MSG-I01).

Definição de “vínculo ativo”: um vínculo (registro em UsuarioCliente) é considerado ativo quando RemovidoEm IS NULL e Situacao = 'V' (Vinculado). O campo Situacao tem domínio C (Convidado), V (Vinculado) e B (Bloqueado) — definido em (CIU-E3), RN-CIU-011. Um registro com RemovidoEm nulo mas Situacao = 'C' existe (não foi excluído logicamente — RN-CIU-005) mas não conta como vínculo ativo para fins desta regra: é exatamente o que o passo anterior (verificação de convite pendente) captura antes de chegar aqui. Da mesma forma, Situacao = 'B' (vínculo bloqueado pelo administrador) também não conta como ativo — sua definição de bloqueio fica fora do escopo deste épico e do E3, a especificar quando a gestão de usuários da clínica for detalhada.

Definição de “clínica acessível”: ter um único vínculo ativo não significa necessariamente ter acesso a uma única clínica — o Cliente (o tenant com quem o vínculo é feito) pode compreender mais de uma ClienteEmpresa (por exemplo, filiais de uma mesma rede, ou clínicas de um conglomerado que não compartilham dados entre si). Uma clínica é considerada acessível quando existe, para algum vínculo ativo do usuário, um registro em ClientePerfilAcessoUsuario associando aquele vínculo a uma ClienteEmpresa específica (RN-CIU-011, em CIU-E3 — o administrador seleciona a(s) clínica(s) específica(s) ao atribuir um Perfil de acesso, o vínculo não libera automaticamente todas as ClienteEmpresa do Cliente). A quantidade de clínicas acessíveis é a contagem de ClienteEmpresa distintas alcançadas dessa forma, somando todos os vínculos ativos do usuário — não a contagem de vínculos em si. Consulta exata (junções entre tabelas) detalhada na Seção 4.

Nota (RN-CIU-022): este mesmo mecanismo (verificação de convite pendente + avaliação de vínculos) é reaproveitado quando o E2 autentica automaticamente o profissional ao final do auto-cadastro. Um profissional recém-cadastrado pelo próprio auto-cadastro público nunca tem convite pendente no momento em que conclui o cadastro (se tivesse, o CPF já pertenceria a um Usuario criado pelo administrador, e o E2 teria bloqueado o cadastro por CPF duplicado — RN-CIU-004) — o caso típico é 0 vínculos ativos, resultando no direcionamento a Meu Perfil com o banner MSG-I01. Um profissional convidado por uma clínica (E3), por outro lado, nunca passa pelo E2 — é direcionado para a tela de conclusão de cadastro ou para o login, e dali para a tela de aceite do vínculo, conforme RN-CIU-023 (E3).

RN-CIU-010 — Tentativas de login (parametrizável)

O sistema controla tentativas de login falhas de forma parametrizada. Os parâmetros são:

  • Quantidade de tentativas (atualmente 5) — número máximo de tentativas falhas consecutivas antes do bloqueio
  • Minutos de bloqueio (atualmente 15) — duração do bloqueio temporário em minutos

Quando o usuário atinge o limite de tentativas falhas, o sistema bloqueia novas tentativas pelo período parametrizado. A cada login bem-sucedido, o contador de tentativas é zerado. Após o bloqueio expirar, o usuário pode tentar novamente.

RN-CIU-016 — Sem validação de formato nem máscara no login

No fluxo de login, o sistema não aplica máscara visual nem validação de formato no campo de documento. O campo aceita qualquer texto digitado de forma livre — letras, números, símbolos, qualquer combinação. Isso evita dar pistas a quem está tentando acessar o sistema sobre:

  • Se o documento tem formato válido (indicando que o sistema reconhece aquele CPF)
  • Se o documento existe na base (diferenciando “formato inválido” de “credenciais incorretas”)

A única resposta para qualquer falha de login é a mensagem genérica MSG-E01 (ver Seção 2), sem distinguir a causa.

Esta regra está alinhada com a prática de segurança contra enumeração de usuários — o atacante não consegue descobrir quais CPFs estão cadastrados apenas observando o comportamento do formulário de login.

Premissas

Nenhuma premissa específica registrada além das regras transversais do guarda-chuva (Seção 5).

Dependências

Este épico não possui dependências funcionais de outros épicos — é a base do sistema. Relação com os demais épicos:

  • Paraleliza com o E2 (Auto-cadastro Público) — ambos podem ser desenvolvidos simultaneamente, pois compartilham a mesma estrutura de dados de usuário e a mesma lógica de armazenamento de senha (hash + salt).
  • É consumido pelo E2 — desde RN-CIU-022 (autenticação automática pós-auto-cadastro), o E2 invoca o mesmo processo de geração de sessão/token documentado neste épico (Seção 2, “Mecanismo de autenticação”) ao concluir o wizard.
  • É consumido pelo E3 — desde a revisão de RN-CIU-022 (guarda-chuva, v2.2), o E3 (Convite e Vínculo) também passa a depender deste épico: o campo convitesPendentes, já retornado pelo endpoint de login (Seção 2, “Integração com Backend”), é consumido pelo E3 para decidir se o roteamento pós-login deve ser desviado para a tela de aceite do vínculo, antes de aplicar o roteamento por vínculos descrito em RN-CIU-009 acima.

Requisitos SBIS Aplicáveis

NGS1.02.01 (Método de autenticação), NGS1.02.02 (Proteção dos parâmetros de autenticação), NGS1.02.03 (Qualidade da senha), NGS1.02.11 (Igualdade de senhas), NGS1.02.12 (Obtenção de nova senha), NGS1.02.13 (Controle de tentativas de login), NGS1.02.16 (Informações em autenticação inválida), NGS1.02.17 (Revelação de credenciais), ECF.17.19 (Mensagens do sistema) — todos estágio 1 (Clínica/ambulatório), obrigatórios; NGS1.02.19 (Uso de SALT) — estágio 2, recomendado. Detalhamento na Seção 2.

Metadados do Épico

AtributoValor
PrioridadeMust Have — fundação do sistema, sem este épico nenhum outro funciona
ComplexidadeMédia — fluxos bem definidos, tabelas já existem, parametrização via UsuarioSenhaParametros
DependênciasNenhuma (épico base)
Regras transversais aplicadas5 (RN-CIU-005, 006, 007, 008, 022)
Regras específicas deste épico4 (RN-CIU-001, 009, 010, 016)
Paraleliza comE2 (Auto-cadastro Público) — compartilha estrutura de dados e lógica de criptografia de senha
Consumido porE2 — reutiliza o mecanismo de autenticação e roteamento pós-login para autenticar automaticamente o profissional ao final do wizard de auto-cadastro (RN-CIU-022); E3 — consome o campo convitesPendentes do endpoint de login para desviar o roteamento para a tela de aceite do vínculo
Histórias de usuário2 (US-CIU-003, US-CIU-009)
Critérios de aceitação19
Fluxos de exceção6 (EX-E1-01 a EX-E1-06)
Endpoints4
Telas2 (Login, Recuperação de Senha em 2 etapas)
Tabelas utilizadas6 (Usuario, UsuarioSenhaHistorico, UsuarioCliente, UsuarioSenhaParametros, ClienteEmpresa, ClientePerfilAcessoUsuario) — todas existentes
Mensagens catalogadas20 (8 erros, 2 sucessos, 1 informativa, 4 placeholders, 1 texto orientador, 6 rótulos)
Requisitos SBIS atendidos9 (NGS1.02.01, 02, 03, 11, 12, 13, 16, 17, ECF.17.19) + 1 recomendado (NGS1.02.19)

Lista consolidada de itens marcados [PROPOSTA] nesta versão

  1. Consulta exata (junções entre UsuarioCliente, ClientePerfilAcessoUsuario e ClienteEmpresa) para compor a contagem de clínicas acessíveis e o campo clinicasAcessiveis da resposta do login (Seção 2 e Seção 4) — a existência da granularidade Cliente × ClienteEmpresa e a regra de que o administrador escolhe clínicas específicas foram confirmadas pelo solicitante; a forma exata da consulta e do payload é proposta deste documento.

Histórico de Versões

  • v1.0 a v1.9 (07/08/2026 a 27/08/2026) — histórico completo preservado no documento original legado (CIU-E1) Identidade e autenticação v1.9.md, arquivado em Histórico/. Resumo da v1.9: corrigida a definição de “vínculo ativo” (RN-CIU-009) para exigir Situacao = ‘V’, não apenas RemovidoEm nulo — consequência da adoção do domínio C/V/B no campo Situacao de UsuarioCliente, definido em (CIU-E3) v2.0.
  • v2.1 (14/09/2026) — corrigida a RN-CIU-009: o roteamento pós-login (cockpit direto vs. seleção de clínica) decidia pela quantidade de vínculos ativos (registros em UsuarioCliente); a contagem correta é a de clínicas (ClienteEmpresa) acessíveis, já que um único vínculo pode compreender mais de uma ClienteEmpresa (filiais de uma mesma rede, ou clínicas de um conglomerado sem dados compartilhados) — achado ao consultar a Biblioteca de Schema (DDL) a pedido do solicitante, que confirmou a granularidade e a regra de o administrador escolher clínicas específicas por vínculo (RN-CIU-011, em CIU-E3). Consequência da mesma correção no E3 (v3.2) e no E6 (v1.1). Adicionada a definição de “clínica acessível” e a lista consolidada de itens [PROPOSTA].
  • v2.0 (30/08/2026) — Reconstruído integralmente no modelo padrão Seção 1-4 da Skill Designer, a pedido do solicitante (“recrie CIU-E1 e CIU-E2 no novo formato”) — deixa de ser legado (estrutura própria de 12 itens). Mesmo tratamento já aplicado ao E3 (v2.1 → v3.0) e ao E6 (construído desde a origem no modelo novo). Todo o conteúdo da v1.9 tem lugar no novo formato — nenhuma informação omitida, apenas reorganizada: Seção 1 (Visão Geral + Regras de Negócio + Dependências/Paralelização do documento legado) → 01-Definição; Seção 2 (Histórias, Descrição Funcional, Critérios de Aceitação, Fluxos de Exceção, Validações, Componentes, Backend, Mensagens, SBIS) → 02-Especificação; Seção 3 (Protótipo HTML) segue pendente, como já estava na v1.9 (nunca foi produzida); Mapeamento de Tabelas (antes Seção 9.3, sem detalhamento de migrations/seeders) → 04-Mapeamento de Banco de Dados, agora com a subseção “Seeds da Funcionalidade” (Lição #19 da Skill Designer) — nenhum seed novo proposto por este épico. Numeração de Fluxos de Exceção corrigida de “EX-E1.0X” (com ponto) para “EX-E1-0X” (com hífen), alinhando à convenção já usada pelos demais épicos (EX-E3-XX, EX-E6-XX) e registrada na Seção “Numeração” do guarda-chuva.

Visão de gráfico

Backlinks