194 lines
12 KiB
Markdown
194 lines
12 KiB
Markdown
## 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}`
|