feat: 产品迭代7月份

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

@@ -0,0 +1,193 @@
+## 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}`