feat: 实名即生效套餐沉默期、延期办理与资产出库时间
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Failing after 8m39s

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
邹进
2026-10-27 16:32:58 +09:00
parent d2b0d2f534
commit 909f4d0ec2
112 changed files with 10473 additions and 82 deletions

View File

@@ -136,6 +136,9 @@ func RegisterAdminRoutes(router fiber.Router, handlers *bootstrap.Handlers, midd
if handlers.PollingConfig != nil {
registerPollingConfigRoutes(authGroup, handlers.PollingConfig, doc, basePath)
}
if handlers.PackageSilence != nil {
registerPackageSilenceRoutes(authGroup, handlers.PackageSilence, doc, basePath)
}
if handlers.PollingPause != nil {
registerPollingPauseRoutes(authGroup, handlers.PollingPause, doc, basePath)
}

View File

@@ -0,0 +1,138 @@
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,
})
}

View File

@@ -127,6 +127,9 @@ func RegisterPersonalCustomerRoutes(router fiber.Router, doc *openapi.Generator,
if handlers.ClientPopup != nil {
registerPersonalPopupRoutes(authGroup, handlers.ClientPopup, doc, basePath)
}
if handlers.ClientPackageSilence != nil {
registerPersonalPackageSilenceRoutes(authGroup, handlers.ClientPackageSilence, doc, basePath)
}
// 获取个人资料
Register(authGroup, doc, basePath, "GET", "/profile", handlers.PersonalCustomer.GetProfile, RouteSpec{