fix: 第1批 M8、M13、M14 审批提交失败终态与退款关闭类终态定位

- 审批核心在实例进入提交失败的同一事务内写 submission_failed 决策投递与终态事件,消费入口单独放行
- 核销(4)、退款(7)、扫码注册(3)、资料资格(4)、线下充值(7)、佣金提现(5)新增“审批提交失败”终态并释放预占/冻结
- 三处恢复入口不再重放提交失败;退款关闭类终态按审批尝试定位退款单(M13)
- 核销列表与详情批量返回审批提交状态;筛选、字段说明、状态名称、退款导出加入新状态
- 迁移 000239 放宽五张业务表状态约束与决策投递取值约束(测试库已执行 up/down/up)
- OpenSpec Change fix-approval-submission-failure-terminal:18/26,测试部署后端到端验证与存量补数据待完成
This commit is contained in:
邹进
2026-10-12 00:03:46 +09:00
parent 25c081fe60
commit 6298a9061f
42 changed files with 810 additions and 87 deletions

View File

@@ -0,0 +1,50 @@
## MODIFIED Requirements
### Requirement: 代理注册原审批可受控恢复
系统 SHALL 提供 `POST /api/admin/agent-distribution-registrations/{id}/recover-approval`,允许有权平台账号及申请直接上级代理恢复仍待审批的注册申请。恢复 MUST 校验原审批实例及业务关联、上级店铺启用状态和调用方范围,复用原实例与稳定提交事实;不得新建注册记录、审批实例、企业微信审批单、店铺、账号或钱包。结果未知时 MUST 优先确认原提交,已有审批单号时 MUST 同步原审批;审批实例为提交失败时 MUST 返回“审批提交失败为终态,请重新发起”,MUST NOT 重放原提交事件。终态申请(含审批提交失败)或停用上级 MUST 返回稳定冲突;恢复 MUST 写入脱敏审计。
#### Scenario: 提交失败不可恢复
- **WHEN** 注册申请的原审批实例已提交失败时请求恢复
- **THEN** 系统返回“审批提交失败为终态,请重新发起”,不重放提交事件、不新建注册记录或业务实体
#### Scenario: 结果未知优先确认
- **WHEN** 待审批申请的原提交结果未知
- **THEN** 系统进入原实例确认流程,不直接创建新的企业微信审批
#### Scenario: 终态或停用上级拒绝恢复
- **WHEN** 注册申请已终态或其直接上级店铺已停用时请求恢复
- **THEN** 系统返回稳定冲突且不改变注册、审批或实体事实
## ADDED Requirements
### Requirement: 扫码注册代理审批提交失败
审批核心对注册申请的审批实例发出 `submission_failed` 决策时,系统 SHALL 确认审批实例仍为提交失败,将注册记录从待审批(0)条件更新为审批提交失败(3),记录脱敏失败原因并写审计,按事件幂等;MUST NOT 创建店铺、账号、钱包或层级。审批提交失败为终态,MUST NOT 阻止同一手机号、用户名或店铺编号再次提交;客户重新扫码提交形成新的注册记录与新的审批实例。
#### Scenario: 注册审批提交失败
- **WHEN** 待审批注册申请的审批实例提交企微失败
- **THEN** 注册记录变为审批提交失败,不创建任何业务实体,同一手机号可重新扫码提交
### Requirement: 佣金提现审批提交失败
审批核心对提现申请最新审批尝试发出 `submission_failed` 决策时,系统 SHALL 确认审批实例仍为提交失败,在同一事务内仅一次释放该次尝试的冻结余额并记录释放时间,将提现申请从待审核条件更新为审批提交失败(5),记录脱敏失败原因并写审计,按事件幂等。审批提交失败的申请 MUST 允许代理修改金额、收款信息和本次发票后重新发起,重新发起时按新金额重新冻结、新增审批尝试与审批实例,资料资格保持有效。
#### Scenario: 提现审批提交失败释放冻结
- **WHEN** 待审核提现申请的审批实例提交企微失败
- **THEN** 申请变为审批提交失败,冻结金额仅一次释放,钱包余额与流水一致
#### Scenario: 提交失败后重新发起
- **WHEN** 代理对审批提交失败的提现申请修改后重新发起
- **THEN** 系统按新金额重新冻结并创建新的审批尝试与审批实例,历史尝试不被覆盖
### Requirement: 提现资料资格审批提交失败
审批核心对资料版本审批实例发出 `submission_failed` 决策时,系统 SHALL 确认审批实例仍为提交失败,将资料版本从等待终审(0)条件更新为审批提交失败(4),记录脱敏失败原因并写审计,按事件幂等。审批提交失败为终态,MUST NOT 阻止代理提交新的资料版本,MUST NOT 影响已通过的有效版本。
#### Scenario: 资料资格审批提交失败
- **WHEN** 等待终审的资料版本审批实例提交企微失败
- **THEN** 该版本变为审批提交失败,代理可提交新的资料版本,已通过的有效版本不受影响

