Spec — Comercial no App Gestão: alunos, contratos e vendas rápidas

Status: planejada, sem ciclo de implementação iniciado.
Data: 2026-10-08.
Escopo: extensão independente da spec principal do App Gestão.
Repositórios envolvidos: painel/API PHP e aplicativo Flutter cfcprodutivogestao-2026.

Esta spec amplia o papel Gestor com três fluxos comerciais separados:

1. cadastro de aluno;
2. criação de contrato;
3. venda rápida baseada nas Ações rápidas já configuradas pelo CFC no painel.

Ela não reabre nem altera o percentual histórico de conclusão da spec-app-gestao-telas.md. O escopo original permanece concluído; esta é uma frente nova, com cronograma, histórico e percentual próprios.

1. Decisão de vocabulário

Há dois conceitos que receberam o mesmo nome em momentos diferentes. A partir desta spec, eles ficam separados de modo obrigatório:

Nos textos do app, a chamada de ação será Nova venda ou Venda rápida. O termo Ação rápida aparece apenas para identificar a configuração escolhida na venda.

2. Referências e fatos verificados

2.1 Consequência arquitetural

O app reutiliza as classes de domínio, mas não chama nem espelha os AJAXs do painel. O AJAX atual de movimentação dinâmica depende da sessão web e aceita campos financeiros enviados pelo formulário. A API mobile deve construir no servidor o comando seguro e entregar à classe canônica apenas valores já validados.

3. Objetivo e resultado esperado

O gestor deve conseguir, pelo app e dentro do seu próprio CFC:

• cadastrar um novo aluno;
• registrar, quando necessário, os dados complementares do mesmo formulário de aluno já existente no painel;
• iniciar, com esse aluno ou com um aluno já existente, uma venda rápida configurada previamente no painel;
• criar um contrato pelo fluxo próprio de contratos;
• solicitar a assinatura do aluno quando a configuração do CFC permitir e acompanhar o respectivo status;
• localizar os contratos de um aluno por nome, CPF ou RENACH;
• visualizar confirmação clara do que foi criado, sem precisar abrir o painel para conferir os efeitos iniciais.

Cada fluxo produz um resultado diferente e não deve acionar os demais de forma implícita.

4. Escopo e exclusões

4.1 Incluído

• Gestor puro e gestor de usuário com duplo papel, quando a capacidade estiver presente.
• Cadastro mínimo de aluno, com CPF validado no servidor.
• Busca e seleção de aluno no contexto comercial.
• Consulta e execução de Ações rápidas ativas do CFC.
• Criação de contratos pelo caminho canônico já utilizado pelo painel, delimitada pelos recursos que o backend conseguir expor com segurança.
• Rastro de usuário, tenant, horário, operação e identificador de repetição.
• Estados de carregamento, vazio, erro, indisponibilidade e confirmação para cada fluxo.
• DDLs versionados, idempotentes e documentados quando realmente necessários.

4.2 Fora do escopo desta etapa

• Edição, exclusão, estorno ou cancelamento de aluno, contrato ou venda pelo app.
• Mudança de preço, desconto, conta, categoria financeira ou unidade de custo de uma Ação rápida pelo app.
• Transformar uma Ação rápida em carrinho genérico de múltiplos itens.
• Assinar, aprovar, rejeitar, reenviar ou cancelar a assinatura pelo app. O app apenas pode solicitar a pendência no ato do contrato e consultar seu status.
• Impressão, envio manual do contrato ou upload documental dentro do fluxo inicial de contrato.
• Processar ou acionar CFC Pay/ND7 no primeiro recorte mobile.
• Mudanças nos cadastros/configurações de Ações rápidas, serviços, modelos de contrato ou permissões pelo aplicativo; isso continua no painel.
• Alterar o app do aluno, o app gêmeo ou consumidores externos da API.

5. Regras transversais e invariantes

5.1 Tenant, sessão e autorização

1. clientes_id e usuarios_id são derivados somente do token de usuário já validado pela API. O aplicativo não envia nem escolhe esses identificadores.
2. Todo aluno, ação, serviço, conta, forma de pagamento e contrato consultado deve pertencer ao mesmo CFC do token.
3. Capacidade ausente remove o ponto de entrada e também é revalidada no endpoint. Ocultar um botão nunca é a única proteção.
4. O contrato de capacidades de login/refresh ganha apenas chaves aditivas; clientes antigos continuam entendendo seu payload atual.

