更新

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

@@ -46,6 +46,33 @@
 - **WHEN** 创建对应充值
 - **THEN** 边界内请求进入既有支付流程，越界请求返回参数或业务错误
 
+### Requirement: 佣金待计算状态可恢复
+
+系统 SHALL 将已支付订单的佣金待计算状态与可靠投递事实关联；投递异常不得静默遗留为无法继续处理的待计算订单。
+
+#### Scenario: 佣金投递链路异常
+
+- **WHEN** 佣金计算任务提交或消费链路发生可恢复异常
+- **THEN** 订单维持待计算且投递状态、重试次数和失败摘要可查询，恢复投递后按既有规则得出有佣金、无佣金或待人工修正结果
+
+### Requirement: 退款佣金回扣可靠完成
+
+系统 SHALL 在退款审批生效时持久化佣金回扣请求；回扣请求的投递或处理异常不得静默遗留，且退款单在全部应回扣佣金失效并完成对应钱包流水前不得标记为已回扣。
+
+#### Scenario: 已退款订单佣金回扣失败后恢复
+
+- **WHEN** 已退款订单的佣金回扣首次处理失败或进程中断
+- **THEN** 退款单保持佣金未回扣状态并保留可重试事实，后续成功处理后佣金记录失效、佣金钱包按既有规则扣减且退款单标记为已回扣
+
+### Requirement: 退款后处理可补偿
+
+系统 SHALL 对已退款但佣金未回扣或资产未完成后处理的退款单提供幂等补偿；重复补偿不得重复扣减佣金钱包、重复写回扣流水或重复处理资产。
+
+#### Scenario: 遗留退款单补偿
+
+- **WHEN** 补偿流程发现已退款且 `commission_deducted=false` 的退款单
+- **THEN** 系统恢复该退款单的唯一后处理请求，并在既有回扣成功后更新其回扣完成标记
+
 ## 可达操作索引
 
 本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
@@ -65,3 +92,30 @@
 ### 提现配置管理
 
 `GET /api/admin/commission/withdrawal-settings`（提现配置列表）；`POST /api/admin/commission/withdrawal-settings`（新增提现配置）；`GET /api/admin/commission/withdrawal-settings/current`（获取当前生效的提现配置）。
+
+### Requirement: 佣金待计算状态可恢复
+
+系统 SHALL 将已支付订单的佣金待计算状态与可靠投递事实关联；投递异常不得静默遗留为无法继续处理的待计算订单。
+
+#### Scenario: 佣金投递链路异常
+
+- **WHEN** 佣金计算任务提交或消费链路发生可恢复异常
+- **THEN** 订单维持待计算且投递状态、重试次数和失败摘要可查询，恢复投递后按既有规则得出有佣金、无佣金或待人工修正结果
+
+### Requirement: 退款佣金回扣可靠完成
+
+系统 SHALL 在退款审批生效时持久化佣金回扣请求；回扣请求的投递或处理异常不得静默遗留，且退款单在全部应回扣佣金失效并完成对应钱包流水前不得标记为已回扣。
+
+#### Scenario: 已退款订单佣金回扣失败后恢复
+
+- **WHEN** 已退款订单的佣金回扣首次处理失败或进程中断
+- **THEN** 退款单保持佣金未回扣状态并保留可重试事实，后续成功处理后佣金记录失效、佣金钱包按既有规则扣减且退款单标记为已回扣
+
+### Requirement: 退款后处理可补偿
+
+系统 SHALL 对已退款但佣金未回扣或资产未完成后处理的退款单提供幂等补偿；重复补偿不得重复扣减佣金钱包、重复写回扣流水或重复处理资产。
+
+#### Scenario: 遗留退款单补偿
+
+- **WHEN** 补偿流程发现已退款且 `commission_deducted=false` 的退款单
+- **THEN** 系统恢复该退款单的唯一后处理请求，并在既有回扣成功后更新其回扣完成标记

openspec/specs/order-commission-delivery/spec.md

@@ -0,0 +1,34 @@
+# 订单佣金可靠投递当前行为
+
+## Purpose
+
+保证已支付订单的佣金计算请求具有可追踪的可靠投递与幂等补偿能力，避免短暂异步故障导致佣金永久遗漏。
+
+## Requirements
+
+### Requirement: 已支付订单佣金计算可靠投递
+
+系统 SHALL 在已支付订单的资金、订单状态和套餐激活事实提交时，持久化唯一的佣金计算投递事实；该事实须在首次投递失败后按既有可靠投递机制重试，并保存当前状态与最后失败摘要。
+
+#### Scenario: 首次投递失败后恢复
+
+- **WHEN** 佣金计算首次未能提交给异步消费者
+- **THEN** 订单保持待计算，持久化投递事实保留待重试状态，后续成功投递后订单进入既有佣金计算流程
+
+### Requirement: 佣金计算重复投递幂等
+
+系统 SHALL 容忍同一订单的佣金计算事件被重复投递、重复消费或由补偿流程再次请求，且不得创建重复佣金记录或重复增加佣金钱包余额。
+
+#### Scenario: 重复消费同一订单
+
+- **WHEN** 已完成佣金计算的订单再次收到佣金计算请求
+- **THEN** 系统不新增佣金记录、不改变佣金钱包余额，并保留该订单既有佣金结果
+
+### Requirement: 待计算订单可补偿
+
+系统 SHALL 对已支付且仍处于佣金待计算状态、但缺少可投递事实或投递超过重试上限的订单提供幂等补偿；补偿结果须能区分已补发、无需补发和补发失败。
+
+#### Scenario: 历史待计算订单补偿
+
+- **WHEN** 补偿流程发现已支付且长期待计算的订单
+- **THEN** 系统为该订单建立或恢复唯一投递事实，并使其重新进入佣金计算流程而不重复发放佣金