junhong_cmp_fiber/internal/routes/refund.go

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"
)

// registerRefundRoutes 注册退款管理路由
// 平台和代理账号可访问，企业账号禁止访问
func registerRefundRoutes(router fiber.Router, handler *admin.RefundHandler, doc *openapi.Generator, basePath string) {
	refund := router.Group("/refunds", func(c *fiber.Ctx) error {
		userType := middleware.GetUserTypeFromContext(c.UserContext())
		if userType != constants.UserTypeSuperAdmin &&
			userType != constants.UserTypePlatform &&
			userType != constants.UserTypeAgent {
			return errors.New(errors.CodeForbidden, "无权限访问退款管理功能")
		}
		return c.Next()
	})
	groupPath := basePath + "/refunds"

	Register(refund, doc, groupPath, "POST", "", handler.Create, RouteSpec{
		Summary:     "创建退款申请",
		Description: "实收金额由系统从原成功支付记录或订单实际收款派生并冻结，请求体中的 actual_received_amount 已废弃并被忽略。退款方式必填：原路退款、退回资产钱包、退回代理主钱包按各自资金路径执行，客户收款信息退款需同时提供 customer_account_info 与退款凭证；非客户收款信息方式的客户收款信息与凭证不参与校验。",
		Tags:        []string{"退款管理"},
		Input:       new(dto.CreateRefundRequest),
		Output:      new(dto.RefundResponse),
		Auth:        true,
	})

	Register(refund, doc, groupPath, "GET", "", handler.List, RouteSpec{
		Summary: "退款申请列表",
		Tags:    []string{"退款管理"},
		Input:   new(dto.RefundListRequest),
		Output:  new(dto.RefundListResponse),
		Auth:    true,
	})

	// 字面量路径必须先于同段参数路由 /:id 注册：Fiber 按注册顺序匹配，若 /:id 在前，
	// "order-options" 会被当作退款申请 ID 解析而永远命中不到本端点。
	// 该端点留在 /refunds 组内，以继承既有组级门禁（超管/平台/代理，企业账号拒绝）。
	Register(refund, doc, groupPath, "GET", "/order-options", handler.OrderOptions, RouteSpec{
		Summary:     "按来源订单查询可选退款方式",
		Description: "只读查询，不产生任何副作用。复用创建与重提使用的方式判定与原路可退的凭证判定，不新增第二套判定；判定所需事实缺失时返回不可用原因而非报错。查询受订单数据范围约束，越权与订单不存在不可区分。",
		Tags:        []string{"退款管理"},
		Input:       new(dto.RefundOrderOptionsRequest),
		Output:      new(dto.RefundOrderOptionsResponse),
		Auth:        true,
	})

	Register(refund, doc, groupPath, "GET", "/:id", handler.GetByID, RouteSpec{
		Summary: "退款申请详情",
		Tags:    []string{"退款管理"},
		Input:   new(dto.RefundIDRequest),
		Output:  new(dto.RefundResponse),
		Auth:    true,
	})

	Register(refund, doc, groupPath, "POST", "/:id/trigger-approval", handler.TriggerApproval, RouteSpec{
		Summary: "补发历史退款审批",
		Tags:    []string{"退款管理"},
		Input:   new(dto.RefundIDRequest),
		Output:  new(dto.RefundResponse),
		Auth:    true,
	})

	Register(refund, doc, groupPath, "POST", "/:id/approve", handler.Approve, RouteSpec{
		Summary: "审批通过退款申请",
		Tags:    []string{"退款管理"},
		Input:   new(dto.ApproveRefundRequest),
		Output:  nil,
		Auth:    true,
	})

	Register(refund, doc, groupPath, "POST", "/:id/reject", handler.Reject, RouteSpec{
		Summary: "审批拒绝退款申请",
		Tags:    []string{"退款管理"},
		Input:   new(dto.RejectRefundRequest),
		Output:  nil,
		Auth:    true,
	})

	Register(refund, doc, groupPath, "POST", "/:id/return", handler.Return, RouteSpec{
		Summary: "退回退款申请",
		Tags:    []string{"退款管理"},
		Input:   new(dto.ReturnRefundRequest),
		Output:  nil,
		Auth:    true,
	})

	Register(refund, doc, groupPath, "POST", "/:id/resubmit", handler.Resubmit, RouteSpec{
		Summary:     "重新提交退款申请",
		Description: "仅已拒绝、已退回或原路退款失败且无审批异常的退款申请可重提；重提时实收金额仍由系统重新派生冻结并忽略请求中的 actual_received_amount，退款原因去除首尾空白后不得为空，每次重提新增一条审批尝试记录并创建新的企业微信审批实例，历史尝试材料与审批结果不被覆盖。",
		Tags:        []string{"退款管理"},
		Input:       new(dto.ResubmitRefundRequest),
		Output:      nil,
		Auth:        true,
	})

	Register(refund, doc, groupPath, "POST", "/:id/offline-settlement", handler.RegisterOfflineSettlement, RouteSpec{
		Summary:     "登记线下退款处理流水号",
		Description: "仅客户收款信息退款（线下到账方式）可登记；重复提交即更正，历史值由审计留存。登记只写线下处理流水号与登记人、登记时间，不改变退款状态、实收金额、套餐失效与佣金回溯规则。",
		Tags:        []string{"退款管理"},
		Input:       new(dto.OfflineSettlementRequest),
		Output:      new(dto.RefundResponse),
		Auth:        true,
	})
}