# Specification: 022-admin-reporting-refresh

## Status

| Field | Value |
|-------|-------|
| **Created** | 2024-12-30 |
| **Current Phase** | Phase 1 Complete, Phase 2 Ready |
| **Last Updated** | 2024-12-30 |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | 10 features across MoSCoW, all validation checks passed |
| solution-design.md | completed | All 5 ADRs confirmed, validation checklist passed |
| implementation-plan.md | completed | 6 phases, TDD structure, parallel execution enabled |

**Status values**: `pending` | `in_progress` | `completed` | `skipped`

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2024-12-30 | Start with PRD | User chose to formalize requirements from discovery analysis |
| 2024-12-30 | In-app alerts only | Simpler implementation, keeps users engaged in dashboard |
| 2024-12-30 | <2 second load target | Premium experience, requires aggressive pre-aggregation |
| 2024-12-30 | Period comparison enabled | Enable Period A vs Period B for analytical flexibility |
| 2024-12-30 | Data retention: forever | No automatic deletion of analytics data |
| 2024-12-30 | ADR-1: Pre-aggregation | Daily TaskEngine jobs for sub-second queries |
| 2024-12-30 | ADR-2: Store-level first | No category breakdown until POS data fixed |
| 2024-12-30 | ADR-3: Syncfusion EJ2 | Native MACD/stock charts, heat maps, DataGrid for exports (license owned) |
| 2024-12-30 | ADR-4: Central MACD storage | Enable cross-store category comparisons |
| 2024-12-30 | ADR-5: 60s cache TTL | Balance freshness and performance |
| 2024-12-30 | PLAN created | 6 phases with parallel execution after foundation |

## Context

Complete admin reporting refresh based on analysis in `docs/analytics/`:

### Source Analysis Documents

1. **analytics-enhancement-report.md** - Comprehensive discovery report
2. **report-recommendations.md** - Prioritized recommendations
3. **velocity-macd-specification.md** - Detailed MACD implementation spec

### Scope Summary

**Priority 1: Inventory Velocity Reports**
- Days-to-Sale Analysis Dashboard
- Category Momentum Indicators (MACD-Style)
- Pricing Optimization Analysis

**Priority 2: Customer Behavior Reports**
- Seller Retention Analysis
- Wait Time Optimization Report
- NPS & Satisfaction Dashboard

**Priority 3: Financial Performance Reports**
- Return Rate Tracking
- Enhanced P&L Dashboard
- Seasonal Performance Analysis

**Priority 4: Cross-Store Benchmarking**
- Store Comparison Dashboard
- Best Practices Identifier

**Priority 5: Marketing Effectiveness**
- Campaign ROI Dashboard

### Key Technical Components

- New database tables: `analytics_store_velocity`, `analytics_category_velocity`, `analytics_seller_cohorts`
- New service classes in `BuyerKiosk\Analytics\`
- TaskEngine jobs for daily aggregation
- Syncfusion EJ2 Charts and DataGrid visualizations
- API endpoints: `/api/analytics/:typeNum/*`

### Key Findings from Discovery

- Items 180+ days have **55% margin erosion**
- Current avg days-to-sale: 85 days (target: 60-90)
- 13,021 unique sellers with 1.98 avg visits/seller
- Return rates: 0.4-1.8% (well below industry 3% threshold)
- Category/department taxonomy not flowing from POS (limitation)

---
*This file is managed by the specification-management skill.*