Sub-project #2d — NexaCloud Dual-Run Reconciliation (Design)

Date: 2026-05-27
Status: Design (proceeding straight to build — approach determined by parent spec §10)
Module: fusion_centralize_billing (Odoo 19 Enterprise; tested on odoo-trial)
Parent: Sub-project #2. Depends on 2a (the importer creates the shadow subscriptions + the cpu_seconds charge catalog this reconciles against).
Model already exists: fusion.billing.reconciliation (service_id, partner_id, period, odoo_amount, external_amount, delta, status ∈ match/delta/resolved, note).

1. Goal

Prove, for ≥ 1 billing cycle, that Odoo's billing engine computes the same charge as NexaCloud already does — per subscription, per period — before any real billing is flipped. Read-only against NexaCloud; writes only fusion.billing.reconciliation rows in Odoo.

2. What gets compared

For each imported shadow subscription and period:

external_amount = NexaCloud's actual pre-tax charge for that subscription+period (the NexaCloud invoice subtotal, i.e. flat plan + its own metered overage, before HST).
odoo_amount = what Odoo would charge for the same period: flat + overage, where
- flat = the shadow subscription's plan-product line price_unit (the imported flat price), and
- overage = charge._compute_billable(cpu_seconds)[1] for the period's CPU usage, with cpu_seconds = Σ usage_records.cpu_hours × 3600 (the 2a unit convention).
delta = odoo_amount − external_amount.
status = match if abs(delta) ≤ tolerance (default $0.01, configurable), else delta.

Comparing pre-tax subtotals keeps it apples-to-apples — HST is native Odoo and not what we're validating; the metered math + catalog mapping is.

3. Architecture (mirrors 2a: pure compute split from the read)

_compute_reconciliation(flat_amount, charge, cpu_seconds, external_amount, tolerance) → (odoo_amount, delta, status). Pure, deterministic, unit-tested with fixtures. This is the reconciliation core.
_reconcile_rows(rows, tolerance=0.01) — pure Odoo: for each input row {subscription_external_id, period, cpu_seconds, external_amount}, resolve the shadow sale.order (by x_fc_nexacloud_subscription_id), its flat (plan-line price_unit) and its charge (by x_fc_nexacloud_plan_id → charge.plan_code), call _compute_reconciliation, and upsert one fusion.billing.reconciliation row keyed by (service_id, partner_id, period). Returns a summary {match, delta, skipped, failed}.
_read_reconciliation_rows(period=None) — read-only psycopg2 (reuses the 2a DSN): per subscription+period, Σ usage_records.cpu_hours and the NexaCloud invoice subtotal. Integration glue (validated manually, like 2a's reader); not unit-tested against a foreign DB.
Trigger: a button on the existing import wizard (“Run Reconciliation”) and a model method suitable for an ir.cron. A non-zero delta/failed count is surfaced loudly (banner + ERROR log), same as the importer.

4. 2a amendment (small, required)

Add x_fc_nexacloud_plan_id (Char) to sale.order and set it in the importer's _import_subscription (from subscription.plan_id). Reconciliation needs sub → plan → charge, and parsing it out of the product default_code would be fragile.

5. Idempotency / re-runnability

Reconciliation rows upsert on (service_id, partner_id, period), so re-running a period updates its row rather than duplicating — the dual-run is run every cycle.

6. Shadow-safety

Reconciliation is pure measurement: it reads NexaCloud and writes only fusion.billing.reconciliation. It never touches subscriptions, invoices, payments, or the charge catalog, so the 2a shadow guarantees are untouched.

7. Testing

TransactionCase on odoo-trial with fixtures:

_compute_reconciliation: under-quota match; overage match; a real delta flips status to delta; tolerance boundary.
_reconcile_rows: creates one recon row per subscription; match vs delta set correctly; re-run upserts (no duplicate); a row for an unknown subscription/charge lands in skipped/failed, not a crash.
amendment: importer sets x_fc_nexacloud_plan_id.

8. Out of scope

The flip (set charge.plan_id, attach tokens, confirm subs) — happens once deltas are within tolerance for ≥ 1 cycle; not automated here.
Reading NexaCloud RAM/disk/bandwidth (CPU is the only metered-overage metric in v1, per 2a).
A reconciliation dashboard/report view beyond the list of fusion.billing.reconciliation.

9. Success criteria

For fixture data where Odoo's math equals NexaCloud's, every row is match; where it diverges beyond tolerance, the row is delta with the correct signed delta.
Re-running a period upserts (no duplicate rows).
Full suite green on odoo-trial (FCB_EXIT=0).

4.9 KiB Raw Blame History Unescape Escape