Pole Integer w Odoo — Kompletny Poradnik dla Programistów

Wprowadzenie

Jeżeli kiedykolwiek wpisywałeś ilość na zamówieniu sprzedaży, odliczałeś dni otwarcia zadania albo przypisałeś priorytet leadowi, najpewniej korzystałeś z pola Integer w Odoo. To uniwersalny typ danych w modelu Odoo — prosty, ale często niedoceniany w projektach.

Zrozumienie specyfiki pola Integer jest istotne nie tylko dla administratorów konfigurujących formularze, lecz także dla deweloperów piszących moduły i konsultantów projektujących model danych dla klientów.

Ten przewodnik wyjaśnia, co pole Integer przechowuje, jak zachowuje się w ramach ORM i interfejsu Odoo oraz jak je tworzyć lub modyfikować za pomocą Odoo Studio i kodu Python. Znajdziesz tu też praktyczne przykłady i wskazówki, na co zwracać uwagę.

Czym jest pole Integer w Odoo

W Odoo pole Integer przeznaczone jest do przechowywania liczb całkowitych — bez miejsc dziesiętnych i ułamków. W bazie danych odpowiada kolumnie typu INTEGER w PostgreSQL (4 bajty), co daje zakres wartości sięgający około -2 miliardów do +2 miliardów.

Dla użytkownika pole Integer wygląda jak zwykłe pole numeryczne w formularzu albo kolumna liczby w widoku listy. To naturalny wybór tam, gdzie liczymy pełne jednostki: ilości sztuk, punkty, dni trwania czy numery sekwencyjne — sytuacje, w których połówki nie mają sensu.

Poniżej przykład deklaracji pola w module Python (zobacz sekcję techniczną dla pełnego kontekstu).

from odoo import fields, models

class ProjectTask(models.Model):
    _inherit = 'project.task'

    estimated_hours = fields.Integer(
        string='Estimated Hours',
        default=0,
    )

Parametr string określa etykietę widoczną w UI, a default ustawia wartość początkową przy tworzeniu nowego rekordu.

W Odoo Studio typ ten figuruje jako Integer. Pola dodane przez Studio otrzymują automatycznie prefiks x_studio_, natomiast pola tworzone w kodzie lub przez API mają techniczną nazwę określoną przez twórcę.

Jak działa to pole

Gdy definiujesz pole Integer, Odoo automatycznie tworzy odpowiadającą kolumnę w bazie danych podczas instalacji lub aktualizacji modułu — nie musisz pisać migracji SQL ręcznie.

Na poziomie bazy kolumna jest typu INTEGER. ORM Odoo zajmuje się konwersjami typów: pusty input zwróci 0, a nie None czy False. To kluczowa różnica w porównaniu z polami Float czy Char, które mogą zwracać False przy braku wartości.

Kluczowe atrybuty pola

Poniżej najważniejsze właściwości, które można skonfigurować dla pola Integer:

• string: Etykieta wyświetlana użytkownikowi.
• default: Wartość przypisywana automatycznie nowym rekordom. Jeśli nie podasz, domyślnie to 0.
• required: Oznacza pole jako obowiązkowe. Ponieważ domyślną wartością jest 0, opcja ta przydaje się, gdy chcesz uniemożliwić zapis rekordu z wartością zerową.
• readonly: Uniemożliwia edycję pola w interfejsie.
• index: Tworzy indeks PostgreSQL na kolumnie, przyspieszając filtrowanie i wyszukiwanie po tym polu.
• compute: Powiązanie z metodą Pythona, która oblicza wartość pola na podstawie innych danych.
• store: W połączeniu z compute decyduje, czy obliczona wartość jest zapisywana w bazie, czy też przeliczana za każdym razem.
• copy: Określa, czy wartość ma być kopiowana podczas duplikowania rekordu.
• groups: Ogranicza widoczność pola do określonych grup użytkowników.

Wygląd w widokach

W formularzach pole Integer renderuje się jako pole numeryczne — Odoo dodaje separatory tysięcy przy większych liczbach, co poprawia czytelność.

W widokach listy wartości są wyrównane do prawej, zgodnie ze zwyczajem. W widokach wyszukiwania pole obsługuje operatory: równe, większe niż i mniejsze niż.

Możesz też użyć widgetów, które zmieniają sposób prezentacji. Na przykład widget priority zamienia liczbę na klikalne gwiazdki, a progressbar pokaże pasek postępu, gdy wartości powiążesz z maksimum.

Interakcja z ORM Odoo

Z punktu widzenia dewelopera odczyt i zapis pola Integer jest prosty — w Pythonie zawsze otrzymasz int. Puste pole zwróci 0, więc trzeba uważać przy warunkach sprawdzających „brak wartości” — zero może oznaczać zarówno faktyczną wartość, jak i brak wpisu.

