feat(sms): 新增节点短信提醒(审核未通过/被租用需辅助/上架未成交)

This commit is contained in:
yml2213
2026-10-14 14:57:52 +08:00
parent efa0aa4ffd
commit 93e102b7c0
38 changed files with 3228 additions and 70 deletions
+274
View File
@@ -0,0 +1,274 @@
// Package smsdispatch 负责把业务事务里入队的节点短信真正发出去。
//
// 设计要点:
// - 业务侧只在事务内写 sms_messages(pending),发送完全异步,短信失败不影响业务;
// - 通道选择与登录验证码一致:分站启用独立短信且配置了该节点模板时走分站通道与分站签名,
// 否则回退主站通道与主站模板;
// - 失败按 retryDelay 退避重试,超过 maxRetry 标记 failed,便于运营排查。
package smsdispatch
import (
"context"
"encoding/json"
"fmt"
"strings"
"time"
smsprovider "hfb_sys/backend/internal/integrations/sms"
"hfb_sys/backend/internal/model"
"hfb_sys/backend/internal/modules/sms"
"github.com/redis/go-redis/v9"
"go.uber.org/zap"
"gorm.io/datatypes"
"gorm.io/gorm"
)
const lockKey = "hfb:job:smsdispatch:lock"
// SiteSenderResolver 解析分销站点的独立短信通道,由 distribution.SMSResolver 实现。
type SiteSenderResolver interface {
ResolveBusinessSender(ctx context.Context, siteID uint64) (smsprovider.Provider, string, map[string]string, error)
}
type Job struct {
db *gorm.DB
redis *redis.Client
logger *zap.Logger
repo *sms.Repository
configs sms.ConfigReader
provider smsprovider.Provider
mainSignName string
siteResolver SiteSenderResolver
interval time.Duration
batchSize int
maxRetry int
retryDelay time.Duration
instanceID string
}
func New(
db *gorm.DB,
redisClient *redis.Client,
logger *zap.Logger,
provider smsprovider.Provider,
mainSignName string,
configs sms.ConfigReader,
siteResolver SiteSenderResolver,
) *Job {
return &Job{
db: db,
redis: redisClient,
logger: logger,
repo: sms.NewRepository(db),
configs: configs,
provider: provider,
mainSignName: strings.TrimSpace(mainSignName),
siteResolver: siteResolver,
interval: time.Minute,
batchSize: 100,
maxRetry: 3,
retryDelay: 5 * time.Minute,
instanceID: newInstanceID(),
}
}
func (j *Job) Start(ctx context.Context) {
if j == nil || j.db == nil {
return
}
go j.loop(ctx)
}
func (j *Job) loop(ctx context.Context) {
j.run(ctx)
ticker := time.NewTicker(j.interval)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return
case <-ticker.C:
j.run(ctx)
}
}
}
func (j *Job) run(ctx context.Context) {
release, ok := j.acquireLock(ctx)
if !ok {
return
}
defer release()
sent, err := j.dispatch(ctx)
if err != nil {
j.logger.Warn("节点短信派发失败", zap.Error(err))
return
}
if sent > 0 {
j.logger.Info("节点短信派发完成", zap.Int("handled", sent))
}
}
func (j *Job) dispatch(ctx context.Context) (int, error) {
cfg, err := sms.LoadConfig(ctx, j.configs)
if err != nil {
return 0, err
}
rows, err := j.repo.ListPending(ctx, j.batchSize, time.Now().Add(-j.retryDelay))
if err != nil {
return 0, err
}
handled := 0
for _, row := range rows {
if err := ctx.Err(); err != nil {
return handled, err
}
if err := j.sendOne(ctx, cfg, row); err != nil {
j.logger.Warn("节点短信处理失败",
zap.Uint64("sms_message_id", row.ID),
zap.String("node", row.Node),
zap.String("phone", maskPhone(row.Phone)),
zap.Error(err),
)
continue
}
handled++
}
return handled, nil
}
func (j *Job) sendOne(ctx context.Context, cfg sms.Config, row model.SmsMessage) error {
node := strings.TrimSpace(row.Node)
if !sms.IsKnownNode(node) {
return j.repo.MarkSkipped(ctx, row.ID, "未登记的短信节点")
}
if strings.TrimSpace(row.Phone) == "" {
return j.repo.MarkSkipped(ctx, row.ID, "接收人手机号为空")
}
if !cfg.Enabled {
return j.repo.MarkSkipped(ctx, row.ID, "节点短信总开关未开启")
}
nodeCfg, ok := cfg.Node(node)
if !ok || !nodeCfg.Enabled {
return j.repo.MarkSkipped(ctx, row.ID, "该节点短信未启用")
}
mainTemplateCode := strings.TrimSpace(nodeCfg.TemplateCode)
if mainTemplateCode == "" {
return j.repo.MarkSkipped(ctx, row.ID, "主站未配置该节点模板 CODE")
}
provider, signName, templateCode := j.resolveSender(ctx, row, node, mainTemplateCode)
if provider == nil {
return j.repo.MarkSkipped(ctx, row.ID, "短信通道不可用")
}
req := smsprovider.TemplateRequest{
Phone: strings.TrimSpace(row.Phone),
SignName: signName,
TemplateCode: templateCode,
Params: decodeParams(row.TemplateParams),
}
if err := provider.SendTemplate(ctx, req); err != nil {
return j.handleSendFailure(ctx, row, err)
}
return j.repo.MarkSent(ctx, row.ID, templateCode, signName, time.Now())
}
// resolveSender 决定使用分站通道还是主站通道:分站启用独立短信且配置了该节点模板时优先分站。
func (j *Job) resolveSender(ctx context.Context, row model.SmsMessage, node string, mainTemplateCode string) (smsprovider.Provider, string, string) {
if row.DistributionSiteID != nil && *row.DistributionSiteID > 0 && j.siteResolver != nil {
siteProvider, siteSignName, siteTemplates, err := j.siteResolver.ResolveBusinessSender(ctx, *row.DistributionSiteID)
if err != nil {
j.logger.Warn("解析分站短信通道失败,回退主站通道",
zap.Uint64("site_id", *row.DistributionSiteID),
zap.Error(err),
)
} else if siteProvider != nil {
if code := strings.TrimSpace(siteTemplates[node]); code != "" {
return siteProvider, siteSignName, code
}
}
}
if j.provider == nil {
return nil, "", ""
}
return j.provider, j.mainSignName, mainTemplateCode
}
func (j *Job) handleSendFailure(ctx context.Context, row model.SmsMessage, sendErr error) error {
retryCount := row.RetryCount + 1
if retryCount >= j.maxRetry {
if err := j.repo.MarkFailed(ctx, row.ID, retryCount, sendErr.Error()); err != nil {
return err
}
j.logger.Warn("节点短信重试次数用尽",
zap.Uint64("sms_message_id", row.ID),
zap.String("node", row.Node),
zap.Int("retry_count", retryCount),
zap.Error(sendErr),
)
return nil
}
return j.repo.MarkRetry(ctx, row.ID, retryCount, sendErr.Error())
}
func decodeParams(raw datatypes.JSON) map[string]string {
if len(raw) == 0 {
return nil
}
var params map[string]string
if err := json.Unmarshal(raw, &params); err != nil {
return nil
}
if len(params) == 0 {
return nil
}
return params
}
// acquireLock 通过 Redis 分布式锁确保同一时刻只有一个实例派发。
// 未配置 Redis 时直接执行;Redis 出错时降级执行(重复发送由状态与重试次数兜底)。
func (j *Job) acquireLock(ctx context.Context) (func(), bool) {
if j.redis == nil {
return func() {}, true
}
ok, err := j.redis.SetNX(ctx, lockKey, j.instanceID, 2*j.interval).Result()
if err != nil {
j.logger.Warn("节点短信任务获取锁失败,将以单实例模式执行", zap.Error(err))
return func() {}, true
}
if !ok {
return nil, false
}
return j.releaseLock, true
}
func (j *Job) releaseLock() {
if j.redis == nil {
return
}
relCtx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
script := redis.NewScript(`if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end`)
if err := script.Run(relCtx, j.redis, []string{lockKey}, j.instanceID).Err(); err != nil {
j.logger.Warn("节点短信任务释放锁失败", zap.Error(err))
}
}
func newInstanceID() string {
return fmt.Sprintf("smsdispatch-%d", time.Now().UnixNano())
}
func maskPhone(phone string) string {
phone = strings.TrimSpace(phone)
if len(phone) < 7 {
return phone
}
return phone[:3] + "****" + phone[len(phone)-4:]
}
@@ -0,0 +1,397 @@
package smsdispatch
import (
"context"
"errors"
"testing"
"time"
"hfb_sys/backend/internal/database"
smsprovider "hfb_sys/backend/internal/integrations/sms"
"hfb_sys/backend/internal/model"
"hfb_sys/backend/internal/modules/sms"
"go.uber.org/zap"
"gorm.io/datatypes"
"gorm.io/gorm"
)
type fakeProvider struct {
sent []smsprovider.TemplateRequest
err error
}
func (p *fakeProvider) SendLoginCode(ctx context.Context, phone string, code string) error {
return nil
}
func (p *fakeProvider) SendTemplate(ctx context.Context, req smsprovider.TemplateRequest) error {
p.sent = append(p.sent, req)
return p.err
}
type fakeConfigReader struct {
value string
err error
}
func (r *fakeConfigReader) FindValue(ctx context.Context, key string) (string, error) {
if r.err != nil {
return "", r.err
}
if key != sms.ConfigKey {
return "", gorm.ErrRecordNotFound
}
return r.value, nil
}
type fakeSiteResolver struct {
provider smsprovider.Provider
signName string
templates map[string]string
err error
}
func (r *fakeSiteResolver) ResolveBusinessSender(ctx context.Context, siteID uint64) (smsprovider.Provider, string, map[string]string, error) {
return r.provider, r.signName, r.templates, r.err
}
func newDispatchTestDB(t *testing.T) *gorm.DB {
t.Helper()
db := database.NewTestDB()
if err := database.AutoMigrateIfMissing(db, &model.SmsMessage{}); err != nil {
t.Fatalf("AutoMigrate() error = %v", err)
}
return db
}
func configValue(t *testing.T, nodes map[string]sms.NodeConfig) string {
t.Helper()
raw, err := sms.MarshalConfig(sms.Config{Enabled: true, Nodes: nodes})
if err != nil {
t.Fatalf("MarshalConfig() error = %v", err)
}
return raw
}
func seedPending(t *testing.T, db *gorm.DB, row model.SmsMessage) model.SmsMessage {
t.Helper()
if row.Status == "" {
row.Status = model.SmsStatusPending
}
if row.Phone == "" {
row.Phone = "13800000000"
}
if err := db.Create(&row).Error; err != nil {
t.Fatalf("创建待发送记录失败: %v", err)
}
return row
}
func loadRow(t *testing.T, db *gorm.DB, id uint64) model.SmsMessage {
t.Helper()
var row model.SmsMessage
if err := db.First(&row, id).Error; err != nil {
t.Fatalf("查询短信记录失败: %v", err)
}
return row
}
func TestDispatchUsesMainChannelWhenNoSite(t *testing.T) {
db := newDispatchTestDB(t)
mainProvider := &fakeProvider{}
reader := &fakeConfigReader{value: configValue(t, map[string]sms.NodeConfig{
sms.NodeOrderHandoffAssist: {Enabled: true, TemplateCode: "SMS_512540945"},
})}
job := New(db, nil, zap.NewNop(), mainProvider, "大锤商行", reader, nil)
row := seedPending(t, db, model.SmsMessage{
UserID: 1,
Phone: "13800000001",
Node: sms.NodeOrderHandoffAssist,
BizType: "order",
BizID: 1001,
})
handled, err := job.dispatch(context.Background())
if err != nil {
t.Fatalf("dispatch() error = %v", err)
}
if handled != 1 {
t.Fatalf("dispatch() handled = %d, want 1", handled)
}
if len(mainProvider.sent) != 1 {
t.Fatalf("主站通道发送次数 = %d, want 1", len(mainProvider.sent))
}
req := mainProvider.sent[0]
if req.TemplateCode != "SMS_512540945" || req.SignName != "大锤商行" || req.Phone != "13800000001" {
t.Fatalf("请求 = %+v", req)
}
got := loadRow(t, db, row.ID)
if got.Status != model.SmsStatusSent || got.TemplateCode != "SMS_512540945" || got.SignName != "大锤商行" || got.SentAt == nil {
t.Fatalf("落库记录 = %+v", got)
}
}
func TestDispatchPrefersSiteChannelWhenTemplateConfigured(t *testing.T) {
db := newDispatchTestDB(t)
mainProvider := &fakeProvider{}
siteProvider := &fakeProvider{}
siteID := uint64(9)
reader := &fakeConfigReader{value: configValue(t, map[string]sms.NodeConfig{
sms.NodeOrderHandoffAssist: {Enabled: true, TemplateCode: "SMS_MAIN"},
})}
resolver := &fakeSiteResolver{
provider: siteProvider,
signName: "分站签名",
templates: map[string]string{sms.NodeOrderHandoffAssist: "SMS_SITE"},
}
job := New(db, nil, zap.NewNop(), mainProvider, "大锤商行", reader, resolver)
row := seedPending(t, db, model.SmsMessage{
UserID: 2,
Node: sms.NodeOrderHandoffAssist,
BizType: "order",
BizID: 1002,
DistributionSiteID: &siteID,
})
if _, err := job.dispatch(context.Background()); err != nil {
t.Fatalf("dispatch() error = %v", err)
}
if len(mainProvider.sent) != 0 {
t.Fatalf("分站已配置模板时不应使用主站通道")
}
if len(siteProvider.sent) != 1 {
t.Fatalf("分站通道发送次数 = %d, want 1", len(siteProvider.sent))
}
if req := siteProvider.sent[0]; req.TemplateCode != "SMS_SITE" || req.SignName != "分站签名" {
t.Fatalf("分站请求 = %+v", req)
}
if got := loadRow(t, db, row.ID); got.TemplateCode != "SMS_SITE" || got.SignName != "分站签名" {
t.Fatalf("分站落库记录 = %+v", got)
}
}
func TestDispatchFallsBackToMainWhenSiteTemplateMissing(t *testing.T) {
db := newDispatchTestDB(t)
mainProvider := &fakeProvider{}
siteProvider := &fakeProvider{}
siteID := uint64(10)
reader := &fakeConfigReader{value: configValue(t, map[string]sms.NodeConfig{
sms.NodeListingReviewRejected: {Enabled: true, TemplateCode: "SMS_MAIN"},
})}
resolver := &fakeSiteResolver{
provider: siteProvider,
signName: "分站签名",
templates: map[string]string{sms.NodeOrderHandoffAssist: "SMS_SITE"},
}
job := New(db, nil, zap.NewNop(), mainProvider, "大锤商行", reader, resolver)
row := seedPending(t, db, model.SmsMessage{
UserID: 3,
Node: sms.NodeListingReviewRejected,
BizType: "listing",
BizID: 1003,
DistributionSiteID: &siteID,
})
if _, err := job.dispatch(context.Background()); err != nil {
t.Fatalf("dispatch() error = %v", err)
}
if len(siteProvider.sent) != 0 {
t.Fatalf("分站未配置该节点模板时不应走分站通道")
}
if len(mainProvider.sent) != 1 || mainProvider.sent[0].TemplateCode != "SMS_MAIN" {
t.Fatalf("应回退主站模板,实际 = %+v", mainProvider.sent)
}
if got := loadRow(t, db, row.ID); got.Status != model.SmsStatusSent {
t.Fatalf("status = %q, want sent", got.Status)
}
}
func TestDispatchFallsBackToMainWhenSiteResolutionFails(t *testing.T) {
db := newDispatchTestDB(t)
mainProvider := &fakeProvider{}
siteID := uint64(11)
reader := &fakeConfigReader{value: configValue(t, map[string]sms.NodeConfig{
sms.NodeOrderHandoffAssist: {Enabled: true, TemplateCode: "SMS_MAIN"},
})}
resolver := &fakeSiteResolver{err: errors.New("解密失败")}
job := New(db, nil, zap.NewNop(), mainProvider, "大锤商行", reader, resolver)
seedPending(t, db, model.SmsMessage{
UserID: 4,
Node: sms.NodeOrderHandoffAssist,
BizType: "order",
BizID: 1004,
DistributionSiteID: &siteID,
})
if _, err := job.dispatch(context.Background()); err != nil {
t.Fatalf("dispatch() error = %v", err)
}
if len(mainProvider.sent) != 1 {
t.Fatalf("分站解析失败应回退主站通道,实际发送 %d 次", len(mainProvider.sent))
}
}
func TestDispatchSkipsWhenTemplateMissing(t *testing.T) {
db := newDispatchTestDB(t)
mainProvider := &fakeProvider{}
reader := &fakeConfigReader{value: configValue(t, map[string]sms.NodeConfig{
sms.NodeOrderHandoffAssist: {Enabled: true, TemplateCode: ""},
})}
job := New(db, nil, zap.NewNop(), mainProvider, "大锤商行", reader, nil)
row := seedPending(t, db, model.SmsMessage{
UserID: 5,
Node: sms.NodeOrderHandoffAssist,
BizType: "order",
BizID: 1005,
})
if _, err := job.dispatch(context.Background()); err != nil {
t.Fatalf("dispatch() error = %v", err)
}
if len(mainProvider.sent) != 0 {
t.Fatalf("未配置模板时不应发送")
}
got := loadRow(t, db, row.ID)
if got.Status != model.SmsStatusSkipped || got.SkipReason == "" {
t.Fatalf("应标记 skipped 并写原因,实际 = %+v", got)
}
}
func TestDispatchSkipsWhenNodeDisabled(t *testing.T) {
db := newDispatchTestDB(t)
mainProvider := &fakeProvider{}
reader := &fakeConfigReader{value: configValue(t, map[string]sms.NodeConfig{
sms.NodeOrderHandoffAssist: {Enabled: false, TemplateCode: "SMS_512540945"},
})}
job := New(db, nil, zap.NewNop(), mainProvider, "大锤商行", reader, nil)
row := seedPending(t, db, model.SmsMessage{
UserID: 6,
Node: sms.NodeOrderHandoffAssist,
BizType: "order",
BizID: 1006,
})
if _, err := job.dispatch(context.Background()); err != nil {
t.Fatalf("dispatch() error = %v", err)
}
if len(mainProvider.sent) != 0 {
t.Fatalf("节点关闭时不应发送")
}
if got := loadRow(t, db, row.ID); got.Status != model.SmsStatusSkipped {
t.Fatalf("status = %q, want skipped", got.Status)
}
}
func TestDispatchRetriesThenFails(t *testing.T) {
db := newDispatchTestDB(t)
mainProvider := &fakeProvider{err: errors.New("渠道异常")}
reader := &fakeConfigReader{value: configValue(t, map[string]sms.NodeConfig{
sms.NodeOrderHandoffAssist: {Enabled: true, TemplateCode: "SMS_512540945"},
})}
job := New(db, nil, zap.NewNop(), mainProvider, "大锤商行", reader, nil)
// 退避设为 0,便于在测试内连续重试。
job.retryDelay = 0
row := seedPending(t, db, model.SmsMessage{
UserID: 7,
Node: sms.NodeOrderHandoffAssist,
BizType: "order",
BizID: 1007,
})
if _, err := job.dispatch(context.Background()); err != nil {
t.Fatalf("第一次 dispatch() error = %v", err)
}
got := loadRow(t, db, row.ID)
if got.Status != model.SmsStatusPending || got.RetryCount != 1 || got.LastError == "" {
t.Fatalf("首次失败应留待重试,实际 = %+v", got)
}
// 第二次达到 maxRetry(3) 前仍是 pending,第三次用尽后置为 failed。
if _, err := job.dispatch(context.Background()); err != nil {
t.Fatalf("第二次 dispatch() error = %v", err)
}
if _, err := job.dispatch(context.Background()); err != nil {
t.Fatalf("第三次 dispatch() error = %v", err)
}
got = loadRow(t, db, row.ID)
if got.Status != model.SmsStatusFailed || got.RetryCount != job.maxRetry {
t.Fatalf("重试用尽后应标记 failed,实际 = %+v", got)
}
if len(mainProvider.sent) != job.maxRetry {
t.Fatalf("发送尝试次数 = %d, want %d", len(mainProvider.sent), job.maxRetry)
}
}
func TestDispatchPassesTemplateParams(t *testing.T) {
db := newDispatchTestDB(t)
mainProvider := &fakeProvider{}
reader := &fakeConfigReader{value: configValue(t, map[string]sms.NodeConfig{
sms.NodeOrderHandoffAssist: {Enabled: true, TemplateCode: "SMS_512540945"},
})}
job := New(db, nil, zap.NewNop(), mainProvider, "大锤商行", reader, nil)
seedPending(t, db, model.SmsMessage{
UserID: 8,
Node: sms.NodeOrderHandoffAssist,
BizType: "order",
BizID: 1008,
TemplateParams: datatypes.JSON([]byte(`{"brand_name":"大锤商行"}`)),
})
if _, err := job.dispatch(context.Background()); err != nil {
t.Fatalf("dispatch() error = %v", err)
}
if len(mainProvider.sent) != 1 {
t.Fatalf("发送次数 = %d, want 1", len(mainProvider.sent))
}
if got := mainProvider.sent[0].Params["brand_name"]; got != "大锤商行" {
t.Fatalf("params.brand_name = %q, want 大锤商行", got)
}
}
func TestDecodeParamsInvalidJSONFallsBackToNil(t *testing.T) {
if params := decodeParams(datatypes.JSON([]byte(`{oops`))); params != nil {
t.Fatalf("非法 JSON 应回落 nil, got %+v", params)
}
if params := decodeParams(datatypes.JSON([]byte(`{}`))); params != nil {
t.Fatalf("空对象应回落 nil, got %+v", params)
}
if params := decodeParams(nil); params != nil {
t.Fatalf("nil 应回落 nil, got %+v", params)
}
}
func TestDispatchIgnoresRecordsInRetryBackoff(t *testing.T) {
db := newDispatchTestDB(t)
mainProvider := &fakeProvider{}
reader := &fakeConfigReader{value: configValue(t, map[string]sms.NodeConfig{
sms.NodeOrderHandoffAssist: {Enabled: true, TemplateCode: "SMS_512540945"},
})}
job := New(db, nil, zap.NewNop(), mainProvider, "大锤商行", reader, nil)
job.retryDelay = time.Hour
seedPending(t, db, model.SmsMessage{
UserID: 12,
Node: sms.NodeOrderHandoffAssist,
BizType: "order",
BizID: 1012,
Status: model.SmsStatusPending,
RetryCount: 1,
})
if _, err := job.dispatch(context.Background()); err != nil {
t.Fatalf("dispatch() error = %v", err)
}
if len(mainProvider.sent) != 0 {
t.Fatalf("退避窗口内不应重试")
}
}