# Comeback Cash E2E Test Manual

This document provides manual E2E test procedures for the Comeback Cash feature.
These tests should be run against a staging environment with real database connections.

## Prerequisites

1. Deploy to staging: `./deploy.sh`
2. Run migrations: `php userfrosting/conductor migrate`
3. Have a test store configured (e.g., `ou00`) with a known API key

## T10.3.1: Store Owner Creates Sales-Side Event with Tiered Earning

### Steps:
1. Log into workspace as store owner
2. Navigate to Comeback Cash section
3. Click "Create Event"
4. Configure:
   - Name: "Test Tiered Sales Event"
   - Side: Sales
   - Earning Type: Tiered
   - Tiers:
     - $25-49.99 → $5 reward
     - $50-99.99 → $10 reward
     - $100+ → $20 reward
   - Redemption Min Purchase: $10
5. Save event
6. Activate event

### Expected Results:
- Event appears in list with status "Active"
- Only one active sales-side event allowed
- Ably notification sent (check console for `comeback_cash.event_started`)

---

## T10.3.2: Store Owner Creates Buy-Side Event (Flat, No Threshold)

### Steps:
1. Navigate to Comeback Cash section
2. Click "Create Event"
3. Configure:
   - Name: "Test Buy Event"
   - Side: Buy
   - Earning Type: Flat (only option)
   - Flat Amount: $5
   - Redemption Min Purchase: $10
4. Save and activate

### Expected Results:
- Event created with flat earning type
- Tiered/percentage options should be disabled for buy-side
- Event activates successfully

---

## T10.3.3: POS Fetches Settings and Issues Coupon

### Test: Fetch Settings

```bash
curl -X GET "https://staging.example.com/api/ou00/comeback-cash/settings" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Expected Response:
```json
{
  "success": true,
  "buy_side": {
    "active": true,
    "event_id": 1,
    "earning_type": "flat",
    "earning_flat_amount": 5.00,
    ...
  },
  "sales_side": {...},
  "version": "abc123..."
}
```

### Test: Issue Coupon (Buy-Side)

```bash
curl -X POST "https://staging.example.com/api/ou00/comeback-cash/coupons" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "side": "buy",
    "transaction_id": "TEST-BUY-001",
    "transaction_amount": 50.00,
    "customer_phone": "+15551234567"
  }'
```

### Expected Response:
```json
{
  "success": true,
  "coupon": {
    "code": "ABCD1234",
    "value": 5.00,
    "expires_at": "2025-01-05T23:59:59-06:00",
    "event_name": "Test Buy Event"
  }
}
```

### Test: Issue Coupon (Sales-Side Below Threshold)

```bash
curl -X POST "https://staging.example.com/api/ou00/comeback-cash/coupons" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "side": "sales",
    "transaction_id": "TEST-SALE-001",
    "transaction_amount": 15.00
  }'
```

### Expected Response:
```json
{
  "success": true,
  "coupon": null,
  "reason": "Amount below minimum threshold"
}
```

---

## T10.3.4: Employee Redeems Coupon via Workspace

### Steps:
1. Log into workspace as employee
2. Navigate to Comeback Cash > Redeem
3. Scan or enter coupon code: "ABCD1234"
4. Enter transaction amount: $25.00
5. Click "Redeem"

### Expected Results:
- Coupon validates successfully
- Shows coupon value and event name
- Redemption creates audit record
- Coupon status updates to "redeemed"

### API Test: POS Redemption

```bash
curl -X POST "https://staging.example.com/api/ou00/comeback-cash/redeem" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "ABCD1234",
    "transaction_id": "TEST-REDEEM-001",
    "transaction_amount": 30.00,
    "employee_id": 42
  }'
```

### Expected Response:
```json
{
  "success": true,
  "redeemed_amount": 5.00,
  "remaining_value": 0.00,
  "coupon_status": "redeemed"
}
```

---

## T10.3.5: View Redemption Report

### Steps:
1. Navigate to Comeback Cash > Reports
2. Select active event
3. View redemption statistics

### Expected Data:
- Total coupons issued
- Total coupons redeemed
- Total value issued vs redeemed
- Redemption rate percentage
- Recent redemption activity

### API Test:

```bash
curl -X GET "https://staging.example.com/ou00/api/comeback-cash/events/1/report" \
  -H "Cookie: session=YOUR_SESSION"
```

---

## Error Case Tests

### Invalid API Key
```bash
curl -X GET "https://staging.example.com/api/ou00/comeback-cash/settings" \
  -H "X-API-Key: invalid-key"
```
Expected: 401 Unauthorized

### Redeem Expired Coupon
Expected: 410 Gone with error code "EXPIRED"

### Redeem Below Min Purchase
Expected: 422 Unprocessable with error code "MIN_PURCHASE_NOT_MET"

### Redeem Already Redeemed Coupon
Expected: 409 Conflict with error code "ALREADY_REDEEMED"

---

## Verification Checklist

- [ ] Settings API returns correct active events
- [ ] Buy-side always issues coupon (no threshold)
- [ ] Sales-side respects tier thresholds
- [ ] Duplicate transaction returns existing coupon (idempotent)
- [ ] SMS queued when phone provided
- [ ] Ably broadcasts on event status changes
- [ ] Workspace redemption creates audit record
- [ ] Reports show accurate statistics
- [ ] All error codes match SDD specification