Campo Float no Odoo: O Guia Completo

Introdução

O campo Float é um dos tipos de campo mais utilizados no Odoo quando os seus dados envolvem números decimais. Preços unitários, pesos de produtos, percentagens de desconto, taxas de imposto, fatores de conversão em listas de materiais - todos estes são tipicamente armazenados como campos Float no modelo de dados do Odoo.

À primeira vista, parece uma entrada numérica simples. Mas há várias coisas que vale a pena saber sobre como ele lida com precisão, como se comporta em relatórios e agregações, e quando você deve usar um tipo de campo diferente.

Este guia cobre o que o campo Float armazena, como se comporta no framework Odoo, como criá-lo e personalizá-lo usando o Odoo Studio ou Python, e casos de uso reais em Vendas, Inventário e Contabilidade.

O que é o campo Float no Odoo

No ORM do Odoo, o campo Float armazena números decimais. Ele mapeia para uma coluna de double precision no PostgreSQL, que fornece até 15 dígitos significativos de precisão. Para a maioria dos casos de uso empresarial, isso é muito mais do que você precisa.

Do ponto de vista do usuário, um campo Float aparece como uma entrada numérica nas visualizações de formulário. O número de casas decimais exibidas é controlado pelo parâmetro digits que você define no campo. Nas visualizações de lista, os valores Float são exibidos com a mesma precisão e são alinhados à direita por padrão. Em tabelas dinâmicas e gráficos, os campos Float participam de agregações como soma, média ou máximo.

Aqui está como fica em uma definição de modelo Python:

from odoo import fields, models

class SaleOrderLine(models.Model):
    _inherit = 'sale.order.line'

    custom_margin = fields.Float(
        string='Custom Margin',
        digits=(5, 2),
        default=0.0,
    )

O parâmetro digits é uma tupla. O primeiro número é o total de dígitos significativos, o segundo é o número de casas decimais. Assim, (5, 2) permite até cinco dígitos significativos com duas casas decimais.

Você também pode referenciar um grupo de precisão nomeado em vez de codificar os dígitos:

price_premium = fields.Float(
    string='Price Premium',
    digits='Product Price',
)

O Odoo tem vários grupos de precisão integrados gerenciados em Configurações > Técnico > Estrutura do Banco de Dados > Precisão Decimal. Os principais incluem Preço do Produto, Unidade de Medida do Produto, Desconto e Peso em Estoque. Usar grupos de precisão significa que os usuários podem ajustar a precisão decimal pela interface sem nenhuma alteração de código.

No Odoo Studio, o campo Float é rotulado como Número Decimal. Quando criado através do Studio, ele usa a precisão padrão, a menos que você o configure de outra forma no painel de propriedades do campo. Isso o torna um dos campos mais acessíveis do Odoo Studio para usuários de negócios que precisam estender formulários sem suporte de desenvolvedor.

Como o campo funciona

Quando você define um campo Float no Odoo, o framework cuida da criação da coluna no banco de dados automaticamente durante a instalação ou atualização do módulo. Nenhum SQL manual ou scripts de migração são necessários.

O parâmetro digits controla duas coisas ao mesmo tempo: como os valores são exibidos na interface e como eles são arredondados antes de serem armazenados. Se você definir digits=(6, 2) e um usuário inserir 3.14159, o Odoo arredonda e armazena 3.14. Esse arredondamento acontece no nível ORM, não apenas na camada de exibição.

Atributos Chave do Campo

Estas são as propriedades mais importantes que você pode configurar em um campo Float no framework Odoo:

• dígitos: Uma tupla como (6, 2) ou uma string de grupo de precisão nomeada. Controla tanto a precisão de exibição quanto a de armazenamento.
• obrigatório: Torna o campo obrigatório. Um campo Float com um valor de 0.0 passará na verificação de obrigatório, o que pode não ser sempre o comportamento pretendido.
• padrão: Valor padrão quando um novo registro é criado. Definir default=0.0 garante que o campo sempre tenha um valor numérico em vez de False.
• calcular: Liga um método Python que calcula o valor do campo dinamicamente. Útil para valores derivados como margens ou resultados de conversão em campos computados do odoo.
• armazenar: Quando usado com calcular, salva o valor computado no banco de dados para que possa ser pesquisado, filtrado e agrupado.
• operador_de_grupo: Controla como o campo é agregado em visualizações de pivot e gráfico. Valores comuns são 'soma', 'média', 'mínimo' e 'máximo'. Campos Float têm como padrão 'soma'.
• copiar: Controla se o valor é copiado ao duplicar um registro. O padrão é True.

