From db146846674495a1c613a3022c86cd8d4f7ac5e1 Mon Sep 17 00:00:00 2001 From: Deeman Date: Wed, 25 Feb 2026 09:41:54 +0100 Subject: [PATCH] docs: update USER_FLOWS.md for marketplace + lead response flows - Flow 11: note CTA token in forward email + matching notification tasks - Flow 12 (new): supplier lead_respond endpoint + one-click CTA token flow - Flow 13 (was 12): add Marketplace admin dashboard row, update Leads row with search/filter/HTMX inline actions, note HTMX partials Co-Authored-By: Claude Sonnet 4.6 --- docs/USER_FLOWS.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/docs/USER_FLOWS.md b/docs/USER_FLOWS.md index 3f30b3b..645334e 100644 --- a/docs/USER_FLOWS.md +++ b/docs/USER_FLOWS.md @@ -169,23 +169,40 @@ Same as Flow 2 but arrives at `//leads/quote` directly (no planner state). |------|-----|-------| | 1 | View teased lead | `GET //suppliers/dashboard/leads` — lead shown with blurred contact info | | 2 | Unlock | `POST //suppliers/leads//unlock` — deducts 1 credit, reveals full lead | -| 3 | Receive email | `send_lead_forward_email` task enqueued — full project brief sent to supplier | +| 3 | Receive email | `send_lead_forward_email` task enqueued — full project brief sent to supplier with one-click CTA link | | 4 | Entrepreneur notified | `send_lead_matched_notification` task — notifies entrepreneur a supplier was matched | **Auth required:** Yes — `@_lead_tier_required` **Credit check:** Server-side check; if 0 credits → redirect to boosts tab +**Matching notification:** On quote verification, `notify_matching_suppliers` task auto-notifies growth/pro suppliers whose `service_area` matches the lead's country (max 20 per lead); `send_weekly_lead_digest` sends a Monday 08:00 UTC summary of new matching leads to all paid suppliers --- -## 12. Admin Flows +## 12. Supplier → Update Lead Response Status + +**Entry:** Supplier dashboard leads tab, or one-click CTA link in forward email + +| Step | URL | Notes | +|------|-----|-------| +| 1a | Click "Mark as contacted" in email | `GET /suppliers/leads/cta/` — one-click; advances status `sent` → `contacted`; redirects to `/suppliers/dashboard?tab=leads` | +| 1b | Update via dashboard | `POST //suppliers/leads//respond` — HTMX; sets `status` and optional `supplier_note`; returns 204 | + +**Auth required:** CTA link is unauthenticated (token is the credential); dashboard endpoint requires `@_lead_tier_required` +**Valid statuses:** `sent / viewed / contacted / quoted / won / lost / no_response` +**Idempotency:** CTA only advances `sent → contacted`; subsequent clicks are no-ops + +--- + +## 13. Admin Flows **Entry:** `/admin/` (requires `@role_required("admin")`) | Area | URL | What you can do | |------|-----|-----------------| | Dashboard | `GET /admin/` | Stats overview | +| Marketplace | `GET /admin/marketplace` | Lead funnel, credit economy, supplier engagement, live activity stream, inline feature flag toggles | | Users | `GET /admin/users`, `/admin/users/` | List, view, impersonate | -| Leads | `GET /admin/leads`, `/admin/leads/` | List, filter, view detail, change status, forward to supplier, create | +| Leads | `GET /admin/leads`, `/admin/leads/` | List (search + period filter + summary cards), view detail, HTMX inline status change + forward to supplier | | Suppliers | `GET /admin/suppliers`, `/admin/suppliers/` | List, view, adjust credits, change tier, create | | Feedback | `GET /admin/feedback` | View all submitted feedback | | Email Sent Log | `GET /admin/emails`, `/admin/emails/` | List all outgoing emails (filter by type/event/search), detail with API-enriched HTML preview | @@ -197,6 +214,7 @@ Same as Flow 2 but arrives at `//leads/quote` directly (no planner state). | Articles | `GET /admin/articles` | CRUD, publish/unpublish, rebuild HTML | | Task Queue | `GET /admin/tasks` | View worker tasks, retry/delete failed | +**HTMX partials:** `lead_status_badge.html` (status change), `lead_forward_history.html` (forward history), `marketplace_activity.html` (activity stream) **Dev shortcut:** `/auth/dev-login?email=` where email is in `config.ADMIN_EMAILS` ---