Pole Float w Odoo — Kompletny Przewodnik dla Deweloperów

Wprowadzenie

Pole typu Float to jedno z najczęściej używanych pól w Odoo, gdy pracujemy z liczbami dziesiętnymi. Ceny jednostkowe, wagi produktów, procenty rabatów, stawki podatkowe czy współczynniki konwersji w BOM — to przykłady danych, które zwykle zapisuje się jako Float w modelu danych Odoo.

Na pierwszy rzut oka to zwykłe pole numeryczne, ale warto wiedzieć, jak Odoo zarządza precyzją, jak wyniki wpływają na raporty i agregacje oraz w jakich sytuacjach lepiej wybrać inny typ pola.

Ten przewodnik wyjaśnia, co Float przechowuje, jak zachowuje się w ramach frameworka Odoo, jak tworzyć i konfigurować takie pole za pomocą Odoo Studio lub kodu Python oraz przedstawia praktyczne przykłady zastosowań w sprzedaży, magazynie i księgowości.

Czym jest pole Float w Odoo

W ORM Odoo pole Float przechowuje liczby dziesiętne i mapuje się na kolumnę double precision w PostgreSQL, co daje do około 15 znaczących cyfr precyzji — zwykle więcej niż potrzeba w biznesie.

Dla użytkownika pole Float wygląda jak pole numeryczne w formularzu. Liczbę miejsc po przecinku kontroluje parametr digits zdefiniowany przy polu. W widokach listy wartości Float są wyrównane do prawej, a w tabelach przestawnych i wykresach biorą udział w agregacjach typu suma, średnia czy maksimum.

Tak wygląda definicja pola w modelu Python:

from odoo import fields, models

class SaleOrderLine(models.Model):
    _inherit = 'sale.order.line'

    custom_margin = fields.Float(
        string='Custom Margin',
        digits=(5, 2),
        default=0.0,
    )

Parametr digits to krotka, gdzie pierwsza liczba oznacza łączną liczbę cyfr znaczących, a druga liczbę miejsc po przecinku. Przykładowo (5, 2) pozwala na pięć cyfr znaczących z dwoma miejscami dziesiętnymi.

Zamiast wpisywać digits na stałe, można odwołać się do nazwanego zestawu precyzji:

price_premium = fields.Float(
    string='Price Premium',
    digits='Product Price',
)

Odoo oferuje gotowe grupy precyzji dostępne w Ustawieniach → Techniczne → Struktura bazy → Dokładność dziesiętna. Najczęściej używane to Product Price, Product Unit of Measure, Discount i Stock Weight. Korzystanie z takich grup pozwala zmieniać precyzję z poziomu interfejsu bez modyfikacji kodu.

W Odoo Studio pole Float występuje pod nazwą Decimal Number. Pole tworzone ze Studio używa domyślnej precyzji, chyba że w panelu właściwości ustawisz inaczej — dlatego to wygodne rozwiązanie dla realizacji prostych rozszerzeń bez developerów.

Jak działa to pole

Definiując pole Float Odoo automatycznie tworzy odpowiednią kolumnę w bazie danych przy instalacji lub aktualizacji modułu — nie trzeba pisać ręcznych skryptów SQL czy migracji.

Parametr digits wpływa jednocześnie na sposób wyświetlania i na zaokrąglanie wartości przed zapisem. Jeżeli ustawisz digits=(6, 2) i wpiszesz 3.14159, Odoo zaokrągli i zapisze 3.14. To zaokrąglenie odbywa się już na poziomie ORM, a nie tylko w widoku.

Kluczowe atrybuty pola

Poniżej najważniejsze właściwości, które warto skonfigurować dla pola Float w Odoo:

• digits: Krotka typu (6, 2) lub nazwana grupa precyzji. Steruje wyświetlaniem i zapisem wartości.
• required: Oznacza pole jako obowiązkowe. Uwaga: wartość 0.0 przejdzie walidację jako obecna, co nie zawsze jest oczekiwane.
• default: Wartość domyślna dla nowych rekordów. default=0.0 zapewnia, że pole zawiera liczbę, a nie False.
• compute: Powiązanie z metodą Pythona obliczającą wartość pola dynamicznie — przydatne dla marż lub współczynników przeliczania.
• store: W połączeniu z compute zapisuje wynik obliczeń w bazie, dzięki czemu można po nim wyszukiwać i grupować dane.
• group_operator: Określa, jak pole będzie agregowane w pivotach i wykresach — np. 'sum', 'avg', 'min', 'max'. Domyślnie Float to 'sum'.
• copy: Określa czy wartość jest kopiowana przy duplikowaniu rekordu. Domyślnie True.

Widoki i prezentacja

W formularzach Float renderuje się jako pole numeryczne i respektuje ustawienia lokalne użytkownika odnośnie separatora dziesiętnego. W listach jest domyślnie wyrównane do prawej. W wyszukiwaniu można filtrować wartości Float przy użyciu operatorów porównania.