Como Aparece nas Visualizações

Em visualizações de formulário, um campo Float é renderizado como uma entrada numérica. A exibição respeita a localidade do usuário para separadores decimais. Em visualizações de lista, os valores Float são alinhados à direita por padrão. Em visualizações de pesquisa, você pode filtrar por valores Float usando operadores de comparação numérica.

Você pode aplicar widgets a campos Float em visualizações. O widget percentagem, por exemplo, multiplica o valor armazenado por 100 para exibição e adiciona um sinal de porcentagem, o que é útil para campos que armazenam valores na faixa de 0-1. Este é um padrão comum no desenvolvimento do Odoo ao trabalhar com taxas e fatores.

Interação com o ORM do Odoo

Ler um campo Float fornece um float Python, ou False se o campo não foi definido e nenhum padrão está definido. Escrever em um campo Float aceita inteiros, floats ou False. O ORM aplica a precisão de dígitos no momento da salvamento.

Uma nota importante para o desenvolvimento do Odoo: não compare valores Float com == em Python. Devido à forma como a aritmética de ponto flutuante funciona a nível de hardware, valores que parecem iguais podem não ser. Use float_compare e float_is_zero de odoo.tools.float_utils em vez disso, que respeitam a precisão do campo definida no seu modelo de dados Odoo.

Casos de uso empresarial

O campo Float aparece em quase todos os módulos de uma implementação Odoo. Aqui estão cinco exemplos práticos de fluxos de trabalho empresariais reais.

Vendas: Percentagens de Desconto nas Linhas de Pedido

O campo nativo discount em sale.order.line é um campo Float. Quando um representante de vendas aplica um desconto de 15%, o Odoo armazena 15.0 e aplica-o ao cálculo do preço unitário. Este valor flui para orçamentos impressos e faturas de clientes, e participa em relatórios de margem. Acertar os descontos é importante tanto para a comunicação com o cliente quanto para a análise da rentabilidade do negócio.

Inventário: Pesos e Volumes de Produtos

Os produtos no Odoo têm campos nativos de weight e volume, ambos Floats. Um produto que pesa 2.5 kg ou ocupa 0.003 m3 precisa de precisão decimal que um campo Integer simplesmente não pode fornecer. Esses valores alimentam diretamente os cálculos de custo de envio e integrações com transportadoras. Se você estiver usando o Odoo com um conector de entrega, valores Float precisos em peso e volume determinam a tarifa de envio retornada pela API da transportadora.

Contabilidade: Taxas de Imposto

As taxas de imposto em account.tax são campos Float. Um IVA padrão de 21% é armazenado como 21.0, uma taxa reduzida pode ser 6.0 ou 5.5. O motor de contabilidade do Odoo lê esses valores para calcular os montantes de imposto em cada fatura e conta de fornecedor. A precisão é importante aqui porque pequenas diferenças de arredondamento podem se acumular ao longo de centenas de transações e causar discrepâncias nos relatórios de impostos.

Fabricação: Quantidades da Lista de Materiais

Na Fabricação do Odoo, a quantidade de cada componente em uma lista de materiais é um campo Float. Uma receita pode exigir 0.75 litros de um ingrediente líquido ou 2.5 kg de uma matéria-prima. Os campos Float lidam naturalmente com essas quantidades fracionárias. Usar um campo Integer neste contexto forçaria o arredondamento e introduziria erros de produção que se acumulam ao longo do tempo.

Compra: Fatores de Preço e Margens de Fornecedor

