2.9 KiB
2.9 KiB
Device API Specification Delta
ADDED Requirements
Requirement: Device Series ID Query Parameter
The system SHALL support filtering devices by package series ID in query parameters.
Query Parameter: series_id (number, optional)
Scenario: Filter devices by series
- WHEN admin queries devices with series_id parameter
- THEN system returns only devices associated with that package series
- AND returns empty list if no matches found
Scenario: Query without series filter
- WHEN admin queries devices without series_id parameter
- THEN system returns all devices matching other filter criteria
- AND series association is not considered
Requirement: Device Series ID Response Field
The system SHALL include package series ID in device response data.
Response Field: series_id (number | null)
- Value is package series ID if device is bound to a series
- Value is null if device has no series binding
Scenario: Display series association
- WHEN system returns device in list response
- THEN each device includes series_id field
- AND field shows current series binding or null
Scenario: Null series binding
- WHEN device has no series binding
- THEN series_id field is null
- AND device 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 Device Series Binding
The system SHALL provide an endpoint to batch set package series binding for devices.
Endpoint: PATCH /api/admin/devices/series-binding
Request Body:
{
"device_ids": [1, 2, 3],
"series_id": 123 // Changed from series_allocation_id
}
Field Definitions:
device_ids: Array of device IDs (max 500 items)series_id: Package series ID (tb_package_series.id), 0 means clear association
Response:
{
"code": 0,
"data": {
"success_count": 3,
"fail_count": 0,
"failed_items": null
}
}
Scenario: Successful batch series binding
- WHEN admin calls batch series binding API with valid device IDs and series_id
- THEN system updates series association for all valid devices
- 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 devices
- AND returns success confirmation
Scenario: Partial failure handling
- WHEN some devices in the batch cannot be updated
- THEN system processes valid devices successfully
- AND returns failed_items list with reasons for failures