View File

@@ -0,0 +1,13 @@
## ADDED Requirements
### Requirement: 线下代理充值审批提交失败
审批核心对线下代理充值申请的审批实例发出 `submission_failed` 决策时,系统 SHALL 确认审批实例仍为提交失败,将充值记录从待审批条件更新为审批提交失败(7),记录脱敏失败原因并写审计,按事件幂等;MUST NOT 入账或改变代理钱包余额。审批提交失败为终态,代理充值列表、筛选、状态名称与导出 MUST 显示该状态;要再充值由申请人重新发起新的充值申请。
#### Scenario: 线下充值审批提交失败
- **WHEN** 待审批线下代理充值申请的审批实例提交企微失败
- **THEN** 充值记录变为审批提交失败,钱包余额不变,列表与筛选可见该状态
#### Scenario: 重复投递
- **WHEN** 同一 `submission_failed` 决策被重复投递
- **THEN** 充值记录状态与审计只生效一次

View File

@@ -0,0 +1,46 @@
## MODIFIED Requirements
### Requirement: 核销申请审批、重提与幂等
核销申请状态 SHALL 为 `审批中`、`已通过`、`已驳回`、`已撤销/已关闭`、`审批提交失败`,且不得以申请状态覆盖账单核销状态。提交或重提时系统 MUST 新增一条不可变审批尝试记录(冻结当次收款方式、外部付款、附件、备注、账单分摊及审批材料快照)并为其创建新的企业微信审批实例;申请只保存最新审批实例 ID 用于展示。企业微信业务类型 MUST 为 `employee_collection_approval`,其业务标识 MUST 取审批尝试记录主键,使同一申请的多次提交各自持有独立审批实例,且 MUST NOT 修改既有审批实例的共享唯一约束或既有 `refund_approval`、`offline_recharge_approval` 场景语义。
企业微信最终通过时,系统 MUST 幂等地将申请标记为已通过、将各分摊写入账单已核销金额并释放其预占;最终驳回时 MUST 标记申请已驳回、释放全部预占且保留审批意见。已驳回或审批提交失败的申请可修改全部申请内容后重提,重提生成新的审批尝试与新的企业微信审批,历史审批实例、材料和结果不得覆盖;已通过分摊不可修改。
审批核心对最新审批尝试发出 `submission_failed` 决策时,系统 MUST 确认审批实例仍为提交失败,并在同一事务内释放该次尝试的全部预占分摊与账单预占、将申请从审批中条件更新为审批提交失败、以脱敏失败摘要写入终态原因并写审计;非最新尝试或申请已不是审批中时幂等结束。审批提交失败为终态,MUST NOT 再通过“恢复审批”重放原提交,恢复入口对该情形 MUST 返回“审批提交失败为终态,请重新发起”,`recoverable` MUST 返回 false。回调延迟或提交结果未知时申请保持在途,系统 MUST 使用既有查询/恢复机制确认渠道结果,且不得由本地人工通过或拒绝绕过企业微信。企业微信对已通过申请撤销时,系统 MUST NOT 回滚已核销金额,MUST 将申请转为异常终态、保留审计与账单详情提示,并禁止自动重提。同一撤销结果在本地申请仍为审批中时(回调乱序或通过结果未被消费),系统 MUST 释放该次审批尝试的全部审批中预占、将申请转为异常终态并记录终态原因、保留审计,MUST NOT 自动重提。
#### Scenario: 企业微信通过核销申请
- **WHEN** 企业微信对含多笔分摊的核销申请返回最终通过,且该结果首次被消费
- **THEN** 系统仅一次更新申请、各账单已核销金额和状态,并保留审批实例及冻结快照
#### Scenario: 企业微信驳回后重提
- **WHEN** 企业微信最终驳回核销申请
- **THEN** 系统释放预占、保留驳回实例和意见;员工或有代办权限的超级管理员修改申请后重提时新增审批尝试记录并创建新的审批实例,历史实例与材料不被覆盖
#### Scenario: 企业微信通过后撤销
- **WHEN** 已通过的核销申请收到企业微信撤销结果
- **THEN** 系统不回滚已核销金额,将申请标记为异常终态、保留审计并在账单详情提示,且不允许自动重提
#### Scenario: 审批中收到通过后撤销
- **WHEN** 企业微信对仍处于审批中的核销申请返回“通过后撤销”(回调乱序或本地未消费到通过结果)
- **THEN** 系统释放该申请全部审批中预占、将申请转为异常终态并记录终态原因、保留审计,且不回滚任何已核销金额;该申请禁止自动重提,账单可重新发起新的核销申请
#### Scenario: 审批提交失败释放预占
- **WHEN** 核销申请的最新审批实例因缺必填控件映射或企微明确拒绝而提交失败
- **THEN** 申请变为审批提交失败、全部预占释放、账单可再次核销、审计写入,且对该申请“恢复审批”被拒
#### Scenario: 审批提交失败后重提
- **WHEN** 员工修改审批提交失败的申请后重提
- **THEN** 系统新增审批尝试记录并创建新的企业微信审批,申请回到审批中
#### Scenario: 提交结果未知保持在途
- **WHEN** 核销申请的审批实例提交结果未知
- **THEN** 申请保持审批中,预占不释放
## ADDED Requirements
### Requirement: 核销申请返回审批提交状态
核销申请列表与详情 SHALL 返回审批提交状态、状态名称、脱敏失败摘要、可恢复标记、最近一次恢复结果与时间,按申请的最新审批实例一次批量读取企微审批上下文,MUST NOT 逐行查询;状态名称映射与失败摘要脱敏 MUST 与退款审批投影一致。无审批上下文的申请 MUST 返回默认值,MUST NOT 报错或丢行。
#### Scenario: 列表返回提交状态
- **WHEN** 查询一页核销申请,其中部分有审批上下文、部分没有
- **THEN** 有上下文的申请返回与测试库企微审批上下文一致的提交状态,没有的返回默认值,整页无逐行查询

