feat(push): implement system notification and push framework

pkg/push/custom.go

@@ -0,0 +1,80 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package push
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+)
+
+func init() {
+	Register("custom", &CustomPusher{})
+}
+
+// CustomPusher 自定义 Webhook 发送实现
+type CustomPusher struct{}
+
+// Send 发送自定义 webhook
+func (p *CustomPusher) Send(ctx context.Context, cfg Config, _ string, body map[string]any, template string, _ map[string]any) error {
+	if cfg.URL == "" {
+		return errors.New("custom: URL is required")
+	}
+
+	var reqBody []byte
+
+	if template != "" {
+		// 替换模板中的 {{key}} 占位符
+		rendered := ParseTemplate(template, body)
+		reqBody = []byte(rendered)
+	} else {
+		// 兜底：直接把 body 转为 JSON 字符串发送
+		var err error
+		reqBody, err = json.Marshal(body)
+		if err != nil {
+			return fmt.Errorf("custom: marshal body failed: %w", err)
+		}
+	}
+
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, cfg.URL, bytes.NewReader(reqBody))
+	if err != nil {
+		return fmt.Errorf("custom: create http request failed: %w", err)
+	}
+	httpReq.Header.Set("Content-Type", "application/json")
+
+	// 如果配置了 Key 且格式为 "HeaderName:HeaderValue"，我们可以附加测试用 Header
+	if cfg.Key != "" && strings.Contains(cfg.Key, ":") {
+		parts := strings.SplitN(cfg.Key, ":", 2) //nolint:mnd
+		httpReq.Header.Set(strings.TrimSpace(parts[0]), strings.TrimSpace(parts[1]))
+	}
+
+	client := &http.Client{Timeout: 10 * time.Second}
+	resp, err := client.Do(httpReq)
+	if err != nil {
+		return fmt.Errorf("custom: http request failed: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("custom: http status %s", resp.Status)
+	}
+
+	return nil
+}
+
+// ValidateConfig 校验自定义配置
+func (p *CustomPusher) ValidateConfig(cfg Config) error {
+	if cfg.URL == "" {
+		return errors.New("webhook URL is required")
+	}
+	if !strings.HasPrefix(cfg.URL, "http://") && !strings.HasPrefix(cfg.URL, "https://") {
+		return errors.New("webhook URL must start with http:// or https://")
+	}
+	return nil
+}

pkg/push/email.go