Pola Integer sprawdzają się też w polach obliczanych i filtrach domenowych używanych w widokach, akcjach serwerowych czy automatyzacjach w całym systemie.

Zastosowania biznesowe

Pole Integer pojawia się praktycznie w każdym module Odoo. Poniżej pięć typowych scenariuszy, gdzie jest kluczowe.

1. CRM: ocena leadów

Zespoły sprzedaży często sortują leady według punktacji. Możesz dodać pole Integer «Lead Score» na modelu okazji i pozwolić handlowcom ręcznie wpisywać punkty lub obliczać je automatycznie na podstawie kryteriów takich jak wielkość firmy, budżet czy aktywność.

Dzięki temu łatwiej priorytetyzować pipeline i skupić się na najbardziej obiecujących szansach.

2. Sprzedaż: minimalne wielkości zamówień

W modułach Sprzedaż i Magazyn Integer sprawdza się do określania minimalnych ilości zamówienia przy produktach lub cennikach. Ustawienie minimum na 10 sztuk zablokuje złożenie zamówienia poniżej tej liczby, co ogranicza późniejsze korekty i wyjaśnienia z klientami.

3. Magazyn: reguły uzupełniania zapasów

Reguły zamawiania w Odoo opierają się na Integerach dla progów minimum i maksimum. Gdy stan spadnie poniżej minima, Odoo tworzy zamówienie uzupełniające do zdefiniowanego maksimum. Poprawne ustawienie tych wartości zapobiega zarówno brakowi towaru, jak i nadmiernym zapasom.

4. Zarządzanie projektami: story points i estymacje

Zespoły korzystające z modułu Project często dodają pole Integer na story points lub estymowane godziny pracy. Widoczne na zadaniu w kanbanie lub liście ułatwia śledzenie pojemności zespołu i tempa realizacji sprintów.

5. Księgowość: liczba dni płatności

Warunki płatności w Księgowości definiuje się przez Integer określający liczbę dni (np. Net 30, Net 60). Te wartości wpływają na daty płatności faktur, dlatego ich poprawność ma bezpośrednie znaczenie dla przepływów pieniężnych.

Tworzenie i dostosowywanie pola Integer

Dodawanie pola Integer odbywa się na dwa główne sposoby: przez Odoo Studio bez kodu albo przez definicję w Pythonie, gdy potrzebujesz pełnej kontroli.

Korzystanie z Odoo Studio

Odoo Studio to narzędzie no-code/low-code wbudowane w Odoo, służące do szybkiego dodawania pól i modyfikacji widoków. Jak to zrobić w Studio:

1. Otwórz formularz, do którego chcesz dodać pole.
2. Aktywuj Studio z menu w prawym górnym rogu.
3. Z listy pól po lewej przeciągnij typ Integer na formularz.
4. Nadaj etykietę, ustaw, czy pole ma być wymagane i definuj wartość domyślną.
5. Zapisz zmiany i wyjdź ze Studio.

Studio automatycznie tworzy pole z prefiksem x_studio_ i zapisuje definicję w ir.model.fields. Pole staje się natychmiast dostępne w formularzach i listach.

Tworzenie przez Python (dostosowanie techniczne)

Deweloperzy budujący moduły definiują pole bezpośrednio w klasie modelu Pythona. To daje pełną kontrolę nad atrybutami pola i integracją z logiką biznesową.

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='Score from 0 to 100 used to prioritize opportunities',
    )

Po dodaniu pola w kodzie uruchom aktualizację modułu (np. odoo-bin -u your_module), by zmiany zostały zastosowane i kolumna utworzona w bazie danych.

Tworzenie przez XML-RPC API

Pola Integer można także dodać zdalnie przez XML-RPC API Odoo — przydatne przy automatycznych wdrożeniach lub gdy nie masz bezpośredniego dostępu do serwera.

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',
    }]
)

Dla pola Integer ttype ma wartość 'integer', a state 'manual' oznacza pole niestandardowe (nie zdefiniowane przez moduł).

Dodawanie pola obliczanego typu Integer

Pola obliczane są przydatne, gdy wartość ma być wyprowadzona z innych danych — na przykład zliczanie otwartych zadań przypisanych do projektu.

class Project(models.Model):
    _inherit = 'project.project'

    open_task_count = fields.Integer(
        string='Open Tasks',
        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),
            ])

Ustawienie store=True powoduje zapisanie wyniku w bazie, co umożliwia filtrowanie i sortowanie po tym polu bez konieczności przeliczania za każdym razem.

Dobre praktyki

Praktyczne wskazówki dotyczące wykorzystania pola Integer w modelu danych Odoo.

Używaj Integer do zliczeń i wartości całkowitych