5.2 Fonte de verdade comercial

1. O painel é a única origem das configurações de serviços, Ações rápidas, categorias financeiras, contas e modelos de contrato.
2. O servidor recarrega essas configurações imediatamente antes da escrita. Dados exibidos pelo app nunca autorizam uma gravação por si só.
3. Valores monetários enviados pelo aplicativo são tratados como intenção de interface, não como autoridade comercial. Onde esta spec definir valor fixo, o servidor ignora qualquer tentativa de sobrescrevê-lo.
4. A API retorna JSON UTF-8 normalizado. Nenhuma tela mobile recebe fragmento HTML, htmlentities ou links do painel dentro de mensagens de domínio.

5.3 Escritas seguras

1. Toda escrita recebe uma chave de idempotência aleatória, persistida no dispositivo até obter resposta conclusiva.
2. A chave é única por CFC, usuário, tipo de operação e intenção de escrita. Repetir a mesma requisição devolve o resultado original; não duplica crédito, contrato, parcela ou movimentação.
3. A camada adaptadora registra o usuário autenticado nas classes canônicas e nos registros financeiros/históricos resultantes.
4. O ciclo de escrita deve comprovar atomicidade usando a mesma conexão de banco. Se uma classe legada impedir transação abrangente, o ciclo é bloqueado até haver adaptação segura ou reconciliação explicitamente aprovada; nunca se aceita sucesso parcial silencioso.
5. Falhas retornam mensagem comum ao app e detalhe técnico apenas ao log local de diagnóstico.

5.4 Permissões propostas

Serão criadas ações próprias, com IDs definidos somente no preflight da migration, sem números arbitrários nesta spec:

As permissões existentes de desconto em contratos ou Ações rápidas não serão habilitadas pelo app nesta versão: preço e rota financeira permanecem travados na configuração de origem.

6. Fluxo A — Cadastro de aluno

6.1 Objetivo

Cadastrar a identidade mínima de um aluno sem inferir venda, crédito ou contrato. O gestor também pode completar, na mesma jornada, os dados adicionais já aceitos pelo cadastro do painel. O resultado é um aluno disponível para os fluxos seguintes, sem criar dois cadastros ou duas regras de validação.

6.2 Entrada e navegação

• Entrada primária: Atalhos do Painel → Novo aluno.
• Entrada secundária: busca de aluno sem resultado → Cadastrar aluno.
• Após sucesso, a tela de confirmação oferece:
• Ver aluno;
• Fazer venda rápida;
• Criar contrato;
• Concluir.

Nenhuma dessas ações seguintes é automática.

6.3 Tela e campos

A tela usa o padrão visual de formulário do protótipo: cabeçalho institucional, faixa laranja, campos com rótulo acima e botão primário fixo no rodapé.

O contrato de API de cadastro deve expor metadados de campo — rótulo, tipo, obrigatoriedade, opções e grupo rápido/avançado — derivados da mesma configuração e validação canônicas do painel. A submissão é única: ela aceita somente campos oferecidos pelo preflight e grava tudo pela classe de aluno existente. Não será inventado um segundo conjunto de regras no Flutter.

6.4 Regras e mensagens

• CPF inválido: “Informe um CPF válido.”
• CPF já cadastrado neste CFC: “Já existe um aluno com este CPF neste CFC.”
• Campo avançado inválido: o app aponta o campo e preserva todo o restante do formulário, sem descartar o cadastro rápido já preenchido.
• Erro de rede: preserva o formulário e oferece Tentar novamente.
• Sem permissão: o atalho não aparece e o endpoint responde sem vazar dados.
• Sucesso: “Aluno cadastrado. Agora você pode iniciar uma venda ou contrato.”

7. Fluxo B — Venda rápida por Ação rápida

7.1 Conceito

Venda rápida é a execução de uma configuração ativa de clientes_financeiro_movimentacao_dinamica para um aluno existente. Ela cria uma movimentação dinâmica, inclui o serviço escolhido, credita o aluno e cria o efeito financeiro correspondente.

Não cria registro de contrato, não gera assinatura e não representa uma versão abreviada de contrato.

7.2 Semântica inicial preservada

