apskel-pos-backend/test_voucher_api.md

# Voucher API Test Guide

## API Endpoints

### 1. Get Random Vouchers for Spin
**GET** `/api/v1/vouchers/spin`

Query Parameters:
- `limit` (optional): Number of vouchers to return (1-50, default: 10)

**Response:**
```json
{
  "message": "Success",
  "data": {
    "vouchers": [
      {
        "voucher_code": "VOUCHER001",
        "name": "John Doe",
        "phone_number": "08**1234",
        "is_winner": false
      },
      {
        "voucher_code": "VOUCHER002",
        "name": "Jane Smith",
        "phone_number": "09**5678",
        "is_winner": false
      }
    ],
    "count": 2
  }
}
```

### 2. Get Random Vouchers by Rows (UPDATED!)
**GET** `/api/v1/vouchers/rows`

Query Parameters:
- `rows` (optional): Number of rows to return (1-10, default: 4)
- `winner_number` (optional): Winner number to filter by (if not provided, defaults to 0)

**Logic:**
- If `winner_number` is provided: Randomly select from vouchers where `winner_number = provided_value` AND `is_winner = false`
- If no vouchers found for the specified `winner_number`: Fallback to `winner_number = 0` AND `is_winner = false`
- If `winner_number` is not provided: Randomly select from vouchers where `winner_number = 0` AND `is_winner = false`
- Excludes vouchers already marked as winners
- Distributes vouchers evenly across the specified number of rows
- **Automatically selects one random winner from each row and sets their `is_winner` to `true`**

**Response:**
```json
{
  "message": "Success",
  "data": {
    "rows": [
      {
        "row_number": 1,
        "vouchers": [
          {
            "voucher_code": "VOUCHER001",
            "name": "John Doe",
            "phone_number": "08**1234",
            "is_winner": true
          },
          {
            "voucher_code": "VOUCHER002",
            "name": "Jane Smith",
            "phone_number": "09**5678",
            "is_winner": false
          },
          {
            "voucher_code": "VOUCHER003",
            "name": "Bob Johnson",
            "phone_number": "08**9012",
            "is_winner": false
          }
        ]
      },
      {
        "row_number": 2,
        "vouchers": [
          {
            "voucher_code": "VOUCHER004",
            "name": "Alice Brown",
            "phone_number": "09**3456",
            "is_winner": false
          },
          {
            "voucher_code": "VOUCHER005",
            "name": "Charlie Wilson",
            "phone_number": "08**7890",
            "is_winner": true
          }
        ]
      }
    ],
    "total_rows": 2,
    "total_vouchers": 5
  }
}
```

### 3. List All Vouchers
**GET** `/api/v1/vouchers`

Query Parameters:
- `page` (optional): Page number (default: 1)
- `limit` (optional): Items per page (default: 10, max: 100)

**Response:**
```json
{
  "message": "Success",
  "data": {
    "data": [
      {
        "id": "uuid",
        "name": "John Doe",
        "email": "john@example.com",
        "phone_number": "08123456789",
        "voucher_code": "VOUCHER001",
        "winner_number": 1,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total_count": 1,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}
```

### 4. Get Voucher by ID
**GET** `/api/v1/vouchers/{id}`

**Response:**
```json
{
  "message": "Success",
  "data": {
    "id": "uuid",
    "name": "John Doe",
    "email": "john@example.com",
    "phone_number": "08123456789",
    "voucher_code": "VOUCHER001",
    "winner_number": 1,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

### 5. Get Voucher by Code
**GET** `/api/v1/vouchers/code/{code}`

**Response:**
```json
{
  "message": "Success",
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "phone_number": "08123456789",
    "voucher_code": "VOUCHER001",
    "winner_number": 1,
    "is_winner": false
  }
}
```

## Features

1. **Random Selection**: The `/spin` endpoint returns random vouchers from the database
2. **Phone Number Masking**: Phone numbers are masked for privacy (shows first 2 and last 2 digits)
3. **Pagination**: List endpoint supports pagination
4. **Authentication**: All endpoints require admin or manager role
5. **Validation**: Input validation for limit parameters

## Database Schema

```sql
CREATE TABLE vouchers (
    id BIGSERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(255) NOT NULL,
    phone_number VARCHAR(20) NOT NULL,
    voucher_code VARCHAR(50) NOT NULL,
    winner_number INT NOT NULL DEFAULT 0,
    is_winner BOOLEAN NOT NULL DEFAULT FALSE
);
```

## Usage Examples

```bash
# Get 5 random vouchers for spin
curl -X GET "http://localhost:8080/api/v1/vouchers/spin?limit=5" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get 4 rows (default) - vouchers distributed evenly across rows
curl -X GET "http://localhost:8080/api/v1/vouchers/rows" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get 3 rows - vouchers distributed evenly across 3 rows (from winner_number = 0)
curl -X GET "http://localhost:8080/api/v1/vouchers/rows?rows=3" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get 3 rows - vouchers from winner_number = 1 (fallback to winner_number = 0 if none found)
curl -X GET "http://localhost:8080/api/v1/vouchers/rows?rows=3&winner_number=1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get 3 rows - vouchers from winner_number = 5 (will fallback to winner_number = 0 if none found)
curl -X GET "http://localhost:8080/api/v1/vouchers/rows?rows=3&winner_number=5" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# List all vouchers with pagination
curl -X GET "http://localhost:8080/api/v1/vouchers?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```