200 lines
9.2 KiB
Markdown
200 lines
9.2 KiB
Markdown
## 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] |