Odoo를 설정해 본 사람이라면 곳곳에서 대괄호로 둘러싸인 필터 조건을 본 적이 있을 것입니다. 액션 버튼, 자동화 규칙, 레코드 규칙, 이메일 템플릿 등 여러 곳에 등장하는 이 표현들은 단순한 텍스트가 아니라 필터 로직입니다. 아울러 Odoo ORM에는 이 필터 표현을 구조화된 데이터로 저장하고 편집할 수 있게 해주는 전용 필드 타입, 즉 Domain 필드(Domain field type)가 존재합니다.
도메인 필드를 이해하는 것은 개발자가 커스텀 모듈을 만들 때나 비즈니스 사용자가 자동화 흐름을 구성할 때 모두 중요합니다. 이 가이드는 도메인 필드가 실제로 무엇을 저장하는지부터, 실무 예시, 개발 팁, 그리고 피해야 할 대표적 실수까지를 포괄적으로 다룹니다.
Odoo에서의 Domain 필드란 무엇인가요
Odoo에서 ‘도메인(domain)’은 레코드를 검색(필터링)하기 위한 조건들의 리스트를 뜻합니다. 튜플과 논리 연산자를 사용한 고유한 문법을 따르며, 데이터베이스 조회 시 SQL의 WHERE 절로 변환됩니다.
일반적인 도메인 식의 예는 다음과 같습니다:
[('customer_rank', '>', 0), ('active', '=', True)]이 의미는 이렇게 해석됩니다: customer_rank가 0보다 크고 active가 True인 모든 레코드를 반환하라.
Domain 필드(fields.Domain)는 이러한 도메인 표현을 레코드 안에 구조화된 형태로 저장하는 ORM 필드 타입입니다. 일반 텍스트 필드와 달리 문법 검증을 제공하고, 사용자가 코드 없이도 시각적으로 조건을 만들 수 있는 전용 위젯을 포함합니다.
인터페이스에서의 표시 방식
Odoo UI에서는 Domain 필드가 기본적으로 도메인 편집기 위젯으로 렌더링됩니다. 이 위젯은 사용자가 필드를 선택하고, 연산자를 고르며, 값을 입력해 조건을 조합할 수 있는 시각적 빌더를 제공합니다. 액세스 규칙이나 자동화 필터를 설정할 때 보이는 동일한 인터페이스입니다.
데이터베이스에는 도메인 값이 텍스트—정확히는 파이썬 리스트의 문자열 표현—로 저장됩니다. 필드 타입이 직렬화와 검증을 처리해주기 때문에 개발자는 파이썬 레벨에서 깨끗한 도메인 값을 다룰 수 있습니다.
이는 Odoo 데이터 모델 설계의 중요한 특징입니다: 필드는 단순 저장소가 아니라 의미(semantic), UI 동작, 검증 로직을 함께 지니는 정의 단위입니다.
필드의 동작 방식
Domain 필드는 Odoo ORM 및 레코드 필터링 시스템과 밀접하게 통합되어 있습니다. 도메인이 저장되고 평가될 때 내부적으로 어떤 일이 벌어지는지 요약하면 다음과 같습니다.
저장과 표현 방식
도메인이 DB에 저장될 때는 직렬화된 문자열로 보관됩니다. 예컨대 현재 사용자에 한해 초안 상태의 레코드를 제한하는 도메인은 텍스트로 저장되고, 조회 시점에 평가되어 동적으로 uid 같은 특수 변수를 현재 사용자 ID로 치환합니다. 이로써 값 하드코딩 없이도 동적 필터링이 가능합니다.
Odoo ORM은 그 문자열을 안전하게 평가(safe_eval)해 SQL WHERE 절로 변환합니다. safe_eval은 제한된 파이썬 표현식과 Odoo 특화 컨텍스트 변수를 지원하도록 설계되어 있습니다.
도메인 위젯
UI에서 fields.Domain 타입 필드는 기본적으로 도메인 위젯을 사용합니다. 이 위젯은 조건을 추가하고 AND/OR로 결합하며 코드 작성 없이 결과를 미리 확인할 수 있게 해줍니다.
이 위젯 덕분에 도메인 필드는 비개발자에게도 친숙합니다. 도메인 문법을 몰라도 시각적 빌더로 필터를 구성할 수 있습니다.
모델 컨텍스트
Domain 필드는 특정 모델에 연결될 수 있으며, 이는 도메인 빌더가 어떤 필드를 제안할지를 결정합니다. 필드 정의에서 model_field 속성으로 이 연결을 지정합니다. 모델 컨텍스트가 없으면 위젯은 일반 텍스트 입력으로 대체되어 사용자에게 불친절합니다.
이 컨텍스트 바인딩은 Odoo 프레임워크가 필드 정의와 UI 동작을 연결하는 중요한 메커니즘입니다. 필드는 자신이 필터할 모델을 알고 있어 UI가 그에 맞춰 동작합니다.
다른 레코드와의 상호작용
Domain 필드는 관계형 필드와 함께 사용되어 Many2one 드롭다운을 제한하거나 자동화 액션의 대상 범위를 정의하거나 리포트 및 대시보드의 스코프를 결정합니다. 도메인 표현은 ORM 수준에서 실시간 필터로 적용되므로 Odoo의 보안 규칙과 필드 접근 제어를 존중합니다.
실무 적용 사례
도메인 필드는 거의 모든 Odoo 모듈에서 사용됩니다. 다음 다섯 가지 실무 예시는 도메인이 어떻게 비즈니스 워크플로우를 구동하는지 보여줍니다.
1. 자동화 액션과 이메일 트리거
자동화(설정 > 기술 > 자동화)에서 액션을 트리거할 레코드를 한정하려면 도메인을 정의합니다. 예를 들어 연체 송장에 대한 자동 이메일은 게시(posted) 되었고 미지급이며 마감일이 지난 송장만을 대상으로 삼을 수 있습니다. 이 도메인은 base.automation 모델의 filter_domain 필드에 저장되며, 조건에 맞는 레코드에만 액션이 실행됩니다.
2. 레코드 규칙과 접근 제어
Odoo의 보안 레코드 규칙은 도메인 필드를 사용해 특정 사용자 그룹이 볼 수 있거나 수정할 수 있는 레코드를 제한합니다. 예컨대 영업 팀 규칙은 현재 사용자 팀에 할당된 레코드만 보이도록 제한할 수 있습니다. 이렇게 하면 별도 코드 없이 행 수준 보안(row-level security)을 구현할 수 있습니다.
3. 재고 및 운영 필터링
창고와 재고 관리에서는 예정 작업이나 재주문 규칙이 특정 제품군, 위치, 재고 수준을 대상으로 하도록 도메인을 사용합니다. 예컨대 재고 보충 자동화는 보관 품목 중 재고가 재주문점 이하인 항목만 대상으로 삼아 대량의 불필요한 처리를 막습니다.
4. CRM 파이프라인과 리드 분류
CRM에서는 파이프라인 단계 자동화, 활동 규칙, 리드 배정 등이 도메인으로 분류 및 자격을 판정합니다. 국가, 산업, 거래 규모 등 기준으로 영업 담당자에게 리드를 연결하는 규칙은 도메인으로 구성되므로 인터페이스에서 손쉽게 조정할 수 있습니다.
5. 동적 Many2one 드롭다운
커스텀 폼에서 Many2one에 도메인을 적용하면 드롭다운에 나타나는 레코드를 제어할 수 있습니다. 예를 들어 공급업체 필드를 활성화된 공급자 중 공급 등급이 0이 아닌 것만 보이도록 제한하면 입력 오류가 줄고 사용자 경험이 개선됩니다. 도메인은 같은 폼의 다른 필드 값을 참조해 동적으로 변경될 수도 있습니다.
필드 생성과 커스터마이징 방법
Domain 필드를 다루는 방법은 크게 두 가지입니다: 코드 없이 구성 가능한 Odoo Studio를 이용하거나, 커스텀 모듈에서 파이썬/XML로 직접 구현하는 방법입니다.
Odoo Studio 활용
Odoo Studio의 시각적 필드 생성기에서는 별도의 Domain 필드 타입을 제공하지 않습니다. 그러나 대부분의 비즈니스 설정에서는 필요하지 않습니다. 자동화 액션, 레코드 규칙, 서버 액션에 내장된 시각적 도메인 편집기가 이미 충분한 기능을 제공합니다.
폼에서 Many2one 필드에 도메인 필터를 추가하려면 Studio에서 필드 속성을 편집하고 도메인 표현을 직접 입력하면 됩니다. Studio는 도메인 문법을 검증하고 뷰 정의에 저장합니다.
기술적 커스터마이징 (파이썬)
커스텀 Odoo 모듈에서는 Domain 필드를 추가하는 것이 표준 개발 과정의 일부입니다. 다음은 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'
)여기서 model_field 속성은 도메인 위젯이 사용할 모델명을 model_name 필드에서 가져오도록 연결합니다. 모델명을 별도 필드로 보관하면 필요시 동적으로 모델을 선택하는 시나리오도 구현할 수 있습니다.
폼 뷰에 위젯 추가하기
폼 뷰에서 도메인 빌더를 보이게 하려면 모델 필드와 도메인 필드를 뷰 XML에 함께 참조해야 합니다.
<field name="model_name" invisible="1"/>
<field name="filter_domain" widget="domain"
options="{'model': 'model_name'}"/>widget="domain" 선언과 모델 옵션이 없으면 필드는 일반 텍스트로 렌더링됩니다. 사용자에게 도메인 편집기를 노출하려면 둘 다 반드시 포함하세요.
XML-RPC API로 도메인 값 쓰기
API로 도메인 필드 값을 설정할 때는 항상 문자열로 전달해야 합니다.
models.execute_kw(db, uid, api_key, 'my.model', 'write',
[[record_id], {
'filter_domain': "[('active', '=', True)]"
}]
)파이썬 리스트 객체를 그대로 전달하면 Odoo 버전에 따라 에러가 나거나 조용히 실패하는 일이 자주 발생합니다. API를 통해 쓸 때는 도메인을 문자열로 직렬화해 보내세요.
권장 사용법
이런 실무 습관은 도메인 필드를 다룰 때 시간과 문제를 크게 줄여줍니다.
배포 전에 도메인 문법 검증
잘못된 도메인 식은 Odoo가 평가하려는 순간 에러를 일으킵니다. 자동화 액션이나 레코드 규칙에 저장하기 전에 Odoo 검색 창이나 개발자 모드에서 도메인을 테스트하세요. API를 통해 search_count 호출로 기대한 레코드 수를 확인하는 것도 좋은 방법입니다.
동적 변수 사용 권장
도메인 안에 사용자 ID, 회사 ID, 날짜를 하드코딩하지 마세요. 대신 uid, context_today(), current_company_id 같은 동적 변수를 사용하면 환경 간 이식성이 좋아지고 값 변경으로 인한 문제를 방지할 수 있습니다.
항상 모델 컨텍스트를 바인딩
커스텀 모델에 Domain 필드를 추가할 때는 반드시 model_field 속성을 설정하고 뷰에 포함시키세요. 그렇지 않으면 사용자는 시각적 빌더 대신 일반 텍스트 입력을 보게 되어 사용성이 떨어지고 유효하지 않은 값이 저장될 가능성이 커집니다.
도메인을 읽기 쉽게 유지
|(OR)과 &(AND)를 중첩해 복잡해진 도메인은 관리하기 어렵습니다. 파이썬 코드에 의도를 설명하는 주석을 달고, 도메인이 지나치게 복잡해지면 서버 액션이나 계산 필드로 대체하는 것을 고려하세요.
프로그램 평가에는 safe_eval 사용
서버 액션이나 자동화 액션 내부 등에서 도메인 문자열을 평가해야 할 때는 파이썬의 내장 eval 대신 Odoo의 safe_eval을 사용하세요. 더 안전하고 Odoo 특화 컨텍스트를 올바르게 처리하며 내부 동작과도 일관됩니다.
실제 데이터를 이용한 테스트
도메인을 실환경에 적용하기 전에 항상 현실적인 데이터로 검증하세요. 특히 자동화 액션이나 레코드 규칙 같은 경우 잘못된 필터가 엉뚱한 레코드를 처리하거나 사용자 접근을 차단할 수 있습니다.
흔한 실수들
다음은 Odoo에서 도메인 필드를 다룰 때 자주 발생하는 실수들과 그 회피법입니다.
필드 타입과 도메인 문법 혼동
Odoo에서 ‘도메인’이라는 단어는 두 가지를 가리킬 수 있습니다: 필터 문법(튜플의 리스트)과 그 문법을 데이터로 저장하는 ORM 필드 타입 fields.Domain. 초보자는 이 둘을 섞어 쓰는 경우가 많습니다. 요약하면 Domain 필드는 저장소이고, 도메인 표현은 그 안의 필터 로직입니다.
API에 리스트 대신 문자열을 전달
XML-RPC로 Domain 필드에 쓰기할 때는 문자열을 전달해야 합니다. 리스트를 그대로 보내면 타입 에러나 버전에 따른 조용한 실패가 발생합니다. 항상 도메인을 문자열로 직렬화하세요.
위젯에 모델 컨텍스트를 빼먹음
폼 뷰에 Domain 필드를 추가하면서 위젯 옵션에 모델 컨텍스트를 지정하지 않으면 사용자는 시각적 빌더 대신 일반 텍스트 입력을 보게 됩니다. 도메인 빌더는 참조할 모델을 알아야 등장합니다. 뷰 정의에 model_field 연결을 반드시 포함하세요.
레코드 ID를 하드코딩함
특정 레코드 ID를 도메인에 직접 포함하면 그 레코드가 삭제되거나 설정을 다른 DB로 복사할 때 문제가 생깁니다. 가능한 한 uid나 관계형 조회 같은 동적 참조를 사용해 도메인을 이식성 있게 만드세요.
너무 광범위하거나 과도하게 제한적인 레코드 규칙
레코드 규칙 도메인이 너무 관대하면 접근해서는 안 될 데이터가 노출됩니다. 반대로 너무 제한적이면 사용자에게 아무 알림 없이 레코드가 보이지 않을 수 있습니다. 규칙은 관리자 관점이 아닌 대상 사용자 그룹의 관점에서 테스트하세요.
아카이브된 레코드(비활성 레코드)를 잊음
기본적으로 Odoo는 아카이브된 레코드(active = False)를 검색 결과에서 제외합니다. 이를 고려하지 않으면 데이터에 빈틈이 생길 수 있습니다. 아카이브된 레코드도 포함해야 한다면 ('active', 'in', [True, False]) 같은 조건을 추가하세요.
마무리
도메인 필드는 Odoo의 동작 원리에서 큰 부분을 차지하는 구성 요소입니다. 접근 제어와 자동화 액션에서부터 동적 드롭다운과 대시보드 필터에 이르기까지 도메인 표현은 레코드 필터링의 중추입니다. 그리고 fields.Domain 타입은 그 로직을 데이터 모델 안에 깔끔하고 검증된 형태로 담아줍니다.
비개발자에게는 도메인 위젯이 코드 없이 필터 구성을 가능하게 하고, 개발자에게는 도메인 필드 타입이 단순 Char 필드와 위젯 오버라이드에 의존하던 과거보다 모델 정의를 명확하게 만듭니다. Odoo Studio에서 작업하든, 커스텀 파이썬 모듈을 작성하든, UI에서 자동화 워크플로우를 구성하든 도메인 필드를 이해하면 활용 범위가 크게 늘어납니다.
이 가이드에서 다룬 개념들은 Odoo의 여러 버전과 모듈 전반에 적용됩니다. 도메인 필드를 이해하는 데 투자한 시간은 Odoo를 다루는 데 매우 값진 자산이 됩니다.
Odoo 도입이나 최적화에 도움이 필요하신가요?
Dasolo는 기업이 Odoo를 비즈니스 니즈에 맞게 도입·커스터마이즈·최적화하도록 돕습니다. 자동화 워크플로우 구성, 커스텀 모듈 개발, 기존 Odoo 환경의 기능 확장 등 어떤 필요든 저희 팀이 기술적 역량으로 자신 있게 지원합니다.
도메인 필드나 Odoo 구현의 다른 부분에 대해 질문이 있으시면, 문의해 주세요. 구조와 설정을 검토해 드리고 적절한 방향을 제시해 드리겠습니다.