one-pipe-system/openspec/changes/rename-series-allocation-id-to-series-id/specs/iot-card-api/spec.md

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:

{
  "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:

{
  "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