Cálculo de Custos

Código analisado: project/web/dashboard/cost/ (views.py, api.py, serializers.py, urls.py), project/cdata/api/cropyear/calendar.py e project/cdata/models_api/products/__init__.py. Data da análise: 28/08/2026. Revise este documento se o código-fonte mudar.

Este documento explica, em linguagem de negócio, como o custo de uma operação é apurado no sistema, quais variáveis estão envolvidas, os períodos considerados para cada categoria e os endpoints disponíveis para consulta.

O cálculo é centralizado na API de custos (project/web/dashboard/cost/) e é apresentado por Atividade de Talhão (Parcel_Activity).

1. Visão geral — Grupos de custo

Para cada Atividade de Talhão são apurados quatro grupos de custo:

Grupo	Campo	Origem	Forma de atribuição
Insumos	`total_products`	Produtos aplicados na atividade (OS)	Direto da OS (`dosage × preço`)
Combustível	`total_fuels`	Entradas de combustível da organização	Rateio por área (`work_area_ha`)
Despesas	`total_expenses`	Despesas operacionais da organização	Rateio por área (`work_area_ha`)
Terceiros	`third_party_cost`	Custo de terceiros lançado na OS	Direto da OS (`custo por ha x area da atividade`)

Diferença fundamental: os insumos e os custos de terceiros são atribuídos diretamente à atividade — sabe-se exatamente o que foi aplicado/gasto em cada talhão. Já combustível e despesas não são lançados atividade a atividade: são somados para a organização inteira e depois distribuídos proporcionalmente à área trabalhada (work_area_ha) de cada atividade.

Custo de terceiros é um valor lançado diretamente na Ordem de Serviço. Ele é retornado isoladamente no payload e não é somado em total_products, total_fuels ou total_expenses.

2. Endpoints disponíveis

Todos os endpoints de custo estão sob project/web/dashboard/cost/urls.py.

Endpoint	View	Filtros extras	Exige `can_view_costs`
`parcels/<cs_year>`	`Parcel_Activity_Cost`	—	Sim
`farm/<farm_id>/<cs_year>`	`Farm_Cost`	Fazenda	Sim
`parcel/<parcel_id>/<cs_year>`	`Parcel_Cost`	Talhão	Sim
`serviceorder/<serviceorder_id>`	`ServiceOrder_Cost`	OS (safra inferida — ver §4.3)	Sim
`product/<cs_year>`	`Product`	—	Não (só autenticação)
`meta/<cs_year>`	`Dashboard_Meta`	—	Não (só autenticação)

Importante: mesmo nos endpoints filtrados por fazenda, talhão ou OS, o denominador de área usado no rateio de combustível e despesas é sempre a área total da organização na safra — não a área do filtro. Ou seja, o rateio é calculado sobre o total da organização e depois aplicado às atividades retornadas pelo filtro.

3. Períodos — dois conceitos distintos

O sistema utiliza dois períodos diferentes dependendo do tipo de dado. Esta distinção é intencional e foi solicitada pelo time de negócio.

3.1 Período da safra (cropyear) — Abr a Mar

Início: 1º de abril do ano da safra − 1
Fim: 31 de março do ano da safra

Exemplo — safra 2025: de 01/04/2024 a 31/03/2025.

Este período é usado para:

Selecionar atividades elegíveis (direto por cs_year ou atividades de preparo de solo por dt_end dentro do período).

3.2 Ano-calendário — Jan a Dez

Início: 1º de janeiro do ano da safra
Fim: 31 de dezembro do ano da safra

Exemplo — safra 2025: de 01/01/2025 a 31/12/2025.

Este período é usado para:

Filtrar entradas de combustível pela data (dt).
Filtrar despesas operacionais pela data (dt).
Apurar o preço médio de insumo (Product_CropSeason_AvgPrice).

Por que a diferença? As atividades agrícolas seguem o ciclo da safra (Abr–Mar). Já as despesas indiretas (combustível e despesas operacionais) e o preço médio de insumo são apurados pelo ano-calendário (Jan–Dez), pois refletem custos financeiros incorridos no ano civil.

