feat(billing): design + scaffold fusion_centralize_billing

Centralize billing for all NexaSystems services (NexaCloud, NexaDesk,
NexaMaps, custom apps, memberships) on the Odoo 19 Enterprise instance,
replacing Lago. The module adds only the metering + integration layer;
native sale_subscription / account_accountant / payment_stripe do all the
financial work (invoicing, HST, dunning, portal, credit notes, Stripe).

Includes:
- Design spec (docs/superpowers/specs/2026-05-27-nexa-billing-centralized-design.md):
  6 locked decisions, architecture, data model, usage engine, Lago-shaped
  API, webhook control loop, NexaCloud pilot, phased dual-run migration.
- Module scaffold: 7 fusion.billing.* models (service, account.link, metric,
  charge, usage, webhook, reconciliation), bearer-auth API controller shell,
  security ACLs, README. Compiles on Odoo 19.0; engine/API bodies are stubs
  pending the implementation plan.
- CLAUDE.md rule #15: no sale.subscription model in Odoo 19 — a subscription
  is a sale.order(is_subscription) + sale.subscription.plan (verified live).

Task 0 verified: a single Stripe account is shared across NexaCloud and all
Lago providers, so no Stripe account/card migration is required.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

fusion_centralize_billing/models/__init__.py

@@ -0,0 +1,7 @@
+from . import service
+from . import account_link
+from . import metric
+from . import charge
+from . import usage
+from . import webhook
+from . import reconciliation

fusion_centralize_billing/models/account_link.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1
+from odoo import fields, models
+
+
+class FusionBillingAccountLink(models.Model):
+    """Identity resolution: maps an app's external account id to one res.partner.
+
+    Folds the NexaCloud user / NexaDesk tenant / NexaMaps client for the same
+    real-world client onto a single partner (the unified customer). See spec §5.1.
+    """
+
+    _name = "fusion.billing.account.link"
+    _description = "Fusion Billing — External Account → Partner Link"
+    _order = "service_id, external_id"
+
+    service_id = fields.Many2one(
+        "fusion.billing.service", required=True, ondelete="cascade", index=True,
+    )
+    external_id = fields.Char(
+        required=True, index=True,
+        help="The app's own account id (NexaCloud user, NexaDesk tenant, Maps client).",
+    )
+    external_email = fields.Char()
+    partner_id = fields.Many2one(
+        "res.partner", required=True, ondelete="restrict", index=True,
+    )
+
+    _service_external_uniq = models.Constraint(
+        "unique(service_id, external_id)",
+        "An external account can only link to one partner per service.",
+    )

fusion_centralize_billing/models/charge.py

@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1
+from odoo import fields, models
+
+
+class FusionBillingCharge(models.Model):
+    """Maps a plan + metric to quota + overage pricing.
+
+    This is where "5,000,000 included / $0.10 per 1k overage" (NexaMaps) or a
+    NexaCloud CPU-seconds quota lives. Keyed by the shared ``plan_code`` the app
+    references; Odoo owns the money, the app owns feature entitlements. See spec §5.1.
+    """
+
+    _name = "fusion.billing.charge"
+    _description = "Fusion Billing — Metered Charge (quota + overage)"
+    _order = "plan_code, name"
+
+    name = fields.Char(required=True)
+    plan_code = fields.Char(
+        required=True, index=True,
+        help="Shared plan_code the source app references (matches a sale.subscription.plan).",
+    )
+    plan_id = fields.Many2one(
+        "sale.subscription.plan",
+        help="Optional link to the Odoo recurrence/plan for this charge.",
+    )
+    metric_id = fields.Many2one(
+        "fusion.billing.metric", required=True, ondelete="restrict",
+    )
+    product_id = fields.Many2one(
+        "product.product", help="Usage product invoiced for overage.",
+    )
+    included_quota = fields.Float(
+        default=0.0, help="Units included before overage applies, per period.",
+    )
+    price_per_unit = fields.Monetary(help="Overage price per unit_batch.")
+    unit_batch = fields.Float(
+        default=1.0, help="Batch size for overage pricing, e.g. 1000 = priced per 1k.",
+    )
+    charge_model = fields.Selection(
+        [
+            ("standard", "Standard (per unit)"),
+            ("graduated", "Graduated"),
+            ("package", "Package"),
+            ("volume", "Volume"),
+        ],
+        default="standard", required=True,
+    )
+    currency_id = fields.Many2one(
+        "res.currency", default=lambda self: self.env.company.currency_id,
+    )
+    active = fields.Boolean(default=True)

