# Advanced Customer Account for WooCommerce - Development Plan

A modern, React-powered WooCommerce My Account page replacement with SPA experience, advanced features, and freemium business model. Built with WooCommerce REST API for fast, seamless customer portal experience.

---

## 🛠️ Technical Stack

| Layer | Technology | Version |
|-------|------------|---------|
| **Build System** | `@wordpress/scripts` | ^31.4.0 |
| **React** | `@wordpress/element` | ^6.39.0 |
| **UI Components** | `@wordpress/components` | ^32.1.0 |
| **State Management** | `@wordpress/data` | ^10.39.0 |
| **API Client** | `@wordpress/api-fetch` | ^7.39.0 |
| **i18n** | `@wordpress/i18n` | ^6.12.0 |
| **Hooks** | `@wordpress/hooks` | ^4.39.0 |
| **Notices** | `@wordpress/notices` | ^5.39.0 |
| **Icons** | `@wordpress/icons` | ^11.6.0 |
| **Utilities** | `@wordpress/compose`, `@wordpress/url` | Latest |
| **CSS** | Custom CSS with Flexbox/Grid, BEM naming | - |
| **Form Validation** | `react-hook-form` + `zod` | ^7.54.0 / ^3.23.0 |
| **Date Handling** | `date-fns` | ^3.6.0 |
| **Class Names** | `classnames` | ^2.5.1 |
| **PDF Generation** | `dompdf` (PHP) | ^2.0 |

---

## 🆓 Free Version Features

### 1. Modern Dashboard
- Welcome message with customer name
- Quick stats (total orders, money spent, member since)
- Recent 5 orders with status badges
- Profile completeness indicator
- Quick action buttons

### 2. Customer Interest-Based Products
- **"Recommended For You"** section based on purchase history
- **"Based on Your Recent Orders"** - similar products
- **"Frequently Bought Together"** - complementary products
- Algorithm: Analyze order categories, tags, attributes
- Display 4-8 products with "Add to Cart" button

### 3. Special Offers & Deals
- **"Exclusive Offers"** - products on sale matching customer interests
- **"New Arrivals For You"** - latest products in purchased categories
- **"Limited Time Deals"** - countdown timer for urgency
- Personalized offer banners based on browsing/purchase behavior
- **"Back in Stock"** - previously viewed out-of-stock items now available

### 4. My Coupons Dashboard
- Display all available coupons for the customer
- One-click copy-to-clipboard + "Apply to Cart" button
- Expiration alerts (< 7 days warning)
- Usage limit display ("2 of 5 uses remaining")
- Coupon usage history with order links
- Group by type: Percentage, Fixed Cart, Fixed Product

### 5. Support Ticket System (Basic)
- Create general support tickets from My Account
- View all tickets with status (Open, In Progress, Closed)
- Add replies to existing tickets
- Email notifications on admin reply
- **Limit: 3 active tickets** (Pro = unlimited)

### 6. Quick Reorder
- "Buy Again" button on past orders
- One-click add all items to cart
- Handle out-of-stock gracefully

### 7. Recently Viewed Products
- Last 10 viewed products in My Account
- Quick "Add to Cart" from list
- Clear history option

### 8. Account Activity Log
- Last 10 activities (orders, profile updates, logins)
- Timeline view with timestamps

### 9. Order Notes
- Add personal notes to orders (customer side)

### 10. Basic PDF Invoice
- Download simple invoice PDF for orders

### 11. Menu Customization
- Show/hide menu endpoints
- Drag-drop reordering
- Basic icons (Dashicons)
- **Limit: 2 custom endpoints**

---

## 💎 Pro Version Features

| Category | Pro Enhancement |
|----------|-----------------|
| **Recommendations** | AI-powered suggestions, cross-sell widgets, "Complete the Look" |
| **Offers** | Personalized discount banners, abandoned cart offers, loyalty rewards |
| **Coupons** | Auto-apply best coupon, birthday coupons, referral codes |
| **Tickets** | Unlimited, order-linked, attachments, priority levels, SLA |
| **Activity Log** | Full history, export CSV, security alerts |
| **Invoices** | Custom templates, bulk download, packing slips |
| **Menu** | Unlimited endpoints, role-based visibility, custom icons |
| **Security** | 2FA, login history, session management |
| **Wishlist Integration** | Connect with YITH/TI Wishlist, display in dashboard |

