Deploy com AWS SAM¶

O deploy da aplicação é definido por template.yaml, samconfig.toml e scripts/deploy_from_env.ps1. Este runbook descreve os recursos e comandos existentes; nenhuma publicação ou verificação de conta AWS foi realizada para produzir esta documentação.

Ambientes e nomes¶

Ambiente	Configuração versionada	Stack padrão	Região da configuração
`dev`	`default` em `samconfig.toml`	`gogenetic-agent`	`sa-east-1`
`staging`	Permitido pelo parâmetro SAM, sem seção própria no samconfig	Definir explicitamente, por exemplo `gogenetic-agent-staging`	Definir explicitamente
`prod`	`prod` em `samconfig.toml`	`gogenetic-agent-prod`	`sa-east-1`

O nome da stack e o parâmetro Environment são independentes. Os nomes físicos da tabela, filas e funções usam Environment, não StackName; duas stacks com o mesmo ambiente na mesma conta/região podem disputar os mesmos nomes.

Recursos implantados¶

flowchart LR
    SRC[Checkout aprovado] --> BUILD[SAM build]
    ENV[Configuração local protegida] --> SSM[SSM por ambiente]
    ENV --> PARAM[Parâmetros SAM]
    BUILD --> CF[CloudFormation / SAM deploy]
    PARAM --> CF
    CF --> API[HTTP API]
    API --> WEB[Webhook Lambda]
    API --> UI[Emulator / Atendimento Lambda]
    WEB --> FIFO[SQS FIFO e DLQ]
    FIFO --> ORCH[Orchestrator Lambda]
    SSM --> ORCH
    ORCH --> DDB[DynamoDB single-table]
    UI --> DDB
    CF --> SCHEDULE[EventBridge schedules]
    SCHEDULE --> CRM[CRM Sync: 1 minuto]
    SCHEDULE --> HAND[Renotificação: 1 hora]
    SCHEDULE --> EXPORT[Exportação: segunda 12 UTC]
    CRM --> DDB
    HAND --> DDB
    EXPORT --> DDB

Recurso	Handler / detalhe
`WebhookHandlerFunction`	`webhook_handler.app.lambda_handler`; GET/POST `/webhook`; 60 s
`OrchestratorFunction`	`orchestrator.app.lambda_handler`; SQS batch 1, falha parcial; 90 s
`EmulatorFunction`	`emulator.app.lambda_handler`; HTTP `/{proxy+}`; 60 s
`AdminExportFunction`	`admin_export.app.lambda_handler`; `cron(0 12 ? * MON *)`; 90 s
`HandoffRenotifyFunction`	`handoff_renotify.app.lambda_handler`; `rate(1 hour)`; 60 s
`CrmSyncFunction`	`crm_sync.app.lambda_handler`; `rate(1 minute)`; 120 s, concorrência reservada 1

Defaults globais: Python 3.12 e 512 MB. DynamoDB é PAY_PER_REQUEST, GSI1 e TTL ttl. Fila FIFO usa visibilidade 120 s, retenção 4 dias, atraso 0 e redrive após 3 recebimentos para DLQ com retenção de 14 dias. Consulte SQS para processamento e repetição.

Divergência documental

O README menciona três Lambdas em uma descrição histórica. O template atual define seis. context/infra/deploy.md também registra pendências históricas; sua existência não permite concluir quais recursos estão ativos hoje em uma conta externa.

Pré-requisitos e validação local¶

Use checkout/commit aprovado, Python 3.12, AWS CLI, SAM CLI e credenciais da conta de destino. Configure o profile no ambiente e confirme a identidade sem imprimir secrets:

$env:AWS_PROFILE = "<PERFIL_AWS>"
aws sts get-caller-identity --query '{Account:Account,Arn:Arn}'
sam --version
aws --version
sam validate --lint --region sa-east-1
sam build

IAM deve permitir as operações necessárias de CloudFormation, SAM/S3, criação dos recursos e gestão de secrets planejada. CAPABILITY_IAM é passado pelo script porque o template cria papéis e políticas. Acesso externo correto só é comprovado no ambiente alvo.

Deploy pelo script existente¶

O script lê um arquivo CHAVE=valor, rejeita linhas sem =, suporta aspas externas e exige configuração WhatsApp completa. -ValidateOnly valida o arquivo sem chamar AWS ou SAM:

.\scripts\deploy_from_env.ps1 -EnvFile .env.staging -Environment staging -Region sa-east-1 -StackName gogenetic-agent-staging -ValidateOnly

No modo de validação, OpenAI API key é obrigatória salvo -SkipOpenAiSsm, e os quatro modelos precisam estar presentes. Em prod, o arquivo precisa declarar explicitamente EGESTOR_ENABLED, HUBSPOT_ENABLED, HANDOFF_NOTIFIER_ENABLED, HANDOFF_NOTIFIER_TYPE e OPERATOR_UI_BASE_URL. Ausência dessas chaves é erro, para evitar desativação silenciosa de integrações.