Ao configurar listas de preços de fornecedores ou regras de markup, os campos Float armazenam os multiplicadores e margens. Um fator de margem de 1.25 (25% de markup) ou um fator de desconto de 0.85 (15% de desconto sobre o preço de tabela) são valores típicos na lógica de preços de compra. Esses valores Float alimentam os cálculos automáticos de preços em pedidos de compra e ajudam as equipes de compras a manter preços consistentes entre os fornecedores.

Criando ou personalizando o campo Float

Existem três maneiras principais de adicionar um campo Float a um modelo Odoo, dependendo do seu contexto técnico e abordagem de implementação.

Usando Odoo Studio (Sem Código)

O Odoo Studio é a ferramenta de personalização de baixo código integrada. Para adicionar um campo Float sem escrever nenhum código:

1. Abra o Odoo Studio a partir do menu principal.
2. Navegue até o formulário onde você deseja o campo.
3. Arraste um campo Número Decimal do seletor de campos para o formulário.
4. Defina o rótulo, o valor padrão e o número de casas decimais no painel de propriedades.
5. Salve e feche o Studio.

O Studio cria o campo com um prefixo x_studio_ e o adiciona automaticamente à visualização do formulário. Nenhum trabalho de banco de dados é necessário da sua parte. Esta é uma das maneiras mais acessíveis de criar campos no Odoo para usuários que desejam personalização do Odoo sem complexidade técnica.

Usando Python em um Módulo Personalizado

Para desenvolvedores que estão construindo módulos Odoo, os campos Float são definidos diretamente em Python. Esta é a abordagem recomendada para qualquer desenvolvimento Odoo que precise ser versionado e implantado em vários ambientes:

from odoo import fields, models

class ResPartner(models.Model):
    _inherit = 'res.partner'

    x_credit_limit = fields.Float(
        string='Limite de Crédito',
        digits=(12, 2),
        default=0.0,
        help='Saldo máximo em aberto permitido para este cliente.',
    )

Após adicionar o campo ao modelo, inclua-o na XML da vista relevante para que apareça na interface. O Odoo trata automaticamente da coluna do banco de dados na instalação ou atualização do módulo. Esta é a abordagem padrão do guia do desenvolvedor Odoo para qualquer trabalho sério de personalização do Odoo.

Usando a API XML-RPC

Se você estiver gerenciando personalizações do Odoo programaticamente, por exemplo, através de um script de implantação ou um caderno de configuração remota, você pode criar campos Float via a API XML-RPC:

field_id = models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'ir.model.fields', 'create',
    [{
        'name': 'x_custom_coefficient',
        'field_description': 'Coeficiente Personalizado',
        'model_id': model_id,
        'ttype': 'float',
        'state': 'manual',
    }]
)

O valor state: manual informa ao Odoo que este campo foi criado manualmente em vez de por um módulo, que é a configuração correta para campos criados através do Studio ou da API. A precisão decimal para campos Float criados pela API é gerida através das configurações de Precisão Decimal no menu técnico. Esta é a abordagem que a Dasolo utiliza para a criação remota de campos como parte de scripts de configuração automatizada do Odoo.

Melhores práticas

1. Use grupos de precisão nomeados para valores padrão

Em vez de codificar digits=(6, 2), faça referência a um grupo de precisão como 'Preço do Produto' ou 'Unidade de Medida do Produto'. Isso permite que usuários com acesso técnico ajustem a precisão a partir da interface sem alterações de código, e alinha seus campos personalizados com a mesma precisão que os campos nativos do Odoo no mesmo contexto.

2. Use Monetário para quantias em moeda, não Float

Este é o ponto mais importante desta lista. O campo Monetário é especificamente projetado para quantias que têm uma moeda. Ele se liga a um campo de moeda no mesmo modelo, lida com arredondamento de acordo com as regras de moeda e funciona corretamente em ambientes de múltiplas moedas. Usar um campo Float para quantias de fatura ou preços de venda causará inconsistências de arredondamento e quebrará relatórios de múltiplas moedas.

3. Sempre defina um valor padrão

Defina default=0.0 para campos numéricos que devem começar em zero. Sem um padrão, o valor do campo é False (nulo no banco de dados) até que o usuário o preencha. Isso pode causar erros inesperados em campos computados ou métodos Python que assumem que um valor numérico está sempre presente.