@@ -0,0 +1,109 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package push
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"net/smtp"
+	"strings"
+)
+
+func init() {
+	Register("email", &EmailPusher{})
+}
+
+// EmailPusher 极简 SMTP 邮件推送实现 (静态、解耦)
+type EmailPusher struct{}
+
+// Send 发送邮件
+func (p *EmailPusher) Send(ctx context.Context, cfg Config, target string, body map[string]any, _ string, ext map[string]any) error {
+	if cfg.URL == "" || cfg.Key == "" || cfg.Secret == "" {
+		return errors.New("email: SMTP configuration (url, key, secret) is incomplete")
+	}
+	if target == "" {
+		return errors.New("email: target email address is required")
+	}
+
+	title := defaultTitle
+	if t, ok := body["title"].(string); ok && t != "" {
+		title = t
+	}
+
+	content := ""
+	if c, ok := body["content"].(string); ok && c != "" {
+		content = c
+	} else {
+		// 自动格式化 map
+		var parts []string
+		for k, v := range body {
+			parts = append(parts, fmt.Sprintf("<p><b>%s</b>: %v</p>", k, v))
+		}
+		content = strings.Join(parts, "")
+	}
+
+	// 邮件头和体
+	from := cfg.Key
+	to := target
+
+	// 如果 ext 中指定了 from_name，我们在 From 头部包含它
+	fromName := "System Notification"
+	if ext != nil {
+		if fn, ok := ext["from_name"].(string); ok && fn != "" {
+			fromName = fn
+		}
+	}
+
+	subjectHeader := fmt.Sprintf("Subject: %s\r\n", title)
+	fromHeader := fmt.Sprintf("From: %s <%s>\r\n", fromName, from)
+	toHeader := fmt.Sprintf("To: %s\r\n", to)
+	mimeHeader := "MIME-version: 1.0;\r\nContent-Type: text/html; charset=\"UTF-8\";\r\n\r\n"
+
+	// 拼装完整的邮件报文
+	// 简单的 HTML 正文渲染
+	htmlBody := fmt.Sprintf(`<html><body><h2>%s</h2><div>%s</div></body></html>`, title, content)
+	msg := []byte(fromHeader + toHeader + subjectHeader + mimeHeader + htmlBody + "\r\n")
+
+	// 解析 Host 和 Port
+	host, port, err := net.SplitHostPort(cfg.URL)
+	if err != nil {
+		host = cfg.URL
+		port = "25" // 默认 SMTP 端口
+	}
+
+	auth := smtp.PlainAuth("", cfg.Key, cfg.Secret, host)
+
+	// 异步超时处理
+	errChan := make(chan error, 1)
+	go func() {
+		errChan <- smtp.SendMail(host+":"+port, auth, from, []string{to}, msg)
+	}()
+
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case err := <-errChan:
+		if err != nil {
+			return fmt.Errorf("email: send smtp mail failed: %w", err)
+		}
+	}
+
+	return nil
+}
+
+// ValidateConfig 校验邮件 SMTP 配置
+func (p *EmailPusher) ValidateConfig(cfg Config) error {
+	if cfg.URL == "" {
+		return errors.New("SMTP host:port is required")
+	}
+	if cfg.Key == "" {
+		return errors.New("SMTP username is required")
+	}
+	if cfg.Secret == "" {
+		return errors.New("SMTP password is required")
+	}
+	return nil
+}

pkg/push/lark.go

