Documentação

Personas

• Profissional — enfermeiro/médico/etc. que se cadastra, é aprovado, aceita plantões, faz check-in/out e recebe o repasse.
• Gestor do hospital — contrata a assinatura, cadastra cartão, publica pedidos de plantão, acompanha os profissionais e a parte financeira/fiscal.
• (Admin da plataforma é fora deste backlog — painel administrativo à parte.)

Convenções

• IDs locais (E# épico, E#-H# história) só para referência neste doc — o Jira gera os dele.
• Estimativa em story points (Fibonacci) é sugestão — refinar com o time.
• Toda história assume o padrão de resposta da API, Bearer token (Sanctum) e mensagens em PT-BR. O backend (API REST + WebSocket) já está implementado.

Definition of Ready (resumo)

Critérios de aceitação claros · endpoints/eventos mapeados · design/fluxo definido · sem dependência bloqueante aberta.

Definition of Done (resumo)

Critérios de aceitação atendidos · responsivo · estados de erro/carregamento/vazio tratados · testado em dispositivo real (app) · texto em PT-BR · telemetria básica (se aplicável).

E1 — Autenticação e conta · cross-cutting

Objetivo: entrar com segurança e manter a sessão.

E1-H1 — Cadastro do profissional 3

Como visitante,
quero criar conta com nome, e-mail, telefone e senha,
para começar o onboarding.

• validação de senha (mín. 8 caracteres).
• e-mail duplicado → erro amigável (não cria conta).
• ao concluir já entra logado (token) e cai no onboarding (E2).

Técnico: POST /auth/register.

E1-H2 — Login 2

Como profissional,
quero entrar com e-mail e senha,
para acessar minha conta.

• credenciais inválidas → mensagem genérica (sem revelar se o e-mail existe).
• conta bloqueada/suspensa → mensagem clara, sem acesso.
• token persistido com segurança (Keychain/Keystore); reabrir o app mantém a sessão.

Técnico: POST /auth/login; bootstrap GET /auth/me.

E1-H3 — Recuperação de senha 2

Como quem esqueceu a senha,
quero pedir recuperação por e-mail,
para voltar a acessar.

• sempre a mesma mensagem de sucesso (anti-enumeração).
• o link abre a página web de redefinição.

Técnico: POST /auth/send-recovery-email.

E1-H4 — Trocar senha logado 1

Como profissional logado,
quero trocar minha senha informando a atual,
para manter a conta segura.

Técnico: POST /auth/change-password.

E1-H5 — Logout 1

Como profissional,
quero sair da conta,
para proteger meu acesso no dispositivo.

• revoga o token no servidor e volta ao login.

Técnico: POST /auth/logout.

E1-H6 — 2FA (TOTP) 3

Como profissional,
quero ativar verificação em duas etapas,
para proteger meus recebimentos.

• ativar gera QR/secret; confirmar com código.
• no login com 2FA ativo, exige o desafio; posso desativar.

Técnico: POST /2fa/enable · POST /2fa/confirm · POST /2fa/challenge · DELETE /2fa.

E2 — Onboarding & habilitação · aba Perfil (com gating)

Objetivo: completar tudo que é pré-requisito para aceitar plantão pago: aprovação do cadastro, categorias, conselho, documentos, dados fiscais (CNPJ) e subconta de recebimento aprovada.

E2-H1 — Status de habilitação (checklist) 3

Como profissional novo,
quero ver o que falta para ficar apto,
para ser aprovado e poder aceitar.

• checklist com cadastro (aprovação), categorias, conselho, documentos, dados fiscais e subconta.
• cada item linka para a tela de resolução.
• enquanto não apto, a aba Plantões mostra estado bloqueado explicando o motivo.

Técnico: GET /auth/me (status/approval_status); agrega os recursos abaixo.

E2-H2 — Escolher categorias de atuação 3

Como profissional,
quero marcar minhas categorias (ex.: "Enfermeiro Pleno"),
para receber só plantões compatíveis.

• lista as categorias ativas (especialidade + nível); seleção múltipla.
• só vejo/aceito plantões das minhas categorias.

Técnico: GET /categories · PUT /me/categories.

E2-H3 — Inscrições em conselho 2

Como profissional,
quero cadastrar meus registros de conselho (COREN, CRM…),
para comprovar minha habilitação profissional.

• adicionar conselho + nº de registro + UF; listar; remover.

Técnico: GET /councils · GET/POST /me/councils · DELETE /me/councils/{id}.

E2-H4 — Envio de documentos 3

Como profissional,
quero enviar carteira do conselho e demais documentos,
para análise do admin.

• upload (foto/PDF) com validade; ver status (pendente/aprovado/reprovado); reenviar; remover.

Técnico: GET/POST /me/documents · DELETE /me/documents/{id}.

E2-H5 — Dados fiscais (emissão de NF) 5

Como profissional,
quero cadastrar meu CNPJ e dados fiscais,
para que minha NF seja emitida e eu receba.

• CNPJ obrigatório (MEI/PJ) — RPA não suportado.
• campos IM, regime, município, item de serviço (ISS).
• upload do certificado A1 (.pfx) + senha (armazenada criptografada); editável (trocar CNPJ/certificado).
• explica que sem isso não recebe.

Técnico: GET /me/tax-profile · PUT /me/tax-profile (multipart com certificate).

E2-H6 — Conta de recebimento (subconta) 3

Como profissional,
quero cadastrar meus dados bancários/recebimento,
para ter a subconta aprovada (KYC).

• dados bancários/PIX; ver status da subconta (pendente/aprovado).
• aviso de que a aprovação é pré-requisito para aceitar plantão pago.

Técnico: GET/PUT /bank-accounts (subconta criada no gateway; status via paymentRecipient).

E3 — Aba Plantões (oportunidades)

Objetivo: ver oportunidades compatíveis e aceitar — com a regra "os primeiros a aceitar preenchem".

E3-H1 — Feed de plantões disponíveis 5

Como profissional apto,
quero ver os plantões abertos das minhas categorias,
para escolher um para aceitar.

• lista os plantões pending compatíveis (categoria + raio, se configurado).
• cada card mostra hospital, data/horário, categoria, valor e distância.
• pull-to-refresh; estado vazio amigável.

Técnico: GET /shifts.

E3-H2 — Detalhe do plantão 3

Como profissional,
quero abrir o plantão e ver todos os dados,
para decidir com segurança.

• comissão e líquido visíveis ANTES de aceitar (MEI/PJ).
• local no mapa; janela de aceite (timer).

Técnico: GET /shifts/{id}.

E3-H3 — Aceitar plantão (pré-autorização) 5

Como profissional,
quero aceitar a vaga,
para garantir o plantão.

• ao aceitar, a vaga é reservada (pré-autorização no cartão do hospital, com split).
• se outro aceitou primeiro → mensagem "vaga não disponível".
• se a pré-autorização falhar (assíncrona) a vaga reabre e sou avisado.
• bloqueia aceite se cadastro/subconta não aprovados ou categoria incompatível.

Técnico: POST /shifts/{id}/accept (dispara job de pré-auth + split).

E4 — Aba Agenda (meus plantões + presença)

Objetivo: acompanhar os plantões aceitos e registrar presença (check-in/out) com geolocalização e selfie.

E4-H1 — Meus plantões (próximos) 3

Como profissional,
quero ver meus plantões aceitos e em andamento,
para me organizar.

• ordenados por data; status (aceito, em atendimento, finalizado); ação contextual (check-in/out).

Técnico: GET /shifts/history · GET /shifts/{id}.

E4-H2 — Check-in (geo + selfie) 5

Como profissional no local,
quero fazer check-in,
para iniciar o plantão.

• captura GPS + selfie.
• se fora do raio → recusa com a distância e orientação (o evento é registrado).
• tentativas repetidas fora do raio podem bloquear a conta (aviso).
• sucesso muda o status para "em atendimento".

Técnico: POST /shifts/{id}/check-in (multipart selfie); raio validado server-side.

E4-H3 — Check-out 3

Como profissional ao fim do plantão,
quero fazer check-out,
para encerrar e disparar meu pagamento.

• check-out com GPS; dispara a captura do pagamento.
• mostra confirmação e quando o repasse deve cair.

Técnico: POST /shifts/{id}/check-out.

E4-H4 — Histórico de plantões 2

Como profissional,
quero ver meus plantões passados,
para conferir o que trabalhei.

• status final (concluído/cancelado/no-show) e valor; filtro por período.

Técnico: GET /shifts/history · GET /reports/shifts.

E4-H5 — Ping de localização em campo 3

Como profissional a caminho/em campo,
quero que minha posição apareça pro hospital,
para transparência.

• envia a posição a cada ~15s enquanto houver plantão ativo (com consentimento de localização).
• o hospital vê no mapa ao vivo (REST, poll 5s — sem WebSocket por ora).

Técnico: POST /me/location { lat, lng } (consumido por GET /hospital/live-map).

E5 — Aba Carteira (recebimentos)

Objetivo: ver saldo, repasses e comprovantes; gerir dados de recebimento.

E5-H1 — Saldo da carteira 3

Como profissional,
quero ver meu saldo disponível, bloqueado e total,
para acompanhar meus recebimentos.

• explica que o valor fica bloqueado após o check-out e libera no repasse (split + antecipação ~D+2).

Técnico: GET /wallet.

E5-H2 — Lista de repasses 3

Como profissional,
quero ver meus repasses com status e valores,
para conferir cada pagamento.

• valor líquido, comissão, status (processando/pago) e data; abre detalhe.

Técnico: GET /payouts · GET /payouts/{id}.

E5-H3 — Comprovante (PDF) 2

Como profissional,
quero baixar o comprovante do repasse,
para minha contabilidade.

Técnico: GET /payouts/{id}/receipt.

E5-H4 — Dados bancários / PIX 2

Como profissional,
quero cadastrar/editar minha chave PIX e dados bancários,
para receber na conta certa.

Técnico: GET/PUT /bank-accounts.

E6 — Aba Perfil (cadastro & ajustes)

Objetivo: manter dados, preferências de trabalho e segurança.

E6-H1 — Editar perfil 2

Como profissional,
quero editar meus dados pessoais,
para mantê-los atualizados.

Técnico: PUT /me.

E6-H2 — Disponibilidade (agenda semanal) 3

Como profissional,
quero definir meus horários disponíveis,
para receber plantões compatíveis.

• grade por dia da semana com faixas de horário; validação de horário.

Técnico: GET/PUT /me/availability.

E6-H3 — Raio máximo de atuação 2

Como profissional,
quero definir a distância máxima (km),
para filtrar as oportunidades que recebo.

Técnico: PUT /me/max-distance.

E6-H4 — Perfil público & avaliações 2

Como profissional,
quero ver como o hospital me vê (nome, nota média, conselhos) e minhas avaliações,
para cuidar da minha reputação.

Técnico: GET /me/public-profile · GET /ratings.

E6-H5 — Atalhos para onboarding e segurança 1

Como profissional,
quero acessar categorias, conselhos, documentos, dados fiscais e 2FA a partir do Perfil,
para resolver pendências sem procurar.

E7 — Notificações & dispositivos · cross-cutting (cabeçalho)

Objetivo: avisar de novas oportunidades e eventos, mesmo com o app fechado.

E7-H1 — Registrar dispositivo (push) 3

Como sistema,
quero registrar o token de push no login e removê-lo no logout,
para entregar notificações ao dispositivo certo.

Técnico: POST /me/devices · DELETE /me/devices/{id}.

E7-H2 — Central de notificações 3

Como profissional,
quero uma central com minhas notificações,
para não perder nada importante.

• sino com badge; lista (novo plantão, status, repasse); marcar como lida; tocar leva à tela relevante.

Técnico: GET /notifications · POST /notifications/{id}/read.

E7-H3 — Aviso de nova oportunidade 2

Como profissional,
quero receber push quando surgir plantão compatível,
para aceitar antes dos outros.

• tocar abre o detalhe (reforço por WhatsApp/ligação é responsabilidade do backend).

Técnico: notificação order_published (push).

E8 — Relatórios do profissional · aba Carteira/Perfil

E8-H1 — Meus ganhos 3

Como profissional,
quero ver o total recebido por período, ticket médio e nº de plantões,
para acompanhar minha renda.

Técnico: GET /reports/earnings.

E8-H2 — Relatório de plantões 2

Como profissional,
quero um relatório dos meus plantões por período,
para ter histórico consolidado.

Técnico: GET /reports/shifts.

E9 — Cross-cutting (navegação, estados, segurança)

E9-H1 — Tab bar + retomar fluxo 3

• tab bar persistente; ao reabrir, retomo onde parei (plantão em andamento → Agenda; pré-auth pendente → aviso).
• deep links abrem a aba/tela certa.

E9-H2 — Conta bloqueada/suspensa 2

• conta bloqueada (ex.: check-ins fora do raio repetidos) → tela explicando, sem acesso às ações; tokens revogados derrubam a sessão.

E9-H3 — Estados de erro/carregamento/offline 3

• padrões de loading/skeleton, erro com retry, vazio; degradação offline básica.

E9-H4 — Telemetria & consentimentos 2

• consentimento de localização/câmera (selfie); LGPD; eventos básicos de uso.

E1 — Conta & acesso do hospital

Objetivo: criar o hospital, entrar e gerir o acesso com segurança.

E1-H1 — Cadastro do hospital + 1º gestor 5

Como novo hospital,
quero me cadastrar (dados da empresa + 1º usuário gestor),
para começar a usar a plataforma.

• dados do hospital (razão social, CNPJ, endereço) + admin (nome, e-mail, senha).
• CNPJ/e-mail duplicado → erro.
• ao concluir, entra logado e vai para o gate de assinatura (E2).

Técnico: POST /hospital/auth/register.

E1-H2 — Login / Logout 2

Como gestor,
quero entrar e sair da conta com segurança,
para operar o painel.

Técnico: POST /auth/login · GET /auth/me · POST /auth/logout.

E1-H3 — Recuperação / troca de senha 2

Como gestor,
quero recuperar ou trocar minha senha,
para não perder o acesso.

Técnico: POST /auth/send-recovery-email · POST /auth/change-password.

E1-H4 — 2FA (TOTP) 3

Como gestor,
quero ativar a verificação em duas etapas,
para proteger uma conta que movimenta pagamentos.

• ativar/confirmar/desafio/desativar.

Técnico: POST /2fa/enable|confirm|challenge · DELETE /2fa.

E2 — Assinatura & cartão (gate de uso)

Objetivo: o hospital só publica pedidos com assinatura ativa + cartão válido. A cobrança mensal é recorrente no gateway.

E2-H1 — Cadastrar cartão (tokenizado) 5

Como gestor,
quero cadastrar o cartão de crédito,
para assinar e pagar os plantões.

• cartão tokenizado uma vez (reuso nas pré-autorizações); mostra bandeira + últimos 4.
• listar e remover cartões.

Técnico: GET/POST /hospital/cards · DELETE /hospital/cards/{id}.

E2-H2 — Assinar plano 3

Como gestor,
quero assinar o plano mensal,
para liberar o uso da plataforma.

• escolher plano + cartão; cria assinatura recorrente no gateway; status fica ativo.

Técnico: POST /hospital/subscription/subscribe.

E2-H3 — Ver assinatura / status 2

Como gestor,
quero ver plano, status e próxima cobrança,
para acompanhar minha assinatura.

• status ativa / em atraso / cancelada; em atraso (dunning) → aviso e gate para novas publicações.

Técnico: GET /hospital/subscription.

E2-H4 — Cancelar assinatura 2

Como gestor,
quero cancelar a assinatura,
para encerrar o uso sem surpresas.

• cancela a recorrência no gateway; plantões em andamento não são afetados; novas publicações bloqueadas.

Técnico: POST /hospital/subscription/cancel.

E3 — Publicação de pedidos (demanda)

Objetivo: publicar a demanda com um ou mais perfis e quantidades; cada vaga gera um plantão independente.

E3-H1 — Criar pedido multi-perfil 8

Como gestor,
quero publicar um pedido com perfis e quantidades (ex.: 5 Enfermeiros Pleno + 3 Médicos Sênior), data/hora e local,
para preencher meus plantões.

• exige assinatura ativa + cartão; bloqueia publicação sem eles.
• adiciona N itens (categoria × quantidade); mostra valor por vaga, total a reservar e comissão discriminada.
• ao publicar, gera as vagas (pending) e notifica os profissionais.

Técnico: POST /hospital/orders (itens: professional_category_id, service_type_id, quantity; opcional cost_center_id).

E3-H2 — Listar/abrir pedidos 3

Como gestor,
quero ver meus pedidos e abrir cada um,
para acompanhar o preenchimento.

• lista com total, nº de vagas, preenchidas/total e status (aberto/preenchido/cancelado).
• detalhe mostra os itens (perfis) e os plantões gerados.

Técnico: GET /hospital/orders · GET /hospital/orders/{id}.

E3-H3 — Cancelar pedido 3

Como gestor,
quero cancelar um pedido,
para desistir de vagas que não preciso mais.

• anula as vagas pendentes (libera as reservas); vagas já aceitas seguem sua regra.

Técnico: POST /hospital/orders/{id}/cancel.

E4 — Plantões / vagas

Objetivo: acompanhar e gerir cada vaga (plantão) gerada.

E4-H1 — Lista de plantões 3

Como gestor,
quero ver as vagas com profissional, status, data e valor,
para acompanhar a operação.

• filtros por status/período.

Técnico: GET /hospital/shifts · GET /hospital/shifts/{id}.

E4-H2 — Cancelar uma vaga 2

Como gestor,
quero cancelar uma vaga específica,
para ajustar a demanda.

• void da pré-autorização se a vaga estava reservada.

Técnico: POST /hospital/shifts/{id}/cancel.

E4-H3 — Avaliar o profissional 3

Como gestor,
quero avaliar o profissional após o plantão,
para alimentar a reputação.

• nota + comentário, disponível após o check-out/conclusão.

Técnico: POST /hospital/shifts/{id}/rate.

E5 — Mapa ao vivo (REST polling)

Objetivo: acompanhar quem está em campo e a posição dos profissionais. Decisão atual: via REST (polling ~5s), não WebSocket — evolução futura já contratada no backend.

E5-H1 — Mapa ao vivo (posição + status) 5

Como gestor,
quero ver num mapa os profissionais com plantão ativo e a posição deles,
para monitorar o andamento.

• consulta a cada ~5s; mostra profissional, status (aceito / em atendimento), categoria e última posição.
• posição stale (> 2 min) é sinalizada.
• isolado por tenant (só os plantões do hospital).

Técnico: GET /hospital/live-map (poll 5s). Futuro (Reverb): canal hospital.{id} com OrderAccepted, CheckInRegistered, ProfessionalLocationUpdated.

E6 — Financeiro & fiscal

Objetivo: transparência de custos, comissão e notas fiscais.

E6-H1 — Custo por plantão (discriminado) 3

Como gestor,
quero ver por plantão o valor, a comissão e o líquido ao profissional,
para entender exatamente o que pago.

• status do pagamento (pré-autorizado/capturado/estornado).

Técnico: GET /hospital/shifts/{id} · GET /hospital/reports.

E6-H2 — NFs por plantão 3

Como gestor,
quero as notas fiscais de cada plantão,
para a contabilidade do hospital.

• lista as NFs (profissional + plataforma) por plantão; download de PDF/XML; status de emissão.
• NF é sempre 1 por plantão — não há documento fiscal consolidado.

Técnico: GET /hospital/reports (webhook de NF mantém o status atualizado).

E6-H3 — Relatório mensal consolidado 3

Como gestor,
quero um resumo do mês com a soma do que contratei,
para controlar o gasto.

• total de plantões, valor total, comissão, líquido e quebra por categoria no mês escolhido.
• substitui a "fatura consolidada" — sem documento fiscal único.

Técnico: GET /hospital/reports/monthly?month=YYYY-MM.

E7 — Dashboard & relatórios

E7-H1 — Dashboard 3

Como gestor,
quero uma visão geral do dia,
para agir rápido no que importa.

• plantões abertos/preenchidos, gasto no período, vagas pendentes, alertas.

Técnico: GET /hospital/ — KPIs (shifts_today, open_vacancies, in_attendance, month_cost_cents), upcoming_shifts e alerts (unaccepted_overdue, checkin_late).

E7-H2 — Relatórios 3

Como gestor,
quero relatórios operacionais/financeiros por período,
para analisar e exportar.

Técnico: GET /hospital/reports.

E8 — Centros de custo

Objetivo: organizar os gastos por centro de custo (nome livre — setor/unidade).

E8-H1 — Gerenciar centros de custo (CRUD) 3

Como gestor,
quero criar, editar, ativar e remover centros de custo,
para organizar meus pedidos e gastos.

Técnico: GET/POST /hospital/cost-centers · PUT/DELETE /hospital/cost-centers/{id}.

E8-H2 — Vincular centro de custo ao pedido 2

Como gestor,
quero escolher o centro de custo ao publicar (opcional),
para rastrear o gasto por setor.

Técnico: POST /hospital/orders (campo cost_center_id).

E9 — Usuários internos

E9-H1 — Gerenciar usuários do hospital 3

Como gestor,
quero adicionar/remover outros gestores,
para a equipe operar a conta.

• listar, criar (nome/e-mail/senha) e remover; não pode remover a si mesmo.
• todos com acesso total (sem níveis — RBAC descopado).

Técnico: GET/POST /hospital/users · DELETE /hospital/users/{id}.

E10 — Favoritar / Bloquear profissional

E10-H1 — Favoritar / bloquear 3

Como gestor,
quero favoritar ou bloquear um profissional,
para priorizar ou impedir quem atende meus plantões.

• marcar favorite/blocked; remover relação.
• bloqueado não é notificado nem consegue aceitar plantões deste hospital.

Técnico: GET /hospital/professionals · POST /hospital/professionals/{id}/relation · DELETE /hospital/professionals/{id}/relation.

E11 — Conta & configurações

E11-H1 — Editar perfil do gestor 1

Como gestor,
quero editar meus dados,
para mantê-los atualizados.

Técnico: PUT /me.

E12 — Cross-cutting

E12-H1 — Gate de assinatura em toda ação de publicação 2

• sem assinatura ativa/cartão → CTA para resolver antes de publicar.

E12-H2 — Estados de erro/carregando/vazio 2

• padrões consistentes de loading, erro com retry e vazio em todas as listagens.

E12-H3 — Isolamento por tenant 2

• o hospital só vê seus próprios dados/eventos (garantido server-side).

Notas para o PO

• Dependências externas: pré-autorização, captura, split e NFs dependem do gateway de pagamento (webhooks). Os apps reagem ao status; não há "marcar como pago" manual.
• Regras de negócio centrais (servidor): "primeiro a aceitar leva"; check-in validado por raio (150 m) + selfie; check-out dispara captura + emissão de NF; repasse com antecipação ~D+2; comissão da plataforma discriminada.
• Decisões registradas: NF sempre 1 por plantão (sem consolidada) · mapa ao vivo via REST polling (WebSocket é evolução futura) · RBAC granular descopado (usuários do hospital têm acesso total) · RPA não suportado (profissional recebe via CNPJ).
• Stack do painel: shadcn/ui (React + Tailwind + Radix) com o tema ZyronCare — badge padrão na variante outline, botões primários petróleo em pílula, listagens com Tabs.
• Fora do escopo: painel administrativo da plataforma e qualquer módulo não previsto → alteração de escopo.