package routes import ( "github.com/gofiber/fiber/v2" "github.com/break/junhong_cmp_fiber/internal/handler/admin" apphandler "github.com/break/junhong_cmp_fiber/internal/handler/app" "github.com/break/junhong_cmp_fiber/internal/model/dto" "github.com/break/junhong_cmp_fiber/pkg/openapi" ) // silenceSwitchDoc 是总开关对延期接口的影响说明。 const silenceSwitchDoc = "\n\n沉默期总开关关闭时返回错误码 1274(silence_feature_disabled);已发生的支付回调、查单与审批回调不受开关影响。" // registerPackageSilenceRoutes 注册后台沉默期接口(add-package-silence-period)。 func registerPackageSilenceRoutes(router fiber.Router, handler *admin.PackageSilenceHandler, doc *openapi.Generator, basePath string) { group := router.Group("/package-silence") path := basePath + "/package-silence" tags := []string{"沉默期"} Register(group, doc, path, "GET", "/switch", handler.GetSwitch, RouteSpec{ Summary: "查询沉默期总开关", Description: "返回总开关当前值与打开前 4 项检查结果(未配置默认沉默期的套餐、未回填记录、全部套餐延期政策、企微审批场景)。", Tags: tags, Input: nil, Output: new(dto.SilenceSwitchResponse), Auth: true, }) Register(group, doc, path, "PUT", "/switch", handler.UpdateSwitch, RouteSpec{ Summary: "切换沉默期总开关(仅超级管理员)", Description: "打开前逐项检查,任一项不满足返回 1275(silence_switch_precheck_failed),data.failed_items 为未满足项与数量;" + "关闭(应急)不检查:规则暂停、数据保留。每次切换写审计 package.silence_switch_changed。", Tags: tags, Input: new(dto.SilenceSwitchRequest), Output: new(dto.SilenceSwitchResponse), Auth: true, }) policyTags := []string{"沉默期 - 延期政策"} Register(group, doc, path, "GET", "/policies", handler.ListPolicies, RouteSpec{ Summary: "延期政策列表", Description: "需 package_silence:policy 权限。", Tags: policyTags, Input: new(dto.SilencePolicyListRequest), Output: new([]dto.SilencePolicyResponse), Auth: true, }) Register(group, doc, path, "GET", "/policies/match", handler.MatchPolicy, RouteSpec{ Summary: "查询套餐当前匹配的延期政策", Description: "优先级:指定套餐 > 套餐系列 > 全部套餐;只匹配启用且在生效期内的政策。", Tags: policyTags, Input: new(dto.SilencePolicyMatchRequest), Output: new(dto.SilencePolicyMatchResponse), Auth: true, }) Register(group, doc, path, "GET", "/policies/:id", handler.GetPolicy, RouteSpec{ Summary: "延期政策详情", Tags: policyTags, Input: new(dto.SilenceIDPath), Output: new(dto.SilencePolicyResponse), Auth: true, }) Register(group, doc, path, "POST", "/policies", handler.CreatePolicy, RouteSpec{ Summary: "新增延期政策", Description: "同一优先级的适用范围与生效时间段不能重叠,重叠返回 1269(silence_policy_overlap)。修改只影响之后发起的延期。", Tags: policyTags, Input: new(dto.SilencePolicyRequest), Output: new(dto.SilencePolicyResponse), Auth: true, }) Register(group, doc, path, "PUT", "/policies/:id", handler.UpdatePolicy, RouteSpec{ Summary: "编辑延期政策", Description: "全量提交字段;已创建的延期订单与已提交的审批按快照执行。", Tags: policyTags, Input: new(dto.SilencePolicyUpdateParams), Output: new(dto.SilencePolicyResponse), Auth: true, }) Register(group, doc, path, "PUT", "/policies/:id/status", handler.UpdatePolicyStatus, RouteSpec{ Summary: "启停延期政策", Description: "启用时同样做重叠校验。", Tags: policyTags, Input: new(dto.SilencePolicyStatusParams), Output: new(dto.SilencePolicyResponse), Auth: true, }) extTags := []string{"沉默期 - 延期"} Register(group, doc, path, "GET", "/eligibility", handler.Eligibility, RouteSpec{ Summary: "延期资格", Description: "待实名但已到期的先判定为过期;返回最少 / 最多天数与月数、单价、各月数档位;金额全部由后端计算。" + silenceSwitchDoc, Tags: extTags, Input: new(dto.SilenceEligibilityRequest), Output: new(dto.SilenceEligibilityResponse), Auth: true, }) Register(group, doc, path, "GET", "/quote", handler.Quote, RouteSpec{ Summary: "按天数试算付费延期", Description: "按每月 30 天向上取整计费(1 天按 30 天,31 天按 60 天),延长天数等于计费天数。" + silenceSwitchDoc, Tags: extTags, Input: new(dto.SilenceQuoteRequest), Output: new(dto.SilenceQuoteResponse), Auth: true, }) Register(group, doc, path, "POST", "/orders/qrcode", handler.CreateQRCodeOrder, RouteSpec{ Summary: "运营创建在线延期订单并生成支付二维码", Description: "需 package_silence:extend 权限;商户按支付方式经商户池路由并冻结;返回 qr_content 由前端渲染为二维码,客户扫码支付后自动延期,不审批。" + "同一套餐已有待支付订单时先查单:未支付则关闭旧单再新建,已支付则按已支付处理并返回旧单。" + silenceSwitchDoc, Tags: extTags, Input: new(dto.SilenceOnlineOrderRequest), Output: new(dto.SilenceExtensionOrderResponse), Auth: true, }) Register(group, doc, path, "POST", "/orders/offline", handler.RegisterOffline, RouteSpec{ Summary: "登记线下付费延期", Description: "需 package_silence:offline 权限;实收金额必须等于系统计算金额(1273),同一收款方式下交易单号唯一(1272);" + "政策未勾选 offline_paid 免审批时提交企微审批,通过后延期,驳回订单 rejected 且系统不退款。" + silenceSwitchDoc, Tags: extTags, Input: new(dto.SilenceOfflineOrderRequest), Output: new(dto.SilenceExtensionOrderResponse), Auth: true, }) Register(group, doc, path, "GET", "/orders", handler.ListOrders, RouteSpec{ Summary: "延期订单列表", Description: "叠加店铺数据范围;支付方式、收款商户、交易流水号取已支付或已退款支付单快照。导出使用统一导出任务,场景 package_silence_order,筛选参数同本接口。", Tags: extTags, Input: new(dto.SilenceOrderListRequest), Output: new(dto.SilenceOrderPageResult), Auth: true, }) Register(group, doc, path, "GET", "/orders/:id", handler.GetOrder, RouteSpec{ Summary: "延期订单详情", Description: "待支付且未过支付截止的订单返回 qr_content,可继续扫码支付。", Tags: extTags, Input: new(dto.SilenceIDPath), Output: new(dto.SilenceExtensionOrderResponse), Auth: true, }) Register(group, doc, path, "POST", "/orders/:id/close", handler.CloseOrder, RouteSpec{ Summary: "作废待支付延期订单", Description: "需 package_silence:extend 权限,只能作废数据范围内待支付的在线订单。作废前先查单:渠道已支付则按支付成功办理延期并拒绝作废;" + "作废后同一套餐可重新下单,作废后才到达的支付进入异常并原路退款。", Tags: extTags, Input: new(dto.SilenceOrderCancelRequest), Output: new(dto.SilenceExtensionOrderResponse), Auth: true, }) Register(group, doc, path, "POST", "/special", handler.SubmitSpecial, RouteSpec{ Summary: "提交特殊延期(单个 / 批量)", Description: "需 package_silence:extend 权限,批量(多条或导入文件)另需 package_silence:extend_batch;免费延期受政策次数约束(1267);" + "不受付费上限与套餐是否支持延期约束,只要求新截止晚于今天。政策未勾选对应免审批场景(批量看 batch)时提交企微审批,通过后逐条执行。" + silenceSwitchDoc, Tags: extTags, Input: new(dto.SilenceSpecialRequest), Output: new(dto.SilenceBatchResponse), Auth: true, }) Register(group, doc, path, "GET", "/batches", handler.ListBatches, RouteSpec{ Summary: "延期批次列表", Tags: extTags, Input: new(dto.SilenceBatchListRequest), Output: new(dto.SilenceBatchPageResult), Auth: true, }) Register(group, doc, path, "GET", "/batches/:id", handler.GetBatch, RouteSpec{ Summary: "延期批次详情(含明细)", Tags: extTags, Input: new(dto.SilenceIDPath), Output: new(dto.SilenceBatchResponse), Auth: true, }) Register(group, doc, path, "POST", "/extensions/:id/handle", handler.HandleException, RouteSpec{ Summary: "处理异常延期明细", Description: "需 package_silence:exception 权限;retry 按原快照重新执行,close 关闭(在线订单按冻结商户原路退款)。不得直接改截止时间。", Tags: extTags, Input: new(dto.SilenceExceptionHandleParams), Output: new(dto.SilenceExtensionResponse), Auth: true, }) Register(group, doc, path, "GET", "/records", handler.ListRecords, RouteSpec{ Summary: "套餐沉默期流水", Description: "设置、调整、过期、结束、延期、换货迁移、回填等不可变流水。", Tags: tags, Input: new(dto.SilenceRecordListRequest), Output: new([]dto.SilenceRecordResponse), Auth: true, }) Register(group, doc, path, "GET", "/usages", handler.ListUsages, RouteSpec{ Summary: "即将过期 / 已过期套餐", Description: "view=expiring(默认 7 天内到期)/ expired / all;导出使用统一导出任务,场景 package_silence_usage,筛选参数同本接口。", Tags: tags, Input: new(dto.SilenceUsageListRequest), Output: new(dto.SilenceUsagePageResult), Auth: true, }) Register(router, doc, basePath, "GET", "/assets/:asset_type/:id/first-purchase-records", handler.ListFirstPurchaseRecords, RouteSpec{ Summary: "资产首次购买套餐记录", Description: "按资产查看各世代首次购买套餐记录(首次购买套餐时间、来源(首次购买套餐 / 历史回填)、订单号、结束时间与原因);换货后的新资产在当前世代真正购买套餐后才有记录;只读。", Tags: []string{"资产 - 首次购买套餐时间"}, Input: new(dto.AssetFirstPurchaseRecordRequest), Output: new([]dto.AssetFirstPurchaseRecordResponse), Auth: true, }) } // registerPersonalPackageSilenceRoutes 注册 H5 沉默期延期接口。 func registerPersonalPackageSilenceRoutes(router fiber.Router, handler *apphandler.ClientPackageSilenceHandler, doc *openapi.Generator, basePath string) { group := router.Group("/package-silence") path := basePath + "/package-silence" tags := []string{"个人客户 - 沉默期延期"} Register(group, doc, path, "GET", "/eligibility", handler.Eligibility, RouteSpec{ Summary: "延期资格", Description: "资产须属于当前客户;套餐沉默期已过期(资产套餐历史 silence.extendable=true)时显示延期入口。" + silenceSwitchDoc, Tags: tags, Input: new(dto.SilenceEligibilityRequest), Output: new(dto.SilenceEligibilityResponse), Auth: true, }) Register(group, doc, path, "GET", "/quote", handler.Quote, RouteSpec{ Summary: "按天数试算", Description: "按每月 30 天向上取整计费。" + silenceSwitchDoc, Tags: tags, Input: new(dto.SilenceQuoteRequest), Output: new(dto.SilenceQuoteResponse), Auth: true, }) Register(group, doc, path, "POST", "/orders", handler.CreateOrder, RouteSpec{ Summary: "自助下单付费延期", Description: "返回 qr_content(支付链接 / 二维码内容);支付成功后自动延期,不审批,不从代理钱包扣款。" + silenceSwitchDoc, Tags: tags, Input: new(dto.SilenceOnlineOrderRequest), Output: new(dto.SilenceExtensionOrderResponse), Auth: true, }) Register(group, doc, path, "GET", "/orders", handler.ListOrders, RouteSpec{ Summary: "我的延期订单", Tags: tags, Input: new(dto.SilenceOrderListRequest), Output: new(dto.SilenceOrderPageResult), Auth: true, }) Register(group, doc, path, "GET", "/orders/:id", handler.GetOrder, RouteSpec{ Summary: "我的延期订单详情", Description: "待支付且未过支付截止的订单返回 qr_content,可继续支付。", Tags: tags, Input: new(dto.SilenceIDPath), Output: new(dto.SilenceExtensionOrderResponse), Auth: true, }) Register(group, doc, path, "POST", "/orders/:id/cancel", handler.CancelOrder, RouteSpec{ Summary: "作废我的待支付延期订单", Description: "只能作废自己的待支付订单。作废前先查单:已支付则按支付成功办理延期并拒绝作废;作废后可重新下单。", Tags: tags, Input: new(dto.SilenceOrderCancelRequest), Output: new(dto.SilenceExtensionOrderResponse), Auth: true, }) Register(group, doc, path, "GET", "/records", handler.ListRecords, RouteSpec{ Summary: "套餐沉默期流水", Tags: tags, Input: new(dto.SilenceRecordListRequest), Output: new([]dto.SilenceRecordResponse), Auth: true, }) }