Este modulo agrega resultados de rebates para a tela inicial do webapp (cards e tabela)
e para o modal de detalhes por rede.
Prefixo: /api/rebates-results
Vendas: Σ TOTAL NF no contexto do período de filtro.
Abatimentos: Σ Abatimentos no contexto do período de filtro.
Impertinência: Desconto a maior + Notas fiscais não localizadas + Produtos não incentivados + Abatimentos sem contratos
TradeRoi: Abatimento Total / Crescimento das Vendas.
Participação: Vendas Total / Vendas De uma Rede (Retornado em %).
Integração (Outro): Σ do Matched Value de Eventos Retornados no contexto do período de filtro.
Verba total por mecanismo: Verba_recorrente + Verba_por_evento + Verba_performance + Verba_pontual no contexto do período de filtro.
Verba recorrente: Desconto calculado das cláusulas percentuais e valores fixos recorrentes para o período do contexto.
Verba por eventos: Desconto calculado das cláusulas vinculadas a lojas (eventos) para o período do contexto.
Verba performance: Desconto calculado das cláusulas de crescimento/performance para o período do contexto.
Verba pontual: Verba total dos contratos pontuais para o período do contexto.
Participação fornecedor: (Verba_total_mecanismos_fornecedor / Verba_total_mecanismos_geral) × 100.
Crescimento das vendas: ((Vendas do periodo - Vendas do periodo anterior) / Vendas do periodo) * 100
View/union que consolida colunas de multiplas tabelas de resultados. Quando uma coluna nao existe em uma tabela, o valor vem NULL na view.
Os endpoints usam variaveis de ambiente para definir quais indicadores devem ser calculados e em qual ordem.
Detalhes e exemplos em docs/env.md.
INDICATORS_STATISTICS: lista de indicadores usada por GET /complete.SUMMARY_STATISTICS: lista de indicadores usada por GET /summary.INDICATORS_STATISTICS_MODAL: lista de indicadores usada por GET /by-retail-chain/{retail_chain_id} (modal).MONETARY_UNIT: unidade monetaria usada para compor IndicatorUnit (ex: R$).Obs: cada endpoint filtra os indicadores suportados pelo seu mapping. Entradas desconhecidas sao ignoradas (nao quebra o endpoint).
GET /api/rebates-results/complete -> cards/indicadores agregadosGET /api/rebates-results/summary -> tabela resumo (paginada)GET /api/rebates-results/by-retail-chain/{retail_chain_id} -> linhas para o modal de detalhes por redeGET /api/rebates-results/download/{retail_chain_id}/results/{result_label_id} -> exporta Excel do labelGET /api/rebates-results/<tabela>/ (paginado)GET /api/rebates-results/<tabela>/{id_} (quando a tabela tem campo id)Objetivo: retornar totais por rede e uma linha acumulada para renderizar a tabela principal do webapp.
SUMMARY_STATISTICS.SUMMARY_STATISTICS.server/rebates_results/service.py em functions_summary_indicator_mapping.Indicator em server/rebates_results/models/rebates_results_summary_model.py.Response model: ContractSummaryTable:
ContractSummaryTable(
legends=[SummaryLegend(name, unit), ...],
data=[ContractSummaryTableItem(retail_chain_id, name, values=[BaseIndicator(name, value), ...]), ...],
accumulated=ContractSummaryTableItem(retail_chain_id=None, name="ACCUMULATED", values=[BaseIndicator(...), ...]),
)
Objetivo: retornar indicadores consolidados para o periodo filtrado.
INDICATORS_STATISTICS.INDICATORS_STATISTICS.server/rebates_results/service.py em functions_per_detailed_indicator.Indicator em server/rebates_results/models/rebates_results_summary_model.py.Response model: lista de ContractSummaryIndicator:
[
ContractSummaryIndicator(
main_value=IndicatorValue(name, value, unit),
additional_values=[IndicatorValue(...), ...],
variation=Decimal | None,
primary=bool,
),
...
]
Nota: o service monta um grafo com gloe e executa em paralelo os indicadores independentes. Alguns indicadores dependem de outros (ex: TRADEROI).
Objetivo: retornar uma lista de linhas por result_label_id para uma rede, com indicadores para o modal de detalhes.
INDICATORS_STATISTICS_MODAL (valores do modal sao resolvidos pelo mapping de AdditionalIndicator).server/rebates_results/service.py em indicator_value_mapping.AdditionalIndicator em server/rebates_results/models/rebates_results_summary_model.py.Response model: RebatesConciliatedResultAggregate:
RebatesConciliatedResultAggregate(
legends=[SummaryLegend(name, unit), ...],
data=[
RebatesConciliatedResult(
retail_chain_id=int,
result_label_id=int,
report_type=str,
contract_type=str,
variation_reason=str | None,
indicators=[BaseIndicator(name, value), ...],
origin_table=str,
segment=str | None,
analytical_table=str | None,
goals_rules_invoices_analytical_table=str | None,
),
...
],
)
Notas:
SALES_PARTICIPATION e BUDGET_PARTICIPATION são calculados como percentual com base nos totais agregados retornados pelo repository.Objetivo: exportar um Excel com as linhas de resultados para um result_label_id.
Como funciona o mapping:
origin_table em server/rebates_results/repository.py usando a view SummarizedRebatesResultView.origin_table -> model fica em server/rebates_results/utils.py na variavel _RESULT_TABLE_MODEL_MAP..xlsx com colunas renomeadas.O controller registra endpoints GET para varios modelos de resultados. O padrão e:
GET /api/rebates-results/<tabela>/ (paginado)GET /api/rebates-results/<tabela>/{id_} (quando a tabela tem campo id)O nome da rota e o __tablename__ do modelo, com _ trocado por -. Para a lista completa, ver server/rebates_results/controller.py (variavel _RESULT_MODELS).