@@ -0,0 +1,273 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package push
+
+import (
+	"bytes"
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+)
+
+func init() {
+	Register("lark", &LarkPusher{})
+}
+
+const (
+	msgTypeInteractive = "interactive"
+)
+
+// LarkPusher 飞书 Webhook 机器人推送实现
+type LarkPusher struct{}
+
+type larkTextContent struct {
+	Text string `json:"text"`
+}
+
+type larkCardHeaderTitle struct {
+	Content string `json:"content"`
+	Tag     string `json:"tag"`
+}
+
+type larkCardHeader struct {
+	Template string              `json:"template"` // "blue", "orange", "red" etc.
+	Title    larkCardHeaderTitle `json:"title"`
+}
+
+type larkCardElementText struct {
+	Content string `json:"content"`
+	Tag     string `json:"tag"` // "lark_md"
+}
+
+type larkCardElement struct {
+	Tag  string              `json:"tag"` // "div"
+	Text larkCardElementText `json:"text"`
+}
+
+type larkCardContent struct {
+	Header   larkCardHeader    `json:"header"`
+	Elements []larkCardElement `json:"elements"`
+}
+
+type larkMessageRequest struct {
+	MessageType string           `json:"msg_type"`
+	Timestamp   string           `json:"timestamp,omitempty"`
+	Sign        string           `json:"sign,omitempty"`
+	Content     larkTextContent  `json:"content,omitempty"`
+	Card        *larkCardContent `json:"card,omitempty"`
+}
+
+type larkMessageResponse struct {
+	Code int    `json:"code"`
+	Msg  string `json:"msg"`
+}
+
+// Send 执行飞书消息发送
+//
+//nolint:nestif,cyclop
+func (p *LarkPusher) Send(ctx context.Context, cfg Config, _ string, body map[string]any, template string, _ map[string]any) error {
+	if cfg.URL == "" {
+		return errors.New("lark: URL is required")
+	}
+
+	var req larkMessageRequest
+
+	// 1. 如果有自定义模板，我们尝试进行解析
+	if template != "" {
+		rendered := ParseTemplate(template, body)
+
+		// 尝试解析原生的 Lark Card
+		var customCard larkCardContent
+		var rawMap map[string]any
+		_ = json.Unmarshal([]byte(rendered), &rawMap)
+
+		if rawMap != nil && rawMap["elements"] != nil {
+			// 如果包含 elements 字段，说明是用户定制的原生飞书卡片 JSON
+			if err := json.Unmarshal([]byte(rendered), &customCard); err == nil {
+				req.MessageType = msgTypeInteractive
+				req.Card = &customCard
+			} else {
+				req.MessageType = "text"
+				req.Content.Text = rendered
+			}
+		} else {
+			// 说明配置的是系统统一通知消息 of JSON 模板：{"title": "...", "content": "...", "level": "..."}
+			type larkNotificationMessage struct {
+				Title   string `json:"title"`
+				Content string `json:"content"`
+				Level   string `json:"level"`
+			}
+			var msg larkNotificationMessage
+			if err := json.Unmarshal([]byte(rendered), &msg); err == nil && (msg.Title != "" || msg.Content != "") {
+				title := msg.Title
+				if title == "" {
+					title = defaultTitle
+				}
+				content := msg.Content
+				level := strings.ToUpper(msg.Level)
+				if level == "" {
+					level = "INFO"
+				}
+
+				headerColor := "blue"
+				switch level {
+				case "IMPORTANT":
+					headerColor = "orange"
+				case "CRITICAL":
+					headerColor = "red"
+				}
+
+				req.MessageType = msgTypeInteractive
+				req.Card = &larkCardContent{
+					Header: larkCardHeader{
+						Template: headerColor,
+						Title: larkCardHeaderTitle{
+							Content: title,
+							Tag:     "plain_text",
+						},
+					},
+					Elements: []larkCardElement{
+						{
+							Tag: "div",
+							Text: larkCardElementText{
+								Content: content,
+								Tag:     "lark_md",
+							},
+						},
+					},
+				}
+			} else {
+				// 兜底：如果无法按 JSON 解析出结构化字段，当做普通文本发送
+				req.MessageType = "text"
+				req.Content.Text = rendered
+			}
+		}
+	} else {
+		// 2. 如果无模板，默认生成一个精美的飞书互动卡片
+		title := defaultTitle
+		if t, ok := body["title"].(string); ok && t != "" {
+			title = t
+		}
+
+		content := ""
+		if c, ok := body["content"].(string); ok && c != "" {
+			content = c
+		} else {
+			// 兜底：如果连 content 都没有，把 body 里的所有值拼成 markdown
+			var parts []string
+			for k, v := range body {
+				parts = append(parts, fmt.Sprintf("**%s**: %v", k, v))
+			}
+			content = strings.Join(parts, "\n")
+		}
+
+		level := "INFO"
+		if l, ok := body["level"].(string); ok && l != "" {
+			level = strings.ToUpper(l)
+		}
+
+		// 根据级别确定飞书卡片头部的背景色模板
+		headerColor := "blue"
+		switch level {
+		case "IMPORTANT":
+			headerColor = "orange"
+		case "CRITICAL":
+			headerColor = "red"
+		}
+
+		req.MessageType = msgTypeInteractive
+		req.Card = &larkCardContent{
+			Header: larkCardHeader{
+				Template: headerColor,
+				Title: larkCardHeaderTitle{
+					Content: title,
+					Tag:     "plain_text",
+				},
+			},
+			Elements: []larkCardElement{
+				{
+					Tag: "div",
+					Text: larkCardElementText{
+						Content: content,
+						Tag:     "lark_md",
+					},
+				},
+			},
+		}
+	}
+
+	// 3. 计算签名 (如果配置了 secret)
+	if cfg.Secret != "" {
+		timestamp := time.Now().Unix()
+		sign, err := larkSign(cfg.Secret, timestamp)
+		if err != nil {
+			return fmt.Errorf("lark: sign failed: %w", err)
+		}
+		req.Timestamp = strconv.FormatInt(timestamp, 10)
+		req.Sign = sign
+	}
+
+	jsonData, err := json.Marshal(req)
+	if err != nil {
+		return fmt.Errorf("lark: marshal request failed: %w", err)
+	}
+
+	// 4. 发送 POST 请求
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, cfg.URL, bytes.NewBuffer(jsonData))
+	if err != nil {
+		return fmt.Errorf("lark: create http request failed: %w", err)
+	}
+	httpReq.Header.Set("Content-Type", "application/json")
+
+	client := &http.Client{Timeout: 10 * time.Second}
+	resp, err := client.Do(httpReq)
+	if err != nil {
+		return fmt.Errorf("lark: http request failed: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("lark: http status %s", resp.Status)
+	}
+
+	var res larkMessageResponse
+	if err := json.NewDecoder(resp.Body).Decode(&res); err != nil {
+		return fmt.Errorf("lark: decode response failed: %w", err)
+	}
+
+	if res.Code != 0 {
+		return fmt.Errorf("lark: send message failed, code %d: %s", res.Code, res.Msg)
+	}
+
+	return nil
+}
+
+// ValidateConfig 校验飞书配置
+func (p *LarkPusher) ValidateConfig(cfg Config) error {
+	if cfg.URL == "" {
+		return errors.New("webhook URL is required")
+	}
+	if !strings.HasPrefix(cfg.URL, "http://") && !strings.HasPrefix(cfg.URL, "https://") {
+		return errors.New("webhook URL must start with http:// or https://")
+	}
+	return nil
+}
+
+func larkSign(secret string, timestamp int64) (string, error) {
+	stringToSign := fmt.Sprintf("%v", timestamp) + "\n" + secret
+	h := hmac.New(sha256.New, []byte(stringToSign))
+	_, err := h.Write(nil)
+	if err != nil {
+		return "", err
+	}
+	return base64.StdEncoding.EncodeToString(h.Sum(nil)), nil
+}

