# Admin Seat Details Endpoint - Executive Summary

## What's Missing

Currently, the `/api/venue/availability/{eventId}` endpoint only returns:
- ✅ Seat status (available/held/booked)
- ✅ Seat price
- ❌ **No owner information** (customer name, email)
- ❌ **No order details** (order ID, payment status)
- ❌ **No timing information** (hold expiry, booking time)
- ❌ **No admin context** (shadow sold, comp tickets, admin notes)

## Proposed Solution

**New Endpoint**: `GET /api/admin/seats/{seat_id}/details`

**Authentication**: Admin JWT required

**Purpose**: Comprehensive admin-only seat information for tooltips, operations, and troubleshooting

---

## Key Data Returned

### 1. **Basic Seat Information**
- Seat ID, row, number, type, zone
- Position, accessibility, active status
- Current price and pricing history

### 2. **Reservation Status** ⭐ **CRITICAL**
- Current status (available/held/booked/shadow_sold/blocked)
- Hold details (token, session, expiry time, seconds remaining)
- Price snapshot (price at booking time vs current price)

### 3. **Owner Information** ⭐ **CRITICAL**
- Customer name, email, phone
- User ID (if registered) or guest status
- Created by admin (for comp tickets)

### 4. **Order Details** ⭐ **IMPORTANT**
- Order ID, session ID, total amount
- Order status, payment status, payment method
- Payment mode (immediate/cash/invoice/comp/shadow_sold)
- Idempotency key, timestamps

### 5. **Payment Transaction**
- Payment gateway (Stripe, PayPal, etc.)
- Transaction ID, amount, currency
- Status, initiated/completed timestamps
- Stripe customer ID, metadata

### 6. **Line Items Breakdown**
- Individual ticket line items
- Booking fees, taxes, discounts
- Per-item pricing and totals
- Seat-specific line items

### 7. **Admin Context**
- Is shadow sold / blocked / comp ticket
- Created by admin ID and notes
- Can be released / reassigned / refunded
- Available admin actions

### 8. **History** (optional, `?include_history=true`)
- Previous reservation states
- Status transitions with timestamps
- Hold tokens and session IDs

### 9. **Audit Logs** (optional, `?include_audit_logs=true`)
- Admin actions (shadow sold, releases, etc.)
- System events (bookings, payments)
- Performed by user/admin/system
- Timestamps and metadata

### 10. **Related Seats Context**
- Parent table (if table child)
- Child seats (if parent table)
- Section statistics (capacity, available, held, booked)

---

## Use Cases

### 1. **Admin Tooltip on Hover** 🎯 **PRIMARY USE CASE**
**What admin sees**:
```
Seat A1 (VIP Zone)
Status: Booked
Owner: John Doe (john.doe@example.com)
Order: #5678 - Paid (€183.25)
Booked: Oct 20, 2025 3:32 PM
```

**Data needed**: `seat`, `reservation.status`, `reservation.owner`, `order.id`, `order.total_amount`

### 2. **Seat Operations Panel**
Admin can:
- Release held seats (if expired or customer abandoned)
- Reassign booked seats (for customer service)
- Issue refunds (with line item breakdown)
- Mark as shadow sold (for comp tickets)
- Block seats (for maintenance, VIP areas)

**Data needed**: `availability`, `order`, `payment`, `line_items`

### 3. **Customer Support Investigation**
Support agent needs to:
- Verify customer payment went through
- Check if seat was accidentally double-booked
- Investigate pricing discrepancies
- Review hold/booking timeline

**Data needed**: `history`, `audit_logs`, `payment`, `reservation.pricing`

### 4. **Fire Marshal Capacity Reports**
Admin needs to:
- Count occupied seats in each section
- Identify blocked/shadow sold seats
- Generate capacity reports

**Data needed**: `seat`, `related_seats` section statistics

### 5. **Pricing Audit & Revenue Analytics**
Finance team needs to:
- Compare price at booking vs current price
- Review fee calculations and tax amounts
- Audit comp/shadow sold tickets
- Verify refund amounts

**Data needed**: `reservation.pricing`, `line_items`, `payment`

---

## Response Time & Performance

**Target**: < 300ms for basic response (without history/audit logs)

**Optimization strategies**:
1. Eager load all relationships in single query
2. Use database indexes on `seat_id`, `event_id`, `order_id`
3. Conditional loading for expensive queries (history, audit logs)
4. Short-term caching (10 seconds) for high-traffic events
5. Response compression (gzip)

