4.4 - Aba Value: agregação, KPI e gauge
Aba Value — agregação, KPI e gauge
A aba Value aparece para tile, kpi e gauge. Ela controla como o número do card é calculado e comparado. Veja nos prints abaixo.
aggregation
Como o item resume os registros do model_id filtrados pelo domain e pela janela de data.
count
O que faz: search_count(domain). Simples e rápido — conta os registros.
Não exige measure_field_id.
sum
O que faz: Soma do campo numérico escolhido em measure_field_id.
Exige measure_field_id.
avg
O que faz: Média do campo numérico escolhido em measure_field_id.
Exige measure_field_id.
Print 1 — aba Valor com aggregation=Contagem (padrão, sem measure_field_id):
Repare que o campo measure_field_id não aparece — count não precisa dele.
Print 2 — ao trocar para aggregation=Soma, um campo novo aparece:
O campo Campo de medida aparece — é onde você escolhe expected_revenue, amount_total, etc.
O Campo de medida — aprofundamento
O measure_field_id é o campo numérico que será somado, contado ou medido. É o núcleo matemático do item. Vamos entender exatamente o que aceita.
Domínio técnico
O boardkit filtra o dropdown com a expressão NUMERIC_FIELD_DOMAIN:
[('model_id', '=', model_id),
('name', '!=', 'id'),
('store', '=', True),
('ttype', 'in', ['integer', 'float', 'monetary'])]
Quatro regras rígidas. O dropdown só mostra campos que passam todas.
4 regras que o campo deve cumprir
- Mesmo modelo do item (ou
model_2_idno Second Data Source). - Não ser
id— não dá pra somar o ID técnico. - Estar armazenado (
store=True) — campos computed puros não aparecem. - Tipo técnico:
integer,floatoumonetary.
| Tipo | Quando usar | Exemplos comuns |
|---|---|---|
| integer | Contagens inteiras: quantidade de registros, total de itens. | quantity, priority, sequence, employee_ids (count). |
| float | Métricas com casas decimais: pesos, durações, taxas, percentuais. | margin, duration, conversion_rate, hourly_rate. |
| monetary | Valores monetários armazenados (precisa ser monetary field no Odoo, não float com currency_id). |
expected_revenue, amount_total, amount_untaxed, price_subtotal. |
Atenção: float com currency_id não é monetary
Se o modelo tem um campo float ligado a um currency_id separado (em vez de ser declarado como fields.Monetary), ele só soma o número puro — sem conversão de moeda. Se você precisa somar valores monetários com conversão, o campo precisa ser monetary declarado.
Exemplos práticos por modelo Odoo
Combinações clássicas de modelo + campo + agregação:
| Modelo | measure_field_id recomendado | Agregação | Cenário |
|---|---|---|---|
crm.lead | expected_revenue monetary | sum | Pipeline total em R$ |
crm.lead | (nenhum — count) | count | Total de leads abertos |
sale.order | amount_total monetary | sum | Faturamento total |
account.move | amount_residual monetary | sum | Saldo a receber |
product.product | list_price monetary | sum | Valor de catálogo |
res.partner | (nenhum — count) | count | Total de contatos |
hr.employee | hourly_cost monetary | sum | Custo hora total |
project.task | planned_hours float | sum | Horas planejadas |
project.task | (nenhum — count) | count | Total de tarefas |
stock.move | product_uom_qty float | sum | Quantidade movimentada |
helpdesk.ticket | (nenhum — count) | count | Total de tickets |
Como descobrir o campo certo?
- Abra o Technical Settings → Database Structure → Fields no Odoo.
- Filtre pelo modelo (ex.:
crm.lead). - Procure colunas com
Stored = TrueeTypeeminteger,floatoumonetary. - Os campos monetários (Monetary) têm um
currency_fieldassociado. - O campo
idnunca serve — é o identificador interno.
compare_previous_period
Disponível para tile e kpi. Quando marcado, o boardkit calcula o valor da mesma janela deslocada para trás (_previous_date_range) e exibe um delta badge ao lado do número.
Print 3 — o checkbox Comparar com o período anterior marcado:
No preview à direita, o card agora mostra o número atual ao lado de um badge ↑ +12% ou ↓ -100% — a diferença vs o período anterior.
Requisitos do compare_previous_period
date_field_idconfigurado (campo de data do modelo).- Um filtro de data ativo (do item ou do dashboard).
- Sem isso, o badge simplesmente não aparece — não dá erro.
Grupo KPI (item_type=kpi)
4 campos extras controlam como o KPI exibe o resultado.
| Campo | O que faz | Valores |
|---|---|---|
kpi_mode |
Modo de comparação do KPI. Define como o segundo valor é obtido. | target ou comparison |
target_enabled |
Liga/desliga a meta. Só relevante no modo target. | True ou False |
target_value |
Valor numérico da meta. | 100000.0 |
kpi_display |
Como mostrar os dois valores lado a lado. | value sum ratio percent |
Os dois modos do kpi_mode
target
Compara o valor atual com um número fixo definido em target_value. Exemplo: receita esperada vs meta de R$ 100.000.
Exige target_enabled=True e target_value.
comparison
Compara o valor atual com o valor de outro modelo (model_2_id). Exemplo: oportunidades ganhas vs cota de vendas.
Exige model_2_id, domain_2, aggregation_2.
Second Data Source
Quando kpi_mode=comparison, aparece um subgrupo com os campos do segundo modelo:
| Campo | O que define |
|---|---|
model_2_id | Modelo a ser comparado (filtro ITEM_MODEL_DOMAIN). |
domain_2 | Filtro estático sobre o segundo modelo (widget domain). |
aggregation_2 | count / sum / avg — mesma lógica do item principal. |
measure_field_2_id | Campo numérico do segundo modelo. |
date_field_2_id | Campo de data do segundo modelo (opcional). |
_onchange_model_2_id
Ao trocar o segundo modelo, o boardkit limpa automaticamente domain_2, date_field_2_id e measure_field_2_id — evita lixo de campos incompatíveis.
Grupo Gauge (item_type=gauge)
Para gauges, há 3 campos que controlam a escala e a meta.
| Campo | O que faz | Padrão |
|---|---|---|
target_enabled | Liga/desliga o alvo. Sem alvo, mostra só o valor atual. | False |
target_value | Valor numérico da meta (linha de referência no gauge). | — |
gauge_max | Topo da escala. Quando vazio, o boardkit calcula max(value, target, 1) * 1.2. | auto |
Validações automáticas
Ao salvar, o boardkit roda 3 verificações que protegem contra configurações quebradas:
_check_fields_belong_to_model
Garante que measure_field_id, date_field_id etc. pertencem ao model_id.
_check_custom_dates
date_from <= date_to quando date_filter=custom. Evita intervalos invertidos.
_check_domains
O domínio é avaliado com safe_eval; se quebrar, o item fica com erro no preview.
Dica: tile mais rápido do boardkit
Para um tile simples (ex.: "Total de clientes"), deixe aggregation=count e measure_field_id vazio — é a forma mais rápida e mais barata de exibir um totalizador.
Agora que você domina a aba Value, vamos para a aba Chart — onde os gráficos ganham forma.
Detalhe da aba Value: aggregation, measure_field_id, compare_previous_period, alvo e o modo comparison entre dois modelos.
Por enquanto não há comentários.