Uma Ação rápida pode relacionar mais de um serviço. A tela atual do painel permite escolher um serviço dentre os serviços dessa ação antes de concluir a operação. A primeira versão do app preserva exatamente isso:

• uma confirmação executa um serviço elegível da Ação rápida;
• a ação continua sendo o limitador de quais serviços podem ser vendidos;
• o aplicativo não transforma, por conta própria, todos os serviços de uma ação em uma venda conjunta.

Uma futura “venda de pacote indivisível” exigirá spec própria, pois mudaria créditos, preço, financeiro, reversão e auditoria em comparação ao painel.

7.3 Jornada mobile

Aluno → Ação rápida → Serviço e quantidade → Condições → Conferência → Sucesso

7.4 Campos que o app pode e não pode editar

7.5 CFC Pay e integrações externas

Se a forma de pagamento selecionada exigir integração CFC Pay/ND7, a ação não fica concluível no primeiro recorte. A tela explica:

“Esta forma de pagamento deve ser concluída pelo painel neste momento.”

O motivo é evitar uma venda que entregue créditos antes de a integração externa ter seu resultado confirmado. A operação presencial, paga ou pendente, segue disponível nas formas já suportadas pelo domínio local.

7.6 Contrato da API proposto

Os nomes de rota serão confirmados no ciclo de fundação segundo o roteador existente. Para a spec, o contrato lógico é:

O endpoint de confirmação deve ignorar ou rejeitar campos de valor, conta, categoria e unidade de custo enviados pelo cliente quando divergirem da ação recarregada no servidor.

8. Fluxo C — Contratos

8.1 Objetivo

O contrato continua sendo a contratação completa do aluno. Ele utiliza o domínio existente de contrato para gerar serviços, categorias, créditos, parcelas e movimentação financeira com documento do tipo contrato.

8.2 Jornada prevista

Aluno → Configuração comercial → Cobrança → Assinatura → Conferência → Sucesso

8.3 Limites iniciais

• A tela não expõe desconto manual, valor livre ou edição de serviço fora das combinações que o painel já reconhece.
• Se a configuração de assinatura estiver ativa (status = 1), o app oferece a flag Exigir assinatura do aluno. Ela é enviada somente como intenção e é reconfirmada pelo backend com leitura da configuração ativa; a criação usa criarPendenciaAssinatura no domínio canônico. Se a configuração não estiver ativa, a opção não aparece.
• O app não coleta assinatura, não abre assinatura embutida e não altera os status. Ele apenas exibe Assinatura não exigida, Pendente, Assinado, Aprovado, Rejeitado ou Cancelado de acordo com a fonte canônica.
• Emissão documental, impressão e cobrança integrada continuam fora deste primeiro fluxo.
• O ciclo de fundação deve inventariar os campos de contrato obrigatórios e as possibilidades realmente suportadas pelo domínio. Caso o painel não disponha de modelo/configuração suficiente para uma seleção segura, o ponto de entrada de contrato fica indisponível até o requisito ser formalizado.

8.4 Prevenção de duplicidade

Além da chave de idempotência, a API preserva a regra canônica de intervalo para novos contratos do mesmo aluno. A resposta ao app deve explicar em termos operacionais que existe um contrato recente, sem expor dados de outro usuário ou CFC.

8.5 Busca e acompanhamento de contratos

A entrada Contratos começa por uma busca de aluno reutilizável. O gestor pode pesquisar por nome, CPF ou RENACH, com normalização de acentos e números compatível com os seletores já existentes do App Gestão. Cada resultado é restrito ao CFC do token e apresenta nome, CPF formatado e RENACH quando houver.

Depois da seleção, a tela exibe os contratos daquele aluno em ordem decrescente, com: número/data, resumo de serviços, total, situação financeira/documental canônica e situação de assinatura. Um contrato sem registro de assinatura mostra Assinatura não exigida; o app não oferece ações de assinatura nessa lista.

As ações disponíveis são Novo contrato e Ver resumo. Reenvio, aprovação, cancelamento, impressão e edição continuam no painel. A API deve buscar os contratos e as pendências de assinatura em lote, evitando consulta adicional por card quando a lista tiver vários itens.

9. Navegação e apresentação visual

9.1 Pontos de entrada

