提案以及归档

openspec/specs/agent-recharge-payment-voucher/spec.md

@@ -0,0 +1,43 @@
+## ADDED Requirements
+
+### Requirement: 创建线下充值订单时必须上传支付凭证
+
+系统 SHALL 在 `POST /api/admin/agent-recharges` 接口中，当 `payment_method=offline` 时强制要求 `payment_voucher_key` 字段非空。凭证 key 为通过 `/storage/upload-url` 上传至对象存储后获得的文件标识符。当 `payment_method=wechat` 时，`payment_voucher_key` 字段忽略。
+
+#### Scenario: 线下支付缺少凭证时拒绝创建
+
+- **WHEN** 调用 `POST /api/admin/agent-recharges`，`payment_method=offline` 且 `payment_voucher_key` 为空或未传
+- **THEN** 系统返回 400，错误码 `CodeInvalidParam`，消息"线下充值必须上传支付凭证"
+
+#### Scenario: 线下支付有凭证时创建成功
+
+- **WHEN** 调用 `POST /api/admin/agent-recharges`，`payment_method=offline` 且 `payment_voucher_key` 非空
+- **THEN** 系统创建充值记录，凭证 key 写入 `tb_agent_recharge_record.payment_voucher_key`，返回 200
+
+#### Scenario: 微信支付不需要凭证
+
+- **WHEN** 调用 `POST /api/admin/agent-recharges`，`payment_method=wechat`，不传 `payment_voucher_key`
+- **THEN** 系统正常创建充值记录，不做凭证校验，返回 200
+
+### Requirement: 充值记录存储支付凭证
+
+系统 SHALL 将 `payment_voucher_key` 持久化到 `tb_agent_recharge_record` 表的 `payment_voucher_key` 列，与充值记录创建在同一个数据库操作内完成。
+
+#### Scenario: 凭证随记录创建写入
+
+- **WHEN** `Create` 方法执行创建充值记录
+- **THEN** `payment_voucher_key` 与其他字段一同写入数据库，不可分割
+
+### Requirement: 充值记录响应包含凭证信息
+
+系统 SHALL 在 `AgentRechargeResponse` 中返回 `payment_voucher_key` 字段，允许为空（历史记录及微信支付无凭证）。
+
+#### Scenario: 已上传凭证的线下充值记录查询
+
+- **WHEN** 查询已创建的线下充值记录
+- **THEN** 响应 `payment_voucher_key` 字段返回非空的对象存储 key
+
+#### Scenario: 微信支付记录无凭证字段
+
+- **WHEN** 查询微信支付的充值记录
+- **THEN** 响应 `payment_voucher_key` 字段为空字符串或 omitempty（前端不展示）