0003 — Strategia di autenticazione per versione Odoo

• Status: accepted
• Date: 2026-04-26

Context

Odoo non ha una strategia di autenticazione uniforme tra le versioni supportate dal progetto:

• v16/17: solo username + password classici. L'API key non è effettivamente disponibile per integrazioni RPC.
• v18: introduce le API key, ma la xmlrpc/jsonrpc legacy le accetta come password durante il login, non come Bearer token.
• v19: introduce JSON-RPC v2, dove l'API key viaggia come Bearer token e Odooly richiede user="__api_key__" come sentinella.

Imporre lo stesso schema a tutte le versioni significherebbe rompere qualcosa: o si perde il supporto API key, o si perde il supporto v16/17.

Decision

InstanceConfig (config.py) accetta entrambe le forme e valida i campi in funzione della versione:

• v16/17: username + password_env obbligatori, api_key_env vietato (errore esplicito).
• v18/19: deve essere presente almeno uno tra api_key_env e (username + password_env). Se entrambi sono presenti, l'API key ha precedenza.

OdooClient._build_auth_kwargs (client.py) traduce poi la configurazione nei kwargs corretti per Odooly:

• v19 + api_key → user="__api_key__", api_key=<value>.
• v18 + api_key → user=<username>, password=<api_key> (legacy auth).
• altrimenti → user=<username>, password=<password>.

Consequences

• ✅ Una stessa configurazione instances.json può convivere con istanze v16/17 (legacy) e v18/19 (cloud) senza ramificazioni nel codice utente.
• ✅ Gli errori sono catturati a tempo di validazione (pydantic), non a tempo di RPC, riducendo i misdiagnostic.
• ⚠️ Per v18 con sola API key, attualmente Odoo si aspetta comunque un username valido come "user" del login. Vedi TODO(odoo18-auth) in config.py: la decisione futura è se richiedere username anche per v18-only o introdurre un sentinel come per v19.
• ⚠️ Aggiungere una nuova versione Odoo (v20+) richiederà aggiornare Literal[16, 17, 18, 19] in config.py, _validate_auth_fields, e _build_auth_kwargs. Lo slash command /add-odoo-version documenta i passi.