Introdução
Se você já definiu uma quantidade em um pedido de venda, acompanhou quantos dias uma tarefa esteve aberta ou configurou uma pontuação de prioridade em um lead, você usou um campo Inteiro no Odoo. É um dos tipos de campo mais comuns no modelo de dados do Odoo, e ainda assim é frequentemente subestimado.
Compreender como o campo Inteiro funciona é importante para usuários empresariais que configuram formulários, para desenvolvedores que escrevem módulos personalizados e para consultores que projetam modelos de dados para seus clientes.
Este guia abrange o que o campo Inteiro armazena, como se comporta na estrutura e interface do Odoo, como criá-lo ou personalizá-lo com o Odoo Studio ou Python, juntamente com casos de uso práticos e coisas a ter em mente.
O que é o Campo Inteiro no Odoo
No Odoo ORM, o campo Integer é projetado para armazenar números inteiros. Sem casas decimais, sem frações. Ele mapeia diretamente para uma coluna INTEGER no PostgreSQL, que é um inteiro com sinal de 4 bytes suportando valores de aproximadamente -2 bilhões a +2 bilhões.
Do ponto de vista do usuário, um campo Integer aparece como uma entrada numérica simples em formulários e como uma coluna numérica em visualizações de lista. É a escolha certa para qualquer coisa que deve ser contada em unidades inteiras: quantidades, pontuações, durações em dias, números de sequência ou qualquer métrica onde meio unidade não faz sentido.
Aqui está uma definição típica em um módulo Python:
from odoo import fields, models
class ProjectTask(models.Model):
_inherit = 'project.task'
estimated_hours = fields.Integer(
string='Estimated Hours',
default=0,
)O parâmetro string controla o rótulo exibido na interface. O parâmetro default define o valor automaticamente quando um novo registro é criado.
No Odoo Studio, este tipo de campo é listado simplesmente como Integer. Quando criado através do Studio, ele recebe um prefixo x_studio_. Quando criado via Python ou a API XML-RPC, você escolhe o nome técnico você mesmo.
Como o Campo Funciona
Quando você define um campo Integer no Odoo, o framework cria automaticamente a coluna correspondente no banco de dados durante a instalação ou atualização do módulo. Você não precisa escrever migrações SQL manualmente.
No nível do banco de dados, a coluna é tipada como INTEGER no PostgreSQL. O Odoo ORM cuida da coerção de tipo, então se o usuário não inserir nada, o campo retorna 0 em vez de None ou False. Esta é uma distinção importante em comparação com outros tipos de campo como Float ou Char, que podem retornar False quando vazios.
Atributos Chave do Campo
Aqui estão as propriedades mais importantes que você pode configurar em um campo Integer:
- string: O rótulo mostrado aos usuários na interface.
- default: O valor atribuído automaticamente a novos registros. Por padrão, é
0se não especificado. - obrigatório: Torna o campo obrigatório. Como o padrão já é
0, isso é mais útil quando você quer bloquear o salvamento com um valor zero. - somente leitura: Impede que os usuários editem o valor diretamente na interface.
- índice: Cria um índice PostgreSQL na coluna, acelerando filtros e buscas nesse campo.
- cálculo: Liga um método Python que calcula o valor do campo dinamicamente a partir de outros campos.
- armazenar: Combinado com
cálculo, controla se o valor calculado é salvo no banco de dados ou recalculado em tempo real. - copiar: Controla se o valor é transferido ao duplicar um registro.
- grupos: Restringe a visibilidade do campo a grupos de usuários específicos.
Como Aparece nas Visões
Em visões de formulário, um campo Inteiro é renderizado como uma caixa de entrada numérica. O Odoo adiciona automaticamente separadores de milhar para legibilidade ao exibir números maiores.
Em visões de lista, campos Inteiros aparecem como números simples, alinhados à direita por convenção. Em visões de busca, eles suportam filtros de igual, maior que e menor que.
Você pode emparelhar um campo Inteiro com widgets específicos em visões para mudar sua aparência. O widget prioridade, por exemplo, transforma um campo Inteiro em estrelas clicáveis. O widget barra de progresso pode exibir um valor Inteiro como uma barra de progresso quando combinado com um valor máximo.
Interação com o Odoo ORM
Do ponto de vista de um desenvolvedor, ler e escrever campos Inteiros é simples. O valor é sempre um int do Python. Campos Inteiros vazios retornam 0, o que significa que você deve ter cuidado ao escrever condições que verificam a ausência de um valor. Um zero e um campo vazio parecem iguais, a menos que você projete em torno disso.
Os campos Inteiros também funcionam naturalmente em campos calculados e em filtros de domínio usados por visualizações, ações de servidor e ações automatizadas em todo o framework Odoo.
Casos de Uso Empresarial
O campo Inteiro aparece em quase todos os módulos do Odoo. Aqui estão cinco cenários práticos onde ele desempenha um papel central.
1. CRM: Pontuação de Leads
As equipes de vendas frequentemente desejam priorizar leads com base em uma pontuação. Você pode adicionar um campo Inteiro personalizado chamado Pontuação de Lead no modelo de oportunidade do CRM. Os representantes de vendas atualizam a pontuação manualmente, ou uma ação automatizada a calcula com base em critérios como tamanho da empresa, orçamento ou nível de engajamento.
Isso facilita a classificação do seu pipeline por pontuação e o foco nas oportunidades mais promissoras.
2. Vendas: Quantidades Mínimas de Pedido
Nos módulos de Vendas e Inventário, campos Inteiros controlam as quantidades mínimas de pedido em produtos ou listas de preços. Definir um mínimo de 10 unidades em um produto garante que o sistema bloqueie pedidos abaixo desse limite, economizando idas e vindas com os clientes mais tarde.
3. Inventário: Regras de Reabastecimento
As regras de reabastecimento no Odoo dependem inteiramente de campos Inteiros para limites de quantidade mínima e máxima. Quando o estoque cai abaixo do mínimo, o Odoo aciona automaticamente um pedido de reabastecimento até o máximo definido. Obter esses valores corretos é crítico para evitar tanto faltas de estoque quanto situações de excesso de estoque.
4. Gestão de Projetos: Pontos de História e Estimativas de Esforço
Equipes que usam o Odoo Project para fluxos de trabalho ágeis frequentemente adicionam um campo Inteiro personalizado para pontos de história ou horas estimadas. Este campo aparece nas tarefas na visualização kanban ou de lista e ajuda a equipe a acompanhar a capacidade e a velocidade ao longo dos sprints.
5. Contabilidade: Dias de Condições de Pagamento
As condições de pagamento na Contabilidade do Odoo utilizam campos Inteiros para definir o número de dias permitidos para pagamento. Condições líquidas de 30, 60 dias ou personalizadas são todas configuradas através de valores Inteiros. Esses valores alimentam diretamente os cálculos das datas de vencimento das faturas, o que torna a precisão aqui importante para a gestão do fluxo de caixa.
Criando ou Personalizando o Campo Inteiro
Existem duas maneiras principais de adicionar um campo Inteiro a um modelo Odoo: usando o Odoo Studio sem escrever código ou definindo-o diretamente em Python para mais controle.
Usando Odoo Studio
O Odoo Studio é a ferramenta sem código e de baixo código incorporada ao Odoo para personalizar campos e visualizações. Para adicionar um campo Inteiro através do Studio:
- Abra o formulário onde deseja adicionar o campo.
- Ative o Studio no menu superior direito.
- Na lista de campos à esquerda, arraste o tipo de campo Inteiro para o seu formulário.
- Defina o rótulo do campo, escolha se é obrigatório e configure o valor padrão.
- Salve e saia do Studio.
O Studio cria o campo com um prefixo x_studio_ automaticamente e armazena a definição em ir.model.fields. O campo está imediatamente disponível em formulários e visualizações de lista.
Usando Python (Personalização Técnica)
Para desenvolvedores que estão a construir módulos personalizados ou a realizar desenvolvimento Odoo com mais controle, o campo Integer é definido diretamente em uma classe de modelo Python:
from odoo import fields, models
class CrmLead(models.Model):
_inherit = 'crm.lead'
x_lead_score = fields.Integer(
string='Lead Score',
default=0,
index=True,
help='Pontuação de 0 a 100 usada para priorizar oportunidades',
)Após definir o campo no código, execute odoo-bin -u your_module para aplicar as alterações ao banco de dados. A coluna é criada automaticamente.
Usando a API XML-RPC
Você também pode criar um campo Integer remotamente usando a API XML-RPC do Odoo. Isso é útil para implantações automatizadas ou quando se trabalha sem acesso direto ao servidor:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_lead_score',
'field_description': 'Lead Score',
'model_id': crm_lead_model_id,
'ttype': 'integer',
'state': 'manual',
}]
)O valor ttype para campos Integer é simplesmente 'integer'. O state deve ser 'manual' para indicar um campo personalizado em vez de um definido pelo módulo.
Adicionando um Campo Integer Computado
Campos Integer Computados são poderosos para derivar valores automaticamente. Por exemplo, contando o número de tarefas vinculadas a um projeto:
class Project(models.Model):
_inherit = 'project.project'
open_task_count = fields.Integer(
string='Tarefas Abertas',
compute='_compute_open_task_count',
store=True,
)
def _compute_open_task_count(self):
for project in self:
project.open_task_count = self.env['project.task'].search_count([
('project_id', '=', project.id),
('stage_id.fold', '=', False),
])Definir store=True salva o valor no banco de dados, tornando-o disponível para filtragem e ordenação em visualizações de lista sem recalculá-lo toda vez.
Melhores Práticas
Aqui estão dicas práticas para aproveitar ao máximo os campos Integer em seu modelo de dados Odoo.
Use Integer for Counts and Whole-Unit Quantities
Escolha Integer quando o valor deve ser sempre um número inteiro e decimais não fariam sentido. Para qualquer coisa envolvendo dinheiro, medições ou quantidades que podem ser fracionárias, use o tipo de campo Float ou Monetary em vez disso.
Set a Sensible Default
Os campos Integer têm como padrão 0 no Odoo. Em muitos casos, isso é aceitável, mas pense se zero é um valor significativo para o seu caso de uso. Se zero significa algo específico (como nenhuma pontuação atribuída ainda), você pode querer lidar com isso explicitamente na sua lógica de negócios ou adicionar um campo Booleano auxiliar para rastrear se o valor foi definido.
Add an Index When You Filter on the Field
Se você planeja filtrar, classificar ou agrupar por um campo Integer com frequência, adicione index=True na definição do campo. Isso cria um índice de banco de dados e pode acelerar significativamente as consultas em grandes conjuntos de dados. A desvantagem é um pequeno aumento no armazenamento e no tempo de gravação, que quase sempre vale a pena para campos usados em condições de pesquisa.
Use store=True for Computed Integer Fields
Se você definir um campo Integer computado que os usuários precisam filtrar ou classificar em visualizações de lista, sempre defina store=True. Sem isso, o Odoo não pode usar o campo em filtros de domínio, e agrupar por ele não funcionará como esperado.
Document Your Ranges
Quando um campo Integer tem um intervalo significativo, como uma pontuação de 0 a 100, documente isso no parâmetro help. Este texto aparece como uma dica na interface e evita que os usuários adivinhem quais valores são válidos.
Think Twice Before Using Integer for IDs or References
Se você precisar referenciar outro registro, use um campo Many2one em vez de armazenar um ID manualmente em um campo Integer. Os campos Many2one oferecem navegação integrada, regras em cascata e integração adequada com o ORM. Um Integer que contém um ID bruto é frágil e contorna a estrutura do Odoo.
Armadilhas Comuns
Estes são os erros que surgem com mais frequência ao trabalhar com campos Inteiros no Odoo.
Confundir Inteiro com Flutuante
Um erro comum é usar um campo Inteiro onde um campo Flutuante seria mais apropriado. Se os seus utilizadores precisarem de inserir 1.5, 0.25 ou qualquer valor fracionário, Inteiro é a escolha errada. O Odoo irá truncar silenciosamente a entrada decimal, o que leva à perda de dados e confusão do utilizador. Use Flutuante para quantidades que podem ser fracionárias, e Monetário para valores em moeda.
Assumir que Zero Significa Vazio
Como os campos Inteiros sempre retornam 0 quando não definidos, não há como distinguir entre um registo onde o campo nunca foi preenchido e um onde alguém intencionalmente inseriu zero. Se esta distinção for importante para o seu fluxo de trabalho, adicione um campo Booleano como has_score ao lado do Inteiro, ou use um campo Flutuante com um valor padrão False em vez disso.
Não Adicionar um Índice em Campos Frequentemente Filtrados
Se você adicionar um campo Inteiro e depois usá-lo como filtro em visualizações ou ações automatizadas, esquecer de adicionar index=True pode desacelerar visivelmente as visualizações de lista em bases de dados maiores. É mais fácil adicionar o índice desde o início do que otimizar depois.
Usar Inteiro para Armazenar Proporções Baseadas em Decimais
Às vezes, os desenvolvedores armazenam percentagens como campos Inteiros, escrevendo 75 para significar 75%. Isso funciona até que alguém precise de 72.5%, momento em que o campo quebra a exigência. Se houver alguma chance de que uma percentagem ou proporção precise de precisão decimal, use Flutuante desde o início.
Esquecer store=True em Campos Computados Usados em Filtros
Este é um dos erros mais comuns no desenvolvimento Odoo. Um campo Inteiro computado sem store=True não pode ser usado em filtros de domínio, ações automatizadas ou operações de agrupamento em visualizações de lista. Pense sempre sobre onde o campo será usado antes de decidir se deve armazená-lo.
Conclusão
O campo Inteiro é um bloco de construção fundamental no modelo de dados do Odoo. Parece simples, e na maioria dos casos é. Mas conhecer seus comportamentos específicos, como o fato de que campos vazios retornam 0 e campos computados precisam de store=True para funcionar em filtros, ajuda a evitar os tipos de bugs e problemas de design que são fáceis de introduzir e mais difíceis de corrigir depois.
Seja você configurando o Odoo para uma equipe de vendas, construindo um módulo personalizado ou projetando regras de reabastecimento para um armazém, os campos Inteiros aparecerão em cada etapa. Compreender como eles funcionam no ORM do Odoo, como criá-los com o Studio ou Python, e quando usá-los em vez de Float ou Monetary é parte do que torna uma implementação do Odoo sólida e sustentável.
Se você está trabalhando em uma personalização do Odoo e quer ter certeza de que seu modelo de dados está construído da maneira certa desde o início, esse tipo de conhecimento fundamental compensa durante toda a vida do projeto.
Trabalhe com um Especialista em Odoo
Na Dasolo, ajudamos empresas a implementar, personalizar e otimizar o Odoo em todos os módulos e indústrias. Seja você precisando projetar um modelo de dados limpo, construir campos e fluxos de trabalho personalizados, ou conectar o Odoo a sistemas externos através da API, trazemos a experiência para fazer isso da maneira certa.
Se você tiver perguntas sobre sua configuração do Odoo ou quiser discutir um projeto, entre em contato com nossa equipe. Estamos felizes em ajudar.