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, }) }