Campos Computados Armazenados no Odoo: Guia Completo

Introdução

Se você passou tempo trabalhando com Odoo, provavelmente encontrou campos que calculam seu valor automaticamente. Um campo computado armazenado leva isso um passo adiante: ele calcula o valor e o salva diretamente no banco de dados.

Essa distinção é mais importante do que pode parecer à primeira vista. Um campo que apenas calcula em tempo real não pode ser pesquisado, filtrado, agrupado ou exportado de forma eficiente. Um campo computado armazenado pode. Ele se comporta como uma coluna de banco de dados regular, enquanto ainda é impulsionado pela lógica que você define.

Este guia cobre tudo o que você precisa saber sobre campos computados armazenados no Odoo: como eles funcionam dentro do modelo de dados do Odoo, como criá-los usando o Odoo Studio ou Python, casos de uso empresarial reais e os erros mais comuns a evitar.

O que é um Campo Computado Armazenado no Odoo

No ORM do Odoo, cada campo em um modelo contém um pedaço de dados. A maioria dos campos armazena o que o usuário insere manualmente. Um campo computado é diferente: seu valor é gerado por uma função Python em vez de ser inserido por um usuário.

Um campo computado armazenado é simplesmente um campo computado com store=True. Quando suas dependências mudam, o Odoo executa a função de computação e escreve o resultado na coluna do banco de dados. O valor fica então disponível como qualquer outro campo.

Em Python, o padrão básico se parece com isto:

total_amount = fields.Float(
    string='Total Amount',
    compute='_compute_total_amount',
    store=True,
)

@api.depends('quantity', 'unit_price')
def _compute_total_amount(self):
    for record in self:
        record.total_amount = record.quantity * record.unit_price

O parâmetro store=True é o que separa um campo computado armazenado de um campo computado regular. Sem ele, o valor é recalculado toda vez que o campo é lido, mas nunca persistido no banco de dados.

Na interface do Odoo, um campo computado armazenado se parece exatamente com qualquer outro campo. Os usuários o veem em formulários, visualizações de lista e relatórios. Eles podem filtrá-lo, agrupar registros usando-o e incluí-lo em exportações. Não há indicador visual de que o valor é computado em vez de inserido.

Campos Computados Armazenados vs Não Armazenados

Entender essa diferença é essencial para qualquer trabalho de desenvolvimento Odoo:

• Campo computado não armazenado: Calculado em tempo real quando lido. Não pode ser usado em filtros, busca ou agrupamento. Mais leve em armazenamento, mas não disponível para consultas no banco de dados.
• Campo computado armazenado: Calculado quando as dependências mudam e salvo no banco de dados. Pesquisável, filtrável, exportável. Ocupa espaço no banco de dados como qualquer coluna regular.

A escolha entre os dois não é sobre qual é melhor em geral. Depende do que você precisa do campo. Se você apenas o exibe em um único formulário, o não armazenado é suficiente. Se você precisa filtrar, classificar ou agregar por ele, use o armazenado.

Como o Campo Funciona

Quando você define um campo computado armazenado no Odoo, o ORM configura gatilhos de recomputação automática com base nos campos listados no decorador @api.depends().

Sempre que qualquer um desses campos dependentes mudar em um registro, o Odoo marca esse registro como necessitando de recomputação. O método de computação é executado e o resultado é escrito de volta na coluna do banco de dados para aquele campo.

O Ciclo de Recomputa5o

Aqui est o que acontece passo a passo:

1. Um utilizador ou um processo automatizado altera um campo que est listado em @api.depends().
2. Odoo detecta a altera5o e identifica todos os registos que dependem deste campo.
3. O m todo de c lculo chamado para esses registos.
4. O valor calculado escrito na coluna do banco de dados.
5. O campo est agora disponível para pesquisa, filtro e exporta5o com o valor atualizado.

Na maioria dos casos, esta recomputa5o acontece imediatamente dentro da mesma transa5o. Para grandes opera5es em lote, o Odoo pode adiar algumas recomputa5es e process -las em segundo plano.

Depend ncias Entre Modelos Relacionados

O decorador @api.depends() suporta caminhos pontuados para acessar campos em modelos relacionados. Por exemplo:

