wavelet init

Wavelet/internal/apps/admin/push/channels.go

@@ -0,0 +1,278 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package push
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strconv"
+	"strings"
+
+	pkgpush "github.com/Rain-kl/Wavelet/pkg/push"
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+	"github.com/Rain-kl/Wavelet/internal/model"
+)
+
+// ListChannelDefinitions 获取各种消息通道的表单配置定义列表
+// @Summary 获取所有消息通道配置字段定义
+// @Description 返回系统支持的所有消息通道类型（如飞书、邮件、自定义、Telegram）的动态表单定义，需要管理员权限
+// @Tags admin-push
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]Definition} "通道配置定义列表"
+// @Router /api/v1/admin/push/channels/definitions [get]
+func ListChannelDefinitions(c *gin.Context) {
+	c.JSON(http.StatusOK, response.OK(ListDefinitions()))
+}
+
+// ListChannels 获取消息通道列表
+// @Summary 获取所有消息通道
+// @Description 返回系统配置的所有消息通道列表，需要管理员权限
+// @Tags admin-push
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]model.PushChannel} "消息通道列表"
+// @Router /api/v1/admin/push/channels [get]
+func ListChannels(c *gin.Context) {
+	channels, err := listPushChannels(c.Request.Context())
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(channels))
+}
+
+// CreateChannelRequest 创建通道参数
+type CreateChannelRequest struct {
+	Name        string `json:"name" binding:"required"`
+	Description string `json:"description"`
+	Type        string `json:"type" binding:"required"`
+	Token       string `json:"token"`
+	URL         string `json:"url"`
+	Other       string `json:"other"`
+	Enabled     bool   `json:"enabled"`
+}
+
+// CreateChannel 创建消息通道
+// @Summary 创建消息通道
+// @Description 新建一个消息通道配置，需要管理员权限
+// @Tags admin-push
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body CreateChannelRequest true "创建参数"
+// @Success 200 {object} response.Any{data=model.PushChannel} "创建成功"
+// @Router /api/v1/admin/push/channels [post]
+func CreateChannel(c *gin.Context) {
+	var req CreateChannelRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	channel, err := createPushChannel(c.Request.Context(), req)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(channel))
+}
+
+// UpdateChannelRequest 修改通道参数
+type UpdateChannelRequest struct {
+	Description string `json:"description"`
+	Type        string `json:"type" binding:"required"`
+	Token       string `json:"token"`
+	URL         string `json:"url"`
+	Other       string `json:"other"`
+	Enabled     bool   `json:"enabled"`
+}
+
+// UpdateChannel 更新消息通道
+// @Summary 更新消息通道
+// @Description 修改消息通道配置，需要管理员权限
+// @Tags admin-push
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param id path uint64 true "通道ID"
+// @Param request body UpdateChannelRequest true "更新参数"
+// @Success 200 {object} response.Any{data=model.PushChannel} "更新成功"
+// @Router /api/v1/admin/push/channels/{id} [put]
+func UpdateChannel(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, "invalid channel id")
+		return
+	}
+
+	var req UpdateChannelRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	channel, err := updatePushChannel(c.Request.Context(), id, req)
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			response.AbortNotFound(c, "channel not found")
+			return
+		}
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(channel))
+}
+
+// DeleteChannel 删除消息通道
+// @Summary 删除消息通道
+// @Description 根据ID删除消息通道，需要管理员权限
+// @Tags admin-push
+// @Produce json
+// @Security SessionCookie
+// @Param id path uint64 true "通道ID"
+// @Success 200 {object} response.Any "删除成功"
+// @Router /api/v1/admin/push/channels/{id} [delete]
+func DeleteChannel(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, "invalid channel id")
+		return
+	}
+
+	if err := deletePushChannel(c.Request.Context(), id); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			response.AbortNotFound(c, "channel not found")
+			return
+		}
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// TestChannelRequest 测试通道连通性参数
+type TestChannelRequest struct {
+	Name   string `json:"name"`
+	Type   string `json:"type"`
+	Token  string `json:"token"`
+	URL    string `json:"url"`
+	Other  string `json:"other"`
+	Target string `json:"target"`
+}
+
+// TestChannel 测试通道连通性
+// @Summary 测试通道连通性
+// @Description 触发一次临时的或现有的通道连通性推送测试，需要管理员权限
+// @Tags admin-push
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body TestChannelRequest true "测试参数"
+// @Success 200 {object} response.Any "测试触发成功"
+// @Router /api/v1/admin/push/channels/test [post]
+func TestChannel(c *gin.Context) {
+	var req TestChannelRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	ctx := c.Request.Context()
+	url, token, other, channelType, err := loadChannelForTest(ctx, req)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if channelType == channelEmail {
+		url, token, other = resolveSMTPConfig(ctx, url, token, other)
+	}
+
+	tempChannel := model.PushChannel{
+		Name:    "test_temp",
+		URL:     url,
+		Token:   token,
+		Other:   other,
+		Type:    channelType,
+		Enabled: true,
+	}
+	if err := tempChannel.Validate(); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	url = tempChannel.URL
+
+	var config pkgpush.Config
+	var renderedJSON string
+	switch channelType {
+	case channelLark:
+		config = pkgpush.Config{Channel: channelLark, URL: url, Secret: token}
+		renderedJSON = other
+	case channelEmail:
+		config = pkgpush.Config{Channel: channelEmail, URL: url, Key: token, Secret: other}
+	case channelTelegram:
+		config = pkgpush.Config{Channel: channelTelegram, URL: url, Secret: token, Key: other}
+	default:
+		config = pkgpush.Config{Channel: channelCustom, URL: url}
+		customPushReq := CustomPushRequest{
+			Title:       "通道测试通知",
+			Content:     "这是一条来自系统的消息通道连通性测试消息。",
+			Description: "系统通道测试",
+			URL:         "https://example.com",
+			To:          req.Target,
+		}
+		renderedJSON = renderCustomPayload(other, customPushReq)
+	}
+
+	payload := SendPayload{
+		EventKey: "test_channel",
+		Config:   config,
+		Target:   req.Target,
+		Body: NotificationMessage{
+			Title:   "通道测试通知",
+			Content: "这是一条来自系统的消息通道连通性测试消息。",
+			Level:   defaultLevelInfo,
+		},
+		Template: renderedJSON,
+	}
+	if err := enqueuePushTask(ctx, payload); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// CustomPushRequest 外部公开推送请求参数
+type CustomPushRequest struct {
+	Title       string `json:"title" form:"title"`
+	Description string `json:"description" form:"description"`
+	Content     string `json:"content" form:"content"`
+	URL         string `json:"url" form:"url"`
+	To          string `json:"to" form:"to"`
+	Token       string `json:"token" form:"token"`
+}
+
+func escapeJSONString(s string) string {
+	b, _ := json.Marshal(s)
+	const minJSONLen = 2
+	if len(b) >= minJSONLen {
+		return string(b[1 : len(b)-1])
+	}
+	return s
+}
+
+func renderCustomPayload(template string, req CustomPushRequest) string {
+	result := template
+	result = strings.ReplaceAll(result, "$title", escapeJSONString(req.Title))
+	result = strings.ReplaceAll(result, "$description", escapeJSONString(req.Description))
+	result = strings.ReplaceAll(result, "$content", escapeJSONString(req.Content))
+	result = strings.ReplaceAll(result, "$url", escapeJSONString(req.URL))
+	result = strings.ReplaceAll(result, "$to", escapeJSONString(req.To))
+	return result
+}

Wavelet/internal/apps/admin/push/channels_definition.go

@@ -0,0 +1,183 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package push
+
+import "sync"
+
+const (
+	// KeyURL represents the URL field key
+	KeyURL = "url"
+	// KeyToken represents the Token field key
+	KeyToken = "token"
+	// KeyOther represents the Other field key
+	KeyOther = "other"
+
+	// TypeText represents standard text input type
+	TypeText = "text"
+	// TypePassword represents password input type
+	TypePassword = "password"
+	// TypeTextarea represents textarea input type
+	TypeTextarea = "textarea"
+)
+
+// Field represents a form field configuration for a channel.
+type Field struct {
+	Key         string `json:"key"`         // unique key for the field (e.g. url, token, other)
+	Label       string `json:"label"`       // human readable label (e.g. "Webhook 地址")
+	Type        string `json:"type"`        // input type: "text" | "password" | "textarea"
+	Required    bool   `json:"required"`    // whether this field is required
+	Placeholder string `json:"placeholder"` // input placeholder
+	Description string `json:"description"` // field explanation/help text
+}
+
+// Definition represents the metadata and form schema for a notification channel.
+type Definition struct {
+	Type        string  `json:"type"`        // channel type (e.g., custom, lark, email)
+	Name        string  `json:"name"`        // display name
+	Description string  `json:"description"` // short description
+	Fields      []Field `json:"fields"`      // form fields
+}
+
+var (
+	defMu       sync.RWMutex
+	definitions = make(map[string]Definition)
+)
+
+// RegisterChannelDefinition registers a channel definition.
+func RegisterChannelDefinition(def Definition) {
+	defMu.Lock()
+	defer defMu.Unlock()
+	definitions[def.Type] = def
+}
+
+// ListDefinitions returns all registered channel definitions.
+func ListDefinitions() []Definition {
+	defMu.RLock()
+	defer defMu.RUnlock()
+
+	// We want a stable order: custom, lark, telegram, email
+	order := []string{channelCustom, channelLark, channelTelegram, channelEmail}
+	res := make([]Definition, 0, len(definitions))
+	for _, t := range order {
+		if d, ok := definitions[t]; ok {
+			res = append(res, d)
+		}
+	}
+	// Add any others
+	for t, d := range definitions {
+		found := false
+		for _, o := range order {
+			if o == t {
+				found = true
+				break
+			}
+		}
+		if !found {
+			res = append(res, d)
+		}
+	}
+	return res
+}
+
+func init() {
+	// Register custom webhook channel
+	RegisterChannelDefinition(Definition{
+		Type:        channelCustom,
+		Name:        "自定义消息通道",
+		Description: "使用自定义 HTTP POST 请求向外部 Webhook 发送数据。",
+		Fields: []Field{
+			{
+				Key:         KeyURL,
+				Label:       "请求地址",
+				Type:        TypeText,
+				Required:    true,
+				Placeholder: "在此填写完整的请求地址，必须使用 HTTPS 协议",
+				Description: "接口请求的完整 HTTPS URL，例如 https://api.example.com/webhook",
+			},
+			{
+				Key:         KeyOther,
+				Label:       "请求体 (JSON)",
+				Type:        TypeTextarea,
+				Required:    true,
+				Placeholder: "在此输入请求体，支持模板变量，必须为合法的 JSON 格式",
+				Description: "可使用的变量：$title, $description, $content, $url, $to。例如 {\"text\": \"$content\"}",
+			},
+		},
+	})
+
+	// Register Lark robot channel
+	RegisterChannelDefinition(Definition{
+		Type:        channelLark,
+		Name:        "飞书群机器人",
+		Description: "配置飞书群自定义机器人的 Webhook 接口投递。",
+		Fields: []Field{
+			{
+				Key:         KeyURL,
+				Label:       "Webhook 地址",
+				Type:        TypeText,
+				Required:    true,
+				Placeholder: "https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_TOKEN",
+				Description: "从飞书群机器人设置中复制 of Webhook URL",
+				// Note: using 'of' was in feishu.go, let's keep original wording or fix it
+			},
+			{
+				Key:         KeyToken,
+				Label:       "签名校验密钥 (Secret) (可选)",
+				Type:        TypeText,
+				Required:    false,
+				Placeholder: "可选，若机器人启用了安全设置中的签名校验，请在此输入",
+				Description: "飞书群机器人安全设置中的签名校验 Key",
+			},
+			{
+				Key:         KeyOther,
+				Label:       "自定义卡片 JSON 模版 (可选)",
+				Type:        TypeTextarea,
+				Required:    false,
+				Placeholder: "可选，留空则默认使用系统内置的精美互动卡片",
+				Description: "若填写，必须是合法的飞书卡片 JSON 格式",
+			},
+		},
+	})
+
+	// Register Telegram channel
+	RegisterChannelDefinition(Definition{
+		Type:        channelTelegram,
+		Name:        "Telegram 机器人",
+		Description: "配置 Telegram 机器人推送消息。",
+		Fields: []Field{
+			{
+				Key:         KeyURL,
+				Label:       "API 基础地址 (可选)",
+				Type:        TypeText,
+				Required:    false,
+				Placeholder: "https://api.telegram.org",
+				Description: "接口请求的 HTTPS 基础地址，留空默认为 https://api.telegram.org",
+			},
+			{
+				Key:         KeyToken,
+				Label:       "机器人 Token (Bot Token)",
+				Type:        TypePassword,
+				Required:    true,
+				Placeholder: "在此输入 Telegram 机器人的 Bot Token",
+				Description: "通过 BotFather 申请到的机器人 Access Token",
+			},
+			{
+				Key:         KeyOther,
+				Label:       "默认会话 ID (Chat ID) (可选)",
+				Type:        TypeText,
+				Required:    false,
+				Placeholder: "例如 -100123456789 或 @channel_name",
+				Description: "默认的消息接收 Chat ID。如果通知事件中未配置 targets，将推送到此 ID",
+			},
+		},
+	})
+
+	// Register Email channel
+	RegisterChannelDefinition(Definition{
+		Type:        channelEmail,
+		Name:        "邮件推送通道",
+		Description: "邮件推送通道直接使用系统全局 SMTP 设置进行发送，无需在此填写服务器配置。",
+		Fields:      []Field{},
+	})
+}

Wavelet/internal/apps/admin/push/constants.go

@@ -0,0 +1,15 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package push
+
+const (
+	channelCustom    = "custom"
+	channelEmail     = "email"
+	channelLark      = "lark"
+	channelTelegram  = "telegram"
+	defaultLevelInfo = "INFO"
+	keyTitle         = "title"
+	keyContent       = "content"
+	keyLevel         = "level"
+)

Wavelet/internal/apps/admin/push/custom_events/admin_login.go

@@ -0,0 +1,38 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package custom_events defines custom push notification events.
+package custom_events
+
+import (
+	"context"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/admin/push"
+	"github.com/Rain-kl/Wavelet/internal/listener"
+)
+
+// AdminLogin is the metadata definition for the admin login event.
+var AdminLogin = push.EventMetadata{
+	Key:  "admin_login",
+	Name: "管理员登录",
+	DefaultTemplate: push.NotificationMessage{
+		Title:   "管理员登录提醒",
+		Content: "管理员 {{user.username}} 于 {{time}} 从 IP {{ip}} 登录系统。",
+		Level:   "INFO",
+	},
+	Description: "当管理员成功登录系统时触发此通知",
+}
+
+func handleAdminLogin(ctx context.Context, event listener.AdminLoggedIn) {
+	if event.User == nil {
+		return
+	}
+
+	body := map[string]any{
+		"user": event.User,
+		"ip":   event.IP,
+		"time": time.Now().Format("2006-01-02 15:04:05"),
+	}
+	push.DefaultTrigger.Trigger(ctx, AdminLogin, body)
+}

Wavelet/internal/apps/admin/push/custom_events/admin_login_test.go

@@ -0,0 +1,175 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package custom_events
+
+import (
+	"context"
+	"encoding/json"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/admin/push"
+	"github.com/Rain-kl/Wavelet/internal/listener"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/task"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+	"github.com/hibiken/asynq"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm"
+)
+
+var registerOnce sync.Once
+
+func ensureRegistered() {
+	registerOnce.Do(Register)
+}
+
+func setupAdminLoginIntegrationTest(t *testing.T) (*gorm.DB, func()) {
+	t.Helper()
+
+	dbConn, mr, cleanup := testhelper.SetupTestEnvironment(t)
+
+	err := dbConn.AutoMigrate(
+		&model.PushEvent{},
+		&model.PushHistory{},
+		&model.PushChannel{},
+	)
+	require.NoError(t, err)
+
+	sysUser := &model.User{
+		ID:       999,
+		Username: "system",
+		Nickname: "系统",
+		Password: "*",
+		IsActive: true,
+	}
+	require.NoError(t, dbConn.Create(sysUser).Error)
+
+	task.AsynqClient = asynq.NewClient(asynq.RedisClientOpt{Addr: mr.Addr()})
+	task.RegisterHandler(push.SendNotificationTask, &push.PushHandler{})
+	task.RegisterTaskMeta(push.SendNotificationMeta)
+
+	ensureRegistered()
+
+	require.NoError(t, push.SyncEvents(context.Background()))
+
+	return dbConn, func() {
+		cleanup()
+		if task.AsynqClient != nil {
+			task.AsynqClient.Close()
+			task.AsynqClient = nil
+		}
+	}
+}
+
+func seedMockPushChannel(t *testing.T, dbConn *gorm.DB) *model.PushChannel {
+	t.Helper()
+
+	channel := &model.PushChannel{
+		Name:    "mock_channel",
+		Type:    "custom",
+		URL:     "https://webhook.site/admin-login",
+		Other:   `{"text": "$content"}`,
+		Enabled: true,
+	}
+	require.NoError(t, dbConn.Create(channel).Error)
+	return channel
+}
+
+func enableAdminLoginEvent(t *testing.T, dbConn *gorm.DB, channelName string, targets []string) {
+	t.Helper()
+
+	var event model.PushEvent
+	require.NoError(t, dbConn.Where("event_key = ?", AdminLogin.Key).First(&event).Error)
+
+	event.Enabled = true
+	event.Channels = []string{channelName}
+	event.Targets = targets
+	require.NoError(t, dbConn.Save(&event).Error)
+}
+
+func waitForAsyncTrigger(t *testing.T) {
+	t.Helper()
+	time.Sleep(100 * time.Millisecond)
+}
+
+func countPushTasks(t *testing.T, dbConn *gorm.DB) int64 {
+	t.Helper()
+
+	var count int64
+	require.NoError(t, dbConn.Model(&model.TaskExecution{}).
+		Where("task_type = ?", push.SendNotificationTask).
+		Count(&count).Error)
+	return count
+}
+
+func TestAdminLoginPushIntegration(t *testing.T) {
+	dbConn, cleanup := setupAdminLoginIntegrationTest(t)
+	defer cleanup()
+
+	channel := seedMockPushChannel(t, dbConn)
+	defer dbConn.Delete(channel)
+
+	enableAdminLoginEvent(t, dbConn, channel.Name, []string{"ops_team"})
+
+	adminUser := &model.User{
+		ID:       1001,
+		Username: "super_admin",
+		IsAdmin:  true,
+		IsActive: true,
+	}
+	require.NoError(t, dbConn.Create(adminUser).Error)
+
+	t.Run("admin login emits push task with user and ip", func(t *testing.T) {
+		dbConn.Where("task_type = ?", push.SendNotificationTask).Delete(&model.TaskExecution{})
+
+		listener.EmitAdminLoggedIn(context.Background(), adminUser, "203.0.113.42")
+		waitForAsyncTrigger(t)
+
+		var execution model.TaskExecution
+		require.NoError(t, dbConn.Where("task_type = ?", push.SendNotificationTask).First(&execution).Error)
+
+		var payload push.SendPayload
+		require.NoError(t, json.Unmarshal([]byte(execution.Payload), &payload))
+
+		assert.Equal(t, AdminLogin.Key, payload.EventKey)
+		assert.Equal(t, "ops_team", payload.Target)
+		assert.Equal(t, "管理员登录提醒", payload.Body.Title)
+		assert.Contains(t, payload.Body.Content, "super_admin")
+		assert.Contains(t, payload.Body.Content, "203.0.113.42")
+	})
+
+	t.Run("non-admin login does not trigger push", func(t *testing.T) {
+		dbConn.Where("task_type = ?", push.SendNotificationTask).Delete(&model.TaskExecution{})
+
+		nonAdmin := &model.User{
+			ID:       2002,
+			Username: "regular_user",
+			IsAdmin:  false,
+			IsActive: true,
+		}
+		require.NoError(t, dbConn.Create(nonAdmin).Error)
+
+		listener.EmitAdminLoggedIn(context.Background(), nonAdmin, "198.51.100.1")
+		waitForAsyncTrigger(t)
+
+		assert.Equal(t, int64(0), countPushTasks(t, dbConn))
+	})
+
+	t.Run("disabled admin login event does not enqueue push", func(t *testing.T) {
+		dbConn.Where("task_type = ?", push.SendNotificationTask).Delete(&model.TaskExecution{})
+
+		var event model.PushEvent
+		require.NoError(t, dbConn.Where("event_key = ?", AdminLogin.Key).First(&event).Error)
+		event.Enabled = false
+		require.NoError(t, dbConn.Save(&event).Error)
+
+		listener.EmitAdminLoggedIn(context.Background(), adminUser, "10.0.0.1")
+		waitForAsyncTrigger(t)
+
+		assert.Equal(t, int64(0), countPushTasks(t, dbConn))
+	})
+}

Wavelet/internal/apps/admin/push/custom_events/register.go

@@ -0,0 +1,17 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package custom_events
+
+import (
+	"github.com/Rain-kl/Wavelet/internal/apps/admin/push"
+	"github.com/Rain-kl/Wavelet/internal/listener"
+)
+
+// Register wires push notification handlers for domain events and registers
+// built-in event metadata. Must be called once during application bootstrap
+// before push.SyncEvents.
+func Register() {
+	push.RegisterBuiltInEvent(AdminLogin)
+	listener.OnAdminLoggedIn(handleAdminLogin)
+}

Wavelet/internal/apps/admin/push/events.go

@@ -0,0 +1,343 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package push defines push notification HTTP routes, background tasks, and events.
+package push
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/task"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	pkgpush "github.com/Rain-kl/Wavelet/pkg/push"
+	"gorm.io/gorm"
+)
+
+// NotificationMessage represents the structured notification message payload.
+type NotificationMessage struct {
+	Title   string         `json:"title"`
+	Content string         `json:"content"`
+	Level   string         `json:"level"`
+	Ext     map[string]any `json:"ext,omitempty"`
+}
+
+// Flatten converts the structured NotificationMessage back to a flat map (original json structure).
+func (m NotificationMessage) Flatten() map[string]any {
+	res := map[string]any{
+		keyTitle:   m.Title,
+		keyContent: m.Content,
+		keyLevel:   m.Level,
+	}
+	for k, v := range m.Ext {
+		res[k] = v
+	}
+	return res
+}
+
+// EventMetadata represents the metadata of a push notification event.
+type EventMetadata struct {
+	Key             string              `json:"key"`
+	Name            string              `json:"name"`
+	DefaultTemplate NotificationMessage `json:"default_template"`
+	Description     string              `json:"description"`
+}
+
+// SendPayload 异步投递推送载荷 (供 task/Worker 使用)
+type SendPayload struct {
+	EventKey string              `json:"event_key"`
+	Config   pkgpush.Config      `json:"config"`
+	Target   string              `json:"target"`
+	Body     NotificationMessage `json:"body"`
+	Template string              `json:"template"`
+}
+
+// BuiltInEvents lists all built-in events defined in custom_events.
+var BuiltInEvents []EventMetadata
+
+// RegisterBuiltInEvent registers a built-in event definition.
+func RegisterBuiltInEvent(meta EventMetadata) {
+	BuiltInEvents = append(BuiltInEvents, meta)
+}
+
+// EventTrigger represents the unified event trigger class.
+type EventTrigger struct{}
+
+// DefaultTrigger is the singleton instance of EventTrigger.
+var DefaultTrigger = &EventTrigger{}
+
+// Trigger receives event metadata and processes the event notification dispatch asynchronously.
+//
+//nolint:contextcheck
+func (t *EventTrigger) Trigger(ctx context.Context, meta EventMetadata, body map[string]any) {
+	asyncCtx := context.WithoutCancel(ctx)
+	go func() {
+		if body == nil {
+			body = make(map[string]any)
+		}
+		if _, hasUser := body["user"]; !hasUser || body["user"] == nil {
+			body["user"] = getSystemUser(asyncCtx)
+		}
+
+		eventPtr, err := repository.GetActivePushEventByKey(asyncCtx, meta.Key)
+		if err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return
+			}
+			logger.ErrorF(asyncCtx, "push_event_trigger: failed to get active event %s: %v", meta.Key, err)
+			return
+		}
+		event := *eventPtr
+		if len(event.Channels) == 0 {
+			return
+		}
+
+		flatBody := getFlatBody(body)
+		msg, _ := t.buildMessage(&event, meta, flatBody, body)
+		t.enqueuePushTasks(asyncCtx, meta, &event, msg, flatBody)
+	}()
+}
+
+func (t *EventTrigger) buildMessage(event *model.PushEvent, meta EventMetadata, flatBody map[string]any, body map[string]any) (NotificationMessage, string) {
+	var msg NotificationMessage
+	renderedTemplate := ""
+
+	templateSource := event.Template
+	if templateSource != "" {
+		var err error
+		msg, renderedTemplate, err = t.parseCustomTemplate(event, templateSource, flatBody)
+		if err != nil {
+			msg.Title = event.Name
+			msg.Content = renderedTemplate
+			msg.Level = defaultLevelInfo
+		}
+	} else {
+		msg = t.parseDefaultTemplate(meta, flatBody)
+	}
+
+	if msg.Ext == nil {
+		msg.Ext = make(map[string]any)
+	}
+	for k, v := range body {
+		if k == keyTitle || k == keyContent || k == keyLevel {
+			continue
+		}
+		if _, exists := msg.Ext[k]; !exists {
+			msg.Ext[k] = v
+		}
+	}
+
+	return msg, renderedTemplate
+}
+
+func (t *EventTrigger) parseCustomTemplate(event *model.PushEvent, templateSource string, flatBody map[string]any) (NotificationMessage, string, error) {
+	var msg NotificationMessage
+	renderedTemplate := pkgpush.ParseTemplate(templateSource, flatBody)
+
+	var tMap map[string]any
+	if err := json.Unmarshal([]byte(renderedTemplate), &tMap); err != nil {
+		return msg, renderedTemplate, err
+	}
+
+	if title, ok := tMap[keyTitle].(string); ok && title != "" {
+		msg.Title = title
+	} else {
+		msg.Title = event.Name
+	}
+	delete(tMap, keyTitle)
+
+	if content, ok := tMap[keyContent].(string); ok && content != "" {
+		msg.Content = content
+	} else {
+		msg.Content = renderedTemplate
+	}
+	delete(tMap, keyContent)
+
+	if level, ok := tMap[keyLevel].(string); ok && level != "" {
+		msg.Level = level
+	} else {
+		msg.Level = defaultLevelInfo
+	}
+	delete(tMap, keyLevel)
+
+	msg.Ext = tMap
+	return msg, renderedTemplate, nil
+}
+
+func (t *EventTrigger) parseDefaultTemplate(meta EventMetadata, flatBody map[string]any) NotificationMessage {
+	var msg NotificationMessage
+	msg.Title = pkgpush.ParseTemplate(meta.DefaultTemplate.Title, flatBody)
+	msg.Content = pkgpush.ParseTemplate(meta.DefaultTemplate.Content, flatBody)
+	msg.Level = pkgpush.ParseTemplate(meta.DefaultTemplate.Level, flatBody)
+
+	if meta.DefaultTemplate.Ext != nil {
+		msg.Ext = make(map[string]any)
+		for k, v := range meta.DefaultTemplate.Ext {
+			if strVal, ok := v.(string); ok {
+				msg.Ext[k] = pkgpush.ParseTemplate(strVal, flatBody)
+			} else {
+				msg.Ext[k] = v
+			}
+		}
+	}
+	return msg
+}
+
+func (t *EventTrigger) enqueuePushTasks(ctx context.Context, meta EventMetadata, event *model.PushEvent, msg NotificationMessage, flatBody map[string]any) {
+	for _, channelName := range event.Channels {
+		customChannel, err := repository.GetActivePushChannelByName(ctx, channelName)
+		if err == nil {
+			t.enqueueCustomPushChannelTasks(ctx, meta, event, customChannel, msg, flatBody)
+			continue
+		}
+		logger.WarnF(ctx, "push_event_trigger: channel %q not found in DB or disabled: %v", channelName, err)
+	}
+}
+
+func (t *EventTrigger) enqueueCustomPushChannelTasks(ctx context.Context, meta EventMetadata, event *model.PushEvent, channel *model.PushChannel, msg NotificationMessage, flatBody map[string]any) {
+	if len(event.Targets) == 0 {
+		t.enqueueSingleCustomPushChannelTask(ctx, meta, channel, "", msg)
+		return
+	}
+
+	for _, target := range event.Targets {
+		resolvedTarget := resolveTarget(ctx, target, flatBody, channel.Name)
+		t.enqueueSingleCustomPushChannelTask(ctx, meta, channel, resolvedTarget, msg)
+	}
+}
+
+func (t *EventTrigger) enqueueSingleCustomPushChannelTask(ctx context.Context, meta EventMetadata, channel *model.PushChannel, target string, msg NotificationMessage) {
+	var config pkgpush.Config
+	var renderedTemplate string
+
+	switch channel.Type {
+	case channelLark:
+		config = pkgpush.Config{Channel: channelLark, URL: channel.URL, Secret: channel.Token}
+		renderedTemplate = channel.Other
+	case channelEmail:
+		url, token, other := resolveSMTPConfig(ctx, channel.URL, channel.Token, channel.Other)
+		config = pkgpush.Config{Channel: channelEmail, URL: url, Key: token, Secret: other}
+	case channelTelegram:
+		config = pkgpush.Config{Channel: channelTelegram, URL: channel.URL, Secret: channel.Token, Key: channel.Other}
+	default:
+		config = pkgpush.Config{Channel: channelCustom, URL: channel.URL}
+		customPushReq := CustomPushRequest{
+			Title:       msg.Title,
+			Content:     msg.Content,
+			Description: meta.Description,
+			To:          target,
+		}
+		if urlVal, ok := msg.Ext["url"].(string); ok {
+			customPushReq.URL = urlVal
+		}
+		renderedTemplate = renderCustomPayload(channel.Other, customPushReq)
+	}
+
+	payload := SendPayload{
+		EventKey: meta.Key,
+		Config:   config,
+		Target:   target,
+		Body:     msg,
+		Template: renderedTemplate,
+	}
+	if err := enqueuePushTask(ctx, payload); err != nil {
+		logger.ErrorF(ctx, "push_event_trigger: enqueuePushTask failed for %s channel %s -> %s: %v", channel.Type, channel.Name, target, err)
+	}
+}
+
+func enqueuePushTask(ctx context.Context, payload SendPayload) error {
+	payloadBytes, err := json.Marshal(payload)
+	if err != nil {
+		return err
+	}
+	_, err = task.DispatchTask(ctx, "send_notification", payloadBytes, "system")
+	return err
+}
+
+func getFlatBody(body map[string]any) map[string]any {
+	jsonBytes, err := json.Marshal(body)
+	if err != nil {
+		return body
+	}
+	var jsonMap map[string]any
+	if err := json.Unmarshal(jsonBytes, &jsonMap); err != nil {
+		return body
+	}
+
+	flatResult := make(map[string]any)
+	flattenMap("", jsonMap, flatResult)
+	return flatResult
+}
+
+func flattenMap(prefix string, m map[string]any, result map[string]any) {
+	for k, v := range m {
+		key := k
+		if prefix != "" {
+			key = prefix + "." + k
+		}
+		if nestedMap, ok := v.(map[string]any); ok {
+			flattenMap(key, nestedMap, result)
+		} else {
+			result[key] = v
+		}
+	}
+}
+
+func resolveTarget(ctx context.Context, target string, flatBody map[string]any, channel string) string {
+	target = strings.TrimSpace(target)
+	if target == "" {
+		return ""
+	}
+
+	resolved := resolveDynamicKeyword(target, flatBody)
+	if strings.Contains(resolved, "@") {
+		return resolved
+	}
+	if val, matched := resolveSystemTarget(ctx, resolved, channel); matched {
+		return val
+	}
+
+	user, found := resolveTargetUser(ctx, resolved, channel)
+	if !found {
+		return resolved
+	}
+	if channel == channelEmail && user.Email != "" {
+		return user.Email
+	}
+	if channel != channelEmail && user.Username != "" {
+		return user.Username
+	}
+	return resolved
+}
+
+func resolveDynamicKeyword(target string, flatBody map[string]any) string {
+	switch target {
+	case "user.id", "id":
+		if val, ok := flatBody["user.id"]; ok {
+			return fmt.Sprintf("%v", val)
+		}
+		if val, ok := flatBody["id"]; ok {
+			return fmt.Sprintf("%v", val)
+		}
+	case "user.username", "username":
+		if val, ok := flatBody["user.username"]; ok {
+			return fmt.Sprintf("%v", val)
+		}
+		if val, ok := flatBody["username"]; ok {
+			return fmt.Sprintf("%v", val)
+		}
+	case "user.email", channelEmail:
+		if val, ok := flatBody["user.email"]; ok {
+			return fmt.Sprintf("%v", val)
+		}
+		if val, ok := flatBody["email"]; ok {
+			return fmt.Sprintf("%v", val)
+		}
+	}
+	return target
+}

