API de vendas com autorização por loja e organização, quota compartilhada e integração com ERP. A central reúne incidentes, entregas e links para investigar o período no Grafana e no Jaeger. Dados e ERP são sintéticos.
Captura da interface atual com dados sintéticos de referência de 12/10/2026, 06:00 UTC e probe desativado. Guia de uso · detalhe da ocorrência · desktop e mobile.
Selecione hoje, 7 ou 30 dias UTC e filtre por estado. O gráfico conta os inícios em todos os incidentes retidos do filtro, mesmo ao mudar a página da fila. Abra uma ocorrência para conferir as entregas e investigar as métricas do período.
Escopo e contratos do laboratório
Uma integração consulta faturamento e disponibilidade de produtos. A aplicação separa o caminho comercial do ERP e limita o trabalho em andamento. Os dados e o ERP são sintéticos; PostgreSQL, Redis, HTTP e observabilidade executam em containers no mesmo computador.
A implementação inclui cálculos em centavos, quota compartilhada, cache com controle de preenchimento e cliente ERP com prazo total. Código e contratos.
A quota permite escolher janela fixa ou GCRA, com taxa por organização e capacidade de rajada explícita. A janela fixa continua como padrão. O verificador HTTP gera casos a partir do OpenAPI, executa pelo proxy descartável e registra cobertura, falhas e reprodução sem credenciais. Políticas de quota · contratos HTTP.
A central mantém o período, o estado e a página ao investigar uma ocorrência e voltar pelo runbook. Recuperação recebida e encerramento administrativo têm registros distintos. Uso, quota e latência vêm do Prometheus/Grafana; a contagem de incidentes não substitui essas séries.
Loja 7, período comercial de 01/01/2026. Valores sintéticos da fixture independente.
Ver a conta e repetir a consulta autenticada
| Pedido sintético | Quantidade × preço | Total |
|---|---|---|
| 101 | 2 × R$ 25,00 + 1 × R$ 35,00 | R$ 85,00 |
| 102 | 1 × R$ 40,00 | R$ 40,00 |
| Resultado | 4 unidades / 2 pedidos | R$ 125,00 |
O ticket médio é 125 ÷ 2 = R$ 62,50. A fixture independente define esses valores sintéticos para o período comercial de 01/01/2026; eles não representam preços de mercado.
Com a credencial da organização técnica, consulte:
GET /v1/stores/7/summary?start=2026-01-01&end=2026-01-01Esperado: revenue_cents: 12500, order_count: 2 e average_ticket_cents: 6250. O roteiro explica a credencial e a execução; a sequência histórica de 22/09/2026, 12:49 UTC liga consulta, falha controlada e recuperação recebida à mesma ocorrência.
O resumo comercial usa PostgreSQL e Redis; estoque consulta o ERP. As consultas de vendas não dependem da resposta do ERP. Sequências e limites.
Diagrama completo, portas e responsabilidades
flowchart TB
C["Cliente com Bearer"] -->|"HTTP :8104"| N["NGINX<br/>entrada e balanceamento"]
subgraph API["Réplica FastAPI · módulos internos"]
G["Autorização<br/>quota + admissão"]
S["Consultas comerciais<br/>resumo e vendas"]
E["Cliente ERP<br/>prazo total 900 ms"]
G -->|"lojas / vendas"| S
G -->|"estoque"| E
end
N -->|"HTTP :8000"| G
G -->|"autenticação · pool 2"| DB[("PostgreSQL<br/>identidade e vendas")]
G -->|"quota atômica"| R[("Redis único<br/>DB 0 quota · DB 1 cache")]
S -->|"SQL · pool 4"| DB
S -->|"TTL 15 s + lock"| R
E -->|"HTTP /availability"| ERP["ERP sintético :8080<br/>estoque e falhas"]
subgraph OBS["Perfil observability · opcional"]
P["Prometheus<br/>métricas por réplica"]
J["Jaeger<br/>traces amostrados"]
end
P -.->|"/internal/metrics"| G
G -.->|"OTLP · 25%"| J
As setas contínuas representam chamadas e acesso a dados; as pontilhadas, coleta e exportação de telemetria. Os blocos dentro de api são módulos do mesmo processo. A implantação Compose usa uma rede Docker comum e publica entradas em loopback; as réplicas continuam no mesmo host.
| Responsabilidade | Implementação e contrato |
|---|---|
| Identidade e carga | Rotas, autorização e admissão: loja/escopo são conferidos antes da quota Redis e de qualquer acesso ao cache. Limites de concorrência pertencem a cada réplica. |
| Leitura comercial | Queries e cache: chave inclui versão, tenant, loja e período; um miss coordena o cálculo entre réplicas. O cursor de vendas preserva esses filtros. |
| Dependência ERP | Cliente HTTP: até 4 chamadas por processo, circuito próprio, validação do corpo e até um retry dentro do prazo total de 900 ms. Uma falha no estoque não obriga o resumo de vendas a consultar o ERP. |
| Incidente e investigação | Receiver: consulta a fixture pelo proxy e recebe webhooks do Alertmanager; SQLite guarda ocorrência e entregas. Grafana consulta Prometheus e Jaeger recebe os traces. |
A consulta de resumo segue Bearer → autorização → quota → admissão → versão do dataset no PostgreSQL → cache; em miss, SQL e preenchimento protegido por token. O alerta segue probe/métricas → Prometheus → Alertmanager → webhook autenticado → SQLite → central HTML. Sequências, persistência e falhas detalham esses dois caminhos e suas fronteiras.
| Escolha | Motivo e compromisso |
|---|---|
| FastAPI + SQLAlchemy Core + PostgreSQL | Consultas autorizadas com SQL explícito; autenticação consulta o banco a cada chamada. |
| Pydantic | Valida os contratos HTTP, os webhooks e as respostas do ERP. |
| SQLite | Guarda incidentes e entregas dos alertas na central local. |
| Redis | Coordena quota e preenchimento do cache entre réplicas; a quota depende de sua disponibilidade. |
| NGINX + Compose | Entrada comum e ambiente reproduzível; todos os processos continuam no mesmo host. |
| Prometheus/Alertmanager, Grafana, OpenTelemetry e Jaeger | Métricas, alertas e traces amostrados; uma consulta sem trace ainda exige logs e outros sinais. |
| HTML, CSS e JavaScript | Central local de incidentes; o JavaScript sinaliza leituras vencidas e orienta a navegação. |
Decisões, alternativas e implementação · versões Python fixadas · imagens configuradas. Versões fixadas não são uma declaração de versão mais recente.
Docker com containers Linux, Compose 2.24.4+ e Python 3.11+ no host. Instalação descartável, com checks, testes e falhas controladas:
python scripts/review.pyO comando informa portas temporárias em 127.0.0.1, grava resultados em artifacts/problem-review/<UTC>/ e remove os recursos exclusivos da tentativa.
Requisitos e isolamento da revisão
O Compose mínimo atende ao uso de !override no perfil de revisão, conforme a documentação Docker. Python no host executa o runner; não há medição de memória mínima garantida.
A revisão identifica projetos e imagens de API, proxy e ferramentas por tentativa. O gate de contratos usa uma imagem própria com o grupo opcional contracts; Schemathesis não é instalado no runtime da API. Comando dedicado, relatórios e critérios.
Demonstração persistente no Windows
Para explorar a demonstração persistente no Windows, com PowerShell 7:
./scripts/sentinel.ps1 setup -Replicas 2
./scripts/sentinel.ps1 check
./scripts/sentinel.ps1 test
./scripts/sentinel.ps1 demoO setup gera credenciais locais; stop preserva volumes. Instalação Linux, credenciais e limpeza · implementação dos comandos.
Guia da central · contratos HTTP e quota · consulta → falha → recuperação em 22/09/2026.
Sequência operacional real de 22/09/2026
Captura histórica às 12:53:54 UTC: duas entregas da mesma ocorrência no ambiente local, com ERP e vendas sintéticos. Execução e demais capturas · registro das entregas.
| Pergunta | Fonte e data da execução | Limite |
|---|---|---|
| Os contratos passaram nos testes? | XML isolado e HTTP, 22/09/2026 | Suítes distintas da imagem identificada no recibo; não aprovam automaticamente edições posteriores. |
| O ERP degradado coexistiu com vendas? | Recibo da carga das 12:12 UTC, 22/09/2026: 151 conclusões, 114 válidas e 37 falhas previstas do ERP | Ensaio curto e local; as falhas do ERP não são contadas como sucesso comercial. |
| A mesma ocorrência recuperou? | Entregas reais, 22/09/2026 | Recuperação recebida é diferente de encerramento manual. |
Índice de verificações · fontes e afirmações. Capturas, testes, benchmark e scanner têm escopos próprios; suas contagens não são somadas.
Limites e segurança
- Quota comercial padrão: 30 requisições/s por organização; prazo total ERP: 900 ms. São regras do seed e do cliente ERP, detalhadas na matriz de limites; não medem capacidade.
QUOTA_ALGORITHM=fixed-windowpreserva a janela de um segundo e sua rajada na fronteira.gcrausa capacidade totalQUOTA_BURST_CAPACITY, padrão 10; todas as réplicas precisam usar a mesma política. Semântica e transição do ensaio.- Dados comerciais imutáveis e duas réplicas no mesmo host. O laboratório não demonstra SLO mensal, capacidade máxima ou disponibilidade entre máquinas. Escopo das provas.
- Serviços publicados em loopback; tokens e runtime ficam fora do Git. Scans dizem respeito às imagens e bases identificadas em cada execução. Controles e limites.
- A revisão de segurança de 03/10/2026 registra a avaliação de 18 itens de segurança, as correções de rate limit e os testes com PostgreSQL e Redis descartáveis.
- A central exige atualização manual. “Sem incidentes” não prova saúde. Leitura dos registros e do probe · contrato da interface.
Documentação
| Para entender | Guia |
|---|---|
| Problema, componentes e escolhas | Casos · arquitetura · decisões |
| Consultas, dinheiro e isolamento | Contrato de dados |
| Executar e investigar | Demonstração · indicadores e procedimentos |
| Conferir resultados e fontes | Verificação · desempenho · fontes e datas |
| Interface e manutenção | Central de incidentes · galeria · documentação do projeto |
Para conversar sobre APIs, isolamento e observabilidade neste laboratório:
Licença MIT. Ícones da stack e LinkedIn: Devicon licença MIT.
Fontes dos ícones e cartões: documentação da stack.