@api.depends('partner_id.country_id.name')
def _compute_country_name(self):
    for record in self:
        record.country_name = record.partner_id.country_id.name or ''

Neste caso, o Odoo rastreia altera5es em partner_id, country_id e name entre modelos. Se o nome do pa s mudar em um parceiro, todos os registos relacionados s o automaticamente recomputados. Este um dos aspectos mais poderosos do framework Odoo.

Impacto na Base de Dados

Como o campo é armazenado, o Odoo cria uma coluna real na tabela do banco de dados PostgreSQL. Isso significa que o campo participa diretamente em consultas SQL. Pesquisas e filtros em campos computados armazenados são rápidos e eficientes, assim como pesquisas em campos regulares.

Casos de Uso Empresarial

Os campos computados armazenados aparecem em todas as áreas do Odoo. Aqui estão cinco exemplos práticos de fluxos de trabalho empresariais reais.

1. Vendas: Percentagem de Margem nas Linhas de Pedido

Uma equipe de vendas quer ver a percentagem de margem em cada linha de pedido de venda sem abrir uma calculadora. Um campo computado armazenado pega o preço unitário e o preço de custo, calcula a margem e a armazena na linha. O gerente de vendas pode então filtrar pedidos por percentagem de margem, encontrar linhas não rentáveis instantaneamente e agrupar por faixas de margem em visualizações de pivô.

2. CRM: Dias Sem Atividade em um Lead

Um campo computado armazenado no modelo de lead do CRM pode rastrear quantos dias se passaram desde a última atividade agendada. Combine isso com uma ação agendada que aciona a recomputação todas as manhãs, e sua equipe de vendas pode filtrar leads pelo limiar de inatividade. Nenhum acompanhamento manual necessário.

3. Inventário: Quantidade Líquida Disponível

Para produtos com regras de estoque complexas, um campo computado armazenado pode conter um valor pré-calculado, como a quantidade em mãos menos a quantidade reservada. Como o valor é armazenado, os gerentes de produto podem classificar e filtrar a lista de produtos por disponibilidade sem que o Odoo execute cálculos complexos de estoque ao vivo para cada linha na tela.

4. Contabilidade: Contagem de Faturas Vencidas por Cliente

No modelo de cliente, um campo computado armazenado pode contar quantas faturas estão atualmente vencidas. Quando a equipe de contabilidade abre a lista de contatos, pode classificar os clientes por contagem de faturas vencidas com um clique. Isso só é possível porque a contagem é armazenada no banco de dados em vez de ser calculada em tempo real para cada linha.

5. Manufatura: Duração Total Estimada do Trabalho

Em uma Lista de Materiais, um campo computado armazenado pode somar a duração estimada em todas as operações do centro de trabalho anexadas ao BOM. Os planejadores de produção podem então filtrar e classificar os BOMs pelo tempo total de trabalho, o que é útil para planejamento de capacidade e agendamento. Sempre que uma operação é adicionada ou modificada, o total é atualizado automaticamente.

Criando ou Personalizando o Campo

Existem duas maneiras principais de criar campos computados armazenados no Odoo: usando o Odoo Studio para casos simples ou escrevendo código Python em um módulo personalizado para controle total.

Usando o Odoo Studio

O Odoo Studio permite que você adicione campos computados sem escrever nenhum código. Quando você cria um novo campo do tipo Inteiro, Flutuante ou Monetário no Studio, pode ativar uma opção de fórmula que aceita uma expressão semelhante ao Python. O Studio lida com o rastreamento de dependências nos bastidores.

Os campos computados do Studio são uma boa opção quando a lógica é uma expressão aritmética simples entre campos no mesmo registro. Eles são fáceis de configurar e não requerem um ambiente de desenvolvimento. No entanto, eles têm limites reais. Se sua lógica envolver campos de modelos relacionados, ramificações condicionais ou agregação entre registros filhos, o Studio não será suficiente. Você precisará de um módulo personalizado.

Esta é uma distinção importante ao planejar sua personalização do Odoo: o Studio é rápido para casos diretos, mas o Python oferece total flexibilidade quando a lógica se torna complexa.

Usando um Módulo Python Personalizado

