## ADDED Requirements

### Requirement: Backend-first field semantics

The admin frontend SHALL use backend-provided business facts for real-name status, payment methods, estimated expiry, approval status, task status, balances, available amounts, debt amounts, and asset identifiers. The frontend MUST NOT infer or recalculate these values from partial data.

#### Scenario: Payment methods are displayed from the API

- **WHEN** the asset or recharge API returns `allowed_payment_methods`
- **THEN** the admin or related integration UI uses that list instead of hard-coded payment rules

#### Scenario: Financial amounts are displayed from the API

- **WHEN** a fund or credit response returns calculated balances
- **THEN** the frontend displays the returned values in fen-based data and only converts them for presentation

### Requirement: Admin asset and shop integration

The admin frontend SHALL support the confirmed July filters and fields for shops, IoT cards, devices, orders, exchanges, and assets, including contact-phone search, salesperson data, client login restriction, real-name filters, separate old/new exchange searches, asset identifiers, and estimated final expiry.

#### Scenario: Exchange assets are searched independently

- **WHEN** a user enters old and new asset search terms
- **THEN** the frontend sends `old_asset_keyword` and `new_asset_keyword` independently and preserves AND filtering semantics

#### Scenario: A shop login restriction is edited

- **WHEN** an authorized user updates a shop
- **THEN** the request includes the optional `client_login_disabled` value and the list/detail views display the returned value

### Requirement: Package allocation and series authorization

The admin frontend SHALL use the existing package and series authorization APIs for default expiry settings, override expiry settings, package multi-selection, authorization detail lookup, and package add/update/remove operations.

#### Scenario: A series authorization is edited

- **WHEN** a user opens an existing authorization
- **THEN** the frontend queries by authorization record ID, marks authorized package IDs, and keeps company cost price separate from authorization cost price

#### Scenario: Authorized packages are updated

- **WHEN** a user submits package changes
- **THEN** the frontend sends a 1–100 item `packages[]` array, uses `remove=true` for removals, and loads additional package pages when the series contains more than 100 packages

### Requirement: Credit and system configuration integration

The admin frontend SHALL integrate role default credit, shop actual credit, fund summary, and controlled system configuration APIs using fen-based amounts, server-calculated values, optimistic-lock versions, and registered configuration validation metadata.

#### Scenario: A shop credit limit update conflicts

- **WHEN** the credit update is rejected because the wallet `version` is stale
- **THEN** the frontend refreshes the latest fund summary and asks the user to retry with the latest version

#### Scenario: A configuration is read-only

- **WHEN** a configuration item is returned with `readonly=true`
- **THEN** the frontend disables its editing control and does not submit an update for that item

### Requirement: WeCom approval status integration

The admin frontend SHALL provide the confirmed WeCom configuration workflow and SHALL display business approval status as read-only for refund and offline recharge records when the approval provider is WeCom or an approval instance exists.

#### Scenario: A WeCom business record is awaiting approval

- **WHEN** a refund or offline recharge record has `approval_provider=wecom` or an `approval_instance_id`
- **THEN** the frontend displays the backend approval status and hides legacy manual approval actions

#### Scenario: A template mapping is rejected

- **WHEN** the backend rejects a scene template mapping
- **THEN** the frontend preserves the submitted form values and displays the backend validation message

### Requirement: Notifications, asynchronous tasks, exports, and Gateway controls

The admin frontend SHALL integrate low-balance notifications, expiring asset summaries, batch purchase tasks, export tasks, card speed tiers, and device allocation tasks according to the confirmed task, CSV, datasource, and timeout semantics.

#### Scenario: A batch task is restored

- **WHEN** a user reloads or re-enters a batch purchase or device allocation page
- **THEN** the frontend queries the existing task detail using the saved task identifier and does not create a duplicate task

#### Scenario: A speed tier is selected

- **WHEN** a user operates on an IoT card
- **THEN** the frontend submits a fixed speed-tier code from `-1` through `8`; a device page does not expose a speed-tier control

### Requirement: H5 and C-end work is explicitly external

The July integration specification SHALL identify H5/C-end changes as external follow-up work. This change MUST NOT modify H5/C-end pages or their API call implementations.

#### Scenario: A requirement depends on C-end behavior

- **WHEN** a requirement involves C-end login restriction, real-name flow, payment methods, asset display, order renewal, or C-end notifications
- **THEN** the item is marked as an external dependency and excluded from this change's implementation tasks

### Requirement: Permission and error boundaries

The admin frontend SHALL apply confirmed permission codes to new pages, buttons, and row actions, enforce data isolation in the UI, and present stable user-facing errors for authentication, authorization, validation, timeout, conflict, and unknown-result cases.

#### Scenario: A user lacks an action permission

- **WHEN** the current account does not have the configured permission code
- **THEN** the corresponding page action is hidden or disabled and the frontend does not invoke the API

#### Scenario: An asynchronous operation has an unknown result

- **WHEN** a task or Gateway operation times out with an unknown result
- **THEN** the frontend preserves the current data, shows a safe status message, and provides a refresh or manual verification path instead of blindly retrying

