one-pipe-system/openspec/changes/update-agent-self-recharge-and-offline-approval/specs/agent-recharge/spec.md

ADDED Requirements

Requirement: 代理在线自充可用收款方式

前端 SHALL 通过 GET /api/admin/agent-self-recharge-payment-methods 获取代理在线自充的可用支付方式与金额范围，并在该接口返回空 methods 时禁止创建在线充值单。

Scenario: 读取可用支付方式

• WHEN 平台账号或代理账号进入代理充值页面并打开在线充值弹窗
• THEN 前端 MUST 调用 GET /api/admin/agent-self-recharge-payment-methods
• AND 前端 MUST 使用响应 methods 渲染可选的微信与支付宝方式
• AND 前端 MUST 使用响应 min_amount 与 max_amount 作为金额上下限
• AND 前端 MUST NOT 再调用 GET /api/admin/agent-recharges/payment-methods

Scenario: 可用方式为空

• GIVEN GET /api/admin/agent-self-recharge-payment-methods 返回空 methods
• WHEN 用户打开在线充值弹窗
• THEN 前端 MUST 提示「当前暂无可用的在线支付方式」
• AND 前端 MUST 禁用在线充值提交
• AND 前端 MUST NOT 解释为空的原因是被允许范围限制还是无可用商户
• AND 前端 MUST NOT 因空列表报错或阻断页面其余功能

Scenario: 超级管理员不通过该接口读取允许范围

• WHEN 当前登录账号为超级管理员
• THEN 前端 MUST NOT 为读取允许范围调用 GET /api/admin/agent-self-recharge-payment-methods
• AND 前端 MUST 统一处理该接口对超级管理员返回的 403

Scenario: 允许范围变更不影响存量待支付单

• WHEN 允许范围配置发生变更
• THEN 前端 MUST NOT 刷新或改写已创建待支付充值单的支付方式与商户信息

Requirement: 线下预存款申请字段

线下预存款创建请求 SHALL 在 payment_method 为 offline 时提交 offline_payment_method_id、external_transaction_no 与可选的 other_voucher_key，并与既有的 payment_voucher_key 分开提交。

Scenario: 提交线下预存款申请

• GIVEN 用户以平台账号或超级管理员身份打开线下代充弹窗
• WHEN 用户提交申请
• THEN 请求体 MUST 包含 amount、payment_method 为 offline 与 shop_id
• AND MUST 包含必填 offline_payment_method_id，取值来自 GET /api/admin/employee-collection-payment-methods 的启用项
• AND MUST 包含必填 external_transaction_no
• AND MUST 包含至少 1 个 payment_voucher_key
• AND MAY 包含最多 5 个 other_voucher_key

Scenario: 支付凭证与其他凭证分开提交

• WHEN 用户上传支付凭证与其他凭证
• THEN 支付凭证 MUST 通过 payment_voucher_key 提交
• AND 其他凭证 MUST 通过 other_voucher_key 提交
• AND 前端 MUST NOT 将两类凭证合并到同一字段

Scenario: 交易流水号与在线交易号互不覆盖

• WHEN 前端提交或展示线下预存款申请
• THEN external_transaction_no MUST 只作为线下人工申报的交易流水号
• AND 前端 MUST NOT 用 payment_transaction_id 覆盖或替代 external_transaction_no
• AND 前端 MUST NOT 对 external_transaction_no 做重复性校验

Requirement: 付款凭证交易流水号识别预填

前端 SHALL 通过 POST /api/admin/agent-recharges/payment-voucher-ocr 以已上传的付款凭证对象键换取交易流水号预填值，识别失败 MUST NOT 阻断人工填写与提交。

Scenario: 识别成功预填交易流水号

• GIVEN 线下代充弹窗已上传至少 1 个付款凭证
• WHEN 用户点击识别凭证
• THEN 前端 MUST 调用 POST /api/admin/agent-recharges/payment-voucher-ocr，请求体为 { payment_voucher_key }
• AND 前端 MUST 将响应 external_transaction_no 写入交易流水号输入框
• AND 交易流水号输入框 MUST 保持可编辑并提示用户对照凭证核对

Scenario: 识别失败不阻断提交

• GIVEN OCR 返回失败，包括凭证不是图片、对象不存在或识别服务异常
• WHEN 用户点击识别凭证
• THEN 前端 MUST 展示失败提示
• AND 前端 MUST NOT 阻断用户手动填写交易流水号并提交
• AND 前端 MUST NOT 清空用户已填写内容

Scenario: 识别请求展示加载态并使用足够超时

• WHEN 前端发起 OCR 请求
• THEN 前端 MUST 在请求期间展示 loading 并防止重复提交
• AND 请求超时 MUST NOT 低于 30 秒

Scenario: 只预填交易流水号

• WHEN OCR 识别成功
• THEN 前端 MUST 只预填 external_transaction_no
• AND 前端 MUST NOT 预填金额、付款人、付款时间或备注

Requirement: 代理充值交易流水号与收款方式展示

代理充值列表与详情 SHALL 展示线下预存款的 external_transaction_no 与收款方式快照，在线充值只展示 payment_transaction_id。

Scenario: 列表展示线下补充字段

• WHEN 列表返回 payment_method 为 offline 的充值单
• THEN 列表 MUST 展示 external_transaction_no
• AND 列表 MUST 使用 offline_payment_method_name 展示收款方式

Scenario: 详情展示收款方式快照

• WHEN 详情返回历史线下充值单
• THEN 前端 MUST 使用 offline_payment_method_code 与 offline_payment_method_name 展示收款方式
• AND 前端 MUST NOT 用 offline_payment_method_id 反查字典当前值
• AND 前端 MUST 展示 other_voucher_key 对应的其他凭证

Scenario: 两类交易号独立展示

• WHEN 详情展示在线充值单
• THEN 前端 MUST 只展示 payment_transaction_id
• AND 前端 MUST NOT 把 external_transaction_no 当作在线渠道交易号展示

Scenario: 列表不新增交易流水号筛选

• WHEN 前端实现代理充值列表筛选
• THEN 前端 MUST 只使用 page、page_size、shop_id、status、recharge_source、start_date 与 end_date
• AND 前端 MUST NOT 新增交易流水号筛选条件

Requirement: 付款凭证上传类型声明

代理充值付款凭证与其他凭证在获取上传地址时 SHALL 显式声明 content_type 为 image/jpeg。

Scenario: 上传地址声明图片类型

• WHEN 前端为代理充值线下凭证请求上传地址
• THEN 请求 MUST 携带 content_type 为 image/jpeg
• AND 上传请求 MUST 使用相同的内容类型