3.3 Preço médio de insumo — detalhamento

O preço médio do produto (Product_CropSeason_AvgPrice) é apurado por ano-calendário:

Coletam-se as entradas de produto (Product_Stock_Entry) da organização no ano-calendário, com qty > 0 e unity_price >= 0.
Se houver mais de 5 entradas, o preço é a média ponderada (peso = quantidade qty) dos preços unitários.
Se houver 5 ou menos entradas, o preço fica 0.

Fallback de mercado (check_fallback_cropseason_avg_price):

Quando o preço médio está 0, o sistema substitui pelo preço médio de mercado do produto (SKU) — campo avg_price_market.
Esse fallback é executado sempre que uma nova entrada de produto é registrada ou uma nova Ordem de Serviço consome o produto. Por isso ele funciona como fallback automático: ao ocorrer um desses eventos, o preço é reavaliado e, se necessário, atualizado com o valor de mercado.

No momento do cálculo de custo, o endpoint apenas lê o preço armazenado em Product_CropSeason_AvgPrice. Se o registro não existir ou o preço for None, o custo do produto fica 0 — o fallback só garante um valor se tiver sido disparado previamente por uma entrada ou consumo.

3.4 Resolução de safra na consulta por Ordem de Serviço

O endpoint serviceorder/<serviceorder_id> não recebe a safra na URL. A safra é inferida a partir das atividades da OS (resolve_cs_year_for_serviceorder):

Consideram-se as atividades da OS com work_area_ha > 0 e dt_end preenchido.
Para cada atividade, o ano é cs_year (se preenchido) ou o ano-safra derivado de dt_end.
Soma-se a work_area_ha por ano.
A safra escolhida é a do ano com maior área trabalhada. Em caso de empate na área, vence o ano maior.
Se nenhuma atividade for elegível, retorna erro ("Safra não pode ser nula").

4. Regras de elegibilidade

Uma Atividade de Talhão só entra no cálculo de custo se:

A Ordem de Serviço (OS) estiver encerrada (dt_close preenchido).
A atividade tiver área trabalhada maior que zero (work_area_ha > 0).
A atividade pertencer à safra consultada:
cs_year igual à safra; ou
atividade de preparo de solo (cs_year = 0) com dt_end dentro do período da safra (Abr–Mar).

Denominador de área (combustível e despesas): a soma da área trabalhada de todas as atividades elegíveis da organização na safra — independentemente do filtro (fazenda/talhão/OS) aplicado ao endpoint.

5. Fórmulas e variáveis por grupo

5.1 Insumos (produtos) — `total_products`

Cada produto aplicado gera um custo:

prod_cost = dosage × preço_médio_do_produto (ano-calendário)

dosage: dose/quantidade aplicada do produto na atividade.
preço_médio: vem de Product_CropSeason_AvgPrice, filtrado por org_id, cropseason = cs_year (ano da safra) e product_id. Apurado por ano-calendário como média ponderada (ver §3.3).
prod_cost é arredondado para 3 casas decimais.
Se o preço médio for None (registro inexistente), prod_cost fica 0.
total_products = soma de todos os prod_cost da atividade, arredondada para 3 casas decimais.

O detalhamento por produto é retornado no campo products (lista com product_id e prod_cost).

5.2 Combustível — `total_fuels`

Não é atribuído por atividade; é distribuído por área, agrupado por tipo de combustível (fuel_type):

price_ha (por tipo) = Σ(qty × unity_price) ÷ área_total_org total_fuels = Σ(price_ha de todos os tipos) × work_area_ha

qty × unity_price: quantidade × preço unitário de cada entrada de combustível no ano-calendário (Jan–Dez).
área_total_org: soma das áreas trabalhadas de todas as atividades elegíveis da organização na safra.
Resultado é arredondado para 3 casas decimais.

O detalhamento por tipo de combustível é retornado no campo fuels (lista com fuel_type e total_price = price_ha × work_area_ha).

5.3 Despesas operacionais — `total_expenses`

Distribuído por área, agrupado por centro de custo (activity__cost_center__name):