Do pól Float można przypisywać widgety. Przykładowo widget percentage mnoży przechowywaną wartość przez 100 i dodaje znak procentu w wyświetleniu — przydatne, gdy pole przechowuje wartość w zakresie 0–1.

Interakcja z ORM Odoo

Odczyt pola Float zwraca w Pythonie typ float lub False, jeśli pole nie ma wartości i nie ustawiono domyślnie. Zapis akceptuje int, float lub False. Precyzja z digits jest stosowana przy zapisie.

W kodzie Pythona nie porównuj Float za pomocą operatora ==. Ze względu na reprezentację binarną porównania mogą dawać fałszywe wyniki. Zamiast tego używaj float_compare i float_is_zero z odoo.tools.float_utils, które uwzględniają zadeklarowaną precyzję.

Zastosowania biznesowe

Pole Float występuje praktycznie w każdym module Odoo. Oto pięć praktycznych przykładów jego zastosowania w rzeczywistych procesach biznesowych.

Sprzedaż: Procenty rabatu na pozycjach zamówienia

Natívne pole discount na sale.order.line to Float. Gdy sprzedawca wpisze 15% rabatu, Odoo zapisze 15.0 i użyje go w kalkulacji ceny jednostkowej. Ta wartość trafia do ofert, faktur i analiz marż — poprawne przechowywanie rabatów ma bezpośredni wpływ na komunikację z klientem i wyniki finansowe.

Magazyn: Wagi i objętości produktów

Produkty mają pola weight i volume, oba jako Float. Przykładowo waga 2,5 kg czy objętość 0,003 m3 wymaga precyzji dziesiętnej. Te wartości napędzają kalkulacje kosztów wysyłki i integracje z przewoźnikami — nieprawidłowe dane powodują błędne stawki zwracane przez API przewoźnika.

Księgowość: Stawki podatkowe

Stawki podatkowe w account.tax są polami Float. Standardowy VAT 21% zapisuje się jako 21.0, stawki obniżone jako 6.0 czy 5.5. Silna precyzja jest ważna, bo drobne różnice zaokrągleń kumulują się przy wielu transakcjach i mogą generować rozbieżności w raportach podatkowych.

Produkcja: Ilości w strukturach produktów (BOM)

W produkcji ilości komponentów w BOM to pola Float — receptura może wymagać 0,75 litra cieczy czy 2,5 kg surowca. Floaty obsługują takie wartości naturalnie. Użycie Integer dla ilości frakcyjnych prowadziłoby do zaokrągleń i błędów produkcyjnych narastających w czasie.

Zakupy: Współczynniki i marże dostawców

Przy cennikach dostawców i zasadach narzutów mnożniki i marże przechowuje się jako Float. Przykłady: współczynnik 1,25 (25% narzutu) lub 0,85 (15% rabatu). Te wartości wpływają na automatyczne obliczenia cen na zamówieniach zakupowych i pomagają standaryzować politykę cenową dostawców.

Tworzenie i modyfikacja pola Float

Są trzy główne sposoby dodania pola Float do modelu Odoo — zależnie od twojego podejścia i środowiska wdrożeniowego.

Odoo Studio (bez kodu)

Odoo Studio to narzędzie low-code do prostych modyfikacji. Aby dodać pole Float bez kodowania:

1. Otwórz Odoo Studio z menu głównego.
2. Przejdź do formularza, który chcesz rozszerzyć.
3. Przeciągnij pole Decimal Number z palety na formularz.
4. W panelu właściwości ustaw etykietę, wartość domyślną i liczbę miejsc po przecinku.
5. Zapisz i zamknij Studio.

Studio tworzy pole z prefiksem x_studio_ i automatycznie dodaje je do widoku formularza — bez konieczności ingerencji w bazę danych. To najprostsza ścieżka dla użytkowników biznesowych chcących szybko rozszerzyć formularze.

Własny moduł w Pythonie

Dla deweloperów rekomendowanym sposobem jest definiowanie pól w Pythonie — to konieczne, gdy zmiany mają być wersjonowane i wdrażane na wielu środowiskach:

from odoo import fields, models

class ResPartner(models.Model):
    _inherit = 'res.partner'

    x_credit_limit = fields.Float(
        string='Credit Limit',
        digits=(12, 2),
        default=0.0,
        help='Maximum outstanding balance allowed for this customer.',
    )

Po dodaniu pola w modelu dołącz go do odpowiedniego pliku XML widoku, aby był widoczny w interfejsie. Odoo samodzielnie zaktualizuje schemat bazy przy instalacji lub aktualizacji modułu — to standardowy sposób pracy dla deweloperów.

Z użyciem API XML-RPC

Gdy zarządzasz konfiguracją zdalnie — np. skryptami wdrożeniowymi — możesz tworzyć pola Float przez XML-RPC:

field_id = models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'ir.model.fields', 'create',
    [{
        'name': 'x_custom_coefficient',
        'field_description': 'Custom Coefficient',
        'model_id': model_id,
        'ttype': 'float',
        'state': 'manual',
    }]
)

