gerador-proposta/docs/gerador-propostas/SOURCE_OF_TRUTH.md

Source of Truth — Gerador de Propostas EloPro — MVP

1. Decisões consolidadas

• Produto standalone dentro do ecossistema EloPro.
• Integração com CRO é opcional e serve para pré-preenchimento quando houver contexto explícito de cliente.
• Tenant técnico = workspace_id; isolamento por RLS. CNPJ é dado comercial, não chave de tenant.
• Papéis funcionais: Superadmin, Administrador, Gestor e Usuário. Mapeamento atual EloPro: profiles.is_superadmin, owner/admin, gestor, agent.
• Modelos são importados por Admin/Gestor a partir de PDF, PPTX ou DOCX.
• Marcadores variáveis: [campo]. O sistema não infere trechos variáveis.
• Limite: 10 modelos por workspace; Rascunho, Ativo e Arquivado contam. Versões internas não ocupam nova vaga.
• Status de proposta: apenas Rascunho e Gerada.
• Estados de UI da criação: Preencher → Validar → Gerar; são estados da mesma experiência, não status persistidos independentes.
• Primeira geração bem-sucedida cria PROP-###### e V1.
• Versões formais são imutáveis. Edição posterior cria/retoma o rascunho da próxima versão.
• Download e envio por e-mail usam exatamente o PDF da versão exibida.
• Lock: um editor por recurso, TTL funcional de 10 minutos, sem force takeover no MVP.
• Autosave obrigatório.
• Contrato fica visível/desabilitado nesta fase. Apresentação permanece pendente.

2. Regras de negócio

• RN-001 Standalone — fluxo principal funciona sem Calculadora, Contratos, Planilhas ou outros produtos.
• RN-002 Brasil/BRL — pt-BR, BRL; sem seletor obrigatório de moeda.
• RN-003 Segurança server-side — permissão, entitlement, limite e estado também no backend/RLS.
• RN-004 Autosave — autosave não substitui Salvar/Salvar e sair.
• RN-005 Limite de modelos — máximo 10 por workspace; draft/active/archived contam.
• RN-006 Modelo ativo — somente modelo Ativo inicia proposta.
• RN-007 Marcadores — somente [campo] explícito origina campo.
• RN-008 Tipos de campo — Texto e Número/moeda; default Texto, obrigatório=Não.
• RN-009 Estrutura do modelo — marcador não é criado/excluído/renomeado na tela de validação; correção estrutural exige reenvio.
• RN-010 Versão de modelo — primeira ativação V1; alterações V2+ preservam histórico.
• RN-011 Criação de rascunho — abrir 4.2 não cria rascunho; nasce no primeiro persist válido.
• RN-012 Status — apenas Rascunho/Gerada; edição em andamento é indicador.
• RN-013 Fluxo 4.2 — Preencher/Validar/Gerar são estados da mesma página.
• RN-014 Salvar — com pendências salva e fica em Preencher; sem pendências cria checkpoint e vai para Validar.
• RN-015 Salvar e sair — persiste/checkpoint; libera lock somente após sucesso.
• RN-016 Lock — um editor; 10 min; sem tomada forçada; observador vê último persistido.
• RN-017 Geração formal — só existe sucesso se PDF formal existir; falha não cria número/versão formal.
• RN-018 Numeração — primeira geração cria PROP-###### e V1; escopo da sequência ainda precisa de decisão técnica formal.
• RN-019 Imutabilidade — versão formal gerada é imutável.
• RN-020 Nova versão — somente com alteração de conteúdo + nova geração bem-sucedida.
• RN-021 Histórico — versões antigas podem ser vistas/baixadas/enviadas, nunca editadas/excluídas/usadas como base.
• RN-022 E-mail — usa exatamente PDF exibido; não muda status Gerada.
• RN-023 Auditoria — autoria e eventos críticos rastreáveis.
• RN-024 Logo — logo da empresa obrigatório para identidade da proposta; cores opcionais.
• RN-025 Erros — erros são estados das telas existentes, sem criar novas páginas numeradas.

3. Requisitos funcionais

RF-001 autenticar/resolver workspace; RF-002 listar propostas por escopo; RF-003 listar modelos ativos; RF-004 confirmar seleção sem criar draft; RF-005 abrir 4.2 sem draft vazio; RF-006 prefill CRO quando aplicável; RF-007 campos dinâmicos; RF-008 validação durante edição; RF-009 autosave; RF-010 draft no primeiro persist; RF-011 Salvar; RF-012 Salvar e sair; RF-013 trocar modelo; RF-014 lock; RF-015 validar antes de gerar; RF-016 gerar PDF; RF-017 reconciliar geração assíncrona; RF-018 número comercial; RF-019 versionar; RF-020 detectar ausência de alteração; RF-021 visualizar vigente/histórica; RF-022 baixar PDF; RF-023 enviar e-mail; RF-024 registrar envio; RF-025 excluir draft elegível; RF-026 listar modelos; RF-027 limite 10/10; RF-028 upload PDF/PPTX/DOCX; RF-029 analisar marcadores; RF-030 draft de modelo após upload+análise técnica; RF-031 reprocessar correção no mesmo draft; RF-032 configurar campos; RF-033 autosave/lock de modelo; RF-034 ativar V1; RF-035 versionar modelo V2+; RF-036 arquivar; RF-037 excluir modelo nunca usado (Admin); RF-038 auditoria; RF-039 RLS; RF-040 Sentry.