View File

@@ -0,0 +1,29 @@
## ADDED Requirements
### Requirement: 审批提交失败通知业务模块
审批实例因企微明确拒绝提交或审批表单无法构造(如缺必填控件映射)而变为“提交失败”(7)时,系统 SHALL 在同一事务内经既有终态决策通道发出决策 `submission_failed`:MUST 同时写入标准决策 Outbox 事件与决策投递记录(与其他终态决策相同,缺投递记录时业务消费者不会处理);事件标识 MUST 沿用既有格式 `approval:{审批实例标识}:submission_failed`,重复写入不产生第二个事件。决策事件结构不新增字段,失败原因由业务模块从该实例的企微审批上下文读取并脱敏后保存。决策消费入口 MUST 接受 `submission_failed`;渠道回调与轮询的审批状态推进 MUST NOT 因此接受该决策值。提交结果未知(8)MUST NOT 发出该决策,仍由既有恢复机制确认。所有已注册的审批业务类型(核销、退款、扫码注册代理、线下充值、佣金提现、提现资料资格)MUST 显式处理该决策,MUST NOT 将其按驳回处理;各业务处理前 MUST 确认审批实例仍为提交失败,否则幂等结束。
#### Scenario: 企微明确拒绝提交
- **WHEN** 某业务单的审批实例提交企微被明确拒绝
- **THEN** 审批实例变为提交失败,同一事务写入一条 `submission_failed` 决策事件,对应业务模块随后将业务单置为“审批提交失败”
#### Scenario: 审批表单构造失败
- **WHEN** 某审批实例因缺少必填控件映射无法构造表单
- **THEN** 系统按提交失败处理并发出 `submission_failed` 决策
#### Scenario: 提交结果未知不发决策
- **WHEN** 审批实例提交结果未知
- **THEN** 系统不发出 `submission_failed` 决策,业务单保持审批中
#### Scenario: 业务模块确实收到决策
- **WHEN** 审批实例变为提交失败并写入决策事件
- **THEN** 该事件存在对应的决策投递记录,业务消费者能认领并处理,业务单状态发生变化,而不是被当作已处理直接结束
#### Scenario: 渠道回调不能推进到提交失败
- **WHEN** 企微回调或轮询带来的决策值为 `submission_failed`
- **THEN** 审批状态推进按不受支持的决策拒绝,审批实例状态不变
#### Scenario: 决策重复投递
- **WHEN** 同一 `submission_failed` 决策被重复投递
- **THEN** 业务单状态、释放的占用与审计均只生效一次

