364 lines
13 KiB
Markdown
364 lines
13 KiB
Markdown
# Section 4: ACCOUNT Modules - Audit & Action Plan
|
|
|
|
**Date:** December 27, 2025
|
|
**Status:** Finalized for Implementation
|
|
**Scope:** Account Settings, Plans & Billing, Usage (AI Models excluded - admin only)
|
|
|
|
---
|
|
|
|
## 4.1 Account Settings
|
|
|
|
**Route:** `/account/settings`
|
|
**File:** `pages/account/AccountSettingsPage.tsx`
|
|
**Tabs:** Account, Profile, Team
|
|
|
|
### Current Functionality
|
|
- **Account Tab:** Organization name, billing email, full billing address, tax ID/VAT
|
|
- **Profile Tab:** First/last name, email, phone, timezone, language, notifications, security
|
|
- **Team Tab:** List team members, invite via email, remove members, role display
|
|
|
|
---
|
|
|
|
### Issues to Address
|
|
|
|
| # | Issue | Priority | Action |
|
|
|---|-------|----------|--------|
|
|
| 1 | Profile NOT connected to API | 🔴 Critical | Study existing backend - if profile API exists and is consistent with system, connect it. If not present, create consistent with existing API structure |
|
|
| 2 | Change Password does nothing | 🔴 Critical | Implement password change functionality |
|
|
| 3 | No role assignment on invite | High | Add role dropdown (Admin/Member) to invitation form |
|
|
| 4 | No role editing for members | High | Add ability to change member role after invitation |
|
|
| 5 | No email verification | High | Implement email verification flow when email is changed |
|
|
| 6 | Orphaned TeamManagement.tsx | High | Delete `pages/account/TeamManagement.tsx` - functionality exists in AccountSettingsPage |
|
|
| 7 | No 2FA option | Medium | Add two-factor authentication option in security section |
|
|
| 8 | No account deletion | Medium | Add account closure/deletion capability |
|
|
| 9 | No session management | Medium | Add view/revoke active sessions capability |
|
|
| 10 | No pending invitation management | Medium | Add ability to resend or cancel pending invitations |
|
|
| 11 | No team member limit display | Medium | Show "X of Y team members" based on plan limit |
|
|
| 12 | Inconsistent role system | Medium | Backend returns `is_admin` boolean but UI shows Admin/Member - align these |
|
|
|
|
---
|
|
|
|
### Implementation Notes
|
|
|
|
**For Issue #1 (Profile API):**
|
|
- First: Audit backend to check if profile endpoint exists
|
|
- If exists: Study implementation, verify consistency with other APIs, then connect frontend
|
|
- If not exists: Create new endpoint following existing API patterns in the codebase
|
|
- Fields to persist: first_name, last_name, email, phone, timezone, language, notification preferences
|
|
|
|
**For Issue #2 (Password change):**
|
|
- Implement secure password change requiring current password
|
|
- Validate new password meets requirements
|
|
- Consider session invalidation after password change
|
|
|
|
**For Issue #12 (Role consistency):**
|
|
- Decide on role system: boolean `is_admin` or role enum (admin/member/viewer)
|
|
- Align frontend display with backend data structure
|
|
|
|
---
|
|
|
|
## 4.2 Plans & Billing
|
|
|
|
**Route:** `/account/plans`
|
|
**Files:** `pages/account/PlansAndBillingPage.tsx`, `pages/Billing/CreditPurchase.tsx`
|
|
**Tabs:** Current Plan, Upgrade Plan, History
|
|
|
|
### Current Functionality
|
|
- **Current Plan:** Plan name, status, credits, balance, renewal date, features
|
|
- **Upgrade:** Pricing table, plan comparison, change policy
|
|
- **History:** Invoices with PDF download, payments, payment methods
|
|
|
|
### Payment Context
|
|
Currently using manual payment methods only (bank transfer, wallet). No automatic payment processing.
|
|
|
|
---
|
|
|
|
### Issues to Address
|
|
|
|
| # | Issue | Priority | Action |
|
|
|---|-------|----------|--------|
|
|
| 1 | No proration preview | High | Show prorated amount before plan upgrade/downgrade |
|
|
| 2 | Credit purchase not linked | Medium | Link to credit purchase from Plans & Billing page |
|
|
| 3 | Cancellation is immediate | High | Add confirmation dialog before plan cancellation |
|
|
| 4 | No downgrade proration display | Medium | Show calculation when downgrading plan |
|
|
| 5 | Throttling errors surface to users | Medium | Replace raw throttling messages with user-friendly spinner/message |
|
|
| 6 | No billing cycle visualization | Medium | Make renewal date prominent, show billing cycle clearly |
|
|
| 7 | No cancellation reason collection | Low | Add optional reason selection when cancelling |
|
|
|
|
---
|
|
|
|
### Issues NOT Being Addressed (Per Discussion)
|
|
|
|
| Issue | Reason |
|
|
|-------|--------|
|
|
| No payment failure retry | Manual payment only - no auto-retry needed |
|
|
| Payment method UI incomplete | Manual payment only - limited methods by design |
|
|
|
|
---
|
|
|
|
### Implementation Notes
|
|
|
|
**For Issue #1 (Proration preview):**
|
|
- Before confirming plan change, show:
|
|
- Current plan remaining value
|
|
- New plan cost
|
|
- Prorated amount due/credited
|
|
- Calculate based on days remaining in billing cycle
|
|
|
|
**For Issue #3 (Cancellation confirmation):**
|
|
- Modal dialog: "Are you sure you want to cancel?"
|
|
- Show what they'll lose (features, remaining credits)
|
|
- Require explicit confirmation
|
|
|
|
**For Issue #5 (Throttling messages):**
|
|
- Intercept throttling errors
|
|
- Show spinner with "Processing your request..." instead of technical error
|
|
- Implement proper retry logic behind the scenes
|
|
|
|
---
|
|
|
|
## 4.3 Usage
|
|
|
|
**Route:** `/account/usage`
|
|
**Files:** `pages/account/UsageAnalyticsPage.tsx`, `pages/account/UsageLimits.tsx`, `pages/account/CreditActivity.tsx`
|
|
**Tabs:** Your Limits & Usage, Credit History, API Activity
|
|
|
|
### Current Functionality
|
|
- **Quick Stats:** Credits left, used this month, monthly limit, usage %
|
|
- **Limits:** Hard limits (sites, users, keywords, clusters) + Monthly limits
|
|
- **Credit History:** Transaction log with type, amount, description
|
|
- **API Activity:** Call statistics, endpoint breakdown
|
|
|
|
---
|
|
|
|
### Issues to Address
|
|
|
|
| # | Issue | Priority | Action |
|
|
|---|-------|----------|--------|
|
|
| 1 | API Activity is HARDCODED | 🔴 Critical | Implement real API activity tracking - replace fake values (1,234, 567, 342) |
|
|
| 2 | Success rate is fake | 🔴 Critical | Calculate and display real success rate from actual data |
|
|
| 3 | No usage alerts | High | Implement default alerts at usage thresholds (80%, 90%, 100%) - sent to all users automatically |
|
|
| 4 | No per-site usage | High | Add breakdown showing which site consumed what |
|
|
| 5 | No usage forecasting | Medium | Add "At current rate, you'll reach limit in X days" |
|
|
| 6 | No actionable insights | Medium | Suggest upgrade when approaching limits |
|
|
| 7 | Credit history lacks context | Medium | Add links from credit transactions to related content/operations |
|
|
|
|
---
|
|
|
|
### Issues NOT Being Addressed (Per Discussion)
|
|
|
|
| Issue | Reason |
|
|
|-------|--------|
|
|
| No per-user usage | Not needed for current phase |
|
|
| No usage export | Not needed for current phase |
|
|
|
|
---
|
|
|
|
### Implementation Notes
|
|
|
|
**For Issue #1 & #2 (Real API Activity):**
|
|
- Backend needs to log API calls (may already exist)
|
|
- Track: endpoint, timestamp, status (success/fail), response time
|
|
- Aggregate for display: total calls, success rate, calls by endpoint
|
|
- Replace hardcoded values with real calculated data
|
|
|
|
**For Issue #3 (Usage alerts):**
|
|
- Default behavior: all users receive alerts
|
|
- Trigger points: 80%, 90%, 100% of limits
|
|
- Delivery: in-app notification + email
|
|
- No user preferences needed - alerts go to everyone
|
|
|
|
**For Issue #4 (Per-site usage):**
|
|
- Break down credit usage by site
|
|
- Show: "Site A: 450 credits, Site B: 230 credits"
|
|
- Pie chart or table visualization
|
|
|
|
---
|
|
|
|
## 4.4 AI Models (Admin Only)
|
|
|
|
**Status:** ❌ SKIP ENTIRELY
|
|
|
|
Not part of user-facing modules. Admin only - no changes needed.
|
|
|
|
---
|
|
|
|
## 4.5 ACCOUNT Cross-Module Issues (MAJOR)
|
|
|
|
These are architectural issues requiring proper analysis and solutions.
|
|
|
|
### Issues to Address
|
|
|
|
| # | Issue | Priority | Action |
|
|
|---|-------|----------|--------|
|
|
| 1 | Multiple credit balance sources | 🔴 Critical | Establish ONE source of truth for credit balance. Analyze: Plans page, Usage page, billingStore - determine which is authoritative, remove others, refactor all references |
|
|
| 2 | Fragmented billing pages | High | **AI Agent Task:** Audit system to identify all billing-related pages/functions, find duplicates/redundancies, propose consolidation solution |
|
|
| 3 | Legacy routes still exist | High | Remove legacy routes (`/billing/overview`, `/team`, `/profile`), remove redirect code, refactor any references throughout codebase |
|
|
| 4 | No notification preferences | Low | Not needed - default alerts go to all users |
|
|
|
|
---
|
|
|
|
### Implementation Notes
|
|
|
|
**For Issue #1 (Single source of truth for balance):**
|
|
|
|
*Phase 1: Analysis*
|
|
- Identify all places that fetch/display credit balance:
|
|
- `billingStore.ts` (Zustand store)
|
|
- Plans & Billing page
|
|
- Usage page
|
|
- Dashboard (if applicable)
|
|
- Header component (if showing balance)
|
|
- Document how each fetches data (API endpoint, frequency)
|
|
|
|
*Phase 2: Decision*
|
|
- Determine which should be THE source:
|
|
- Likely `billingStore` as central state management
|
|
- Single API endpoint for balance data
|
|
- All components should read from this one source
|
|
|
|
*Phase 3: Implementation*
|
|
- Refactor all components to use single source
|
|
- Remove duplicate API calls
|
|
- Remove duplicate state management
|
|
- Ensure consistency across all views
|
|
|
|
**For Issue #2 (Fragmented billing pages):**
|
|
|
|
*AI Agent Audit Task:*
|
|
```
|
|
TASK: Billing Pages Consolidation Audit
|
|
|
|
1. DISCOVER all billing-related files:
|
|
- pages/account/PlansAndBillingPage.tsx
|
|
- pages/Billing/CreditPurchase.tsx
|
|
- pages/Billing/Credits.tsx (if exists)
|
|
- pages/Settings/CreditsAndBilling.tsx (if exists)
|
|
- Any other billing-related pages
|
|
|
|
2. ANALYZE each page:
|
|
- What functionality does it provide?
|
|
- What routes point to it?
|
|
- Is it actively used or orphaned?
|
|
- Does it duplicate functionality from another page?
|
|
|
|
3. IDENTIFY redundancies:
|
|
- Same functionality in multiple places
|
|
- Overlapping features
|
|
- Dead/orphaned pages
|
|
|
|
4. PROPOSE solution:
|
|
- Which pages to keep
|
|
- Which pages to merge
|
|
- Which pages to delete
|
|
- Final consolidated structure
|
|
|
|
5. DOCUMENT migration path:
|
|
- What routes need updating
|
|
- What references need changing
|
|
- What imports need refactoring
|
|
```
|
|
|
|
**For Issue #3 (Legacy routes removal):**
|
|
|
|
*Routes to remove:*
|
|
- `/billing/overview`
|
|
- `/team`
|
|
- `/profile`
|
|
|
|
*Process:*
|
|
1. Find route definitions in router/App.tsx
|
|
2. Remove route entries
|
|
3. Find and remove redirect logic
|
|
4. Search codebase for any links to these routes
|
|
5. Update or remove those links
|
|
6. Delete any orphaned components only used by these routes
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
### Total Issues by Section
|
|
|
|
| Section | Critical | High | Medium | Low | Total |
|
|
|---------|----------|------|--------|-----|-------|
|
|
| 4.1 Account Settings | 2 | 4 | 6 | 0 | 12 |
|
|
| 4.2 Plans & Billing | 0 | 2 | 4 | 1 | 7 |
|
|
| 4.3 Usage | 2 | 2 | 3 | 0 | 7 |
|
|
| 4.4 AI Models | - | - | - | - | Skipped |
|
|
| 4.5 Cross-Module | 1 | 2 | 0 | 1 | 4 |
|
|
| **TOTAL** | **5** | **10** | **13** | **2** | **30** |
|
|
|
|
---
|
|
|
|
### Critical Items (Must Fix)
|
|
|
|
1. **Account Settings** - Profile tab not connected to API
|
|
2. **Account Settings** - Password change does nothing
|
|
3. **Usage** - API Activity tab shows hardcoded fake data
|
|
4. **Usage** - Success rate is fake (98.5%)
|
|
5. **Cross-Module** - Multiple credit balance sources causing inconsistency
|
|
|
|
---
|
|
|
|
### High Priority Items
|
|
|
|
1. Account Settings - Role assignment on invite
|
|
2. Account Settings - Role editing for members
|
|
3. Account Settings - Email verification
|
|
4. Account Settings - Delete orphaned TeamManagement.tsx
|
|
5. Plans & Billing - Proration preview
|
|
6. Plans & Billing - Cancellation confirmation dialog
|
|
7. Usage - Usage alerts at thresholds
|
|
8. Usage - Per-site usage breakdown
|
|
9. Cross-Module - Billing pages consolidation audit
|
|
10. Cross-Module - Legacy routes removal
|
|
|
|
---
|
|
|
|
### Files to Delete
|
|
|
|
| File | Reason |
|
|
|------|--------|
|
|
| `pages/account/TeamManagement.tsx` | Orphaned - functionality in AccountSettingsPage |
|
|
| Legacy route redirect handlers | After removing `/billing/overview`, `/team`, `/profile` |
|
|
| Duplicate billing pages | After consolidation audit determines which to remove |
|
|
|
|
---
|
|
|
|
### Files to Modify
|
|
|
|
| File | Changes |
|
|
|------|---------|
|
|
| `pages/account/AccountSettingsPage.tsx` | Connect profile API, implement password change, add role management, add invitation management |
|
|
| `pages/account/PlansAndBillingPage.tsx` | Add proration preview, cancellation confirmation, link credit purchase |
|
|
| `pages/account/UsageAnalyticsPage.tsx` | Implement real API activity, add per-site breakdown, add forecasting |
|
|
| `store/billingStore.ts` | Establish as single source of truth for balance |
|
|
| Router/App.tsx | Remove legacy routes |
|
|
| All components using credit balance | Refactor to use single source |
|
|
|
|
---
|
|
|
|
### Backend Work Required
|
|
|
|
| Area | Work |
|
|
|------|------|
|
|
| Profile API | Audit existing endpoint OR create new one consistent with API structure |
|
|
| Password change API | Implement secure password change endpoint |
|
|
| API Activity tracking | Ensure backend logs API calls, create endpoint to retrieve activity data |
|
|
| Usage alerts | Backend service to check thresholds and trigger notifications |
|
|
| Per-site usage | Endpoint to return credit usage broken down by site |
|
|
|
|
---
|
|
|
|
### AI Agent Specific Tasks
|
|
|
|
| Task | Description |
|
|
|------|-------------|
|
|
| Billing Pages Audit | Discover all billing pages, analyze functionality, identify redundancies, propose consolidation |
|
|
| Credit Balance Refactor | Identify all balance sources, determine single source, refactor all references |
|
|
| Legacy Routes Cleanup | Remove routes, remove redirects, update all references |
|
|
| Profile API Study | Check if endpoint exists, verify consistency, connect or create |
|
|
|
|
---
|