# Public Stock Order API Design

## Goal

Provide two read-only public APIs for internal systems to query approved stock order PI numbers and VIN numbers, with API Key authentication.

## Data Model

- `stock_orders.approval_status = 2` means approved
- `stock_orders.pi_no` — PI number (string)
- `stock_order_items.vin` — VIN/chassis number (string)
- `stock_order_items.model_snapshot` — car model name (plain string)
- `stock_order_items.order_id` → `stock_orders.id`

## Authentication

New middleware `ApiKeyAuth`:

- Read `Fdesk-Api-Key` header
- Compare against key stored in `.env` (`API_KEY`) or `config/app.php`
- Reject with 401 on mismatch or missing key
- Bypass both `AuthCheck` (JWT) and `BasicData` middleware

## Endpoints

### A. PI Number List

```
GET /common/public/pi/list
Headers: Fdesk-Api-Key: <key>
Query: page, page_size, pi_no (optional filter)
```

Response:
```json
{
  "status": "success",
  "code": 200,
  "data": {
    "total": 150,
    "per_page": 20,
    "current_page": 1,
    "data": [
      {
        "pi_no": "PI20250601001",
        "vins": ["LSVAU2A39N2123456", "LSVAU2A39N2123457"],
        "model_names": ["Model Y", "Model 3"]
      }
    ]
  }
}
```

Logic:
1. Query `stock_orders` where `approval_status = 2` and `pi_no IS NOT NULL` and `pi_no != ''`
2. Optional filter by `pi_no` (LIKE match)
3. Paginate
4. For each order, eager-load `items` → collect `vin` and `model_snapshot`
5. Return aggregated result

### B. VIN Number List

```
GET /common/public/vin/list
Headers: Fdesk-Api-Key: <key>
Query: page, page_size, vin (optional filter)
```

Response:
```json
{
  "status": "success",
  "code": 200,
  "data": {
    "total": 500,
    "per_page": 20,
    "current_page": 1,
    "data": [
      {
        "vin": "LSVAU2A39N2123456",
        "model_name": "Model Y"
      }
    ]
  }
}
```

Logic:
1. Query `stock_order_items` via `stock_orders` where `approval_status = 2`
2. Optional filter by `vin` (LIKE match)
3. Paginate
4. Return `vin` + `model_snapshot` per item

## File Changes

| Action | File | Description |
|--------|------|-------------|
| New | `app/middleware/ApiKeyAuth.php` | API Key auth middleware |
| New | `app/common/controller/PublicApiController.php` | Two endpoints |
| Modify | `config/route.php` | Add `/common/public/*` route group with ApiKeyAuth |

## Constraints

- Read-only, no write operations
- Only `approval_status = 2` records
- Pagination required (default page_size = 20)
- No JWT / BasicData middleware for these routes