"""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:, asin: or parent:.') 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:, asin: or parent:.') 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