update

openspec/changes/add-refund-methods-and-original-route-refunds/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-31

openspec/changes/add-refund-methods-and-original-route-refunds/design.md

@@ -0,0 +1,38 @@
+## Context
+
+退款服务已有申请、企业微信审批和钱包审计路径，但现有状态/人工入口不足以表达渠道退款未知结果。支付商户池 Change 完成后，新支付单可读取冻结实际商户；历史单继续走旧支付配置。
+
+## Decisions
+
+- 退款单新增方式、冻结实收金额、套餐使用/材料快照、渠道退款状态/流水/安全失败原因和审批实例历史；金额均为分。
+- 创建、审批消费和渠道执行使用同一退款单锁及条件状态更新。一笔订单的活动退款唯一约束防止并发重复；渠道请求使用稳定请求标识，结果未知进入恢复任务而非重发。
+- 企业微信通过事务内完成套餐失效与钱包退款准备；原路渠道调用使用可靠事件，成功回写退款终态。客户收款信息退款以企微通过终态完成。
+- 移除/拒绝本地人工终审语义，保留历史兼容读取；未成功重提始终冻结新实例快照。
+
+## 行为契约
+
+### 退款申请与重提
+
+- `POST /refunds`：调用者必须在订单数据范围内。服务锁定订单和既有活动退款，读取订单或原成功支付记录的权威实收金额；缺失、非正或已存在审批中/原路处理中/原路失败申请时拒绝。请求包含退款原因、退款方式、退款金额、客户收款信息及附件（仅客户收款信息方式）；金额为正分且不超过冻结实收金额。
+- 服务按实际支付方式生成可选方式：微信/支付宝线上支付为原路或客户收款信息，资产钱包/代理主钱包仅原钱包，后台线下/员工代收仅客户收款信息；不匹配的方式返回“该订单不支持此退款方式”。客户收款信息与至少一个凭证附件必须同时存在，且不读取员工收款方式字典。
+- `PUT /refunds/:id` 或既有重提入口只允许驳回、关闭或渠道明确失败的未成功申请；重新锁定订单和申请，保存新的原因、方式、金额、收款信息、附件和套餐使用快照，创建新的企业微信审批实例。提交失败或审批未知不是可重提状态；已成功、审批中、原路处理中返回状态冲突。
+
+### 企业微信终审与权益处理
+
+- 回调和既有审批恢复任务以审批实例 ID 进入同一幂等用例；移除新业务的本地人工通过、拒绝和退回终审路径，历史接口仅保留兼容读取或明确拒绝。
+- 首次最终通过时锁定退款和订单，校验批准金额不超过冻结实收金额；在事务中标记审批通过、使关联套餐失效、接续下一套餐、评估停机并建立退款执行事实。重复/乱序回调不得再次失效套餐或启动第二次渠道退款。
+- 客户收款信息方式在企业微信通过时标记退款成功；原钱包方式沿用原钱包退款事务；原路方式只写待执行可靠事件，不能在审批事务中假定渠道已成功。
+
+### 原路执行与恢复
+
+- 原路执行消费者在调用前锁定退款，验证原支付单、实际收款商户、渠道流水、可退金额和当前商户退款凭证。新支付按冻结 `merchant_id` 加载商户当前凭证，历史支付按 `payment_config_id`；商户停用不阻断历史校验。
+- 以退款 ID/稳定渠道请求号至多提交一次可确认请求。渠道明确成功时保存渠道退款流水并转退款成功；超时、未知、凭证失效、余额不足、拒绝均写安全原因并保持处理中或失败恢复状态，不得标记成功或盲目再次调用。
+- 原路失败后若改为客户收款信息退款，必须修改申请材料并走新企业微信审批；审批通过后撤销只记录审批异常，不恢复套餐权益、不取消已提交渠道退款且不自动重提。
+
+### 读取与审计
+
+- 退款列表、详情和导出返回冻结实收金额、方式、申请/渠道状态、失败安全摘要、审批实例和渠道流水，并按既有订单数据范围过滤。审计记录申请、重提、审批终态、权益处理、渠道调用和恢复，但不得记录凭证内容、完整收款文本或商户密钥。
+
+## Migration Plan
+
+新增成对迁移和活动退款约束，先部署兼容读写与恢复消费者，再关闭人工审批入口；隔离库验证方式矩阵、重复回调、渠道未知、失败重提、权益时点和 up/down/up。

openspec/changes/add-refund-methods-and-original-route-refunds/proposal.md

@@ -0,0 +1,28 @@
+## Scope
+
+- 迭代编号：`AUG26-006`。
+
+## Why
+
+现有退款以本地审批状态处理，不能按来源实际支付事实决定退款方式、冻结实收金额，或在企业微信通过后用原实际收款商户可靠执行原路退款。
+
+## What Changes
+
+- 退款申请冻结来源订单、权威实收金额、唯一套餐使用情况、退款金额/原因、方式和当次审批材料；实收金额不可由提交人修改。
+- 建立线上支付、资产钱包、代理主钱包和后台线下订单的退款方式矩阵，并在创建、提交和执行前重复校验。
+- 企业微信是唯一审批终审：通过即按既有规则失效套餐；客户收款信息退款即完成，原路退款须待渠道明确成功才完成。
+- 原路退款固定使用原支付单实际商户和渠道流水；超时/未知/失败保留可恢复状态，不重复退款；未成功申请可按规则修改并新建审批实例重提。
+
+## Capabilities
+
+### New Capabilities
+
+- 无。
+
+### Modified Capabilities
+
+- `order-refund-exchange`: 退款申请、状态机、方式矩阵和套餐联动。
+
+## Impact
+
+影响退款模型/接口、企业微信审批、支付商户与渠道退款、资产/代理钱包、员工账单和佣金回溯；需新增成对迁移并淘汰本地人工终审入口。

