Skip to content

About

API de vendas B2B com quota por organização, cache compartilhado e observabilidade de falhas e recuperação.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

48 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

API Sentinel

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.

Demonstração Arquitetura Executar localmente Verificação e evidências Arthur Joanes no LinkedIn

Demonstração

Central com filtro de período UTC, inícios dos incidentes retidos e fila de investigação

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.

Conta de referência

Comparação dos pedidos da fixture: 8.500 e 4.000 centavos somam R$ 125,00, em quatro unidades e dois pedidos; ticket médio R$ 62,50

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-01

Esperado: 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.

Arquitetura

Cliente com Bearer passa por NGINX e API; PostgreSQL guarda identidade e vendas, Redis coordena quota e cache, ERP fornece estoque; Prometheus e Jaeger acompanham o mesmo host

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
Loading

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.

Stack e decisões

Python FastAPI Pydantic SQLAlchemy Core PostgreSQL SQLite Redis Docker NGINX Prometheus e Alertmanager Grafana Jaeger OpenTelemetry HTML CSS JavaScript

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.

Executar localmente

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.py

O 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 demo

O setup gera credenciais locais; stop preserva volumes. Instalação Linux, credenciais e limpeza · implementação dos comandos.

Verificação e evidências

Guia da central · contratos HTTP e quota · consulta → falha → recuperação em 22/09/2026.

Sequência operacional real de 22/09/2026

Histórico da ocorrência 2 com abertura recebida às 12:53:33 UTC e recuperação recebida às 12:53:53 UTC

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-window preserva a janela de um segundo e sua rajada na fronteira. gcra usa capacidade total QUOTA_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

Autor e licença

Para conversar sobre APIs, isolamento e observabilidade neste laboratório:

Arthur Joanes no LinkedIn

Licença MIT. Ícones da stack e LinkedIn: Devicon licença MIT.

Fontes dos ícones e cartões: documentação da stack.

About

API de vendas B2B com quota por organização, cache compartilhado e observabilidade de falhas e recuperação.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages