# NexaCloud → Odoo Invoice Ledger (Design)

- **Date:** 2026-05-27
- **Status:** Design approved (brainstorming) — pending written-spec review
- **Module:** `fusion_centralize_billing` (Odoo 19 Enterprise; build/test on odoo-trial, run on `nexamain`)
- **Supersedes (for NexaCloud):** the metered-billing direction (recompute charges from a CPU-seconds model). The dual-run proved that model captures ~6% of reality.

## 1. Why this exists (the pivot)

The dual-run reconciliation (2026-05-27) showed **94% of NexaCloud's revenue is billed
outside** the per-deployment/CPU-metered model the engine was built for:

| NexaCloud invoices | count | total |
|---|---|---|
| NOT linked to a `subscriptions` row (Hosting services, add-ons) | 22 | **$2,881.08** |
| Linked to a `subscriptions` row (what the metered importer reads) | 7 | **$180.79** |

NexaCloud bills via **Stripe** — service invoices (Odoo ERP Hosting / WordPress Hosting
~$214.50/mo), **add-ons** (Daily Backup, WhatsApp, Forms Builder, White Label), and
**Stripe proration** ("Remaining time on …"). That billing already works. **Re-implementing
Stripe's proration + add-on logic in Odoo is the wrong move.** Instead, Odoo **ingests
NexaCloud's actual invoices** and becomes the single **accounting system of record**
(posted invoices + reconciled payments + HST), while NexaCloud/Stripe keep doing the billing.

## 2. Goal & scope (locked in brainstorming)

- **Full accounting SoR:** posted `account.move` customer invoices, **Stripe payments
  reconciled** (invoices show paid, AR accurate), **HST** modelled.
- **All history + ongoing.** Backfill every NexaCloud invoice, then a daily cron for new ones.
- **Revenue split by service family** into distinct income accounts (P&L breakdown).
- **Draft-first rollout:** first nexamain run creates drafts for review, then bulk-post.

## 3. Architecture

A new ingestion component in `fusion_centralize_billing`, mirroring the importer's
read/write split (reuses the read-only DSN + the `account.link` partner mapping already
set up on nexamain):

- **`_read_nexacloud_invoices(since=None)`** — read-only `psycopg2`: `invoices` +
  `invoice_items` (+ `users` for partner resolution), optionally since a date. Returns
  plain row dicts. The only code touching NexaCloud.
- **`_ingest_invoices(data, post=False)`** — pure Odoo: for each NexaCloud invoice,
  upsert one `account.move` (`move_type='out_invoice'`) with lines, tax, and (if paid) a
  reconciled payment. Idempotent on `x_fc_nexacloud_invoice_id`. Returns a summary. With
  `post=False` invoices are left **draft**; a separate `_post_ingested(...)` bulk-posts
  after review.
- Trigger: an **`account.move`-creation wizard/action** + a daily `ir.cron` for ongoing.

## 4. Data mapping

### 4.1 Invoice → `account.move`
- `move_type='out_invoice'`, `partner_id` = unified `res.partner` (resolve `invoice.user_id`
  → `account.link` (service=nexacloud) → partner; create via the importer's resolver if missing),
  `invoice_date` = NexaCloud invoice date, `ref` = `invoice_number`, `currency_id` = CAD.
- New fields (x_fc_*) on `account.move`: `x_fc_nexacloud_invoice_id` (idempotency key, unique),
  `x_fc_stripe_invoice_id`.

### 4.2 `invoice_item` → `account.move.line` (one per item)
- `name` = item description, `quantity`, `price_unit`, `account_id` = the **service-family
  income account** (see 4.3).
- **Tax:** derive the invoice's effective rate from `invoice.tax / invoice.subtotal`; map to
  the matching Odoo `account.tax` — **HST 13%** when ≈13%, **no tax** when 0, else the closest
  configured tax. Odoo's computed tax must equal NexaCloud's `invoice.tax` (assert in tests).

### 4.3 Service-family → income account (keyword mapping, with fallback)
| Family | Matches (description keywords) |
|---|---|
| **Hosting** | "Odoo ERP Hosting", "WordPress Website Hosting" |
| **Managed plans** | "Managed", "Managed Odoo - Standard", "… - Managed" |
| **Add-ons** | "Daily Backup Protection", "WhatsApp Business Messaging", "Forms Builder", "White Label Branding" |
| **Proration** | "Remaining time on …" → resolve to the family of the named item |
| **Other** (fallback) | anything unmatched → a generic NexaCloud income account (flagged in the summary for review) |

Income-account codes come from the COA (`nexa_coa_setup`); confirm/create at implementation.

### 4.4 Payment reconciliation
- For invoices with `status='paid'` (or `amount_paid >= amount_due`): register an
  `account.payment` via a **"NexaCloud Stripe" bank journal**, dated `paid_at`, amount
  `amount_paid`, ref = `stripe_invoice_id`; reconcile it against the posted invoice so the
  invoice shows **paid** and AR clears.
- Open/unpaid invoices: post (or draft) without a payment → they sit in AR. Void invoices:
  ingest as cancelled (or skip) — decide from the data at implementation.

## 5. Idempotency & ongoing sync
- Upsert on `x_fc_nexacloud_invoice_id` (a DB-unique field on `account.move`). Re-running
  updates a still-draft move or skips a posted one (never duplicates, never silently mutates
  a posted ledger entry — posted invoices that changed upstream are reported for manual review).
- Daily `ir.cron` calls `_read_nexacloud_invoices(since=last_run)` → `_ingest_invoices(post=True)`
  for go-forward invoices (configurable auto-post once trusted).

## 6. Safety & rollout (touches the live ledger)
1. Build + **TDD on odoo-trial** (fixture invoices → assert move totals, tax = source tax,
   payment reconciled, idempotency, family→account mapping).
2. **Dry-run** mode (read + report, write nothing) — like the importer.
3. First **nexamain** run: ingest **all history as DRAFT**, report a summary (counts per
   family, total $, unmatched-"Other" lines, tax mismatches). **You review a sample.**
4. **Bulk-post** after approval. Then enable the daily cron.
5. **Prune the obsolete metered shadow data** first: delete the 87 draft shadow
   `sale.order`s (`x_fc_shadow=True`), the ~464 `NC-*` products, the NexaCloud charges, and
   the reconciliation rows — they belong to the superseded recompute approach and would
   confuse the ledger.

## 7. Out of scope
- The metered recompute engine's go-live (flip, control loop, usage push) — superseded for
  NexaCloud. The engine code stays in the module (potential future metered service, e.g.
  NexaMaps) but is inert.
- NexaDesk / NexaMaps ledgers — separate (same ingestion pattern when needed).
- Reproducing Stripe's billing logic — explicitly NOT done; we ingest its output.

## 8. Verify at implementation (Odoo 19; never from memory)
- `account.move` / `account.move.line` / `account.payment` field names + the post flow
  (`action_post`) and payment register/reconcile API (read `account` + `account_accountant`
  reference on odoo-trial).
- The HST `account.tax` record + income accounts + a usable bank journal on `nexamain`
  (from `nexa_coa_setup`); create the "NexaCloud Stripe" journal + family income accounts if absent.
- Whether `invoice_items.amount` is pre-tax (expected: `invoice.subtotal = Σ items`; tax separate).

## 9. Success criteria
- A fixture NexaCloud invoice ingests to a posted `account.move` whose untaxed total, tax
  (= source `invoice.tax`), and total match the source; a paid one is reconciled and shows paid.
- Re-running ingests nothing new (idempotent).
- Dry-run on nexamain reports the full backfill (counts per family, $ totals, unmatched lines)
  with zero writes; the real run creates drafts; bulk-post on approval.
- Full suite green on odoo-trial (`FCB_EXIT=0`).

## 10. Backfill status + go-forward caveat (2026-05-27)

- **Backfill done + verified on nexamain.** 23 customer invoices posted + payment-reconciled
  ($3,403.46), 1 void deleted. NexaCloud's `created_at`/`status`/`paid_at` proved
  **unreliable** (sync-stamped today; one void marked otherwise), so invoice + payment dates
  and paid status were verified against the **source systems**:
  - **Stripe** (14 invoices, `in_*` ids) — real `created` / `paid_at` via the Stripe API.
  - **Lago** (9 `NEX-*` invoices, `lago:*` ids, billed pre-Stripe) — `issuing_date` +
    `payment_status=succeeded` via the Lago API (`billing.nexasystems.ca/api/api/v1`, key in
    Fusion-Chat; Lago host 192.168.1.117, double-hop ssh via supabase-prod).
  Partner names came from the NexaCloud `company` field (not the user's full_name).
- **GO-FORWARD: verified sync is LIVE (2026-05-27).** The verification used in the backfill
  is now folded into the ingest path, and the daily cron is enabled:
  - `_fc_verify(inv)` routes each invoice to its source by `stripe_invoice_id` prefix
    (`in_` → Stripe REST `GET /v1/invoices/{id}`; `lago:` → Lago REST) and returns
    `{invoice_date, void, draft, paid, paid_at, amount_paid}` taken from the SOURCE — or
    `None` if it can't be determined/reached. Credentials live in `ir.config_parameter`:
    `fusion_billing.stripe_api_key` (set, live), `fusion_billing.lago_api_url` /
    `fusion_billing.lago_api_key` (optional; unset — no new Lago invoices expected).
  - `_cron_sync_verified()` reads all NexaCloud invoices, skips ones already posted, then
    for the rest: skips **void** and **draft** (not finalized at source), logs **unverified**
    for retry next run, and ingests the rest with `_ingest_invoices(post=True, verified=…)`
    so the move uses the source invoice_date (accounting date too) and a payment is
    reconciled ONLY when the source confirms paid. Never acts on NexaCloud's raw fields.
  - Cron `cron_fc_invoice_ledger` on nexamain: **active**, daily at 06:00 UTC. (A stale
    pre-existing copy of this record still called the removed `_cron_ingest_recent`; because
    the data file is `noupdate="1"` the upgrade didn't rewrite it, so its server-action code
    + name were corrected once via SQL. Fresh installs get the right definition from the XML.)
  - First live run (2026-05-27): 23 already-posted, 1 void + 2 Stripe drafts + 5 genuine
    $0 invoices all correctly skipped, **0 new posted**, ledger intact at $3,403.46.
  - Verification helpers are unit-tested without network (routing short-circuits when no
    credentials are set; the cron is exercised with `_read_nexacloud_invoices` / `_fc_verify`
    patched). Full suite green on odoo-trial (`FCB_EXIT=0`).