---

## 📁 Plugin Structure

```
advanced-customer-account/
├── advanced-customer-account.php       # Main plugin file
├── uninstall.php                       # Cleanup on uninstall
├── composer.json                       # PHP dependencies
├── package.json                        # JS dependencies
├── webpack.config.js                   # Custom webpack config
│
├── includes/
│   ├── class-aca-loader.php            # Autoloader
│   ├── class-aca-activator.php         # Activation hooks
│   ├── class-aca-deactivator.php       # Deactivation hooks
│   │
│   ├── Admin/
│   │   ├── class-aca-admin.php         # Admin settings page
│   │   ├── class-aca-admin-menu.php    # Menu customization UI
│   │   └── class-aca-ticket-admin.php  # Ticket management
│   │
│   ├── API/
│   │   ├── class-aca-rest-controller.php  # Base REST controller
│   │   ├── class-aca-dashboard-api.php
│   │   ├── class-aca-orders-api.php
│   │   ├── class-aca-coupons-api.php
│   │   ├── class-aca-tickets-api.php
│   │   ├── class-aca-recommendations-api.php
│   │   └── class-aca-profile-api.php
│   │
│   ├── PostTypes/
│   │   └── class-aca-ticket-cpt.php    # Support Ticket CPT
│   │
│   ├── Services/
│   │   ├── class-aca-recommendation-engine.php
│   │   ├── class-aca-pdf-generator.php
│   │   └── class-aca-email-service.php
│   │
│   └── Frontend/
│       ├── class-aca-shortcode.php     # [aca_my_account]
│       └── class-aca-assets.php        # Enqueue scripts/styles
│
├── src/                                # React source code
│   ├── index.js                        # Entry point
│   ├── App.jsx                         # Main app component
│   │
│   ├── components/                     # Reusable components
│   │   ├── Layout/
│   │   │   ├── Sidebar.jsx
│   │   │   ├── Header.jsx
│   │   │   └── MainContent.jsx
│   │   ├── Common/
│   │   │   ├── LoadingSpinner.jsx
│   │   │   ├── ErrorBoundary.jsx
│   │   │   ├── Pagination.jsx
│   │   │   └── EmptyState.jsx
│   │   ├── Orders/
│   │   │   ├── OrderCard.jsx
│   │   │   ├── OrderDetails.jsx
│   │   │   └── OrderStatus.jsx
│   │   ├── Coupons/
│   │   │   ├── CouponCard.jsx
│   │   │   └── CouponList.jsx
│   │   ├── Tickets/
│   │   │   ├── TicketForm.jsx
│   │   │   ├── TicketCard.jsx
│   │   │   └── TicketThread.jsx
│   │   └── Products/
│   │       ├── ProductCard.jsx
│   │       └── ProductGrid.jsx
│   │
│   ├── pages/                          # Page components
│   │   ├── Dashboard.jsx
│   │   ├── Orders.jsx
│   │   ├── OrderView.jsx
│   │   ├── Addresses.jsx
│   │   ├── Profile.jsx
│   │   ├── Coupons.jsx
│   │   ├── Tickets.jsx
│   │   ├── TicketView.jsx
│   │   ├── Recommendations.jsx
│   │   ├── Offers.jsx
│   │   └── RecentlyViewed.jsx
│   │
│   ├── store/                          # @wordpress/data stores
│   │   ├── index.js
│   │   ├── orders/
│   │   ├── coupons/
│   │   ├── tickets/
│   │   └── profile/
│   │
│   ├── hooks/                          # Custom React hooks
│   │   ├── useNavigation.js
│   │   ├── useOrders.js
│   │   ├── useCoupons.js
│   │   └── useTickets.js
│   │
│   ├── utils/                          # Utility functions
│   │   ├── formatters.js
│   │   └── validators.js
│   │
│   └── styles/                         # CSS files
│       ├── variables.css               # CSS custom properties
│       ├── base.css                    # Reset, typography
│       ├── components.css              # Component styles
│       ├── layout.css                  # Grid/Flexbox layouts
│       └── utilities.css               # Helper classes
│
├── build/                              # Compiled assets (git ignored)
│
├── templates/                          # PHP templates
│   ├── invoice.php                     # PDF invoice template
│   └── emails/                         # Email templates
│
└── languages/                          # Translation files
    └── advanced-customer-account.pot
```