**Typical query count**: 3-5 queries (with eager loading)
- 1 query: Seat with event
- 1 query: Reservation with order, payment, line items
- 1 query: Related seats section statistics
- Optional: History (1 query)
- Optional: Audit logs (1 query)

---

## Implementation Priority

### Phase 1: Core Functionality ⭐ **HIGH PRIORITY**
- [ ] Basic seat information
- [ ] Current reservation status
- [ ] Owner information (customer name, email)
- [ ] Order details (ID, status, amount)
- [ ] Availability flags (can release, can refund)

**Goal**: Enable admin tooltips with owner information

### Phase 2: Enhanced Details ⭐ **MEDIUM PRIORITY**
- [ ] Payment transaction details
- [ ] Line items breakdown
- [ ] Admin context (shadow sold, comp, notes)
- [ ] Related seats context

**Goal**: Enable seat operations panel and customer support

### Phase 3: Historical & Audit ⭐ **LOW PRIORITY**
- [ ] Reservation history
- [ ] Audit logs
- [ ] Real-time updates (WebSocket/SSE)
- [ ] Bulk seat details endpoint

**Goal**: Enable advanced troubleshooting and compliance reporting

---

## Security & Compliance

### Authentication & Authorization
- ✅ Admin JWT required (`auth.admin.jwt` middleware)
- ✅ Rate limiting (`api.rate.limit:admin`)
- ⚠️ Optional: Granular permissions (`seats.view_details`)

### Audit Logging
Every access to this endpoint is logged:
```
ADMIN_SEAT_DETAILS_ACCESS
- admin_id: 42
- seat_id: seat-A1-12345
- event_id: 123
- ip_address: 192.168.1.1
- timestamp: 2025-10-28T10:30:00Z
```

### Data Privacy
- Customer PII (email, phone) only visible to authenticated admins
- Respect GDPR anonymization flags (`orders.is_anonymized`)
- Optional: PII viewing requires `customers.view_pii` permission

---

## Next Steps

### Backend (Laravel) - `/Users/charlie/code/showprima/`
1. Create `app/Http/Controllers/API/Admin/SeatDetailsController.php`
2. Add route to `routes/api/admin/seats.php` (or create new file)
3. Implement query with eager loading
4. Add validation, error handling, logging
5. Write tests (PHPUnit)

### Frontend (Next.js) - `/Users/charlie/code/showprima-frontend/`
1. Create TypeScript interface for response
2. Add API client method in `@showprima/admin` package
3. Update seat tooltip component to call new endpoint
4. Add seat operations panel with admin actions
5. Test with various seat states

---

## Questions & Considerations

### 1. Should we include customer's full order history?
**Recommendation**: No, keep focused on single seat. Provide link to customer page if needed.

### 2. Should we include ticket PDF download link?
**Recommendation**: Yes, add in Phase 2 as `ticket.pdf_url` field.

### 3. How to handle seats that have never been reserved?
**Recommendation**: Return seat data with `reservation: null` and `availability.is_available: true`.

### 4. Should history include expired holds that were never confirmed?
**Recommendation**: Yes, useful for troubleshooting abandoned carts and hold expiry issues.

### 5. Real-time updates vs polling?
**Recommendation**: Start with polling (every 10s), add WebSocket in Phase 3 if needed.

---

## Success Metrics

**Improved Admin Experience**:
- ✅ Admins can see seat owner without clicking into order details
- ✅ Reduce time to resolve customer support tickets (target: 50% reduction)
- ✅ Eliminate need to check database directly for seat information
- ✅ Enable proactive customer service (identify issues before customer complains)

**Technical Metrics**:
- ✅ Response time < 300ms (95th percentile)
- ✅ Cache hit rate > 80% during events
- ✅ Zero N+1 query issues
- ✅ 100% test coverage for business logic

**Business Impact**:
- ✅ Faster customer support resolution
- ✅ Better seat management efficiency
- ✅ Improved admin user satisfaction
- ✅ Reduced database query load

---

## Conclusion

The proposed `GET /api/admin/seats/{seat_id}/details` endpoint will **transform admin seat management** by providing comprehensive seat context in a single API call.

**Key benefits**:
1. ✅ **Enhanced admin tooltips** with owner information
2. ✅ **Streamlined customer support** with full context
3. ✅ **Efficient seat operations** with actionable data
4. ✅ **Audit compliance** with complete history
5. ✅ **Better UX** with fewer clicks and page loads

See `ADMIN_SEAT_DETAILS_ENDPOINT_SPEC.md` for complete technical specification.