pkg/push/push.go

@@ -0,0 +1,61 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package push 提供解耦的、无外部业务依赖 of 通知推送底层实现
+package push
+
+import (
+	"context"
+	"fmt"
+	"sync"
+)
+
+const defaultTitle = "系统通知"
+
+// Config 基础通知渠道配置
+type Config struct {
+	Channel string         `json:"channel"`          // 渠道名称，例如 "lark", "custom", "email" 等，唯一标识
+	URL     string         `json:"url,omitempty"`    // Webhook 地址或 SMTP 地址
+	Secret  string         `json:"secret,omitempty"` // 签名密钥或 SMTP 密码/Token
+	Key     string         `json:"key,omitempty"`    // AppID 或 SMTP 用户名
+	Ext     map[string]any `json:"ext,omitempty"`    // 预留拓展 JSON 配置
+}
+
+// Pusher 通知推送渠道接口
+type Pusher interface {
+	// Send 发送通知消息
+	// target: 发送目标 (如邮箱地址或特定用户标识；若为 bot 机器人此项为空)
+	// body: 消息体数据 (含默认字段如 title, content, level)
+	// template: 消息卡片/模板 JSON (可选)
+	// ext: 预留的单次发送拓展数据
+	Send(ctx context.Context, cfg Config, target string, body map[string]any, template string, ext map[string]any) error
+
+	// ValidateConfig 校验渠道配置合法性
+	ValidateConfig(cfg Config) error
+}
+
+var (
+	pushersMu sync.RWMutex
+	pushers   = make(map[string]Pusher)
+)
+
+// Register 注册一个推送渠道实现
+func Register(channelType string, pusher Pusher) {
+	pushersMu.Lock()
+	defer pushersMu.Unlock()
+	if pusher == nil {
+		panic("push: Register pusher is nil")
+	}
+	pushers[channelType] = pusher
+}
+
+// GetPusher 获取指定类型的推送渠道实现
+func GetPusher(channelType string) (Pusher, error) {
+	pushersMu.RLock()
+	defer pushersMu.RUnlock()
+	pusher, ok := pushers[channelType]
+	if !ok {
+		return nil, fmt.Errorf("push: unknown channel type %q", channelType)
+	}
+	return pusher, nil
+}