O Painel ganha uma seção nomeada Operação comercial, distinta dos Atalhos do Painel já existentes. Ela só aparece quando existir ao menos uma capacidade comercial.

Quando houver pouco espaço, a seção abre uma folha inferior “Operação comercial”, sem reusar o rótulo Ações rápidas para os atalhos.

9.2 Componentes

Os três fluxos reutilizam os componentes já consolidados no app:

• cabeçalho institucional em duas faixas;
• seletor com busca de aluno e CPF formatado;
• cards brancos de canto arredondado e sombra leve;
• resumo financeiro com valor, rótulo e status textual;
• botão primário fixo no rodapé, com espaçamento de rolagem suficiente para não encobrir o último campo;
• estados de carregamento, vazio, erro e sem conexão conforme a spec principal.

As referências visuais deste escopo ficam em local-docs/design/prototipo/cadastro-e-venda/: a tela de cadastro evidencia o acesso progressivo aos dados avançados; a tela de contrato evidencia a opção de exigir assinatura; e uma tela de consulta mostra busca por aluno e status das assinaturas. Elas são referência de composição, não regra de banco nem contrato de API.

Como o protótipo atual não possui telas próprias para esses três fluxos, a primeira etapa visual deve produzir uma composição de referência alinhada aos tokens, tipografia e espaçamentos de local-docs/design/prototipo/, antes de consolidar as telas Flutter.

9.3 Microcopy inicial

10. Persistência, DDL e compatibilidade

10.1 Alterações previstas

10.2 Migration e documentação obrigatórias

Antes de aplicar qualquer DDL:

1. executar leitura de SHOW TABLES, SHOW COLUMNS, SHOW INDEX e dos IDs disponíveis para definir nomes/índices e ações sem colisão;
2. criar migration versionada em docker/local/db/migrations/;
3. executar a migration duas vezes no MySQL local, comprovando idempotência;
4. documentar o DDL, pré-requisitos e rollback seguro em um novo arquivo de local-docs/implementacoes/;
5. só então habilitar os endpoints dependentes da estrutura.

Nenhum DDL será aplicado em ambiente externo como consequência desta spec. Uma promoção de ambiente exige autorização posterior e específica.

10.3 Auditoria

As operações devem permitir responder, sem ambiguidade:

• qual usuário vendeu, cadastrou ou criou o contrato;
• em qual CFC;
• quando ocorreu;
• qual ação/configuração originou a venda;
• quais créditos, contrato e movimentação financeira resultaram;
• se a resposta foi uma repetição idempotente.

11. Critérios de aceite e validações

11.1 Cadastro de aluno

• CPF inválido e CPF duplicado no mesmo CFC são recusados.
• O mesmo CPF em outro CFC não interfere na criação do tenant atual.
• O aluno criado recebe os saldos iniciais canônicos, sem crédito comprado.
• O formulário rápido exige somente os campos obrigatórios devolvidos pelo preflight; o avançado aceita os campos suportados pelo painel sem criar regra diferente no app.
• Repetir uma solicitação após queda de rede não cria aluno duplicado.

11.2 Venda rápida

• Ação inativa, inexistente, de outro CFC ou sem serviço válido não pode ser consultada ou executada.
• Serviço fora da ação é recusado, mesmo se o app for manipulado.
• Preço, conta, categoria e unidade de custo enviados de forma adulterada não alteram o resultado configurado da ação.
• A venda cria os créditos esperados, uma movimentação dinâmica e o efeito financeiro correto para pago ou pendente.
• Repetir a mesma chave devolve o mesmo resultado, sem segundo crédito nem segunda movimentação.
• O painel continua exibindo a venda e os créditos como operação canônica.

11.3 Contratos

• O contrato usa os serviços, categorias, créditos e parcelas retornados pela prévia canônica.
• Tentativas de serviço/preço fora do contrato são recusadas.
• Um retry não cria segundo contrato ou segunda cobrança.
• A regra existente de contrato recente permanece aplicada.
• A flag de assinatura só é exibida e aceita quando a configuração do CFC está ativa (status = 1). Quando marcada, cria uma única pendência canônica; quando desmarcada, o contrato não recebe pendência.
• A busca por nome, CPF ou RENACH não retorna aluno de outro CFC e os contratos retornados mostram o status atual de assinatura sem permitir sua alteração.

11.4 Regressão e dispositivos

