Se você passou algum tempo configurando o Odoo, provavelmente já se deparou com expressões de domínio. Essas condições de filtro preenchidas por colchetes aparecem em botões de ação, regras automatizadas, regras de registro e modelos de email em toda a plataforma. Mas menos pessoas percebem que o Odoo também fornece um tipo de Campo de Domínio em seu ORM, projetado especificamente para armazenar e exibir essas expressões como dados estruturados.
Compreender os campos de domínio é importante, seja você um desenvolvedor Odoo construindo módulos personalizados ou um usuário empresarial configurando fluxos de trabalho automatizados. Este guia cobre tudo, desde o que um campo de domínio realmente armazena até exemplos práticos, dicas de desenvolvimento e os erros mais comuns a evitar.
Qual é o Campo de Domínio no Odoo
No Odoo, um domínio é uma lista de condições de filtro usadas para consultar registros. Segue uma sintaxe específica usando tuplas e operadores lógicos, e mapeia diretamente para cláusulas SQL WHERE quando o Odoo executa uma consulta ao banco de dados.
Uma expressão de domínio típica se parece com isto:
[('customer_rank', '>', 0), ('active', '=', True)]Isto traduz-se em: retornar todos os registos onde customer_rank é maior que 0 E active é Verdadeiro.
O campo Domain (fields.Domain) é um tipo de campo no Odoo ORM que armazena estas expressões como dados estruturados dentro de um registo. Ao contrário de um campo de texto simples, ele vem com validação incorporada e um widget de interface de utilizador dedicado que permite aos utilizadores construir condições de filtro visualmente, sem escrever qualquer código.
Como aparece na interface
Na interface do Odoo, um campo Domain é renderizado utilizando o widget do editor de domínio por padrão. Este widget apresenta um construtor de regras visual onde os utilizadores podem escolher um campo, selecionar um operador (igual, contém, maior que, e assim por diante) e inserir um valor. É a mesma interface que você vê ao configurar regras de acesso ou critérios de filtro em ações automatizadas.
Na base de dados, os valores de domínio são armazenados como texto simples, especificamente como a representação em string de uma lista Python. O tipo de campo lida com a serialização e validação de forma transparente, para que os desenvolvedores trabalhem com valores de domínio limpos em Python enquanto a camada de armazenamento cuida do resto.
Isto faz parte do design mais amplo do modelo de dados Odoo: os campos não são apenas contentores de armazenamento. Eles carregam significado semântico, comportamento da interface de utilizador e lógica de validação juntos em uma única definição.
Como o Campo Funciona
O campo Domain integra-se de forma estreita com o Odoo ORM e o sistema de filtragem de registos. Aqui está o que acontece nos bastidores quando você salva e avalia um domínio.
Armazenamento e representação
Quando um domínio é salvo na base de dados, o Odoo armazena-o como uma string serializada. Um domínio que restringe registos ao estado de rascunho para o utilizador atual é armazenado como um valor de texto que o Odoo avalia no momento da consulta. A variável especial uid é resolvida para o ID do utilizador atual em tempo de execução, tornando a filtragem dinâmica possível sem codificar valores.
O Odoo ORM pega essa string, avalia-a de forma segura e a converte em uma cláusula WHERE SQL. Esta avaliação acontece através de safe_eval, que suporta um subconjunto controlado de expressões Python juntamente com variáveis de contexto específicas do Odoo.
O widget de domínio
Na interface do Odoo, campos do tipo fields.Domain utilizam o widget de domínio por padrão. Este widget apresenta o construtor de filtros que você vê em muitas partes do Odoo. Os utilizadores podem adicionar condições, combiná-las com lógica AND ou OR, e visualizar resultados sem tocar em qualquer código.
O widget é o que torna os campos de domínio genuinamente acessíveis aos utilizadores de negócios. Não é necessário entender a sintaxe de domínio para configurar um filtro. O construtor visual trata da tradução por si.
Contexto do modelo
Um campo de domínio pode estar ligado a um modelo específico, que informa ao Odoo quais campos oferecer no construtor de domínio. Você define isso através do atributo model_field na definição do campo. Sem um contexto de modelo, o widget de domínio recorre a uma entrada de texto simples, que é muito menos útil para os utilizadores finais.
Essa ligação de contexto é uma parte fundamental de como o framework Odoo conecta definições de campos ao comportamento da interface. O campo conhece o modelo que filtra, e a interface se adapta de acordo.
Interação com outros registos
Os campos de domínio são frequentemente utilizados juntamente com campos relacionais para restringir quais registos aparecem em um dropdown Many2one, para definir quais registos uma ação automatizada visa, ou para definir o escopo de um relatório ou painel. A expressão de domínio atua como um filtro ao vivo aplicado ao nível do ORM, o que significa que respeita as regras de segurança do Odoo e os controles de acesso aos campos.
Casos de Uso Empresarial
Os campos de domínio aparecem em praticamente todos os módulos do Odoo. Aqui estão cinco exemplos do mundo real que mostram como eles impulsionam fluxos de trabalho empresariais práticos.
1. Ações automatizadas e gatilhos de e-mail
Quando você configura uma ação automatizada no Odoo (Configurações > Técnico > Automação), você define um domínio para especificar quais registos acionam a ação. Por exemplo, um e-mail automatizado para faturas em atraso pode visar apenas faturas publicadas que estão não pagas e além do seu prazo. Este domínio é armazenado diretamente no modelo base.automation em um campo de domínio chamado filter_domain. A ação só é acionada para registos que correspondem.
2. Regras de registo e controle de acesso
As regras de registo de segurança do Odoo usam campos de domínio para restringir quais registos um grupo de utilizadores pode ver ou editar. Uma regra da equipe de vendas pode limitar a visibilidade a registos atribuídos à equipe do utilizador atual, avaliada no momento da consulta. Isso proporciona segurança a nível de linha sem a necessidade de escrever código personalizado. Cada filtro em cada regra de registo no Odoo é uma expressão de domínio armazenada em um campo de domínio.
3. Filtragem de inventário e operações
Na gestão de armazém e inventário, ações programadas e regras de reabastecimento utilizam domínios para direcionar categorias específicas de produtos, locais ou níveis de stock. Uma ação de reabastecimento automatizada pode ser limitada a produtos armazenáveis com quantidade disponível igual ou inferior a um ponto de reabastecimento, evitando processamento desnecessário em milhares de registos.
4. Pipeline de CRM e qualificação de leads
No módulo de CRM, a automação de etapas do pipeline, regras de atividade e atribuição de leads dependem de expressões de domínio para categorizar e qualificar leads. Regras de atribuição de leads personalizadas utilizam domínios para corresponder leads ao vendedor certo com base no país, setor ou tamanho do negócio. O campo de domínio é o que torna essas regras configuráveis a partir da interface, em vez de exigir alterações de código para cada novo cenário.
5. Dropdowns dinâmicos Many2one
Em formulários personalizados, um domínio aplicado a um campo Many2one controla quais registos aparecem no dropdown. Restringir um campo de fornecedor para mostrar apenas fornecedores ativos com uma classificação de fornecedor não nula cria experiências de utilizador mais focadas e reduz erros de entrada. O domínio pode até ser dinâmico, referenciando valores de outros campos no mesmo formulário, fazendo com que as opções disponíveis mudem com base nas seleções do utilizador.
Criando ou Personalizando o Campo
Existem duas abordagens principais para trabalhar com campos de domínio no Odoo: usar o Odoo Studio para personalização sem código ou escrever Python e XML em um módulo personalizado.
Usando o Odoo Studio
O Odoo Studio atualmente não expõe um tipo de campo Domain independente em seu criador de campos visual. Para a maioria das necessidades de configuração empresarial, você não precisa de um. Os editores de domínio existentes integrados em ações automatizadas, regras de registo e ações de servidor oferecem a você o construtor de domínio visual sem exigir um campo personalizado.
Se você quiser adicionar um filtro de domínio a um campo Many2one em um formulário, pode fazer isso no Studio editando as propriedades do campo e inserindo uma expressão de domínio diretamente. O Studio valida a sintaxe do domínio e a armazena na definição da visualização.
Personalização técnica em Python
Em um módulo Odoo personalizado, adicionar um campo de domínio é uma parte direta do guia do desenvolvedor odoo padrão. Aqui está um exemplo básico usando o ORM:
from odoo import models, fields
class MyModel(models.Model):
_name = 'my.model'
model_name = fields.Char(default='res.partner')
filter_domain = fields.Domain(
string='Filter Domain',
model_field='model_name',
help='Domain expression to filter partner records'
)O atributo model_field liga o editor de domínio ao nome do modelo armazenado em model_name. Isso informa ao widget de domínio quais campos oferecer no construtor visual. Manter o nome do modelo em um campo separado também permite a seleção dinâmica de modelo, caso seu caso de uso exija.
Adicionando o widget a uma vista de formulário
Para exibir o construtor de domínio em uma vista de formulário, faça referência tanto ao campo do modelo quanto ao campo de domínio no XML da vista:
<field name="model_name" invisible="1"/>
<field name="filter_domain" widget="domain"
options="{'model': 'model_name'}"/>Sem a declaração widget="domain" e a opção de modelo, o campo é renderizado como texto simples. Sempre inclua ambos ao construir formulários que expõem a configuração de domínio aos usuários.
Escrevendo valores de domínio via API XML-RPC
Se você estiver definindo valores de campo de domínio programaticamente via API, sempre passe o valor como uma string:
models.execute_kw(db, uid, api_key, 'my.model', 'write',
[[record_id], {
'filter_domain': "[('active', '=', True)]"
}]
)Passar um objeto de lista Python em vez de uma string é um erro comum que causa erros ou falhas silenciosas, dependendo da versão do Odoo. Sempre serialize seu domínio para uma string antes de escrevê-lo através da API.
Melhores Práticas
Esses hábitos práticos economizarão seu tempo e evitarão problemas ao trabalhar com campos de domínio no Odoo.
Valide a sintaxe do domínio antes de implantar
Uma expressão de domínio inválida gera erros no momento em que o Odoo tenta avaliá-la. Teste seus domínios na barra de pesquisa do Odoo ou no modo de desenvolvedor antes de salvá-los em ações automatizadas ou regras de registro. Uma rápida chamada search_count via API também é uma maneira confiável de confirmar que um domínio retorna o número esperado de registros.
Use dynamic variables where possible
Evite codificar IDs de utilizador, IDs de empresa ou datas em expressões de domínio. Use variáveis dinâmicas como uid, context_today() e current_company_id em vez disso. Isso mantém seus domínios portáteis e evita falhas silenciosas quando os registros mudam entre ambientes.
Always bind the model context
Ao adicionar um campo de Domínio a um modelo personalizado, sempre defina o atributo model_field e inclua-o na visualização. Sem isso, os utilizadores veem um campo de texto simples em vez do construtor de domínio visual, o que reduz a usabilidade e aumenta a chance de valores inválidos serem salvos.
Keep domains readable
Domínios complexos aninhados usando | (OU) e & (E) podem se tornar difíceis de ler e manter. Adicione comentários no seu código Python explicando a intenção por trás de cada domínio. Se um domínio se tornar muito complexo, considere se uma ação de servidor ou um campo computado seria mais claro e mais fácil de testar.
Use safe_eval for programmatic evaluation
Ao avaliar strings de domínio em código Python, por exemplo, dentro de uma ação de servidor ou ação automatizada, use o safe_eval embutido do Odoo em vez do eval nativo do Python. É mais seguro, lida corretamente com variáveis de contexto específicas do Odoo e é consistente com a forma como o Odoo avalia domínios internamente.
Test with realistic data
Sempre verifique se o seu domínio corresponde aos registros esperados antes de entrar em produção. Isso é especialmente importante para ações automatizadas e regras de registro, onde um filtro incorreto pode processar os registros errados ou bloquear o acesso do utilizador sem qualquer aviso visível.
Erros Comuns
Here are the mistakes that come up most often when working with domain fields in Odoo, and how to avoid them.
Confundir o tipo de campo com a sintaxe de domínio
A palavra "domínio" significa duas coisas diferentes no Odoo. Refere-se à sintaxe de filtro (uma lista de tuplas) e também se refere a fields.Domain, um tipo específico de campo ORM que armazena essas expressões como dados. Novatos em personalização do Odoo costumam confundir os dois. Um campo de domínio é um recipiente de armazenamento. A expressão de domínio é a lógica de filtro dentro dele.
Passando uma lista em vez de uma string via API
Ao escrever em um campo de domínio via XML-RPC, você deve passar uma string, não um objeto de lista Python. Passar o domínio como uma lista bruta causará um erro de tipo ou falha silenciosa, dependendo da versão do Odoo. Sempre serialize seu domínio para uma string antes de escrevê-lo através da API.
Faltando contexto do modelo no widget
Se você adicionar um campo de domínio a uma visualização de formulário sem especificar o contexto do modelo nas opções do widget, os usuários verão um campo de texto simples em vez do construtor de domínio visual. O construtor de domínio só aparece quando o widget sabe a qual modelo se referir. Sempre inclua o link model_field na definição da sua visualização.
Hardcoding IDs de registros em domínios
Domínios que referenciam IDs de registros específicos diretamente quebram silenciosamente quando esses registros são excluídos ou quando você copia a configuração para um novo banco de dados. Use referências dinâmicas como uid ou buscas relacionais sempre que possível para manter seus domínios portáteis.
Domínios de regras de registro excessivamente amplos ou restritivos
Um domínio de regra de registro que é muito permissivo pode expor registros a usuários que não deveriam vê-los. Um que é muito restritivo pode ocultar registros silenciosamente sem qualquer explicação para o usuário. Sempre teste os domínios de regras de registro da perspectiva do grupo de usuários-alvo, e não da conta de administrador que ignora todas as regras.
Esquecendo registros arquivados
Por padrão, o Odoo exclui registros arquivados (onde active = False) dos resultados de pesquisa. Se seu domínio não levar isso em conta, você pode obter lacunas inesperadas em seus dados. Adicione ('active', 'in', [True, False]) quando precisar incluir registros arquivados nos resultados do filtro.
Conclusão
Os campos de domínio são um dos blocos de construção que silenciosamente alimentam uma grande parte de como o Odoo funciona. Desde controle de acesso e ações automatizadas até dropdowns dinâmicos e filtros de painel, as expressões de domínio são a espinha dorsal do filtragem de registros no Odoo, e o tipo fields.Domain oferece aos desenvolvedores uma maneira limpa e validada de armazenar e apresentar essa lógica diretamente no modelo de dados do Odoo.
Para os utilizadores de negócios, o widget de domínio torna a configuração de filtros acessível sem qualquer código. Para os desenvolvedores, o tipo de campo Domínio traz clareza às definições de modelo que antes dependiam de campos Char genéricos com uma sobreposição de widget. Quer esteja a trabalhar no Odoo Studio, a escrever um módulo Python personalizado ou a configurar fluxos de trabalho automatizados a partir da interface, compreender como funcionam os campos de domínio abre uma ampla gama de possibilidades.
Os conceitos abordados neste guia aplicam-se a todas as versões e módulos do Odoo. O tempo gasto a compreender os campos de domínio é um tempo bem investido, porque eles estão genuinamente em toda a parte no Odoo.
Precisa de ajuda com a sua implementação do Odoo?
A Dasolo ajuda empresas a implementar, personalizar e otimizar o Odoo para as suas necessidades específicas de negócios. Quer esteja a configurar fluxos de trabalho automatizados, a construir módulos personalizados ou a tentar tirar mais proveito da sua configuração existente do Odoo, a nossa equipa tem a profundidade técnica para o ajudar a avançar com confiança.
Se tiver perguntas sobre os campos de Domínio ou qualquer outro aspecto da sua implementação do Odoo, entre em contacto connosco. Estamos felizes por analisar a sua configuração e orientá-lo na direção certa.