@luquimbo/bi-superpowers 3.1.1 → 3.2.0

package/library/examples/retail-analytics/README.md

@@ -1,439 +0,0 @@
-# Retail Analytics - Complete Example
-
-A complete, end-to-end example demonstrating BI Agent Superpowers patterns for a retail analytics solution.
-
----
-
-## Overview
-
-This example shows how to build a professional retail analytics solution using:
-
-- **Star schema data model** with fact and dimension tables
-- **DAX measures** for KPIs, time intelligence, and rankings
-- **Power Query** patterns for data transformation
-- **Power BI theme** for consistent styling
-
----
-
-## Business Requirements
-
-### Stakeholders
-- Store managers: Daily sales performance
-- Regional directors: Cross-store comparisons
-- Finance team: Revenue and margin analysis
-- Operations: Inventory and category insights
-
-### Key Questions
-1. What are our sales trends over time?
-2. Which products and categories drive revenue?
-3. How do stores compare in performance?
-4. What's our margin by product category?
-5. Who are our top customers?
-
----
-
-## Data Model
-
-### Star Schema Design
-
-```
-                    ┌─────────────────┐
-                    │   DimDate       │
-                    │─────────────────│
-                    │ DateKey (PK)    │
-                    │ Date            │
-                    │ Year            │
-                    │ Quarter         │
-                    │ Month           │
-                    │ MonthName       │
-                    │ Week            │
-                    │ DayOfWeek       │
-                    │ IsWeekend       │
-                    └────────┬────────┘
-                             │
-┌─────────────────┐          │          ┌─────────────────┐
-│   DimProduct    │          │          │   DimCustomer   │
-│─────────────────│          │          │─────────────────│
-│ ProductKey (PK) │          │          │ CustomerKey (PK)│
-│ ProductID       │          │          │ CustomerID      │
-│ ProductName     │          │          │ CustomerName    │
-│ Category        │          │          │ Email           │
-│ SubCategory     │          │          │ City            │
-│ Brand           │          │          │ State           │
-│ UnitCost        │          │          │ Region          │
-│ UnitPrice       │          │          │ JoinDate        │
-│ IsActive        │          │          │ Tier            │
-└────────┬────────┘          │          └────────┬────────┘
-         │                   │                   │
-         │     ┌─────────────┴───────────────┐   │
-         │     │        FactSales            │   │
-         │     │─────────────────────────────│   │
-         └────>│ SalesKey (PK)               │<──┘
-               │ DateKey (FK)                │
-               │ ProductKey (FK)             │
-               │ CustomerKey (FK)            │
-               │ StoreKey (FK)               │
-               │ Quantity                    │
-               │ UnitPrice                   │
-               │ Discount                    │
-               │ Amount                      │
-               │ Cost                        │
-               └─────────────┬───────────────┘
-                             │
-                    ┌────────┴────────┐
-                    │   DimStore      │
-                    │─────────────────│
-                    │ StoreKey (PK)   │
-                    │ StoreID         │
-                    │ StoreName       │
-                    │ StoreType       │
-                    │ City            │
-                    │ State           │
-                    │ Region          │
-                    │ OpenDate        │
-                    │ SquareFeet      │
-                    └─────────────────┘
-```
-
-### Table Details
-
-See [data-model.md](./data-model.md) for complete column definitions and data types.
-
----
-
-## Power Query Transformations
-
-### Source Data Preparation
-
-```m
-// FactSales transformation
-let
-    Source = Sql.Database("server", "RetailDB"),
-    Sales = Source{[Schema="dbo", Item="SalesTransactions"]}[Data],
-
-    // 1. Filter to current fiscal year (folds to WHERE)
-    FilteredByDate = Table.SelectRows(Sales, each
-        [TransactionDate] >= #date(2024, 1, 1)
-    ),
-
-    // 2. Select only needed columns (folds to SELECT)
-    SelectedColumns = Table.SelectColumns(FilteredByDate, {
-        "TransactionID", "TransactionDate", "ProductID",
-        "CustomerID", "StoreID", "Quantity", "UnitPrice",
-        "DiscountAmount"
-    }),
-
-    // 3. Add calculated columns
-    WithCalculations = Table.AddColumn(
-        Table.AddColumn(
-            Table.AddColumn(SelectedColumns, "Amount",
-                each [Quantity] * [UnitPrice] - [DiscountAmount], Currency.Type
-            ),
-            "DateKey", each Date.ToText([TransactionDate], "yyyyMMdd"), type text
-        ),
-        "SalesKey", each Text.From([TransactionID]), type text
-    ),
-
-    // 4. Set final types
-    TypedTable = Table.TransformColumnTypes(WithCalculations, {
-        {"Quantity", Int64.Type},
-        {"UnitPrice", Currency.Type},
-        {"DiscountAmount", Currency.Type}
-    })
-in
-    TypedTable
-```
-
-See [power-query.md](./power-query.md) for all table transformations.
-
----
-
-## DAX Measures
-
-### Base Measures
-
-```dax
-// Revenue
-Revenue =
-SUM(FactSales[Amount])
-
-// Cost
-Cost =
-SUMX(
-    FactSales,
-    FactSales[Quantity] * RELATED(DimProduct[UnitCost])
-)
-
-// Profit
-Profit =
-[Revenue] - [Cost]
-
-// Profit Margin
-Profit Margin % =
-DIVIDE([Profit], [Revenue])
-
-// Transaction Count
-Transactions =
-COUNTROWS(FactSales)
-
-// Average Order Value
-AOV =
-DIVIDE([Revenue], [Transactions])
-```
-
-### Time Intelligence
-
-```dax
-// Revenue YTD
-Revenue YTD =
-TOTALYTD([Revenue], DimDate[Date])
-
-// Revenue Prior Year
-Revenue PY =
-CALCULATE([Revenue], SAMEPERIODLASTYEAR(DimDate[Date]))
-
-// Revenue YoY Growth %
-Revenue YoY % =
-VAR _Current = [Revenue]
-VAR _PY = [Revenue PY]
-RETURN
-    DIVIDE(_Current - _PY, _PY)
-
-// Revenue Rolling 3 Months
-Revenue R3M =
-CALCULATE(
-    [Revenue],
-    DATESINPERIOD(DimDate[Date], MAX(DimDate[Date]), -3, MONTH)
-)
-```
-
-### Rankings
-
-```dax
-// Product Rank by Revenue
-Product Rank =
-IF(
-    HASONEVALUE(DimProduct[ProductName]),
-    RANKX(
-        ALL(DimProduct[ProductName]),
-        [Revenue],
-        ,
-        DESC,
-        DENSE
-    )
-)
-
-// Store Rank by Revenue
-Store Rank =
-IF(
-    HASONEVALUE(DimStore[StoreName]),
-    RANKX(
-        ALL(DimStore[StoreName]),
-        [Revenue],
-        ,
-        DESC,
-        DENSE
-    )
-)
-
-// Top 10 Products Revenue
-Revenue Top 10 Products =
-CALCULATE(
-    [Revenue],
-    TOPN(10, ALL(DimProduct[ProductName]), [Revenue], DESC)
-)
-```
-
-### KPI Formatting
-
-```dax
-// Revenue with conditional color
-Revenue Color =
-VAR _YoY = [Revenue YoY %]
-RETURN
-    SWITCH(
-        TRUE(),
-        _YoY >= 0.1, "#166534",   // Dark green - exceeds
-        _YoY >= 0, "#22C55E",      // Green - positive
-        _YoY >= -0.1, "#EAB308",   // Yellow - slightly down
-        "#991B1B"                   // Dark red - significantly down
-    )
-
-// Trend indicator
-Revenue Trend =
-VAR _YoY = [Revenue YoY %]
-RETURN
-    SWITCH(
-        TRUE(),
-        _YoY >= 0.1, "▲▲",
-        _YoY >= 0, "▲",
-        _YoY >= -0.1, "▼",
-        "▼▼"
-    )
-```
-
-See [measures.dax](./measures.dax) for the complete measure library.
-
----
-
-## Visualizations
-
-### Dashboard Layout
-
-```
-┌──────────────────────────────────────────────────────────────────┐
-│  RETAIL ANALYTICS                          [Date Range Slicer]   │
-├──────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐│
-│  │  Revenue    │ │   Profit    │ │  Margin %   │ │    AOV      ││
-│  │  $2.4M      │ │   $480K     │ │   20.1%     │ │   $45.20    ││
-│  │   ▲ 12.3%   │ │   ▲ 8.1%    │ │   ▼ 0.3pp   │ │   ▲ 5.2%    ││
-│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘│
-│                                                                  │
-│  ┌───────────────────────────────┐ ┌───────────────────────────┐│
-│  │   Revenue Trend               │ │   Revenue by Category     ││
-│  │   [Line Chart - R12M]         │ │   [Bar Chart]             ││
-│  │                               │ │                           ││
-│  │                               │ │                           ││
-│  └───────────────────────────────┘ └───────────────────────────┘│
-│                                                                  │
-│  ┌───────────────────────────────┐ ┌───────────────────────────┐│
-│  │   Top 10 Products             │ │   Store Performance       ││
-│  │   [Table with bars]           │ │   [Map or Bar Chart]      ││
-│  │                               │ │                           ││
-│  │                               │ │                           ││
-│  └───────────────────────────────┘ └───────────────────────────┘│
-│                                                                  │
-└──────────────────────────────────────────────────────────────────┘
-```
-
-### Recommended Visuals
-
-| Visual | Measures | Purpose |
-|--------|----------|---------|
-| Card | Revenue, Profit, Margin %, AOV | KPI summary |
-| Line chart | Revenue by Month | Trend analysis |
-| Clustered bar | Revenue by Category | Category comparison |
-| Table | Top Products with Revenue, YoY % | Detailed ranking |
-| Map | Revenue by Region/State | Geographic analysis |
-| Slicer | Date, Category, Region | Filtering |
-
----
-
-## Theme
-
-Use the `bi-superpowers-default.json` theme for this report.
-
-### Key Theme Settings
-
-| Element | Setting |
-|---------|---------|
-| Background | #FAFAFA (page), #FFFFFF (cards) |
-| Primary text | #171717 |
-| Data colors | IBCS grayscale (#000000, #737373, #A3A3A3) |
-| Good | #166534 (dark green) |
-| Bad | #991B1B (dark red) |
-| Border radius | 10px |
-| Font | Segoe UI |
-
-See [theme.json](./theme.json) for the complete theme file.
-
----
-
-## Implementation Checklist
-
-### Data Model
-- [ ] Create DimDate table with all date attributes
-- [ ] Load DimProduct with Category/SubCategory hierarchy
-- [ ] Load DimCustomer with Region hierarchy
-- [ ] Load DimStore with geographic attributes
-- [ ] Load FactSales with surrogate keys
-- [ ] Create relationships (all 1:*)
-- [ ] Mark DimDate as Date Table
-- [ ] Hide foreign key columns
-
-### Measures
-- [ ] Create base measures (Revenue, Cost, Profit)
-- [ ] Create time intelligence measures (YTD, PY, YoY %)
-- [ ] Create ranking measures
-- [ ] Create conditional formatting measures
-- [ ] Organize measures in folders
-
-### Visualizations
-- [ ] Apply theme
-- [ ] Create KPI cards row
-- [ ] Add trend line chart
-- [ ] Add category comparison
-- [ ] Add Top N table
-- [ ] Add geographic visual
-- [ ] Configure slicers
-- [ ] Add tooltips
-- [ ] Test all interactions
-
-### Polish
-- [ ] Add report title
-- [ ] Add last refresh date
-- [ ] Configure mobile layout
-- [ ] Test filter interactions
-- [ ] Optimize performance (DAX Studio)
-- [ ] Document assumptions
-
----
-
-## Files in This Example
-
-| File | Description |
-|------|-------------|
-| [README.md](./README.md) | This overview |
-| [data-model.md](./data-model.md) | Complete table definitions |
-| [power-query.md](./power-query.md) | All M code transformations |
-| [measures.dax](./measures.dax) | Complete DAX measure library |
-| [theme.json](./theme.json) | Power BI theme file |
-
----
-
-## Extending This Example
-
-### Add Customer Segmentation
-
-```dax
-Customer Segment =
-VAR _CustomerRevenue = [Revenue]
-VAR _AvgCustomerRevenue =
-    CALCULATE(
-        AVERAGEX(VALUES(DimCustomer[CustomerKey]), [Revenue]),
-        ALL(DimCustomer)
-    )
-RETURN
-    SWITCH(
-        TRUE(),
-        _CustomerRevenue >= _AvgCustomerRevenue * 2, "VIP",
-        _CustomerRevenue >= _AvgCustomerRevenue, "Regular",
-        "Occasional"
-    )
-```
-
-### Add Inventory Analysis
-
-Create a FactInventory table and add measures like:
-
-```dax
-Stock Days =
-DIVIDE([Current Stock], [Daily Sales Rate])
-
-Reorder Alert =
-IF([Stock Days] < 14, "Reorder", "OK")
-```
-
-### Add Forecast Comparison
-
-If you have budget/forecast data:
-
-```dax
-Revenue vs Budget % =
-DIVIDE([Revenue] - [Budget], [Budget])
-
-Budget Variance =
-[Revenue] - [Budget]
-```