Quem atua como desenvolvedor freelancer ou presta serviços de tecnologia conhece bem o gargalo da etapa comercial: gastar horas formatando propostas no Docs/Canva, enviando PDFs estáticos por WhatsApp ou redigindo mensagens sem padronização de escopo, cronograma e garantias.
O problema não é apenas o tempo gasto na redação, mas a falta de rastreabilidade: propostas que viram 'telefone sem fio', alterações de escopo sem histórico formal e a ausência de um aceite eletrônico com validade jurídica mínima. Para resolver essa fricção do meu próprio fluxo, desenvolvi o ViraPropo, uma aplicação para gerar propostas comerciais consultivas estruturadas, disponibilizar visualização pública via web e registrar assinaturas eletrônicas auditáveis.
A aplicação foi construída com foco em simplicidade operacional, baixo custo de infraestrutura e performance em ambiente serverless.
Framework Full-Stack
- Next.js 16 (App Router) + React 19 + TypeScript.
Provedor de LLM
- Google Generative AI SDK (@google/generative-ai) consumindo Gemini Flash.
Banco de Dados
- PostgreSQL hospedado remotamente, consumido via driver nativo pg com pool de conexões e transações manuais.
Validação de Schemas
- Zod 4 para validação de payloads nas rotas de API e formulários.
Autenticação e Criptografia
- JWT (jsonwebtoken) para sessões stateless, bcryptjs para hashing de credenciais e módulo nativo crypto do Node.js para hashes de integridade SHA-256.
Gateways de Pagamento / Webhooks
- Integração com Asaas e Abacate Pay com tabela dedicada de idempotência (webhook_eventos) para evitar duplicidade no processamento de eventos.
Hospedagem & Deploy
- Vercel (Edge Middleware + Serverless Route Handlers).
Decisões Técnicas e Desafios de Implementação
3.1. Integração com LLM: Structured Outputs vs. Geração Direta de HTML
- Inicialmente, testei pedir para a IA gerar o documento HTML completo com CSS inline. O resultado foi péssimo: inconsistências no design responsivo, quebra de tabelas em telas menores e alucinações nas tags de fechamento.
- A solução foi migrar para Structured Outputs. O modelo atua exclusivamente como um sintetizador de inteligência de negócios (diagnóstico de oportunidade, divisão de entregáveis em fases executivas, diferenciais competitivos e reversão de riscos), retornando um JSON estrito validado.
- Os dados retornados pelo JSON são injetados em templates HTML modulares (gerarTemplatePro / gerarTemplateFree), garantindo conformidade visual, sanitização e responsividade.
3.2. Persistência Atômica e Visualização Pública
- A persistência do documento e seus itens filhos ocorre em uma única transação atômica no PostgreSQL. O identificador único da proposta é um UUIDv4 gerado pelo banco (gen_random_uuid()), acompanhado de um código legível (PROP-YYYY-XXXX).
- Na rota pública /p/[id], o HTML da proposta é renderizado dentro de um isolado via srcDoc. Isso impede conflitos de CSS entre o design system da aplicação (Tailwind CSS) e os estilos inline do documento comercial.
3.3. Assinatura Eletrônica e Manifesto Jurídico (Dual Signature + SHA-256)
- Para que o aceite não seja apenas um botão que altera uma flag no banco, implementei um fluxo de Dupla Assinatura Criptográfica:
- Assinatura do Emissor (Criação): No momento em que o dev gera a proposta, o sistema calcula o hash do conteúdo do documento somado ao IP, timestamp e dados do emissor.
- Assinatura do Cliente (Aceite): Quando o cliente clica em "Aceitar & Assinar", um modal coleta o nome completo e CPF/CNPJ. A rota /api/propostas/[id]/assinar valida os dados via Zod, extrai o IP real do cliente via headers (x-forwarded-for) e gera o hash final de aceite.
- Manifesto de Assinaturas (PDF / Print): Ao utilizar a funcionalidade de impressão ou exportação para PDF, o componente injeta automaticamente uma página final de Manifesto de Assinaturas com quebra de página forçada (break-before: page). O manifesto lista o ID do documento, hash SHA-256, dados e IPs de ambos os signatários, com respaldo legal amparado pela MP nº 2.200-2/2001 e Lei Federal nº 14.063/2020.
LLM em Serverless exige arquitetura de fallback: Confiar 100% no tempo de resposta de APIs de 8.5s ou mais, implementar um gerador determinístico de fallback (gerarCopywritingFallback) para garantir que o usuário nunca receba um erro 504 na tela; a proposta é montada imediatamente após a solicitação.
Conclusão
- ViraPropo é uma aplicação robusta e eficiente para gerar propostas comerciais consultivas estruturadas, com visualização pública via web e assinaturas eletrônicas auditáveis, tudo em um ambiente serverless de baixo custo e alta performance.