Para qualquer coisa além de fórmulas básicas, você define o campo em Python dentro de um módulo Odoo personalizado. Aqui está um exemplo concreto que adiciona um campo de percentual de margem às linhas de pedido de venda:

from odoo import models, fields, api

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

    x_margin_pct = fields.Float(
        string='Margin %',
        compute='_compute_margin_pct',
        store=True,
        digits=(5, 2),
    )

    @api.depends('price_unit', 'purchase_price')
    def _compute_margin_pct(self):
        for line in self:
            if line.price_unit:
                line.x_margin_pct = (
                    (line.price_unit - line.purchase_price) / line.price_unit
                ) * 100
            else:
                line.x_margin_pct = 0.0

Quando este módulo é instalado, o Odoo cria a coluna x_margin_pct no banco de dados, executa o método de computação para todos os registros existentes e começa a rastrear alterações em price_unit e purchase_price a partir daquele ponto.

O prefixo do campo x_ é a convenção para campos personalizados no Odoo para evitar conflitos com campos principais. Esta é uma prática padrão em desenvolvimento Odoo.

Tornando um Campo Computado Armazenado Editável

Por padrão, os campos calculados são somente leitura. Se você quiser que os usuários possam substituir o valor calculado manualmente, pode definir um método inverse ao lado do seu método de cálculo. O método inverso é executado quando um usuário escreve diretamente no campo e pode atualizar os campos de origem de acordo. Este padrão é útil para campos onde o valor calculado é um bom padrão, mas às vezes precisa de uma substituição manual.

Campos do Odoo Studio e a API XML-RPC

Para equipes que gerenciam campos de banco de dados Odoo através da API XML-RPC, você pode criar campos padrão via o modelo ir.model.fields. No entanto, para campos calculados armazenados com lógica Python personalizada, o próprio método de cálculo deve residir no código do lado do servidor. A abordagem da API funciona bem para provisionar campos simples como parte de implantações automatizadas, mas a lógica por trás de um campo calculado sempre requer um módulo personalizado instalado no servidor.

Melhores Práticas

Aqui estão as práticas que consultores experientes do Odoo seguem ao trabalhar com campos calculados armazenados.

Declare Todas as Dependências Precisamente

O decorador @api.depends() deve listar cada campo que seu método de cálculo lê. Se você esquecer um, o campo não será atualizado quando essa dependência mudar. Revise seu método de cálculo linha por linha e certifique-se de que cada acesso a campo esteja listado no decorador.

Mantenha os Métodos de Cálculo Rápidos

Seu método de cálculo é executado em cada registro que é afetado por uma mudança de dependência. Em uma instância Odoo movimentada, isso pode significar milhares de registros ao mesmo tempo. Evite consultas ao banco de dados dentro dos métodos de cálculo sempre que possível. Se você precisar acessar dados relacionados, use os campos que já estão carregados em vez de executar buscas adicionais.

Use store=True Apenas Quando Necessário

Campos armazenados consomem espaço no banco de dados e acionam operações de gravação em cada recomputação. Se você só precisa exibir o campo em uma visualização de formulário e nunca filtrar ou agrupar por ele, um campo calculado não armazenado é a opção mais leve. Tome essa decisão de forma deliberada em vez de optar por armazenado para tudo.

Lide com Casos Limite no Método de Cálculo

Sempre considere valores vazios ou ausentes dentro do seu método de cálculo. Divisão por zero, registros relacionados ausentes e valores nulos são causas comuns de erros silenciosos em campos calculados. Adicione verificações explícitas e defina valores padrão seguros quando o cálculo normal não puder prosseguir.

Planeie a Recomputa1 Inicial em Tabelas Grandes

Quando voc instala um m dulo que adiciona um novo campo computado armazenado, o Odoo o recomputa para cada registro existente na tabela. Em uma tabela com centenas de milhares de linhas, isso pode levar um tempo significativo. Teste sua migra1 em um ambiente de teste primeiro e planeje um potencial tempo de inatividade ou processamento em segundo plano ao implantar em produ1.

Evite Dependncias Circulares

Se o campo A depende do campo B e o campo B depende do campo A, o Odoo gerará um erro quando o m dulo for carregado. Projete suas dependncias de campos computados para fluir em uma c1o apenas.

Armadilhas Comuns

