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

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

internal/handler/admin/agent_recharge.go

@@ -4,12 +4,14 @@ import (
 	"bytes"
 	"strconv"
 	"strings"
+	"time"
 
 	"github.com/bytedance/sonic"
 	"github.com/go-playground/validator/v10"
 	"github.com/gofiber/fiber/v2"
 
 	agentrechargeapp "github.com/break/junhong_cmp_fiber/internal/application/agentrecharge"
+	systemconfigapp "github.com/break/junhong_cmp_fiber/internal/application/systemconfig"
 	"github.com/break/junhong_cmp_fiber/internal/model/dto"
 	agentrechargequery "github.com/break/junhong_cmp_fiber/internal/query/agentrecharge"
 	agentRechargeSvc "github.com/break/junhong_cmp_fiber/internal/service/agent_recharge"
@@ -24,6 +26,8 @@ type AgentRechargeHandler struct {
 	service   *agentRechargeSvc.Service
 	online    *agentrechargeapp.OnlineCreationService
 	status    *agentrechargequery.PaymentStatusQuery
+	ocr       *agentrechargeapp.PaymentVoucherOCRService
+	config    *systemconfigapp.UpdateService
 	validator *validator.Validate
 }
 
@@ -37,6 +41,16 @@ func (h *AgentRechargeHandler) SetPaymentStatusQuery(query *agentrechargequery.P
 	h.status = query
 }
 
+// SetPaymentVoucherOCRService 注入付款凭证识别用例。
+func (h *AgentRechargeHandler) SetPaymentVoucherOCRService(service *agentrechargeapp.PaymentVoucherOCRService) {
+	h.ocr = service
+}
+
+// SetSystemConfigUpdateService 注入受控系统配置写服务，用于代理自充允许范围修改。
+func (h *AgentRechargeHandler) SetSystemConfigUpdateService(service *systemconfigapp.UpdateService) {
+	h.config = service
+}
+
 // NewAgentRechargeHandler 创建代理预充值 Handler
 func NewAgentRechargeHandler(service *agentRechargeSvc.Service, validator *validator.Validate) *AgentRechargeHandler {
 	return &AgentRechargeHandler{service: service, validator: validator}
@@ -73,8 +87,9 @@ func (h *AgentRechargeHandler) createOnline(c *fiber.Ctx, req dto.CreateAgentRec
 	if h.online == nil {
 		return errors.New(errors.CodeServiceUnavailable, "代理在线充值能力未配置")
 	}
-	if req.ShopID != nil || len(req.PaymentVoucherKey) > 0 || strings.TrimSpace(req.Remark) != "" {
-		return errors.New(errors.CodeInvalidParam, "在线充值不能指定店铺、支付凭证或运营备注")
+	if req.ShopID != nil || len(req.PaymentVoucherKey) > 0 || len(req.OtherVoucherKey) > 0 ||
+		req.OfflinePaymentMethodID != 0 || strings.TrimSpace(req.ExternalTransactionNo) != "" || strings.TrimSpace(req.Remark) != "" {
+		return errors.New(errors.CodeInvalidParam, "在线充值不能指定店铺、收款方式、交易流水号、支付凭证或运营备注")
 	}
 	result, err := h.online.Execute(c.UserContext(), agentrechargeapp.CreateOnlineCommand{
 		AccountID: middleware.GetUserIDFromContext(c.UserContext()), UserType: middleware.GetUserTypeFromContext(c.UserContext()),
@@ -108,6 +123,69 @@ func (h *AgentRechargeHandler) PaymentMethods(c *fiber.Ctx) error {
 	})
 }
 
+// SelfRechargePaymentMethods 查询代理自充实际可用支付方式。
+// GET /api/admin/agent-self-recharge-payment-methods
+// 响应只含交集结果，不含允许范围、商户身份或凭证。
+func (h *AgentRechargeHandler) SelfRechargePaymentMethods(c *fiber.Ctx) error {
+	return h.PaymentMethods(c)
+}
+
+// UpdateSelfRechargePaymentMethods 修改代理在线自充允许范围。
+// PUT /api/admin/agent-self-recharge-payment-methods
+// 复用受控系统配置写服务，获得超级管理员限定、咨询锁串行与前后值审计。
+func (h *AgentRechargeHandler) UpdateSelfRechargePaymentMethods(c *fiber.Ctx) error {
+	var req dto.AgentSelfRechargePaymentMethodsUpdateRequest
+	decoder := sonic.ConfigStd.NewDecoder(bytes.NewReader(c.Body()))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	if err := h.validator.Struct(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if h.config == nil {
+		return errors.New(errors.CodeServiceUnavailable, "代理自充允许范围维护能力未配置")
+	}
+	item, err := h.config.Execute(c.UserContext(), constants.SystemConfigAgentSelfRechargeAllowedMethods,
+		dto.UpdateSystemConfigRequest{Value: req.AllowedMethods})
+	if err != nil {
+		return err
+	}
+	updatedAt := ""
+	if item.UpdatedAt != nil {
+		updatedAt = item.UpdatedAt.UTC().Format(time.RFC3339)
+	}
+	return response.Success(c, &dto.AgentSelfRechargePaymentMethodsUpdateResponse{
+		AllowedMethods: item.Value, AllowedMethodsName: constants.GetAgentSelfRechargeAllowedMethodsName(item.Value),
+		UpdatedAt: updatedAt,
+	})
+}
+
+// PaymentVoucherOCR 识别付款凭证，只返回交易流水号预填值。
+// POST /api/admin/agent-recharges/payment-voucher-ocr
+// 识别失败返回明确失败，不影响提交人人工填写交易流水号后创建申请。
+func (h *AgentRechargeHandler) PaymentVoucherOCR(c *fiber.Ctx) error {
+	var req dto.AgentRechargePaymentVoucherOCRRequest
+	decoder := sonic.ConfigStd.NewDecoder(bytes.NewReader(c.Body()))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	if err := h.validator.Struct(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if h.ocr == nil {
+		return errors.New(errors.CodeServiceUnavailable, "付款凭证识别能力未配置")
+	}
+	result, err := h.ocr.Recognize(c.UserContext(), req.PaymentVoucherKey)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, &dto.AgentRechargePaymentVoucherOCRResponse{
+		ExternalTransactionNo: result.ExternalTransactionNo,
+	})
+}
+
 // List 查询代理充值订单列表
 // GET /api/admin/agent-recharges
 func (h *AgentRechargeHandler) List(c *fiber.Ctx) error {