[Parked · Feature] Seller Studio insights (views/likes/sales) & zero-effort promo toolkit #489

Header

• Phase: Parked / On Hold — not V1 urgent. Ships after Pack Issues 1–2 (needs variants + view/like/sale events). Unpark only with CEO + Notes Shop escrow in daily use.
• Must NOT block: Listing create (Issue 1), buyer search/checkout (Issue 2), [Urgent · V1] Unified account + roles + child sub-profiles + hours ledger #459 / #461A, matching fee rails.
• Owner: Locate during impl (Seller Studio dashboard; likely near materials-orders-desk.tsx / account materials section tutor-materials-section.tsx).
• Depends on / related:
  • Pack Issues 1–2 (variants; views/likes/sales/hot_score).
  • #268 D6 seller desk — supersede/extend (comment).
  • Money reporting must align with #203 / #269 / #429 — gross from completed/delivered orders; fee 20% bookkeeping unchanged.
  • Profile pin shelf composes with #415 / existing tutor-materials-section.tsx.
  • Not #474 membership analytics.
• Architecture: Aggregate from existing material_orders + Issue 2 counters. Prefer daily rollup table/JSONB over scanning raw events. Dates in HKT (Asia/Hong_Kong, UTC+8).

Problem

Creators migrating from IG / Xiaohongshu / Carousell / Gumroad need Shopify-like visibility without designing creatives:

1. No store-wide KPI (revenue, units, views, likes, conversion) in HKT windows.
2. No per-variant sales mix (which tier actually sells).
3. High promo friction — no 1-click EN/繁中 blurbs, QR, or pin-to-profile shelf (max 4).
4. Code path: seller desk / account materials — locate during impl.

CEO / product lock

Exact behaviour

Triggers

• Seller opens Seller Studio → Materials & Insights (route locate during impl) or clicks Promote / Share on own listing.

Step-by-step flow

1. Select period: 7d | 30d | all (HKT day boundaries).
2. KPI row: Gross Sales (HK$), Units Sold, Unique Views, Likes/Saves, Conversion % = units / unique_views * 100 (0 if views=0).
3. Expandable listings table: views, likes, sold, revenue; child rows per variant tier mix %.
4. Ranking health tips from missing completeness (previews, 2nd variant, upgrade link) — advisory only; does not write Hot score.
5. Promote modal: storefront URL + UTM, QR download, EN + 繁中 blurb (title, formats, from-price, sold count, link). Toggle Pin to tutor profile (max 4).

Data in / out / side effects

• In: auth seller id, period.
• Out: KPI aggregates + per-listing metrics + variant_sales_breakdown[] + listing_health_tips[].
• Side effects: is_pinned_on_tutor_profile (or equivalent) updates; public tutor profile shows ≤4 pinned material cards.

MUST / MUST NOT

• MUST scope queries to current seller only → tampering another id = 403.
• MUST count only confirmed/completed/delivered orders (exclude cancelled/abandoned) — match # Issue D7 — Order, receipt, and dispute #269/[Feature / Notes Shop] Escrow Hold & Anti-Scam (Seller-Funded Refunds) #429 definitions locate during impl.
• MUST revenue = sum of snapshot price_paid on orders, not current price × historical units.
• MUST use HKT for 7d/30d windows.
• MUST NOT expose another seller’s conversion/revenue.
• MUST NOT include paid boost purchase UI.

UI / look

Dashboard wireframe

+-----------------------------------------------------------------------------------+
| Materials & Course Studio     Period: [7D] [• 30D] [All]   [+ New Material]       |
| KPI: Revenue | Units | Unique Views | Likes | Conv %                              |
| YOUR LISTINGS                                                                     |
| ▼ Speech Video Pack   Views 890  ♥64  Sold 38  Rev HK$14,200  [Promo] [Edit]      |
|    Tier1 10 (26%) | Tier2 22 (58%) | Tier3 6 (16%)                                |
|    [✓ Ranking Health: Strong · Pinned]                                            |
| ▶ Econ Mocks          …                          [Promo]                          |
|    [💡 Tip: Link a Next-Step Upgrade…]                                            |
+-----------------------------------------------------------------------------------+

States

Copy EN + 繁中

Promo blurb templates (must ship both languages):

• EN: {title} — {formats} · from HK${min_price} · {sold} sold on MatchMax. {url}
• 繁中: {title} — {formats} · HK${min_price} 起 · 已售 {sold} · MatchMax {url}

Logic & edge cases

Implementation checklist

• Touch: seller desk UI (locate), orders.functions.ts / orders-desk.functions.ts, tutor-materials-section.tsx, optional pin column on digital_materials.
• Rollup (HKT):

// material_daily_metrics (listing_id, date_hkt date, unique_views, likes_delta, units_sold, revenue_hkd)
// UNIQUE (listing_id, date_hkt); date_hkt = (timestamptz AT TIME ZONE 'Asia/Hong_Kong')::date
// Dashboard 7d/30d = SUM between date_hkt bounds; target <20ms indexed read.
export const MAX_PINNED_MATERIALS = 4;
export const ANALYTICS_TZ = 'Asia/Hong_Kong';

• Justify new material_daily_metrics table vs JSONB rollup column — OK if needed for speed; not a second shop product table.
• Health tips pure functions from listing completeness flags (preview count, variant length, upgrade FK present).

Acceptance criteria

• KPI bar correct for 7D / 30D / All in HKT.
• Expand multi-variant row → per-tier units + revenue %.
• Health tips appear when previews/variants/upgrade missing.
• Promo modal: EN+繁中 copy, link, QR; pin max 4 on public tutor profile.
• Seller A cannot read Seller B analytics (403).
• Revenue ignores cancelled orders; uses paid snapshots.

Out of scope

• Issues 1–2 write paths / ranking formula ownership (consume only).
• Payouts automation beyond existing commission bookkeeping.
• Ad pixels, OAuth social posting, paid boost wallet (Later infra).
• [Parked · Epic] Creator-Monetized Study Vehicles — Gated Vaults · AI Mock Builder · Hybrid Tuition Bridge #474 membership metrics.

Test plan

1. Seller A dashboard baseline KPIs.
2. Incognito buyer: view PDP, like, purchase Tier 2 once (staging cashier).
3. Refresh Seller A: views+1, likes+1, Tier2 units+1, gross + paid amount.
4. Pin listing; open public tutor profile → featured shelf shows card.
5. Attempt 5th pin → blocked. Attempt analytics as Seller B with A’s id → 403.

Open questions

1. Exact Seller Studio route path when unparking?
2. Gross Sales = buyer paid total before or after 20% platform fee display? (Recommendation: show Gross buyer-paid + separate Est. platform fee 20% line — confirm.)
3. Pin shelf on private_notes_only accounts — hide shelf or N/A?