View File

@@ -0,0 +1,97 @@
## MODIFIED Requirements
### Requirement: 订单、退款与换货状态门禁
系统 SHALL 仅允许待支付订单取消;退款申请按待审批、已通过、已拒绝、已退回、原路退款处理中、原路退款失败、审批提交失败流转,仅已拒绝、已退回、原路退款失败和审批提交失败申请可修改并重新提交;换货按待填写信息、待发货、已发货、已完成或已取消流转,并拒绝与当前状态或流程类型不匹配的操作。处于待审批、原路退款处理中或原路退款失败的退款申请 MUST 阻止同一订单创建新的退款申请,且 MUST NOT 被再次推进为新的审批实例或第二次渠道退款。已拒绝与审批提交失败的退款申请为终态,MUST NOT 阻止同一订单创建新的退款申请,也 MUST NOT 阻止该资产换货。
#### Scenario: 重复推进终态
- **GIVEN** 退款或换货已进入不允许当前操作的状态
- **WHEN** 再次审批、发货、完成、取消或重新提交
- **THEN** 系统返回状态冲突且不重复改变资产、余额或业务状态
#### Scenario: 原路退款失败后重提
- **WHEN** 退款申请处于原路退款失败状态且调用方在其数据范围内修改材料后重新提交
- **THEN** 系统新增一条审批尝试记录与一个新的企业微信审批实例并使申请回到待审批,历史尝试与已提交的渠道退款不被覆盖
#### Scenario: 企业微信通过后撤销的申请被再次推进
- **GIVEN** 退款申请已记录企业微信通过后撤销的审批异常
- **WHEN** 调用者再次提交或重提该申请
- **THEN** 系统返回状态冲突,不恢复套餐权益、不取消已提交的渠道退款且不自动重提
#### Scenario: 审批提交失败的退款不阻断换货
- **GIVEN** 资产的退款申请处于审批提交失败
- **WHEN** 调用方为该资产发起换货
- **THEN** 系统不因该退款申请拒绝换货
### Requirement: 企业微信唯一终审与审批尝试重提
退款申请 SHALL 保存退款原因、冻结实收金额、唯一关联套餐及其使用情况、方式、金额和当次材料快照。超级管理员、平台用户和代理可在各自订单数据范围内创建、修改并重提未成功申请;企业微信是唯一终审,本地 MUST NOT 人工通过、拒绝或退回已关联审批实例的申请。每次创建或重提 MUST 新增一条不可变的审批尝试记录,并以该尝试记录作为通用审批业务标识;同一申请每次提交各自持有独立审批实例,历史尝试材料与审批结果不被覆盖。退款单 SHALL 仅保存最新尝试与最新审批实例引用用于展示。
同一订单同时至多存在一张待审批、原路退款处理中或原路退款失败的退款申请。企业微信驳回、撤销或删除待审批申请后,系统 MUST 将退款申请置为已拒绝(终态),拒绝原因分别为“企业微信审批已拒绝”“企业微信审批已撤销”“企业微信审批已删除”,并写审计;要再退款须在卡管对该申请重新发起,生成新的审批尝试与新的企业微信审批。企业微信侧对已驳回或已撤销审批重新提交产生的新审批单号,系统 MUST NOT 关联到任何退款申请,只按既有“未关联本系统业务,已忽略”留痕。原路退款明确失败后可修改未成功申请的金额、原因、方式、收款信息和附件并重提;每次重提必须新建审批实例及快照。
审批核心对最新审批实例发出 `submission_failed` 决策时,系统 MUST 确认审批实例仍为提交失败,将退款申请从待审批条件更新为审批提交失败(终态),记录脱敏失败原因并写审计,按事件幂等;该申请 MUST 可在卡管重新发起,MUST NOT 再通过恢复入口重放原提交。审批结果未知时申请保持在途,使用既有查询与恢复闭环,不得另建或重提。企业微信通过后撤销时不回滚套餐失效或已启动退款,标记审批异常并禁止自动重提。
审批终态(含通过、驳回、撤销、删除、通过后撤销与提交失败)MUST 以审批实例标识判别业务归属:先按审批尝试记录标识与审批实例匹配,未命中时按退款申请标识与审批实例匹配以兼容尚未切换到尝试模式的存量申请,两者均不匹配时返回稳定冲突错误,不得回落到任一候选业务单。定位后 MUST 对退款申请加行锁再推进状态。
#### Scenario: 审批通过前结果未知
- **WHEN** 企业微信提交成功性或最终结果暂时未知
- **THEN** 申请保持在途且订单不得创建第二张活动申请,系统通过既有恢复机制确认结果
#### Scenario: 未成功申请重提新建实例
- **GIVEN** 退款申请处于已拒绝、已退回、原路退款失败或审批提交失败状态且无审批异常
- **WHEN** 调用者修改材料后重新提交
- **THEN** 系统在同一事务新增审批尝试记录并创建新的企业微信审批实例,原尝试记录与历史审批结果保持不变
#### Scenario: 尝试模式申请被企业微信撤销
- **GIVEN** 退款申请以审批尝试记录作为审批业务标识,且处于待审批
- **WHEN** 企业微信对该审批返回撤销、拒绝或删除
- **THEN** 系统按审批尝试定位到该退款申请,将其置为已拒绝并记录对应原因与审计,该资产随后可换货
#### Scenario: 企业微信侧重新提交不关联
- **WHEN** 企业微信回调一个卡管未创建的审批单号(企微侧对已驳回或已撤销审批的重新提交)
- **THEN** 系统不关联任何退款申请,只留痕“未关联本系统业务,已忽略”
#### Scenario: 审批提交失败
- **WHEN** 待审批退款申请的最新审批实例提交企微失败
- **THEN** 退款申请变为审批提交失败并写审计,列表、筛选、导出显示该状态;重复投递结果不变
#### Scenario: 存量申请审批终态仍被消费
- **GIVEN** 退款申请由本能力上线前创建,其审批实例的业务标识指向退款申请本身
- **WHEN** 该审批实例到达通过或关闭终态
- **THEN** 系统按审批实例标识匹配到该退款申请并幂等推进,不按尝试模式误判为不存在
#### Scenario: 已关联实例的本地人工终审
- **GIVEN** 退款申请已关联审批实例
- **WHEN** 后台账号调用本地通过、拒绝或退回入口
- **THEN** 系统拒绝该操作且不改变退款申请与订单状态
#### Scenario: 存量无实例待审批申请仍可终结
- **GIVEN** 退款申请未关联任何审批实例且处于待审批状态
- **WHEN** 后台账号在既有开关开放时调用本地通过、拒绝或退回入口
- **THEN** 系统按既有语义终结该申请,不要求该申请先接入企业微信审批
### Requirement: 退款原审批实例可受控恢复
系统 SHALL 提供 `POST /api/admin/refunds/{id}/recover-approval`,允许既有退款管理范围内的超级管理员、平台用户和代理恢复仍处于待审批的退款最新审批实例;企业账号拒绝,越权与不存在不可区分。恢复 MUST 复用原审批实例及 `approval:{instance_id}:submission` 稳定提交事实,不得新增审批尝试/实例、修改冻结退款材料或触发退款、订单、套餐与资金动作。已有 `sp_no` 只查询同步,结果未知只确认;审批实例为提交失败时 MUST 返回“审批提交失败为终态,请重新发起”,MUST NOT 重放原提交事件。审批终态、审批提交失败、原路退款处理中或渠道退款失败 MUST 返回状态冲突。审批提交失败的退款申请 `recoverable` MUST 为 false。历史快照缺失新增键时,只能从关联不可变审批尝试补齐缺失值并写脱敏审计。
#### Scenario: 恢复入口只处理原审批事实
- **WHEN** 授权账号请求恢复待审批退款
- **THEN** 系统按最新尝试与实例关联选择恢复分支,列表/详情返回提交状态、可恢复标记、安全失败摘要和最近恢复时间,重复或并发请求至多一次改变提交事实。
#### Scenario: 提交失败不可恢复
- **WHEN** 授权账号对审批实例已提交失败的退款申请请求恢复
- **THEN** 系统返回“审批提交失败为终态,请重新发起”,不重放提交事件、不改变审批实例