fetch(modify):修复角色分配权限

openspec/changes/rename-series-allocation-id-to-series-id/specs/device-api/spec.md

@@ -0,0 +1,100 @@
+# 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