# API Request/Response Logging - Implementation Summary

## Problem
The `orders` table has columns for storing API request/response data (`api_request_payload`, `api_response_data`, `api_request_timestamp`, `api_response_timestamp`, `api_http_status`), but these columns were **not being populated** when orders were placed.

## Root Cause
The data flow had three missing links:

1. **DeltaBroker.placeOrder()** - Was logging API calls but not capturing the data in `OrderResultDto`
2. **OrderExecutionEngine** - Was not passing API data from `OrderResultDto` to `OrderRepository`
3. **Database Table** - Columns existed but were never populated

## Solution

### 1. Modified `DeltaBroker.placeOrder()` 
**File**: `app/Execution/Brokers/DeltaBroker.php`

**Changes**:
- Added `$apiRequestTimestamp = time()` before making API call
- Added `$apiResponseTimestamp = time()` after receiving response
- Added `$apiHttpStatus` tracking (200 for success, extracted from exception for errors)
- Modified all three `OrderResultDto` constructor calls to include API logging parameters:
  - **Success case** (lines 519-540): Passes `$requestPayload`, `$response`, timestamps, and HTTP status
  - **Mock case** (lines 567-585): Passes mock request/response data with timestamps
  - **Error case** (lines 591-620): Passes request payload and error response with timestamps

### 2. Modified `OrderExecutionEngine`
**File**: `app/Execution/Engine/OrderExecutionEngine.php`

**Changes**:
- Updated `persistLiveTrade()` method (lines 218-242):
  - Added API logging fields from `$result->apiRequest`, `$result->apiResponse`, etc.
  - Converts timestamps to MySQL DATETIME format
  
- Updated `persistRejectedTrade()` method (lines 244-268):
  - Added same API logging fields for rejected orders
  - Ensures failed orders are also fully logged

### 3. OrderRepository Already Supported It!
**File**: `app/Execution/Repository/OrderRepository.php`

The repository already had the logic to handle API logging fields (lines 24-101). It checks for these fields and includes them in the INSERT statement if present. **No changes needed here.**

## Data Flow (After Fix)

```
1. DeltaBroker.placeOrder()
   ├─ Captures: $apiRequestTimestamp
   ├─ Makes API call: POST /v2/orders
   ├─ Captures: $apiResponseTimestamp, $apiHttpStatus
   └─ Returns: OrderResultDto (with API data)
   
2. OrderExecutionEngine.executeOnBroker()
   ├─ Calls: $broker->placeOrder($order)
   ├─ Receives: OrderResultDto (with API data)
   └─ Calls: persistLiveTrade($order, $result)
   
3. OrderExecutionEngine.persistLiveTrade()
   ├─ Extracts API data from OrderResultDto
   ├─ Builds $data array with API fields
   └─ Calls: $this->repo->save($data)
   
4. OrderRepository.save()
   ├─ Checks: isset($data['api_request_payload'])
   ├─ Adds fields to INSERT statement
   └─ Saves to database: orders table
```

## What Gets Logged

### Request Payload (JSON)
```json
{
  "product_id": 27,
  "side": "sell",
  "size": 1.0,
  "order_type": "limit_order",
  "limit_price": "350.50"
}
```

### Response Data (JSON)
```json
{
  "result": {
    "id": "DELTA-ORDER-ID-1738061234-abc123",
    "product_id": 27,
    "side": "sell",
    "size": "1.0",
    "status": "filled",
    "average_fill_price": "350.50"
  }
}
```

### Timestamps
- `api_request_timestamp`: `2026-01-27 16:30:45`
- `api_response_timestamp`: `2026-01-27 16:30:46`

### HTTP Status
- `api_http_status`: `200` (or error code like `400`, `500`)

## Verification

### Check if data is being saved:
```sql
SELECT 
    id,
    symbol,
    broker_order_id,
    api_request_payload,
    api_response_data,
    api_request_timestamp,
    api_response_timestamp,
    api_http_status
FROM orders
ORDER BY created_at DESC
LIMIT 5;
```

### View formatted JSON:
```sql
SELECT 
    id,
    symbol,
    JSON_PRETTY(api_request_payload) as request,
    JSON_PRETTY(api_response_data) as response,
    api_http_status as status_code
FROM orders
WHERE api_request_payload IS NOT NULL
ORDER BY created_at DESC
LIMIT 1;
```

## Benefits

1. **Full Audit Trail**: Every API call is logged with request/response
2. **Debugging**: Easy to see exactly what was sent to broker and what was received
3. **Compliance**: Regulatory requirements for trade logging
4. **Error Analysis**: Failed orders include error details in `api_response_data`
5. **Performance Monitoring**: Timestamps show API response times

## Testing

To test the implementation:

1. **Trigger a trade** (either manually or wait for signal)
2. **Check logs**: `grep "[DELTA][ORDER]" storage/logs/*/market-data.log`
3. **Query database**: Run the verification SQL above
4. **Verify all fields are populated**

## Notes

- **Paper Trading**: API logging only works for LIVE trades (paper trades don't make real API calls)
- **Mock Mode**: When `DELTA_USE_LIVE_API=false`, mock request/response data is logged
- **Error Cases**: Even rejected orders log the request payload and error response
- **JSON Encoding**: Arrays are automatically JSON-encoded by `OrderRepository`

---

**Status**: ✅ **COMPLETE**  
**Date**: 2026-01-27  
**Files Modified**: 2 (DeltaBroker.php, OrderExecutionEngine.php)