Wavelet/internal/apps/admin/push/logics.go

@@ -0,0 +1,413 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package push
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strconv"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/task"
+	pkgpush "github.com/Rain-kl/Wavelet/pkg/push"
+	"gorm.io/gorm"
+)
+
+type smtpConfig struct {
+	Host     string
+	Port     string
+	Username string
+	Password string
+}
+
+func loadSMTPConfig(ctx context.Context) smtpConfig {
+	host, _ := repository.GetSystemConfigByKey(ctx, model.ConfigKeySMTPHost)
+	port, _ := repository.GetSystemConfigByKey(ctx, model.ConfigKeySMTPPort)
+	user, _ := repository.GetSystemConfigByKey(ctx, model.ConfigKeySMTPUsername)
+	pass, _ := repository.GetSystemConfigByKey(ctx, model.ConfigKeySMTPPassword)
+	return smtpConfig{
+		Host:     host.Value,
+		Port:     port.Value,
+		Username: user.Value,
+		Password: pass.Value,
+	}
+}
+
+func syncBuiltInEvents(ctx context.Context) error {
+	for _, meta := range BuiltInEvents {
+		_, err := repository.GetPushEventByKey(ctx, meta.Key)
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			var defaultTemplateStr string
+			if defaultTemplateBytes, err := json.Marshal(meta.DefaultTemplate); err == nil {
+				defaultTemplateStr = string(defaultTemplateBytes)
+			}
+			event := model.PushEvent{
+				EventKey: meta.Key,
+				Name:     meta.Name,
+				Channels: []string{},
+				Targets:  []string{},
+				Template: defaultTemplateStr,
+				Enabled:  false,
+			}
+			if err := repository.CreatePushEvent(ctx, &event); err != nil {
+				return err
+			}
+		} else if err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func listPushEvents(ctx context.Context) ([]model.PushEvent, error) {
+	return repository.ListPushEvents(ctx)
+}
+
+func createPushEvent(ctx context.Context, req CreateEventRequest) (model.PushEvent, error) {
+	eventKey, eventName, defaultTemplateBytes, err := getEventInfo(req)
+	if err != nil {
+		return model.PushEvent{}, err
+	}
+
+	count, err := repository.CountPushEventsByKey(ctx, eventKey)
+	if err != nil {
+		return model.PushEvent{}, err
+	}
+	if count > 0 {
+		return model.PushEvent{}, errors.New("this notification event is already configured")
+	}
+
+	templateStr := strings.TrimSpace(req.Template)
+	if templateStr == "" {
+		templateStr = string(defaultTemplateBytes)
+	} else {
+		var tempMap map[string]any
+		if err := json.Unmarshal([]byte(templateStr), &tempMap); err != nil {
+			return model.PushEvent{}, errors.New("custom template is not a valid JSON format")
+		}
+	}
+
+	channels := req.Channels
+	if channels == nil {
+		channels = []string{}
+	}
+	targets := req.Targets
+	if targets == nil {
+		targets = []string{}
+	}
+
+	event := model.PushEvent{
+		EventKey: eventKey,
+		Name:     eventName,
+		TaskType: req.TaskType,
+		Channels: channels,
+		Targets:  targets,
+		Template: templateStr,
+		Enabled:  req.Enabled,
+	}
+	if err := event.Validate(); err != nil {
+		return model.PushEvent{}, err
+	}
+	if err := repository.CreatePushEvent(ctx, &event); err != nil {
+		return model.PushEvent{}, err
+	}
+	return event, nil
+}
+
+func deletePushEvent(ctx context.Context, id uint64) error {
+	event, err := repository.GetPushEventByID(ctx, id)
+	if err != nil {
+		return err
+	}
+	return repository.DeletePushEvent(ctx, &event)
+}
+
+func updatePushEvent(ctx context.Context, id uint64, req UpdateEventRequest) error {
+	event, err := repository.GetPushEventByID(ctx, id)
+	if err != nil {
+		return err
+	}
+
+	event.Channels = req.Channels
+	event.Targets = req.Targets
+	event.Template = req.Template
+	event.Enabled = req.Enabled
+	if err := event.Validate(); err != nil {
+		return err
+	}
+	return repository.SavePushEvent(ctx, &event)
+}
+
+func togglePushEvent(ctx context.Context, id uint64) (bool, error) {
+	event, err := repository.GetPushEventByID(ctx, id)
+	if err != nil {
+		return false, err
+	}
+
+	enabled := !event.Enabled
+	if enabled && len(event.Channels) == 0 {
+		return false, errors.New("cannot enable event without any push channels configured")
+	}
+	if err := repository.UpdatePushEventEnabled(ctx, &event, enabled); err != nil {
+		return false, err
+	}
+	return enabled, nil
+}
+
+func listPushHistories(ctx context.Context, filter repository.PushHistoryListFilter) (int64, []model.PushHistory, error) {
+	return repository.ListPushHistories(ctx, filter)
+}
+
+func applySMTPFallbackToPushConfig(ctx context.Context, cfg *pkgpush.Config) {
+	if cfg.Channel != channelEmail || (cfg.URL != "" && cfg.Key != "") {
+		return
+	}
+	smtp := loadSMTPConfig(ctx)
+	if smtp.Host == "" || smtp.Username == "" {
+		return
+	}
+	port := smtp.Port
+	if port == "" {
+		port = "587"
+	}
+	cfg.URL = smtp.Host + ":" + port
+	cfg.Key = smtp.Username
+	cfg.Secret = smtp.Password
+}
+
+func listPushChannels(ctx context.Context) ([]model.PushChannel, error) {
+	return repository.ListPushChannels(ctx)
+}
+
+func createPushChannel(ctx context.Context, req CreateChannelRequest) (model.PushChannel, error) {
+	count, err := repository.CountPushChannelsByName(ctx, req.Name)
+	if err != nil {
+		return model.PushChannel{}, err
+	}
+	if count > 0 {
+		return model.PushChannel{}, errors.New("channel name already exists")
+	}
+
+	channel := model.PushChannel{
+		Name:        req.Name,
+		Description: req.Description,
+		Type:        req.Type,
+		Token:       req.Token,
+		URL:         req.URL,
+		Other:       req.Other,
+		Enabled:     req.Enabled,
+	}
+	if err := channel.Validate(); err != nil {
+		return model.PushChannel{}, err
+	}
+	if err := repository.CreatePushChannel(ctx, &channel); err != nil {
+		return model.PushChannel{}, err
+	}
+	return channel, nil
+}
+
+func updatePushChannel(ctx context.Context, id uint64, req UpdateChannelRequest) (model.PushChannel, error) {
+	channel, err := repository.GetPushChannelByID(ctx, id)
+	if err != nil {
+		return model.PushChannel{}, err
+	}
+
+	channel.Description = req.Description
+	channel.Type = req.Type
+	channel.Token = req.Token
+	channel.URL = req.URL
+	channel.Other = req.Other
+	channel.Enabled = req.Enabled
+	if err := channel.Validate(); err != nil {
+		return model.PushChannel{}, err
+	}
+	if err := repository.SavePushChannel(ctx, &channel); err != nil {
+		return model.PushChannel{}, err
+	}
+	return channel, nil
+}
+
+func deletePushChannel(ctx context.Context, id uint64) error {
+	channel, err := repository.GetPushChannelByID(ctx, id)
+	if err != nil {
+		return err
+	}
+	return repository.DeletePushChannel(ctx, &channel)
+}
+
+func loadChannelForTest(ctx context.Context, req TestChannelRequest) (string, string, string, string, error) {
+	if req.Name != "" {
+		channel, err := repository.GetPushChannelByName(ctx, req.Name)
+		if err != nil {
+			return "", "", "", "", errors.New("channel not found")
+		}
+		return channel.URL, channel.Token, channel.Other, channel.Type, nil
+	}
+	return req.URL, req.Token, req.Other, req.Type, nil
+}
+
+func listActivePushEventsByTaskType(ctx context.Context, taskType string) ([]model.PushEvent, error) {
+	return repository.ListActivePushEventsByTaskType(ctx, taskType)
+}
+
+func loadUserFromPayload(ctx context.Context, data map[string]any) any {
+	if u, exists := data["user"]; exists && u != nil {
+		return u
+	}
+
+	if userID, ok := extractUserID(data); ok && userID > 0 {
+		if user, err := repository.GetUserByID(ctx, userID); err == nil {
+			return &user
+		}
+	}
+
+	if username := extractUsername(data); username != "" {
+		if user, err := repository.GetUserByUsername(ctx, username); err == nil {
+			return &user
+		}
+	}
+	return nil
+}
+
+func recordPushHistory(ctx context.Context, req SendPayload, status, errMsg string) error {
+	title := req.Body.Title
+	content := req.Body.Content
+	level := req.Body.Level
+	if title == "" {
+		title = "系统通知"
+	}
+	if level == "" {
+		level = defaultLevelInfo
+	}
+
+	target := req.Target
+	if target == "" {
+		if req.Config.URL != "" {
+			target = req.Config.URL
+			const maxTargetLen = 50
+			const truncatedLen = 47
+			if len(target) > maxTargetLen {
+				target = target[:truncatedLen] + "..."
+			}
+		} else {
+			target = "default"
+		}
+	}
+
+	history := model.PushHistory{
+		EventKey: req.EventKey,
+		Channel:  req.Config.Channel,
+		Target:   target,
+		Title:    title,
+		Content:  content,
+		Level:    level,
+		Status:   status,
+		ErrorMsg: errMsg,
+	}
+	return repository.CreatePushHistory(ctx, &history)
+}
+
+func resolveTargetUser(ctx context.Context, resolved string, _ string) (model.User, bool) {
+	found := false
+	var user model.User
+
+	if id, err := strconv.ParseUint(resolved, 10, 64); err == nil {
+		if u, err := repository.GetUserByID(ctx, id); err == nil {
+			user = u
+			found = true
+		}
+	}
+	if !found {
+		if u, err := repository.GetUserByUsername(ctx, resolved); err == nil {
+			user = u
+			found = true
+		}
+	}
+	return user, found
+}
+
+func resolveSystemTarget(ctx context.Context, resolved string, channel string) (string, bool) {
+	if resolved != "系统" && resolved != "system" && resolved != "0" {
+		return "", false
+	}
+	adminUser, err := repository.GetFirstAdminUser(ctx)
+	if err != nil {
+		return resolved, true
+	}
+	if channel == channelEmail && adminUser.Email != "" {
+		return adminUser.Email, true
+	}
+	if channel != channelEmail && adminUser.Username != "" {
+		return adminUser.Username, true
+	}
+	return resolved, true
+}
+
+func resolveSMTPConfig(ctx context.Context, url, token, other string) (string, string, string) {
+	if url != "" && token != "" {
+		return url, token, other
+	}
+	smtp := loadSMTPConfig(ctx)
+	if smtp.Host == "" || smtp.Username == "" {
+		return url, token, other
+	}
+	port := smtp.Port
+	if port == "" {
+		port = "587"
+	}
+	if url == "" {
+		url = smtp.Host + ":" + port
+	}
+	if token == "" {
+		token = smtp.Username
+	}
+	if other == "" {
+		other = smtp.Password
+	}
+	return url, token, other
+}
+
+func getSystemUser(ctx context.Context) *model.User {
+	user := repository.GetSystemUser(ctx)
+	return &user
+}
+
+func getEventInfo(req CreateEventRequest) (string, string, []byte, error) {
+	if req.TaskType != "" {
+		meta := task.GetTaskMetaByAsynqTask(req.TaskType)
+		if meta == nil {
+			return "", "", nil, errors.New("unsupported task type")
+		}
+		eventKey := "task_completed:" + req.TaskType
+		eventName := "任务完成: " + meta.Name
+		defaultTemplate := NotificationMessage{
+			Title:   "任务完成: " + meta.Name,
+			Content: "异步任务 {{task_name}} (ID: {{task_id}}) 已完成。状态: {{task_status}}，耗时: {{task_duration}} ms。",
+			Level:   defaultLevelInfo,
+		}
+		defaultTemplateBytes, err := json.Marshal(defaultTemplate)
+		if err != nil {
+			return "", "", nil, err
+		}
+		return eventKey, eventName, defaultTemplateBytes, nil
+	}
+
+	if req.EventKey == "" {
+		return "", "", nil, errors.New("either event_key or task_type must be provided")
+	}
+
+	meta, found := findBuiltInEvent(req.EventKey)
+	if !found {
+		return "", "", nil, errors.New("unsupported built-in event key")
+	}
+
+	defaultTemplateBytes, err := json.Marshal(meta.DefaultTemplate)
+	if err != nil {
+		return "", "", nil, err
+	}
+	return req.EventKey, meta.Name, defaultTemplateBytes, nil
+}

Wavelet/internal/apps/admin/push/push_test.go

@@ -0,0 +1,759 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package push
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/task"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+	pkgpush "github.com/Rain-kl/Wavelet/pkg/push"
+	"github.com/alicebob/miniredis/v2"
+	"github.com/gin-gonic/gin"
+	"github.com/hibiken/asynq"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+var adminLoginEvent = EventMetadata{
+	Key:  "admin_login",
+	Name: "管理员登录",
+	DefaultTemplate: NotificationMessage{
+		Title:   "管理员登录提醒",
+		Content: "管理员 {{user.username}} 于 {{time}} 从 IP {{ip}} 登录系统。",
+		Level:   "INFO",
+	},
+	Description: "当管理员成功登录系统时触发此通知",
+}
+
+func init() {
+	RegisterBuiltInEvent(adminLoginEvent)
+}
+
+// mockPusher mock implementation of pkgpush.Pusher
+type mockPusher struct {
+	mu       sync.Mutex
+	sentBody map[string]any
+	sentTgt  string
+}
+
+func (m *mockPusher) Send(ctx context.Context, cfg pkgpush.Config, target string, body map[string]any, template string, ext map[string]any) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.sentBody = body
+	m.sentTgt = target
+	return nil
+}
+
+func (m *mockPusher) ValidateConfig(cfg pkgpush.Config) error {
+	return nil
+}
+
+func setupPushTest(t *testing.T) (*gorm.DB, *miniredis.Miniredis, func()) {
+	dbConn, mr, cleanup := testhelper.SetupTestEnvironment(t)
+
+	// AutoMigrate push tables in SQLite test environment
+	err := dbConn.AutoMigrate(&model.PushEvent{}, &model.PushHistory{}, &model.User{}, &model.PushChannel{}, &model.SystemConfig{})
+	require.NoError(t, err)
+
+	// 写入数据库系统默认用户 Seed 记录
+	sysUser := &model.User{
+		ID:       999,
+		Username: "system",
+		Nickname: "系统",
+		Password: "*",
+		IsActive: true,
+	}
+	err = dbConn.Create(sysUser).Error
+	require.NoError(t, err)
+
+	// Initialize AsynqClient pointing to miniredis
+	task.AsynqClient = asynq.NewClient(asynq.RedisClientOpt{
+		Addr: mr.Addr(),
+	})
+
+	// Register the task handler and metadata
+	task.RegisterHandler(SendNotificationTask, &PushHandler{})
+	task.RegisterTaskMeta(SendNotificationMeta)
+
+	return dbConn, mr, func() {
+		cleanup()
+		if task.AsynqClient != nil {
+			task.AsynqClient.Close()
+			task.AsynqClient = nil
+		}
+	}
+}
+
+func setupTestRouter(authUser *model.User) *gin.Engine {
+	r := testhelper.NewTestGinEngine()
+	adminGroup := r.Group("/api/v1/admin/push")
+
+	adminGroup.Use(func(c *gin.Context) {
+		if authUser != nil {
+			oauth.SetToContext(c, "user_obj", authUser)
+		}
+		c.Next()
+	})
+
+	adminGroup.GET("/events", ListEvents)
+	adminGroup.GET("/events/builtin", ListBuiltInEvents)
+	adminGroup.POST("/events", CreateEvent)
+	adminGroup.PUT("/events/:id", UpdateEvent)
+	adminGroup.DELETE("/events/:id", DeleteEvent)
+	adminGroup.POST("/events/:id/toggle", ToggleEvent)
+	adminGroup.GET("/histories", ListHistories)
+	adminGroup.POST("/test", TestPush)
+
+	return r
+}
+
+func TestSyncEvents(t *testing.T) {
+	dbConn, _, cleanup := setupPushTest(t)
+	defer cleanup()
+
+	// 1. SyncEvents first time
+	err := SyncEvents(context.Background())
+	require.NoError(t, err)
+
+	// Verify event exists in DB
+	var event model.PushEvent
+	err = dbConn.Where("event_key = ?", "admin_login").First(&event).Error
+	require.NoError(t, err)
+	assert.Equal(t, "管理员登录", event.Name)
+	assert.False(t, event.Enabled)
+
+	// Verify DefaultTemplate matches GORM template field
+	var defaultMsg NotificationMessage
+	err = json.Unmarshal([]byte(event.Template), &defaultMsg)
+	require.NoError(t, err)
+	assert.Equal(t, adminLoginEvent.DefaultTemplate.Title, defaultMsg.Title)
+	assert.Equal(t, adminLoginEvent.DefaultTemplate.Content, defaultMsg.Content)
+}
+
+func TestEventTrigger(t *testing.T) {
+	dbConn, _, cleanup := setupPushTest(t)
+	defer cleanup()
+
+	// SyncEvents
+	err := SyncEvents(context.Background())
+	require.NoError(t, err)
+
+	t.Run("trigger disabled event silently ignored", func(t *testing.T) {
+		body := map[string]any{
+			"user": map[string]any{"username": "test_admin"},
+			"ip":   "127.0.0.1",
+		}
+		DefaultTrigger.Trigger(context.Background(), adminLoginEvent, body)
+
+		// Sleep briefly since Trigger runs in goroutine
+		time.Sleep(50 * time.Millisecond)
+
+		// Verify no tasks enqueued in TaskExecution GORM table
+		var count int64
+		dbConn.Model(&model.TaskExecution{}).Count(&count)
+		assert.Equal(t, int64(0), count)
+	})
+
+	t.Run("trigger enabled event enqueues task", func(t *testing.T) {
+		// Create an enabled custom channel in GORM
+		customChan := &model.PushChannel{
+			Name:    "mock_channel",
+			Type:    "custom",
+			URL:     "https://webhook.site/trigger",
+			Other:   `{"text": "$content"}`,
+			Enabled: true,
+		}
+		err = dbConn.Create(customChan).Error
+		require.NoError(t, err)
+		defer dbConn.Delete(customChan)
+
+		// Enable the push event in DB using struct to trigger JSON serializer
+		var event model.PushEvent
+		err = dbConn.Where("event_key = ?", "admin_login").First(&event).Error
+		require.NoError(t, err)
+
+		event.Enabled = true
+		event.Channels = []string{"mock_channel"}
+		event.Targets = []string{"admin_user"}
+		err = dbConn.Save(&event).Error
+		require.NoError(t, err)
+
+		// Trigger
+		body := map[string]any{
+			"user": map[string]any{
+				"username": "super_admin",
+			},
+			"ip":   "1.1.1.1",
+			"time": "2026-06-14 18:00:00",
+		}
+		DefaultTrigger.Trigger(context.Background(), adminLoginEvent, body)
+
+		// Wait for goroutine execution
+		time.Sleep(50 * time.Millisecond)
+
+		// Verify TaskExecution enqueued record
+		var execution model.TaskExecution
+		err = dbConn.Where("task_type = ?", SendNotificationTask).First(&execution).Error
+		require.NoError(t, err)
+
+		// Verify enqueued payload structure
+		var payload SendPayload
+		err = json.Unmarshal([]byte(execution.Payload), &payload)
+		require.NoError(t, err)
+		assert.Equal(t, "admin_login", payload.EventKey)
+		assert.Equal(t, "custom", payload.Config.Channel)
+		assert.Equal(t, "https://webhook.site/trigger", payload.Config.URL)
+		assert.Equal(t, "admin_user", payload.Target)
+		assert.Equal(t, "管理员登录提醒", payload.Body.Title)
+		assert.Contains(t, payload.Body.Content, "super_admin")
+		assert.Contains(t, payload.Body.Content, "1.1.1.1")
+	})
+
+	t.Run("trigger without user injects virtual system user", func(t *testing.T) {
+		// Create an enabled custom channel in GORM
+		customChan := &model.PushChannel{
+			Name:    "mock_channel",
+			Type:    "custom",
+			URL:     "https://webhook.site/trigger",
+			Other:   `{"text": "$content"}`,
+			Enabled: true,
+		}
+		err = dbConn.Create(customChan).Error
+		require.NoError(t, err)
+		defer dbConn.Delete(customChan)
+
+		// Enable the push event in DB
+		var event model.PushEvent
+		err = dbConn.Where("event_key = ?", "admin_login").First(&event).Error
+		require.NoError(t, err)
+
+		// 清理旧任务执行记录
+		dbConn.Where("task_type = ?", SendNotificationTask).Delete(&model.TaskExecution{})
+
+		event.Enabled = true
+		event.Channels = []string{"mock_channel"}
+		event.Targets = []string{"user.username"} // 动态目标
+		err = dbConn.Save(&event).Error
+		require.NoError(t, err)
+
+		// Trigger with empty body (simulates cron scheduler triggering)
+		DefaultTrigger.Trigger(context.Background(), adminLoginEvent, nil)
+
+		// Wait for goroutine execution
+		time.Sleep(50 * time.Millisecond)
+
+		// Verify TaskExecution enqueued record
+		var execution model.TaskExecution
+		err = dbConn.Where("task_type = ?", SendNotificationTask).First(&execution).Error
+		require.NoError(t, err)
+
+		var payload SendPayload
+		err = json.Unmarshal([]byte(execution.Payload), &payload)
+		require.NoError(t, err)
+
+		// 检查 payload 是否将 target (user.username) 成功替换为 "system"
+		assert.Equal(t, "system", payload.Target)
+		// 检查 payload 中的 Content，应当被替换为 "system" 变量
+		assert.Contains(t, payload.Body.Content, "system")
+	})
+}
+
+func TestPushHandler(t *testing.T) {
+	dbConn, _, cleanup := setupPushTest(t)
+	defer cleanup()
+
+	mPusher := &mockPusher{}
+	pkgpush.Register("mock_channel", mPusher)
+
+	handler := &PushHandler{}
+
+	payload := SendPayload{
+		EventKey: "admin_login",
+		Config: pkgpush.Config{
+			Channel: "mock_channel",
+			URL:     "http://mock-url",
+		},
+		Target: "admin_user",
+		Body: NotificationMessage{
+			Title:   "Structured Alert",
+			Content: "Hello World",
+			Level:   "WARNING",
+			Ext:     map[string]any{"extra_val": 42},
+		},
+	}
+	payloadBytes, err := json.Marshal(payload)
+	require.NoError(t, err)
+
+	t.Run("validate payload", func(t *testing.T) {
+		validated, valErr := handler.ValidatePayload(payloadBytes)
+		require.NoError(t, valErr)
+		assert.NotEmpty(t, validated)
+	})
+
+	t.Run("execute task successfully", func(t *testing.T) {
+		res, execErr := handler.Execute(context.Background(), payloadBytes)
+		require.NoError(t, execErr)
+		assert.Contains(t, res.Message, "推送成功")
+
+		// Verify mock pusher received flattened variables
+		mPusher.mu.Lock()
+		assert.Equal(t, "admin_user", mPusher.sentTgt)
+		assert.Equal(t, "Structured Alert", mPusher.sentBody["title"])
+		assert.Equal(t, "Hello World", mPusher.sentBody["content"])
+		assert.Equal(t, "WARNING", mPusher.sentBody["level"])
+		assert.Equal(t, float64(42), mPusher.sentBody["extra_val"]) // unmarshaled json numbers are float64 by default
+		mPusher.mu.Unlock()
+
+		// Verify PushHistory recorded
+		var history model.PushHistory
+		err = dbConn.First(&history).Error
+		require.NoError(t, err)
+		assert.Equal(t, "admin_login", history.EventKey)
+		assert.Equal(t, "mock_channel", history.Channel)
+		assert.Equal(t, "success", history.Status)
+		assert.Equal(t, "Structured Alert", history.Title)
+	})
+}
+
+func TestPushRouters(t *testing.T) {
+	dbConn, _, cleanup := setupPushTest(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	r := setupTestRouter(adminUser)
+
+	// Sync events to populate db
+	err := SyncEvents(context.Background())
+	require.NoError(t, err)
+
+	t.Run("list events", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/push/events", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+		var resp response.Any
+		err = json.Unmarshal(w.Body.Bytes(), &resp)
+		require.NoError(t, err)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var events []model.PushEvent
+		err = json.Unmarshal(dataBytes, &events)
+		require.NoError(t, err)
+
+		assert.Len(t, events, 1)
+		assert.Equal(t, "admin_login", events[0].EventKey)
+	})
+
+	t.Run("toggle event status", func(t *testing.T) {
+		var event model.PushEvent
+		dbConn.First(&event)
+
+		// 1. 未配置任何渠道时开启，应该被拒绝
+		req, _ := http.NewRequest("POST", "/api/v1/admin/push/events/"+strconv.FormatUint(event.ID, 10)+"/toggle", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+		assert.Equal(t, http.StatusBadRequest, w.Code)
+
+		// 2. 为该事件关联渠道后，再切换开启，应当成功
+		event.Channels = []string{"email"}
+		dbConn.Save(&event)
+
+		req2, _ := http.NewRequest("POST", "/api/v1/admin/push/events/"+strconv.FormatUint(event.ID, 10)+"/toggle", nil)
+		w2 := httptest.NewRecorder()
+		r.ServeHTTP(w2, req2)
+		assert.Equal(t, http.StatusOK, w2.Code)
+
+		var updated model.PushEvent
+		dbConn.First(&updated)
+		assert.True(t, updated.Enabled)
+	})
+
+	t.Run("update event", func(t *testing.T) {
+		var event model.PushEvent
+		dbConn.First(&event)
+
+		updateReq := UpdateEventRequest{
+			Channels: []string{"email"},
+			Targets:  []string{"user@test.com"},
+			Template: `{"title": "Custom Login Alert", "content": "Alert", "level": "WARNING"}`,
+			Enabled:  true,
+		}
+		bodyBytes, _ := json.Marshal(updateReq)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/push/events/"+strconv.FormatUint(event.ID, 10), bytes.NewBuffer(bodyBytes))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		var updated model.PushEvent
+		dbConn.First(&updated)
+		assert.Equal(t, []string{"email"}, updated.Channels)
+		assert.Equal(t, []string{"user@test.com"}, updated.Targets)
+		assert.Contains(t, updated.Template, "Custom Login Alert")
+	})
+
+	t.Run("list push histories", func(t *testing.T) {
+		// Populate history record
+		hist := model.PushHistory{
+			EventKey: "admin_login",
+			Channel:  "email",
+			Target:   "user@test.com",
+			Title:    "Custom Login Alert",
+			Content:  "Alert",
+			Level:    "WARNING",
+			Status:   "success",
+		}
+		dbConn.Create(&hist)
+
+		req, _ := http.NewRequest("GET", "/api/v1/admin/push/histories?page=1&page_size=10", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+		var resp response.Any
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataMap, ok := resp.Data.(map[string]any)
+		assert.True(t, ok)
+		assert.Equal(t, float64(1), dataMap["total"])
+	})
+
+	t.Run("test push endpoint", func(t *testing.T) {
+		mPusher := &mockPusher{}
+		pkgpush.Register("test_channel", mPusher)
+
+		testReq := TestPushRequest{
+			Config: pkgpush.Config{
+				Channel: "test_channel",
+				URL:     "http://test-url",
+			},
+			Target: "test_target",
+		}
+		bodyBytes, _ := json.Marshal(testReq)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/push/test", bytes.NewBuffer(bodyBytes))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+	})
+
+	t.Run("list built-in events", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/push/events/builtin", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+		var resp response.Any
+		err := json.Unmarshal(w.Body.Bytes(), &resp)
+		require.NoError(t, err)
+
+		builtins, ok := resp.Data.([]any)
+		assert.True(t, ok)
+		assert.NotEmpty(t, builtins)
+	})
+
+	t.Run("create and delete push event", func(t *testing.T) {
+		// Clean up any existing admin_login event first
+		dbConn.Where("event_key = ?", "admin_login").Delete(&model.PushEvent{})
+
+		// 1. Create event
+		createReq := CreateEventRequest{
+			EventKey: "admin_login",
+			Channels: []string{"email"},
+			Targets:  []string{"admin@test.com"},
+			Enabled:  true,
+		}
+		bodyBytes, _ := json.Marshal(createReq)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/push/events", bytes.NewBuffer(bodyBytes))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		// Verify created in DB
+		var event model.PushEvent
+		err := dbConn.Where("event_key = ?", "admin_login").First(&event).Error
+		require.NoError(t, err)
+		assert.Equal(t, "admin_login", event.EventKey)
+		assert.Equal(t, "管理员登录", event.Name)
+		assert.True(t, event.Enabled)
+
+		// 2. Try creating again (should fail)
+		w2 := httptest.NewRecorder()
+		req2, _ := http.NewRequest("POST", "/api/v1/admin/push/events", bytes.NewBuffer(bodyBytes))
+		req2.Header.Set("Content-Type", "application/json")
+		r.ServeHTTP(w2, req2)
+		assert.Equal(t, http.StatusBadRequest, w2.Code)
+
+		// 3. Delete event
+		w3 := httptest.NewRecorder()
+		req3, _ := http.NewRequest("DELETE", "/api/v1/admin/push/events/"+strconv.FormatUint(event.ID, 10), nil)
+		r.ServeHTTP(w3, req3)
+		assert.Equal(t, http.StatusOK, w3.Code)
+
+		// Verify deleted from DB
+		var count int64
+		dbConn.Model(&model.PushEvent{}).Where("event_key = ?", "admin_login").Count(&count)
+		assert.Equal(t, int64(0), count)
+	})
+}
+
+func TestResolveTarget(t *testing.T) {
+	dbConn, _, cleanup := setupPushTest(t)
+	defer cleanup()
+
+	// 1. 创建测试用户与管理员用户
+	testUser := &model.User{
+		ID:       9999,
+		Username: "target_user",
+		Email:    "target@test.com",
+		IsAdmin:  false,
+	}
+	err := dbConn.Create(testUser).Error
+	require.NoError(t, err)
+
+	adminUser := &model.User{
+		ID:       8888,
+		Username: "admin_user",
+		Email:    "admin@test.com",
+		IsAdmin:  true,
+	}
+	err = dbConn.Create(adminUser).Error
+	require.NoError(t, err)
+
+	flatBody := map[string]any{
+		"user.id":       float64(9999), // JSON 反序列化后一般是 float64
+		"user.username": "target_user",
+		"user.email":    "target@test.com",
+	}
+
+	ctx := context.Background()
+
+	t.Run("dynamic user.id resolved and converted for email channel", func(t *testing.T) {
+		res := resolveTarget(ctx, "user.id", flatBody, "email")
+		assert.Equal(t, "target@test.com", res)
+	})
+
+	t.Run("dynamic user.username resolved and converted for email channel", func(t *testing.T) {
+		res := resolveTarget(ctx, "user.username", flatBody, "email")
+		assert.Equal(t, "target@test.com", res)
+	})
+
+	t.Run("dynamic user.email resolved directly for email channel", func(t *testing.T) {
+		res := resolveTarget(ctx, "user.email", flatBody, "email")
+		assert.Equal(t, "target@test.com", res)
+	})
+
+	t.Run("fixed user id resolved and converted for email channel", func(t *testing.T) {
+		res := resolveTarget(ctx, "9999", flatBody, "email")
+		assert.Equal(t, "target@test.com", res)
+	})
+
+	t.Run("fixed username resolved and converted for email channel", func(t *testing.T) {
+		res := resolveTarget(ctx, "target_user", flatBody, "email")
+		assert.Equal(t, "target@test.com", res)
+	})
+
+	t.Run("fixed email address resolved directly for email channel", func(t *testing.T) {
+		res := resolveTarget(ctx, "fixed@example.com", flatBody, "email")
+		assert.Equal(t, "fixed@example.com", res)
+	})
+
+	t.Run("fixed username resolved for non-email channel", func(t *testing.T) {
+		res := resolveTarget(ctx, "target_user", flatBody, "lark")
+		assert.Equal(t, "target_user", res)
+	})
+
+	t.Run("non-exist user resolved as fallback", func(t *testing.T) {
+		res := resolveTarget(ctx, "non_exist_user", flatBody, "email")
+		assert.Equal(t, "non_exist_user", res)
+	})
+
+	t.Run("system target resolves to admin email for email channel", func(t *testing.T) {
+		res := resolveTarget(ctx, "系统", flatBody, "email")
+		assert.Equal(t, "admin@test.com", res)
+
+		res2 := resolveTarget(ctx, "system", flatBody, "email")
+		assert.Equal(t, "admin@test.com", res2)
+
+		res3 := resolveTarget(ctx, "0", flatBody, "email")
+		assert.Equal(t, "admin@test.com", res3)
+	})
+
+	t.Run("system target resolves to admin username for lark channel", func(t *testing.T) {
+		res := resolveTarget(ctx, "系统", flatBody, "lark")
+		assert.Equal(t, "admin_user", res)
+	})
+}
+
+func TestPushChannelAPI(t *testing.T) {
+	// 1. 模型校验测试
+	t.Run("validate push channel model constraints", func(t *testing.T) {
+		// 校验名称合法性
+		c1 := &model.PushChannel{Name: "invalid-name!", URL: "https://hook.com", Other: "{}"}
+		assert.Error(t, c1.Validate())
+
+		// 校验 URL 安全前缀 HTTPS
+		c2 := &model.PushChannel{Name: "custom_channel", URL: "http://insecure-hook.com", Other: "{}"}
+		assert.Error(t, c2.Validate())
+
+		// 校验 JSON 格式
+		c3 := &model.PushChannel{Name: "custom_channel", URL: "https://hook.com", Other: "{invalid-json}"}
+		assert.Error(t, c3.Validate())
+
+		// 正确配置
+		c4 := &model.PushChannel{Name: "custom_channel", URL: "https://hook.com", Other: "{\"content\":\"$content\"}"}
+		assert.NoError(t, c4.Validate())
+
+		// 飞书渠道校验：非 HTTPS 地址报错
+		c5 := &model.PushChannel{Name: "lark_channel", Type: "lark", URL: "http://open.feishu.cn", Other: ""}
+		assert.Error(t, c5.Validate())
+
+		// 飞书正确配置
+		c6 := &model.PushChannel{Name: "lark_channel", Type: "lark", URL: "https://open.feishu.cn", Other: ""}
+		assert.NoError(t, c6.Validate())
+
+		// Telegram 渠道校验
+		cTelegramErr := &model.PushChannel{Name: "tg_channel", Type: "telegram", URL: "https://api.telegram.org", Token: "", Other: ""}
+		assert.Error(t, cTelegramErr.Validate())
+
+		cTelegramErr2 := &model.PushChannel{Name: "tg_channel", Type: "telegram", URL: "http://api.telegram.org", Token: "123:abc", Other: ""}
+		assert.Error(t, cTelegramErr2.Validate())
+
+		cTelegramOk := &model.PushChannel{Name: "tg_channel", Type: "telegram", URL: "", Token: "123:abc", Other: "-100123"}
+		assert.NoError(t, cTelegramOk.Validate())
+		assert.Equal(t, "https://api.telegram.org", cTelegramOk.URL)
+
+		// 邮件配置校验：允许空配置以复用系统全局设置
+		c7 := &model.PushChannel{Name: "email_channel", Type: "email", URL: "", Token: "", Other: ""}
+		assert.NoError(t, c7.Validate())
+
+		// 邮件正确配置 (非 HTTPS 协议 URL 允许)
+		c8 := &model.PushChannel{Name: "email_channel", Type: "email", URL: "smtp.exmail.qq.com:465", Token: "user@example.com", Other: "authcode"}
+		assert.NoError(t, c8.Validate())
+	})
+
+	// 2. HTTP CRUD & 触发鉴权测试
+	dbConn, _, cleanup := setupPushTest(t)
+	defer cleanup()
+
+	// 构建路由以进行 HTTP 模拟请求
+	r := testhelper.NewTestGinEngine()
+	adminGroup := r.Group("/api/v1/admin")
+	{
+		adminGroup.GET("/push/channels", ListChannels)
+		adminGroup.POST("/push/channels", CreateChannel)
+		adminGroup.PUT("/push/channels/:id", UpdateChannel)
+		adminGroup.DELETE("/push/channels/:id", DeleteChannel)
+		adminGroup.POST("/push/channels/test", TestChannel)
+	}
+
+	var createdID uint64
+
+	t.Run("admin create channel", func(t *testing.T) {
+		reqBody := CreateChannelRequest{
+			Name:        "my_custom_channel",
+			Description: "My custom channel webhook",
+			Type:        "custom",
+			Token:       "my_chan_token",
+			URL:         "https://webhook.site/test",
+			Other:       `{"title": "$title", "body": "$content"}`,
+			Enabled:     true,
+		}
+		bodyBytes, _ := json.Marshal(reqBody)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/push/channels", bytes.NewBuffer(bodyBytes))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+		var resp response.Any
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataMap, ok := resp.Data.(map[string]any)
+		assert.True(t, ok)
+		assert.Equal(t, "my_custom_channel", dataMap["name"])
+		createdID = uint64(dataMap["id"].(float64))
+	})
+
+	t.Run("admin list channels", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/push/channels", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+		var resp response.Any
+		json.Unmarshal(w.Body.Bytes(), &resp)
+		list, ok := resp.Data.([]any)
+		assert.True(t, ok)
+		assert.Len(t, list, 1)
+	})
+
+	t.Run("admin update channel", func(t *testing.T) {
+		updateReq := UpdateChannelRequest{
+			Description: "Updated remark",
+			Type:        "custom",
+			Token:       "new_chan_token",
+			URL:         "https://webhook.site/updated",
+			Other:       `{"text": "$content"}`,
+			Enabled:     true,
+		}
+		bodyBytes, _ := json.Marshal(updateReq)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/push/channels/"+strconv.FormatUint(createdID, 10), bytes.NewBuffer(bodyBytes))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		var updated model.PushChannel
+		dbConn.First(&updated, createdID)
+		assert.Equal(t, "Updated remark", updated.Description)
+		assert.Equal(t, "new_chan_token", updated.Token)
+		assert.Equal(t, `{"text": "$content"}`, updated.Other)
+	})
+
+	t.Run("admin test channel endpoint", func(t *testing.T) {
+		testReq := TestChannelRequest{
+			Name:   "my_custom_channel",
+			Target: "test_target",
+		}
+		bodyBytes, _ := json.Marshal(testReq)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/push/channels/test", bytes.NewBuffer(bodyBytes))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+	})
+
+	t.Run("admin delete channel", func(t *testing.T) {
+		req, _ := http.NewRequest("DELETE", "/api/v1/admin/push/channels/"+strconv.FormatUint(createdID, 10), nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		var count int64
+		dbConn.Model(&model.PushChannel{}).Where("id = ?", createdID).Count(&count)
+		assert.Equal(t, int64(0), count)
+	})
+}

Wavelet/internal/apps/admin/push/routers.go

@@ -0,0 +1,292 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package push defines push notification HTTP routes.
+package push
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"strconv"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/pkg/push"
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+// UpdateEventRequest 更新事件请求参数
+type UpdateEventRequest struct {
+	Channels []string `json:"channels"`
+	Targets  []string `json:"targets"`
+	Template string   `json:"template" binding:"required"`
+	Enabled  bool     `json:"enabled"`
+}
+
+// TestPushRequest 测试推送通道请求参数
+type TestPushRequest struct {
+	Config push.Config `json:"config" binding:"required"`
+	Target string      `json:"target"`
+}
+
+// SyncEvents automatically registers/updates built-in events in the database.
+func SyncEvents(ctx context.Context) error {
+	return syncBuiltInEvents(ctx)
+}
+
+// ListEvents 获取通知事件列表
+// @Summary 获取所有通知事件
+// @Description 返回系统配置的通知事件列表，包括预置和自定义事件，需要管理员权限
+// @Tags admin-push
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]model.PushEvent} "通知事件列表"
+// @Router /api/v1/admin/push/events [get]
+func ListEvents(c *gin.Context) {
+	ctx := c.Request.Context()
+	events, err := listPushEvents(ctx)
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(events))
+}
+
+// CreateEventRequest 创建事件请求参数
+type CreateEventRequest struct {
+	EventKey string   `json:"event_key"`
+	TaskType string   `json:"task_type"` // 关联的异步任务类型
+	Channels []string `json:"channels"`
+	Targets  []string `json:"targets"`
+	Template string   `json:"template"`
+	Enabled  bool     `json:"enabled"`
+}
+
+func findBuiltInEvent(key string) (EventMetadata, bool) {
+	for _, meta := range BuiltInEvents {
+		if meta.Key == key {
+			return meta, true
+		}
+	}
+	return EventMetadata{}, false
+}
+
+// ListBuiltInEvents 获取内置通知事件列表
+// @Summary 获取所有内置通知事件
+// @Description 返回系统定义的所有内置通知事件元数据，供前端下拉框选择，需要管理员权限
+// @Tags admin-push
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]EventMetadata} "内置通知事件列表"
+// @Router /api/v1/admin/push/events/builtin [get]
+func ListBuiltInEvents(c *gin.Context) {
+	c.JSON(http.StatusOK, response.OK(BuiltInEvents))
+}
+
+// CreateEvent 创建通知事件
+// @Summary 创建通知事件
+// @Description 绑定系统内置事件或异步任务、推送渠道、接收目标并创建通知事件配置，需要管理员权限
+// @Tags admin-push
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body CreateEventRequest true "创建参数"
+// @Success 200 {object} response.Any{data=model.PushEvent} "创建成功"
+// @Router /api/v1/admin/push/events [post]
+func CreateEvent(c *gin.Context) {
+	var req CreateEventRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	event, err := createPushEvent(c.Request.Context(), req)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(event))
+}
+
+// DeleteEvent 删除通知事件配置
+// @Summary 删除通知事件配置
+// @Description 删除数据库中的特定通知事件配置，需要管理员权限
+// @Tags admin-push
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "事件 ID"
+// @Success 200 {object} response.Any{data=string} "删除成功"
+// @Router /api/v1/admin/push/events/{id} [delete]
+func DeleteEvent(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, "invalid event id")
+		return
+	}
+
+	if err := deletePushEvent(c.Request.Context(), id); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			response.AbortNotFound(c, "notification event not found")
+			return
+		}
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// UpdateEvent 更新通知事件
+// @Summary 更新通知事件
+// @Description 更新已有通知事件的推送渠道、接收目标和内容模板，需要管理员权限
+// @Tags admin-push
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "事件 ID"
+// @Param request body push.UpdateEventRequest true "更新参数"
+// @Success 200 {object} response.Any{data=string} "修改成功"
+// @Router /api/v1/admin/push/events/{id} [put]
+func UpdateEvent(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, "invalid event id")
+		return
+	}
+
+	var req UpdateEventRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if err := updatePushEvent(c.Request.Context(), id, req); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			response.AbortNotFound(c, "notification event not found")
+			return
+		}
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// ToggleEvent 快捷切换通知事件启用状态
+// @Summary 快捷切换通知事件启用状态
+// @Description 启用或禁用指定的通知事件
+// @Tags admin-push
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "事件 ID"
+// @Success 200 {object} response.Any{data=string} "切换成功"
+// @Router /api/v1/admin/push/events/{id}/toggle [post]
+func ToggleEvent(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, "invalid event id")
+		return
+	}
+
+	enabled, err := togglePushEvent(c.Request.Context(), id)
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			response.AbortNotFound(c, "notification event not found")
+			return
+		}
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(enabled))
+}
+
+// pushHistoriesResponse 推送历史分页响应
+//
+//nolint:unused
+type pushHistoriesResponse struct {
+	Total   int64               `json:"total"`
+	Results []model.PushHistory `json:"results"`
+}
+
+// ListHistories 分页获取通知推送历史
+// @Summary 分页获取通知推送历史
+// @Description 返回分页的通知历史日志数据，需要管理员权限
+// @Tags admin-push
+// @Produce json
+// @Security SessionCookie
+// @Param page query int false "当前页码"
+// @Param page_size query int false "分页大小"
+// @Param event_key query string false "过滤事件名称"
+// @Param status query string false "过滤发送状态"
+// @Success 200 {object} response.Any{data=pushHistoriesResponse} "推送历史列表"
+// @Router /api/v1/admin/push/histories [get]
+func ListHistories(c *gin.Context) {
+	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+	pageSize, _ := strconv.Atoi(c.DefaultQuery("page_size", "20"))
+	if page < 1 {
+		page = 1
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+
+	total, results, err := listPushHistories(c.Request.Context(), repository.PushHistoryListFilter{
+		EventKey: c.Query("event_key"),
+		Status:   c.Query("status"),
+		Page:     page,
+		PageSize: pageSize,
+	})
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(map[string]any{
+		"total":   total,
+		"results": results,
+	}))
+}
+
+// TestPush 测试推送通道发送
+// @Summary 测试推送通道发送
+// @Description 接收临时通知渠道配置并在本地同步调用 Pusher.Send 发送测试消息
+// @Tags admin-push
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body push.TestPushRequest true "测试请求体"
+// @Success 200 {object} response.Any{data=string} "测试成功"
+// @Router /api/v1/admin/push/test [post]
+func TestPush(c *gin.Context) {
+	var req TestPushRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	pusher, err := push.GetPusher(req.Config.Channel)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	if err := pusher.ValidateConfig(req.Config); err != nil {
+		response.AbortBadRequest(c, fmt.Sprintf("validation failed: %v", err))
+		return
+	}
+
+	applySMTPFallbackToPushConfig(c.Request.Context(), &req.Config)
+
+	testBody := map[string]any{
+		keyTitle:   "测试通道推送",
+		keyContent: "当您收到这条消息，说明当前渠道连通性测试通过。",
+		keyLevel:   defaultLevelInfo,
+	}
+	if err := pusher.Send(c.Request.Context(), req.Config, req.Target, testBody, "", nil); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}

