📄 Quote Builder Agent — Manual Técnico

Versão: 1.0
Data: 2026-01-22
Status: Produção ✅

📋 Visão Geral

O Quote Builder Agent é responsável por gerar propostas comerciais formais:
- Gera texto WhatsApp (≤650 caracteres)
- Gera PDF profissional
- Armazena no S3
- Versiona propostas
- Registra audit trail

Posição no Fluxo

Offer Agent → Quote Builder → Execution Orchestrator → WhatsApp/CRM
          (oferta)       (proposta PDF)        (envio)

🔌 API Endpoints

Base URL

https://csuite.internut.com.br/quotes

Porta Local: `8020`

Endpoints Principais

Método	Endpoint	Descrição
`POST`	`/quotes/build`	Gera nova proposta
`GET`	`/quotes/{quote_id}`	Busca proposta
`GET`	`/quotes/{quote_id}/versions`	Lista versões
`GET`	`/quotes/{quote_id}/v/{version}`	Versão específica
`GET`	`/quotes/{quote_id}/pdf`	Redirect para PDF
`GET`	`/quotes/{quote_id}/pdf-info`	Info do PDF
`POST`	`/quotes/{quote_id}/status`	Atualiza status
`GET`	`/quotes/{quote_id}/audit`	Audit trail
`GET`	`/health`	Health check

📥 Gerar Proposta

Request

POST /quotes/build
Content-Type: application/json

{
  "correlation_id": "CASE-8841-202601221700-a3f7",
  "client_id": 8841,
  "seller_id": 22,
  "client_name": "Robson Baterias",
  "seller_name": "João Silva",
  "items": [
    {
      "sku": "Y5S",
      "qty": 2,
      "unit_price": 198.00,
      "total": 396.00,
      "role": "anchor",
      "description": "Bateria Y5S 60Ah"
    },
    {
      "sku": "KIT-001",
      "qty": 2,
      "unit_price": 50.00,
      "total": 100.00,
      "description": "Kit Peças"
    }
  ],
  "pricing_total": 496.00,
  "payment_terms_text": "Prazo máximo 28 dias",
  "validity_hours": 48
}

Response

{
  "quote_id": "QT-2026-000001",
  "version": 1,
  "correlation_id": "CASE-8841-202601221700-a3f7",
  "status": "draft",
  "total": 496.0,
  "valid_until": "2026-01-24T14:14:44-03:00",
  "whatsapp_text": "Olá Robson Baterias, tudo bem?\n\nResumo da proposta:\n• Bateria Y5S 60Ah — 2 un\n• Kit Peças — 2 un\n\nTotal: R$ 496,00\n\nCondições:\n• Prazo máximo 28 dias\n• Validade: 48h\n\n📄 Proposta completa:\nhttps://csuite-quotes-prod.s3.sa-east-1.amazonaws.com/quotes/QT-2026-000001/QT-2026-000001-v1.pdf\n\nPosso seguir com a emissão do pedido?",
  "whatsapp_text_length": 296,
  "pdf_url": "https://csuite-quotes-prod.s3.sa-east-1.amazonaws.com/quotes/QT-2026-000001/QT-2026-000001-v1.pdf",
  "pdf_s3_key": "quotes/QT-2026-000001/QT-2026-000001-v1.pdf"
}

📊 Status da Proposta

Transições Válidas

draft → sent → accepted | rejected | expired | canceled

Atualizar Status

POST /quotes/{quote_id}/status
Content-Type: application/json

{
  "status": "sent",
  "actor_type": "agent",
  "actor_name": "execution-orchestrator"
}

🗄️ Storage S3

Bucket

s3://csuite-quotes-prod (sa-east-1)

Estrutura

quotes/
└── QT-2026-000001/
    ├── QT-2026-000001-v1.pdf
    ├── QT-2026-000001-v2.pdf
    └── ...

Lifecycle

90 dias → Standard-IA
365 dias → Glacier
Versões antigas → Deletadas após 90 dias

⚙️ Configuração

Variáveis de Ambiente

# Database
MYSQL_DSN=mysql+pymysql://user:pass@host:3306/csuite_quote

# Storage (S3)
S3_USE_STUB=false
S3_BUCKET=csuite-quotes-prod
S3_REGION=sa-east-1
STORAGE_BASE_URL=https://csuite-quotes-prod.s3.sa-east-1.amazonaws.com
S3_URL_EXPIRATION=604800

# Quote Config
DEFAULT_VALIDITY_HOURS=48
MAX_WHATSAPP_CHARS=650
TOTAL_TOLERANCE=1.00

# App
LOG_LEVEL=INFO

🐳 Deploy

Desenvolvimento Local

cd c-suite/agents/quote-builder
./scripts/run-local.sh

Docker Compose

docker-compose up --build

Docker Swarm (Prod)

./deploy.sh --build

📊 Banco de Dados

Schema: `csuite_quote`

Tabela `quote`

Campo	Tipo	Descrição
quote_id	VARCHAR(30)	ID único (QT-YYYY-NNNNNN)
correlation_id	VARCHAR(80)	Referência do caso
client_id	BIGINT	ID do cliente
seller_id	BIGINT	ID do vendedor
status	VARCHAR(20)	draft/sent/accepted/rejected
total	DECIMAL(15,2)	Valor total
valid_until	TIMESTAMP	Validade
pdf_url	VARCHAR(500)	URL do PDF

Tabela `quote_version`

Histórico de versões
JSON completo da proposta
Texto WhatsApp

Tabela `quote_audit`

Trail de auditoria
Actor (agent/human/system)
Payloads

📊 Métricas

Métrica	Valor
Tempo médio de build	< 2s
PDF generation	< 1s
WhatsApp text	≤ 650 chars
SLA uptime	99.9%

📝 Changelog

Data	Versão	Descrição
2026-01-22	1.0	MVP completo com S3 real