feat(代理自充): AUG26-017 代理自充收款方式与线下预存款审批字段

- 受控配置新增代理在线自充允许范围（仅微信/仅支付宝/同时支持），读侧与创建侧取允许范围与可用商户池交集，两侧失败关闭
- 新增允许范围查询与修改端点，读限代理与平台账号、写限超级管理员，复用受控配置写服务留痕
- tb_agent_recharge_record 新增交易流水号、线下收款方式三列快照与其他凭证列（成对迁移 000213）
- 线下申请校验启用的收款方式字典项与必填交易流水号，交易流水号独立于在线渠道交易号、不参与去重
- 扩展 offline_recharge_approval 场景可映射字段白名单与字典引用保护
- 新增付款凭证识别能力与交易流水号预填接口，识别不落库、日志不记录载荷

internal/routes/admin.go

@@ -135,6 +135,7 @@ func RegisterAdminRoutes(router fiber.Router, handlers *bootstrap.Handlers, midd
 		registerEmployeeCollectionApplicationRoutes(authGroup, handlers.EmployeeCollection, doc, basePath)
 	}
 	if handlers.AgentRecharge != nil {
+		registerAgentSelfRechargePaymentMethodRoutes(authGroup, handlers.AgentRecharge, doc, basePath)
 		registerAgentRechargeRoutes(authGroup, handlers.AgentRecharge, doc, basePath)
 	}
 	if handlers.Refund != nil {

internal/routes/agent_recharge.go

@@ -45,6 +45,15 @@ func registerAgentRechargeRoutes(router fiber.Router, handler *admin.AgentRechar
 		Auth:    true,
 	})
 
+	Register(group, doc, groupPath, "POST", "/payment-voucher-ocr", handler.PaymentVoucherOCR, RouteSpec{
+		Summary:     "识别付款凭证中的交易流水号",
+		Description: "按付款凭证对象键调用识别能力，只返回交易流水号预填值供人工确认或更正；识别结果不写入任何资金事实，失败不阻断人工填写。",
+		Tags:        []string{"代理预充值"},
+		Input:       new(dto.AgentRechargePaymentVoucherOCRRequest),
+		Output:      new(dto.AgentRechargePaymentVoucherOCRResponse),
+		Auth:        true,
+	})
+
 	Register(group, doc, groupPath, "GET", "/:id/payment-status", handler.PaymentStatus, RouteSpec{
 		Summary: "查询代理充值本地支付与到账状态",
 		Tags:    []string{"代理预充值"},

internal/routes/agent_self_recharge_payment_method.go

@@ -0,0 +1,49 @@
+package routes
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+	"github.com/break/junhong_cmp_fiber/pkg/openapi"
+)
+
+// registerAgentSelfRechargePaymentMethodRoutes 注册代理自充允许范围读取与修改路由。
+// 读取对代理与平台账号开放，返回的是允许范围与可用商户池的交集；修改仅超级管理员可用。
+// 该路径不在代理充值业务组内，因此读取与写入的角色门禁在此显式声明。
+func registerAgentSelfRechargePaymentMethodRoutes(router fiber.Router, handler *admin.AgentRechargeHandler, doc *openapi.Generator, basePath string) {
+	group := router.Group("/agent-self-recharge-payment-methods", func(c *fiber.Ctx) error {
+		userType := middleware.GetUserTypeFromContext(c.UserContext())
+		if c.Method() == fiber.MethodPut {
+			if userType != constants.UserTypeSuperAdmin {
+				return errors.New(errors.CodeForbidden, "仅超级管理员可以修改代理自充允许范围")
+			}
+			return c.Next()
+		}
+		if userType != constants.UserTypeAgent && userType != constants.UserTypePlatform {
+			return errors.New(errors.CodeForbidden, "仅代理或平台账号可以查询代理自充可用支付方式")
+		}
+		return c.Next()
+	})
+	groupPath := basePath + "/agent-self-recharge-payment-methods"
+
+	Register(group, doc, groupPath, "GET", "", handler.SelfRechargePaymentMethods, RouteSpec{
+		Summary:     "查询代理自充实际可用支付方式",
+		Description: "返回超级管理员允许范围与当前可用商户池支付方式的交集，固定顺序；交集为空时返回空列表且不报错。响应不含允许范围本身、商户身份或凭证。",
+		Tags:        []string{"代理预充值"},
+		Output:      new(dto.AgentRechargePaymentMethodsResponse),
+		Auth:        true,
+	})
+
+	Register(group, doc, groupPath, "PUT", "", handler.UpdateSelfRechargePaymentMethods, RouteSpec{
+		Summary:     "修改代理在线自充允许范围",
+		Description: "仅超级管理员可修改，取值仅限仅微信、仅支付宝、同时支持；每次修改记录操作者、修改前后值与时间，且只影响后续新单。",
+		Tags:        []string{"代理预充值"},
+		Input:       new(dto.AgentSelfRechargePaymentMethodsUpdateRequest),
+		Output:      new(dto.AgentSelfRechargePaymentMethodsUpdateResponse),
+		Auth:        true,
+	})
+}