---

## 🔌 REST API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/aca/v1/dashboard` | GET | Dashboard stats & widgets |
| `/aca/v1/recommendations` | GET | Interest-based product suggestions |
| `/aca/v1/recommendations/similar/{product_id}` | GET | Similar products |
| `/aca/v1/offers` | GET | Personalized offers & deals |
| `/aca/v1/offers/new-arrivals` | GET | New products in customer's categories |
| `/aca/v1/offers/back-in-stock` | GET | Previously viewed, now available |
| `/aca/v1/coupons` | GET | Available coupons |
| `/aca/v1/coupons/history` | GET | Used coupons |
| `/aca/v1/coupons/apply/{code}` | POST | Apply coupon to cart |
| `/aca/v1/tickets` | GET/POST | List & create tickets |
| `/aca/v1/tickets/{id}` | GET | Single ticket |
| `/aca/v1/tickets/{id}/replies` | POST | Add reply |
| `/aca/v1/orders` | GET | Customer orders |
| `/aca/v1/orders/{id}` | GET | Single order details |
| `/aca/v1/orders/{id}/reorder` | POST | Quick reorder |
| `/aca/v1/orders/{id}/notes` | GET/POST | Order notes |
| `/aca/v1/orders/{id}/invoice` | GET | PDF invoice |
| `/aca/v1/recently-viewed` | GET | Recently viewed products |
| `/aca/v1/activity` | GET | Activity log |
| `/aca/v1/profile` | GET/PUT | Profile data |
| `/aca/v1/addresses` | GET/PUT | Billing & shipping addresses |

---

## 🧠 Recommendation Engine Logic

```
Customer Interest Analysis:
1. Purchased product categories → Weight: 40%
2. Purchased product tags → Weight: 25%
3. Purchased product attributes (color, size, brand) → Weight: 20%
4. Recently viewed products → Weight: 15%

Product Matching:
- Find products in same categories not yet purchased
- Exclude already purchased products
- Prioritize by: Sale status, Rating, Stock status
- Limit: 8 products per section
```

---

## 🔒 Security Standards

### PHP Nonce Verification

```php
// Form submission
if ( ! isset( $_POST['aca_nonce'] ) || 
     ! wp_verify_nonce( sanitize_text_field( wp_unslash( $_POST['aca_nonce'] ) ), 'aca_save_settings' ) 
) {
    wp_die( esc_html__( 'Security check failed.', 'advanced-customer-account' ) );
}
```

### Data Sanitization Functions

| Input Type | Function |
|-----------|----------|
| Text | `sanitize_text_field()` |
| Textarea | `sanitize_textarea_field()` |
| Email | `sanitize_email()` |
| URL | `sanitize_url()` |
| Integer | `absint()` |
| HTML | `wp_kses_post()` |
| Key/Slug | `sanitize_key()` |

### Output Escaping Functions

| Context | Function |
|---------|----------|
| HTML | `esc_html()` |
| Attribute | `esc_attr()` |
| URL | `esc_url()` |
| Textarea | `esc_textarea()` |
| JavaScript | `esc_js()` |
| Rich HTML | `wp_kses_post()` |
| JSON | `wp_json_encode()` |

### Translation Functions

| Use Case | Function |
|----------|----------|
| Return translated | `__( 'text', 'advanced-customer-account' )` |
| Echo translated | `_e( 'text', 'advanced-customer-account' )` |
| With escape (HTML) | `esc_html__()`, `esc_html_e()` |
| With escape (attr) | `esc_attr__()`, `esc_attr_e()` |
| With context | `_x()`, `esc_html_x()` |
| Plural | `_n()` |