Depois de revisar o plano e autorizar a publicação do ambiente:

.\scripts\deploy_from_env.ps1 -EnvFile .env.staging -Environment staging -Region sa-east-1 -StackName gogenetic-agent-staging

Para produção, use arquivo de configuração próprio e passe -Environment prod -StackName gogenetic-agent-prod. -NoBuild reutiliza o build existente e exige certeza de que corresponde ao checkout. -SkipOpenAiSsm só evita a escrita da chave OpenAI; não impede gravação de secrets de outros providers nem deploy.

O script atual imprime variáveis: chaves com TOKEN|SECRET|KEY|PASSWORD|EMAIL recebem máscara parcial, outras podem sair integralmente, incluindo telefones. -ValidateOnly também faz isso. Não compartilhe a saída bruta nem trate a máscara parcial como anonimização completa.

SSM e parâmetros¶

Caminho SSM	Tipo escrito pelo script	Condição
`/gogenetic-agent/<ambiente>/openai-api-key`	`SecureString`	Sempre, salvo `-SkipOpenAiSsm`
`/gogenetic-agent/<ambiente>/egestor-base-url`	`String`	eGestor habilitado e URL/token locais presentes juntos
`/gogenetic-agent/<ambiente>/egestor-api-token`	`SecureString`	Mesma condição
`/gogenetic-agent/<ambiente>/crm-comercial-access-token`	`SecureString`	CRM habilitado e token local presente

Se eGestor estiver habilitado, URL/token devem estar presentes juntos ou ambos ausentes para usar os parâmetros já provisionados. CRM permite token local ausente e presume SSM pronto. Esses caminhos correspondem aos *_SSM_PARAM do template; não expõem valores de secrets.

O script escreve SSM antes de sam build. Uma falha de build/deploy não desfaz essas escritas. Registre previamente as versões/configurações que deverão ser restauradas em eventual rollback, sem copiar valores para relatórios.

Os overrides incluem flags, quatro modelos, WhatsApp, CRM pipeline/stages/owner, eGestor, notificador, whitelist, domínio e URL de operadores. DevUiEnabled=false é imposto pelo script. Não existe transformação genérica de todas as chaves .env em parâmetros SAM.

Configuração não encaminhada pelo script

OPENAI_REASONING_EFFORT não é adicionado por deploy_from_env.ps1 aos overrides de OpenAiReasoningEffort. O SAM tem esse parâmetro e samconfig.toml na seção prod fixa medium, mas o script não seleciona --config-env prod. Confira a configuração efetiva e use um fluxo SAM explicitamente revisado se precisar desse override. sam deploy não importa .env automaticamente.

O fluxo manual suportado é sam build seguido de sam deploy --guided, ou sam deploy --config-env prod quando a configuração completa já foi preparada. Não trate os poucos parâmetros presentes no samconfig como inventário completo dos secrets e switches do ambiente. Veja variáveis.

Outputs e validação pós-deploy¶

aws cloudformation describe-stacks --region sa-east-1 --stack-name gogenetic-agent-staging --query 'Stacks[0].{Status:StackStatus,Outputs:Outputs}'
aws lambda get-function-configuration --region sa-east-1 --function-name gogenetic-agent-orchestrator-staging --query '{State:State,Update:LastUpdateStatus,Runtime:Runtime,Timeout:Timeout}'

Os outputs são WebhookUrl, EmulatorUrl, OperatorUiUrl, AgentTableName, DebounceQueueUrl e, se houver domínio customizado, OperatorCustomDomainTarget e OperatorCustomDomainHostedZoneId. O template cria domínio/mapping apenas com nome e certificado configurados; o alias DNS deve ser configurado separadamente. A condição não cria certificado ACM nem registro DNS.

Confirme stack estável, saúde HTTP, bloqueio da UI dev e fluxo de acesso antes dos testes reais do runbook de homologação. Output de URL não comprova assinatura Meta, token válido, entrega de WhatsApp ou contrato CRM.

Rollback¶

Se a atualização falhar, leia eventos CloudFormation e aguarde a conclusão de rollback antes de reaplicar. Se a stack ficar em UPDATE_ROLLBACK_FAILED, uma operação de recuperação, após corrigir a causa, é:

aws cloudformation continue-update-rollback --region sa-east-1 --stack-name gogenetic-agent-staging

Para uma regressão de aplicação com stack estável, prepare checkout separado da revisão aprovada anterior, faça novo build e reaplique preservando explicitamente parâmetros atuais necessários. Não há alias/versionamento de Lambda nem estratégia blue/green configurados no template. Reversão de código não reverte dados DynamoDB, mensagens entregues, negócios criados nem alterações SSM feitas pelo script. Não delete a stack como procedimento de rollback: o template não declara política de retenção/backup da tabela.

Testes do mecanismo: tests/unit/scripts/test_deploy_from_env.py e tests/unit/test_template_scoping.py. A validação SAM e os testes locais não comprovam deploy em conta externa.