pkg/push/template.go

@@ -0,0 +1,78 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package push
+
+import (
+	"encoding/json"
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+// ParseTemplate parses template strings by replacing {{placeholder}} structures with values from body.
+// It is a single-pass parser designed for high performance and low allocations.
+func ParseTemplate(template string, body map[string]any) string {
+	var buf strings.Builder
+	buf.Grow(len(template))
+
+	i := 0
+	for {
+		pos := strings.Index(template[i:], "{{")
+		if pos == -1 {
+			buf.WriteString(template[i:])
+			break
+		}
+		// Write prefix
+		buf.WriteString(template[i : i+pos])
+		i += pos + 2 // skip "{{"
+
+		endPos := strings.Index(template[i:], "}}")
+		if endPos == -1 {
+			// Unbalanced "{{"
+			buf.WriteString("{{")
+			buf.WriteString(template[i:])
+			break
+		}
+		key := template[i : i+endPos]
+		if val, ok := body[key]; ok {
+			buf.WriteString(formatValue(val))
+		} else {
+			// Keep the placeholder if key not found
+			buf.WriteString("{{")
+			buf.WriteString(key)
+			buf.WriteString("}}")
+		}
+		i += endPos + 2 // skip "}}"
+	}
+	return buf.String()
+}
+
+func formatValue(v any) string {
+	if v == nil {
+		return ""
+	}
+	switch val := v.(type) {
+	case string:
+		return val
+	case []byte:
+		return string(val)
+	case int:
+		return strconv.Itoa(val)
+	case int32:
+		return strconv.FormatInt(int64(val), 10)
+	case int64:
+		return strconv.FormatInt(val, 10)
+	case float64:
+		return strconv.FormatFloat(val, 'f', -1, 64)
+	case bool:
+		return strconv.FormatBool(val)
+	default:
+		// If it's a map, slice, or struct, marshal it to JSON.
+		b, err := json.Marshal(v)
+		if err == nil {
+			return string(b)
+		}
+		return fmt.Sprintf("%v", v)
+	}
+}

pkg/push/template_test.go

@@ -0,0 +1,75 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package push
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestParseTemplate(t *testing.T) {
+	tests := []struct {
+		name     string
+		template string
+		body     map[string]any
+		expected string
+	}{
+		{
+			name:     "simple replacement",
+			template: "hello {{name}}",
+			body:     map[string]any{"name": "world"},
+			expected: "hello world",
+		},
+		{
+			name:     "multiple replacements",
+			template: "{{greeting}} {{name}}!",
+			body:     map[string]any{"greeting": "Hello", "name": "Alice"},
+			expected: "Hello Alice!",
+		},
+		{
+			name:     "missing key preserves placeholder",
+			template: "hello {{name}} and {{other}}",
+			body:     map[string]any{"name": "world"},
+			expected: "hello world and {{other}}",
+		},
+		{
+			name:     "unbalanced placeholders",
+			template: "hello {{name",
+			body:     map[string]any{"name": "world"},
+			expected: "hello {{name",
+		},
+		{
+			name:     "nil value",
+			template: "val: {{val}}",
+			body:     map[string]any{"val": nil},
+			expected: "val: ",
+		},
+		{
+			name:     "basic types",
+			template: "int: {{i}}, float: {{f}}, bool: {{b}}",
+			body:     map[string]any{"i": 123, "f": 45.67, "b": true},
+			expected: "int: 123, float: 45.67, bool: true",
+		},
+		{
+			name:     "complex type slice",
+			template: "items: {{items}}",
+			body:     map[string]any{"items": []string{"a", "b"}},
+			expected: `items: ["a","b"]`,
+		},
+		{
+			name:     "complex type map",
+			template: "obj: {{obj}}",
+			body:     map[string]any{"obj": map[string]any{"key": "value"}},
+			expected: `obj: {"key":"value"}`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := ParseTemplate(tt.template, tt.body)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}