# Device Management Specification

## ADDED Requirements

### Requirement: Device List Management

The system SHALL provide a searchable device list with multi-condition filtering, pagination, and batch operations.

#### Scenario: Search devices by multiple criteria

**WHEN** an administrator enters search criteria (device number, device name, status, shop, batch number, device type, manufacturer, creation time range) **THEN** the system shall display only devices matching all specified criteria with pagination support

#### Scenario: View device list with bound card count

**WHEN** the device list is displayed **THEN** each device row shall show: ID, device number, device name, device model, device type, manufacturer, max slots, bound card count, status, shop, batch number, activation time, creation time

#### Scenario: Toggle device status

**WHEN** an administrator clicks the status switch for a device **THEN** the system shall update the device status between ENABLED and DISABLED and refresh the display

#### Scenario: Delete a device

**WHEN** an administrator clicks the delete button and confirms the deletion **THEN** the system shall delete the device and refresh the list

#### Scenario: Select multiple devices for batch operations

**WHEN** an administrator checks multiple device rows **THEN** the system shall enable batch operation buttons (Allocate, Recall) and track selected device IDs

### Requirement: Device Detail Viewing

The system SHALL display comprehensive device information including basic properties and bound SIM cards.

#### Scenario: View device basic information

**WHEN** an administrator navigates to a device detail page **THEN** the system shall display all device properties in a descriptive layout: device number, name, model, type, manufacturer, max SIM slots, status, shop, batch number, activation time, creation time

#### Scenario: View bound SIM cards with slot positions

**WHEN** viewing device details **THEN** the system shall display a table of bound cards showing: slot position (1-4), ICCID, phone number, carrier, card status, and binding time

#### Scenario: Empty slots display

**WHEN** a device has fewer than max_sim_slots cards bound **THEN** empty slot positions shall be clearly indicated with "Bind Card" action buttons

### Requirement: Device-Card Binding Management

The system SHALL allow administrators to bind and unbind SIM cards to specific device slots.

#### Scenario: Bind a card to a device slot

**WHEN** an administrator selects a card and slot position (1-4) in the binding dialog **THEN** the system shall create the binding, update the bound card count, and refresh the card list

#### Scenario: Prevent duplicate slot binding

**WHEN** an administrator attempts to bind a card to an already occupied slot **THEN** the system shall show an error message and prevent the binding

#### Scenario: Unbind a card from device

**WHEN** an administrator clicks unbind for a bound card and confirms **THEN** the system shall remove the binding, decrement the bound card count, and refresh the card list

#### Scenario: Validate slot range

**WHEN** an administrator selects a slot position **THEN** the system shall only allow values from 1 to the device's max_sim_slots value

### Requirement: Batch Device Allocation

The system SHALL support batch allocation of devices to shops with result tracking.

#### Scenario: Allocate multiple devices to a shop

**WHEN** an administrator selects multiple devices, chooses a target shop, adds optional remarks, and confirms allocation **THEN** the system shall allocate all selected devices to the shop and display success/failure results for each device

#### Scenario: Show allocation results

**WHEN** the batch allocation completes **THEN** the system shall display: total count, success count, failure count, and detailed failure reasons for each failed device

#### Scenario: Prevent allocation of already allocated devices

**WHEN** the batch allocation includes devices already allocated to a shop **THEN** the system shall show warnings for those devices but proceed with allocating unallocated devices

### Requirement: Batch Device Recall

The system SHALL support batch recall of devices from shops with result tracking.

#### Scenario: Recall multiple devices

**WHEN** an administrator selects multiple devices, adds optional remarks, and confirms recall **THEN** the system shall recall all selected devices from their shops and display success/failure results

#### Scenario: Show recall results

**WHEN** the batch recall completes **THEN** the system shall display: total count, success count, failure count, and detailed failure reasons for each failed device

#### Scenario: Prevent recall of unallocated devices

**WHEN** the batch recall includes devices not allocated to any shop **THEN** the system shall show warnings for those devices but proceed with recalling allocated devices

### Requirement: Device Import via Object Storage

The system SHALL support CSV-based device import using a three-step object storage upload process.

#### Scenario: Import devices with three-step process

**WHEN** an administrator uploads a CSV file **THEN** the system shall:

1. Get upload URL from StorageService.getUploadUrl
2. Upload file to object storage using StorageService.uploadFile
3. Call DeviceService.importDevices with the file_key **AND** display the task number for tracking

#### Scenario: Validate CSV format

**WHEN** the CSV file is uploaded **THEN** the system shall validate the presence of required columns: device_no, device_name, device_model, device_type, max_sim_slots, manufacturer

#### Scenario: Import devices with card bindings

**WHEN** the CSV includes iccid_1, iccid_2, iccid_3, iccid_4 columns **THEN** the system shall attempt to bind the specified cards to slots 1-4 respectively during import

#### Scenario: Handle import errors

**WHEN** the import process encounters errors (duplicate device_no, invalid ICCID, etc.) **THEN** the system shall record failed rows in the import task with detailed error messages

### Requirement: Import Task Management

The system SHALL track device import tasks with detailed status and record information.

#### Scenario: List import tasks with type filter

**WHEN** an administrator views the task management page **THEN** the system shall display both ICCID import tasks and Device import tasks with a type filter dropdown

#### Scenario: View device import task details

**WHEN** an administrator clicks on a device import task **THEN** the system shall display: task ID, status, total count, success count, failed count, skipped count, created time, completed time

#### Scenario: View successful import records

**WHEN** viewing a device import task detail **THEN** the system shall show a table of successfully imported devices with: device_no, device_name, bound ICCIDs

#### Scenario: View failed import records

**WHEN** viewing a device import task detail with failures **THEN** the system shall show a table of failed records with: row number, device_no, failure reason

#### Scenario: Navigate from import page to task detail

**WHEN** a device import completes successfully **THEN** the system shall display the task number with a link to view task details

## MODIFIED Requirements

### Requirement: Task Type Support

Task management SHALL support multiple task types including ICCID import and Device import with type-specific detail views.

**Previous behavior**: Task management only supported ICCID import tasks.

#### Scenario: Filter tasks by type

**WHEN** an administrator selects a task type filter (ICCID Import / Device Import) **THEN** the system shall display only tasks of the selected type

#### Scenario: Display task type badges

**WHEN** viewing the task list **THEN** each task shall display a type badge indicating whether it's an ICCID import or Device import task