fusion_centralize_billing/models/metric.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1
+from odoo import fields, models
+
+
+class FusionBillingMetric(models.Model):
+    """A billable metric (CPU-seconds, API calls, messages, tokens ...).
+
+    Defines how raw usage is aggregated within a billing period. See spec §5.1 / §6.
+    """
+
+    _name = "fusion.billing.metric"
+    _description = "Fusion Billing — Billable Metric"
+    _order = "code"
+
+    name = fields.Char(required=True)
+    code = fields.Char(required=True, index=True)
+    aggregation = fields.Selection(
+        [
+            ("sum", "Sum"),
+            ("max", "Max"),
+            ("last", "Last value"),
+            ("unique_count", "Unique count"),
+        ],
+        default="sum", required=True,
+    )
+    unit_label = fields.Char(help="e.g. CPU-seconds, API calls, messages, tokens.")
+    rounding = fields.Float(default=1.0)
+    active = fields.Boolean(default=True)
+
+    _code_uniq = models.Constraint("unique(code)", "Metric code must be unique.")

fusion_centralize_billing/models/reconciliation.py

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1
+from odoo import fields, models
+
+
+class FusionBillingReconciliation(models.Model):
+    """Dual-run shadow-mode comparison: Odoo-computed vs the app's actual billing.
+
+    During phased cutover (NexaCloud first), Odoo computes invoices while the app
+    keeps charging. This row records the per-customer, per-period delta so we only
+    flip once deltas are within tolerance. See spec §10.
+    """
+
+    _name = "fusion.billing.reconciliation"
+    _description = "Fusion Billing — Dual-Run Reconciliation"
+    _order = "period desc, service_id"
+
+    service_id = fields.Many2one(
+        "fusion.billing.service", required=True, ondelete="cascade", index=True,
+    )
+    partner_id = fields.Many2one("res.partner", required=True, ondelete="cascade", index=True)
+    period = fields.Char(required=True, help="Billing period label, e.g. 2026-05.")
+    odoo_amount = fields.Monetary()
+    external_amount = fields.Monetary(string="App-actual Amount")
+    delta = fields.Monetary(help="odoo_amount - external_amount.")
+    currency_id = fields.Many2one(
+        "res.currency", default=lambda self: self.env.company.currency_id,
+    )
+    status = fields.Selection(
+        [
+            ("match", "Within tolerance"),
+            ("delta", "Delta — investigate"),
+            ("resolved", "Resolved"),
+        ],
+        default="delta", required=True, index=True,
+    )
+    note = fields.Text()

fusion_centralize_billing/models/service.py

@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1
+import hashlib
+import secrets
+
+from odoo import api, fields, models
+
+
+class FusionBillingService(models.Model):
+    """A source app that pushes billing data (NexaCloud / NexaDesk / NexaMaps).
+
+    The bearer API key is shown ONCE on generation and stored only as a SHA-256
+    hash. This record is the auth + routing boundary for the inbound API and the
+    target for outbound webhooks. See spec §5.1 / §7 / §8.
+    """
+
+    _name = "fusion.billing.service"
+    _description = "Fusion Billing — Source Service"
+    _order = "name"
+
+    name = fields.Char(required=True)
+    code = fields.Char(
+        required=True, index=True,
+        help="Stable code the app identifies itself with, e.g. nexacloud / nexadesk / nexamaps.",
+    )
+    active = fields.Boolean(default=True)
+
+    api_key_hash = fields.Char(
+        string="API Key (SHA-256)",
+        help="Hash of the bearer key. The raw key is displayed once at generation time.",
+    )
+    webhook_url = fields.Char(help="Endpoint this app exposes to receive billing webhooks.")
+    webhook_secret = fields.Char(help="Shared secret for HMAC-SHA256 webhook signatures.")
+
+    account_link_ids = fields.One2many(
+        "fusion.billing.account.link", "service_id", string="Customer Links",
+    )
+    account_link_count = fields.Integer(compute="_compute_account_link_count")
+
+    _code_uniq = models.Constraint("unique(code)", "Service code must be unique.")
+
+    @api.depends("account_link_ids")
+    def _compute_account_link_count(self):
+        for rec in self:
+            rec.account_link_count = len(rec.account_link_ids)
+
+    def action_generate_api_key(self):
+        """Generate a fresh bearer key, store only its hash, return the raw key.
+
+        TODO(spec §7): surface the raw key once in the UI (wizard/notification).
+        """
+        self.ensure_one()
+        raw = secrets.token_urlsafe(32)
+        self.api_key_hash = hashlib.sha256(raw.encode()).hexdigest()
+        return raw

