Merchant Live Data Rollout Plan (+ Decision Log continuation)

Date: 2026-07-25 Status: Live tracker + decision log (continues D-numbering from 2026-07-25-push-notifications.md) Spec: ../specs/2026-07-25-merchant-live-data-design.mdBranch: feat/merchant-dashboard-live-data (heavy-hitters worktree, off origin/dev)

1. Phases

Phase	Delivers	Depends on
M1: Client wrappers	Admin getMerchantDashboardMetrics() + web merchantMetricsService.js for GET /analytics/merchant/dashboard (soft-fail pattern)	nothing
M2: Admin Overview live	Remove SAMPLE + buildSampleActivity(); wire venues/lanterns/waves/uniques + offer counts + recent offers; drop wave-accept-rate stat; honest empty states	M1
M3: Web honesty pass	Delete mockVenues, dev picker, fakeAds + creator; owned-venues section w/ activeLanternCount; fix dead #/merchant/new link; honest StatCard period label	M1
M4: Applications persist	merchants-api POST /merchants/apply + merchant_applications rules (server-only) + MerchantSignup wiring + openapi.json sync	nothing
M5: Verification	test-plan skill doc; unit tests per surface; rules tests for the new collection; live browser pass with test accounts; validate + /code-review + draft PR	M1-M4

2. Live status

• [x] Consolidation (rule 13): governing docs 2026-07-22 ad-network plan + 2026-07-24 claim/redeem; #178 partial overlap (applications), #320/#167 explicitly future; no competing PRs
• [x] Spec written
• [x] M1 wrappers (getMerchantDashboardMetrics admin + fetchMerchantVenueMetrics web)
• [x] M2 admin Overview live (SAMPLE + synthetic chart gone; 343/343 admin tests)
• [x] M3 web honesty pass (mock venues / dev picker / fakeAds deleted; owned-venues section; 8/8 screen tests)
• [x] M4 applications persist (POST /merchants/apply, server-only collection + rules test, signup wired; 4 route + 3 client tests; openapi sync green)
• [ ] M5 verification + PR (test plan below; full validate; /code-review gate; draft PR)

Decision log additions

#	Decision	Rationale
D25	Admin activity chart plots the real per-day verified-impressions series from the delivery rollup (7d/30d) instead of a fabricated lantern series	No per-day lantern source exists server-side; the honest options were a real ad-views chart or no chart. Lantern/wave period totals live in the stat cards from the dashboard endpoint.
D26	Web dashboard is a read-only viewer: the dead #/merchant/new link was removed, not replaced with a cross-app deep link	Offer CRUD is canonical in the admin portal; a per-env portal URL deep link adds a break-prone seam for no pilot value.
D27	/merchants/apply is public (App Check + IP rate limit), not token-gated; dedup by SHA-256 of normalized email; reviewed applications never reopen and resubmits leak nothing	Applicants are venue owners, not app users; email-keyed idempotency kills duplicate spam without enumerable state.
D28	(operator, 2026-07-26) The web #/merchant dashboard is REMOVED entirely: screen, route, ProfileSettings card, dev merchant-role spoof, delivery service client, and App.jsx merchant-role resolution. Supersedes D26 and the M3 honesty pass. The web app keeps only #/merchant/signup (the public application funnel).	The portal is canonical in the admin MerchantShell; a second half-portal in the web app confused every agent and human who touched it.

3. Decision log (continued)

#	Decision	Rationale
D19	New theme branches are created fresh from origin/dev inside the dedicated worktree (operator standing approval 2026-07-25); carried docs ride the next theme's first commit	Squash-merges orphan the old branch history; a stale branch cannot host a clean follow-up PR.
D20	Theme scope = admin MerchantShell Overview first (canonical surface), web dashboard gets an honesty pass, signup gets real persistence	Operator declared admin canonical (2026-07-22 plan); its Overview is the most-fabricated surface a real venue owner would see.
D21	Zero new metric endpoints: wire the unused GET /analytics/merchant/dashboard, merchants-api offers, and the existing rollup join	Every needed number already has a server source; building new surfaces would repeat the complexity-ahead-of-demand mistake.
D22	Stats with no data source (wave accept rate, spend, period deltas) are REMOVED, not faked or zeroed	Honest telemetry is the house rule; a fabricated 68% accept rate in front of a paying venue is a trust failure.
D23	Web create-offer stays a link to the admin portal flow; no web offer-CRUD screen this theme	Admin owns offer CRUD (canonical); a second creation surface duplicates a locked, polished flow for no pilot value.
D24	merchant_applications is server-only (client read/write false), written via a new authenticated + rate-limited merchants-api endpoint	Same posture as offerClaims; applicant contact info must never be client-readable.

4. Needs operator input

• Nothing blocking. Open questions 1-2 in the spec (application notifications, peak-times bucket) are follow-ups.