# IoT Card API Specification Delta

## ADDED Requirements

### Requirement: IoT Card Series ID Query Parameter

The system SHALL support filtering standalone IoT cards by package series ID in query parameters.

**Query Parameter**: `series_id` (number, optional)

#### Scenario: Filter cards by series

- **WHEN** admin queries standalone cards with series_id parameter
- **THEN** system returns only cards associated with that package series
- **AND** returns empty list if no matches found

#### Scenario: Query without series filter

- **WHEN** admin queries cards without series_id parameter
- **THEN** system returns all cards matching other filter criteria
- **AND** series association is not considered

### Requirement: IoT Card Series ID Response Field

The system SHALL include package series ID in standalone IoT card response data.

**Response Field**: `series_id` (number | null)
- Value is package series ID if card is bound to a series
- Value is null if card has no series binding

#### Scenario: Display series association

- **WHEN** system returns IoT card in list response
- **THEN** each card includes series_id field
- **AND** field shows current series binding or null

#### Scenario: Null series binding

- **WHEN** card has no series binding
- **THEN** series_id field is null
- **AND** card can still be displayed in results

## RENAMED Requirements

### API Field Renaming

- FROM: `series_allocation_id` (in batch series binding endpoints)
- TO: `series_id`

**Reason**: Field name `series_allocation_id` implied a reference to an allocation record ID, but it actually stores the package series ID directly. Renaming to `series_id` clarifies this relationship and aligns with frontend naming conventions.

## MODIFIED Requirements

### Requirement: Batch Set Card Series Binding

The system SHALL provide an endpoint to batch set package series binding for IoT cards.

**Endpoint**: `PATCH /api/admin/iot-cards/series-binding`

**Request Body**:
```json
{
  "iccids": ["898600..."],
  "series_id": 123  // Changed from series_allocation_id
}
```

**Field Definitions**:
- `iccids`: Array of ICCIDs (max 500 items)
- `series_id`: Package series ID (tb_package_series.id), 0 means clear association

**Response**:
```json
{
  "code": 0,
  "data": {
    "success_count": 100,
    "fail_count": 0,
    "failed_items": null
  }
}
```

#### Scenario: Successful batch series binding

- **WHEN** admin calls batch series binding API with valid ICCIDs and series_id
- **THEN** system updates series association for all valid cards
- **AND** returns success count and failure details

#### Scenario: Clear series association

- **WHEN** admin calls batch series binding API with series_id = 0
- **THEN** system clears series association for specified cards
- **AND** returns success confirmation

#### Scenario: Partial failure handling

- **WHEN** some cards in the batch cannot be updated
- **THEN** system processes valid cards successfully
- **AND** returns failed_items list with reasons for failures