fusion_centralize_billing/models/usage.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1
+from odoo import fields, models
+
+
+class FusionBillingUsage(models.Model):
+    """Aggregated usage rollup for a (subscription, metric, period).
+
+    Aggregate-push model: apps send periodic counters (not raw events). The
+    ``idempotency_key`` makes re-sent counters safe — they never double-count.
+    A pre-invoice cron sums these and feeds billable quantity onto the subscription.
+
+    NOTE (Odoo 19, verified): the subscription is a ``sale.order`` with
+    ``is_subscription=True`` — there is no ``sale.subscription`` model. See spec §5.2.
+    """
+
+    _name = "fusion.billing.usage"
+    _description = "Fusion Billing — Aggregated Usage (period rollup)"
+    _order = "period_start desc"
+
+    subscription_id = fields.Many2one(
+        "sale.order", required=True, ondelete="cascade", index=True,
+        string="Subscription", domain=[("is_subscription", "=", True)],
+    )
+    metric_id = fields.Many2one(
+        "fusion.billing.metric", required=True, ondelete="restrict", index=True,
+    )
+    period_start = fields.Datetime(required=True)
+    period_end = fields.Datetime(required=True)
+    quantity = fields.Float(default=0.0)
+    source = fields.Char(default="push")
+    idempotency_key = fields.Char(
+        index=True, help="Dedupe key so re-sent counters never double-count.",
+    )
+
+    _idempotency_uniq = models.Constraint(
+        "unique(idempotency_key)", "Usage idempotency key must be unique.",
+    )

fusion_centralize_billing/models/webhook.py

@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Nexa Systems Inc.
+# License OPL-1
+from odoo import fields, models
+
+
+class FusionBillingWebhook(models.Model):
+    """Outbound webhook queue: lifecycle events delivered to source apps.
+
+    Processed by a cron with exponential backoff + HMAC-SHA256 signing, dead-lettered
+    after N attempts (mirror the proven retry pattern in NexaDesk's
+    lago-payment-retry-job). Apps react: suspend / restore / deprovision. See spec §8.
+
+    TODO(spec §8): cron processor, HMAC signing, backoff schedule.
+    """
+
+    _name = "fusion.billing.webhook"
+    _description = "Fusion Billing — Outbound Webhook Event"
+    _order = "create_date desc"
+
+    service_id = fields.Many2one(
+        "fusion.billing.service", required=True, ondelete="cascade", index=True,
+    )
+    event_type = fields.Char(
+        required=True, index=True,
+        help="invoice.payment_failed / invoice.payment_succeeded / "
+             "subscription.terminated / subscription.reactivated / usage.threshold_reached",
+    )
+    payload = fields.Json()
+    state = fields.Selection(
+        [
+            ("pending", "Pending"),
+            ("sent", "Sent"),
+            ("failed", "Failed"),
+            ("dead", "Dead-lettered"),
+        ],
+        default="pending", required=True, index=True,
+    )
+    attempts = fields.Integer(default=0)
+    next_retry_at = fields.Datetime()
+    signature = fields.Char(help="HMAC-SHA256 of the payload using the service webhook_secret.")
+    last_error = fields.Text()