File size: 12,729 Bytes
8133df9
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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
"""Typed project results and daily series with independent source reconciliation."""

from datetime import date, timedelta
import hashlib
import json
import math
import re
import uuid

from core import periods

METRICS = ('sales', 'units', 'returns', 'return_rate', 'refund_rate', 'roas')
GRAINS = ('sku', 'asin', 'parent_asin')
MAX_CONFIGS = 20
BOUNDARY = '[completedOn, endExclusive) in the tenant timezone. Today is excluded.'
SERIES_METRICS = (
    ('sales', 'Sales', 'currency'), ('units', 'Units', 'units'),
    ('margin', 'Margin', 'percent'), ('returns', 'Returns', 'units'),
    ('returns_pct', 'Returns %', 'percent'), ('refunds_pct', 'Refunds %', 'percent'),
    ('roas', 'ROAS', 'ratio'), ('sales_yoy', 'Sales YoY', 'percent'),
)
SERIES_BOUNDARY = 'Inclusive requested dates in the tenant timezone. Today is incomplete and excluded from totals.'


class ValidationFailed(RuntimeError):
    """A daily project series does not reconcile to its independent source aggregate."""


def series_scope(value='all'):
    """Parse the modal filter without allowing it to widen project membership."""
    if value == 'all':
        return None
    if not isinstance(value, str) or ':' not in value:
        raise ValueError('scope must be all, sku:<keys>, asin:<key> or parent:<key>.')
    grain, text = value.split(':', 1)
    keys = [key.strip() for key in text.split(',')]
    if (grain not in ('sku', 'asin', 'parent') or not all(keys)
            or (grain != 'sku' and len(keys) != 1)):
        raise ValueError('scope must be all, sku:<keys>, asin:<key> or parent:<key>.')
    return {'grain': grain, 'keys': list(dict.fromkeys(keys))}


def series_window(project, start=None, end=None, *, today=None):
    """Default to thirty days before start through today and aggregate only completed tenant days."""
    today = today or periods.today()

    def parsed(value):
        if not isinstance(value, str) or not re.fullmatch(r'\d{4}-\d{2}-\d{2}', value):
            raise ValueError('Series dates must use YYYY-MM-DD.')
        return date.fromisoformat(value)

    first = (parsed(start) if start is not None else
             parsed(project.get('start_on') or today.isoformat()) - timedelta(days=30))
    last = parsed(end) if end is not None else today
    if first > last or last > today:
        raise ValueError('Series dates must be ordered and cannot end after today.')
    stop = min(last + timedelta(days=1), today)
    lo, hi, rule = periods.yoy_window(first.isoformat(), stop.isoformat(), 'day')
    return {'from': first.isoformat(), 'to': last.isoformat(), 'days': (stop - first).days,
            'current': (first, stop), 'comparison': (date.fromisoformat(lo), date.fromisoformat(hi)),
            'compare_rule': rule}


def _finite(value):
    return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)


