Introduzione
Il campo Monetario è uno dei tipi di campo più utili e più frequentemente mal utilizzati in Odoo. Sembra un numero, memorizza come un float, ma non si comporta come nessuno dei due. Una volta che capisci cosa lo rende diverso, non utilizzerai mai più un semplice Float per un valore finanziario.
Se hai mai guardato il totale di un ordine di vendita, un importo di fattura o un prezzo di prodotto in Odoo, hai già utilizzato un campo Monetario. Sono ovunque nel modello di dati di Odoo e fanno silenziosamente gran parte del lavoro pesante intorno alla formattazione delle valute, all'arrotondamento e alla precisione.
Questa guida è per sviluppatori Odoo, consulenti e utenti aziendali con una mentalità tecnica che vogliono capire come funziona realmente il campo Monetario. Che tu stia seguendo un tutorial sui campi di Odoo, costruendo un modulo personalizzato o semplicemente cercando di capire perché i tuoi importi si arrotondano in modo diverso da quanto previsto, questo è il riferimento di cui hai bisogno.
Cos'è il campo Monetario in Odoo
Il tipo fields.Monetary è uno dei tipi di campo core di Odoo nel framework Odoo. È progettato specificamente per memorizzare valori denominati in valuta: prezzi, importi, totali, budget o qualsiasi numero che rappresenti denaro.
Ciò che lo rende distinto da un Float normale è la relazione obbligatoria con una valuta. Un campo Monetario sa sempre con quale valuta sta lavorando e utilizza quella valuta per determinare quanti decimali visualizzare e come arrotondare i valori memorizzati.
Come appare nell'interfaccia
Nell'interfaccia utente di Odoo, un campo Monetario visualizza il valore formattato secondo la valuta associata. Se la valuta è Euro, si vede qualcosa come € 1.234,50. Se è il Dollaro statunitense, si vede $ 1.234,50. Il numero di decimali segue la configurazione del record della valuta.
Il campo è completamente modificabile nelle viste modulo, si visualizza in modo chiaro nelle viste elenco e si integra naturalmente nelle tabelle pivot e nei report finanziari. Gli utenti finali non devono pensare affatto alla formattazione. Odoo gestisce tutto in modo trasparente.
Il tipo di dati sottostante
A livello di database, un campo Monetario è memorizzato come un float a doppia precisione in PostgreSQL. Le informazioni sulla valuta non sono memorizzate nella stessa colonna. Provengono da un record res.currency correlato, collegato tramite un campo Many2one separato nello stesso modello.
Questa separazione di valore e valuta è intenzionale. Mantiene i campi del database Odoo puliti e rende possibile cambiare la valuta di un record indipendentemente dagli importi memorizzati.
Come funziona il campo
Comprendere la meccanica dietro il campo Monetario ti aiuterà a usarlo correttamente e a evitare il tipo di problemi di arrotondamento o visualizzazione che sono sorprendentemente comuni nello sviluppo personalizzato di Odoo.
Il parametro currency_field
Ogni campo Monetario deve essere abbinato a un campo Many2one che punta a res.currency. Per impostazione predefinita, Odoo cerca un campo chiamato currency_id nello stesso modello. Puoi sovrascrivere questo con il parametro currency_field:
amount = fields.Monetary(string='Importo', currency_field='currency_id')Se il campo valuta è mancante o non impostato su un dato record, Odoo torna alla valuta dell'azienda. Questo previene errori gravi, ma in un ambiente multi-valuta produrrà una formattazione errata. Dichiarare sempre esplicitamente il campo valuta.
Arrotondamento e Precisione
Una delle principali differenze tra Monetario e Float è il modo in cui funziona l'arrotondamento. Il modello res.currency definisce il numero di decimali e il fattore di arrotondamento per ciascuna valuta. Quando Odoo legge o visualizza un valore Monetario, applica automaticamente quelle regole.
Questo significa che un valore memorizzato come 1.2349999 per un campo EUR verrà visualizzato come 1.23, non 1.235 o 1.23499. Questo è critico per i calcoli fiscali, i totali delle fatture e qualsiasi processo di riconciliazione finanziaria. Utilizzare un semplice Float in quei contesti produrrà alla fine discrepanze di arrotondamento difficili da rintracciare.
Interazione con l'ORM di Odoo
Nell'orm di Odoo, leggere un campo Monetario restituisce sempre un float di Python. Il contesto della valuta proviene dal campo valuta abbinato sullo stesso record. Quando si effettuano calcoli in Python che coinvolgono campi Monetari, utilizzare il metodo round() della valuta per preservare la precisione:
rounded_value = self.currency_id.round(self.amount)Questo evita errori di accumulo in virgola mobile che possono apparire nei totali su più righe o nei calcoli iterativi.
Campi Monetari nei Report QWeb
Nei modelli di report QWeb, i campi Monetari si integrano con un widget dedicato che formatta correttamente il valore nei PDF e nei report web:
<span t-esc="record.amount"
t-options='{"widget": "monetary", "display_currency": record.currency_id}'/>Questo garantisce il corretto simbolo di valuta e la formattazione decimale in ogni documento generato, indipendentemente dalla valuta sul record.
Casi d'uso aziendali
I campi monetari sono utilizzati in tutti i moduli standard di Odoo. Ecco cinque esempi concreti che illustrano dove e perché sono importanti nei flussi di lavoro aziendali reali.
1. Vendite: Prezzi dei Prodotti e Totali degli Ordini
Campi come price_unit, price_subtotal e amount_total sugli ordini di vendita e sulle righe degli ordini sono tutti campi Monetari. Rispettano automaticamente la valuta selezionata nell'ordine del cliente, che può differire dalla valuta operativa dell'azienda.
Quando un rappresentante di vendita crea un ordine in USD per un'azienda che opera in EUR, Odoo gestisce correttamente la visualizzazione, l'arrotondamento e la conversione perché il campo Monetario funziona sempre nel contesto della valuta del record, non della valuta di sistema.
2. Contabilità: Importi delle Fatture e Linee Fiscali
Nel modulo di contabilità, ogni colonna di importo su una fattura è un campo Monetario: amount_untaxed, amount_tax, amount_total. La valuta impostata sulla fattura guida l'arrotondamento di tutti questi valori.
Questo non è un dettaglio. Un arrotondamento errato sulle linee fiscali crea squilibri nelle registrazioni contabili che sono difficili da riconciliare. L'arrotondamento consapevole della valuta del campo Monetario è ciò che previene questi problemi a livello di dati.
3. CRM: Ricavi Attesi sulle Opportunità
Il campo expected_revenue su un'opportunità CRM è un campo Monetario. I team di vendita possono catturare i valori del pipeline nella valuta del potenziale cliente, mentre dashboard e report convertono tutto nella valuta dell'azienda per l'analisi del pipeline e la previsione.
Questa configurazione funziona in modo pulito proprio perché i campi Monetari portano informazioni sulla valuta insieme al loro valore numerico.
4. Acquisti: Prezzi dei Fornitori e Ordini di Acquisto
Gli ordini di acquisto utilizzano campi Monetari per i prezzi unitari e i totali, collegati alla valuta concordata con il fornitore. Una fattura di un fornitore in Yen giapponesi viene gestita allo stesso modo di una in Euro. Il campo Monetario si occupa della precisione e della visualizzazione senza alcuna gestione manuale da parte del team acquisti.
5. Campi personalizzati: Budget e monitoraggio degli obiettivi
Una richiesta di personalizzazione molto comune è l'aggiunta di un importo di budget, di un obiettivo di fatturato o di un tetto di costo a un progetto, a un dipartimento o a un modello personalizzato. In tutti questi casi, un campo Monetario è la scelta giusta. Si integra naturalmente con la valuta aziendale, viene visualizzato correttamente in moduli e liste e si comporta in modo prevedibile nei report e nelle esportazioni.
Utilizzare un Float per questo tipo di campo è tecnicamente possibile, ma porta a incoerenze di formattazione e problemi di arrotondamento non appena si presentano scenari multi-valuta.
Creare o personalizzare il campo
Ci sono due modi principali per aggiungere un campo Monetario a un modello Odoo: tramite Odoo Studio per un approccio senza codice, o tramite un modulo Python personalizzato per un controllo completo.
Utilizzare Odoo Studio
Odoo Studio include un tipo Monetario nel suo pannello di creazione dei campi. Quando utilizzi i campi di Odoo Studio per aggiungere un campo Monetario a un modello, Studio aggiunge automaticamente un campo currency_id se non esiste già su quel modello. Questo copre i casi d'uso più comuni senza scrivere alcun codice.
Una cosa di cui essere consapevoli: i campi creati da Studio utilizzano il prefisso x_ (ad esempio, x_studio_budget). Se il tuo modello ha già un campo currency_id, il nuovo campo Monetario lo utilizzerà. In caso contrario, Studio ne creerà uno nuovo. Quando hai diversi campi Monetari sullo stesso modello con valute potenzialmente diverse, vale la pena rivedere attentamente questo campo di valuta condiviso prima di andare in produzione.
Per scenari semplici, Studio è il modo più veloce per creare campi in Odoo e funziona bene per gli utenti aziendali che non hanno accesso allo sviluppo.
Approccio tecnico: Campi Python
In un modulo Odoo personalizzato, la creazione di un campo Monetario richiede due dichiarazioni: il campo stesso e il campo valuta associato. Questo è lo schema standard nello sviluppo dei campi Python di Odoo:
from odoo import fields, models
class ProjectTask(models.Model):
_inherit = 'project.task'
x_budget = fields.Monetary(
string='Budget',
currency_field='x_budget_currency_id',
)
x_budget_currency_id = fields.Many2one(
comodel_name='res.currency',
string='Budget Currency',
default=lambda self: self.env.company.currency_id,
)Impostare la valuta aziendale come predefinita è una scelta pratica per la maggior parte dei campi interni. Previene che il campo valuta appaia vuoto quando un utente apre per la prima volta un record, il che interromperebbe la formattazione del campo Monetario.
Campi Monetari Calcolati
I campi monetari funzionano bene come campi calcolati di odoo. Se hai bisogno di totalizzare gli importi delle righe o applicare una formula che produce un risultato monetario, questo è lo schema standard:
x_total_budget = fields.Monetary(
string='Budget Totale',
currency_field='currency_id',
compute='_compute_total_budget',
store=True,
)
@api.depends('x_line_ids.x_amount')
def _compute_total_budget(self):
for record in self:
record.x_total_budget = sum(record.x_line_ids.mapped('x_amount'))L'attributo store=True è importante se prevedi di filtrare, ordinare o aggregare su questo campo nelle viste elenco o nei report. I campi calcolati non memorizzati non possono essere utilizzati nei filtri di dominio ORM.
Aggiungere un Campo Monetario tramite l'API
Se hai bisogno di creare campi in Odoo programmaticamente tramite XML-RPC (ad esempio, come parte di uno script di configurazione remota), puoi creare il campo Monetario tramite ir.model.fields:
models.execute_kw(ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_budget',
'field_description': 'Budget',
'model_id': model_id,
'ttype': 'monetary',
'currency_field': 'currency_id',
'state': 'manual',
}]
)Questo fa parte del più ampio toolkit di personalizzazione di odoo disponibile tramite l'API XML-RPC, che è trattato in modo più dettagliato in altri articoli di questa collezione di blog.
Migliori pratiche
Il campo Monetario è semplice da usare una volta che conosci gli schemi. Ecco le pratiche che manterranno la tua implementazione pulita e prevengono problemi in futuro.
1. Non Usare Mai Float per Valori Finanziari
Questa è la regola più importante nello sviluppo di odoo quando si tratta di denaro. Se un campo rappresenta un prezzo, un importo, un totale, un budget o qualsiasi numero denominato in valuta, usa fields.Monetary. Un campo Float non ha consapevolezza della valuta e non arrotonderà correttamente tra diverse valute. Il campo Monetario esiste precisamente per risolvere questo problema.
2. Dichiarare Sempre Esplicitamente il Campo Valuta
Non fare affidamento sul fallback di Odoo a currency_id a meno che quel campo non esista effettivamente nel tuo modello. Imposta esplicitamente il parametro currency_field e dichiara sempre il corrispondente Many2one a res.currency. Questo rende chiara la relazione e previene comportamenti di fallback silenzioso in ambienti multi-valuta.
3. Imposta una Valuta Predefinita
Per i campi interni che utilizzeranno quasi sempre la valuta dell'azienda, imposta un valore predefinito sul campo valuta: default=lambda self: self.env.company.currency_id. Questo impedisce che il campo appaia vuoto nei nuovi record, il che farebbe scomparire il simbolo della valuta e la formattazione nell'interfaccia utente.
4. Usa store=True sui Campi Monetari Calcolati che Intendi Cercare
Se definisci un campo Monetario calcolato e ti aspetti che gli utenti o i report filtrino o ordinino in base ad esso, imposta store=True. I campi calcolati non memorizzati non possono apparire nei domini ORM o nelle viste basate su SQL. Questa è una fonte comune di confusione quando si costruiscono dashboard personalizzate in Odoo.
5. Usa Currency Round() per Calcoli Intermedi
Quando scrivi codice Python che esegue più passaggi aritmetici su valori Monetari, applica self.currency_id.round(value) a ciascun passaggio significativo piuttosto che solo alla fine. Gli errori di punto mobile si accumulano su più operazioni e applicare il rounding in anticipo previene discrepanze nei totali.
6. Sii Intenzionale nei Report Multi-Valuta
Quando aggrega valori Monetari attraverso record con valute diverse, non sommare semplicemente i numeri grezzi. Converti tutti i valori in una valuta comune prima utilizzando res.currency.compute(), oppure rendi il report specifico per la valuta. Mischiare valute in una somma produce numeri che sono tecnicamente corretti a livello di campo ma finanziariamente privi di significato.
Trappole comuni
Anche gli sviluppatori Odoo esperti si imbattono in problemi con i campi Monetari. Ecco gli errori più comuni e come evitarli.
Trappola 1: Campo Valuta Mancante
Il problema più frequente quando si aggiunge un campo Monetario è dimenticare di creare il campo Many2one associato alla valuta. Se currency_id non esiste nel modello, Odoo ricadrà silenziosamente sulla valuta dell'azienda in alcuni contesti e solleverà un errore in altri. Crea sempre il campo valuta insieme al campo Monetario, anche se non ti aspetti mai che gli utenti lo cambino.
Trappola 2: Due campi Monetari che condividono un campo Valuta con valute destinate diverse
Se hai due campi Monetari nello stesso modello che devono contenere valori in valute diverse (ad esempio, un prezzo cliente in EUR e un costo fornitore in USD), non possono condividere in modo sicuro un unico campo currency_id. Ognuno ha bisogno del proprio riferimento di valuta. Non farlo significa che un'impostazione di valuta sovrascrive entrambi i campi, il che produrrà dati errati e un comportamento dell'interfaccia utente confuso.
Trappola 3: Discrepanze di arrotondamento quando si aggregano valute diverse
Sommare i valori dei campi Monetari attraverso record con valute diverse produrrà totali che sembrano errati, perché stai aggiungendo importi in EUR a importi in USD come se fossero la stessa unità. Questa è una fonte comune di errori di reporting nelle aziende che operano in più valute. Normalizza sempre a una singola valuta prima di aggregare.
Trappola 4: Confronti in virgola mobile nelle ricerche ORM
Cercare un campo Monetario con un controllo di uguaglianza esatta (ad esempio, cercando record dove amount = 10.0) può far perdere record a causa di come i float sono memorizzati nel database. Usa >= e <= con una piccola tolleranza, o applica l'arrotondamento della valuta prima di confrontare i valori nella logica Python. Questo è un problema generale dell'odoo orm con campi basati su float, non specifico per Monetario, ma è più importante quando si tratta di denaro.
Trappola 5: Ignorare l'arrotondamento della valuta durante l'importazione dei dati
Quando importi record tramite CSV o XML-RPC che includono valori di campo Monetario, i numeri importati vengono memorizzati come forniti senza arrotondamento automatico. Se i tuoi dati sorgente hanno più cifre decimali di quelle consentite dalla valuta di destinazione, il valore memorizzato sarà tecnicamente corretto ma verrà visualizzato in modo diverso da quanto previsto e potrebbe causare piccole discrepanze nei totali. Applica l'arrotondamento della valuta nei tuoi script di importazione o nei passaggi di preparazione dei dati prima di inviare valori a Odoo.
Conclusione
Il campo Monetario è uno di quei tipi di campo Odoo che sembra semplice in superficie ma porta con sé un comportamento molto importante sotto. La sua stretta relazione con il record della valuta è ciò che lo rende affidabile per i dati finanziari: arrotondamento corretto, formattazione coerente e visualizzazione consapevole della valuta in tutta l'interfaccia Odoo e nel motore di report.
Usarlo correttamente, il che significa sempre abbinarlo a un campo di valuta esplicito e mai sostituire un Float per valori finanziari, ti salverà da un'intera categoria di bug sottili che sono notoriamente difficili da rintracciare in produzione. Il modello dati di odoo è costruito attorno a questo tipo di campo per un buon motivo.
Che tu stia seguendo una guida per sviluppatori odoo, personalizzando un modulo standard o costruendo qualcosa di nuovo da zero, ottenere i tuoi campi Monetari corretti è una delle decisioni fondamentali che plasmano quanto affidabilmente la tua implementazione Odoo gestisce il denaro.
Hai bisogno di aiuto con la tua implementazione di Odoo?
Presso Dasolo, aiutiamo le aziende a implementare, personalizzare e ottimizzare Odoo su tutte le scale e configurazioni. Che tu abbia bisogno di un modello dati pulito, di una strategia di campo personalizzata, di supporto multi-valuta o di un'implementazione completa di Odoo, il nostro team ha la profondità tecnica e funzionale per farlo nel modo giusto.
Se hai domande sui campi Monetari o su qualsiasi altro aspetto della tua implementazione di Odoo, siamo felici di aiutarti. Contattaci e parliamo di cosa stai costruendo.