• Lint PHP, verificadores de contrato e harnesses de tenant/autorização aprovados no ambiente local.
• flutter analyze, testes de repositório, estados de tela e serialização de idempotência aprovados no app novo.
• Smoke manual local: criar aluno, vender ação rápida, conferir saldo/crédito, criar contrato de cenário permitido e conferir parcelas.
• Nenhum teste chama CFC Pay, ND7, e-mail, storage externo, homologação ou produção.

12. Cronograma vivo

O avanço desta extensão é medido em nove ciclos de mesmo peso. Um ciclo só fica concluído quando seus critérios de aceite passam, seu histórico é registrado e há commit local coerente em cada repositório realmente alterado.

12.1 Ordem e paralelismo permitido

• C2 e C3 podem ter preparação técnica em paralelo somente depois de C1, mas C3 não é dado como concluído sem a seleção de aluno de C2 disponível.
• C6 pode avançar como leitura/inventário após C2, sem aguardar a escrita da venda rápida.
• C4, C5, C7 e C8 não podem pular seus predecessores.
• Se uma dependência expor decisão de produto não resolvida, o ciclo fica Bloqueado; não se substitui a decisão por comportamento inventado.

12.2 Regra de atualização do cronograma

Ao abrir um ciclo, atualizar a tabela para Em andamento, descrevendo o objetivo real. Ao concluí-lo, registrar somente fatos verificados: arquivos, DDL, testes, limitações e hashes de commit. Reordenação é permitida apenas para respeitar dependência técnica, sem modificar as regras desta spec.

13. Histórico incremental

Em cada ciclo de implementação concluído, acrescentar uma linha nesta tabela e um registro detalhado em:

local-docs/historico/AAAA-MM-DD-app-gestao-comercial-alunos-vendas.md

O registro detalhado deve conter escopo, decisões, arquivos alterados, DDLs, validações, pendências, hashes e a declaração de que não houve push/publicação quando isso permanecer verdadeiro.

14. Política de execução e commits

1. Cada ciclo altera somente o necessário para a entrega especificada.
2. Antes do commit, revisar git status, diffs e alterações preexistentes; nada alheio ao ciclo entra no commit.
3. Validar primeiro; registrar histórico e cronograma em seguida; criar commit local por último.
4. Quando backend e Flutter forem alterados, cada repositório recebe seu commit local próprio, com hash registrado no histórico.
5. Não haverá git push, PR, tag, merge remoto, publicação em loja ou deploy como consequência automática de um ciclo. Qualquer atualização de ambiente remoto ou build distribuível precisa de solicitação explícita posterior.
6. O app legado continua somente como referência de compatibilidade. Nenhum commit é feito nele.

Formato recomendado de mensagem:

(cfc-p) entrega C4 — venda rápida idempotente
(cfc-p-app-gestao-2026) entrega C5 — fluxo de venda rápida

15. Decisões fechadas e decisões condicionais

15.1 Fechadas

• Ações rápidas são o domínio comercial movimentacao dinamica do painel.
• Venda rápida, cadastro de aluno e contrato são fluxos diferentes.
• Venda rápida inicial preserva a semântica atual de um serviço elegível por confirmação.
• O app não edita preço, descontos ou classificação financeira da Ação rápida.
• O fluxo comercial é exclusivo do contexto Gestor.
• O cadastro rápido e o avançado gravam pelo mesmo domínio canônico; campos obrigatórios continuam sendo definidos pelo CFC/servidor.
• A assinatura do aluno é solicitada opcionalmente no app somente quando a configuração já existir no painel; assinatura e mudanças de status seguem fora do app.
• A consulta de contratos é por aluno e aceita nome, CPF ou RENACH, sempre limitada ao CFC do token.
• Todo ciclo terá validação, cronograma vivo, histórico incremental e commits somente locais.

15.2 Condicionais a validar no C0/C6

16. Riscos e contenções

17. Condição de encerramento

Esta extensão fica concluída somente quando os nove ciclos estiverem em Concluído, os testes definidos tiverem evidência no histórico, o app preservar os fluxos já existentes e cada operação comercial puder ser conferida no painel sem divergência de crédito, financeiro, contrato ou autoria.

Não há autorização implícita nesta spec para publicar, enviar builds, alterar ambiente externo ou integrar CFC Pay.