def validate(answer, *, independent):
    """Requery independent totals and return failing checks for any changed or unproved series."""
    checks = []
    first, last = date.fromisoformat(answer['from']), date.fromisoformat(answer['to'])
    dates = [(first + timedelta(days=i)).isoformat() for i in range((last - first).days + 1)]
    expected_keys = [key for key, _label, _unit in SERIES_METRICS]
    metrics = answer['metrics']
    if [metric['key'] for metric in metrics] != expected_keys:
        return [{'check': 'series total ties to economics', 'ok': False,
                 'reason': 'Series metrics do not follow the project result contract.'}]
    for metric in metrics:
        ours = metric.get('total')
        source = independent(metric['key'])
        expected, source_reason = source['value'], source.get('reason')
        points = metric.get('points', [])
        ok = [point.get('date') for point in points] == dates
        if ours is None:
            ok = ok and bool(metric.get('reason')) and all(point.get('value') is None for point in points)
        else:
            ok = (ok and _finite(ours) and _finite(expected)
                  and math.isclose(ours, expected, rel_tol=1e-9, abs_tol=1e-6)
                  and all(point.get('value') is None or _finite(point['value']) for point in points))
            if metric['key'] in ('sales', 'units', 'returns'):
                values = [point['value'] for point in points if point.get('value') is not None]
                ok = ok and bool(values) and math.isclose(math.fsum(values), ours, rel_tol=1e-9, abs_tol=1e-6)
        tie = metric.get('tie', {})
        if tie.get('ok') or tie.get('ours') is not None or tie.get('independent') is not None:
            ok = (ok and ours is not None and tie.get('ok') is True
                  and _finite(tie.get('ours')) and _finite(tie.get('independent'))
                  and math.isclose(tie['ours'], ours, rel_tol=1e-9, abs_tol=1e-6)
                  and _finite(expected)
                  and math.isclose(tie['independent'], expected, rel_tol=1e-9, abs_tol=1e-6))
        checks.append({'check': 'series total ties to economics', 'metric': metric['key'], 'ok': bool(ok),
                       'ours': ours, 'independent': expected,
                       'reason': metric.get('reason') or source_reason})
    return checks


def series(project, *, bounds, read, independent):
    """Publish the fixed chart order and project markers after independent economics reconciliation."""
    first, last = date.fromisoformat(bounds['from']), date.fromisoformat(bounds['to'])
    dates = [(first + timedelta(days=i)).isoformat() for i in range((last - first).days + 1)]
    answer = {'projectId': project['id'], 'from': bounds['from'], 'to': bounds['to'],
              'timezone': timezone_name(), 'boundary': SERIES_BOUNDARY,
              'markers': {'start': project.get('start_on'), 'target': project.get('target_on'),
                          'completed': project.get('completed_on')}, 'metrics': []}
    for key, label, unit in SERIES_METRICS:
        measured = read(key)
        total, reason = measured.get('total'), measured.get('reason')
        if total is None and not reason:
            reason = 'An independent daily source for this metric is unavailable.'
        values = {point['date']: point['value'] for point in measured.get('points', [])} if total is not None else {}
        answer['metrics'].append({'key': key, 'label': label, 'unit': measured.get('unit', unit),
                                  'points': [{'date': day, 'value': values.get(day)} for day in dates],
                                  'total': total, 'reason': reason,
                                  'tie': {'ok': False, 'ours': None, 'independent': None}})
    checks = validate(answer, independent=independent)
    if any(not check['ok'] for check in checks):
        raise ValidationFailed('A series total does not tie to its independent Amazon economics aggregate.')
    for metric, check in zip(answer['metrics'], checks):
        if metric['total'] is not None:
            metric['tie'] = {'ok': True, 'ours': check['ours'], 'independent': check['independent']}
    return answer


def configurations(values):
    """Normalize an ordered list of supported metrics without accepting executable expressions."""
    if not isinstance(values, (list, tuple)) or len(values) > MAX_CONFIGS:
        raise ValueError(f'resultConfigs must be a list of at most {MAX_CONFIGS} configurations.')
    out, seen = [], set()
    for item in values:
        if not isinstance(item, dict) or set(item) - {'id', 'metric', 'grain', 'window', 'days', 'compare'}:
            raise ValueError('Each result configuration must contain only typed result fields.')
        identity = item.get('id', uuid.uuid4().hex)
        if (not isinstance(identity, str) or not re.fullmatch(r'[A-Za-z0-9_-]{1,64}', identity)
                or identity in seen):
            raise ValueError('Result configuration ids must be unique text identifiers.')
        metric, grain = item.get('metric'), item.get('grain', 'sku')
        window, compare = item.get('window', 'fixed'), item.get('compare', 'prior')
        days = item.get('days', 7)
        if metric not in METRICS or grain not in GRAINS:
            raise ValueError('Select a supported Amazon metric and target grain.')
        if window not in ('fixed', 'completion_to_now') or compare not in ('prior', 'yoy'):
            raise ValueError('Select a supported result window and comparison.')
        if type(days) is not int or not 1 <= days <= 366:
            raise ValueError('Result days must be a whole number from 1 to 366.')
        out.append(dict(id=identity, metric=metric, grain=grain, window=window, days=days, compare=compare))
        seen.add(identity)
    return out


