docs rearrange
This commit is contained in:
alorig
200
approved-docs/user-flow-plan.md
Normal file
200
approved-docs/user-flow-plan.md
Normal file
@@ -0,0 +1,200 @@
|
||||
## IGNY8 User & Billing Flow — Current State and Remediation Plan
|
||||
|
||||
### 0) Scope / Sources
|
||||
- Frontend routing: `frontend/src/App.tsx`
|
||||
- Auth store and token handling: `frontend/src/store/authStore.ts`
|
||||
- Balance/usage/billing client: `frontend/src/services/api.ts`, `frontend/src/services/billing.api.ts`
|
||||
- Admin billing UI: `frontend/src/pages/Admin/AdminBilling.tsx`
|
||||
- Backend auth/billing routers: `backend/igny8_core/auth/urls.py`, `backend/igny8_core/business/billing/urls.py`, `backend/igny8_core/modules/billing/urls.py`
|
||||
|
||||
---
|
||||
|
||||
### 1) Signup / Login
|
||||
**Backend endpoints (auth/urls.py)**
|
||||
- POST `/api/v1/auth/register/` → creates user; no email verification enforced.
|
||||
- POST `/api/v1/auth/login/` → issues JWT access/refresh; requires valid account + plan for “happy path”.
|
||||
- POST `/api/v1/auth/refresh/` → refresh token.
|
||||
|
||||
**Frontend behavior (authStore)**
|
||||
- `register()` hits `/v1/auth/register/`; on success stores tokens and marks authenticated.
|
||||
- `login()` hits `/v1/auth/login/`; if user.account missing → throws `ACCOUNT_REQUIRED`; if plan missing → `PLAN_REQUIRED`. So the UI blocks login success if the account/plan is absent.
|
||||
- After login, routes are guarded by `ProtectedRoute` → land on main dashboard (`/`).
|
||||
|
||||
**Gaps**
|
||||
- No email verification or onboarding; user is dropped to dashboard.
|
||||
- If account/plan is missing, errors surface but no guided remediation (no redirect to plan selection).
|
||||
|
||||
---
|
||||
|
||||
### 2) Tenant Billing Data & Balance
|
||||
**Current endpoints used**
|
||||
- Balance: `/v1/billing/transactions/balance/` (business billing CreditTransactionViewSet.balance).
|
||||
- Credit transactions: `/api/v1/billing/transactions/`.
|
||||
- Usage logs/summary/limits: `/api/v1/billing/credits/usage/…`, `/v1/billing/credits/usage/summary/`, `/v1/billing/credits/usage/limits/`.
|
||||
- Invoices: `/api/v1/billing/invoices/` (+ detail, pdf).
|
||||
- Payments: `/api/v1/billing/payments/`.
|
||||
- Credit packages: `/v1/billing/credit-packages/`.
|
||||
|
||||
**UI touchpoints**
|
||||
- Header metric uses `fetchCreditBalance()` → `/v1/billing/transactions/balance/`.
|
||||
- Usage & Analytics, Credits pages, Billing panels use `getCreditBalance()` → same endpoint.
|
||||
|
||||
**Gaps**
|
||||
- Subscription lifecycle (select plan, subscribe/upgrade/cancel) not wired in UI.
|
||||
- Payment methods add/remove not exposed in UI.
|
||||
- Balance fetch falls back to zero on any non-200; no inline “balance unavailable” messaging.
|
||||
|
||||
---
|
||||
|
||||
### 3) Admin Billing (pages/Admin/AdminBilling.tsx)
|
||||
**Current tabs & data**
|
||||
- Overview: stats from `/v1/admin/billing/stats/` (totals, usage).
|
||||
- User Management: `/v1/admin/users/` (credit balances), adjust credits via `/v1/admin/users/{id}/adjust-credits/`.
|
||||
- Credit Pricing: `/v1/admin/credit-costs/` with editable cost per operation; Save posts updates.
|
||||
- Credit Packages: read-only cards from `/v1/billing/credit-packages/`.
|
||||
|
||||
**Gaps**
|
||||
- No admin CRUD for packages (only read).
|
||||
- No exports/filters for payments/invoices in this page (handled elsewhere).
|
||||
|
||||
---
|
||||
|
||||
### 4) Plan Limits / Access
|
||||
**Backend**
|
||||
- Auth login blocks if account plan missing (frontend enforced). Backend exposes plans/subscriptions via `auth/urls.py` (routers: `plans`, `subscriptions`).
|
||||
- Automation service checks `account.credits` directly before heavy AI work (no HTTP).
|
||||
|
||||
**Frontend**
|
||||
- No explicit plan-limit enforcement in UI (sites, seats, module gating) beyond route/module guards already present per module.
|
||||
- No upgrade prompts when hitting limits.
|
||||
|
||||
---
|
||||
|
||||
### 5) AI / Automation Credit Checks
|
||||
- Backend: `automation_service.py` estimates credits, adds 20% buffer, aborts if `account.credits` < required. Not dependent on billing APIs.
|
||||
- Frontend: no preflight credit warning; errors are backend-driven.
|
||||
|
||||
---
|
||||
|
||||
### 6) What’s Missing for a Complete E2E Paid Flow
|
||||
1) **Subscription UX**: Add tenant plan selection + subscribe/upgrade/cancel wired to `/api/v1/auth/subscriptions/...` (or billing subscription endpoints if exposed separately). Show current plan and renewal status.
|
||||
2) **Payment Methods**: Expose add/list/remove default; required for Stripe/PayPal/manual flows.
|
||||
3) **Invoices/Payments (tenant)**: List history with PDF download; surface payment status.
|
||||
4) **Manual payments (if supported)**: Provide upload/reference input; show approval status.
|
||||
5) **Plan limits**: Enforce and message limits on sites, seats, modules; show “Upgrade to increase limit.”
|
||||
6) **Balance UX**: If `/v1/billing/transactions/balance/` fails, show inline warning and retry instead of silently showing 0.
|
||||
7) **Admin packages**: If needed, add CRUD for credit packages (activate/feature/sort/price IDs).
|
||||
8) **Onboarding**: Post-signup redirect to “Choose plan” if no active plan; optional email verification.
|
||||
|
||||
---
|
||||
|
||||
### 7) Recommended Happy Path (Target)
|
||||
1) Signup → email verify (optional) → redirect to Plan selection.
|
||||
2) Choose plan → subscribe (create payment method + subscription intent) → confirm → landing on dashboard with non-zero credits and plan limits loaded.
|
||||
3) User can:
|
||||
- Add sites up to plan limit.
|
||||
- Use Planner/Writer modules; preflight check shows remaining credits.
|
||||
- View Credits/Usage/Invoices/Payments; purchase extra credit packages if needed.
|
||||
4) Header shows live balance from `/v1/billing/transactions/balance/`; errors visible if fetch fails.
|
||||
5) Admin can:
|
||||
- Adjust credit costs, see stats/payments/invoices/approvals.
|
||||
- Manage credit packages (CRUD) if enabled.
|
||||
|
||||
---
|
||||
|
||||
### 8) Quick Endpoint Reference (current wiring)
|
||||
- Balance: `/v1/billing/transactions/balance/`
|
||||
- Tenant: invoices `/api/v1/billing/invoices/`, payments `/api/v1/billing/payments/`, credit-packages `/v1/billing/credit-packages/`, usage `/api/v1/billing/credits/usage/`
|
||||
- Admin: stats `/v1/admin/billing/stats/`, users `/v1/admin/users/`, credit-costs `/v1/admin/credit-costs/`, admin payments `/v1/billing/admin/payments/`, pending approvals `/v1/billing/admin/pending_payments/`
|
||||
|
||||
---
|
||||
|
||||
## Remediation Plan (Do Now)
|
||||
|
||||
### A) Access control / onboarding
|
||||
- After register → force redirect to Plans page.
|
||||
- Lock all app routes except Account Profile, Plans, Billing until subscription is active (route guard).
|
||||
- Optional: email verification gate before plan selection.
|
||||
|
||||
### B) Plans & subscription UX (tenant)
|
||||
- Plans page: list plans from `/api/v1/auth/plans/` (or billing subscriptions endpoint), show limits.
|
||||
- Actions: subscribe/upgrade/cancel wired to subscription endpoints; show status/renewal date.
|
||||
- CTA in header/sidebar if no active plan.
|
||||
|
||||
### C) Payment methods
|
||||
- Add/list/remove default payment methods (Stripe/PayPal/manual) via billing endpoints.
|
||||
- Show “add payment method” inline on Plans/Billing if none exists.
|
||||
|
||||
### D) Checkout / payments
|
||||
- Credit packages purchase flow wired to `/v1/billing/credit-packages/…/purchase/`.
|
||||
- If manual payments allowed: upload/reference form and surface status; tie to admin approvals.
|
||||
- Invoice list/history with PDF download; payment history with status badges.
|
||||
|
||||
### E) Balance and usage UX
|
||||
- Use single endpoint `/v1/billing/transactions/balance/`; on non-200 show inline warning + retry (no silent zero).
|
||||
- Surface plan limits and usage (sites, seats, module access) with upgrade prompts when near/at limit.
|
||||
|
||||
### F) Module access & limits
|
||||
- Enforce plan limits on: add site, team invites, module guards (planner/writer/automation/etc.).
|
||||
- On 403/422 from backend: show upgrade prompt with link to Plans.
|
||||
|
||||
### G) Admin
|
||||
- Optional: add CRUD for credit packages (create/edit/sort/feature) if backend endpoints available.
|
||||
- Keep credit costs editable (already wired); add filters/exports later if needed.
|
||||
|
||||
### H) AI task preflight
|
||||
- Before costly AI actions, fetch balance and show “insufficient credits—purchase/upgrade” prompt.
|
||||
- Handle backend credit errors with actionable UI (purchase/upgrade CTA).
|
||||
|
||||
### I) Error handling / UX polish
|
||||
- Balance widget: display “Balance unavailable” on error; retry button.
|
||||
- Centralize billing error toasts with clear messages (404 vs 402/403 vs 500).
|
||||
|
||||
### J) Implementation order
|
||||
1) Route guard + post-signup redirect to Plans; hide other routes until active plan.
|
||||
2) Plans page with subscribe/upgrade/cancel wiring; add payment method UI.
|
||||
3) Billing page: invoices/payments/history + credit package purchase CTA.
|
||||
4) Balance/usage error handling; plan limit prompts; AI preflight checks.
|
||||
5) Admin package CRUD (if needed) and exports/filters.
|
||||
|
||||
|
||||
|
||||
[User lands]
|
||||
|
|
||||
v
|
||||
[/signup] -- create account --> [Tokens stored]
|
||||
|
|
||||
v
|
||||
[/account/plans] (onboarding gate)
|
||||
|
|
||||
|-- list plans (/v1/auth/plans/)
|
||||
|-- choose plan + payment method (default/selected)
|
||||
|-- subscribe (/v1/auth/subscriptions/)
|
||||
v
|
||||
[Plan active] -----> [Billing tabs available]
|
||||
| | \
|
||||
| | \
|
||||
| v v
|
||||
| [Purchase Credits] [Invoices/Payments]
|
||||
| /api/v1/... (list + PDF download)
|
||||
| |
|
||||
| v
|
||||
| [Balance/Usage/Limits] (shared store, retry)
|
||||
|
|
||||
v
|
||||
[Protected routes unlocked: /, modules, account]
|
||||
|
|
||||
v
|
||||
[Sites -> Add/Manage site]
|
||||
|
|
||||
|-- check plan limits (sites/seats/modules)
|
||||
|-- on limit: show upgrade/purchase prompt
|
||||
v
|
||||
[Site created]
|
||||
|
|
||||
v
|
||||
[Start workflow]
|
||||
|-- Planner/Writer/Automation, etc.
|
||||
|-- preflight: balance/limits; on 402/403 -> prompt upgrade/purchase
|
||||
v
|
||||
[User executes tasks with credits]
|
||||
Reference in New Issue
Block a user