File size: 22,826 Bytes
149aa87
 
 
 
 
 
 
 
 
 
 
92127d3
149aa87
 
 
 
23088ad
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
149aa87
 
 
 
23088ad
149aa87
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8510233
 
 
 
 
 
 
 
149aa87
8510233
149aa87
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
82cdb59
 
 
149aa87
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
23088ad
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
149aa87
 
 
 
 
 
 
 
92127d3
 
 
 
 
 
 
149aa87
 
 
92127d3
149aa87
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
aadfd74
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2e7e617
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
149aa87
2e7e617
149aa87
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2e7e617
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
149aa87
 
 
 
 
 
 
 
 
 
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
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
"""Inventory module — working capital tied up, dead stock, stockouts blocking revenue,
ABC, slow movers, turnover.

Valuation: on-hand qty (stock.quant, internal locations) × standard cost. (stock.quant.value
is a non-stored computed field Odoo refuses to aggregate, so standard-cost valuation is used
and is independently cross-checked.) Sales velocity from sale.order.line over LTM (RI+FFS).
"""
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
import pandas as pd
from harness.canonical_source import odoo as O
import core.periods as P


def _cat_main_map():
    """{category id: MAIN category name}, the SECOND segment of Odoo's `complete_name` path.

    THE ROOT MAPS TO `None`, NOT TO ITS OWN NAME (owner instruction 23, wave 40). Odoo roots the
    whole category tree at one node whose `complete_name` is the bare word "All", and the old
    `parts[0]` fallback handed that word out as though it were a category. It is not one: it is
    the tree's root, and a product filed directly on it is UNCATEGORISED. Exactly one of the 74
    categories is single segment, so the root is the only value that could ever reach this branch.

    MEASURED live 2026-08-23: 3,334 of 5,841 coded products (57.1%) sit directly on the root, so
    this is the MAJORITY of the catalogue and not an edge case.

    `None` IS THE CONTRACT, and all three callers already honour it. `inventory._build`,
    `financial._product_cat` and `sales._product_cat` each read this map through
    `... or '(uncategorized)'`, which is the sentinel the product grid's own field description
    already promises: "Product category; '(uncategorized)' when Odoo carries none". So the root's
    products land on the DECLARED blank value instead of on an invented label, and no caller has
    to learn a new convention.
    """
    cats = O.search_read('product.category', [], ['id', 'complete_name'])
    out = {}
    for c in cats:
        parts = [x.strip() for x in (c['complete_name'] or '').split('/')]
        out[c['id']] = parts[1] if len(parts) >= 2 else None
    return out


def _build(t=None):
    """One master frame: product × on-hand × cost × category × LTM sales."""
    t = t or P.today()
    o = O.get_odoo()

    # On-hand qty per product (internal locations only)
    q = o.read_group('stock.quant', [('location_id.usage', '=', 'internal')],
                     ['product_id', 'quantity:sum'], ['product_id'], lazy=False)
    onhand = {O.m2o_id(r['product_id']): (r.get('quantity') or 0.0)
              for r in q if r.get('product_id')}

    # Products (coded). 'type' lets us separate storable goods from services
    # (delivery charges etc. are services — they can't "stock out").
    fields = ['id', 'default_code', 'name', 'categ_id', 'standard_price', 'sale_ok', 'type']
    prods = o.search_read('product.product', [('default_code', '!=', False)], fields)
    catmap = _cat_main_map()

    # ⭐⭐ W39-T10 — LTM sales per product, ALL CHANNELS (line level). Owner instruction 1 of
    # wave 39: *"Metrics under Odoo products MUST include EVERYTHING, not just Royal and Fisch DBA,
    # but also Amazon."* THIS LINE IS WHERE `qty_ltm` COMES FROM — `sku_inventory` groups it by SKU
    # code and `product_data._inventory_by_code` puts it on the product grid, so a wholesale-only
    # read here under-states velocity (and over-states days-of-supply) for every SKU Amazon moves.
    # ⚠ Consolidated by construction: the shelf is one warehouse and carries no team. The BU
    # re-scoping happens downstream in `product_data._rescope_inventory`, against a share whose
    # DENOMINATOR was widened to match this read — see `product_data._bu_ltm_share`.
    lf, lt = P.ltm(t)
    s = o.read_group('sale.order.line', O.sale_line_domain(lf, lt, all_channels=True),  # W39-T10
                     ['product_id', 'price_subtotal:sum', 'product_uom_qty:sum'],
                     ['product_id'], lazy=False)
    rev = {O.m2o_id(r['product_id']): (r.get('price_subtotal') or 0.0) for r in s if r.get('product_id')}
    qty = {O.m2o_id(r['product_id']): (r.get('product_uom_qty') or 0.0) for r in s if r.get('product_id')}

    rows = []
    for p in prods:
        pid = p['id']
        oh = onhand.get(pid, 0.0)
        cost = p.get('standard_price') or 0.0
        rows.append({
            'product_id': pid,
            'sku': str(p['default_code']).strip(),
            'name': p['name'],
            'type': p.get('type') or '',
            'storable': (p.get('type') == 'product'),
            'category': catmap.get(O.m2o_id(p.get('categ_id'))) or '(uncategorized)',
            'cost': cost,
            'on_hand': oh,
            'inv_value': oh * cost,
            'rev_ltm': rev.get(pid, 0.0),
            'qty_ltm': qty.get(pid, 0.0),
        })
    return pd.DataFrame(rows), (lf, lt)