Esquecer store=True

Este o erro mais comum. O campo exibe corretamente na visualiza1 do formul rio, ent o tudo parece bem durante os testes. Depois, alguém tenta adicion-lo como um filtro ou inclu-lo em um relat rio, e isso n o funciona. Antes de escrever qualquer l gica de computa1, decida de antem1o se precisa que o campo seja pesquis vel. Se sim, adicione store=True desde o comeo.

Faltando uma Dependncia em @api.depends

Se seu m todo de computa1 ler partner_id.country_id, mas seu decorador lista apenas partner_id, o campo n o ser atualizado quando o pa s mudar no registro do parceiro. Rastreie o caminho completo de cada acesso a campo em seu m todo e liste cada passo explicitamente no decorador.

Erros Silenciosos no M todo de Computa1

Se seu m todo de computa1 gerar uma exce1 para um registro, o Odoo ignora silenciosamente a recomputa1 para esse registro e mantém o valor armazenado anterior. O erro pode aparecer nos logs do servidor, mas nada mostrado ao usu1rio. Isso pode levar a valores obsoletos ou incorretos que s o dif ceis de rastrear. Sempre teste seu m todo de computa1 contra registros que tenham dados ausentes ou incomuns.

Degrada1 de Desempenho em Grandes Conjuntos de Dados

Um m todo de computa1 que funciona bem durante o desenvolvimento pode se tornar um gargalo s rio em produ1 se a tabela crescer para dezenas de milhares de registros. Preste aten1 a quantas consultas ao banco de dados seu m todo de computa1 dispara por registro. Uma consulta extra por registro multiplicada por dez mil registros dez mil consultas para uma c1 salva.

Usando sudo() Dentro de Métodos de Cálculo

Chamar sudo() dentro de um método de cálculo para contornar direitos de acesso é um risco de segurança. Se o valor calculado expuser dados que o usuário atual não deveria ver, retorná-lo através de um método de cálculo derrota o modelo de permissões do Odoo. Use sudo() dentro de métodos de cálculo apenas quando você tiver pensado deliberadamente nas implicações de segurança.

Esperando Recomposição Imediata em Todos os Contextos

Na maioria das operações interativas, a recomposição é síncrona. Mas durante importações em lote, trabalhos em segundo plano ou certas operações ORM com flags de contexto, o Odoo pode adiar a recomposição. Não construa lógica de negócios que assume que o valor armazenado está sempre atualizado no exato momento em que um registro é escrito. Verifique o comportamento no contexto específico onde seu campo será usado.

Conclusão

Os campos computados armazenados são uma das ferramentas mais úteis disponíveis ao construir ou estender o Odoo. Eles permitem automatizar cálculos, manter seus dados consistentes e tornar registros pesquisáveis e exportáveis sem qualquer trabalho manual dos seus usuários.

Os pontos-chave a lembrar:

• Use store=True quando precisar que o campo seja pesquisável, filtrável ou exportável.
• Sempre declare todas as dependências em @api.depends(), incluindo caminhos entre modelos.
• Mantenha os métodos de cálculo rápidos e trate casos extremos explicitamente.
• Para fórmulas simples, o Odoo Studio é uma opção rápida. Para qualquer coisa mais complexa, escreva em Python.
• Planeje a recomposição inicial ao implantar em produção em tabelas grandes.

Seja você construindo um novo módulo personalizado, estendendo um modelo Odoo existente ou explorando tipos de campo Odoo pela primeira vez, os campos computados armazenados valem a pena serem compreendidos profundamente. Eles estão na interseção do ORM do Odoo, da camada de banco de dados e da sua lógica de negócios.

Precisa de Ajuda com a Sua Implementação do Odoo?

A Dasolo ajuda empresas a implementar, personalizar e otimizar o Odoo em uma ampla gama de necessidades empresariais. Quer precise adicionar campos calculados ao seu modelo de dados, construir relatórios baseados em valores calculados, ou levar o seu desenvolvimento Odoo mais longe, a nossa equipa tem a experiência para ajudar.

Entre em contato connosco se precisar de apoio com o seu projeto Odoo. Estamos felizes em discutir o seu caso de uso e encontrar a abordagem certa para o seu negócio.