### REST API Security

```php
register_rest_route( 'aca/v1', '/orders', array(
    'methods'             => WP_REST_Server::READABLE,
    'callback'            => array( $this, 'get_orders' ),
    'permission_callback' => array( $this, 'check_permission' ),
    'args'                => array(
        'page' => array(
            'sanitize_callback' => 'absint',
            'default'           => 1,
        ),
    ),
) );

public function check_permission( $request ) {
    if ( ! is_user_logged_in() ) {
        return new WP_Error(
            'rest_unauthorized',
            esc_html__( 'You must be logged in.', 'advanced-customer-account' ),
            array( 'status' => 401 )
        );
    }
    return true;
}
```

---

## 🎨 CSS Architecture (No Tailwind)

### BEM Naming Convention

```css
/* Block */
.aca-dashboard {}

/* Element */
.aca-dashboard__header {}
.aca-dashboard__content {}

/* Modifier */
.aca-dashboard--loading {}
.aca-button--primary {}
```

### CSS Custom Properties

```css
:root {
    /* Colors */
    --aca-color-primary: #5304c1;
    --aca-color-primary-hover: #400692;
    --aca-color-secondary: #23282d;
    --aca-color-success: #46b450;
    --aca-color-warning: #ffb900;
    --aca-color-error: #dc3232;
    
    /* Text */
    --aca-color-text: #1e1e1e;
    --aca-color-text-muted: #757575;
    --aca-color-text-inverted: #ffffff;
    
    /* Background */
    --aca-color-bg: #ffffff;
    --aca-color-bg-alt: #f0f0f0;
    --aca-color-bg-hover: #f6f7f7;
    
    /* Border */
    --aca-color-border: #dcdcde;
    --aca-border-radius: 4px;
    --aca-border-radius-lg: 8px;
    
    /* Spacing */
    --aca-spacing-xs: 4px;
    --aca-spacing-sm: 8px;
    --aca-spacing-md: 16px;
    --aca-spacing-lg: 24px;
    --aca-spacing-xl: 32px;
    
    /* Typography */
    --aca-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
    --aca-font-size-xs: 11px;
    --aca-font-size-sm: 13px;
    --aca-font-size-md: 14px;
    --aca-font-size-lg: 16px;
    --aca-font-size-xl: 20px;
    
    /* Shadows */
    --aca-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
    --aca-shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
    
    /* Transitions */
    --aca-transition-fast: 150ms ease;
    --aca-transition-normal: 250ms ease;
}
```

### Flexbox/Grid Layouts

```css
/* Dashboard grid */
.aca-dashboard {
    display: grid;
    grid-template-columns: 250px 1fr;
    gap: var(--aca-spacing-lg);
    min-height: 100vh;
}

/* Responsive */
@media (max-width: 782px) {
    .aca-dashboard {
        grid-template-columns: 1fr;
    }
}

/* Product grid */
.aca-products-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
    gap: var(--aca-spacing-md);
}

/* Flex utilities */
.aca-flex {
    display: flex;
}

.aca-flex--center {
    align-items: center;
    justify-content: center;
}

.aca-flex--between {
    justify-content: space-between;
}

.aca-flex--column {
    flex-direction: column;
}
```

---

## 📦 package.json

```json
{
    "name": "advanced-customer-account",
    "version": "1.0.0",
    "description": "Advanced Customer Account for WooCommerce",
    "scripts": {
        "build": "wp-scripts build",
        "start": "wp-scripts start",
        "lint:js": "wp-scripts lint-js",
        "lint:css": "wp-scripts lint-style",
        "format": "wp-scripts format",
        "packages-update": "wp-scripts packages-update"
    },
    "devDependencies": {
        "@wordpress/scripts": "^31.4.0"
    },
    "dependencies": {
        "@wordpress/api-fetch": "^7.39.0",
        "@wordpress/components": "^32.1.0",
        "@wordpress/compose": "^7.39.0",
        "@wordpress/data": "^10.39.0",
        "@wordpress/element": "^6.39.0",
        "@wordpress/hooks": "^4.39.0",
        "@wordpress/i18n": "^6.12.0",
        "@wordpress/icons": "^11.6.0",
        "@wordpress/notices": "^5.39.0",
        "@wordpress/url": "^4.39.0",
        "classnames": "^2.5.1",
        "date-fns": "^3.6.0",
        "react-hook-form": "^7.54.0",
        "@hookform/resolvers": "^3.9.0",
        "zod": "^3.23.0"
    }
}
```

