新增接口

openspec/specs/agent-funds-commission/spec.md

@@ -97,13 +97,38 @@
 - **WHEN** 当前账号请求资金概况列表但未提供 `shop_id`
 - **THEN** 系统继续按既有分页、数据范围、店铺名称和主账号用户名条件返回结果
 
+### Requirement: 历史待审批线下代理充值可主动接入企业微信审批
+
+系统 SHALL 提供 `POST /api/admin/agent-recharges/{id}/trigger-approval`，使具有既有代理充值管理访问权限的后台账号可为历史线下代理充值申请主动创建企业微信审批。系统 MUST 仅在线下充值记录处于待审批状态且 `approval_instance_id` 为空时创建审批；审批发起人 MUST 使用该充值记录的原创建账号。创建成功后，系统 MUST 原子保存唯一审批实例、审批提交请求及充值记录的审批实例关联，并返回更新后的充值申请审批摘要。
+
+#### Scenario: 主动发起历史线下代理充值审批成功
+
+- **GIVEN** 线下代理充值申请处于待审批状态、未关联审批实例，且其原创建账号和企业微信线下充值审批场景均可用
+- **WHEN** 有既有代理充值管理访问权限的后台账号请求 `POST /api/admin/agent-recharges/{id}/trigger-approval`
+- **THEN** 系统创建以原创建账号为发起人的唯一企业微信审批并返回审批摘要，后续由既有可靠提交流程提交至企业微信
+
+#### Scenario: 在线、非待审批或已发起记录被拒绝
+
+- **WHEN** 请求主动发起的充值记录不是线下充值、不是待审批状态或已关联审批实例
+- **THEN** 系统返回状态冲突且不创建新的审批实例或提交请求
+
+#### Scenario: 并发主动发起同一充值审批
+
+- **WHEN** 两个请求同时为同一符合条件的线下代理充值申请主动发起审批
+- **THEN** 系统至多创建一个审批实例和一个审批提交请求，未成功创建关联的请求返回冲突
+
+#### Scenario: 原创建人或审批渠道不可用
+
+- **WHEN** 充值申请原创建账号不可用，或企业微信线下充值审批场景不可用
+- **THEN** 系统返回相应错误，充值申请保持未关联审批实例，修复条件后可再次发起
+
 ## 可达操作索引
 
 本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
 
 ### 代理预充值
 
-`GET /api/admin/agent-recharges`（查询代理充值订单列表）；`POST /api/admin/agent-recharges`（创建代理充值订单）；`GET /api/admin/agent-recharges/{id}`（查询代理充值订单详情）；`POST /api/admin/agent-recharges/{id}/offline-pay`（确认线下充值）；`GET /api/admin/agent-recharges/{id}/payment-status`（查询代理充值本地支付与到账状态）；`POST /api/admin/agent-recharges/{id}/reject`（驳回代理充值订单）；`GET /api/admin/agent-recharges/payment-methods`（查询代理在线充值可用支付方式）。
+`GET /api/admin/agent-recharges`（查询代理充值订单列表）；`POST /api/admin/agent-recharges`（创建代理充值订单）；`GET /api/admin/agent-recharges/{id}`（查询代理充值订单详情）；`POST /api/admin/agent-recharges/{id}/trigger-approval`（补发历史线下代理充值审批）；`POST /api/admin/agent-recharges/{id}/offline-pay`（确认线下充值）；`GET /api/admin/agent-recharges/{id}/payment-status`（查询代理充值本地支付与到账状态）；`POST /api/admin/agent-recharges/{id}/reject`（驳回代理充值订单）；`GET /api/admin/agent-recharges/payment-methods`（查询代理在线充值可用支付方式）。
 
 ### 代理商资金管理
 

openspec/specs/order-refund-exchange/spec.md

@@ -38,6 +38,31 @@
 - **WHEN** 该代理查询退款列表或退款申请详情
 - **THEN** 系统返回空列表或不存在，且不泄露任何退款申请
 
+### Requirement: 历史待审批退款可主动接入企业微信审批
+
+系统 SHALL 提供 `POST /api/admin/refunds/{id}/trigger-approval`，使具有既有退款管理访问权限的后台账号可为历史退款申请主动创建企业微信审批。系统 MUST 仅在退款申请状态为待审批且 `approval_instance_id` 为空时创建审批；审批发起人 MUST 使用该退款申请的原创建账号。创建成功后，系统 MUST 原子保存唯一审批实例、审批提交请求及退款申请的审批实例关联，并返回更新后的退款申请审批摘要。
+
+#### Scenario: 主动发起历史退款审批成功
+
+- **GIVEN** 退款申请处于待审批状态、未关联审批实例，且其原创建账号和企业微信退款审批场景均可用
+- **WHEN** 有既有退款管理访问权限的后台账号请求 `POST /api/admin/refunds/{id}/trigger-approval`
+- **THEN** 系统创建以原创建账号为发起人的唯一企业微信审批并返回审批摘要，后续由既有可靠提交流程提交至企业微信
+
+#### Scenario: 非待审批或已发起记录被拒绝
+
+- **WHEN** 请求主动发起的退款申请不是待审批状态或已关联审批实例
+- **THEN** 系统返回状态冲突且不创建新的审批实例或提交请求
+
+#### Scenario: 并发主动发起同一退款审批
+
+- **WHEN** 两个请求同时为同一符合条件的退款申请主动发起审批
+- **THEN** 系统至多创建一个审批实例和一个审批提交请求，未成功创建关联的请求返回冲突
+
+#### Scenario: 原创建人或审批渠道不可用
+
+- **WHEN** 退款申请原创建账号不可用，或企业微信退款审批场景不可用
+- **THEN** 系统返回相应错误，退款申请保持未关联审批实例，修复条件后可再次发起
+
 ## 可达操作索引
 
 本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
@@ -48,7 +73,7 @@
 
 ### 退款管理
 
-`GET /api/admin/refunds`（退款申请列表）；`POST /api/admin/refunds`（创建退款申请）；`GET /api/admin/refunds/{id}`（退款申请详情）；`POST /api/admin/refunds/{id}/approve`（审批通过退款申请）；`POST /api/admin/refunds/{id}/reject`（审批拒绝退款申请）；`POST /api/admin/refunds/{id}/resubmit`（重新提交退款申请）；`POST /api/admin/refunds/{id}/return`（退回退款申请）。
+`GET /api/admin/refunds`（退款申请列表）；`POST /api/admin/refunds`（创建退款申请）；`GET /api/admin/refunds/{id}`（退款申请详情）；`POST /api/admin/refunds/{id}/trigger-approval`（补发历史退款审批）；`POST /api/admin/refunds/{id}/approve`（审批通过退款申请）；`POST /api/admin/refunds/{id}/reject`（审批拒绝退款申请）；`POST /api/admin/refunds/{id}/resubmit`（重新提交退款申请）；`POST /api/admin/refunds/{id}/return`（退回退款申请）。
 
 ### 换货管理