Auditoria de pedidos e cancelamentos de delivery

01 — Contexto

A maioria dos projetos de dados mostra volume em dashboards. Menos frequentes são os que mostram onde a operação deixa de cumprir regra de negócio — e quanto isso custa.

A Delivery Audit Platform simula uma operação de delivery e leva eventos a um fluxo auditável: camadas analíticas, regras explícitas de qualidade ligadas ao negócio e métricas que sustentam priorização (por loja, turno, tipo de falha).

O repositório público documenta API mock, pipeline, regras e dashboards. O recorte é um case reproduzível, não um tenant de produção.

02 — Problema

Operações de delivery geram alto volume de registros: pedidos, transições de status, pagamentos, cancelamentos. Ter dado bruto não implica governança nem acionabilidade.

Na prática aparecem:

• atrasos sem causa clara na cadeia de eventos;
• cancelamentos com custo difícil de consolidar;
• desalinhamento entre visão operacional e financeira;
• indicadores de volume sem vínculo com falha ou SLA;
• dashboards que descrevem o “quanto”, mas pouco o “onde quebrou”.

O efeito: os dados não sustentam decisão com confiança.

Objetivo do recorte:

1. ingerir dados simulados de forma controlada;
2. organizar em camadas até o consumo analítico;
3. aplicar auditoria operacional com regras explícitas;
4. produzir métricas comparáveis no tempo;
5. identificar falhas e estimar impacto financeiro por tipo de evento.

03 — Arquitetura

O desenho é ingestão → refinamento → consumo, com um ponto explícito: a auditoria não é adendo. Consome Gold (ou derivados) e materializa flags, severidades e atributos de negócio.

04 — Stack

• Python — transformações e regras versionadas no mesmo repositório.
• FastAPI — origem mock com entidades e eventos reproduzíveis.
• Pandas — preparação tabular explícita no recorte local.
• Parquet — armazenamento colunar entre camadas.
• DuckDB — consultas analíticas e prototipagem de agregações.
• Streamlit — exploração e narrativa para stakeholder.

A escolha prioriza reprodutibilidade e baixo atrito no recorte local.

05 — Pipeline

Bronze — ingestão próxima ao payload da API; mínima transformação; histórico para replay.

Silver — normalização de schema e tipos; deduplicação e conflitos básicos; enriquecimentos para join.

Gold — tabelas de consumo (fatos, KPIs); contrato mais estável para analytics.

A auditoria roda sobre o dado já estruturado e grava ocorrências consumíveis por API ou BI.

06 — Modelagem

Abordagem dimensional, cortes por loja, tempo, cliente e entregador.

Fato fact_orders — grão: uma linha por pedido. Chaves (pedido, loja, cliente, entregador), timestamps da jornada, medidas financeiras e operacionais, tempos entre etapas e flags quando fizer sentido materializar cedo.

Dimensões: dim_store, dim_customer, dim_courier, dim_date (e turno, se o comparativo operacional exigir).

07 — Data Quality

Qualidade aqui não é só “não nulo”. O motor de auditoria usa regras nomeadas, com severidade e vínculo a impacto estimado:

• atraso acima do limite no aceite pelo restaurante;
• tempo de preparo fora do padrão;
• violação de SLA de entrega;
• cancelamento após início de preparo;
• inconsistência entre valor cobrado, taxas e status de pagamento;
• sequência inválida (ex.: entrega antes de despacho);
• pedido sem entregador em janela crítica.

Contrato típico de ocorrência:

{
  "order_id": "987",
  "flag_type": "cancel_after_prep",
  "severity": "high",
  "estimated_loss": 22.5
}

O JSON ilustra o contrato da ocorrência: tipo de falha, gravidade e dimensão financeira estimada.

08 — Observabilidade

No recorte do repositório: logs das etapas do pipeline, materialização das flags e dashboards Streamlit sobre Gold + auditoria. Cada falha vira registro, não só linha no log. Isso permite tendência por tipo de flag, loja e turno.

09 — Trade-offs

• DuckDB em vez de warehouse gerenciado — o case precisa ser clonável e auditável localmente. Em produção, o Gold iria para o warehouse da organização.
• Pandas em vez de Spark — o volume do mock não justifica cluster. Processamento distribuído entra no recorte de streaming.
• Sem Kafka neste case — o problema do MVP é auditoria em camadas batch, não lag de segundos. Streaming é evolução documentada à parte.
• Streamlit em vez de Power BI — velocidade de narrativa sobre as mesmas tabelas. BI corporativo consumiria Gold, não substituiria o pipeline.
• Mock FastAPI em vez de fonte real — permite injetar falhas e versionar cenários. Integração com ERP/PDV é evolução, não o recorte atual.

10 — Resultado

O repositório entrega:

• pipeline Bronze → Silver → Gold → auditoria, executável ponta a ponta;
• regras de negócio como código;
• modelagem dimensional documentada;
• dashboards de exploração sobre flags e fatos.

Com fonte real, o mesmo desenho sustenta tempo por etapa, taxa de cancelamento, aderência a SLA, volume de inconsistências por tipo de flag e perda operacional estimada sob premissa explícita. Este case usa dados simulados; por isso não reporta KPI de produção.

11 — O que deu errado

A primeira narrativa do projeto era a de sempre: volume e dashboard. Isso descrevia o “quanto” e não o “onde quebrou”. O dado existia; o controle não.

O problema era semântica. Check genérico não prioriza loja, turno nem tipo de falha. Corrigi deslocando o centro do desenho para o motor de auditoria: regra nomeada, severidade, impacto estimado, grão estável no fato.

Segundo atrito: tratar qualidade como etapa final. Sem Bronze preservado, reprocessar regra vira retrabalho. A correção foi insistir em camadas e replay, mesmo num mock.

12 — Código

Código, API mock, pipeline, Streamlit e docs (docs/architecture.md, docs/data_model.md, docs/audit_rules.md) estão em Raphaeldaysc/Delivery-Projeto.