openspec/changes/add-refund-methods-and-original-route-refunds/specs/order-refund-exchange/spec.md

@@ -0,0 +1,32 @@
+## ADDED Requirements
+
+### Requirement: 退款实收金额与方式矩阵
+系统 SHALL 从来源订单或原成功支付记录带出并冻结权威实收金额，提交人不得填写或修改；无法确定时拒绝申请。退款金额和企业微信授权金额不得超过该冻结额，且一笔订单最多一张最终成功退款申请，成功后不得再申请。
+
+线上微信/支付宝套餐订单仅可选原路退款或客户收款信息退款；资产钱包支付仅自动退回原资产钱包；代理预存款/主钱包支付仅自动退回原代理钱包；后台线下/员工代收套餐订单仅可选客户收款信息退款。代理充值预存款业务单不在本期退款范围。客户收款信息退款必须包含客户收款信息自由文本和客户凭证附件，且不得复用公司收款方式字典。
+
+#### Scenario: 无权威实收金额
+- **WHEN** 来源订单无法取得权威实收金额
+- **THEN** 系统拒绝创建退款申请，不允许提交人以自填金额替代
+
+#### Scenario: 钱包订单申请退款
+- **WHEN** 已支付套餐订单的实际支付方式为资产钱包或代理主钱包
+- **THEN** 系统只提供退回对应原钱包方式，不展示原路或客户收款信息退款
+
+### Requirement: 企业微信审批和未成功重提
+退款申请 SHALL 保存退款原因、冻结实收金额、唯一关联套餐及其使用情况、方式、金额和当次材料快照。超级管理员、平台用户和代理可在各自订单数据范围内创建、修改并重提未成功申请；企业微信是唯一终审，本地不得人工通过、拒绝或退回。
+
+同一订单同时至多存在一张审批中、原路处理中或原路失败申请。企业微信驳回、申请关闭或渠道明确失败后可修改未成功申请的金额、原因、方式、收款信息和附件并重提；每次必须新建审批实例及快照。提交失败或审批结果未知保持在途，使用既有查询/恢复闭环，不得另建或重提。企业微信通过后撤销不回滚套餐失效或已启动退款，标记审批异常并禁止自动重提。
+
+#### Scenario: 审批通过前结果未知
+- **WHEN** 企业微信提交成功性或最终结果暂时未知
+- **THEN** 申请保持在途且订单不得创建第二张活动申请，系统通过既有恢复机制确认结果
+
+### Requirement: 原路退款执行与权益时点
+对线上订单，系统在创建、提交及企业微信通过后的执行前均 SHALL 校验原支付单、实际收款商户、渠道流水、可退金额及商户退款能力/凭证；商户停用不得阻断历史单校验。条件不满足时禁用原路并说明原因，只允许客户收款信息退款。
+
+企业微信最终通过即按既有规则使关联套餐失效、接续下一套餐并评估停机；客户收款信息退款同时标记退款成功，不等待线下付款。原路退款必须以冻结金额调用原实际收款商户；仅渠道明确成功后标记成功并保存渠道退款流水。超时、未知、凭证失效、余额不足或渠道拒绝时保留处理中/失败与安全原因，不标记成功或重复调用；需改客户收款信息退款时必须修改后重新审批。
+
+#### Scenario: 原路渠道调用未知
+- **WHEN** 企业微信已通过的原路退款调用超时且无法确认渠道结果
+- **THEN** 退款保持原路处理中或失败恢复状态，套餐权益不恢复，系统不得再次盲目提交退款

openspec/changes/add-refund-methods-and-original-route-refunds/tasks.md

@@ -0,0 +1,15 @@
+## 1. 退款契约与数据
+
+- [ ] 1.1 追踪退款、订单/支付、钱包、套餐、企微审批和商户退款调用链；新增成对迁移、模型、状态/方式常量、实收/材料/渠道结果快照及活动申请唯一约束。
+- [ ] 1.2 实现退款可选方式和权威实收金额投影，创建/提交时冻结金额、套餐使用情况、原因和材料；更新 DTO/OpenAPI。
+
+## 2. 审批、资金与恢复
+
+- [ ] 2.1 将退款终审切换为企业微信回调/查询恢复，移除新业务的本地人工通过/拒绝/退回；实现未成功申请的新实例重提。
+- [ ] 2.2 在企微通过事务内执行套餐失效/接续及原钱包退款；客户收款信息退款直接完成。
+- [ ] 2.3 实现原实际商户、渠道流水和退款能力三次校验、可靠原路退款调用、幂等回写与未知/失败恢复；联动员工账单冲销和佣金回溯入口。
+
+## 3. 验证
+
+- [ ] 3.1 在隔离库验证每种来源方式、实收上限、活动申请互斥、审批重放/未知、渠道失败重提、商户停用历史退款和套餐权益时点。
+- [ ] 3.2 运行 `gofmt -w`、`go build ./cmd/api ./cmd/worker`、`go run cmd/gendocs/main.go`、`openspec validate add-refund-methods-and-original-route-refunds --strict`、`openspec doctor --json` 和 `./scripts/context-health.sh`；自动化测试按项目决策为 N/A。