# Order Management Specification

## ADDED Requirements

### Requirement: Order List Display

The system SHALL display a paginated list of orders with comprehensive filtering and search capabilities.

#### Scenario: Display all orders with pagination

- **GIVEN** the user navigates to the order management page
- **WHEN** the page loads
- **THEN** the system displays a table of orders with pagination controls
- **AND** default page size is 20 items
- **AND** table shows columns: ID, order number, buyer type, buyer ID, order type, payment status, total amount, created date, and actions

#### Scenario: Filter orders by payment status

- **GIVEN** the user is on the order list page
- **WHEN** the user selects a payment status filter (pending=1, paid=2, cancelled=3, refunded=4)
- **AND** clicks the search button
- **THEN** the system displays only orders matching the selected payment status
- **AND** pagination resets to page 1

#### Scenario: Filter orders by order type

- **GIVEN** the user is on the order list page
- **WHEN** the user selects an order type filter (single_card or device)
- **AND** clicks the search button
- **THEN** the system displays only orders matching the selected order type

#### Scenario: Search by order number

- **GIVEN** the user is on the order list page
- **WHEN** the user enters an order number in the search field
- **AND** clicks the search button
- **THEN** the system performs an exact match search
- **AND** displays the matching order if found

#### Scenario: Filter by date range

- **GIVEN** the user is on the order list page
- **WHEN** the user selects a start date and/or end date
- **AND** clicks the search button
- **THEN** the system displays orders created within the specified date range

### Requirement: Order Details Viewing

The system SHALL allow users to view detailed information about each order including order items and payment information.

#### Scenario: View order details

- **GIVEN** the user is viewing the order list
- **WHEN** the user clicks the view/detail action for an order
- **THEN** the system displays comprehensive order information including:
- **AND** order basic info (order_no, order_type, buyer_id, buyer_type)
- **AND** payment info (payment_status, payment_method, paid_at, total_amount)
- **AND** order items list (package_id, package_name, quantity, unit_price, amount)
- **AND** commission info (commission_status, commission_config_version)
- **AND** timestamps (created_at, updated_at)

### Requirement: Order Cancellation

The system SHALL allow authorized users to cancel orders that are in pending payment status.

#### Scenario: Cancel a pending order

- **GIVEN** the user is viewing an order with payment_status = 1 (pending)
- **WHEN** the user clicks the cancel action
- **AND** confirms the cancellation in the confirmation dialog
- **THEN** the system sends a cancel request to POST `/api/admin/orders/{id}/cancel`
- **AND** updates the order status to cancelled (3)
- **AND** displays a success message
- **AND** refreshes the order list

#### Scenario: Cannot cancel paid order

- **GIVEN** the user is viewing an order with payment_status = 2 (paid)
- **WHEN** the cancel action is clicked
- **THEN** the system displays an error message "Cannot cancel a paid order"
- **AND** does not send the cancellation request

### Requirement: Order Creation

The system SHALL provide an interface to create orders for single card or device purchases.

#### Scenario: Create single card order

- **GIVEN** the user clicks the create order button
- **WHEN** the user selects order_type = "single_card"
- **AND** selects an IoT card (iot_card_id)
- **AND** selects one or more packages (package_ids)
- **AND** submits the form
- **THEN** the system sends a POST request to `/api/admin/orders` with the order data
- **AND** displays the newly created order details
- **AND** refreshes the order list

#### Scenario: Create device order

- **GIVEN** the user clicks the create order button
- **WHEN** the user selects order_type = "device"
- **AND** selects a device (device_id)
- **AND** selects one or more packages (package_ids, max 10)
- **AND** submits the form
- **THEN** the system creates the order
- **AND** displays a success message

### Requirement: Order Status Display

The system SHALL display order payment status and order type using color-coded badges and human-readable text.

#### Scenario: Display payment status badge

- **GIVEN** an order is displayed in the table
- **WHEN** the payment_status is 1 (pending)
- **THEN** the system displays a warning-type badge with text "待支付"
- **WHEN** the payment_status is 2 (paid)
- **THEN** the system displays a success-type badge with text "已支付"
- **WHEN** the payment_status is 3 (cancelled)
- **THEN** the system displays an info-type badge with text "已取消"
- **WHEN** the payment_status is 4 (refunded)
- **THEN** the system displays a danger-type badge with text "已退款"

#### Scenario: Display order type badge

- **GIVEN** an order is displayed in the table
- **WHEN** the order_type is "single_card"
- **THEN** the system displays text "单卡购买"
- **WHEN** the order_type is "device"
- **THEN** the system displays text "设备购买"

### Requirement: Currency Formatting

The system SHALL display monetary amounts in yuan (元) with proper formatting and conversion from cents.

#### Scenario: Format order total amount

- **GIVEN** an order has total_amount = 50000 (in cents)
- **WHEN** the order is displayed in the table
- **THEN** the system displays "¥500.00" or "500.00 元"

### Requirement: Data Refresh and Real-time Updates

The system SHALL provide manual refresh capabilities and update data after mutations.

#### Scenario: Manual refresh

- **GIVEN** the user is viewing the order list
- **WHEN** the user clicks the refresh button in the table header
- **THEN** the system reloads the current page of orders with current filters
- **AND** maintains the current pagination state

#### Scenario: Auto-refresh after order cancellation

- **GIVEN** the user successfully cancels an order
- **WHEN** the cancellation is confirmed
- **THEN** the system automatically refreshes the order list
- **AND** displays the updated order status

### Requirement: Internationalization Support

The system SHALL provide full internationalization support for order management UI in Chinese and English.

#### Scenario: Display Chinese text

- **GIVEN** the user's language is set to Chinese (zh)
- **WHEN** the order management page is viewed
- **THEN** all UI text displays in Chinese including menu titles, table headers, status labels, and messages

#### Scenario: Display English text

- **GIVEN** the user's language is set to English (en)
- **WHEN** the order management page is viewed
- **THEN** all UI text displays in English including menu titles, table headers, status labels, and messages