서론
Odoo에서는 데이터가 ‘모델’이라는 설계도로 구조화되어 데이터베이스에 저장됩니다. 매출 주문, 송장, 연락처 같은 모든 사업 데이터는 각기 모델에 저장되며, 모델이 곧 데이터의 구조와 동작 방식을 결정합니다.
모델을 이해하는 것은 개발자와 기능 컨설턴트 모두에게 필수입니다. 모델은 필드 정의, 관계 설정, 비즈니스 로직을 담는 Odoo 데이터 아키텍처의 근간이기 때문에 시스템 설계와 맞춤화의 출발점이 됩니다.
이 글은 Odoo에서 가장 핵심적인 모델 중 하나인 res.partner에 초점을 맞춥니다. 커스텀 모듈을 만들든 외부 시스템을 연동하든, 또는 워크플로를 구성하든 이 모델과의 작업은 매우 빈번합니다.
res.partner 모델이란 무엇인가
res.partner는 Odoo에서 개인, 고객, 공급업체, 법인 등 ‘거래 주체’의 정보를 저장하는 중심 모델입니다. 파트너 관련 모든 기본 정보가 이 레코드에 모입니다.
이 모델은 거의 모든 모듈에서 참조됩니다. 영업, CRM, 회계, 구매, 전자상거래 등에서 고객이나 공급업체를 만들면 res.partner 레코드가 생성되거나 연결됩니다.
모델 정의는 base 모듈에서 시작되며 다른 모듈이 상속을 통해 확장합니다. CRM은 리드 관련 필드를 추가하고 회계는 신용·결제 조건을 더하는 식으로 핵심 구조를 중복 없이 확장합니다.
모델 주요 필드 설명
다음은 res.partner 모델에서 실무적으로 자주 쓰이는 주요 필드들입니다. 이 필드들을 이해하면 연락처를 관리하고 통합할 때 실수를 줄일 수 있습니다.
1. name
형식: Char. 레코드의 대표명입니다. 회사라면 회사명, 개인이라면 성명으로 사용되며, 많은 화면에서 파트너를 식별하는 기본값으로 보여집니다.
2. create_date
형식: Datetime. 레코드가 처음 생성된 일시를 자동으로 저장합니다. 리포트나 감사 추적에 유용합니다.
3. write_date
형식: Datetime. 마지막 수정 시각을 자동으로 기록합니다. 언제 데이터가 갱신됐는지 추적하는 데 쓰입니다.
4. email
형식: Char. 주요 이메일 주소입니다. 커뮤니케이션, 송장 발송, 포털 접근에 사용되며 가능하면 형식 검증이 적용됩니다.
5. phone
형식: Char. 주 연락처(전화번호)입니다. 연락처 폼에 표시되고 커뮤니케이션 워크플로에서 기본으로 사용됩니다.
6. mobile
형식: Char. 휴대전화 번호입니다. SMS 발송이나 긴급 알림 용도로 주로 구분해서 사용합니다.
7. street
형식: Char. 주소의 첫 번째 줄로, 문서나 폼에서 표준 주소 블록으로 사용됩니다.
8. street2
형식: Char. 주소의 두 번째 줄입니다. 아파트 번호나 건물명 등 추가 정보를 담습니다.
9. city
형식: Char. 도시명(시·군·구 등)을 저장합니다. 국가별 주소 표기 방식이 다를 수 있습니다.
10. zip
형식: Char. 우편번호입니다. 주소 검증과 배송비 계산에 영향을 줍니다.
11. state_id
형식: Many2one (res.country.state). 주·도·성 정보를 가리키며, country_id에 따라 도메인이 필터링됩니다. 모든 국가에 해당하지는 않습니다.
12. country_id
형식: Many2one (res.country). 국가 정보를 저장하며 주소 포맷, 세금 규칙, 현지화 처리에 영향을 미칩니다.
13. is_company
형식: Boolean. 레코드가 회사인지 개인인지를 나타냅니다. 회사는 하위 연락처를 둘 수 있고, 개인은 parent_id를 통해 회사와 연결됩니다.
14. parent_id
형식: Many2one (res.partner). 연락처가 속한 회사(또는 상위 파트너)를 가리키는 필드로, 회사-연락처 계층을 구성합니다. 설정 시 주소 등 일부 값을 상속할 수 있습니다.
15. child_ids
형식: One2many (res.partner). parent_id의 역관계로 회사에 속한 모든 연락처를 목록으로 보여줍니다. 회사에서 관련 연락처로 이동할 때 사용합니다.
16. company_id
형식: Many2one (res.company). 멀티컴퍼니 환경에서 해당 파트너가 속한 Odoo 회사를 지정합니다. 가시성 및 접근 권한에 영향을 줍니다.
17. vat
형식: Char. 세금 식별번호(VAT)입니다. 국가별 포맷으로 검증하며, 과세대상이 아님을 표시할 때는 슬래시 등을 관례적으로 사용하기도 합니다. 송장 처리와 준수에 중요합니다.
18. customer_rank
형식: Integer. 고객으로서의 상태를 나타내는 지표입니다. 판매 활동이 생기면 Odoo가 자동으로 증가시키며, 리스트 필터링과 우선순위 판단에 쓰입니다.
19. supplier_rank
형식: Integer. 공급업체 상태를 나타냅니다. 구매 주문이나 매입 전표가 생기면 증가하며, 벤더 식별에 사용됩니다.
20. user_id
형식: Many2one (res.users). 담당 영업사원 혹은 책임자를 지정합니다. CRM, 영업팀 배정, 활동 할당에 사용됩니다.
21. type
형식: Selection. 하위 연락처의 주소 용도(일반 연락처, 청구, 배송, 기타)를 선택합니다. 문서에 어떤 주소를 쓸지 결정하는 데 중요합니다.
22. ref
형식: Char. 내부 참조 코드입니다. 외부 시스템 매핑이나 커스텀 번호 체계에 유용합니다.
23. website
형식: Char. 웹사이트 URL로, 연락처 폼이나 전자상거래 문맥에서 활용됩니다.
24. comment
형식: Html. 내부 메모용 필드입니다. 영업 노트나 특별 지시사항을 기록할 때 사용하며 내부 사용자에게만 보입니다.
25. active
형식: Boolean. 소프트 삭제 플래그입니다. False로 설정하면 기본 뷰에서 아카이브되어 숨겨지지만 물리적으로 삭제되지는 않습니다.
26. lang
형식: Selection. 선호 언어를 저장해 이메일이나 문서를 해당 언어로 보낼 때 사용합니다. 부모 레코드에서 상속 받을 수 있습니다.
27. image_1920
형식: Binary. 파트너의 이미지나 로고를 저장합니다. 폼, 리포트, 웹사이트에서 다양한 크기로 사용됩니다.
28. category_id
형식: Many2many (res.partner.category). 태그나 카테고리로 고객 세분화, 필터링, 마케팅 분류에 활용됩니다. 필요에 따라 자유롭게 정의할 수 있습니다.
비즈니스 워크플로에서의 활용 사례
1. 영업 및 CRM
영업 담당자가 견적을 만들 때 고객을 res.partner에서 선택합니다. 동일한 파트너 레코드가 리드, 기회, 주문에 재사용되며 customer_rank와 user_id가 리포팅과 담당자 배정에 반영됩니다.
2. 회계·청구
송장과 매입 전표는 청구 주소로 파트너를 참조합니다. VAT 필드는 세금 계산에 사용되며, 신용 한도나 결제 조건도 파트너 단위로 관리되는 경우가 많습니다.
3. 구매 및 벤더 관리
구매 주문과 매입 전표는 res.partner에 연결됩니다. supplier_rank는 적극적인 공급업체를 식별하는 지표이며, buyer_id 같은 필드로 담당 구매자를 지정해 관리합니다.
4. 전자상거래 및 포털
웹사이트 방문자가 회원가입하면 파트너 레코드가 생성됩니다. 해당 레코드는 주문, 견적, 포털 접근에 사용되며 주소와 연락처 정보는 모두 이 레코드에서 가져옵니다.
5. 멀티컴퍼니 및 결산
멀티컴퍼니 환경에서는 동일한 실체가 회사별로 다른 파트너 레코드로 존재할 수 있습니다. company_id와 인터컴퍼니 규칙이 데이터 공유 방식을 결정합니다.
개발자가 이 모델을 확장하는 방법
개발자는 여러 패턴으로 res.partner를 확장합니다. Odoo의 모델 상속이 가장 일반적인 방법입니다.
모델 상속
모델을 확장할 때는 _inherit = 'res.partner'를 사용합니다. 새 필드를 추가하거나 메서드를 오버라이드하고 제약을 넣을 수 있습니다. 변경을 별도 모듈로 유지하면 업그레이드가 수월합니다.
필드 추가
상속 모델에 필요한 필드를 정의합니다. Char, Many2one, Boolean, Integer, Text, Selection 등 적절한 타입을 선택하고, 멀티컴퍼니 환경이라면 company-dependent 설정을 고려하세요.
파이썬 확장
create, write, unlink 같은 메서드를 오버라이드해 비즈니스 로직을 넣을 수 있습니다. 원본 동작이 필요하면 super()를 호출해야 하고, 계산 필드와 의존성은 주의 깊게 설계하세요.
Odoo Studio
Odoo Studio로 코드 없이 필드를 추가할 수 있어 빠른 커스터마이징에 적합합니다. 다만 복잡한 로직이나 장기 유지보수는 커스텀 모듈로 구현하는 것이 바람직합니다.
권장 실무 가이드
- 회사-연락처 계층 구조를 올바르게 사용하세요. 먼저 회사 레코드를 만들고 parent_id로 연락처를 연결하는 흐름이 권장됩니다.
- 정확한 주소 포맷과 세금 처리를 위해 country_id를 반드시 설정하세요.
- 신용관리나 리포팅에서 최상위 엔터티가 필요하면 commercial_partner_id를 사용해 그룹화를 하세요.
- API 통합 시에는 XML-RPC나 JSON-RPC를 사용하세요. res.partner 모델은 외부 API로 완전히 노출되어 있으므로 외부 ID 매핑을 꼼꼼히 검토해야 합니다.
- 커스텀 필드명은 x_ 접두사나 모듈 접두사를 붙여 향후 Odoo 버전과의 충돌을 피하세요.
자주 하는 실수들
- 중복 파트너를 무작정 생성하는 실수. email_normalized나 ref 필드를 이용해 중복 체크 및 병합 로직을 구현하세요.
- parent_id와 company_id를 혼동하는 것. parent_id는 회사-연락처 관계, company_id는 멀티컴퍼니 소속을 뜻합니다.
- 하위 연락처의 type을 설정하지 않아 청구·배송 주소가 잘못 쓰이는 경우가 있습니다. 문서용 주소는 정확한 type이 필요합니다.
- core 메서드를 오버라이드하면서 super()를 호출하지 않으면 다른 모듈이나 추후 업그레이드 시 문제가 생길 수 있습니다.
- 필수(custom) 필드를 추가하면서 기본값을 주지 않으면 기존 레코드가 검증 실패로 업그레이드에 실패할 수 있습니다.
맺음말
res.partner는 Odoo 전반에서 중심 역할을 하는 모델입니다. 연락처, 고객, 공급업체 정보를 보관하며, 필드 구조와 확장 방식을 이해하면 설정, 커스터마이즈, 통합 작업이 훨씬 원활해집니다.
기능 컨설턴트가 업무 흐름을 설계하든 개발자가 모듈을 제작하든, res.partner의 작동 원리를 꿰고 있으면 시간 절약과 오류 예방에 큰 도움이 됩니다.
Odoo 도입 지원이 필요하신가요?
Dasolo는 기업의 Odoo 도입·커스터마이징·최적화를 돕습니다. 특히 API 연동과 Odoo 개발에 전문성을 가지고 있으며, res.partner 같은 핵심 모델을 활용한 데이터 아키텍처 경험이 풍부합니다.
Odoo 도입, 맞춤 모듈 개발, 통합 작업에 도움이 필요하면 언제든 연락주세요. 데모 신청하기 프로젝트 논의를 위한 상담을 예약하세요.