def summary(t=None):
    df, (lf, lt) = _build(t)
    in_stock = df[df['on_hand'] > 0]
    dead = df[(df['inv_value'] >= 1000) & (df['rev_ltm'] < 100)]
    # stockouts only make sense for STORABLE goods (services like delivery never stock)
    stockout = df[(df['storable']) & (df['rev_ltm'] >= 5000) & (df['on_hand'] <= 0)]
    uncosted = in_stock[in_stock['cost'] <= 0]
    return {
        'ltm_window': f'{lf} → {lt}',
        'total_inv_value': float(df['inv_value'].sum()),
        'total_on_hand_units': float(df['on_hand'].sum()),
        'skus_in_stock': int((df['on_hand'] > 0).sum()),
        'dead_skus': int(len(dead)),
        'dead_value': float(dead['inv_value'].sum()),
        'stockout_skus': int(len(stockout)),
        'stockout_rev_ltm': float(stockout['rev_ltm'].sum()),
        'uncosted_in_stock_skus': int(len(uncosted)),
    }


def by_category(t=None):
    df, _ = _build(t)
    g = df.groupby('category').agg(
        inv_value=('inv_value', 'sum'),
        rev_ltm=('rev_ltm', 'sum'),
        skus=('product_id', 'count'),
        in_stock=('on_hand', lambda s: int((s > 0).sum())),
    ).reset_index()
    # crude turnover proxy: LTM revenue / on-hand value (higher = faster)
    g['turnover_x'] = g.apply(lambda r: (r['rev_ltm'] / r['inv_value']) if r['inv_value'] > 0 else None, axis=1)
    return g.sort_values('inv_value', ascending=False).to_dict('records')


def dead_stock(t=None, limit=50):
    df, _ = _build(t)
    d = df[(df['inv_value'] >= 1000) & (df['rev_ltm'] < 100)]
    return d.sort_values('inv_value', ascending=False).head(limit)[
        ['sku', 'name', 'category', 'on_hand', 'cost', 'inv_value', 'rev_ltm']].to_dict('records')


def stockouts(t=None, limit=50):
    df, _ = _build(t)
    s = df[(df['storable']) & (df['rev_ltm'] >= 5000) & (df['on_hand'] <= 0)]
    return s.sort_values('rev_ltm', ascending=False).head(limit)[
        ['sku', 'name', 'category', 'on_hand', 'rev_ltm', 'qty_ltm']].to_dict('records')


def abc(t=None):
    """ABC by LTM revenue contribution. A=top 80%, B=next 15%, C=last 5%."""
    df, _ = _build(t)
    d = df[df['rev_ltm'] > 0].sort_values('rev_ltm', ascending=False).copy()
    total = d['rev_ltm'].sum() or 1.0
    d['cum'] = d['rev_ltm'].cumsum() / total
    def cls(c):
        return 'A' if c <= 0.80 else ('B' if c <= 0.95 else 'C')
    d['abc'] = d['cum'].apply(cls)
    out = d.groupby('abc').agg(skus=('product_id', 'count'),
                               rev_ltm=('rev_ltm', 'sum'),
                               inv_value=('inv_value', 'sum')).reset_index()
    return out.to_dict('records')


