# Subscription Feature - Quick Reference Card

## 🚀 Getting Started (30 seconds)

```bash
# 1. Create test subscription
docker-compose exec php-apache php artisan subscriptions:setup-test --status=active

# 2. View it
docker-compose exec php-apache php artisan subscriptions:show 1 --all

# 3. Generate an order
docker-compose exec php-apache php artisan subscriptions:generate_orders --force --subscription-id=1
```

## 📋 Command Cheat Sheet

### Testing & Debugging
```bash
# Create test subscription
php artisan subscriptions:setup-test [--status=active] [--interval=weeks] [--multiplier=2]

# View subscription details
php artisan subscriptions:show <id> [--logs] [--orders] [--all]

# List all subscription commands
php artisan list subscriptions
```

### Production Operations
```bash
# Generate subscriptions from paid orders (run via cron every minute)
php artisan subscriptions:generate_from_orders

# Generate recurring orders (run via cron daily)
php artisan subscriptions:generate_orders

# Send email reminders (run via cron daily)
php artisan subscriptions:send_expiring_assessment_email
php artisan subscriptions:send_subscription_update_reminder
```

### Force Operations (Testing Only)
```bash
# Force generate order (bypass date checks)
php artisan subscriptions:generate_orders --force --subscription-id=<id>

# Simulate payment failure
php artisan subscriptions:generate_orders --force --fail --subscription-id=<id>
```

## 🌐 Browser URLs

| Area | URL |
|------|-----|
| **Member Subscriptions** | `/member/orders/subscriptions` |
| **Admin Subscriptions** | `/admin/subscriptions` |
| **Admin Logs** | `/admin/subscription-logs` |
| **Edit Subscription** | `/admin/subscriptions/edit/<id>` |
| **Mailhog (Emails)** | `http://localhost:8025` |

## ⚙️ Configuration (.env)

```bash
# Required
SUBSCRIPTIONS_ENABLED=true

# Optional (defaults shown)
SUBSCRIPTION_MAX_RESCHEDULE_DAYS=45
```

## 🗄️ Database Quick Queries

```bash
# View all subscriptions
docker-compose exec -T mariadb mysql -u pharma_admin -ppharma_password pharma_db \
  -e "SELECT id, member_id, status, next_issue_date FROM subscriptions;"

# View subscription logs
docker-compose exec -T mariadb mysql -u pharma_admin -ppharma_password pharma_db \
  -e "SELECT * FROM subscription_logs WHERE subscription_id=<ID> ORDER BY created_at DESC LIMIT 10;"
```

## 🔍 Subscription Statuses

| Status | Description | Customer Can | System Can |
|--------|-------------|--------------|------------|
| **pending** | Created, payment not received | View | Wait for payment |
| **active** | Running, orders will generate | Pause, Cancel, Update | Generate orders |
| **paused** | Temporarily stopped by customer | Reactivate, Cancel | Do nothing |
| **cancelled** | Stopped by customer | View history | Do nothing |
| **payment-failed** | Auto-payment failed | Retry payment | Retry or email |
| **expired** | Assessment or max issues reached | Renew | Do nothing |
| **completed** | All issues delivered | View history | Do nothing |

## 📊 Subscription Workflow

```
Order Placed → Order Paid → Subscription Created (pending)
                                    ↓
                            Subscription Activated (active)
                                    ↓
                            Wait for next_issue_date - 3 days
                                    ↓
                            Generate Order → Process Payment
                                    ↓
                    ┌──────────────┴──────────────┐
                Payment Success              Payment Failed
                    ↓                            ↓
            Update next_issue_date      Set status = payment-failed
            Increment count             Send email to customer
            Continue...                 Wait for retry
```

## 🧪 Common Testing Scenarios

### Test Full Customer Journey
```bash
# 1. Setup
php artisan subscriptions:setup-test --status=pending --items=2

# 2. Activate (simulating payment)
# Login to admin → Edit subscription → Change status to "active"

# 3. Generate first recurring order
php artisan subscriptions:generate_orders --force --subscription-id=<ID>

# 4. Check emails
# Open http://localhost:8025
```

### Test Member Actions
```bash
# 1. Create active subscription
php artisan subscriptions:setup-test --status=active

# 2. Login as member → /member/orders/subscriptions
# 3. Test: Pause → Reactivate → Cancel
# 4. Check logs:
php artisan subscriptions:show <ID> --logs
```

### Test Payment Failure
```bash
# 1. Create active subscription
php artisan subscriptions:setup-test --status=active

# 2. Simulate failed payment
php artisan subscriptions:generate_orders --force --fail --subscription-id=<ID>

# 3. Verify email sent (Mailhog)
# 4. Verify status changed:
php artisan subscriptions:show <ID>
```

## 🐛 Troubleshooting

| Problem | Quick Fix |
|---------|-----------|
| Commands not found | `php artisan config:clear && php artisan cache:clear` |
| Subscription not created | Run `php artisan subscriptions:generate_from_orders` |
| Order not generated | Check `next_issue_date` and `status=active` |
| Emails not sending | Check Mailhog at `http://localhost:8025` |
| Config not loading | `php artisan config:clear` |

## 📝 Code Locations

```
plugins/mtc_pharmacy_subscriptions/
├── src/
│   ├── Classes/
│   │   ├── Subscription.php              # Main model
│   │   ├── SubscriptionItem.php          # Items in subscription
│   │   ├── SubscriptionLog.php           # Audit logging
│   │   ├── SubscriptionPreference.php    # Product preferences
│   │   └── PaymentGateways/              # Payment integrations
│   ├── Console/Commands/                 # Artisan commands
│   ├── Http/Controllers/                 # Web controllers
│   ├── config/subscription.php           # Configuration
│   └── templates/                        # Twig templates
├── README.md                             # Full documentation
├── TESTING.md                            # Comprehensive testing guide
└── QUICK_REFERENCE.md                    # This file
```

## 🔗 Related Files in Main Project

```
app/Console/Kernel.php                    # Scheduled tasks
config/app.php                            # Service provider registration
sites/default/js/main-app.js              # Vue components
sites/default/templates/navigation/       # Member menu
shop/classes/class.basket.php             # Basket integration
shop/classes/class.order.php              # Order integration
```

## 📚 Documentation Links

- **[README.md](README.md)** - Complete feature documentation
- **[TESTING.md](TESTING.md)** - Comprehensive testing scenarios
- **[Configuration Options](README.md#configuration-options)** - All config settings
- **[Troubleshooting](README.md#troubleshooting)** - Common issues

## 💡 Pro Tips

1. **Always use `--force` for testing** - Bypasses timing restrictions
2. **Check Mailhog first** - All emails go there in development
3. **Use `--all` flag** - Shows everything about a subscription
4. **Member ID in logs** - Track who did what
5. **Test payment failures** - Critical error path to validate

---

**Need more details?** See [TESTING.md](TESTING.md) for comprehensive testing scenarios.
