one-pipe-system/openspec/changes/update-july-iteration-frontend-integration/specs/july-iteration-frontend-integration/spec.md

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}