# ----------------------------------------------------------- deeper analytics
_CARRY_PCT = 25.0   # default annual carrying cost as a % of inventory value (capital + storage + obsolescence)
_COVERAGE_BUCKETS = [('Critical (<15d)', 0, 15), ('Lean (15 to 45d)', 15, 45),
                     ('Healthy (45 to 120d)', 45, 120), ('Ample (120 to 270d)', 120, 270),
                     ('Overstock (270 to 540d)', 270, 540), ('Excess (>540d)', 540, 1e15)]


def _enrich(df, target_days):
    """Add daily run-rate, days-of-supply, COGS, and excess-vs-target columns."""
    df = df.copy()
    daily = df['qty_ltm'] / 365.0
    df['daily_rate'] = daily
    df['cogs_ltm'] = df['qty_ltm'] * df['cost']

    def _dos(r):
        if r['daily_rate'] > 0:
            return r['on_hand'] / r['daily_rate']
        return float('inf') if r['on_hand'] > 0 else 0.0
    df['dos'] = df.apply(_dos, axis=1)
    df['target_units'] = daily * target_days
    df['excess_units'] = (df['on_hand'] - df['target_units']).clip(lower=0)
    df['excess_value'] = df['excess_units'] * df['cost']
    return df


def analytics(t=None, target_days=180, carry_pct=_CARRY_PCT):
    """Inventory health analytics from ONE build: overstock (excess vs a target days-of-supply), the
    coverage-profile distribution, turnover, average days-of-supply, and the carrying cost of excess."""
    df, (lf, lt) = _build(t)
    df = _enrich(df, target_days)
    instock = df[(df['storable']) & (df['on_hand'] > 0)]
    total_inv = float(df['inv_value'].sum())
    total_cogs = float(df['cogs_ltm'].sum())

    # overstock = sells, but holds materially more than the target coverage
    over = df[(df['storable']) & (df['on_hand'] > 0) & (df['qty_ltm'] > 0)
              & (df['dos'] > target_days) & (df['excess_value'] > 0)]
    over_value = float(over['excess_value'].sum())
    overrows = [{'sku': r['sku'], 'code': r['sku'], 'product': r['name'], 'category': r['category'],
                 'on_hand': float(r['on_hand']),
                 'dos': (None if r['dos'] == float('inf') else round(float(r['dos']), 0)),
                 'excess_units': float(r['excess_units']), 'excess_value': float(r['excess_value']),
                 'carry_cost': float(r['excess_value']) * (carry_pct / 100.0), 'rev_ltm': float(r['rev_ltm'])}
                for _, r in over.sort_values('excess_value', ascending=False).head(80).iterrows()]

    dead = df[(df['inv_value'] >= 1000) & (df['rev_ltm'] < 100)]

    # coverage profile (in-stock storable, by days-of-supply)
    prof = []
    for nm, lo, hi in _COVERAGE_BUCKETS:
        sub = instock[(instock['qty_ltm'] > 0) & (instock['dos'] >= lo) & (instock['dos'] < hi)]
        prof.append({'bucket': nm, 'skus': int(len(sub)), 'inv_value': float(sub['inv_value'].sum()),
                     'units': float(sub['on_hand'].sum())})
    nosale = instock[instock['qty_ltm'] <= 0]
    prof.append({'bucket': 'No recent sales', 'skus': int(len(nosale)),
                 'inv_value': float(nosale['inv_value'].sum()), 'units': float(nosale['on_hand'].sum())})

    healthy_val = sum(p['inv_value'] for p in prof if p['bucket'].startswith(('Healthy', 'Ample')))
    excess_val = sum(p['inv_value'] for p in prof if p['bucket'].startswith(('Overstock', 'Excess', 'No recent')))
    return {
        'window': f'{lf} → {lt}', 'target_days': target_days, 'carry_pct': carry_pct,
        'total_inv_value': total_inv,
        'turnover_x': (total_cogs / total_inv) if total_inv else None,
        'avg_dos': (total_inv / (total_cogs / 365.0)) if total_cogs else None,
        'overstock': overrows, 'overstock_value': over_value, 'overstock_skus': int(len(over)),
        'carrying_cost': over_value * (carry_pct / 100.0),
        'coverage': prof, 'healthy_value': healthy_val, 'excess_value_total': excess_val,
        'dead_value': float(dead['inv_value'].sum()), 'dead_skus': int(len(dead)),
    }