4. Defina group_operator para relatórios

Se um campo Float representa uma quantidade ou montante que faz sentido somar em relatórios, adicione group_operator='sum'. Se representa uma taxa ou uma porcentagem onde a média faz mais sentido, use group_operator='avg'. Acertar isso garante que as tabelas dinâmicas e as visualizações gráficas agreguem seus dados de forma significativa, o que é muito importante nos campos do banco de dados Odoo usados para análise.

5. Documente suas convenções de porcentagem

Se um campo Float armazena uma porcentagem, seja explícito sobre se usa uma faixa de 0-100 (como o campo nativo discount: 15.0 para 15%) ou uma faixa de 0-1 (como alguns campos de margem: 0.15 para 15%). Misturar essas convenções em um modelo de dados produz erros de cálculo silenciosos que são muito difíceis de rastrear depois.

Erros comuns

Usando Float para montantes monetários

Os campos Float não carregam informações de moeda. Um campo Float mostrando 1500 poderia ser euros, dólares ou qualquer outra coisa. Em uma configuração Odoo multi-moeda, isso leva a totais incorretos em relatórios financeiros. Use o tipo de campo Monetary para qualquer montante que tenha uma moeda.

Não definir o parâmetro digits

Sem digits explícito, o Odoo aplica uma precisão padrão de Float de 2 casas decimais. Isso é aceitável para preços, mas não para campos que precisam de 4 ou 6 casas decimais, como taxas de câmbio ou fatores de conversão de unidades. Um fator de conversão arredondado silenciosamente para 2 casas decimais produzirá erros acumulados em cada transação que o utiliza.

Comparando valores Float com == em Python

Devido à forma como os números de ponto flutuante funcionam a nível de hardware, dois valores Float que parecem idênticos podem não ser iguais quando comparados com ==. Por exemplo, 0.1 + 0.2 == 0.3 avalia como False em Python. Use float_compare(value1, value2, precision_digits=2) e float_is_zero(value, precision_digits=2) de odoo.tools.float_utils para comparações confiáveis. Este é um ponto comum em qualquer tutorial técnico do Odoo sobre o assunto.

Usando Float quando Integer é a escolha certa

Se um campo sempre contém números inteiros, como uma contagem, um número de pacotes ou um número de sequência, use um campo Integer em vez disso. Campos Float para números inteiros não são tecnicamente errados, mas criam confusão desnecessária e convidam os usuários a inserir valores decimais onde nenhum faz sentido no contexto de negócios.

Não lidar com valores False em métodos de cálculo

Um campo Float sem um valor padrão retorna False (não 0.0) quando nenhum valor foi definido ainda. Se você estiver realizando cálculos com base em campos Float, sempre verifique se é False antes de fazer operações aritméticas, ou simplesmente adicione default=0.0 à definição do campo. Isso previne exceções TypeError em métodos de cálculo que só aparecem durante cenários de dados reais.

Conclusão

O campo Float é um bloco de construção fundamental do modelo de dados do Odoo. Ele lida com números decimais em preços, quantidades, taxas e medições, e faz isso de forma confiável quando configurado com a precisão e os padrões corretos.

As principais coisas a ter em mente: use grupos de precisão nomeados para valores padrão, use Monetário em vez de Float para quantias em moeda, sempre defina um valor padrão e documente suas convenções para campos de porcentagem. Esses hábitos previnem os problemas mais comuns de qualidade de dados antes que tenham a chance de causar problemas em produção.

Seja você adicionando campos através do Odoo Studio, escrevendo um módulo Python personalizado ou gerenciando seu modelo de dados programaticamente via Odoo ORM ou API XML-RPC, acertar os campos Float desde o início resulta em uma implementação mais limpa e confiável no geral.

Na Dasolo, ajudamos empresas a implementar, personalizar e otimizar o Odoo em todos os departamentos. Se você precisa de ajuda para projetar um modelo de dados limpo, adicionar campos personalizados aos seus formulários ou construir um módulo Odoo completo do zero, nossa equipe está aqui para apoiá-lo. Entre em contato conosco e vamos conversar sobre o seu projeto Odoo.