---

## 📋 Free vs Pro Comparison

| Feature | Free | Pro |
|---------|:----:|:---:|
| Modern Dashboard | ✅ | ✅ |
| Recommended Products | ✅ Basic | AI-Powered |
| Special Offers | ✅ | Personalized |
| New Arrivals For You | ✅ | ✅ |
| Back in Stock Display | ✅ | + Email alerts |
| My Coupons | ✅ | ✅ |
| Auto-Apply Coupon | ❌ | ✅ |
| Referral Coupons | ❌ | ✅ |
| Support Tickets (3) | ✅ | Unlimited |
| Order-Linked Tickets | ❌ | ✅ |
| Ticket Attachments | ❌ | ✅ |
| Quick Reorder | ✅ | ✅ |
| Recently Viewed | ✅ | ✅ |
| Activity Log (10) | ✅ | Full + Export |
| PDF Invoice | ✅ Basic | Custom Templates |
| Custom Endpoints (2) | ✅ | Unlimited |
| Wishlist Integration | ❌ | ✅ YITH/TI |
| 2FA Security | ❌ | ✅ |

---

## 🚀 Implementation Phases

### Phase 1 - Core (v1.0)
- [ ] Plugin bootstrap and autoloader
- [ ] React app setup with @wordpress/scripts
- [ ] Hash-based navigation
- [ ] Dashboard with stats widgets
- [ ] Orders list with details view
- [ ] Address management (billing/shipping)
- [ ] Profile editing with validation
- [ ] Basic menu customization
- [ ] Custom CSS with variables

### Phase 2 - Engagement (v1.5)
- [ ] My Coupons section with copy/apply
- [ ] Recommendation engine
- [ ] Special Offers page
- [ ] Recently Viewed products
- [ ] Quick Reorder functionality
- [ ] Activity Log (last 10)

### Phase 3 - Support (v2.0)
- [ ] Support Ticket CPT
- [ ] Ticket creation form
- [ ] Ticket replies (comments-based)
- [ ] Email notifications
- [ ] Basic PDF Invoice
- [ ] Order notes

### Phase 4 - Pro Launch (v2.5)
- [ ] Pro license system
- [ ] Advanced recommendations (AI-powered)
- [ ] Unlimited tickets + attachments
- [ ] Order-linked tickets
- [ ] Custom PDF templates
- [ ] Unlimited custom endpoints
- [ ] Wishlist integration (YITH/TI)
- [ ] Security features (2FA, login history)

---

## 💰 Revenue Strategy

| License | Price | Includes |
|---------|-------|----------|
| **Free** | $0 | Core features, community support |
| **Personal** | $59/year | 1 site, all Pro features, 1-year updates |
| **Business** | $129/year | 5 sites, priority support |
| **Agency** | $249/year | Unlimited sites, white-label |

---

## 🎯 Competitive Advantage

This free version offers what typically requires **3-4 separate paid plugins**:

1. **Coupon Display Plugin** (~$30/year) → Included
2. **Support Ticket Plugin** (~$49/year) → Included
3. **Product Recommendations** (~$40/year) → Included
4. **My Account Customizer** (~$39/year) → Included

**Total Value: ~$158/year → FREE**

---

## Notes & Decisions

- **No Wishlist Built-in**: Will integrate with external plugins (YITH, TI) in Pro version
- **Hash-based Navigation**: Using `#dashboard`, `#orders` for SPA routing (simpler than React Router)
- **@wordpress/data**: Using WP ecosystem for state management instead of external solutions
- **Custom CSS**: BEM naming with CSS custom properties, no Tailwind
- **PDF Generation**: Server-side with DOMPDF for security and consistency