File size: 15,419 Bytes
dec006b
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
"""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}