### Requirement: Documented API contract alignment

The admin frontend SHALL implement the July integration against the documented API paths and request/response contracts. The documented interface files under `docs/所需接口文档/` SHALL be treated as the source of truth for parameter names, enum values, nullable fields, pagination, permissions, and HTTP error semantics.

#### Scenario: A page loads a documented resource

- **WHEN** a July page queries or mutates a resource
- **THEN** it uses the corresponding documented `/api/admin` endpoint and sends the documented parameter names without translating them to legacy frontend names

#### Scenario: A response contains a nullable or enumerated field

- **WHEN** a documented response returns a nullable field, numeric status, string enum, or `*_name` display field
- **THEN** the frontend preserves the nullable state, uses the documented enum values, and prefers the backend display name instead of inventing a local label

#### Scenario: An API rejects a request

- **WHEN** a documented endpoint returns `400`, `401`, `403`, or `500`
- **THEN** the frontend applies the shared authentication, authorization, validation, server-error, and retry-safe handling without exposing raw transport details as the user-facing message

### Requirement: File upload and batch task contract

The admin frontend SHALL use `POST /api/admin/storage/upload-url` for file-backed July operations, upload to the returned `upload_url` with the requested content type, and pass only the returned `file_key` to the business endpoint. Batch purchase and device allocation CSVs SHALL be UTF-8 single-column files, accept an optional UTF-8 BOM, stay within 10 MB and 1000 data rows, and preserve identifiers as text.

#### Scenario: A batch purchase is submitted

- **WHEN** the user selects one package and one payment method and uploads a valid CSV
- **THEN** the frontend calls `POST /api/admin/asset-package-batch-orders` with `file_key`, `package_id`, `payment_method`, and, for offline payment, 1–5 `voucher_keys`

#### Scenario: A device allocation is submitted

- **WHEN** a platform user selects an allocation target and uploads a valid device CSV
- **THEN** the frontend calls `POST /api/admin/devices/import/allocations` with `file_key`, `operation_type` set to `assign_shop` or `assign_series`, and the selected `target_id`

#### Scenario: A batch task is resumed

- **WHEN** the page is reloaded while a task is non-terminal
- **THEN** the frontend queries the saved task ID, displays the backend `status_name` and progress/result counts, stops polling at the documented terminal state, and never creates a second task

### Requirement: WeCom configuration API workflow

The admin frontend SHALL implement the documented WeCom configuration sequence: list or save applications through `/api/admin/wecom/applications`, test the application, synchronize and query visible members, set the default creator, bind system accounts through `/api/admin/accounts/{account_id}/wecom-binding`, and save or query the two supported scene mappings.

#### Scenario: A WeCom application is configured

- **WHEN** a super administrator saves valid application credentials
- **THEN** the frontend refreshes the application, allows connection testing, and clearly distinguishes `data.success=true` for access-token acquisition from completed member, template, and callback configuration

#### Scenario: A default creator is selected

- **WHEN** the user sets a default creator
- **THEN** the frontend only submits a `userid` selected from the latest synchronized visible-member list and preserves the real local submitter in business records

#### Scenario: A scene mapping is validated

- **WHEN** the user saves `refund_approval` or `offline_recharge_approval`
- **THEN** the frontend submits `application_id`, `template_id`, `control_mapping`, and `status`, preserves input on validation failure, and displays the returned verification/status fields after success

### Requirement: Approval and financial business API contract

The admin frontend SHALL use the documented refund and agent-recharge APIs for business creation and read-only approval tracking. Amounts and voucher keys SHALL follow the documented units and cardinality, and a record with `approval_provider=wecom` or `approval_instance_id` SHALL not expose legacy manual approval actions.

#### Scenario: An offline agent recharge is created

- **WHEN** a platform user submits an offline recharge
- **THEN** the frontend calls `POST /api/admin/agent-recharges` with the target `shop_id`, amount in fen, `payment_method=offline`, and 1–5 voucher keys

#### Scenario: A refund is awaiting WeCom approval

- **WHEN** `GET /api/admin/refunds` or `GET /api/admin/refunds/{id}` returns a WeCom approval instance
- **THEN** the frontend displays `approval_status_name`, `submitter_name`, and documented amount fields as read-only and does not show approve/reject actions

#### Scenario: Approval submission has an unknown result

- **WHEN** `approval_status=8` or the documented status name indicates an unknown submission result
- **THEN** the frontend does not recreate the business record and offers refresh or manual verification instead

### Requirement: Documented device allocation permissions

The admin frontend SHALL enforce the documented permission boundary for device allocation task list and detail APIs. Because those APIs are documented as platform-only, agent and enterprise accounts SHALL not see the allocation task entry or be allowed to invoke the task list/detail endpoints from the UI.

#### Scenario: A non-platform user opens device allocation

- **WHEN** an agent or enterprise account loads the device allocation area
- **THEN** the frontend hides the entry and does not call `/api/admin/devices/import/tasks` or `/api/admin/devices/import/tasks/{id}`