# Ticketing System API Documentation

## Base URL
```
Development: http://localhost:8080/api
Production:  https://your-domain.com/api
```

## Authentication

Most endpoints require a Bearer token in the `Authorization` header:
```
Authorization: Bearer <accessToken>
```

Tokens can also be passed via `accessToken` httpOnly cookie.

### Roles
| Role | Description |
|------|-------------|
| `visitor` | Regular user buying tickets |
| `ticketing` | Event ticketing staff (validation, check-in) |
| `admin_event` | Event organizer/admin |
| `wali_kelas` | Teacher/class guardian |
| `super_admin` | Full system access |

---

## Endpoints

### Auth

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/auth/login` | No | Login with email/password |
| POST | `/auth/register` | No | Register new account |
| POST | `/auth/logout` | No | Logout (revoke refresh token) |
| POST | `/auth/refresh` | No | Refresh access token |
| GET | `/auth/me` | Yes | Get current user info |
| GET | `/auth/login-methods` | No | Get enabled login methods |
| POST | `/auth/forgot-password` | No | Request password reset |
| POST | `/auth/reset-password` | No | Reset password with token |
| GET | `/auth/verify-email` | No | Verify email with token |

**POST /auth/login**
```json
{
  "email": "visitor1@example.com",
  "password": "Password123!",
  "loginTarget": "buy" // optional: "buy" | "dashboard"
}
```

**POST /auth/register**
```json
{
  "email": "user@example.com",
  "password": "password123",
  "fullName": "John Doe"
}
```

### Events (Public)

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/events` | Optional | List published events |
| GET | `/events/:eventId` | No | Get event details + ticket classes |
| GET | `/events/:eventId/images` | No | Get event images |

**GET /events** query params:
- `search` - Search by name/description
- `category` - Filter by category
- `location` - Filter by venue

### Orders (Visitor)

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/orders/create-lock` | Yes | Create ticket reservation lock |
| POST | `/orders/convert` | Yes | Convert lock to order (with buyer info) |
| GET | `/orders` | Yes | List user's orders |
| GET | `/orders/:orderId` | Yes | Get order details + payment info |
| POST | `/orders/:orderId/cancel` | Yes | Cancel order |
| GET | `/orders/lock-info` | Yes | Get lock info for order |

**POST /orders/create-lock**
```json
{
  "eventId": "uuid",
  "ticketClassId": "uuid",
  "quantity": 2
}
```

**POST /orders/convert**
```json
{
  "lockId": "uuid",
  "buyerName": "John Doe",
  "buyerEmail": "john@example.com",
  "buyerPhone": "081234567890",
  "promoCode": "DISCOUNT10",
  "useDomainPromo": false
}
```

### Payments

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/payments/create` | Yes | Create Midtrans Snap payment |
| GET | `/payments/status` | Yes | Check payment status |
| POST | `/payments/webhook` | No | Midtrans webhook receiver |

**POST /payments/create**
```json
{
  "orderId": "uuid"
}
```

### Queue (Ticket War)

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/queue/enter` | Yes | Enter queue for event |
| GET | `/queue/status` | Yes | Get queue position & status |
| POST | `/queue/activate` | Yes | Activate session (user's turn) |
| POST | `/queue/test/simulate` | Yes | [DEV] Simulate queue progress |

### Tickets

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/tickets/list` | Yes | Get user's tickets |
| POST | `/tickets/generate` | Yes | Generate tickets for completed order |
| GET | `/tickets/validate` | Yes | Validate ticket by booking code |

### Promos

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/promos/validate` | Yes | Validate promo code |
| GET | `/promos/domain` | Yes | Check domain-based promo |

### Upload

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/upload` | Yes | Upload file (image) |
| GET | `/uploads/*path` | No | Serve uploaded file |

### Admin (admin_event / super_admin)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/admin/events` | List events |
| POST | `/admin/events` | Create event |
| GET | `/admin/events/:eventId` | Get event details |
| PUT | `/admin/events/:eventId` | Update event |
| POST | `/admin/events/:eventId/duplicate` | Duplicate event |
| GET/POST | `/admin/events/:eventId/ticket-classes` | Manage ticket classes |
| PUT | `/admin/events/:eventId/ticket-classes/:ticketClassId` | Update ticket class |
| DELETE | `/admin/events/:eventId/ticket-classes/:ticketClassId` | Delete ticket class |
| GET | `/admin/events/:eventId/locks` | List order locks |
| POST | `/admin/events/:eventId/locks/:lockId/release` | Release lock |
| GET | `/admin/orders` | List orders |
| GET | `/admin/orders/:orderId` | Get order detail |
| GET | `/admin/attendees` | List all attendees |
| GET | `/admin/events/:eventId/attendees` | List event attendees |
| GET | `/admin/tickets` | List tickets |
| GET | `/admin/payments` | List payments |
| POST | `/admin/payments/:paymentId/mark-paid` | Mark payment as paid |
| GET/POST | `/admin/promos` | Manage promos |
| PUT/DELETE | `/admin/promos/:promoId` | Update/delete promo |
| GET/POST | `/admin/domain-promos` | Manage domain promos |
| GET | `/admin/users` | List users |
| GET | `/admin/users/:userId` | Get user |
| GET | `/admin/settings` | Get settings |
| PUT | `/admin/settings` | Update settings |

### Super Admin

| Method | Path | Description |
|--------|------|-------------|
| GET | `/super-admin/dashboard-stats` | Dashboard statistics |
| GET | `/super-admin/events` | List all events |
| GET | `/super-admin/orders` | List all orders |
| GET | `/super-admin/orders/:orderId` | Get order detail |
| GET | `/super-admin/payments` | List all payments |
| GET | `/super-admin/tickets` | List all tickets |
| GET | `/super-admin/attendees` | List all attendees |
| GET/POST | `/super-admin/users` | List/create users |
| POST | `/super-admin/users/bulk` | Bulk create users |
| GET/DELETE | `/super-admin/users/:userId` | Get/delete user |
| POST | `/super-admin/users/import` | Import users from CSV |
| GET/POST | `/super-admin/classes` | Manage school classes |
| PUT | `/super-admin/classes/:classId` | Update class |
| GET | `/super-admin/logs` | View system logs |
| GET/PUT | `/super-admin/settings` | Manage settings |

### Wali Kelas

| Method | Path | Description |
|--------|------|-------------|
| GET | `/wali-kelas/classes` | Get assigned classes |
| GET | `/wali-kelas/events` | List available events |
| GET | `/wali-kelas/events/:eventId` | Get event details |
| GET | `/wali-kelas/students` | List assigned students |
| GET | `/wali-kelas/orders` | List student orders |
| POST | `/wali-kelas/orders/import` | Import orders from CSV |

### Cron Jobs

| Method | Path | Description |
|--------|------|-------------|
| POST | `/cron/cleanup-expired` | Clean expired locks & queue sessions |

### Health

| Method | Path | Description |
|--------|------|-------------|
| GET | `/health` | Health check (includes DB status) |

---

## Error Response Format
```json
{
  "success": false,
  "error": "Error message here"
}
```

## Success Response Format
```json
{
  "success": true,
  "data": { ... }
}
```

## Database Schema
See `migrations/001_init.sql` for the complete PostgreSQL schema.

## Environment Variables
See `.env.example` for all configuration options.