price_ha (por centro de custo) = Σ(value) ÷ área_total_org total_expenses = Σ(price_ha de todos os centros) × work_area_ha

value: valor de cada despesa operacional no ano-calendário (Jan–Dez).
área_total_org: mesmo denominador do combustível.
Resultado arredondado para 3 casas decimais.

O detalhamento por centro de custo é retornado no campo expenses (lista com activity__name = nome do centro de custo, e total_price).

Nota: o campo no serializer chama-se activity__name, mas o valor exibido é o nome do centro de custo (activity__cost_center__name), não o nome da atividade de despesa.

5.4 Custo de terceiros — `third_party_cost`

Valor lançado diretamente na Ordem de Serviço referente a custos de terceiros. É retornado isoladamente no payload e não compõe nenhum dos três totais acima. Não passa por rateio nem cálculo — é lido diretamente do registro da Atividade de Talhão.

6. Métricas de apoio (`Dashboard_Meta`)

O endpoint meta/<cs_year> entrega métricas de contexto para o dashboard:

org_active_area: soma de area_ha dos talhões ativos na safra (Parcel_CropSeason com cropseason = cs_year).
tch_avg: TCH médio ponderado por área: TCH = Σ(tch × area_ha) ÷ Σ(area_ha) — usa tch ou, se vazio, o fallback tch_pred. Arredondado para 2 casas decimais.
cropseason_options: lista de safras disponíveis para seleção, obtida a partir de:
cs_year das atividades da organização (ano-safra);
dt_end das atividades de preparo de solo (cs_year = 0), convertido para safra;
dt das entradas de combustível, convertido para ano-calendário;
dt das despesas operacionais, convertido para ano-calendário;
mais a safra corrente (data de hoje).
A lista é deduplicada e ordenada.
cropseason_current: safra corrente derivada da data de hoje.

Atenção: cropseason_options mistura valores de ano-safra (atividades) e ano-calendário (combustível e despesas). Isso é uma consequência direta do código e pode gerar opções que não correspondem a safras reais de atividades.

7. Tabela-resumo

Grupo	Fonte principal	Forma de atribuição	Período dos valores	Preço/valor base
Insumos	Produtos aplicados na atividade	Direto à atividade (`dosage × preço`)	Atividade na safra	Preço médio ano-calendário
Combustível	Entradas de combustível	Rateio por área (`work_area_ha`)	Ano-calendário (Jan–Dez)	Σ(qty × unity_price)
Despesas	Despesas operacionais	Rateio por área (`work_area_ha`)	Ano-calendário (Jan–Dez)	Σ(value)
Terceiros	OS	Direto da OS (sem rateio)	—	`third_party_cost`

Resumo para suporte: custos de insumo e terceiros são atribuídos diretamente à atividade. Custos de combustível e despesas são estimados e rateados pela área trabalhada de cada atividade, tomando o total da organização. Atividades seguem o período da safra (Abr–Mar); combustível, despesas e preço médio de insumo seguem o ano-calendário (Jan–Dez).

8. Pontos de atenção

Denominador de área é sempre da organização: mesmo em endpoints filtrados por fazenda, talhão ou OS, o rateio de combustível e despesas usa a área total da organização. Os filtros só limitam quais atividades são retornadas, não o denominador do rateio.
Dois períodos distintos: atividades usam safra (Abr–Mar); combustível, despesas e preço médio de insumo usam ano-calendário (Jan–Dez). Isso é intencional e foi solicitado pelo time de negócio.
Fallback de mercado é assíncrono: o fallback só é aplicado quando uma entrada de produto ou consumo em OS dispara check_fallback_cropseason_avg_price. Se nenhum desses eventos ocorreu, o preço pode estar 0 ou o registro pode não existir — resultando em custo 0 para o produto.
cropseason_options mistura conceitos: a lista de safras disponíveis combina ano-safra (atividades) e ano-calendário (combustível/despesas).
third_party_cost não compõe os totais: é um valor isolado no payload, lido diretamente da OS.
Permissões: Product e Dashboard_Meta exigem apenas autenticação; os demais endpoints exigem can_view_costs.