Wavelet/internal/apps/admin/push/task_listener.go

@@ -0,0 +1,124 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package push
+
+import (
+	"context"
+	"encoding/json"
+	"strconv"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/task"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+)
+
+// RegisterTaskListeners subscribes push notification handlers to task completion events.
+func RegisterTaskListeners() {
+	task.OnTaskCompleted(handleTaskCompleted)
+}
+
+func handleTaskCompleted(ctx context.Context, execution *model.TaskExecution, result *task.TaskResult, execErr error) {
+	events, err := listActivePushEventsByTaskType(ctx, execution.TaskType)
+	if err != nil {
+		logger.ErrorF(ctx, "push_task_completed_listener: failed to query push events for task type %s: %v", execution.TaskType, err)
+		return
+	}
+	if len(events) == 0 {
+		return
+	}
+
+	body := map[string]any{
+		"task_id":       execution.TaskID,
+		"task_name":     execution.TaskName,
+		"task_type":     execution.TaskType,
+		"task_status":   string(execution.Status),
+		"task_duration": execution.Duration,
+		"time":          time.Now().Format("2006-01-02 15:04:05"),
+	}
+	if execErr != nil {
+		body["task_error"] = execErr.Error()
+	} else {
+		body["task_error"] = ""
+	}
+	if result != nil {
+		body["task_result"] = result.Message
+	} else {
+		body["task_result"] = ""
+	}
+
+	var payloadMap map[string]any
+	if execution.Payload != "" {
+		if err := json.Unmarshal([]byte(execution.Payload), &payloadMap); err == nil {
+			body["payload"] = payloadMap
+			extractUserFromMap(ctx, payloadMap, body)
+		}
+	}
+	if result != nil && result.Detail != "" {
+		var detailMap map[string]any
+		if err := json.Unmarshal([]byte(result.Detail), &detailMap); err == nil {
+			body["detail"] = detailMap
+			extractUserFromMap(ctx, detailMap, body)
+		}
+	}
+
+	for _, event := range events {
+		meta := EventMetadata{
+			Key:         event.EventKey,
+			Name:        event.Name,
+			Description: "异步任务执行完毕触发的自动通知",
+		}
+		DefaultTrigger.Trigger(ctx, meta, body)
+	}
+}
+
+func extractUserFromMap(ctx context.Context, data map[string]any, body map[string]any) {
+	if u, exists := body["user"]; exists && u != nil {
+		return
+	}
+	if user := loadUserFromPayload(ctx, data); user != nil {
+		body["user"] = user
+	}
+}
+
+func extractUserID(data map[string]any) (uint64, bool) {
+	for _, k := range []string{"user_id", "userId", "uid"} {
+		val, ok := data[k]
+		if !ok || val == nil {
+			continue
+		}
+		switch v := val.(type) {
+		case float64:
+			if v >= 0 {
+				return uint64(v), true
+			}
+		case int:
+			if v >= 0 {
+				return uint64(v), true
+			}
+		case int64:
+			if v >= 0 {
+				return uint64(v), true
+			}
+		case uint64:
+			return v, true
+		case string:
+			if id, err := strconv.ParseUint(v, 10, 64); err == nil {
+				return id, true
+			}
+		}
+	}
+	return 0, false
+}
+
+func extractUsername(data map[string]any) string {
+	for _, k := range []string{"username", "user_name"} {
+		if val, ok := data[k]; ok && val != nil {
+			if s, ok := val.(string); ok && s != "" {
+				return s
+			}
+		}
+	}
+	return ""
+}

Wavelet/internal/apps/admin/push/tasks.go

@@ -0,0 +1,121 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package push defines push notification HTTP routes and background tasks.
+package push
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+
+	"github.com/Rain-kl/Wavelet/internal/task"
+	"github.com/Rain-kl/Wavelet/pkg/push"
+)
+
+const (
+	// SendNotificationTask 发送推送通知任务标识
+	SendNotificationTask = "push:send"
+	// TaskTypeSendNotification 推送通知管理类型
+	TaskTypeSendNotification = "send_notification"
+)
+
+// SendNotificationMeta represents the task metadata.
+var SendNotificationMeta = task.TaskMeta{
+	Type:         TaskTypeSendNotification,
+	AsynqTask:    SendNotificationTask,
+	Name:         "推送通知",
+	Description:  "异步执行系统通知的多渠道派发与推送",
+	SupportsTime: false,
+	MaxRetry:     task.DefaultMaxRetry,
+	Queue:        task.QueueDefault,
+	Retryable:    true,
+	Params: []task.TaskParam{
+		{
+			Name:        "event_key",
+			Label:       "事件标识",
+			Type:        "string",
+			Required:    true,
+			Placeholder: "admin_login",
+		},
+		{
+			Name:     "target",
+			Label:    "目标接收者",
+			Type:     "string",
+			Required: false,
+		},
+	},
+}
+
+// PushHandler 通知推送异步任务处理器
+//
+//nolint:revive
+type PushHandler struct{}
+
+// ValidatePayload 校验并标准化推送参数
+func (h *PushHandler) ValidatePayload(payload []byte) ([]byte, error) {
+	if len(payload) == 0 {
+		return nil, errors.New("payload is required")
+	}
+
+	var req SendPayload
+	if err := json.Unmarshal(payload, &req); err != nil {
+		return nil, fmt.Errorf("invalid json format: %w", err)
+	}
+
+	if req.Config.Channel == "" {
+		return nil, errors.New("channel type is required")
+	}
+
+	return json.Marshal(req)
+}
+
+// Execute 异步执行推送操作并记录推送历史审计
+func (h *PushHandler) Execute(ctx context.Context, payload []byte) (*task.TaskResult, error) {
+	var req SendPayload
+	if err := json.Unmarshal(payload, &req); err != nil {
+		task.AppendLog(ctx, "解析推送参数失败: %v", err)
+		return nil, fmt.Errorf("parse payload failed: %w", err)
+	}
+
+	task.AppendLog(ctx, "开始推送通知: 事件 = %s, 渠道 = %s, 接收目标 = %s", req.EventKey, req.Config.Channel, req.Target)
+
+	pusher, err := push.GetPusher(req.Config.Channel)
+	if err != nil {
+		errWrap := fmt.Errorf("get pusher failed: %w", err)
+		task.AppendLog(ctx, "推送失败: %v", errWrap)
+		if task.IsFinalAttempt(ctx) {
+			h.recordHistory(ctx, req, "failed", errWrap.Error())
+		}
+		return nil, errWrap
+	}
+
+	// 执行真正的消息推送，扁平化为原始 json 格式
+	flatBody := req.Body.Flatten()
+	err = pusher.Send(ctx, req.Config, req.Target, flatBody, req.Template, nil)
+
+	title := req.Body.Title
+	content := req.Body.Content
+
+	if err != nil {
+		task.AppendLog(ctx, "消息推送失败 (标题: %s): %v", title, err)
+		if task.IsFinalAttempt(ctx) {
+			h.recordHistory(ctx, req, "failed", err.Error())
+		}
+		return nil, fmt.Errorf("pusher.Send failed: %w", err)
+	}
+
+	task.AppendLog(ctx, "消息推送成功 (标题: %s, 内容摘要: %s)", title, content)
+	h.recordHistory(ctx, req, "success", "")
+
+	return &task.TaskResult{
+		Message: fmt.Sprintf("推送成功: [%s] -> %s", req.Config.Channel, req.Target),
+	}, nil
+}
+
+func (h *PushHandler) recordHistory(ctx context.Context, req SendPayload, status string, errMsg string) {
+	if dbErr := recordPushHistory(ctx, req, status, errMsg); dbErr != nil {
+		task.AppendLog(ctx, "写入推送历史审计记录失败: %v", dbErr)
+	}
+}