Files
go-sms-V2/internal/api/http/v1/settle_handler.go
T
2026-11-14 23:06:12 +08:00

609 lines
20 KiB
Go

// settle_handler.go S2:结算域端点。D2 先挂两件——消耗日汇总查询(/billing/
// consume)与手动回补(/ops/settle/aggregate);D3(充值订单审核族)/D4(月结
// 单/阶梯/导出)/D5(利润/对账)随任务推进在本文件追加,契约见 openapi v1.3.0。
package v1
import (
"strconv"
"time"
"github.com/gin-gonic/gin"
"go.uber.org/zap"
"gorm.io/gorm"
"go-sms/internal/config"
"go-sms/internal/middleware"
"go-sms/internal/model/entity"
errs "go-sms/internal/pkg/errors"
"go-sms/internal/pkg/response"
"go-sms/internal/service/settle"
)
// settleConsumeDefaultDays 消耗查询缺省窗口(近 7 天,对齐 stats trend 口径)。
const settleConsumeDefaultDays = 7
func registerSettleRoutes(protected *gin.RouterGroup, deps Deps) {
h := &settleHandler{svc: deps.Settle}
// 消耗日汇总查询:JWT 即可(admin/ops/service 全量;group/customer 仅自己,
// scope 收窄在 handler 内做——与 stats 域同口径,casbin customer settle:read
// 策略为 v20 所种,细分资源门按需后挂)。
protected.GET("/billing/consume", h.consumeList)
// 手动触发回补(运维口径;settle:write)。
protected.POST("/ops/settle/aggregate",
middleware.RequirePermission(deps.Perm, "settle", "write"), h.aggregate)
// S2-D3:充值订单审核族(R3 双通道——即时充值保留,订单流承载付款审核确认;
// 创建/确认/驳回挂 account:recharge 二级权限与即时充值同门;列表=平台角色
// admin/ops/service(group/customer 403——订单含全平台资金信息不放大)。
protected.GET("/billing/orders", h.ordersList)
protected.POST("/billing/orders",
middleware.RequirePermission(deps.Perm, "account", middleware.PermRecharge), h.orderCreate)
protected.POST("/billing/orders/:id/confirm",
middleware.RequirePermission(deps.Perm, "account", middleware.PermRecharge), h.orderConfirm)
protected.POST("/billing/orders/:id/reject",
middleware.RequirePermission(deps.Perm, "account", middleware.PermRecharge), h.orderReject)
// S2-D4:出账+阶梯(settle:write 门=D1 契约;查询类平台角色/客户仅自己)。
protected.GET("/settle/customer", h.customerBills)
protected.POST("/settle/customer/generate",
middleware.RequirePermission(deps.Perm, "settle", "write"), h.customerGenerate)
protected.GET("/settle/customer/:id", h.customerBillDetail)
protected.POST("/settle/customer/:id/confirm",
middleware.RequirePermission(deps.Perm, "settle", "write"), h.customerBillConfirm)
protected.POST("/settle/customer/:id/settle",
middleware.RequirePermission(deps.Perm, "settle", "write"), h.customerBillSettle)
protected.GET("/settle/customer/:id/export", h.customerBillExport)
protected.GET("/settle/upstream", h.upstreamBills)
protected.POST("/settle/upstream/generate",
middleware.RequirePermission(deps.Perm, "settle", "write"), h.upstreamGenerate)
protected.GET("/settle/upstream/:id", h.upstreamBillDetail)
protected.POST("/settle/upstream/:id/settle",
middleware.RequirePermission(deps.Perm, "settle", "write"), h.upstreamBillSettle)
protected.GET("/settle/upstream/:id/export", h.upstreamBillExport)
protected.GET("/settle/ladder", h.ladderList)
protected.POST("/settle/ladder",
middleware.RequirePermission(deps.Perm, "settle", "write"), h.ladderCreate)
protected.PUT("/settle/ladder/:id",
middleware.RequirePermission(deps.Perm, "settle", "write"), h.ladderUpdate)
protected.DELETE("/settle/ladder/:id",
middleware.RequirePermission(deps.Perm, "settle", "write"), h.ladderDelete)
// S2-D5:利润分析双端点(平台角色门——利润含全平台资金信息,group/customer
// 403,与充值订单列表同口径;查询类不挂 settle:write)。
protected.GET("/stats/profit/users", h.profitUsers)
protected.GET("/stats/profit/channels", h.profitChannels)
}
// StartSettleAggregateJob v1 层装配入口(照 StartStatsRefresher 模式,仅
// gateway 调用;测试/迁移工具不启)。
func StartSettleAggregateJob(db *gorm.DB, cfg config.Settle, log *zap.Logger) {
settle.StartAggregateJob(db, cfg.RefreshEvery, cfg.RefreshDays, cfg.BackfillDays, log)
}
type settleHandler struct{ svc *settle.Service }
// consumeList GET /billing/consume:账号×业务×天 消耗事实源查询。
func (h *settleHandler) consumeList(c *gin.Context) {
claims := statsClaims(c) // protected 组内恒在;复用 stats 域提取器
q := settle.ConsumeQuery{Page: 1, PageSize: 20}
if v, err := strconv.ParseInt(c.Query("account_id"), 10, 64); err == nil && v > 0 {
q.AccountID = v
}
q.Business = c.Query("business")
now := time.Now()
q.To = now
q.From = now.AddDate(0, 0, -(settleConsumeDefaultDays - 1))
if s := c.Query("date_from"); s != "" {
d, err := time.ParseInLocation("2006-01-02", s, time.Local)
if err != nil {
response.Error(c, errs.InvalidParam.WithMsg("date_from 须为 YYYY-MM-DD"))
return
}
q.From = d
}
if s := c.Query("date_to"); s != "" {
d, err := time.ParseInLocation("2006-01-02", s, time.Local)
if err != nil {
response.Error(c, errs.InvalidParam.WithMsg("date_to 须为 YYYY-MM-DD"))
return
}
q.To = d
}
if v, err := strconv.Atoi(c.Query("page")); err == nil && v > 0 {
q.Page = v
}
if v, err := strconv.Atoi(c.Query("page_size")); err == nil && v > 0 {
q.PageSize = v
}
// 非平台角色强制收窄到自身账号(带参越权请求直接覆盖,不报错——stats 同口径)。
if claims != nil && !statsIsPlatform(c) {
q.AccountID = claims.AccountID
}
list, total, err := h.svc.ListConsume(c.Request.Context(), q)
if err != nil {
bizResp(c, err)
return
}
response.Success(c, gin.H{"total": total, "list": list})
}
// aggregate POST /ops/settle/aggregate:date 缺省=昨日;幂等 UPSERT 可重入,
// 返回两表落账行数(只回补单日——历史区间回补走重启 job 的 backfill 或逐日调用)。
func (h *settleHandler) aggregate(c *gin.Context) {
var req struct {
Date string `json:"date"`
}
_ = c.ShouldBindJSON(&req)
day := time.Now().AddDate(0, 0, -1)
if req.Date != "" {
d, err := time.ParseInLocation("2006-01-02", req.Date, time.Local)
if err != nil {
response.Error(c, errs.InvalidParam.WithMsg("date 须为 YYYY-MM-DD"))
return
}
day = d
}
accountRows, channelRows, err := h.svc.AggregateDay(c.Request.Context(), day)
if err != nil {
bizResp(c, err)
return
}
response.Success(c, gin.H{
"day": day.Format("2006-01-02"),
"account_rows": accountRows,
"channel_rows": channelRows,
})
}
// ordersList GET /billing/orders:订单分页(account_id/pay_status 过滤;平台角色)。
func (h *settleHandler) ordersList(c *gin.Context) {
if !statsIsPlatform(c) {
response.Error(c, errs.Forbidden.WithMsg("仅平台角色可查看充值订单"))
return
}
q := settle.OrderQuery{Page: 1, PageSize: 20}
if v, err := strconv.ParseInt(c.Query("account_id"), 10, 64); err == nil && v > 0 {
q.AccountID = v
}
if s := c.Query("pay_status"); s != "" {
v, err := strconv.Atoi(s)
if err != nil || v < 0 || v > 2 {
response.Error(c, errs.InvalidParam.WithMsg("pay_status 须为 0/1/2"))
return
}
ps := int8(v)
q.PayStatus = &ps
}
if v, err := strconv.Atoi(c.Query("page")); err == nil && v > 0 {
q.Page = v
}
if v, err := strconv.Atoi(c.Query("page_size")); err == nil && v > 0 {
q.PageSize = v
}
list, total, err := h.svc.ListOrders(c.Request.Context(), q)
if err != nil {
bizResp(c, err)
return
}
response.Success(c, gin.H{"total": total, "list": list})
}
// orderCreate POST /billing/orders:创建待确认订单(不动余额;到账只发生在 confirm)。
func (h *settleHandler) orderCreate(c *gin.Context) {
var req struct {
AccountID int64 `json:"account_id" binding:"required"`
Count int64 `json:"count" binding:"required"`
Amount float64 `json:"amount"`
PayType string `json:"pay_type"`
Remark string `json:"remark"`
}
if err := c.ShouldBindJSON(&req); err != nil {
response.Error(c, errs.InvalidParam.WithMsg("account_id/count 必填"))
return
}
claims := statsClaims(c)
operator := ""
if claims != nil {
operator = claims.Username
}
order, err := h.svc.CreateOrder(c.Request.Context(), &settle.CreateOrderRequest{
AccountID: req.AccountID, Count: req.Count, Amount: req.Amount,
PayType: req.PayType, Operator: operator, Remark: req.Remark,
})
if err != nil {
bizResp(c, err)
return
}
response.Success(c, order)
}
// orderConfirm POST /billing/orders/:id/confirm:付款审核确认(0→1,余额+count)。
func (h *settleHandler) orderConfirm(c *gin.Context) {
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
if err != nil || id <= 0 {
response.Error(c, errs.InvalidParam.WithMsg("订单 ID 非法"))
return
}
claims := statsClaims(c)
operator := ""
if claims != nil {
operator = claims.Username
}
res, err := h.svc.ConfirmOrder(c.Request.Context(), id, operator)
if err != nil {
bizResp(c, err)
return
}
response.Success(c, gin.H{
"order_no": res.Order.OrderNo, "pay_status": res.Order.PayStatus,
"count": res.Order.Count, "balance": res.Balance, "balance_log_id": res.BalanceLogID,
})
}
// orderReject POST /billing/orders/:id/reject:驳回(0→2,不涉余额)。
func (h *settleHandler) orderReject(c *gin.Context) {
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
if err != nil || id <= 0 {
response.Error(c, errs.InvalidParam.WithMsg("订单 ID 非法"))
return
}
var req struct {
Remark string `json:"remark"`
}
_ = c.ShouldBindJSON(&req)
claims := statsClaims(c)
operator := ""
if claims != nil {
operator = claims.Username
}
order, err := h.svc.RejectOrder(c.Request.Context(), id, operator, req.Remark)
if err != nil {
bizResp(c, err)
return
}
response.Success(c, order)
}
// ---- S2-D4:出账 handler ----
// billQueryFrom 通用账单列表参数解析。
func billQueryFrom(c *gin.Context) (settle.BillQuery, error) {
q := settle.BillQuery{Period: c.Query("period"), Page: 1, PageSize: 20}
if v, err := strconv.ParseInt(c.Query("account_id"), 10, 64); err == nil && v > 0 {
q.OwnerID = v
}
if v, err := strconv.ParseInt(c.Query("upstream_id"), 10, 64); err == nil && v > 0 {
q.OwnerID = v
}
if s := c.Query("status"); s != "" {
v, err := strconv.Atoi(s)
if err != nil || v < 0 || v > 2 {
return q, errs.InvalidParam.WithMsg("status 须为 0/1/2")
}
st := int8(v)
q.Status = &st
}
if v, err := strconv.Atoi(c.Query("page")); err == nil && v > 0 {
q.Page = v
}
if v, err := strconv.Atoi(c.Query("page_size")); err == nil && v > 0 {
q.PageSize = v
}
return q, nil
}
// customerBills GET /settle/customer:customer 仅自己;平台角色全量。
func (h *settleHandler) customerBills(c *gin.Context) {
q, err := billQueryFrom(c)
if err != nil {
response.Error(c, err.(*errs.Error))
return
}
if claims := statsClaims(c); claims != nil && !statsIsPlatform(c) {
q.OwnerID = claims.AccountID
}
list, total, err := h.svc.ListCustomerBills(c.Request.Context(), q)
if err != nil {
bizResp(c, err)
return
}
response.Success(c, gin.H{"total": total, "list": list})
}
// customerGenerate POST /settle/customer/generate {period}。
func (h *settleHandler) customerGenerate(c *gin.Context) {
var req struct {
Period string `json:"period" binding:"required"`
}
if err := c.ShouldBindJSON(&req); err != nil {
response.Error(c, errs.InvalidParam.WithMsg("period 必填(YYYY-MM)"))
return
}
res, err := h.svc.GenerateCustomerBills(c.Request.Context(), req.Period)
if err != nil {
bizResp(c, err)
return
}
response.Success(c, res)
}
// customerBillDetail GET /settle/customer/:id:单头+按天明细;customer 仅自己。
func (h *settleHandler) customerBillDetail(c *gin.Context) {
id, _ := strconv.ParseInt(c.Param("id"), 10, 64)
bill, err := h.svc.GetCustomerBill(c.Request.Context(), id)
if err != nil {
bizResp(c, err)
return
}
if claims := statsClaims(c); claims != nil && !statsIsPlatform(c) && bill.AccountID != claims.AccountID {
response.Error(c, errs.Forbidden.WithMsg("非本人账单"))
return
}
days, err := h.svc.CustomerBillDays(c.Request.Context(), bill)
if err != nil {
bizResp(c, err)
return
}
response.Success(c, gin.H{"bill": bill, "days": days})
}
// customerBillConfirm POST /settle/customer/:id/confirm 0→1。
func (h *settleHandler) customerBillConfirm(c *gin.Context) {
id, _ := strconv.ParseInt(c.Param("id"), 10, 64)
if err := h.svc.ConfirmCustomerBill(c.Request.Context(), id); err != nil {
bizResp(c, err)
return
}
response.Success(c, nil)
}
// customerBillSettle POST /settle/customer/:id/settle 1→2+settle_record。
func (h *settleHandler) customerBillSettle(c *gin.Context) {
id, _ := strconv.ParseInt(c.Param("id"), 10, 64)
var req struct {
PayType string `json:"pay_type"`
Remark string `json:"remark"`
}
_ = c.ShouldBindJSON(&req)
operator := ""
if claims := statsClaims(c); claims != nil {
operator = claims.Username
}
rec, err := h.svc.SettleCustomerBill(c.Request.Context(), id, req.PayType, operator, req.Remark)
if err != nil {
bizResp(c, err)
return
}
response.Success(c, rec)
}
// customerBillExport GET /settle/customer/:id/export XLSX。
func (h *settleHandler) customerBillExport(c *gin.Context) {
id, _ := strconv.ParseInt(c.Param("id"), 10, 64)
data, name, err := h.svc.ExportCustomerBillXLSX(c.Request.Context(), id)
if err != nil {
bizResp(c, err)
return
}
c.Header("Content-Disposition", `attachment; filename="`+name+`"`)
c.Data(200, "application/octet-stream", data)
}
// upstreamBills GET /settle/upstream(平台角色)。
func (h *settleHandler) upstreamBills(c *gin.Context) {
if !statsIsPlatform(c) {
response.Error(c, errs.Forbidden.WithMsg("仅平台角色可查看上家账单"))
return
}
q, err := billQueryFrom(c)
if err != nil {
response.Error(c, err.(*errs.Error))
return
}
list, total, err := h.svc.ListUpstreamBills(c.Request.Context(), q)
if err != nil {
bizResp(c, err)
return
}
response.Success(c, gin.H{"total": total, "list": list})
}
// upstreamGenerate POST /settle/upstream/generate {period}。
func (h *settleHandler) upstreamGenerate(c *gin.Context) {
var req struct {
Period string `json:"period" binding:"required"`
}
if err := c.ShouldBindJSON(&req); err != nil {
response.Error(c, errs.InvalidParam.WithMsg("period 必填(YYYY-MM)"))
return
}
res, err := h.svc.GenerateUpstreamBills(c.Request.Context(), req.Period)
if err != nil {
bizResp(c, err)
return
}
response.Success(c, res)
}
// upstreamBillDetail GET /settle/upstream/:id:单头+通道×天明细。
func (h *settleHandler) upstreamBillDetail(c *gin.Context) {
id, _ := strconv.ParseInt(c.Param("id"), 10, 64)
bill, err := h.svc.GetUpstreamBill(c.Request.Context(), id)
if err != nil {
bizResp(c, err)
return
}
rows, err := h.svc.UpstreamBillRows(c.Request.Context(), bill)
if err != nil {
bizResp(c, err)
return
}
response.Success(c, gin.H{"bill": bill, "rows": rows})
}
// upstreamBillSettle POST /settle/upstream/:id/settle 1→2+settle_record(direction=2)。
func (h *settleHandler) upstreamBillSettle(c *gin.Context) {
id, _ := strconv.ParseInt(c.Param("id"), 10, 64)
var req struct {
PayType string `json:"pay_type"`
Remark string `json:"remark"`
}
_ = c.ShouldBindJSON(&req)
operator := ""
if claims := statsClaims(c); claims != nil {
operator = claims.Username
}
rec, err := h.svc.SettleUpstreamBill(c.Request.Context(), id, req.PayType, operator, req.Remark)
if err != nil {
bizResp(c, err)
return
}
response.Success(c, rec)
}
// upstreamBillExport GET /settle/upstream/:id/export XLSX。
func (h *settleHandler) upstreamBillExport(c *gin.Context) {
id, _ := strconv.ParseInt(c.Param("id"), 10, 64)
data, name, err := h.svc.ExportUpstreamBillXLSX(c.Request.Context(), id)
if err != nil {
bizResp(c, err)
return
}
c.Header("Content-Disposition", `attachment; filename="`+name+`"`)
c.Data(200, "application/octet-stream", data)
}
// ---- 阶梯档位 ----
// ladderList GET /settle/ladder?owner_type&owner_id。
func (h *settleHandler) ladderList(c *gin.Context) {
ownerID, _ := strconv.ParseInt(c.Query("owner_id"), 10, 64)
list, err := h.svc.ListLadders(c.Request.Context(), c.Query("owner_type"), ownerID)
if err != nil {
bizResp(c, err)
return
}
response.Success(c, list)
}
// ladderCreate POST /settle/ladder。
func (h *settleHandler) ladderCreate(c *gin.Context) {
var req entity.SettleLadder
if err := c.ShouldBindJSON(&req); err != nil || req.OwnerID <= 0 {
response.Error(c, errs.InvalidParam.WithMsg("owner_type/owner_id/tier_from/price 必填"))
return
}
if err := h.svc.CreateLadder(c.Request.Context(), &req); err != nil {
bizResp(c, err)
return
}
response.Success(c, req)
}
// ladderUpdate PUT /settle/ladder/:id {tier_from?,price?}。
func (h *settleHandler) ladderUpdate(c *gin.Context) {
id, _ := strconv.ParseInt(c.Param("id"), 10, 64)
var req struct {
TierFrom *int64 `json:"tier_from"`
Price *float64 `json:"price"`
}
_ = c.ShouldBindJSON(&req)
if err := h.svc.UpdateLadder(c.Request.Context(), id, req.TierFrom, req.Price); err != nil {
bizResp(c, err)
return
}
response.Success(c, nil)
}
// ladderDelete DELETE /settle/ladder/:id。
func (h *settleHandler) ladderDelete(c *gin.Context) {
id, _ := strconv.ParseInt(c.Param("id"), 10, 64)
if err := h.svc.DeleteLadder(c.Request.Context(), id); err != nil {
bizResp(c, err)
return
}
response.Success(c, nil)
}
// ---- S2-D5:利润分析 ----
// parseProfitDates date_from/date_to 解析(YYYY-MM-DD;零值兜底=本月 1 号~今天,
// 月度利润视角)。返回 ok=false 时已写响应。
func parseProfitDates(c *gin.Context) (from, to time.Time, ok bool) {
now := time.Now()
from = time.Date(now.Year(), now.Month(), 1, 0, 0, 0, 0, now.Location())
to = now
if s := c.Query("date_from"); s != "" {
d, err := time.ParseInLocation("2006-01-02", s, time.Local)
if err != nil {
response.Error(c, errs.InvalidParam.WithMsg("date_from 须为 YYYY-MM-DD"))
return time.Time{}, time.Time{}, false
}
from = d
}
if s := c.Query("date_to"); s != "" {
d, err := time.ParseInLocation("2006-01-02", s, time.Local)
if err != nil {
response.Error(c, errs.InvalidParam.WithMsg("date_to 须为 YYYY-MM-DD"))
return time.Time{}, time.Time{}, false
}
to = d
}
return from, to, true
}
// profitUsers GET /stats/profit/users:用户利润(时间线价收入/成本分摊/直线下级
// 返点 R4/子树过滤;平台角色)。口径详见 settle/profit.go 头注。
func (h *settleHandler) profitUsers(c *gin.Context) {
if !statsIsPlatform(c) {
response.Error(c, errs.Forbidden.WithMsg("仅平台角色可查看利润分析"))
return
}
from, to, ok := parseProfitDates(c)
if !ok {
return
}
q := settle.UserProfitQuery{From: from, To: to, Page: 1, PageSize: 20}
if v, err := strconv.ParseInt(c.Query("parent_id"), 10, 64); err == nil && v > 0 {
q.ParentID = v
}
if v, err := strconv.Atoi(c.Query("page")); err == nil && v > 0 {
q.Page = v
}
if v, err := strconv.Atoi(c.Query("page_size")); err == nil && v > 0 {
q.PageSize = v
}
res, err := h.svc.UserProfit(c.Request.Context(), q)
if err != nil {
bizResp(c, err)
return
}
response.Success(c, res)
}
// profitChannels GET /stats/profit/channels:通道利润(通道价成本直算/收入占比
// 分摊;平台角色)。
func (h *settleHandler) profitChannels(c *gin.Context) {
if !statsIsPlatform(c) {
response.Error(c, errs.Forbidden.WithMsg("仅平台角色可查看利润分析"))
return
}
from, to, ok := parseProfitDates(c)
if !ok {
return
}
q := settle.ChannelProfitQuery{From: from, To: to, Page: 1, PageSize: 20}
if v, err := strconv.ParseInt(c.Query("channel_id"), 10, 64); err == nil && v > 0 {
q.ChannelID = v
}
if v, err := strconv.Atoi(c.Query("page")); err == nil && v > 0 {
q.Page = v
}
if v, err := strconv.Atoi(c.Query("page_size")); err == nil && v > 0 {
q.PageSize = v
}
res, err := h.svc.ChannelProfit(c.Request.Context(), q)
if err != nil {
bizResp(c, err)
return
}
response.Success(c, res)
}