def _bucket(dos_raw, on_hand, qty_ltm):
    """Coverage-bucket label for one SKU from its days-of-supply (matches the coverage profile)."""
    if on_hand <= 0:
        return 'Out of stock'
    if qty_ltm <= 0:
        return 'No recent sales'
    for nm, lo, hi in _COVERAGE_BUCKETS:
        if lo <= dos_raw < hi:
            return nm
    return _COVERAGE_BUCKETS[-1][0]


#: ⭐ AM-4 (2026-08-23), BRANCH (c) — WHAT A SKU WITH NO INVENTORY ROW SAYS FOR ITSELF.
#: `_bucket` never returns this and never can: it is `product_data._dos_with_inbound`'s answer for
#: `on_hand is None`, a case that returns before `_bucket` is reached. It lives here, named, rather
#: than as a literal there, because two places must spell it identically — the product row that
#: carries it, and the permission editor's dropdown, which `routes_admin::
#: _server_side_vocabularies` fills from the list below.
#:
#: ⛔ THE WORDING IS LOAD-BEARING, NOT DECORATION, and AM-4 is explicit about why.
#: `product_data._inventory_by_code` degrades to `{}` on ANY failure, so during an inventory-read
#: outage EVERY product in the catalogue renders this label at once. "Stock not tracked" would
#: then be a catalogue-wide false claim about the warehouse, and "never sold" is false for most of
#: these rows even on a good day. What is genuinely absent in BOTH cases — the ~33 products with
#: no `default_code`, and an outage — is the RECORD, so that is what the label names.
NO_STOCK_RECORD = 'No stock record'

# Every value a `stock_bucket` cell can hold, and the vocabulary the permission editor offers for
# that column (`routes_admin::_server_side_vocabularies` imports this rather than restating it).
# The coverage BANDS run worst→best between the two ends; the last two are not on that axis at all
# — 'No recent sales' is a full shelf nobody is buying from, and `NO_STOCK_RECORD` means there is
# no reading of the shelf to band in the first place.
# ⚠ THE ORDER IS FOR A READER OF THIS FILE, NOT A CONTRACT ANY SURFACE HONOURS. Measured
# 2026-08-24: `routes_admin.py:868` re-sorts every supplied vocabulary alphabetically, and the
# grid's own dropdown (`types.ts::choiceVocabulary`) discovers values from loaded ROWS and sorts
# them too. Same SET on both, never this sequence. Do not add a label here expecting it to land in
# a particular slot on screen.
COVERAGE_LABELS = (['Out of stock'] + [b[0] for b in _COVERAGE_BUCKETS]
                   + ['No recent sales', NO_STOCK_RECORD])


