feat(dashboard): supporting schema, seed, catalog links, funnel/PM labels and API contract (merge resolution)

backend/app/db/init_db.py

@@ -384,11 +384,12 @@ async def ensure_v26(engine: AsyncEngine) -> None:
             "ON CONFLICT (from_unit, to_unit) DO NOTHING",
             c,
         )
-    # v2.5/v2.6 category decoupling from materials: drop trigger, function, and column.
+    # v2.5/v2.6 category decoupling from materials: drop the old supplier-derived
+    # trigger/function. The `materials.category_id` COLUMN is NOT dropped here
+    # anymore — v2.8 re-introduces it (topic-backfilled) for the dashboard's
+    # Category→Material filter cascade (see ensure_dashboard_schema below).
     await run_statement("DROP TRIGGER IF EXISTS trg_supplier_materials_derive_category ON supplier_materials")
     await run_statement("DROP FUNCTION IF EXISTS fn_derive_material_category()")
-    await run_statement("ALTER TABLE materials DROP CONSTRAINT IF EXISTS materials_category_id_fkey")
-    await run_statement("ALTER TABLE materials DROP COLUMN IF EXISTS category_id")
 
     await run_statement("DROP TRIGGER IF EXISTS trg_item_decisions_sync_price ON item_decisions")
     await run_statement("""
@@ -558,3 +559,70 @@ async def ensure_project_transfers_table(engine: AsyncEngine) -> None:
             await conn.execute(text(stmt))
     logger.info("project_transfers table ensured")
 
+# ---------------------------------------------------------------------------
+# v2.8 — MVP dashboard schema: materials.category_id + reporting indexes
+# The dashboard's «What» filter cascade (Category → Material → Brand → Specs)
+# needs a real materials.category_id link. v2.6 had deliberately dropped the
+# old supplier-derived column; this is a fresh, topic-backfilled link
+# (nullable — a material may stay uncategorized). The rest is B-tree index
+# coverage for the aggregation queries in services/dashboard_service.py.
+# Runs AFTER ensure_v26 so the 8 fixed categories always exist for the
+# backfill. Every statement is idempotent.
+# ---------------------------------------------------------------------------
+
+_DASHBOARD_SCHEMA_DDL = [
+    # Fresh column (inline FK names the constraint materials_category_id_fkey,
+    # matching the DO-block guard below for volumes that predate v2.8).
+    """
+    ALTER TABLE materials ADD COLUMN IF NOT EXISTS category_id UUID REFERENCES material_categories(id) ON DELETE SET NULL
+    """,
+    # Backfill from the legacy Persian topic text (NULL stays NULL — the UI
+    # groups those under «بدون دسته»).
+    """
+    UPDATE materials SET category_id = mc.id
+    FROM material_categories mc
+    WHERE materials.topic = mc.name AND materials.category_id IS NULL
+    """,
+    # FK for the (rare) volume that already had the column without it.
+    """
+    DO $$ BEGIN
+        ALTER TABLE materials ADD CONSTRAINT materials_category_id_fkey
+            FOREIGN KEY (category_id) REFERENCES material_categories(id) ON DELETE SET NULL;
+    EXCEPTION WHEN duplicate_object THEN NULL; END $$
+    """,
+    "CREATE INDEX IF NOT EXISTS idx_materials_category ON materials(category_id)",
+    # Drill-down / PM scoping: every dashboard query filters through it.
+    "CREATE INDEX IF NOT EXISTS idx_warehouses_project ON warehouses(project_id)",
+    # Daily flow + daily control (date-range aggregation).
+    "CREATE INDEX IF NOT EXISTS idx_inventory_tx_date ON inventory_transactions(transaction_date)",
+    # Type slices (withdrawal / return / waste) inside a date range.
+    "CREATE INDEX IF NOT EXISTS idx_inventory_tx_type_date ON inventory_transactions(transaction_type, transaction_date)",
+    # Funnel cumulative counts + lead-time average (partial — tiny & hot).
+    "CREATE INDEX IF NOT EXISTS idx_quotes_accepted ON quotes(accepted_date) WHERE accepted_date IS NOT NULL",
+    "CREATE INDEX IF NOT EXISTS idx_quotes_arrived ON quotes(arrived_date) WHERE arrived_date IS NOT NULL",
+    # Funnel per-status counts (existing composite leads with supplier_id).
+    "CREATE INDEX IF NOT EXISTS idx_quotes_status ON quotes(status)",
+    # Project-density workload grouping.
+    "CREATE INDEX IF NOT EXISTS idx_item_decisions_project ON item_decisions(project_id)",
+    # Receipt-level arrival reporting.
+    "CREATE INDEX IF NOT EXISTS idx_item_receipts_received ON item_receipts(received_at)",
+    # «What»-filtered stock scans across warehouses (existing composites lead
+    # with warehouse_id, useless for a bare material/brand filter).
+    "CREATE INDEX IF NOT EXISTS idx_inventory_material_brand ON inventory(material_id, brand_id)",
+]
+
+
+async def ensure_dashboard_schema(engine: AsyncEngine) -> None:
+    """v2.8: materials.category_id (+ backfill) + dashboard reporting indexes.
+
+    Statement-per-transaction like ensure_v26: one failure can never block
+    the rest of the upgrade. Safe to call on every startup.
+    """
+    for ddl in _DASHBOARD_SCHEMA_DDL:
+        try:
+            async with engine.begin() as conn:
+                await conn.execute(text(ddl))
+        except Exception:  # pragma: no cover - pre-existing data conflicts
+            first_line = ddl.splitlines()[0][:100] if ddl.splitlines() else ddl[:100]
+            logger.exception("dashboard schema statement skipped (continuing): %s", first_line)
+    logger.info("dashboard schema ensured (materials.category_id + reporting indexes)")