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

1. 数据库迁移

• 1.1 在 migrations/ 目录创建迁移文件，为 tb_agent_recharge_record 表添加 payment_voucher_key VARCHAR(500) 列（允许 NULL，兼容历史数据）
• 1.2 执行迁移，验证 tb_agent_recharge_record 表已包含 payment_voucher_key 列（使用 PostgreSQL MCP 查询 information_schema.columns 确认）

2. Model 层

• 2.1 在 internal/model/agent_wallet.go 的 AgentRechargeRecord 结构体中添加 PaymentVoucherKey string 字段，包含 gorm tag 和中文注释
• 2.2 运行 lsp_diagnostics 确认 agent_wallet.go 无错误

3. DTO 层

• 3.1 在 internal/model/dto/agent_recharge_dto.go 的 CreateAgentRechargeRequest 中添加 PaymentVoucherKey 字段（validate:"omitempty,max=500"，含 description 标签，注明 payment_method=offline 时必填）
• 3.2 在 AgentRechargeResponse 中添加 PaymentVoucherKey 响应字段（omitempty）
• 3.3 运行 lsp_diagnostics 确认 agent_recharge_dto.go 无错误

4. Service 层

• 4.1 在 internal/service/agent_recharge/service.go 的 Create 方法中，在支付方式判断逻辑后添加凭证非空检查：当 req.PaymentMethod == "offline" 且 strings.TrimSpace(req.PaymentVoucherKey) == "" 时返回 errors.New(errors.CodeInvalidParam, "线下充值必须上传支付凭证")
• 4.2 在 Create 方法构建 AgentRechargeRecord 的赋值块中添加 PaymentVoucherKey: strings.TrimSpace(req.PaymentVoucherKey) 字段
• 4.3 在 toResponse（或等价的响应构建函数）中将 record.PaymentVoucherKey 映射到 AgentRechargeResponse.PaymentVoucherKey
• 4.4 运行 lsp_diagnostics 确认 agent_recharge/service.go 无错误

5. 文档生成器更新

• 5.1 检查 cmd/api/docs.go 和 cmd/gendocs/main.go 中 AgentRechargeHandler 的注册方式（本次未新增 Handler，仅修改已有请求体，确认无需额外改动）

6. 接口验证

• 6.1 调用 POST /api/admin/agent-recharges（payment_method=offline，不传凭证），验证返回 400"线下充值必须上传支付凭证"
• 6.2 调用 POST /api/admin/agent-recharges（payment_method=offline，传入合法凭证 key），验证返回 200，使用 PostgreSQL MCP 查询 tb_agent_recharge_record 确认 payment_voucher_key 字段已写入正确值
• 6.3 调用 POST /api/admin/agent-recharges（payment_method=wechat，不传凭证），验证正常创建成功，无凭证校验报错