@luquimbo/bi-superpowers 3.1.1 → 3.2.0

package/library/templates/data-models/finance-model.md

@@ -1,627 +0,0 @@
-# Finance Data Model
-
-## Overview
-
-A comprehensive semantic model for financial reporting, budgeting, and analysis. Designed to support P&L statements, balance sheets, cash flow analysis, and budget variance tracking with proper account hierarchy handling.
-
----
-
-## Business Context
-
-### Key Business Questions
-
-1. **Profit & Loss**
-   - What is revenue, COGS, and net income by period?
-   - How do expenses trend over time?
-   - What is the margin by product line or department?
-
-2. **Budget Analysis**
-   - How do actuals compare to budget?
-   - What are the key variance drivers?
-   - What is the forecast for year-end?
-
-3. **Balance Sheet**
-   - What are current assets and liabilities?
-   - How has working capital changed?
-   - What is the debt-to-equity ratio?
-
-4. **Cash Flow**
-   - What is cash from operations?
-   - How much was invested in CapEx?
-   - What is the cash runway?
-
----
-
-## Schema Diagram
-
-```
-                    ┌─────────────┐
-                    │  DimDate    │
-                    │─────────────│
-                    │ DateKey (PK)│
-                    │ Date        │
-                    │ FiscalYear  │
-                    │ FiscalPeriod│
-                    │ IsActual    │
-                    └──────┬──────┘
-                           │
-                           │ 1:M
-                           │
-┌─────────────┐     ┌──────┴──────┐     ┌─────────────┐
-│ DimAccount  │     │   FactGL    │     │DimScenario  │
-│─────────────│     │─────────────│     │─────────────│
-│AccountKey PK│────>│ GLKey (PK)  │<────│ScenarioKey  │
-│ AccountID   │ M:1 │ DateKey (FK)│ 1:M │ ScenarioID  │
-│ AccountName │     │AccountKey FK│     │ScenarioName │
-│ AccountType │     │ScenarioKey  │     │ ScenarioType│
-│ AccountGroup│     │CostCenterKey│     └─────────────┘
-│ ParentAcct  │     │ EntityKey FK│
-│ L1-L5 Hier  │     │ Debit       │     ┌─────────────┐
-│ IsPL/IsBS   │     │ Credit      │     │DimCostCenter│
-│ SignConv    │     │ Amount      │     │─────────────│
-└─────────────┘     └──────┬──────┘     │CostCenterKey│
-                           │            │CostCenterID │
-          ┌────────────────┘            │ Name        │
-          │                             │ Department  │
-          │ M:1                         │ Division    │
-          ▼                             │ Manager     │
-┌─────────────┐                         └─────────────┘
-│ DimEntity   │
-│─────────────│     ┌─────────────┐
-│EntityKey PK │     │  FactBudget │
-│ EntityID    │     │─────────────│
-│ EntityName  │     │ BudgetKey   │
-│ Currency    │     │ DateKey     │
-│ ParentEntity│     │ AccountKey  │
-│ IsElim      │     │CostCenterKey│
-└─────────────┘     │ ScenarioKey │
-                    │ Amount      │
-                    └─────────────┘
-```
-
----
-
-## Dimension Tables
-
-### DimDate (Financial Calendar)
-
-**Purpose:** Fiscal calendar with period close tracking
-
-| Column | Data Type | Description | Sample Values |
-|--------|-----------|-------------|---------------|
-| DateKey | INT | Surrogate key (YYYYMMDD) | 20240115 |
-| Date | DATE | Full date | 2024-01-15 |
-| CalendarYear | INT | Calendar year | 2024 |
-| CalendarMonth | INT | Calendar month | 1 |
-| CalendarQuarter | INT | Calendar quarter | 1 |
-| FiscalYear | INT | Fiscal year | 2024 |
-| FiscalPeriod | INT | Fiscal period (1-12 or 1-13) | 7 |
-| FiscalQuarter | INT | Fiscal quarter | 3 |
-| FiscalYearMonth | VARCHAR(10) | FY-Period label | FY24-P07 |
-| PeriodStartDate | DATE | First day of period | 2024-01-01 |
-| PeriodEndDate | DATE | Last day of period | 2024-01-31 |
-| IsActualPeriod | BIT | Has actual data | 1 |
-| IsClosed | BIT | Period is closed | 1 |
-| DaysInPeriod | INT | Days in fiscal period | 31 |
-| IsYearEnd | BIT | Year-end period | 0 |
-
-### DimAccount (Chart of Accounts)
-
-**Purpose:** Account hierarchy with financial statement mapping
-
-| Column | Data Type | Description | Sample Values |
-|--------|-----------|-------------|---------------|
-| AccountKey | INT | Surrogate key | 1001 |
-| AccountID | VARCHAR(20) | GL account number | 4010 |
-| AccountName | VARCHAR(100) | Account name | Product Revenue |
-| AccountDescription | VARCHAR(500) | Full description | Revenue from product sales |
-| AccountType | VARCHAR(30) | High-level type | Revenue |
-| AccountGroup | VARCHAR(50) | Grouping | Operating Revenue |
-| AccountClass | VARCHAR(30) | Class | Income Statement |
-| StatementLine | VARCHAR(50) | Financial statement line | Net Revenue |
-| L1_Category | VARCHAR(50) | Hierarchy Level 1 | Income Statement |
-| L2_Category | VARCHAR(50) | Hierarchy Level 2 | Revenue |
-| L3_Category | VARCHAR(50) | Hierarchy Level 3 | Operating Revenue |
-| L4_Category | VARCHAR(50) | Hierarchy Level 4 | Product Revenue |
-| L5_Account | VARCHAR(100) | Hierarchy Level 5 (Detail) | Product Revenue - Domestic |
-| ParentAccountKey | INT | Parent in hierarchy | 1000 |
-| IsBS | BIT | Balance Sheet account | 0 |
-| IsPL | BIT | P&L account | 1 |
-| IsCF | BIT | Cash Flow relevant | 0 |
-| NormalBalance | VARCHAR(10) | Debit or Credit | Credit |
-| SignConvention | INT | Sign for reporting (+1/-1) | -1 |
-| SortOrder | INT | Display order | 100 |
-| IsActive | BIT | Active account | 1 |
-| IsPostable | BIT | Can receive postings | 1 |
-
-**Account Types:**
-```
-Balance Sheet (IsBS = 1):
-  - Asset
-  - Liability
-  - Equity
-
-Income Statement (IsPL = 1):
-  - Revenue
-  - COGS
-  - Operating Expense
-  - Other Income/Expense
-  - Tax
-```
-
-**Sign Convention:**
-```
-Revenue accounts: SignConvention = -1
-  (Credit balance shows as positive)
-
-Expense accounts: SignConvention = 1
-  (Debit balance shows as positive)
-
-Asset accounts: SignConvention = 1
-  (Debit balance shows as positive)
-
-Liability/Equity: SignConvention = -1
-  (Credit balance shows as positive)
-```
-
-### DimScenario (Scenario Dimension)
-
-**Purpose:** Actual, Budget, Forecast versions
-
-| Column | Data Type | Description | Sample Values |
-|--------|-----------|-------------|---------------|
-| ScenarioKey | INT | Surrogate key | 1 |
-| ScenarioID | VARCHAR(20) | Scenario code | ACT |
-| ScenarioName | VARCHAR(50) | Display name | Actual |
-| ScenarioType | VARCHAR(30) | Type classification | Actual |
-| IsActual | BIT | Actual data flag | 1 |
-| IsBudget | BIT | Budget version flag | 0 |
-| IsForecast | BIT | Forecast version flag | 0 |
-| FiscalYear | INT | Applicable year | 2024 |
-| Version | VARCHAR(20) | Version number | v1.0 |
-| ApprovedDate | DATE | Approval date | 2023-12-15 |
-| IsActive | BIT | Current/active | 1 |
-
-**Common Scenarios:**
-```
-1. Actual (ACT) - Recorded transactions
-2. Budget (BUD) - Annual approved budget
-3. Forecast (FC1, FC2, FC3) - Quarterly reforecasts
-4. Prior Year (PY) - Last year actuals
-5. Plan (PLN) - Long-term plan
-```
-
-### DimCostCenter (Cost Center Dimension)
-
-**Purpose:** Organizational hierarchy for expenses
-
-| Column | Data Type | Description | Sample Values |
-|--------|-----------|-------------|---------------|
-| CostCenterKey | INT | Surrogate key | 501 |
-| CostCenterID | VARCHAR(20) | Cost center code | CC-100 |
-| CostCenterName | VARCHAR(100) | Name | Engineering |
-| Department | VARCHAR(50) | Department | Technology |
-| Division | VARCHAR(50) | Division | Product |
-| BusinessUnit | VARCHAR(50) | Business unit | Software |
-| ManagerName | VARCHAR(100) | Responsible manager | John Smith |
-| ManagerEmail | VARCHAR(100) | Manager email | john.smith@company.com |
-| ParentCostCenterKey | INT | Parent in hierarchy | 500 |
-| L1_Division | VARCHAR(50) | Hierarchy Level 1 | Product |
-| L2_Department | VARCHAR(50) | Hierarchy Level 2 | Technology |
-| L3_CostCenter | VARCHAR(50) | Hierarchy Level 3 | Engineering |
-| IsActive | BIT | Active cost center | 1 |
-
-### DimEntity (Legal Entity Dimension)
-
-**Purpose:** Multi-company consolidation
-
-| Column | Data Type | Description | Sample Values |
-|--------|-----------|-------------|---------------|
-| EntityKey | INT | Surrogate key | 1 |
-| EntityID | VARCHAR(20) | Entity code | US01 |
-| EntityName | VARCHAR(100) | Legal name | Company USA Inc. |
-| ShortName | VARCHAR(50) | Short name | USA |
-| Currency | VARCHAR(3) | Local currency | USD |
-| Country | VARCHAR(50) | Country | United States |
-| Region | VARCHAR(30) | Region | Americas |
-| EntityType | VARCHAR(30) | Type | Operating |
-| ParentEntityKey | INT | Parent entity | NULL |
-| ConsolidationPct | DECIMAL(5,2) | Ownership % | 100.00 |
-| IsElimination | BIT | Elimination entity | 0 |
-| IsConsolidated | BIT | Include in consolidation | 1 |
-| IsActive | BIT | Active entity | 1 |
-
----
-
-## Fact Tables
-
-### FactGL (General Ledger)
-
-**Purpose:** Journal entry level detail
-
-| Column | Data Type | Description | Grain |
-|--------|-----------|-------------|-------|
-| GLKey | BIGINT | Surrogate key | One row per journal line |
-| DateKey | INT | Transaction date (FK) | |
-| AccountKey | INT | GL Account (FK) | |
-| ScenarioKey | INT | Scenario (FK) | |
-| CostCenterKey | INT | Cost Center (FK) | |
-| EntityKey | INT | Legal Entity (FK) | |
-| JournalID | VARCHAR(30) | Journal entry ID | |
-| LineNumber | INT | Line in journal | |
-| Debit | DECIMAL(18,2) | Debit amount | |
-| Credit | DECIMAL(18,2) | Credit amount | |
-| Amount | DECIMAL(18,2) | Net amount (Debit - Credit) | |
-| LocalAmount | DECIMAL(18,2) | Amount in local currency | |
-| FXRate | DECIMAL(12,6) | Exchange rate | |
-| Description | VARCHAR(500) | Transaction description | |
-| Reference | VARCHAR(50) | External reference | |
-| PostedBy | VARCHAR(50) | User who posted | |
-| PostedDate | DATETIME | Posting timestamp | |
-
-### FactBudget (Budget/Forecast)
-
-**Purpose:** Budget and forecast data at summary level
-
-| Column | Data Type | Description | Grain |
-|--------|-----------|-------------|-------|
-| BudgetKey | BIGINT | Surrogate key | One row per account/CC/period |
-| DateKey | INT | Period start date (FK) | |
-| AccountKey | INT | GL Account (FK) | |
-| ScenarioKey | INT | Scenario (FK) | |
-| CostCenterKey | INT | Cost Center (FK) | |
-| EntityKey | INT | Legal Entity (FK) | |
-| Amount | DECIMAL(18,2) | Budget amount | |
-| Units | INT | Budget units (optional) | |
-| Notes | VARCHAR(500) | Budget assumptions | |
-| VersionDate | DATE | Version date | |
-
-### FactBalance (Balance Sheet Snapshots - Optional)
-
-**Purpose:** Period-end balances for BS accounts
-
-| Column | Data Type | Description | Grain |
-|--------|-----------|-------------|-------|
-| BalanceKey | BIGINT | Surrogate key | One row per account/entity/period |
-| DateKey | INT | Period end date (FK) | |
-| AccountKey | INT | GL Account (FK) | |
-| EntityKey | INT | Legal Entity (FK) | |
-| ScenarioKey | INT | Scenario (FK) | |
-| BeginningBalance | DECIMAL(18,2) | Opening balance | |
-| Activity | DECIMAL(18,2) | Period activity | |
-| EndingBalance | DECIMAL(18,2) | Closing balance | |
-
----
-
-## Recommended DAX Measures
-
-### Core Financial Measures
-
-```dax
-// Amount with Sign Convention
-Amount =
-SUMX(
-    FactGL,
-    FactGL[Amount] * RELATED(DimAccount[SignConvention])
-)
-
-// Or simpler if Amount already signed correctly
-Total Amount =
-SUM(FactGL[Amount])
-
-// Revenue
-Revenue =
-CALCULATE(
-    [Amount],
-    DimAccount[AccountType] = "Revenue"
-)
-
-// COGS
-COGS =
-CALCULATE(
-    [Amount],
-    DimAccount[AccountType] = "COGS"
-)
-
-// Gross Profit
-Gross Profit =
-[Revenue] - [COGS]
-
-// Gross Margin %
-Gross Margin % =
-DIVIDE([Gross Profit], [Revenue])
-
-// Operating Expenses
-Operating Expenses =
-CALCULATE(
-    [Amount],
-    DimAccount[AccountType] = "Operating Expense"
-)
-
-// EBITDA
-EBITDA =
-[Gross Profit] - [Operating Expenses] + [Depreciation & Amortization]
-
-// Net Income
-Net Income =
-CALCULATE(
-    [Amount],
-    DimAccount[IsPL] = TRUE
-)
-```
-
-### Budget Variance
-
-```dax
-// Budget Amount
-Budget Amount =
-CALCULATE(
-    [Amount],
-    DimScenario[ScenarioName] = "Budget"
-)
-
-// Actual Amount
-Actual Amount =
-CALCULATE(
-    [Amount],
-    DimScenario[ScenarioName] = "Actual"
-)
-
-// Variance
-Variance $ =
-[Actual Amount] - [Budget Amount]
-
-// Variance % (context-aware)
-Variance % =
-VAR _Actual = [Actual Amount]
-VAR _Budget = [Budget Amount]
-VAR _AccountType = SELECTEDVALUE(DimAccount[AccountType])
-VAR _IsExpense = _AccountType IN {"COGS", "Operating Expense", "Other Expense"}
-RETURN
-IF(
-    _IsExpense,
-    DIVIDE(_Budget - _Actual, ABS(_Budget)),  // Under budget is positive
-    DIVIDE(_Actual - _Budget, ABS(_Budget))   // Over revenue is positive
-)
-
-// Variance Status
-Variance Status =
-VAR _Var = [Variance %]
-RETURN
-SWITCH(
-    TRUE(),
-    _Var >= 0, "Favorable",
-    _Var >= -0.05, "On Track",
-    _Var >= -0.10, "At Risk",
-    "Unfavorable"
-)
-```
-
-### Period Intelligence
-
-```dax
-// YTD Amount
-YTD Amount =
-TOTALYTD(
-    [Amount],
-    DimDate[Date],
-    "6/30"  // Fiscal year end if not Dec 31
-)
-
-// Prior Year
-Prior Year =
-CALCULATE(
-    [Amount],
-    SAMEPERIODLASTYEAR(DimDate[Date])
-)
-
-// YoY Change
-YoY Change =
-[Amount] - [Prior Year]
-
-// YoY %
-YoY % =
-DIVIDE([YoY Change], ABS([Prior Year]))
-
-// MTD
-MTD Amount =
-TOTALMTD([Amount], DimDate[Date])
-
-// Full Year Run Rate
-Full Year Run Rate =
-VAR _YTD = [YTD Amount]
-VAR _MonthsElapsed = DISTINCTCOUNT(DimDate[FiscalPeriod])
-RETURN
-DIVIDE(_YTD * 12, _MonthsElapsed)
-```
-
-### Balance Sheet Measures
-
-```dax
-// Ending Balance (cumulative for BS)
-Ending Balance =
-CALCULATE(
-    [Amount],
-    FILTER(
-        ALL(DimDate),
-        DimDate[Date] <= MAX(DimDate[Date])
-    ),
-    DimAccount[IsBS] = TRUE
-)
-
-// Current Assets
-Current Assets =
-CALCULATE(
-    [Ending Balance],
-    DimAccount[AccountGroup] = "Current Assets"
-)
-
-// Current Liabilities
-Current Liabilities =
-CALCULATE(
-    [Ending Balance],
-    DimAccount[AccountGroup] = "Current Liabilities"
-)
-
-// Working Capital
-Working Capital =
-[Current Assets] + [Current Liabilities]  // Liabilities are negative
-
-// Current Ratio
-Current Ratio =
-DIVIDE([Current Assets], ABS([Current Liabilities]))
-```
-
-### Financial Ratios
-
-```dax
-// Operating Margin
-Operating Margin =
-DIVIDE([EBITDA], [Revenue])
-
-// Return on Assets
-ROA =
-DIVIDE(
-    [Net Income],
-    CALCULATE([Ending Balance], DimAccount[AccountType] = "Asset")
-)
-
-// Debt to Equity
-Debt to Equity =
-DIVIDE(
-    CALCULATE([Ending Balance], DimAccount[AccountType] = "Liability"),
-    CALCULATE([Ending Balance], DimAccount[AccountType] = "Equity")
-)
-```
-
----
-
-## P&L Structure
-
-### Standard P&L Order
-
-```
-Revenue
-  Product Revenue
-  Service Revenue
-  Other Revenue
-─────────────────────
-Total Revenue
-
-Cost of Goods Sold
-  Direct Materials
-  Direct Labor
-  Manufacturing Overhead
-─────────────────────
-Total COGS
-
-GROSS PROFIT
-
-Operating Expenses
-  Sales & Marketing
-    Salaries - Sales
-    Advertising
-    Travel - Sales
-  Research & Development
-    Salaries - R&D
-    Software & Tools
-  General & Administrative
-    Executive Salaries
-    Legal & Professional
-    Rent & Facilities
-    Insurance
-    Depreciation
-─────────────────────
-Total Operating Expenses
-
-OPERATING INCOME (EBIT)
-
-Other Income/Expense
-  Interest Income
-  Interest Expense
-  FX Gains/Losses
-  Other
-─────────────────────
-Total Other
-
-INCOME BEFORE TAX
-
-Income Tax Expense
-─────────────────────
-NET INCOME
-```
-
-### DAX for P&L Matrix
-
-```dax
-// Sort Order for P&L display
-P&L Sort =
-SELECTEDVALUE(DimAccount[SortOrder])
-
-// P&L Amount with proper aggregation
-P&L Amount =
-IF(
-    HASONEVALUE(DimAccount[L5_Account]),
-    [Amount],
-    SUMX(
-        SUMMARIZE(DimAccount, DimAccount[L5_Account]),
-        [Amount]
-    )
-)
-```
-
----
-
-## Security Considerations
-
-### Row-Level Security
-
-```dax
-// Cost Center RLS
-[CostCenterAccess] =
-VAR _UserEmail = USERPRINCIPALNAME()
-VAR _UserCCs =
-    CALCULATETABLE(
-        VALUES(SecurityCostCenter[CostCenterKey]),
-        SecurityCostCenter[UserEmail] = _UserEmail
-    )
-RETURN
-DimCostCenter[CostCenterKey] IN _UserCCs
-
-// Entity RLS
-[EntityAccess] =
-VAR _UserEmail = USERPRINCIPALNAME()
-VAR _UserEntities =
-    CALCULATETABLE(
-        VALUES(SecurityEntity[EntityKey]),
-        SecurityEntity[UserEmail] = _UserEmail
-    )
-RETURN
-DimEntity[EntityKey] IN _UserEntities
-```
-
----
-
-## Implementation Checklist
-
-- [ ] Define fiscal calendar (year-end, periods)
-- [ ] Map Chart of Accounts with hierarchy levels
-- [ ] Set sign convention for each account type
-- [ ] Create scenario dimension with all versions
-- [ ] Build cost center hierarchy
-- [ ] Configure entity structure for consolidation
-- [ ] Load historical GL data
-- [ ] Import budget versions
-- [ ] Create core financial measures
-- [ ] Build variance calculations
-- [ ] Configure RLS for cost center/entity access
-- [ ] Test P&L, BS, and variance reports
-- [ ] Document calculation methodology
-
----
-
-## Related Resources
-
-- [Finance Report Template](../power-bi/finance-report.md)
-- [DAX Patterns](../../snippets/dax/)
-- [Data Modeling Best Practices](../../skills/data-modeling/SKILL.md)