Files
junhong_cmp_fiber/internal/routes/package_silence.go
邹进 909f4d0ec2
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Failing after 8m39s
feat: 实名即生效套餐沉默期、延期办理与资产出库时间
- 迁移 000259~000265:套餐记录沉默期字段与扫描索引、套餐默认沉默期、延期政策/流水/订单/批次/明细 5 张表、默认政策与系统配置(总开关默认关闭)、企微审批白名单、卡与设备出库时间及出库记录
- 沉默期设置(订单发放、自动购包、钱包续费)、后台购买时调整(超默认值按政策免审或企微审批)、统一判定与激活闸门、排队与孤儿扫描跳过过期套餐、过期套餐禁止退款、每 10 分钟扫描
- 总开关专用接口与打开前 4 项检查;延期政策;延期资格与计费;H5 自助与后台二维码在线支付(商户池路由)、支付回调与查单恢复、线下登记、特殊/批量延期、异常重试与原路退款;沉默期审批场景与终态处理
- 换货沉默期流水与出库时间;卡/设备列表、详情、导出与出库记录接口;延期订单与即将过期套餐列表及导出;财务流水纳入延期支付
- 沉默期与出库时间回填工具 cmd/silence-backfill;前端接口变更说明

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 16:32:58 +09:00

139 lines
11 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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: "延期订单详情", Tags: extTags, Input: new(dto.SilenceIDPath), 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/outbound-records", handler.ListOutboundRecords, RouteSpec{
Summary: "资产出库记录", Description: "按资产查看各世代出库记录(出库时间、来源、订单号或换货单号、结束时间与原因);只读。",
Tags: []string{"资产 - 出库时间"}, Input: new(dto.AssetOutboundRecordRequest), Output: new([]dto.AssetOutboundRecordResponse), 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: "我的延期订单详情", Tags: tags, Input: new(dto.SilenceIDPath), 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,
})
}