junhong_cmp_fiber/openspec/changes/archive/2026-09-20-complete-refund-approval-materials-and-recovery/tasks.md

1. 退款审批材料快照

• 1.1 新增稳定审批业务字段编码：退款方式编码、退款方式中文名称、客户收款信息和客户凭证，并登记到退款企微场景字段白名单及正确控件类型。
• 1.2 扩展新建、历史补发与重提的退款审批快照，从当次不可变审批尝试写入方式编码、统一中文名称、客户收款文本和凭证列表；非客户收款方式写空条件值但不伪造材料。
• 1.3 核对退款方式名称只复用既有领域映射，历史审批实例仍读取各自请求快照，不因退款主表或后续重提变化。

2. 企业微信条件映射规则

• 2.1 将企微必需字段规则扩展为固定必需与按请求快照生效的条件必需两类，默认不改变其它审批场景行为。
• 2.2 配置保存时固定强制退款方式映射，并对已配置的客户收款信息多行文本与客户凭证附件映射校验控件类型。
• 2.3 表单构建时按退款方式编码计算本次必需字段：customer_account 强制客户收款文本与凭证映射和值，其他方式不要求；缺失时返回指出具体字段和控件的错误。
• 2.4 确认原路退款、资产钱包退款和代理钱包退款在未配置客户收款控件时仍可提交，且企微材料明确展示对应退款方式。

3. 历史快照补齐与审批恢复

• 3.1 在通用审批 Application/Infrastructure 边界提供按原实例查询同步、确认结果未知和恢复稳定提交事件的接缝，复用 approval:{instance_id}:submission，活动事件幂等返回。
• 3.2 实现退款历史快照受控补齐：锁定退款、最新尝试和原实例，校验关联一致，只从不可变尝试添加缺失的新键，不覆盖已有快照、不读取退款主表，并写脱敏审计。
• 3.3 实现退款恢复用例：仅待审批且最新尝试、实例一致时允许；已有 sp_no 只查询，结果未知只确认，明确未受理失败恢复原事件，正常重试返回当前状态。
• 3.4 保证重复或并发恢复至多一次改变提交事实；恢复不新增尝试或实例，不修改退款材料和状态，不触发套餐、订单、资金或渠道退款动作。

4. 查询投影与 HTTP 入口

• 4.1 扩展退款列表与详情 DTO，返回审批提交状态、状态名、可恢复标记、安全失败摘要和最近恢复时间。
• 4.2 在退款 Query 中按页批量读取最新审批实例、企微上下文和提交事件计算恢复投影，避免逐条查询；敏感收款信息、附件键、企微原文和内部事件键不得进入失败摘要。
• 4.3 新增 POST /api/admin/refunds/{id}/recover-approval Handler 与 RouteSpec，只接受路径退款 ID；同步可执行路由、cmd/api/docs.go、cmd/gendocs/main.go 和 OpenAPI 生成要求。
• 4.4 复用退款管理权限和数据范围：超级管理员、平台用户与代理仅操作原可见退款，企业账号拒绝，越权与不存在不可区分；审批终态、原路处理中和渠道失败返回状态冲突。

5. 验证、配置与规格同步

• 5.1 在维护者指定测试环境分别提交四种退款方式，核对企微材料中的中文方式；客户收款退款包含多行文本和附件，其他方式不要求客户收款控件。
• 5.2 验证客户收款退款缺文本、凭证、映射或控件时明确失败；修复模板后从原尝试补齐历史快照并恢复同一审批实例。
• 5.3 验证结果未知、已有 sp_no、正常重试、重复与并发恢复，以及终态、渠道阶段和越权拒绝；核对尝试数、实例数、退款材料、订单、权益和资金事实不变。
• 5.4 核对列表与详情投影、批量查询和审计脱敏，运行 gofmt -w、go build ./cmd/api ./cmd/worker、go run cmd/gendocs/main.go。
• 5.5 更新退款企微模板上线前置说明、主 Spec 可达操作索引和证据矩阵，运行 openspec validate complete-refund-approval-materials-and-recovery --strict、openspec doctor --json、openspec validate --all 与 ./scripts/context-health.sh。