Wartość state: manual oznacza, że pole zostało utworzone ręcznie, co jest typowe dla pól dodawanych przez Studio lub API. Precyzję dla pól utworzonych przez API reguluje ustawienie Dokładności dziesiętnej w menu technicznym. Taki scenariusz sprawdza się przy automatyzacji konfiguracji Odoo.

Dobre praktyki

1. Korzystaj z nazwanych grup precyzji

Zamiast twardo kodować digits=(6, 2), odwołuj się do grup takich jak 'Product Price' czy 'Product Unit of Measure'. Dzięki temu administracja może zmieniać precyzję z interfejsu, a twoje pola będą zgodne z natywnymi polami Odoo.

2. Dla kwot używaj pola Monetary, nie Float

To kluczowa zasada: pole Monetary jest przystosowane do wartości walutowych — powiązane z polem waluty, obsługuje reguły zaokrąglania i działa poprawnie w środowiskach wielowalutowych. Użycie Float dla kwot może prowadzić do błędów zaokrągleń i problemów w raportach finansowych.

3. Zawsze ustaw wartość domyślną

Nadaj default=0.0 dla pól numerycznych, które powinny zaczynać od zera. Brak domyślnej wartości powoduje, że pole zwraca False do czasu uzupełnienia, co może wywołać błędy w obliczeniach lub metodach zależnych od liczby.

4. Określ group_operator do raportów

Jeśli pole reprezentuje wartość sumowalną, ustaw group_operator='sum'. Gdy ma charakter wskaźnika czy stawki — użyj 'avg'. To kluczowe, żeby tabele przestawne i wykresy agregowały dane w sensowny sposób.

5. Dokumentuj konwencje procentowe

Jeżeli pole przechowuje procent, jasno określ czy używasz zakresu 0–100 (np. 15.0 dla 15%) czy 0–1 (np. 0.15 dla 15%). Mieszanie tych konwencji w modelu prowadzi do cichych błędów obliczeniowych trudnych do wykrycia.

Typowe pułapki

Kiedy Float nie jest odpowiedni dla kwot

Float nie przechowuje informacji o walucie. W środowisku wielowalutowym użycie Float dla kwot może dawać błędne sumy. Dla wartości walutowych stosuj pole Monetary, które jest powiązane z polem waluty i obsługuje zasady zaokrągleń.

Brak ustawienia parametru digits

Jeżeli nie określisz digits, Odoo domyślnie stosuje dwie cyfry po przecinku. To zwykle OK dla cen, ale nie dla kursów walut czy współczynników konwersji, które mogą wymagać 4–6 miejsc. Ciche zaokrąglenie współczynnika do 2 miejsc może generować narastające błędy.

Porównywanie Float przez == w Pythonie

Ze względu na reprezentację binarną dwie wartości, które wyglądają identycznie, mogą nie być równe przy użyciu ==. Przykład: 0.1 + 0.2 == 0.3 zwróci False. Stosuj float_compare(value1, value2, precision_digits=2) i float_is_zero(value, precision_digits=2) z odoo.tools.float_utils do bezpiecznych porównań.

Użycie Float tam, gdzie wystarczy Integer

Jeżeli pole zawsze przechowuje liczby całkowite (np. liczba paczek, egzemplarzy), użyj Integer. Float w takich miejscach wprowadza niepotrzebne zamieszanie i pozwala użytkownikom wpisywać wartości dziesiętne tam, gdzie to nie ma sensu.

Nieobsłużone wartości False w metodach compute

Pole Float bez wartości domyślnej zwróci False, a nie 0.0. Jeśli w metodzie compute nie sprawdzisz False przed działaniami arytmetycznymi, możesz otrzymać TypeError. Alternatywą jest zawsze ustawić default=0.0.

Podsumowanie

Pole Float to podstawowy element modelu danych Odoo. Pozwala przechowywać liczby dziesiętne dla cen, ilości, stawek i pomiarów, działając stabilnie, gdy skonfigurowane jest z odpowiednią precyzją i wartościami domyślnymi.

Najważniejsze wskazówki: korzystaj z nazwanych grup precyzji, stosuj Monetary do kwot walutowych, zawsze ustawiaj wartość domyślną i dokumentuj sposób przechowywania procentów. Te nawyki zapobiegają najczęstszym problemom z jakością danych.

Niezależnie od tego, czy dodajesz pola przez Odoo Studio, tworzysz moduł w Pythonie, czy zarządzasz modelem programowo przez ORM lub XML-RPC, poprawne zaprojektowanie pól Float od początku upraszcza wdrożenie i zwiększa jego niezawodność.

W Dasolo wspieramy firmy we wdrażaniu, dostosowywaniu i optymalizacji Odoo w całej organizacji. Pomagamy zarówno w projektowaniu przejrzystego modelu danych, jak i we wdrożeniu niestandardowych pól czy budowie kompletnego modułu. Skontaktuj się z nami i porozmawiajmy o Twoim projekcie Odoo.