4. Requisitos não funcionais

• Segurança: RLS + autorização server-side; fail-closed.
• Privacidade: nenhum documento/template cross-tenant; Sentry/logs sem documento integral/PII desnecessária.
• Confiabilidade: geração/ativação idempotentes; sem efeitos parciais.
• Concorrência: lock TTL 10 min + renovação por atividade; sem force takeover.
• Recuperação: autosave e retomada respeitando lock.
• Performance: carregamento progressivo; paginação/virtualização quando necessário; metas numéricas ainda abertas.
• Acessibilidade: alvo WCAG 2.1 AA, teclado, foco, labels, contraste, status não apenas por cor.
• Responsividade: web adaptada; mobile não é mera redução proporcional.
• Observabilidade: Sentry client/server/edge + correlação request/job.
• Auditabilidade: eventos mínimos imutáveis; retenção ainda aberta.
• Manutenibilidade: TS strict recomendado, lint, testes, separação por domínio.
• Integridade documental: versão formal referencia versão exata do modelo e artefato.
• Segurança de arquivos: MIME/extensão/conteúdo; tamanho/antivírus/sandbox ainda abertos.

5. Modelo de dados proposto

• proposal_models: id, workspace_id, name, status, current_version, created_by, archived_at.
• proposal_model_versions: id, model_id, version_no, source_file_ref, normalized_template, analysis_json, activated_at, activated_by.
• proposal_model_fields: id, model_version_id, field_key, display_name, type, required, order.
• proposals: id, workspace_id, created_by, owner_user_id, status, commercial_number, current_version_no, model_id, client_ref?, created_at.
• proposal_drafts: id, proposal_id, based_on_version_no?, model_version_id, data_json, content_hash, lock_owner?, updated_at.
• proposal_versions: id, proposal_id, version_no, model_version_id, content_snapshot, content_hash, pdf_ref, generated_by, generated_at.
• proposal_email_events: id, proposal_version_id, actor_id, to_email, subject, result, provider_message_id?, created_at.
• proposal_audit_events: id, workspace_id, proposal_id?, model_id?, actor_id, event_type, metadata, created_at.
• locks preferencialmente no Redis.
• workspace_branding: workspace_id, logo_ref, brand colors opcionais, contact email.

6. Design System EloPro V2.1

• Base predominante: Cloud White #FBFBFE, 65–75% superfícies claras.
• Texto/âncora: Midnight Ink #071B45.
• Primary Blue #1F6FFF; botão primário deve usar token de contraste do DS, Blue 600 #225EDB quando aplicável.
• Bright Blue #2F8FFF; Aqua Signal #00C2A8; Soft Blue #DCEBFF; Warning #F39A2D; Error #E63946.
• Manrope para UI. Source Serif 4 apenas institucional/editorial.
• Spacing 4px base; radius input 10, button 18, card 14, panel 18, modal 24.
• Motion 120/200/320ms, easing cubic-bezier(.2,.8,.2,1).
• Proibido: neon, cyberpunk, holograma, glassmorphism, dark page dominante, grid decorativo, robôs/cérebros futuristas.
• Estados sempre por cor + texto + ícone/semântica; nunca cor isolada.
• Componentes globais: Button, IconButton, Badge, Tag, Card, Input, Select, Checkbox, Radio, Switch, DateField/DateRangeField, Tabs, CapsuleTabs, ContextGroup, SectionPill, Toast, Tooltip, Dialog.
• Preservar quando fizer sentido: ContextLayers, JourneyTrail, OpenFramePanel, SemanticMarker.
• JourneyTrail não é Stepper genérico.
• Lacunas de DS: Search, Table, Stepper, Empty State, Pagination, Skeleton, File Upload, Avatar. Compor localmente usando tokens/primitivos e não promover como componente global sem decisão.
• Iconografia EloPro é prioridade; Lucide apenas fallback técnico.

7. Pendências que NÃO podem ser inventadas

• P-001 fallback de Reply-To sem e-mail comercial.
• P-002 fonte definitiva de Cliente no uso independente.
• P-003 Tipo no MVP e opções definitivas.
• P-004 Apresentação.
• P-005 Gerador de Contratos.
• P-006 tamanho máximo/antivírus/sandbox/extração parcial de arquivo.
• P-007 retenção da auditoria.
• P-008 fonte/lifecycle de entitlements.
• P-009 escopo definitivo da sequência PROP (recomendação técnica atual: workspace, mas não assumir sem ADR/aprovação).
• P-010 motor de ingestão/conversão PDF/PPTX/DOCX.
• P-011 provider de e-mail (EloPro documenta Resend, mas formalizar uso no módulo).
• P-012 metas quantitativas de performance/SLO/document size/generation time.

8. Critérios críticos de aceite

• Nenhum P0/P1 bloqueador aberto.
• Workspace A nunca acessa B por UI, URL manipulada, API/Action direta ou storage.
• Falha de geração não consome PROP nem versão.
• Duplo clique/retry não cria duas versões.
• Versão formal é imutável.
• Lock funcional expira em 10 min e impede edição concorrente.
• Usuário Final não acessa Modelos nem por rota direta.
• 10/10 bloqueia upload antes do processamento.
• PDF baixado/enviado é o mesmo da versão exibida.
• UI segue EloPro V2.1 sem inventar regra funcional.