"""Explain one customer's invoiced revenue with an exact ordered bridge.""" from contextlib import nullcontext from decimal import Decimal from fractions import Fraction _DRIVERS = ("order frequency", "basket size", "product mix", "quantity", "price", "margin") def _number(value): """Refuse missing observations instead of turning them into zero.""" if value is None or isinstance(value, bool): raise ValueError("The invoice observation is incomplete.") value = Decimal(str(value)) if not value.is_finite(): raise ValueError("The invoice observation is not finite.") return Fraction(value) def _money(cents): return format(Decimal(cents) / 100, ".2f") def _group_count(row, first_group): """Accept source count names without inventing a count for an incomplete group.""" count = row.get("__count", row.get(first_group + "_count")) if type(count) is not int or count < 0: raise ValueError("The source group count is unavailable.") return count def _document_group_id(row): """Read the source group identity from its field or exact conjunctive domain.""" identifier = row.get("id") if "id" not in row: # Odoo can omit id even when requested, but returns its equality in __domain. domain = row.get("__domain") if not isinstance(domain, (list, tuple)) or any( term != "&" and not (isinstance(term, (list, tuple)) and len(term) == 3) for term in domain): raise ValueError("The source invoice identity is unavailable.") identities = [term for term in domain if isinstance(term, (list, tuple)) and term[0] == "id"] if len(identities) != 1 or identities[0][1] != "=": raise ValueError("The source invoice identity is unavailable.") identifier = identities[0][2] if type(identifier) is not int or identifier <= 0: raise ValueError("The source invoice identity is unavailable.") return identifier def _period(observation): """Tie every included invoice line to its own untaxed document total.""" documents = {row["id"]: row for row in observation["documents"]} if len(documents) != len(observation["documents"]): raise ValueError("The invoice observation contains duplicate documents.") by_document = {key: [] for key in documents} seen = set() for line in observation["lines"]: if line["id"] in seen or line["move_id"] not in documents: raise ValueError("The invoice line observation is incomplete or duplicated.") seen.add(line["id"]) subtotal = _number(line["price_subtotal"]) # Cost-of-sales journal rows remain in source validation and outside revenue. if line["display_type"] == "cogs": continue if line["display_type"] not in (None, False, "", "product"): if subtotal: raise ValueError("An unsupported invoice line carries an untaxed amount.") continue by_document[line["move_id"]].append(line) groups, total, count = {}, Fraction(0), 0 for identifier, document in documents.items(): untaxed = _number(document["amount_untaxed"]) signed = _number(document["amount_untaxed_signed"]) lines = by_document[identifier] subtotals = [_number(line["price_subtotal"]) for line in lines] if sum(subtotals, Fraction(0)) != untaxed: raise ValueError("Invoice lines do not reconcile to their untaxed document total.") if not untaxed and (signed or any(subtotals)): raise ValueError("A zero-total invoice needs a verified currency conversion.") conversion = signed / untaxed if untaxed else Fraction(1) if conversion <= 0: raise ValueError("The invoice currency conversion is unavailable.") for line, subtotal in zip(lines, subtotals): quantity = _number(line["quantity"]) if quantity and line["product_id"] is not None and line["product_uom_id"] is None: raise ValueError("A product quantity has no observed unit of measure.") # Zero-quantity amounts use charge incidence, never a fabricated unit price. key = (line["product_id"], line["product_uom_id"], "charge" if not quantity else ("positive" if quantity > 0 else "negative")) group = groups.setdefault(key, {"lines": 0, "units": Fraction(0), "revenue": Fraction(0)}) group["lines"] += 1 group["units"] += quantity if quantity else 1 group["revenue"] += subtotal * conversion count += 1 total += signed return {"invoices": len(documents), "lines": count, "groups": groups, "revenue": total} def bridge(previous, current): """Attribute differences between rounded cumulative states without a residual bucket.""" periods = [_period(previous), _period(current)] keys = set(periods[0]["groups"]) | set(periods[1]["groups"]) factors = [] for index, period in enumerate(periods): other = periods[1 - index] basket = (Fraction(period["lines"], period["invoices"]) if period["invoices"] else Fraction(other["lines"], other["invoices"]) if other["invoices"] else Fraction(0)) mix, units, prices = {}, {}, {} for key in keys: group = period["groups"].get(key) donor = group or other["groups"][key] mix[key] = (Fraction(group["lines"] if group else 0, period["lines"]) if period["lines"] else Fraction(donor["lines"], other["lines"])) units[key] = donor["units"] / donor["lines"] prices[key] = donor["revenue"] / donor["units"] factors.append([period["invoices"], basket, mix, units, prices]) def value(state): invoices, basket, mix, units, prices = state return invoices * basket * sum((mix[key] * units[key] * prices[key] for key in keys), Fraction(0)) state = list(factors[0]) cumulative = [round(value(state) * 100)] for index in range(5): state[index] = factors[1][index] cumulative.append(round(value(state) * 100)) totals = [round(period["revenue"] * 100) for period in periods] if cumulative[0] != totals[0] or cumulative[-1] != totals[1]: raise ValueError("The invoice bridge does not reconcile.") changes = [cumulative[index + 1] - cumulative[index] for index in range(5)] + [0] margin = {"available": False, "previous": None, "current": None, "change": None, "reason": "Historical invoice cost is unavailable. Linked order costs require verified " "allocation, currency, date and unit conversion."} drivers = [{"driver": name, "revenue_change_cents": change, "revenue_change": _money(change), "revenue_lost_cents": -change, "revenue_lost": _money(-change)} for name, change in zip(_DRIVERS, changes)] drivers[-1]["diagnostic"] = margin drivers.sort(key=lambda row: -row["revenue_lost_cents"]) return {"status": "no history" if not any(period["invoices"] for period in periods) else "ok", "basis": "invoiced", "history_scope": "requested periods", "previous_revenue": _money(totals[0]), "current_revenue": _money(totals[1]), "revenue_change": _money(totals[1] - totals[0]), "revenue_change_cents": totals[1] - totals[0], "attribution_order": list(_DRIVERS), "drivers": drivers, "margin": margin, "previous_invoice_count": periods[0]["invoices"], "current_invoice_count": periods[1]["invoices"], "method": "Sequential substitution: invoice count, lines per invoice, product, unit and quantity-sign mix, " "units per line, realized company-currency price. Basket size means invoice lines per invoice. " "Each cumulative revenue state rounds half even to cents before differences are taken. " "Missing product-period prices and quantities use the observed other period, so entry and exit " "belong to product mix. An empty period borrows composition from the observed period. " "Zero-quantity lines form separate charge cohorts with one charge per line. Their price " "means amount per charge. Product-less charges remain included. Refunds are separate. " "Margin is a profit diagnostic with zero independent revenue attribution. " "Invoice count measures frequency over the requested windows without normalizing their length."} def validate(observations, *, runtime=None, client=None): """Reconcile pinned mirror documents and line cohorts to independent Odoo read_group results.""" import core.odoo as O if runtime is not None: if client is not None: raise ValueError("An explicit client cannot override the tenant source.") runtime.assert_datastore_matches() source = runtime.odoo_source() if source is None: raise ValueError("The invoice source is unavailable.") binding = source._bound() else: binding = nullcontext() checks = [] pin = observations["pin"] identity = [("partner_id.name", "=", pin["name"])] if pin.get("id") is not None: identity.append(("partner_id", "=", pin["id"])) with binding: reader = client if client is not None else O.get_odoo() base = [("state", "=", "posted"), ("move_type", "=", "out_invoice"), *identity] identities = reader.read_group("account.move", base, ["partner_id"], ["partner_id"], lazy=False) ids = {row["partner_id"][0] if isinstance(row["partner_id"], (tuple, list)) else row["partner_id"] for row in identities if row.get("partner_id")} checks.append({"check": "customer identity stays pinned", "ok": ids == set(observations["history_ids"])}) for observation in observations["periods"]: window = observation["window"] dates = [("invoice_date", ">=", window["date_from"]), ("invoice_date", "<=", window["date_to"])] groups = reader.read_group("account.move", base + dates, ["id", "amount_untaxed_signed:sum", "amount_untaxed:sum"], ["id"], lazy=False, orderby="amount_untaxed_signed") if any(field not in row for row in groups for field in ("amount_untaxed_signed", "amount_untaxed")): raise ValueError("The source invoice total is unavailable.") documents = {row["id"]: row for row in observation["documents"]} live_documents = {_document_group_id(row): row for row in groups} documents_tied = (len(live_documents) == len(groups) and documents.keys() == live_documents.keys() and all(_group_count(row, "id") == 1 and all( round(_number(row[field]) * 100) == round(_number(documents[key][field]) * 100) for field in ("amount_untaxed_signed", "amount_untaxed")) for key, row in live_documents.items())) count = sum(_group_count(row, "id") for row in groups) theirs = sum((_number(row["amount_untaxed_signed"]) for row in groups), Fraction(0)) ours = _period(observation)["revenue"] checks.append({"check": "posted invoice total and count", "window": window, "ours": _money(round(ours * 100)), "independent": _money(round(theirs * 100)), "ok": documents_tied and round(ours * 100) == round(theirs * 100) and count == len(documents)}) line_domain = [("move_id.state", "=", "posted"), ("move_id.move_type", "=", "out_invoice"), ("move_id.partner_id.name", "=", pin["name"]), ("partner_id.name", "=", pin["name"]), ("move_id.invoice_date", ">=", window["date_from"]), ("move_id.invoice_date", "<=", window["date_to"])] if pin.get("id") is not None: line_domain += [("partner_id", "=", pin["id"]), ("move_id.partner_id", "=", pin["id"])] live = [] line_fields = ["move_id", "product_id", "product_uom_id", "display_type"] for sign, comparison in (("positive", ">"), ("negative", "<"), ("charge", "=")): groups = reader.read_group("account.move.line", line_domain + [("quantity", comparison, 0)], [*line_fields, "price_subtotal:sum", "quantity:sum"], line_fields, lazy=False) live.extend((sign, row) for row in groups) def relation(value): return value[0] if isinstance(value, (list, tuple)) else (value or None) expected = {} for row in observation["lines"]: quantity_value = _number(row["quantity"]) sign = "positive" if quantity_value > 0 else "negative" if quantity_value < 0 else "charge" key = (row["move_id"], row["product_id"], row["product_uom_id"], row["display_type"] or None, sign) subtotal, quantity, number = expected.get(key, (Fraction(0), Fraction(0), 0)) expected[key] = (subtotal + _number(row["price_subtotal"]), quantity + _number(row["quantity"]), number + 1) actual = {} for sign, row in live: if any(field not in row for field in (*line_fields, "price_subtotal", "quantity")): raise ValueError("The source invoice line groups are incomplete.") key = tuple(relation(row[field]) for field in line_fields) + (sign,) if key in actual: raise ValueError("The source invoice line groups are incomplete.") actual[key] = (_number(row["price_subtotal"]), _number(row["quantity"]), _group_count(row, "move_id")) tied = actual.keys() == expected.keys() and all( round(actual[key][0] * 100) == round(expected[key][0] * 100) and abs(actual[key][1] - expected[key][1]) <= Fraction(1, 10**9) and actual[key][2] == expected[key][2] for key in expected) checks.append({"check": "posted invoice line cohorts", "window": window, "ok": tied}) return checks def explain_customer(customer, previous_window, window, *, runtime, user, customer_id=None): """Serve a customer bridge only after its mirror observations reconcile independently.""" from harness import semantic observations = semantic.customer_invoice_periods(customer, previous_window, window, customer_id=customer_id, runtime=runtime, user=user) checks = validate(observations, runtime=runtime) if not checks or any(check.get("ok") is not True for check in checks): raise ValueError("The customer invoice observation has not reconciled.") result = bridge(*observations["periods"]) return {**result, "customer_id": observations["pin"].get("id"), "previous_window": previous_window, "window": window, "validation": checks}