def timezone_name():
    """Return the effective tenant business timezone, including the shared UTC fallback."""
    return getattr(periods._business_zone(), 'key', 'UTC')


def windows(project, config, today=None):
    """Anchor equal comparison windows to completion and exclude the tenant's incomplete day."""
    today = today or periods.today()
    base = {'state': 'waiting_for_completion', 'days': 0, 'boundary': BOUNDARY}
    if project.get('status') != 'Completed' or not project.get('completed_on'):
        return base
    start = date.fromisoformat(project['completed_on'])
    if start > today:
        raise ValueError('completedOn cannot be in the future.')
    if start == today:
        return {**base, 'state': 'waiting_for_completed_day'}
    end = today if config['window'] == 'completion_to_now' else start + timedelta(days=config['days'])
    if end > today:
        return {**base, 'state': 'waiting_for_window', 'availableDays': (today - start).days,
                'requestedDays': config['days']}
    days = (end - start).days
    if config['compare'] == 'yoy':
        lo, hi, rule = periods.yoy_window(start.isoformat(), end.isoformat(), 'day')
        prior = (date.fromisoformat(lo), date.fromisoformat(hi))
    else:
        prior, rule = (start - timedelta(days=days), start), None
    return {**base, 'state': 'ready', 'days': days, 'current': (start, end), 'comparison': prior,
            'compare_rule': rule}


def anchor(project, targets, today, zone):
    """Identify the complete completion, configuration, target and tenant-day input set."""
    values = {'status': project['status'], 'completedOn': project.get('completed_on'),
              'configs': project.get('result_configs', []),
              'targets': sorted({(t['grain'], t['key']) for t in targets}),
              'today': today.isoformat(), 'timezone': zone}
    return hashlib.sha256(json.dumps(values, sort_keys=True, separators=(',', ':')).encode()).hexdigest()


def results(project, targets, *, read, metadata, today=None):
    """Publish reconciled figures only after deriving their current completion and target anchor."""
    today, zone = today or periods.today(), timezone_name()
    out = {'projectId': project['id'], 'timezone': zone, 'boundary': BOUNDARY,
           'anchor': anchor(project, targets, today, zone), 'results': []}
    for config in configurations(project.get('result_configs', [])):
        bounds = windows(project, config, today)
        entry = {'config': config, **metadata(config['metric']), 'state': bounds['state'],
                 'current': None, 'comparison': None, 'series': [], 'scope': None,
                 'delta': None, 'deltaPercent': None, 'reason': None,
                 'compare_rule': bounds.get('compare_rule')}
        if bounds['state'] == 'ready':
            figure = read(config, bounds)
            entry.update(figure)
            current, prior = figure.get('current'), figure.get('comparison')
            if current is not None and prior is not None:
                entry['series'] = current.get('series', [])
                states = [current['status'], prior['status']]
                entry['state'] = next((state for state in ('unavailable', 'no_prior_data', 'partial_data')
                                       if state in states), 'ready')
                entry['reason'] = current.get('reason') or prior.get('reason')
                if all(w.get('validated') and w.get('status') == 'available' for w in (current, prior)):
                    a, b = current['value'], prior['value']
                    if a is not None and b is not None and all(math.isfinite(v) for v in (a, b)):
                        change = a - b
                        entry['delta'] = change if math.isfinite(change) else None
                        percent = 100 * change / b if b > 0 else None
                        entry['deltaPercent'] = percent if percent is not None and math.isfinite(percent) else None
        out['results'].append(entry)
    return out