def sku_inventory(target_days=180, carry_pct=_CARRY_PCT, t=None):
    """Per-SKU-code inventory position for the SKU module — keyed by SKU code (variants merged the
    same way the SKU module merges them). CONSOLIDATED: on-hand stock is one physical warehouse, not
    brand-tagged, so this is brand-independent. Returns {code: {name, category, storable, on_hand,
    inv_value, unit_cost, qty_ltm, dos (None=never sells through), bucket, excess_units, excess_value,
    carry_cost, turns, target_units, target_days}}."""
    from harness.canonical_source import active
    if active() is not None:
        g, _ = active().inventory_frame(t or P.today())
    else:
        df, _ = _build(t)
        df = _enrich(df, target_days)
        g = df.groupby('sku').agg(
        name=('name', 'first'), category=('category', 'first'), storable=('storable', 'max'),
        on_hand=('on_hand', 'sum'), inv_value=('inv_value', 'sum'),
        cogs_ltm=('cogs_ltm', 'sum'), qty_ltm=('qty_ltm', 'sum'), rev_ltm=('rev_ltm', 'sum'),
        ).reset_index()
    out = {}
    for r in g.itertuples(index=False):
        daily = r.qty_ltm / 365.0
        dos_raw = (r.on_hand / daily) if daily > 0 else (float('inf') if r.on_hand > 0 else 0.0)
        target_units = daily * target_days
        excess_units = max(r.on_hand - target_units, 0.0)
        # code-level unit cost: on-hand-weighted where in stock, else the LTM COGS unit cost
        unit_cost = (r.inv_value / r.on_hand) if r.on_hand > 0 else (
            (r.cogs_ltm / r.qty_ltm) if r.qty_ltm > 0 else 0.0)
        excess_value = excess_units * unit_cost
        out[r.sku] = {
            'name': r.name, 'category': r.category, 'storable': bool(r.storable),
            'on_hand': float(r.on_hand), 'inv_value': float(r.inv_value),
            'unit_cost': float(unit_cost), 'qty_ltm': float(r.qty_ltm),
            'dos': (None if dos_raw == float('inf') else round(float(dos_raw), 0)),
            'bucket': _bucket(dos_raw, r.on_hand, r.qty_ltm),
            'excess_units': float(excess_units), 'excess_value': float(excess_value),
            'carry_cost': float(excess_value) * (carry_pct / 100.0),
            'turns': (float(r.cogs_ltm) / float(r.inv_value)) if r.inv_value > 0 else None,
            'target_units': float(target_units), 'target_days': target_days,
        }
    return out


