docs/agent/frontend/TICKET_DETAIL_API.md

# Ticket Detail API

## Endpoint
`GET /api/v1/tickets/{ticket_id}/detail`

## Response
```json
{
  "ticket": {
    "id": "uuid",
    "ticket_name": "Peter Otieno",
    "ticket_type": "installation",
    "service_type": "ftth",
    "work_description": "Install Standard 20Mbps for Peter Otieno",
    "status": "open",
    "priority": "normal",
    "scheduled_date": "2025-12-10",
    "scheduled_time_slot": "10:00-14:00",
    "notes": "Needs router configuration assistance",
    ...
  },
  "source_data": {
    "type": "sales_order",
    "id": "uuid",
    "order_number": "SO-2024-001",
    "customer_preferred_package": "Standard 20Mbps",
    "installation_address": "123 Main St, Nairobi",
    "preferred_visit_date": "2025-12-10",
    "status": "pending",
    "total_amount": 5000.00
  },
  "customer": {
    "id": "uuid",
    "name": "Peter Otieno",
    "phone": "+254712345678",
    "email": "peter@example.com",
    "address": "123 Main St, Apt 4B",
    "location_latitude": -1.2921,
    "location_longitude": 36.8219
  },
  "expenses": [
    {
      "id": "uuid",
      "expense_type": "transport",
      "description": "Fuel to customer site",
      "quantity": 1,
      "unit_cost": 500.00,
      "total_cost": 500.00,
      "is_approved": false,
      "approved_at": null,
      "created_at": "2025-11-27T10:00:00Z"
    }
  ],
  "images": [
    {
      "id": "uuid",
      "image_url": "https://...",
      "image_type": "before",
      "caption": "Site before installation",
      "uploaded_by_user_id": "uuid",
      "created_at": "2025-11-27T10:00:00Z"
    }
  ],
  "comments": [
    {
      "id": "uuid",
      "comment_text": "Customer confirmed availability",
      "user_id": "uuid",
      "user_name": "John Doe",
      "created_at": "2025-11-27T10:00:00Z"
    }
  ],
  "assignments": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "user_name": "Field Agent Name",
      "action": "assigned",
      "status": "PENDING",
      "assigned_at": "2025-11-27T08:00:00Z",
      "responded_at": null,
      "journey_started_at": null,
      "arrived_at": null,
      "ended_at": null
    }
  ]
}
```

## Usage

```typescript
const response = await fetch(
  `/api/v1/tickets/${ticketId}/detail`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);
const data = await response.json();

// Display ticket info
<TicketHeader ticket={data.ticket} />

// Display customer info
{data.customer && (
  <CustomerCard customer={data.customer} />
)}

// Display source data (sales order, task, incident, or subscription)
{data.source_data && (
  <>
    {data.source_data.type === 'sales_order' && (
      <SalesOrderCard order={data.source_data} />
    )}
    {data.source_data.type === 'task' && (
      <TaskCard task={data.source_data} />
    )}
    {data.source_data.type === 'incident' && (
      <IncidentCard incident={data.source_data} />
    )}
    {data.source_data.type === 'subscription' && (
      <SubscriptionCard subscription={data.source_data} />
    )}
  </>
)}

// Display expenses
<ExpensesList expenses={data.expenses} />

// Display images
<ImageGallery images={data.images} />

// Display comments
<CommentsList comments={data.comments} />

// Display assignments
<AssignmentTimeline assignments={data.assignments} />
```

## Source Data Types

### Sales Order (type: "sales_order")
```json
{
  "type": "sales_order",
  "id": "uuid",
  "order_number": "SO-2024-001",
  "customer_preferred_package": "Standard 20Mbps",
  "package_price": 5000.00,
  "installation_address": "123 Main St, Apt 4B",
  "installation_latitude": -1.2921,
  "installation_longitude": 36.8219,
  "preferred_visit_date": "2025-12-10",
  "status": "pending"
}
```

**Note:** Customer data comes from `sales_order.customer` relationship

### Task (type: "task")
```json
{
  "type": "task",
  "id": "uuid",
  "task_title": "Install fiber backbone",
  "task_description": "Install 10km fiber cable",
  "task_type": "infrastructure",
  "priority": "high",
  "status": "in_progress",
  "scheduled_date": "2025-12-10",
  "due_date": "2025-12-15"
}
```

### Incident (type: "incident")
```json
{
  "type": "incident",
  "id": "uuid",
  "incident_type": "service_outage",
  "issue_description": "No internet connection",
  "priority": "urgent",
  "status": "open",
  "reported_at": "2025-11-27T10:00:00Z",
  "created_at": "2025-11-27T10:00:00Z"
}
```

### Subscription (type: "subscription")
```json
{
  "type": "subscription",
  "id": "uuid",
  "service_type": "ftth",
  "package_name": "Premium 100Mbps",
  "status": "active",
  "monthly_fee": 5000.00,
  "start_date": "2025-01-01",
  "next_billing_date": "2025-12-01",
  "created_at": "2025-01-01T00:00:00Z"
}
```

## Notes

- `source_data` is null if no source linked
- `source_data.type` indicates the source type (sales_order, task, incident, subscription)
- `customer` is null if no customer linked (tasks don't have customers)
- Arrays are empty if no data exists
- All dates in ISO 8601 format
- Authorization: User must have access to ticket's project