101 lines
2.9 KiB
Markdown
101 lines
2.9 KiB
Markdown
# 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**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"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
|