This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-08-31
|
||||
@@ -0,0 +1,26 @@
|
||||
## Decisions
|
||||
|
||||
- 线上充值复用支付单和实际商户路由，成功消费者以支付单/钱包流水唯一约束入账。
|
||||
- 线下申请保存不可变金额和付款证据快照；审批回调在主钱包锁事务中条件入账。
|
||||
- 线上未知结果和线下审批未知均保持在途，复用既有查询/恢复，不把重试当作新入账。
|
||||
|
||||
## 配置与充值动作契约
|
||||
|
||||
### 允许方式与查询
|
||||
|
||||
- `GET /agent-self-recharge-payment-methods`：代理、平台用户仅返回“全局允许方式 ∩ 当前启用商户池可用方式”的有序 `wechat`/`alipay` 列表；不得返回商户身份、凭证或全局允许范围。交集为空返回空列表。
|
||||
- `PUT /agent-self-recharge-payment-methods`：仅超级管理员，保存 `wechat_only`、`alipay_only` 或 `wechat_and_alipay`；记录操作者、前后值和时间。修改不更新任何已有充值/支付单的支付方式、商户 ID 或快照。
|
||||
|
||||
### 自身店铺充值
|
||||
|
||||
- `POST /agent-recharges` 的代理在线分支强制 `shop_id` 为空且认证店铺为已启用代理自身店铺；传入下级/其他店铺返回无权。线上请求 `amount`、`payment_method`、`request_id`，其中方式必须在当前交集内；以 `request_id` 与调用者/店铺唯一复用既有支付创建结果，失败预下单不入账。
|
||||
- 在线创建在事务内选择实际商户、冻结支付/商户快照并创建充值记录；渠道成功消费者锁定支付、充值和主钱包，以支付 ID/钱包流水唯一约束一次入账。失败、关闭、退款或未知状态不加余额；未知结果由既有查单/回调恢复，禁止客户端重试直接增加余额。
|
||||
|
||||
### 线下转账
|
||||
|
||||
- 线下请求必须包含 `amount`（正分）、`payer_name`、`transferred_at`（带时区时间）、`transfer_channel_or_bank`、`transaction_no`、至少一个 `payment_voucher_key` 和可选备注；创建时冻结全部字段、状态为待企业微信审批，不增加主钱包。
|
||||
- 企业微信通过消费者锁定申请、审批实例和主钱包，条件更新一次增加余额和钱包流水；驳回、撤回、关闭不入账。仅未成功申请可修改上述材料并创建新审批实例重提；未知审批保持在途。平台/超级管理员查询和处理一律先应用既有店铺数据范围，审计不记录凭证正文。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
新增线下充值申请、附件快照、审批关联及唯一约束的成对迁移；验证权限、回调重放、未知、驳回重提和 up/down/up。
|
||||
@@ -0,0 +1,25 @@
|
||||
## Scope
|
||||
|
||||
- 迭代编号：`AUG26-017`。
|
||||
|
||||
## Why
|
||||
|
||||
代理自助充值需同时覆盖线上支付和可审计的线下转账，且不能将付款成功与钱包入账混淆。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 新增代理自身店铺线上微信/支付宝充值。
|
||||
- 新增带凭证的线下转账申请及企业微信终审。
|
||||
- 固化支付回调、审批回调和钱包入账幂等。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `agent-self-recharge-payment`: 代理自助充值支付方式。
|
||||
|
||||
### Modified Capabilities
|
||||
- 无。
|
||||
|
||||
## Impact
|
||||
|
||||
影响代理主钱包、支付商户、企业微信审批、附件、审计和 Schema。
|
||||
@@ -0,0 +1,18 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 代理自助充值支付方式
|
||||
超级管理员 SHALL 维护代理在线自充允许方式：仅微信、仅支付宝或微信和支付宝；代理实际可用线上方式为该允许范围与当前可用对应商户池方式的交集，交集为空时拒绝创建线上充值单。平台用户和代理仅可查询实际可用方式，不得查看或修改允许范围。配置变更只影响后续新单，已创建未支付充值单保留其支付方式及商户快照。系统 SHALL 允许已启用代理在其自身店铺充值入口选择实际可用的线上微信、线上支付宝或线下转账；不得为下级店铺代充。线上方式创建支付单并按实际商户路由，渠道成功回调幂等增加该代理主钱包余额；失败、关闭或未知不得增加余额，未知结果通过既有支付查询/回调恢复，不允许重复支付单入账。
|
||||
|
||||
线下转账申请必须填写转账金额、付款人、转账时间、银行/支付渠道、流水号和凭证附件；创建后状态为待企业微信审批，不立即入账。企业微信通过时在事务内锁定申请并仅一次增加主钱包余额；驳回、关闭或撤回不入账，代理可修改未成功申请后以新审批实例重提。充值金额以分保存，展示元时两位小数；平台/超级管理员仅可查看和处理其既有数据范围。
|
||||
|
||||
#### Scenario: 配置与商户池交集为空
|
||||
- **WHEN** 超级管理员允许一种线上方式，但该方式没有可用商户池成员
|
||||
- **THEN** 代理可用线上方式列表不含该方式，创建该方式充值单被拒绝，已创建未支付单不受影响
|
||||
|
||||
#### Scenario: 重复线上成功回调
|
||||
- **WHEN** 同一线上充值支付成功回调被重复投递
|
||||
- **THEN** 系统只增加一次代理主钱包余额并保留幂等支付事实
|
||||
|
||||
#### Scenario: 线下申请审批驳回
|
||||
- **WHEN** 企业微信驳回线下转账充值申请
|
||||
- **THEN** 系统不增加钱包余额，并允许代理修改申请后创建新审批实例重提
|
||||
@@ -0,0 +1,8 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 代理自充支付方式
|
||||
系统 SHALL 使代理在线自充可用支付方式等于超级管理员维护的允许范围与当前启用商户池支付方式的交集；交集为空时拒绝创建新充值单。配置变更仅影响后续订单，既有未支付订单保留其支付方式和商户快照。
|
||||
|
||||
#### Scenario: 规则命中
|
||||
- **WHEN** 业务请求或任务满足本需求定义的前置条件
|
||||
- **THEN** 系统按上述规则完成处理、保留可追溯事实，并拒绝与状态、权限或幂等约束冲突的重复操作
|
||||
@@ -0,0 +1,9 @@
|
||||
## 1. 充值实现
|
||||
- [ ] 1.1 追踪代理钱包、线上支付、商户路由、线下附件和企业微信审批链路。
|
||||
- [ ] 1.2 新增线下申请/快照/审批关联的成对迁移、模型、状态和幂等约束。
|
||||
- [ ] 1.3 实现自身店铺门禁、线上支付创建/成功入账恢复、线下申请/企微终审/重提和钱包事务审计。
|
||||
- [ ] 1.4 注册路由、OpenAPI及代理/平台查询数据范围。
|
||||
|
||||
## 2. 验证
|
||||
- [ ] 2.1 隔离库验证支付方式、越权代充、重复回调、未知恢复、线下驳回重提和 up/down/up。
|
||||
- [ ] 2.2 运行 `gofmt -w`、`go build ./cmd/api ./cmd/worker`、`go run cmd/gendocs/main.go`、`openspec validate add-agent-self-recharge-payment-methods --strict` 和 `openspec doctor --json`；自动化测试按项目决策为 N/A。
|
||||
Reference in New Issue
Block a user