fix: 回调配置, 调整信用位置, 套餐

openspec/changes/update-july-iteration-frontend-integration/design.md

@@ -20,10 +20,19 @@
 - Decision: `docs/所需接口文档` 是本变更的接口契约索引；页面 API 类型、请求参数、枚举和响应字段必须以对应模块文档为准，不从七月说明中自行扩展路径。
 - Decision: 文件类业务统一采用 `POST /api/admin/storage/upload-url` 获取预签名 URL，直传成功后仅把 `file_key` 传给批量订购或设备分配接口。
 - Decision: 批量订购、设备分配和导出均保存服务端返回的任务 ID；页面恢复时查询原任务，终态后停止轮询，不能因刷新或超时重复创建。
+- Decision: 代理钱包在线充值和平台线下代充共用 `POST /api/admin/agent-recharges`，但使用两套互斥的表单模型。在线表单只允许 `amount`、`payment_method` 和 `request_id`；线下表单才允许 `shop_id`、`payment_voucher_key` 和 `remark`，不能把线下表单对象整体复用到在线请求中。
+- Decision: 在线充值弹窗打开时先请求 `/api/admin/agent-recharges/payment-methods`，支付方式和金额上下限完全由响应驱动。金额在界面显示为元，提交前转换为整数分；支付方式为空时禁止提交并显示无可用支付方式提示。
+- Decision: 在线创建成功后只使用返回的 `recharge_id` 查询 `/api/admin/agent-recharges/{id}/payment-status`，把原始 `qr_content` 交给二维码组件。二维码弹窗可见且订单非终态时每 3 秒轮询；弹窗隐藏、页面进入后台或状态进入 3/4/5/6 后停止轮询。
+- Decision: `request_id` 是一次主动在线充值的幂等键。网络超时或断开只用同一个 ID 重试一次并复用后端返回的原订单/二维码；用户关闭弹窗后重新发起充值或改变金额/支付方式时生成新的 ID，冲突响应不得覆盖原表单或自动创建新订单。
+- Decision: 充值列表和详情均以 `recharge_source` 做业务分支，并优先展示 `recharge_source_name`。在线单展示支付方式、第三方流水和支付/完成时间；线下单展示凭证、备注、提交人和审批状态。存在企微审批来源或实例时只读展示审批进度，不显示确认/驳回操作。
+- Decision: 充值相关导出权限按场景拆分：业务列表入口使用 `agent_recharge:export`，导出任务详情使用 `export_task:agent_recharge_detail`，下载文件使用 `export_task:agent_recharge_download`。权限不足时隐藏入口或操作，不通过前端绕过权限。
 
 ## Risks / Trade-offs
 
 - 接口 DTO 若未按说明返回，页面无法可靠展示审批人、历史资产标识或新旧字段；通过联调清单阻断实现前确认。
+- 支付配置为空或二维码内容为空时，在线充值无法继续；通过动态支付方式加载、空状态和联调环境中微信/支付宝二维码内容非空校验阻断上线。
+- 在线创建请求若错误生成新的 `request_id`，可能产生重复充值单；通过提交态保存 ID、幂等重试和冲突保护降低重复支付风险。
+- `status=2` 只代表第三方已支付，不代表钱包已经入账；通过以 `status=3` 作为余额刷新条件避免提前展示到账。
 - 设备批量分配接口文档已明确任务列表和详情仅平台用户可操作，前端不得向代理账号展示任务入口或通过前端绕过权限。
 - H5/C 端不在本次实现范围，后台只能依赖后端提供的最终字段，跨端验收需要单独安排。
 - 部分接口文档只给出字段模型，缺少业务错误码、权限编码和分页默认值；这些列入待确认清单。
@@ -38,5 +47,5 @@
 ## Open Questions
 
 - 退款和代理充值详情是否需要直接返回企微审批节点人员列表？
-- 各新增后台页面和按钮的最终权限编码是什么？
+- 代理在线充值创建和查询的最终权限编码是否与现有 `agent_recharge:*` 权限保持一致；导出权限编码已由接口文档确定。
 - 批量任务、导出任务、企微审批和 Gateway 超时的稳定错误码及重试语义是什么？

openspec/changes/update-july-iteration-frontend-integration/proposal.md

@@ -7,9 +7,13 @@
 ## What Changes
 
 - 按 `00-七月迭代实现与接口对接说明.md` 更新后台管理端的接口调用和页面展示契约。
