docs: 更新 OpenAPI 文档及提案任务清单，新增 payment_voucher_key 字段

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

openspec/changes/agent-recharges-payment-voucher/tasks.md

@@ -0,0 +1,32 @@
+## 1. 数据库迁移
+
+- [x] 1.1 在 `migrations/` 目录创建迁移文件，为 `tb_agent_recharge_record` 表添加 `payment_voucher_key VARCHAR(500)` 列（允许 NULL，兼容历史数据）
+- [x] 1.2 执行迁移，验证 `tb_agent_recharge_record` 表已包含 `payment_voucher_key` 列（使用 PostgreSQL MCP 查询 `information_schema.columns` 确认）
+
+## 2. Model 层
+
+- [x] 2.1 在 `internal/model/agent_wallet.go` 的 `AgentRechargeRecord` 结构体中添加 `PaymentVoucherKey string` 字段，包含 gorm tag 和中文注释
+- [x] 2.2 运行 `lsp_diagnostics` 确认 `agent_wallet.go` 无错误
+
+## 3. DTO 层
+
+- [x] 3.1 在 `internal/model/dto/agent_recharge_dto.go` 的 `CreateAgentRechargeRequest` 中添加 `PaymentVoucherKey` 字段（`validate:"omitempty,max=500"`，含 description 标签，注明 `payment_method=offline` 时必填）
+- [x] 3.2 在 `AgentRechargeResponse` 中添加 `PaymentVoucherKey` 响应字段（`omitempty`）
+- [x] 3.3 运行 `lsp_diagnostics` 确认 `agent_recharge_dto.go` 无错误
+
+## 4. Service 层
+
+- [x] 4.1 在 `internal/service/agent_recharge/service.go` 的 `Create` 方法中，在支付方式判断逻辑后添加凭证非空检查：当 `req.PaymentMethod == "offline"` 且 `strings.TrimSpace(req.PaymentVoucherKey) == ""` 时返回 `errors.New(errors.CodeInvalidParam, "线下充值必须上传支付凭证")`
+- [x] 4.2 在 `Create` 方法构建 `AgentRechargeRecord` 的赋值块中添加 `PaymentVoucherKey: strings.TrimSpace(req.PaymentVoucherKey)` 字段
+- [x] 4.3 在 `toResponse`（或等价的响应构建函数）中将 `record.PaymentVoucherKey` 映射到 `AgentRechargeResponse.PaymentVoucherKey`
+- [x] 4.4 运行 `lsp_diagnostics` 确认 `agent_recharge/service.go` 无错误
+
+## 5. 文档生成器更新
+
+- [x] 5.1 检查 `cmd/api/docs.go` 和 `cmd/gendocs/main.go` 中 `AgentRechargeHandler` 的注册方式（本次未新增 Handler，仅修改已有请求体，确认无需额外改动）
+
+## 6. 接口验证
+
+- [x] 6.1 调用 `POST /api/admin/agent-recharges`（`payment_method=offline`，不传凭证），验证返回 400"线下充值必须上传支付凭证"
+- [x] 6.2 调用 `POST /api/admin/agent-recharges`（`payment_method=offline`，传入合法凭证 key），验证返回 200，使用 PostgreSQL MCP 查询 `tb_agent_recharge_record` 确认 `payment_voucher_key` 字段已写入正确值
+- [x] 6.3 调用 `POST /api/admin/agent-recharges`（`payment_method=wechat`，不传凭证），验证正常创建成功，无凭证校验报错