def validate_mirror(cur, t=None, codes=None, sample=40):
    """Reconcile the mirror-built `sku_inventory` to a live bounded build; this oracle reads live Odoo.

    Returns `{'checked', 'mismatches': [{sku, column, live, mirror}], 'columns'}` at tolerance 0.01.
    The mirror side reads on_hand from the mirror's internal quants, so a mismatch also names quant drift.
    """
    from harness.canonical_source import MirrorSource, active, bounded, mirrored
    if isinstance(active(), MirrorSource):
        raise RuntimeError('inventory.validate_mirror needs a live oracle; call it outside mirrored()')
    t = t or P.today()
    if codes is None:
        with mirrored(cur):
            whole = sku_inventory(t=t)
        half = max(1, sample // 2)
        by_value = sorted(whole, key=lambda c: (-whole[c]['inv_value'], c))[:half]
        by_units = [c for c in sorted(whole, key=lambda c: (-whole[c]['qty_ltm'], c))
                    if c not in by_value][:sample - len(by_value)]
        codes = by_value + by_units
    codes = [str(c) for c in codes]
    with bounded(cur, 'product', codes):
        live = sku_inventory(t=t)
    with mirrored(cur):
        with bounded(cur, 'product', codes):
            mirror = sku_inventory(t=t)
    columns = sorted({k for side in (live, mirror) for row in side.values() for k in row})
    mismatches = []
    for sku in codes:
        a, b = live.get(sku), mirror.get(sku)
        if a is None or b is None:
            if a is not b:
                mismatches.append({'sku': sku, 'column': '(row)', 'live': a is not None,
                                   'mirror': b is not None})
            continue
        for col in columns:
            x, y = a.get(col), b.get(col)
            numeric = all(isinstance(v, (int, float)) and not isinstance(v, bool) for v in (x, y))
            if (abs(float(x) - float(y)) > 0.01) if numeric else (x != y):
                mismatches.append({'sku': sku, 'column': col, 'live': x, 'mirror': y})
    return {'checked': len(codes), 'mismatches': mismatches, 'columns': columns}


def finance_workflow_contract():
    """Describe inventory work requirements without creating a second fact plane."""
    return [
        {
            'key': 'inventory_value', 'label': 'Inventory value', 'availability': 'unavailable',
            'scope': 'all_channel_inventory',
            'basisLabel': ('Internal-location on-hand quantity multiplied by standard cost at '
                           'product grain.'),
            'missingSource': ('On-hand inventory valuation is not available as a governed Finance '
                              'fact in the tenant mirror.'),
            'sourceModule': 'inventory.summary',
            'validationMethod': 'inventory.validate',
        },
        {
            'key': 'excess_stock', 'label': 'Excess stock', 'availability': 'unavailable',
            'scope': 'all_channel_inventory',
            'basisLabel': ('Physical on-hand compared with a 180-day target using all-channel LTM '
                           'sales velocity.'),
            'missingSource': ('Product-grain excess quantity and value are not available as '
                              'governed Finance facts in the tenant mirror.'),
            'sourceModule': 'inventory.analytics',
            'validationMethod': 'inventory.validate',
        },
        {
            'key': 'dead_stock', 'label': 'Dead stock', 'availability': 'unavailable',
            'scope': 'all_channel_inventory',
            'basisLabel': ('Inventory value of at least $1,000 with less than $100 of all-channel '
                           'LTM revenue at product grain.'),
            'missingSource': ('Product-grain dead-stock value is not available as a governed '
                              'Finance fact in the tenant mirror.'),
            'sourceModule': 'inventory.dead_stock',
            'validationMethod': 'inventory.validate',
        },
    ]


def validate(t=None):
    df, (lf, lt) = _build(t)
    o = O.get_odoo()
    checks = []

    # 1. On-hand units: Σ(per-product) == ungrouped Odoo total
    g = o.read_group('stock.quant', [('location_id.usage', '=', 'internal')],
                     ['quantity:sum'], [], lazy=False)
    odoo_total = (g[0].get('quantity') or 0.0) if g else 0.0
    # our df only covers coded products; compare coded-product on-hand to a coded-only Odoo total
    coded_ids = set(df['product_id'])
    ours = float(df['on_hand'].sum())
    checks.append({
        'check': 'On-hand units (coded SKUs) ≤ Odoo total internal qty',
        'a': round(ours, 0), 'b': round(odoo_total, 0),
        'gap': round(odoo_total - ours, 0),
        'ok': ours <= odoo_total + 1})  # coded ≤ all (uncoded/raw exist)

    # 2. Σ(category inv_value) == total inv_value
    cat_sum = sum(c['inv_value'] for c in by_category(t))
    tot = float(df['inv_value'].sum())
    checks.append({
        'check': 'Inv value: Σ(category) == total',
        'a': round(cat_sum, 2), 'b': round(tot, 2),
        'gap': round(cat_sum - tot, 2),
        'ok': abs(cat_sum - tot) <= 1.0})

    # 3. The velocity feeding coverage/excess/dead-stock is explicitly ALL CHANNELS.  Reconcile
    # the per-product frame against an independent ungrouped live aggregate over the same coded
    # product population so an accidental return to the wholesale-only domain turns this red.
    coded_ids = [int(pid) for pid in df['product_id'].tolist()]
    sales_dom = O.sale_line_domain(lf, lt, all_channels=True)
    if coded_ids:
        sales_dom.append(('product_id', 'in', coded_ids))
    live_units = (O.sum_field('sale.order.line', sales_dom, 'product_uom_qty')
                  if coded_ids and o.search_count('sale.order.line', sales_dom) else 0.0)
    frame_units = float(df['qty_ltm'].sum())
    checks.append({
        'check': 'Inventory LTM units: coded SKU Σ == all-channel line units',
        'a': round(frame_units, 2), 'b': round(live_units, 2),
        'gap': round(frame_units - live_units, 2),
        'ok': abs(frame_units - live_units) <= max(1.0, abs(live_units) * 0.001)})

    # 4. inv_value definition holds for a sampled SKU (qty×cost)
    smp = df[df['on_hand'] > 0].head(1)
    if len(smp):
        r = smp.iloc[0]
        recomputed = r['on_hand'] * r['cost']
        checks.append({
            'check': f"inv_value == on_hand×cost (sample {r['sku']})",
            'a': round(float(r['inv_value']), 2), 'b': round(float(recomputed), 2),
            'gap': round(float(r['inv_value'] - recomputed), 2),
            'ok': abs(r['inv_value'] - recomputed) <= 0.01})
    return checks