+- 按 `产品迭代7月份/000-代理钱包扫码充值接口对接说明.md` 和 `所需接口文档/000-代理钱包扫码充值接口对接.md` 补齐代理钱包在线扫码充值、线下代充和充值导出权限的前端契约。
 - 以 `docs/所需接口文档/01-店铺.md` 至 `21-设备批量分配.md` 为接口参数、响应字段、枚举、权限和错误语义的具体来源。
 - 对资产、店铺、订单、换货、套餐、资金、系列授权、审批、通知、批量任务、导出和 Gateway 相关页面补齐前端适配要求。
 - 统一使用后端返回的实名策略、支付方式、预计到期、审批状态、金额计算结果和任务状态，不在前端重复推导。
+- 代理在线充值只提交金额、动态可用支付方式和幂等 `request_id`，用后端返回的原始 `qr_content` 渲染二维码，并按充值状态轮询到帐结果。
+- 按 `recharge_source` 区分代理在线自充与平台线下代充；线下单展示凭证和审批状态，在线单隐藏线下字段和人工审批操作。
+- 补齐代理充值列表导出入口、导出任务详情和下载的权限编码。
 - 补齐 CSV 上传模板、异步任务恢复、权限按钮、错误处理和并发冲突处理要求。
 - 明确预签名上传先取 `file_key`、再调用批量业务接口的两阶段流程，并固定批量订购、设备分配和导出任务的终态处理规则。
 - **不实施 H5/C 端页面改动**，但在规格和联调清单中标注其依赖的接口及外部工作项。
@@ -18,6 +22,6 @@
 ## Impact
 
 - Affected specs: `july-iteration-frontend-integration`
-- Affected code: 后台资产、店铺、订单、换货、套餐、代理资金、系列授权、审批配置、通知、批量任务和导出页面
+- Affected code: 后台资产、店铺、订单、换货、套餐、代理充值与资金、系列授权、审批配置、通知、批量任务和导出页面；重点涉及 `src/views/finance/agent-recharge`、`src/api/modules/agentRecharge.ts` 和 `src/types/api/agentRecharge.ts`
 - External follow-up: H5/C 端认证限制、实名流程、支付按钮、C 端订单续费、C 端通知和 C 端资产展示
 - Approval gate: 接口待确认项完成前不进入大范围实现

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

@@ -191,3 +191,129 @@ The admin frontend SHALL enforce the documented permission boundary for device a
 
 - **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

openspec/changes/update-july-iteration-frontend-integration/tasks.md

@@ -54,7 +54,17 @@
 - [x] 6.3 验证代理数据隔离、平台权限、敏感字段脱敏和财务操作审计入口。
 - [ ] 6.4 完成后台页面的接口联调、权限组合、空数据、错误、并发冲突和任务恢复验收。
 
-## 7. Explicitly Out Of Scope
+## 7. Agent Wallet QR Recharge
+
+- [ ] 7.1 Extend `AgentRecharge` types and `AgentRechargeService` for `alipay`, dynamic payment methods, amount bounds, `request_id`, `qr_content`, `payment_status`, and the documented payment-status endpoint while preserving nullable fields.
+- [ ] 7.2 Add the agent online recharge dialog flow that loads `/api/admin/agent-recharges/payment-methods`, renders only returned payment methods, validates the returned fen bounds, and disables submission when no method is available.
+- [ ] 7.3 Split online and offline create payloads; submit online recharge with only `amount`, `payment_method`, and a generated `request_id`, render the returned raw `qr_content`, and prevent leakage of shop, voucher, remark, or payment configuration fields.
+- [ ] 7.4 Implement idempotent online-create retry and conflict handling: reuse the original `request_id` for one uncertain retry, generate a new ID for a new user action, and preserve the original form on request conflicts.
+- [ ] 7.5 Implement visible-dialog payment polling with a three-second interval, stop on hidden/background or terminal status, distinguish `status=2` payment success from `status=3` wallet arrival, and refresh the wallet balance/list only after completion.
+- [ ] 7.6 Update recharge list/detail branches to use `recharge_source`, document the online/offline field visibility rules, keep offline confirmation/rejection conditional on the absence of WeCom approval, and prevent online records from invoking offline operations.
+- [ ] 7.7 Apply agent recharge export permissions: `agent_recharge:export`, `export_task:agent_recharge_detail`, and `export_task:agent_recharge_download`; add focused tests for role visibility, payload exclusion, idempotent retry, polling termination, and status transitions.
+
+## 8. Explicitly Out Of Scope
 
 - H5/C 端登录限制、实名流程、支付按钮、资产详情、订单续费和 C 端通知不在本次实现任务内。
 - H5 首页隐藏设备下 ICCID 仍按最新说明标记为不做。