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}

Requirement: Agent Wallet Online Recharge Contract

The admin frontend SHALL support the documented agent wallet online QR recharge flow through /api/admin/agent-recharges/payment-methods and /api/admin/agent-recharges. The available payment methods and amount limits SHALL come from the payment-methods response; the online create request SHALL contain only amount in integer fen, payment_method from the returned methods, and a required request_id. Online agent recharge requests MUST NOT send shop_id, payment_voucher_key, remark, merchant credentials, or payment configuration identifiers.

Scenario: Load available online payment methods

• WHEN an agent opens the online recharge dialog
• THEN the frontend calls GET /api/admin/agent-recharges/payment-methods
• AND it displays only the returned methods values (wechat and/or alipay)
• AND it validates the integer-fen amount against the returned min_amount and max_amount

Scenario: No online payment method is available

• WHEN the payment-methods response returns an empty methods array
• THEN the frontend hides or disables the submit action
• AND it displays that no online payment method is currently available
• AND it does not call the online create endpoint

Scenario: Create an online QR recharge

• WHEN an authorized agent submits a valid online recharge
• THEN the frontend calls POST /api/admin/agent-recharges with amount, payment_method, and request_id
• AND it converts the displayed yuan amount to an integer amount in fen before submission
• AND it uses the returned recharge_id and does not derive the target shop or wallet from user-editable form fields

Scenario: Render the returned QR content

• WHEN online recharge creation succeeds with a non-empty qr_content
• THEN the frontend passes qr_content unchanged to the QR-code component
• AND it does not parse, concatenate, replace, upload, persist, or log the QR content

Requirement: Idempotent Online Recharge Submission

The frontend SHALL preserve one request_id for the lifetime of one active online recharge submission. A timeout or network interruption MAY retry the same submission once with the same request_id, but a user-initiated new recharge MUST generate a new request ID. A conflict caused by reusing the same request ID with a different amount or payment method SHALL preserve the existing form state and require an explicit new recharge attempt.

Scenario: Retry after an uncertain create result

• WHEN the online create request times out or the network disconnects
• THEN the frontend retries at most once with the original request_id
• AND it does not create a new request_id or blindly open a second recharge dialog

Scenario: Start a new recharge after closing the dialog

• WHEN the user closes the QR dialog and clicks online recharge again
• THEN the frontend creates a new request_id
• AND the new amount and payment method are treated as a new active submission

Scenario: Reused request ID conflicts

• WHEN the backend rejects a request because the same request_id is paired with different recharge parameters
• THEN the frontend displays the backend business message
• AND it does not overwrite the original request or automatically submit another amount

Requirement: Online Payment And Wallet Arrival Polling

The online QR recharge dialog SHALL poll only the documented local payment-status endpoint GET /api/admin/agent-recharges/{id}/payment-status. While the QR dialog is visible and the recharge is non-terminal, the frontend SHALL poll at approximately three-second intervals. The frontend SHALL stop polling when the dialog is hidden, the page is not visible, or the recharge status is 3 (completed), 4 (closed), 5 (refunded), or 6 (rejected). It MUST treat status=2 as third-party payment completed but wallet arrival still processing; only status=3 permits refreshing the wallet balance and recharge list.

Scenario: Payment is waiting for the user

• WHEN payment-status returns status=1 and payment_status=0
• THEN the dialog displays that the user is waiting to scan and pay
• AND polling continues while the dialog is visible

Scenario: Payment is received but wallet arrival is processing

• WHEN payment-status returns status=2 and payment_status=1
• THEN the dialog displays payment success and wallet arrival processing
• AND the frontend does not increase or refresh the wallet balance as completed
• AND polling continues

Scenario: Wallet arrival completes

• WHEN payment-status returns status=3
• THEN the frontend displays that the recharge has arrived
• AND it stops polling
• AND it refreshes the current wallet balance and recharge list

Scenario: Online recharge reaches a terminal failure state

• WHEN payment-status returns status=4, status=5, or status=6
• THEN the frontend displays the backend status name or an appropriate failure message
• AND it stops polling without automatically creating a replacement recharge

Requirement: Recharge Source And Operation Boundaries

The recharge list and detail pages SHALL use recharge_source as the only business branch: agent_online for agent online self-recharge and platform_offline for platform offline代充. They SHALL prefer recharge_source_name for display and use the documented list filters shop_id, status, recharge_source, start_date, and end_date. Online records SHALL show payment information and payment/completion timestamps while hiding offline vouchers and manual approval operations. Offline records SHALL show vouchers, remarks, submitter, and approval status; they SHALL not show QR content or invoke the online payment-status endpoint.

Scenario: Filter online recharge records

• WHEN a user selects online recharge source or status filters
• THEN the frontend requests GET /api/admin/agent-recharges with the documented filter names and values
• AND it displays the backend recharge source name, amount, payment method, status, submitter, and timestamps

Scenario: Display a platform offline recharge

• WHEN a platform user opens a record with recharge_source=platform_offline
• THEN the detail view displays the payment voucher, remark, submitter, and approval status
• AND it does not render a QR code or start payment-status polling

Scenario: Confirm or reject an offline recharge

• WHEN a pending offline recharge has no WeCom approval provider or approval instance
• THEN an authorized platform user MAY confirm it through POST /api/admin/agent-recharges/{id}/offline-pay with operation_password
• AND an authorized platform user MAY reject it through POST /api/admin/agent-recharges/{id}/reject with a required rejection_reason of at most 500 characters

Scenario: WeCom approval controls the offline record

• WHEN an offline recharge has approval_provider=wecom or an approval_instance_id
• THEN the frontend displays approval progress as read-only
• AND it hides confirm and reject operations

Requirement: Agent Recharge Export Permissions

The agent recharge list SHALL show its export entry only with agent_recharge:export. The export-task page SHALL protect the agent_recharge detail and download operations with export_task:agent_recharge_detail and export_task:agent_recharge_download, respectively. The frontend SHALL hide unauthorized controls and SHALL NOT invoke the corresponding API as a fallback.

Scenario: An authorized user exports agent recharges

• WHEN the current account has agent_recharge:export
• THEN the agent recharge page displays the export entry and opens the agent_recharge export flow

Scenario: An unauthorized user accesses export actions

• WHEN the current account lacks an export permission
• THEN the related entry, detail action, or download action is hidden
• AND the frontend does not call the export-task detail or download endpoint