feat(sales): add decoupled 17k commercial sales router, ranking engine, and ingestion pipeline

core/sales_ranking_engine.py

@@ -0,0 +1,51 @@
+"""
+core/sales_ranking_engine.py
+Calculates dedicated commercial sales rank across all records in commercial_sales.
+Completely isolated from 500-cohort telemetry XP ranking logic.
+"""
+
+import sqlite3
+import time
+
+DB_PATH = "data/hiffi_catalog.db"
+
+def recalculate_17k_sales_ranks():
+    conn = sqlite3.connect(DB_PATH)
+    cur = conn.cursor()
+
+    print("[*] Calculating global commercial sales rankings...")
+    start_time = time.time()
+
+    # Join with telemetry_metrics to cleanly break ties for 0-sales artists
+    rank_query = """
+        SELECT 
+            cs.sales_id,
+            cs.artist_id,
+            cs.audited_sales_units,
+            COALESCE(tm.total_views, 0) as total_views,
+            COALESCE(tm.spotify_monthly_listeners, 0) as listeners
+        FROM commercial_sales cs
+        LEFT JOIN telemetry_metrics tm ON cs.artist_id = tm.artist_id
+        ORDER BY 
+            cs.audited_sales_units DESC,
+            total_views DESC,
+            listeners DESC,
+            cs.artist_id ASC
+    """
+    rows = cur.execute(rank_query).fetchall()
+    total = len(rows)
+
+    updates = []
+    for rank, row in enumerate(rows, start=1):
+        sales_id = row[0]
+        updates.append((rank, sales_id))
+
+    cur.executemany("UPDATE commercial_sales SET sales_rank = ? WHERE sales_id = ?", updates)
+    conn.commit()
+    conn.close()
+
+    elapsed = round(time.time() - start_time, 2)
+    print(f"✓ Recalculated sales ranks for {total} artists in {elapsed}s.")
+
+if __name__ == "__main__":
+    recalculate_17k_sales_ranks()