Billing and account fixed - final

docs/billing/billing-account-final-plan-2025-12-05.md

@@ -0,0 +1,143 @@
+# IGNY8 Billing & Account Platform — Final Plan  
+**Date:** 2025-12-05  
+**Status:** Canonical (supersedes all prior billing/account docs)  
+**Scope:** Tenant + Admin experience across Billing, Account, Credits, Payment Methods, and Payment Gateways. Frontend + Backend must use the IGNY8 standard API system.
+
+---
+
+## 1) Purpose & Principles
+- Single source of truth for billing/account flows.
+- One canonical API namespace per audience (tenant vs admin).
+- Align models ↔ services ↔ serializers ↔ frontend calls; remove drift.
+- Keep manual payment path healthy while Stripe/PayPal mature.
+- Favor incremental rollout with feature-flagged transitions.
+
+---
+
+## 2) Canonical Namespaces
+- Tenant: `/api/v1/billing/...`
+- Admin: `/api/v1/admin/billing/...`
+- Deprecate legacy `/api/v1/admin/...` (modules/billing) and duplicated routers. Optionally dual-serve for one release behind a feature flag.
+
+---
+
+## 3) Reality Snapshot (current code)
+- Tenant billing viewsets live in `backend/igny8_core/business/billing/views.py` (invoices, payments, credit packages, transactions).
+- Admin billing viewset also exists there (`pending_payments`, approvals, stats) but mounted at `/api/v1/billing/admin/...`.
+- Legacy admin stack in `backend/igny8_core/modules/billing/views.py` exposes stats/users/credit-costs only; no invoices/payments.
+- Model drift: `InvoiceService` expects `currency`, `tax_amount`, `total_amount` that are absent on `Invoice`. `PaymentService` uses `pending_approval`/`completed` statuses not present in `Payment.STATUS_CHOICES`.
+- Frontend admin pages are wired but call nonexistent or legacy routes (e.g., `/v1/admin/payments/`).
+
+---
+
+## 4) Backend Plan
+### 4.1 Models & Migrations (billing app)
+- Invoice: add `currency`, `subtotal_amount`, `tax_amount`, `total_amount`, `line_items` (JSON list), `payment_method` (string), `stripe_invoice_id`/`paypal_invoice_id` (nullable), `metadata`. Keep existing dates/status. Add index on `status, created_at`.
+- Payment: extend `STATUS_CHOICES` to include `pending_approval`, `processing`, `completed`, `failed`, `refunded`, `cancelled`. Add `payment_method` enum (stripe, paypal, bank_transfer, local_wallet, manual), gateway intent/charge ids, `manual_reference`, `failure_reason`, `approved_by/at`, `metadata`.
+- CreditPackage: ensure `slug`, `price`, `credits`, `stripe_price_id` exist and `is_active`, `is_featured`. Add `sort_order` for admin ordering.
+- PaymentMethodConfig: keep as source for country-level enablement; ensure uniqueness `(country_code, payment_method)`.
+- Write forward/backward-safe migrations; backfill currency and totals with sensible defaults (e.g., `USD`, recompute `total_amount=subtotal_amount+tax_amount` where possible).
+
+### 4.2 Services
+- `InvoiceService`: align fields; generate invoice numbers, compute subtotal/tax/total, store line items, mark paid/void/uncollectible, emit events, optionally render PDF stub.
+- `PaymentService`: 
+  - Stripe/PayPal: create intents/orders, store ids, update status on success/failure, attach to invoice, and trigger credit application when relevant.
+  - Manual: create `pending_approval`, allow approve/reject endpoints to flip status and apply credits.
+  - Sync helpers from webhooks/intents; emit structured logs.
+- `SubscriptionService` (existing): ensure plan ↔ subscription sync; use Stripe subscription id; update invoice/payment when Stripe posts events.
+- `CreditPackageService`: list active packages, create invoice + payment intent, on success add credits (`CreditTransaction`) and recalc balance.
+
+### 4.3 Webhooks
+- Add `/api/v1/billing/webhooks/stripe/` and `/api/v1/billing/webhooks/paypal/` with signature verification.
+- Handle events: `invoice.paid`, `invoice.payment_failed`, `customer.subscription.updated/deleted`, `payment_intent.succeeded/failed`, PayPal equivalents.
+- Idempotent processing; log and surface dead-letter queue for failures.
+
+### 4.4 APIs (Tenant)
+- `GET /api/v1/billing/account_balance/` – balance + monthly included.
+- `GET /api/v1/billing/transactions/` – credit transactions (paginated).
+- `GET /api/v1/billing/usage/` – usage logs with filters.
+- `GET /api/v1/billing/invoices/` | `GET /api/v1/billing/invoices/:id/` | `GET /api/v1/billing/invoices/:id/pdf/`.
+- `GET /api/v1/billing/payments/` | `GET /api/v1/billing/payments/:id/`.
+- `GET /api/v1/billing/credit-packages/`.
+- `POST /api/v1/billing/credits/purchase/` – create intent; returns client secret + invoice id.
+- `POST /api/v1/billing/subscriptions/create|upgrade|cancel/`.
+- `GET /api/v1/billing/subscriptions/` – current subscription status.
+- `GET/POST /api/v1/billing/payment-methods/` – list/add; store tokens/ids, not card data.
+
+### 4.5 APIs (Admin)
+- `GET /api/v1/admin/billing/invoices/` | `GET /:id/` – all accounts, filters (status, account, method, date), pagination, export.
+- `GET /api/v1/admin/billing/payments/` | `GET /:id/` – all accounts, filters (status, method, gateway).
+- `POST /api/v1/admin/billing/payments/:id/approve/` | `/reject/` – manual payments only.
+- `GET/POST/PATCH/DELETE /api/v1/admin/billing/credit-packages/` – CRUD with `is_featured`, `sort_order`.
+- `GET /api/v1/admin/billing/stats/` – totals, MRR, pending approvals, failed webhooks.
+- `GET /api/v1/admin/billing/pending_payments/` – for approvals (same payload frontend expects).
+- AuthZ: developer/superuser only; enforce tenant scoping for non-admin routes.
+
+### 4.6 Settings & Config
+- Add `STRIPE_PUBLIC_KEY`, `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `PAYPAL_CLIENT_ID`, `PAYPAL_CLIENT_SECRET`, `PAYPAL_WEBHOOK_ID` to settings/env; feature-flag gateways.
+- Rate-limit payment endpoints; CSRF exempt webhooks only.
+
+---
+
+## 5) Frontend Plan
+### 5.1 Service Layer (`frontend/src/services/billing.api.ts`)
+- Point all admin calls to `/api/v1/admin/billing/...`; remove dead `/v1/admin/...` routes.
+- Reuse tenant calls for user-facing pages; ensure response shapes match new serializers (`InvoiceSerializer`, `PaymentSerializer`, `CreditPackageSerializer`).
+- Add helpers for manual approval actions and credit-package CRUD.
+
+### 5.2 Tenant Pages
+- Plans & Billing (`/account/billing`): tabs for Plan, Credits, Billing History (invoices), Payment Methods. Uses balance, subscription, invoices, payment-methods, credit-packages, purchase intent.
+- Purchase Credits (`/account/credits/purchase`): list packages → create purchase intent → confirm via Stripe/PayPal/manual upload → poll payment.
+- Invoices (`/account/invoices`): paginated table, filters, PDF download.
+- Payment Methods: list/add/remove default (via tokens).
+
+### 5.3 Admin Pages
+- Billing Overview (`/admin/billing`): stats from `/admin/billing/stats/`, pending approvals summary.
+- Invoices (`/admin/invoices`): uses `/admin/billing/invoices/`; add filters (account, status, method, date) and CSV/PDF export.
+- Payments (`/admin/payments`): uses `/admin/billing/payments/`; add filters and status badges.
+- Credit Packages (`/admin/credit-packages`): CRUD via admin endpoints; show `is_active`, `is_featured`, `sort_order`, Stripe price id.
+- Payment Approvals (`/admin/payments/approvals`): call `pending_payments`, approve/reject endpoints; show invoice link and manual references.
+- Sidebar links already present—only fix data wiring.
+
+### 5.4 UX/Consistency
+- Standard empty/error/loading states across billing pages.
+- Currency display from invoice/payment `currency`.
+- Role-guard tenant routes (owner/admin only for purchases; read-only for others where applicable).
+
+---
+
+## 6) Sequenced Action Plan
+- **Day 0 (alignment):** Merge this doc; add “retired” note to older docs; choose namespace flag (`USE_NEW_ADMIN_BILLING_API=true`).
+- **Phase 1 (backend, 2-3 days):** Migrate models; update services; add admin list endpoints; webhook stubs; tests for serializers and viewsets.
+- **Phase 2 (gateways + frontend wiring, 3-4 days):** Implement Stripe/PayPal intent paths, hook webhooks, wire `billing.api.ts` to new endpoints, fix admin pages, enable manual approvals end-to-end.
+- **Phase 3 (polish, 2 days):** Add exports, filters, pagination polish; observability (structured logs, alerts); finalize docs and remove legacy router.
+
+---
+
+## 7) Deliverables & DoD
+- Schema migration applied and reversible; services match models.
+- Canonical endpoints live and documented; legacy admin endpoints removed/flagged off.
+- Tenant billing pages load without 404s; purchases and subscriptions succeed (manual + Stripe at minimum).
+- Admin pages show data, support approvals, and package CRUD.
+- Tests: unit (services), API (tenant/admin billing), integration (purchase + manual approval flow), webhook idempotency.
+- Docs: this file referenced from legacy docs; endpoint matrix embedded in `billing.api.ts` JSDoc or a short `/docs/billing/api-map.md`.
+
+---
+
+## 8) Quick Endpoint Matrix (canonical)
+- Tenant: invoices (`/api/v1/billing/invoices`), payments (`/api/v1/billing/payments`), credit packages + purchase (`/api/v1/billing/credit-packages`, `/credits/purchase`), subscription create/upgrade/cancel (`/subscriptions/...`), payment methods (`/payment-methods`), usage/transactions/balance.
+- Admin: invoices (`/api/v1/admin/billing/invoices`), payments (`/api/v1/admin/billing/payments`), pending approvals (`/api/v1/admin/billing/pending_payments`), approve/reject (`/api/v1/admin/billing/payments/:id/approve|reject`), credit packages CRUD (`/api/v1/admin/billing/credit-packages`), stats (`/api/v1/admin/billing/stats`).
+
+---
+
+## 9) Rollout & Migration Notes
+- Run migrations during maintenance window; backfill currency/totals.
+- If dual-stack needed, proxy legacy admin routes to new handlers temporarily.
+- Communicate new admin endpoints to frontend before flipping flags.
+- Validate webhook secrets in non-prod before enabling in prod.
+
+---
+
+## 10) Retirement Notice
+This document supersedes `docs/working-docs/Original-plan-may-have-wrong-logic.md` and `docs/working-docs/admin-billing-plan-2025-12-05.md`. Treat those as retired; keep only for historical reference.
+