From aa581e5cd938efbbe17fbec9d1a8687c3830f8c9 Mon Sep 17 00:00:00 2001
From: Claude Agent <claude-agent@romfast.ro>
Date: Wed, 8 Apr 2026 16:39:24 +0000
Subject: [PATCH] docs(address): update PJ/PF billing address rules in README +
 add decision doc
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

README.md: replace old different_person logic with PJ/PF rule description
docs/adrese_facturare_variante.md: new file — decision rationale, implementation
summary, verification commands, history of the change

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md                         |  5 +--
 docs/adrese_facturare_variante.md | 59 +++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+), 2 deletions(-)
 create mode 100644 docs/adrese_facturare_variante.md

diff --git a/README.md b/README.md
index 1da074a..6a970d8 100644
--- a/README.md
+++ b/README.md
@@ -195,9 +195,10 @@ gomag-vending/
 ### Reguli Business
 
 **Parteneri & Adrese:**
-- Prioritate partener: daca exista **companie** in GoMag (billing.company_name) → firma (PJ, cod_fiscal + registru). Altfel → persoana fizica, cu **shipping name** ca nume partener
+- Prioritate partener: daca exista **companie** in GoMag (billing.company.name SAU billing.company.code) → firma (PJ, cod_fiscal + registru). Altfel → persoana fizica, cu **shipping name** ca nume partener
 - Adresa livrare: intotdeauna din GoMag shipping
-- Adresa facturare: daca shipping name ≠ billing name → adresa shipping pt ambele; daca aceeasi persoana → adresa billing din GoMag
+- Adresa facturare **PJ**: adresa billing din GoMag (sediul firmei)
+- Adresa facturare **PF**: adresa shipping din GoMag (ramburs curier pe numele destinatarului)
 - Cautare partener in Oracle: cod_fiscal → denumire → create new (ID_UTIL = -3)
 
 **Articole & Mapari:**
diff --git a/docs/adrese_facturare_variante.md b/docs/adrese_facturare_variante.md
new file mode 100644
index 0000000..00bb6b4
--- /dev/null
+++ b/docs/adrese_facturare_variante.md
@@ -0,0 +1,59 @@
+# Adrese Facturare — Regula PJ vs PF
+
+## Cum funcționează ACUM
+
+| Tip client | Adresă livrare ROA | Adresă facturare ROA |
+|------------|-------------------|----------------------|
+| **PJ** (company.name SAU company.code populat) | GoMag shipping | GoMag **billing** (sediul firmei) |
+| **PF** (fără companie) | GoMag shipping | GoMag **shipping** (ramburs curier pe numele destinatarului) |
+
+**Motivație PF:** Banii ramburs de la curier se întorc pe numele de pe adresa de livrare, deci factura trebuie să fie pe aceeași adresă.
+
+**Motivație PJ:** Firma vrea factura pe sediul social (adresa billing din GoMag), nu pe adresa de livrare a curierului.
+
+## Detectie companie (is_company)
+
+```python
+is_company = isinstance(company, dict) and (
+    bool(company.get("name")) or bool(company.get("code"))
+)
+```
+
+Fallback CUI: dacă GoMag trimite `company.name=""` dar `company.code="RO12345678"` → tot PJ.
+Dacă `company_name` e gol dar există CUI → `denumire` = billing person name.
+
+## Implementare
+
+`api/app/services/import_service.py` — Step 3 (billing address):
+
+```python
+if is_pj:
+    # PJ: billing address = GoMag billing (company HQ)
+    billing_addr = format_address_for_oracle(order.billing.address, ...)
+    if billing_addr == shipping_addr:
+        addr_fact_id = addr_livr_id  # optimizare: reuse dacă identice
+    else:
+        addr_fact_id = cauta_sau_creeaza_adresa(billing_addr)
+else:
+    # PF: billing = shipping
+    addr_fact_id = addr_livr_id
+```
+
+## Verificare
+
+```bash
+# Audit comenzi existente
+python3 scripts/verify_address_rules.py --days 7
+
+# Teste Oracle E2E
+./test.sh oracle
+```
+
+## Istoricul deciziei
+
+**Înainte (greșit):** logica `different_person` — compara numele billing vs shipping.
+Dacă difereau → shipping pt ambele. Dacă identice → billing GoMag pt facturare.
+Problema: PJ cu persoane diferite primeau factura pe adresa de shipping (nu pe sediul firmei).
+
+**Decizie (2026-04-08):** Regula simplă PJ/PF, indiferent de compararea numelor.
+Doar comenzile NOI sunt afectate — comenzile existente rămân cu adresele curente.