# BWDK Return Trace Implementation

## PART 1 — Diagnostic Logging Added

### 1. CallbackRoute::handle() - /bwdk-callback endpoint

**File**: `src/Integrations/Digify/Routes/CallbackRoute.php`  
**Method**: `handle()`  
**Lines**: 64-78, 108-120

**Logs Added**:
- Entry point: `BWDK RETURN TRACE: HIT /bwdk-callback`
- Normalized params: `BWDK RETURN TRACE: /bwdk-callback params normalized`
- Redirect: `BWDK RETURN TRACE: /bwdk-callback redirecting to checkout`

**Source**: `bwdk_return_trace`

### 2. WooHooks::handleCancelLanding() - admin-ajax bwdk_back/bwdk_cancel

**File**: `src/Woo/WooHooks.php`  
**Method**: `handleCancelLanding()`  
**Lines**: 735-800

**Logs Added**:
- Entry point: `BWDK RETURN TRACE: HIT admin-ajax bwdk_back` or `bwdk_cancel`
- Redirect: `BWDK RETURN TRACE: admin-ajax [type] redirecting to checkout`

**Source**: `bwdk_return_trace`

### 3. WooHooks::handleReturnRedirect() - admin-ajax bwdk_back (single flow)

**File**: `src/Woo/WooHooks.php`  
**Method**: `handleReturnRedirect()`  
**Lines**: 767-800

**Logs Added**:
- Entry point: `BWDK RETURN TRACE: HIT admin-ajax bwdk_back (single flow)`
- Redirect: `BWDK RETURN TRACE: admin-ajax bwdk_back redirecting to checkout`

**Source**: `bwdk_return_trace`

---

## PART 2 — Force Redirect to Checkout

### Changes Made

#### 1. CallbackRoute::handle() - Always redirect to checkout

**File**: `src/Integrations/Digify/Routes/CallbackRoute.php`

**Two redirect points updated**:

**A) Cancelled orders redirect** (Line ~584):
- Before: Redirected to `$redirect_url` (could be cart/product/checkout)
- After: Always redirects to `wc_get_checkout_url()`
- Added: `nocache_headers()` before redirect

**B) Final redirect** (Line ~825):
- Before: Used `$order_received_url` (could be various URLs)
- After: Always redirects to `wc_get_checkout_url()`
- Fallback: `home_url('/checkout/')` if WooCommerce function not available

#### 2. WooHooks::handleCancelLanding() - Redirect to checkout

**File**: `src/Woo/WooHooks.php`

**Changes**:
- After processing order cancellation notes, always redirects to checkout
- Clears session keys: `bwdk_return_to`, `order_awaiting_payment`
- Handles edge cases:
  - No order_id → redirect to checkout
  - Order not found → redirect to checkout
- Added: `nocache_headers()` before redirect

#### 3. WooHooks::handleReturnRedirect() - Redirect to checkout (changed from product)

**File**: `src/Woo/WooHooks.php`

**Changes**:
- Before: Redirected to product page
- After: Always redirects to checkout
- Clears session keys: `bwdk_return_to`, `order_awaiting_payment`, `bwdk_last_single_pid`
- Added: `nocache_headers()` before redirect

---

## Example Log Lines

### Scenario 1: User returns via /bwdk-callback

```
BWDK RETURN TRACE: HIT /bwdk-callback - REQUEST_URI=/bwdk-callback/?order_uuid=abc-123&reason=back_from_shipping_page query_string=order_uuid=abc-123&reason=back_from_shipping_page GET_keys=["order_uuid","reason"] POST_keys=[] timestamp=2024-01-15 10:30:45

BWDK RETURN TRACE: /bwdk-callback params normalized - incoming_keys=["order_uuid","reason","phone_number"] normalized_order_uuid=abc-123 normalized_reason=back_from_shipping_page merchant_order_id=4148 timestamp=2024-01-15 10:30:45

BWDK RETURN TRACE: /bwdk-callback redirecting to checkout - order_id=4148 reason=back_from_shipping_page checkout_url=https://site.com/checkout/ timestamp=2024-01-15 10:30:45
```

### Scenario 2: User returns via admin-ajax?bwdk_back=1&oid=4148

```
BWDK RETURN TRACE: HIT admin-ajax bwdk_back - REQUEST_URI=/wp-admin/admin-ajax.php?bwdk_back=1&oid=4148 oid=4148 referer=https://digify.shop/... timestamp=2024-01-15 10:30:45

BWDK RETURN TRACE: admin-ajax bwdk_back redirecting to checkout - order_id=4148 checkout_url=https://site.com/checkout/ timestamp=2024-01-15 10:30:45
```

### Scenario 3: User returns via admin-ajax?bwdk_cancel=1&oid=4148

```
BWDK RETURN TRACE: HIT admin-ajax bwdk_cancel - REQUEST_URI=/wp-admin/admin-ajax.php?bwdk_cancel=1&oid=4148 oid=4148 referer=https://digify.shop/... timestamp=2024-01-15 10:30:45

BWDK RETURN TRACE: admin-ajax bwdk_cancel redirecting to checkout - order_id=4148 checkout_url=https://site.com/checkout/ timestamp=2024-01-15 10:30:45
```

### Scenario 4: Single product flow return

```
BWDK RETURN TRACE: HIT admin-ajax bwdk_back (single flow) - REQUEST_URI=/wp-admin/admin-ajax.php?bwdk_back=1&pid=123 pid=123 referer=https://digify.shop/... timestamp=2024-01-15 10:30:45

BWDK RETURN TRACE: admin-ajax bwdk_back redirecting to checkout - checkout_url=https://site.com/checkout/ timestamp=2024-01-15 10:30:45
```

---

## Verification Steps

1. **Check WooCommerce logs** (`wp-content/uploads/wc-logs/`):
   - Filter by source: `bwdk_return_trace`
   - Look for "HIT" entries to see which endpoint was actually called
   - Look for "redirecting to checkout" to confirm redirect happened

2. **Test scenarios**:
   - Go to Digify shipping page → press back
   - Check logs to see which endpoint was hit
   - Verify user lands on checkout page

3. **Expected behavior**:
   - All return paths should log "HIT [endpoint]"
   - All return paths should log "redirecting to checkout"
   - User should always land on checkout page

---

## Files Modified

1. **src/Integrations/Digify/Routes/CallbackRoute.php**
   - Lines 64-78: Added high-visibility entry logging
   - Lines 108-120: Added normalized params logging
   - Lines ~584: Force redirect to checkout (cancelled orders)
   - Lines ~825: Force redirect to checkout (final redirect)

2. **src/Woo/WooHooks.php**
   - Lines 735-800: Updated `handleCancelLanding()` with logging and checkout redirect
   - Lines 767-800: Updated `handleReturnRedirect()` with logging and checkout redirect (changed from product page)

---

## Safety Features

- All redirects use `wp_safe_redirect()` (validates same host)
- Fallback to `home_url('/checkout/')` if WooCommerce functions unavailable
- `nocache_headers()` prevents back-cache issues
- Session keys cleared to avoid stale state
- Logging at every decision point for debugging

---

## Result

- **Diagnostic**: Clear logs show which endpoint is hit
- **UX**: Users always redirected to checkout on return
- **No loops**: Safe redirects prevent infinite loops
- **Clean state**: Session keys cleared to prevent duplicate orders
