junhong_cmp_fiber/openspec/changes/add-agent-self-recharge-payment-methods/tasks.md

1. 允许范围与交集

• 1.1 在 pkg/constants/system_config.go 新增代理在线自充允许方式的配置 Key 与三个稳定取值常量，默认值为同时支持；在 internal/bootstrap 按既有支付方式配置注册该 Key，使用 ValueType=string 与 EnumValues 约束取值。
• 1.2 实现允许范围的读取封装：以 systemconfig.Reader.GetStrict 读取并把取值映射为允许的 wechat/alipay 集合，配置未落库时使用代码注册默认值，配置非法时失败关闭。
• 1.3 在 internal/application/agentrecharge/online_creation.go 的 AvailablePaymentMethods 中把可见角色从仅代理放开为代理与平台账号，并将返回方式改为"允许范围 ∩ 商户池可用方式"的有序列表；交集为空时返回空列表而不报错。
• 1.4 在 OnlineCreationService.Execute 的域校验之后、读取店铺事实之前加入允许范围校验，拒绝不在交集内的支付方式，且不新建充值单或支付单；确认无可用商户时既有 CodeNoPaymentConfig 失败路径保持不回退历史支付配置。
• 1.5 新增 GET /agent-self-recharge-payment-methods（代理与平台账号可查实际可用方式）与 PUT /agent-self-recharge-payment-methods（仅超级管理员，复用受控配置写服务以获得前后值审计），注册为 /api/admin 下的独立单段路由组并在组内显式声明读写角色门禁（需求路径与既有 /api/admin/agent-recharges 前缀不同，无法继承该组的企业账号门禁），并确保响应不包含允许范围、商户身份或凭证。

2. 线下预存款审批字段与 Schema

• 2.1 新增成对迁移为 tb_agent_recharge_record 增加 external_transaction_no、offline_payment_method_id、offline_payment_method_code、offline_payment_method_name 与 other_voucher_keys 列（含注释与查询索引），保持可空以兼容历史行；不修改任何既有迁移，不新增唯一约束，不改动既有 payment_transaction_id 的定义与写入方。
• 2.2 扩展 OfflineCreationCommand 与线下创建用例：接收并校验启用的线下收款方式字典项（不存在或已停用即拒绝）、必填的交易流水号（取值来自识别支付单号并经人工确认）与可选其他凭证，在同一事务保存收款方式三列快照、交易流水号与其他凭证对象键，并保持既有审批实例关联与审计不变；交易流水号不得参与去重或入账前置判定。
• 2.3 确认交易流水号写入路径与在线渠道事实隔离：external_transaction_no 的写入 MUST NOT 触碰 payment_transaction_id、payment_channel、支付状态与钱包，且不影响 Outbox 入账消费者的对账判定。
• 2.4 扩展 internal/application/wecom/scene.go 中 offline_recharge_approval 的可映射业务字段白名单，加入线下收款方式与其他凭证字段，并在审批请求快照中带入对应值；不修改其他场景的字段定义与业务类型 CHECK。
• 2.5 扩展线下收款方式字典的"被引用"判定，使已被代理充值申请引用的字典项不可物理删除且编码不可修改，仅可停用；不改变员工账单建账、核销申请、分摊与退款冲销逻辑。
• 2.6 在代理充值详情与列表投影中返回收款方式快照、交易流水号与其他凭证对象键引用，且不返回凭证内容。

3. 付款凭证识别预填

• 3.1 在 internal/gateway 新增付款凭证识别能力，封装识别接口并按需传入 image_base64；不使用会打印完整响应体的泛型入口，改为自行反序列化并只记录路径、耗时与结果摘要。
• 3.2 实现应用层识别用例：按附件对象键读取对象存储、校验对象存在非空且为图片类型、编码为 base64 后调用 Gateway，只将 order_number 返回为交易流水号预填值；amount、remark、payment_method、payee 与 payment_time 均不返回、不预填、不写入任何业务字段。识别结果不落库、不写入任何资金事实字段。
• 3.3 新增 POST /agent-recharges/payment-voucher-ocr 路由与 Handler，复用既有代理充值组门禁，成功响应只含交易流水号预填值；非图片、对象不存在或识别服务失败时返回明确失败且不阻断人工填写。
• 3.4 确认识别调用路径的日志、审计与错误不包含凭证内容、base64 载荷或识别原始结果。

4. 路由、文档与装配

• 4.1 为新增的两个端点补齐可执行路由注册、cmd/api/docs.go 与 cmd/gendocs/main.go 的占位装配，以及 pkg/openapi/handlers.go、internal/bootstrap/types.go、internal/bootstrap/handlers.go 的 Handler 装配（沿用既有代理充值 Handler 时确认无需新增装配点）。
• 4.2 按 ENG-DTO-001 补齐请求与响应 DTO 的中文 description、枚举与 pkg/constants 一致，金额使用分，时间使用带时区 RFC3339。
• 4.3 更新 docs/integrations/gateway/README.md 的当前实际使用范围与核验证据，纳入付款凭证识别能力；不得写入凭证、密钥或识别样本。
• 4.4 为允许范围修改复用既有受控配置审计动作并在 Change 内确认审计覆盖；新增的申请创建与识别调用按 ENG-AUDIT-001 归入既有事实类型，不新增重复事实。

5. 验证

• 5.1 按 ENG-TEST-001 在维护者指定的 junhong_cmp_test PostgreSQL 与 Redis DB 6 上验证：迁移从本地工作区以显式 DB_* 执行 scripts/migrate.sh，只创建、删除本 Change 自己的 fixture，禁止重置整库。
• 5.2 验证允许范围：三态取值可维护并留痕、非法取值被拒、未配置时使用默认值、非超级管理员不可读不可写。
• 5.3 验证交集：允许范围收窄后查询只返回被允许方式；允许方式无可用商户池成员时查询返回空列表且创建被拒绝、不新建充值单或支付单；配置变更后已创建未支付单的支付方式与商户快照不变。
• 5.4 验证线下字段：引用不存在或已停用收款方式被拒、收款方式快照在改名与停用后保持冻结、缺少交易流水号被拒、重复交易流水号不阻断线下申请、企业微信审批或钱包入账，且不改变 payment_transaction_id、payment_channel、支付状态、钱包或 Outbox 入账消费者的对账判定；支付凭证与其他凭证分别留存并可在审批详情取得。
• 5.5 验证识别预填：图片凭证识别成功后返回预填值且未创建申请、人工更正值生效、非图片与识别失败不阻断人工填写、日志与审计不含凭证内容或识别原始结果。
• 5.6 验证字典引用保护：被代理充值引用的字典项不可删除、编码不可修改、仅可停用。
• 5.7 执行 gofmt -w、go build ./cmd/api ./cmd/worker、go run cmd/gendocs/main.go、./scripts/context-health.sh、openspec validate add-agent-self-recharge-payment-methods --strict 与 openspec doctor --json；上述全局健康门禁必须一并通过，自动化测试按项目决策为 N/A。
• 5.8 仅在本 Change fixture 已清理、且维护者确认新增收款方式、交易流水号与凭证快照没有留存需求时验证迁移 up/down/up；down 可以删除新增列，但不得影响既有充值记录读取。存在仍需保留的真实新增列数据时不得将 down 视为正常可执行场景，MUST NOT 重置整个 junhong_cmp_test。