Stosuj Integer gdy wartość ma być zawsze liczbą całkowitą. Dla wartości pieniężnych, miar wymagających ułamków lub wszędzie tam, gdzie dopuszczalne są części jednostek, wybierz Float lub Monetary.

Zadbaj o sensowną wartość domyślną

Domyślnie Integer ma wartość 0. Zastanów się, czy zero ma w Twoim procesie semantykę — jeśli nie, warto to uwzględnić w logice biznesowej lub dodać pole Boolean informujące, czy wartość została ustawiona.

Dodaj indeks, jeśli często filtrujesz po polu

Jeżeli pole będzie często używane w warunkach wyszukiwania, sortowania lub grupowania, dodaj index=True. Indeks przyspieszy zapytania w dużych bazach kosztem niewielkiego narzutu na zapis i przestrzeń dyskową — zwykle opłacalne.

Używaj store=True dla pól obliczanych używanych w filtrach

Pole obliczane, po którym zamierzasz filtrować lub grupować w widokach, powinno mieć store=True. W przeciwnym razie Odoo nie będzie mogło użyć go w domenach ani grupowaniach tak, jak oczekujesz.

Dokumentuj dopuszczalne zakresy wartości

Gdy pole ma określony sensowny zakres (np. ocena 0–100), dodaj opis w parametrze help. Tekst pojawi się jako podpowiedź w interfejsie i zapobiegnie przypadkowym wpisom poza zakresem.

Przemyśl użycie Integer do przechowywania identyfikatorów

Jeśli chcesz odnieść się do innego rekordu, znacznie lepszym rozwiązaniem jest pole Many2one zamiast przechowywania surowego ID w Integerze. Many2one zapewnia nawigację, reguły kaskadowe i pełną integrację z ORM — surowe ID jest kruche i omija mechanizmy Odoo.

Typowe pułapki

Najczęściej popełniane błędy przy pracy z polem Integer.

Mylne użycie Integer zamiast Float

Częstym błędem jest wybór Integer tam, gdzie konieczna jest precyzja dziesiętna. Jeśli użytkownicy mogą wpisywać 1.5 lub 0.25, Integer spowoduje obcięcie części ułamkowej i utratę danych. Dla miar z ułamkami użyj Float, a dla walut — Monetary.

Przyjmowanie, że zero oznacza brak wartości

Skoro pusty Integer zwraca 0, nie da się rozróżnić „nigdy nie ustawione” od „ustawione na zero”. Jeśli ta różnica jest ważna, dodaj pole Boolean informujące o przypisaniu wartości (np. has_score) albo użyj innego typu pola, który może zwrócić False.

Brak indeksu na polach często używanych w filtrach

Jeżeli pole Integer jest wykorzystywane w filtrach lub automatyzacjach, brak index=True może spowolnić działanie widoków na dużych zbiorach danych. Łatwiej dodać indeks od początku niż optymalizować później.

Przechowywanie wartości procentowych jako całkowitych

Przykładowo zapisanie 75 jako 75% działa do czasu, gdy potrzebna będzie precyzja, np. 72.5%. Jeśli istnieje ryzyko, że proporcje będą wymagać części ułamkowych, użyj Float już na starcie.

Zapomnienie o store=True w polach obliczanych używanych w filtrach

To częsty błąd: obliczane pole bez store=True nie nadaje się do użycia w domenach, akcjach automatycznych ani grupowaniach. Pomyśl zawczasu, jak pole będzie wykorzystywane, zanim zdecydujesz się go nie zapisywać.

Podsumowanie

Pole Integer to fundament modelu danych Odoo — prosty, ale z własnymi niuansami. Wiedza o tym, że puste pole zwróci 0 i że pole obliczane wymaga store=True, pozwala unikać trudnych do wykrycia błędów i projektowych potknięć.

Niezależnie czy konfigurujesz Odoo dla działu sprzedaży, tworzysz moduł czy ustawiasz reguły uzupełniania w magazynie, pola Integer pojawią się na każdym kroku. Wiedza kiedy je stosować zamiast Float czy Monetary zapewnia stabilność i łatwość utrzymania wdrożenia.

Jeżeli pracujesz nad dostosowaniem Odoo i chcesz mieć pewność, że model danych będzie poprawny od początku, taka podstawowa wiedza zwraca się przez cały czas trwania projektu.

Współpraca z ekspertem Odoo

W firmie Dasolo pomagamy klientom wdrażać, dostosowywać i optymalizować Odoo we wszystkich modułach i branżach. Projektujemy czytelne modele danych, tworzymy niestandardowe pola i procesy oraz integrujemy systemy zewnętrzne przez API — tak, by zrobić to raz i dobrze.

Jeśli masz pytania dotyczące Twojego środowiska Odoo lub chcesz przedyskutować projekt, skontaktuj się z naszym zespołem— chętnie doradzimy i pomożemy w realizacji.