# IoT Card Operations Specification

## ADDED Requirements

### Requirement: Query IoT Card Flow Usage

The system SHALL provide the ability to query real-time flow usage for an IoT card via its ICCID.

#### Scenario: Successfully query flow usage

- **WHEN** an authenticated user requests flow usage for a valid ICCID
- **THEN** the system returns flow usage data including used flow amount and unit

#### Scenario: Query with invalid ICCID

- **WHEN** a user requests flow usage for an invalid or non-existent ICCID
- **THEN** the system returns a 400 error with appropriate error message

### Requirement: Query IoT Card Realname Status

The system SHALL provide the ability to query the realname authentication status for an IoT card via its ICCID.

#### Scenario: Successfully query realname status

- **WHEN** an authenticated user requests realname status for a valid ICCID
- **THEN** the system returns the current realname authentication status

#### Scenario: Query status for unauthenticated user

- **WHEN** an unauthenticated user attempts to query realname status
- **THEN** the system returns a 401 unauthorized error

### Requirement: Query IoT Card Real-time Status

The system SHALL provide the ability to query the real-time operational status of an IoT card via its ICCID.

#### Scenario: Successfully query card status

- **WHEN** an authenticated user requests card status for a valid ICCID
- **THEN** the system returns card status information including ICCID and current status (准备/正常/停机)

#### Scenario: Query with unauthorized access

- **WHEN** a user without proper permissions attempts to query card status
- **THEN** the system returns a 403 forbidden error

### Requirement: Get IoT Card Realname Link

The system SHALL provide the ability to generate and retrieve a realname authentication link for an IoT card.

#### Scenario: Successfully retrieve realname link

- **WHEN** an authenticated user requests the realname link for a valid ICCID
- **THEN** the system returns an HTTPS URL that can be used for realname authentication

#### Scenario: Display realname link as QR code

- **WHEN** the system returns a realname authentication link
- **THEN** the UI displays the link as a QR code for easy mobile scanning

### Requirement: Start IoT Card (复机)

The system SHALL provide the ability to start (restore service) an IoT card via its ICCID.

#### Scenario: Successfully start a stopped card

- **WHEN** an authenticated user initiates a start operation on a stopped card
- **THEN** the system processes the request and restores card service
- **AND** displays a success message to the user

#### Scenario: Start operation with confirmation

- **WHEN** a user clicks the start card button
- **THEN** the system prompts for confirmation before executing the operation
- **AND** only proceeds if the user confirms the action

#### Scenario: Insufficient permissions for start operation

- **WHEN** a user without proper permissions attempts to start a card
- **THEN** the system returns a 403 forbidden error

### Requirement: Stop IoT Card (停机)

The system SHALL provide the ability to stop (suspend service) an IoT card via its ICCID.

#### Scenario: Successfully stop an active card

- **WHEN** an authenticated user initiates a stop operation on an active card
- **THEN** the system processes the request and suspends card service
- **AND** displays a success message to the user

#### Scenario: Stop operation with confirmation

- **WHEN** a user clicks the stop card button
- **THEN** the system prompts for confirmation before executing the operation
- **AND** only proceeds if the user confirms the action

#### Scenario: Server error during stop operation

- **WHEN** a server error occurs during the stop operation
- **THEN** the system returns a 500 error with error details
- **AND** displays an appropriate error message to the user

### Requirement: IoT Card Management UI Integration

The system SHALL integrate IoT card operations into the card management page at `/asset-management/iot-card-management`.

#### Scenario: Display primary operation button

- **WHEN** a user views the IoT card management page
- **THEN** the system displays a "查询流量使用" (Query Flow Usage) button as the primary operation

#### Scenario: Display dropdown menu for additional operations

- **WHEN** a user views the IoT card management page
- **THEN** the system displays a "更多操作" (More Operations) dropdown menu
- **AND** the dropdown contains: 查询实名状态, 查询卡状态, 获取实名链接, 启用卡片, 停用卡片

#### Scenario: Show operation results in dialog

- **WHEN** a user executes a query operation (flow, realname status, or card status)
- **THEN** the system displays results in a modal dialog with properly formatted data

### Requirement: Authentication and Authorization

The system SHALL enforce JWT-based authentication for all IoT card operations.

#### Scenario: Access with valid JWT token

- **WHEN** a user makes a request with a valid Bearer token
- **THEN** the system processes the request normally

#### Scenario: Access with expired token

- **WHEN** a user makes a request with an expired JWT token
- **THEN** the system returns a 401 unauthorized error

### Requirement: Error Handling

The system SHALL provide clear error messages for all failure scenarios.

#### Scenario: Handle 400 parameter errors

- **WHEN** a request contains invalid parameters
- **THEN** the system returns a 400 error with specific validation failure details

#### Scenario: Handle 500 server errors

- **WHEN** an internal server error occurs
- **THEN** the system returns a 500 error with error timestamp
- **AND** logs the error for debugging purposes