wavelet init

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

@@ -0,0 +1,245 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package auth_source 提供认证源管理功能
+package auth_source
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/admin"
+	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+// AuthSourceRequest 创建或更新认证源的请求参数
+type AuthSourceRequest struct {
+	Name               string `json:"name"`
+	Type               string `json:"type"`
+	DisplayName        string `json:"display_name"`
+	IsActive           bool   `json:"is_active"`
+	ClientID           string `json:"client_id"`
+	ClientSecret       string `json:"client_secret"`
+	OpenIDDiscoveryURL string `json:"openid_discovery_url"`
+	Scopes             string `json:"scopes"`
+	IconURL            string `json:"icon_url"`
+}
+
+// ToggleAuthSourceRequest 切换认证源启用状态的请求参数
+type ToggleAuthSourceRequest struct {
+	IsActive bool `json:"is_active"`
+}
+
+// ListAuthSources 获取认证源列表
+// @Summary 获取认证源列表
+// @Description 返回所有已配置的 OAuth/OIDC 认证源列表，包括已启用和未启用的，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]model.AuthSource} "认证源列表"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/auth-sources [get]
+func ListAuthSources(c *gin.Context) {
+	sources, err := model.GetAuthSources(c.Request.Context())
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(sources))
+}
+
+// CreateAuthSource 创建认证源
+// @Summary 创建认证源
+// @Description 创建一个新的 OAuth/OIDC 认证源配置，认证源名称必须唯一且符合命名规范，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body auth_source.AuthSourceRequest true "创建认证源参数"
+// @Success 200 {object} response.Any{data=model.AuthSource} "创建成功，返回认证源信息"
+// @Failure 400 {object} response.Any "参数错误或验证失败"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Router /api/v1/admin/auth-sources [post]
+func CreateAuthSource(c *gin.Context) {
+	var req AuthSourceRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	source := model.AuthSource{
+		Name:               req.Name,
+		Type:               req.Type,
+		DisplayName:        req.DisplayName,
+		IsActive:           req.IsActive,
+		ClientID:           req.ClientID,
+		ClientSecret:       req.ClientSecret,
+		OpenIDDiscoveryURL: req.OpenIDDiscoveryURL,
+		Scopes:             req.Scopes,
+		IconURL:            req.IconURL,
+	}
+	if err := model.CreateAuthSource(c.Request.Context(), &source); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	source.Sanitize()
+	c.JSON(http.StatusOK, response.OK(source))
+}
+
+// UpdateAuthSource 更新认证源
+// @Summary 更新认证源
+// @Description 更新指定 ID 的认证源配置。若 client_secret 字段为空，则保留原有密钥不变，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param id path uint64 true "认证源 ID 或名称"
+// @Param request body auth_source.AuthSourceRequest true "更新认证源参数"
+// @Success 200 {object} response.Any{data=model.AuthSource} "更新成功，返回更新后的认证源信息"
+// @Failure 400 {object} response.Any "参数错误或验证失败"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/auth-sources/{id} [put]
+func UpdateAuthSource(c *gin.Context) {
+	id, err := parseSourceID(c)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	var req AuthSourceRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	// 记录更新前的 Discovery URL，以便更新成功后清除旧缓存条目。
+	existing, _ := model.GetAuthSourceByID(c.Request.Context(), id)
+
+	source := model.AuthSource{
+		ID:                 id,
+		Name:               req.Name,
+		Type:               req.Type,
+		DisplayName:        req.DisplayName,
+		IsActive:           req.IsActive,
+		ClientID:           req.ClientID,
+		ClientSecret:       req.ClientSecret,
+		OpenIDDiscoveryURL: req.OpenIDDiscoveryURL,
+		Scopes:             req.Scopes,
+		IconURL:            req.IconURL,
+	}
+	keepSecret := source.ClientSecret == ""
+	if err := model.UpdateAuthSource(c.Request.Context(), &source, keepSecret); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	// Discovery URL 可能已变更，清除旧、新 issuer 的 provider 缓存，
+	// 确保下次登录时重新拉取最新 OIDC 元数据。
+	if existing != nil {
+		oauth.InvalidateOIDCProviderCache(normalizeIssuer(existing.OpenIDDiscoveryURL))
+	}
+	oauth.InvalidateOIDCProviderCache(normalizeIssuer(req.OpenIDDiscoveryURL))
+
+	updated, err := model.GetAuthSourceByID(c.Request.Context(), id)
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	updated.Sanitize()
+	c.JSON(http.StatusOK, response.OK(updated))
+}
+
+// ToggleAuthSource 切换认证源启用状态
+// @Summary 切换认证源启用状态
+// @Description 启用或禁用指定认证源。尝试启用时将验证 Client ID 和 Client Secret 是否已配置，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param id path uint64 true "认证源 ID 或名称"
+// @Param request body auth_source.ToggleAuthSourceRequest true "启用状态"
+// @Success 200 {object} response.Any{data=string} "切换成功"
+// @Failure 400 {object} response.Any "验证失败或认证源不存在"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Router /api/v1/admin/auth-sources/{id}/toggle [put]
+func ToggleAuthSource(c *gin.Context) {
+	id, err := parseSourceID(c)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	var req ToggleAuthSourceRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if err := model.ToggleAuthSource(c.Request.Context(), id, req.IsActive); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// DeleteAuthSource 删除认证源
+// @Summary 删除认证源
+// @Description 删除指定认证源及其关联的所有外部帐号绑定记录，警告：删除后相关用户将无法通过该源登录，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param id path uint64 true "认证源 ID 或名称"
+// @Success 200 {object} response.Any{data=string} "删除成功"
+// @Failure 400 {object} response.Any "ID 无效或删除失败"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Router /api/v1/admin/auth-sources/{id} [delete]
+func DeleteAuthSource(c *gin.Context) {
+	id, err := parseSourceID(c)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	if err := model.DeleteAuthSource(c.Request.Context(), id); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+func parseSourceID(c *gin.Context) (uint64, error) {
+	raw := c.Param("id")
+	if raw == "" {
+		return 0, errors.New(admin.InvalidAuthSourceID)
+	}
+	source, err := model.GetAuthSourceByName(c.Request.Context(), raw)
+	if err == nil {
+		return source.ID, nil
+	}
+	var id uint64
+	if _, scanErr := fmt.Sscanf(raw, "%d", &id); scanErr != nil || id == 0 {
+		return 0, errors.New(admin.InvalidAuthSourceID)
+	}
+	return id, nil
+}
+
+// normalizeIssuer 将 Discovery URL 规范化为 issuer 基础 URL，
+// 与 oauth.buildOAuthConfig 中的规范化逻辑保持一致。
+func normalizeIssuer(discoveryURL string) string {
+	issuer := strings.TrimSuffix(strings.TrimSpace(discoveryURL), "/")
+	issuer = strings.TrimSuffix(issuer, "/.well-known/openid-configuration")
+	issuer = strings.TrimSuffix(issuer, "/.well-known/oauth-authorization-server")
+	return issuer
+}

Wavelet/internal/apps/admin/auth_source/routers_test.go

@@ -0,0 +1,333 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth_source
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+func setupTestRouter(authUser *model.User) *gin.Engine {
+	r := testhelper.NewTestGinEngine()
+	adminGroup := r.Group("/api/v1/admin")
+
+	// Mock authentication middleware
+	adminGroup.Use(func(c *gin.Context) {
+		if authUser != nil {
+			oauth.SetToContext(c, oauth.UserObjKey, authUser)
+		}
+		c.Next()
+	})
+
+	adminGroup.GET("/auth-sources", ListAuthSources)
+	adminGroup.POST("/auth-sources", CreateAuthSource)
+	adminGroup.PUT("/auth-sources/:id", UpdateAuthSource)
+	adminGroup.PUT("/auth-sources/:id/toggle", ToggleAuthSource)
+	adminGroup.DELETE("/auth-sources/:id", DeleteAuthSource)
+	return r
+}
+
+func TestListAuthSources(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	// Seed source
+	source := model.AuthSource{
+		ID:                 1,
+		Name:               "google",
+		Type:               "oidc",
+		DisplayName:        "Google Auth",
+		IsActive:           true,
+		ClientID:           "client_id_123",
+		ClientSecret:       "client_secret_456",
+		OpenIDDiscoveryURL: "https://accounts.google.com",
+	}
+	dbConn.Create(&source)
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	req, _ := http.NewRequest("GET", "/api/v1/admin/auth-sources", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200 OK, got %d", w.Code)
+	}
+
+	var resp response.Any
+	_ = json.Unmarshal(w.Body.Bytes(), &resp)
+
+	dataBytes, _ := json.Marshal(resp.Data)
+	var sources []model.AuthSource
+	_ = json.Unmarshal(dataBytes, &sources)
+
+	if len(sources) != 1 {
+		t.Errorf("expected 1 auth source, got %d", len(sources))
+	}
+	if sources[0].Name != "google" {
+		t.Errorf("expected name 'google', got '%s'", sources[0].Name)
+	}
+	// Verify sanitize removed the secret
+	if sources[0].ClientSecret != "" {
+		t.Error("client secret should be sanitized")
+	}
+	if !sources[0].ClientSecretConfigured {
+		t.Error("client secret configured flag should be true")
+	}
+}
+
+func TestCreateAuthSource(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("create successfully", func(t *testing.T) {
+		reqPayload := AuthSourceRequest{
+			Name:               "github",
+			Type:               "oidc",
+			DisplayName:        "GitHub OIDC",
+			IsActive:           true,
+			ClientID:           "client_id_gh",
+			ClientSecret:       "client_secret_gh",
+			OpenIDDiscoveryURL: "https://github.com",
+		}
+		body, _ := json.Marshal(reqPayload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/auth-sources", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		// Verify database
+		var src model.AuthSource
+		dbConn.Where("name = ?", "github").First(&src)
+		if src.ClientID != "client_id_gh" {
+			t.Errorf("expected client_id_gh, got '%s'", src.ClientID)
+		}
+	})
+
+	t.Run("create invalid validation failure", func(t *testing.T) {
+		reqPayload := AuthSourceRequest{
+			Name:               "invalid name!",
+			Type:               "oidc",
+			DisplayName:        "Invalid",
+			IsActive:           true,
+			ClientID:           "client_id_val",
+			ClientSecret:       "client_secret_val",
+			OpenIDDiscoveryURL: "https://discovery.url",
+		}
+		body, _ := json.Marshal(reqPayload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/auth-sources", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request, got %d", w.Code)
+		}
+	})
+}
+
+func TestUpdateAuthSource(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	// Seed source
+	source := model.AuthSource{
+		ID:                 1,
+		Name:               "microsoft",
+		Type:               "oidc",
+		DisplayName:        "Microsoft",
+		IsActive:           true,
+		ClientID:           "old_client_id",
+		ClientSecret:       "old_secret",
+		OpenIDDiscoveryURL: "https://login.microsoftonline.com",
+	}
+	dbConn.Create(&source)
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("update keep client secret", func(t *testing.T) {
+		reqPayload := AuthSourceRequest{
+			Name:               "microsoft",
+			Type:               "oidc",
+			DisplayName:        "Microsoft Updated",
+			IsActive:           true,
+			ClientID:           "new_client_id",
+			ClientSecret:       "", // empty implies keeping existing secret
+			OpenIDDiscoveryURL: "https://login.microsoftonline.com",
+		}
+		body, _ := json.Marshal(reqPayload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/auth-sources/1", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var src model.AuthSource
+		dbConn.First(&src, 1)
+		if src.DisplayName != "Microsoft Updated" {
+			t.Errorf("expected display name update, got '%s'", src.DisplayName)
+		}
+		if src.ClientSecret != "old_secret" {
+			t.Errorf("expected old secret to be preserved, got '%s'", src.ClientSecret)
+		}
+	})
+
+	t.Run("update new client secret", func(t *testing.T) {
+		reqPayload := AuthSourceRequest{
+			Name:               "microsoft",
+			Type:               "oidc",
+			DisplayName:        "Microsoft Updated Again",
+			IsActive:           true,
+			ClientID:           "new_client_id",
+			ClientSecret:       "brand_new_secret",
+			OpenIDDiscoveryURL: "https://login.microsoftonline.com",
+		}
+		body, _ := json.Marshal(reqPayload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/auth-sources/microsoft", bytes.NewBuffer(body)) // Using Name instead of ID
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var src model.AuthSource
+		dbConn.First(&src, 1)
+		if src.ClientSecret != "brand_new_secret" {
+			t.Errorf("expected secret update, got '%s'", src.ClientSecret)
+		}
+	})
+}
+
+func TestToggleAuthSource(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	source := model.AuthSource{
+		ID:                 1,
+		Name:               "test_source",
+		Type:               "oidc",
+		DisplayName:        "Test Source",
+		IsActive:           false,
+		ClientID:           "",
+		ClientSecret:       "",
+		OpenIDDiscoveryURL: "https://test.discovery.url",
+	}
+	dbConn.Create(&source)
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("cannot activate without credentials", func(t *testing.T) {
+		payload := ToggleAuthSourceRequest{IsActive: true}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/auth-sources/1/toggle", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request when activating without client_id/secret, got %d", w.Code)
+		}
+	})
+
+	t.Run("toggle success after setting credentials", func(t *testing.T) {
+		// Set credentials first
+		dbConn.Model(&model.AuthSource{}).Where("id = ?", 1).Updates(map[string]interface{}{
+			"client_id":     "id",
+			"client_secret": "secret",
+		})
+
+		payload := ToggleAuthSourceRequest{IsActive: true}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/auth-sources/1/toggle", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var src model.AuthSource
+		dbConn.First(&src, 1)
+		if !src.IsActive {
+			t.Error("auth source should be activated")
+		}
+	})
+}
+
+func TestDeleteAuthSource(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	source := model.AuthSource{
+		ID:                 1,
+		Name:               "delete_me",
+		Type:               "oidc",
+		DisplayName:        "Delete Me",
+		IsActive:           true,
+		ClientID:           "id",
+		ClientSecret:       "secret",
+		OpenIDDiscoveryURL: "https://delete.me",
+	}
+	dbConn.Create(&source)
+
+	externalAccount := model.ExternalAccount{
+		ID:           10,
+		AuthSourceID: 1,
+		UserID:       50,
+		ExternalID:   "ext_50",
+	}
+	dbConn.Create(&externalAccount)
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	req, _ := http.NewRequest("DELETE", "/api/v1/admin/auth-sources/1", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200 OK, got %d", w.Code)
+	}
+
+	// Verify AuthSource is deleted
+	var srcCount int64
+	dbConn.Model(&model.AuthSource{}).Where("id = ?", 1).Count(&srcCount)
+	if srcCount != 0 {
+		t.Error("AuthSource should be deleted from the database")
+	}
+
+	// Verify ExternalAccount bindings are also deleted
+	var extCount int64
+	dbConn.Model(&model.ExternalAccount{}).Where("auth_source_id = ?", 1).Count(&extCount)
+	if extCount != 0 {
+		t.Error("related ExternalAccount bindings should be deleted")
+	}
+}

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

@@ -0,0 +1,14 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cache
+
+import (
+	"context"
+
+	"github.com/Rain-kl/Wavelet/internal/repository"
+)
+
+func saveOrUpdateConfig(ctx context.Context, key, value string) error {
+	return repository.SaveOrUpdateSystemConfig(ctx, key, value)
+}

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

@@ -0,0 +1,100 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package cache provides HTTP handlers for managing disk cache.
+package cache
+
+import (
+	"net/http"
+	"strconv"
+
+	"github.com/Rain-kl/Wavelet/internal/diskcache"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+type updateCacheConfigRequest struct {
+	MaxSizeMB  int64 `json:"max_size_mb" binding:"required,min=1"`
+	TTLMinutes int64 `json:"ttl_minutes" binding:"required,min=0"`
+	LRUEnabled bool  `json:"lru_enabled"`
+}
+
+// GetCacheStatus 获取磁盘缓存状态与当前统计数据
+// @Summary 获取缓存状态
+// @Description 获取当前系统磁盘缓存的使用情况（已占用字节、Key 数量等）与策略配置
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=diskcache.Status} "获取成功"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/cache/status [get]
+func GetCacheStatus(c *gin.Context) {
+	status := diskcache.GetGlobalCache().Status()
+	c.JSON(http.StatusOK, response.OK(status))
+}
+
+// UpdateCacheConfig 更新磁盘缓存策略配置
+// @Summary 更新缓存配置
+// @Description 更改磁盘缓存最大容量限制、文件生存时间（TTL）以及是否启用 LRU 淘汰淘汰算法，并进行热更新
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Param request body cache.updateCacheConfigRequest true "缓存配置请求体"
+// @Security SessionCookie
+// @Success 200 {object} response.Any "更新成功"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "服务内部错误"
+// @Router /api/v1/admin/cache/config [post]
+func UpdateCacheConfig(c *gin.Context) {
+	var req updateCacheConfigRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	ctx := c.Request.Context()
+
+	if err := saveOrUpdateConfig(ctx, model.ConfigKeyDiskCacheMaxSizeMB, strconv.FormatInt(req.MaxSizeMB, 10)); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	if err := saveOrUpdateConfig(ctx, model.ConfigKeyDiskCacheTTLMinutes, strconv.FormatInt(req.TTLMinutes, 10)); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	if err := saveOrUpdateConfig(ctx, model.ConfigKeyDiskCacheLRUEnabled, strconv.FormatBool(req.LRUEnabled)); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	diskcache.GetGlobalCache().ReloadConfig(ctx)
+
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// ClearCache 一键清空所有磁盘缓存数据
+// @Summary 清空缓存
+// @Description 清除系统磁盘缓存目录中的所有临时文件，并重置缓存容量和 Key 追踪数据
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any "清理成功"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "服务内部错误"
+// @Router /api/v1/admin/cache/clear [post]
+func ClearCache(c *gin.Context) {
+	if err := diskcache.GetGlobalCache().Clear(); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}

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

@@ -0,0 +1,498 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package db_manage provides router handlers for managing database tables,
+// overview information, and executing custom SQL queries.
+package db_manage
+
+import (
+	"database/sql"
+	"fmt"
+	"math"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/config"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+const (
+	binaryKB        = 0
+	binaryMB        = 1
+	binaryGB        = 2
+	valueThreshold  = 10
+	maxStringLength = 200
+)
+
+// DBOverviewResponse 数据库运行概览响应结构体
+type DBOverviewResponse struct {
+	Type        string `json:"type"`
+	Version     string `json:"version"`
+	Name        string `json:"name"`
+	Size        string `json:"size"`
+	TableCount  int64  `json:"table_count"`
+	Connections int64  `json:"connections"`
+}
+
+// GetTableDataRequest 分页拉取表数据请求结构体
+type GetTableDataRequest struct {
+	Table    string `form:"table" binding:"required"`
+	Page     int    `form:"page,default=1"`
+	PageSize int    `form:"pageSize,default=10"`
+}
+
+// TableDataResponse 动态数据表响应结构体
+type TableDataResponse struct {
+	Columns []string                 `json:"columns"`
+	Total   int64                    `json:"total"`
+	Results []map[string]interface{} `json:"results"`
+}
+
+// ExecuteSQLRequest 执行自定义 SQL 请求结构体
+type ExecuteSQLRequest struct {
+	SQL string `json:"sql" binding:"required"`
+}
+
+// ExecuteSQLResponse 执行自定义 SQL 响应结构体
+type ExecuteSQLResponse struct {
+	Type            string                   `json:"type"` // "select" 或 "exec"
+	Columns         []string                 `json:"columns,omitempty"`
+	Results         []map[string]interface{} `json:"results,omitempty"`
+	AffectedRows    int64                    `json:"affected_rows"`
+	ExecutionTimeMs int64                    `json:"execution_time_ms"`
+}
+
+// formatBytes 格式化字节大小为可读字符串
+func formatBytes(bytes uint64) string {
+	const unit = 1024
+	if bytes < unit {
+		return fmt.Sprintf("%d B", bytes)
+	}
+	div, exp := int64(unit), 0
+	for n := bytes / unit; n >= unit; n /= unit {
+		div *= unit
+		exp++
+	}
+	value := float64(bytes) / float64(div)
+	var suffix string
+	switch exp {
+	case binaryKB:
+		suffix = "KiB"
+	case binaryMB:
+		suffix = "MiB"
+	case binaryGB:
+		suffix = "GiB"
+	default:
+		suffix = "TiB"
+	}
+
+	if value == math.Trunc(value) {
+		if value >= valueThreshold {
+			return fmt.Sprintf("%.0f %s", value, suffix)
+		}
+		return fmt.Sprintf("%.1f %s", value, suffix)
+	}
+	return fmt.Sprintf("%.1f %s", value, suffix)
+}
+
+// getSQLiteOverview 获取 SQLite 数据库概览信息
+func getSQLiteOverview(gormDB *gorm.DB) (DBOverviewResponse, error) {
+	name := config.Config.Database.SQLitePath
+	if name == "" {
+		name = "./data/wavelet.db"
+	}
+
+	var version string
+	var ver string
+	if err := gormDB.Raw("SELECT sqlite_version()").Scan(&ver).Error; err == nil {
+		version = "SQLite " + ver
+	} else {
+		version = "SQLite"
+	}
+
+	var sizeStr string
+	if fi, err := os.Stat(name); err == nil {
+		size := fi.Size()
+		if size < 0 {
+			size = 0
+		}
+		sizeStr = formatBytes(uint64(size))
+	} else {
+		sizeStr = "0 B"
+	}
+
+	var tableCount int64
+	if err := gormDB.Raw("SELECT count(*) FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'").Scan(&tableCount).Error; err != nil {
+		tableCount = 0
+	}
+
+	var connCount int64
+	if sqlDB, err := gormDB.DB(); err == nil {
+		connCount = int64(sqlDB.Stats().OpenConnections)
+	} else {
+		connCount = 1
+	}
+
+	return DBOverviewResponse{
+		Type:        "sqlite",
+		Version:     version,
+		Name:        name,
+		Size:        sizeStr,
+		TableCount:  tableCount,
+		Connections: connCount,
+	}, nil
+}
+
+// getPostgresOverview 获取 PostgreSQL 数据库概览信息
+func getPostgresOverview(gormDB *gorm.DB) (DBOverviewResponse, error) {
+	name := config.Config.Database.Database
+
+	var version string
+	var ver string
+	if err := gormDB.Raw("SELECT version()").Scan(&ver).Error; err == nil {
+		version = ver
+	} else {
+		version = "PostgreSQL"
+	}
+
+	var sizeStr string
+	var sizeBytes sql.NullInt64
+	if err := gormDB.Raw("SELECT pg_database_size(current_database())").Scan(&sizeBytes).Error; err == nil && sizeBytes.Valid {
+		size := sizeBytes.Int64
+		if size < 0 {
+			size = 0
+		}
+		sizeStr = formatBytes(uint64(size))
+	} else {
+		sizeStr = "0 B"
+	}
+
+	var tableCount int64
+	if err := gormDB.Raw("SELECT count(*) FROM information_schema.tables WHERE table_schema = current_schema()").Scan(&tableCount).Error; err != nil {
+		tableCount = 0
+	}
+
+	var connCount int64
+	var pgc sql.NullInt64
+	if err := gormDB.Raw("SELECT count(*) FROM pg_stat_activity WHERE datname = current_database()").Scan(&pgc).Error; err == nil && pgc.Valid {
+		connCount = pgc.Int64
+	} else {
+		if sqlDB, err := gormDB.DB(); err == nil {
+			connCount = int64(sqlDB.Stats().OpenConnections)
+		} else {
+			connCount = 1
+		}
+	}
+
+	return DBOverviewResponse{
+		Type:        "postgres",
+		Version:     version,
+		Name:        name,
+		Size:        sizeStr,
+		TableCount:  tableCount,
+		Connections: connCount,
+	}, nil
+}
+
+// GetDBOverview 获取数据库运行概览
+// @Summary 获取数据库运行概览
+// @Description 获取数据库类型、版本、名称、文件大小、表数量及当前连接数，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=db_manage.DBOverviewResponse} "获取成功"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/db-manage/overview [get]
+func GetDBOverview(c *gin.Context) {
+	gormDB := db.DB(c.Request.Context())
+	if gormDB == nil {
+		response.AbortInternal(c, "数据库未初始化")
+		return
+	}
+
+	var overview DBOverviewResponse
+	var err error
+
+	if !config.Config.Database.Enabled {
+		overview, err = getSQLiteOverview(gormDB)
+	} else {
+		overview, err = getPostgresOverview(gormDB)
+	}
+
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(overview))
+}
+
+// ListDBTables 获取数据库所有表名
+// @Summary 获取数据库所有表名
+// @Description 返回当前数据库的所有用户自定义表名称列表，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]string} "获取成功"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/db-manage/tables [get]
+func ListDBTables(c *gin.Context) {
+	gormDB := db.DB(c.Request.Context())
+	if gormDB == nil {
+		response.AbortInternal(c, "数据库未初始化")
+		return
+	}
+
+	var tables []string
+	var err error
+
+	if !config.Config.Database.Enabled {
+		err = gormDB.Raw("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name").Scan(&tables).Error
+	} else {
+		err = gormDB.Raw("SELECT table_name FROM information_schema.tables WHERE table_schema = current_schema() ORDER BY table_name").Scan(&tables).Error
+	}
+
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(tables))
+}
+
+// GetDBTableData 获取数据表 data
+func GetDBTableData(c *gin.Context) {
+	var req GetTableDataRequest
+	if err := c.ShouldBindQuery(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	gormDB := db.DB(c.Request.Context())
+	if gormDB == nil {
+		response.AbortInternal(c, "数据库未初始化")
+		return
+	}
+
+	// 安全转义表名并拼接
+	quotedTable := `"` + strings.ReplaceAll(req.Table, `"`, `""`) + `"`
+
+	var total int64
+	if err := gormDB.Raw("SELECT count(*) FROM " + quotedTable).Scan(&total).Error; err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	offset := (req.Page - 1) * req.PageSize
+	if offset < 0 {
+		offset = 0
+	}
+	limit := req.PageSize
+	if limit <= 0 {
+		limit = 10
+	}
+
+	rows, err := gormDB.Raw("SELECT * FROM "+quotedTable+" LIMIT ? OFFSET ?", limit, offset).Rows()
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	defer func() {
+		_ = rows.Close()
+	}()
+
+	cols, err := rows.Columns()
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	results, err := scanTableRows(rows, cols)
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(TableDataResponse{
+		Columns: cols,
+		Total:   total,
+		Results: results,
+	}))
+}
+
+// scanTableRows 扫描并提取数据表行数据，做截断处理
+func scanTableRows(rows *sql.Rows, cols []string) ([]map[string]interface{}, error) {
+	results := make([]map[string]interface{}, 0)
+	for rows.Next() {
+		columns := make([]interface{}, len(cols))
+		columnPointers := make([]interface{}, len(cols))
+		for i := range columns {
+			columnPointers[i] = &columns[i]
+		}
+
+		if err := rows.Scan(columnPointers...); err != nil {
+			return nil, err
+		}
+
+		rowMap := make(map[string]interface{})
+		for i, colName := range cols {
+			val := columns[i]
+			if b, ok := val.([]byte); ok {
+				strVal := string(b)
+				runes := []rune(strVal)
+				if len(runes) > maxStringLength {
+					strVal = string(runes[:maxStringLength]) + "..."
+				}
+				rowMap[colName] = strVal
+			} else if str, ok := val.(string); ok {
+				runes := []rune(str)
+				if len(runes) > maxStringLength {
+					str = string(runes[:maxStringLength]) + "..."
+				}
+				rowMap[colName] = str
+			} else {
+				rowMap[colName] = val
+			}
+		}
+		results = append(results, rowMap)
+	}
+	return results, nil
+}
+
+// executeSQLQuery 执行并解析查询类 SQL 语句
+func executeSQLQuery(gormDB *gorm.DB, sqlStr string, startTime time.Time) (ExecuteSQLResponse, error) {
+	rows, err := gormDB.Raw(sqlStr).Rows()
+	if err != nil {
+		return ExecuteSQLResponse{}, err
+	}
+	defer func() {
+		_ = rows.Close()
+	}()
+
+	cols, err := rows.Columns()
+	if err != nil {
+		return ExecuteSQLResponse{}, err
+	}
+
+	results := make([]map[string]interface{}, 0)
+	for rows.Next() {
+		columns := make([]interface{}, len(cols))
+		columnPointers := make([]interface{}, len(cols))
+		for i := range columns {
+			columnPointers[i] = &columns[i]
+		}
+
+		if err := rows.Scan(columnPointers...); err != nil {
+			return ExecuteSQLResponse{}, err
+		}
+
+		rowMap := make(map[string]interface{})
+		for i, colName := range cols {
+			val := columns[i]
+			if b, ok := val.([]byte); ok {
+				rowMap[colName] = string(b)
+			} else {
+				rowMap[colName] = val
+			}
+		}
+		results = append(results, rowMap)
+	}
+
+	executionTime := time.Since(startTime).Milliseconds()
+	return ExecuteSQLResponse{
+		Type:            "select",
+		Columns:         cols,
+		Results:         results,
+		AffectedRows:    int64(len(results)),
+		ExecutionTimeMs: executionTime,
+	}, nil
+}
+
+// executeSQLMutation 执行修改/更新类 SQL 语句
+func executeSQLMutation(gormDB *gorm.DB, sqlStr string, startTime time.Time) (ExecuteSQLResponse, error) {
+	tx := gormDB.Exec(sqlStr)
+	if tx.Error != nil {
+		return ExecuteSQLResponse{}, tx.Error
+	}
+
+	executionTime := time.Since(startTime).Milliseconds()
+	return ExecuteSQLResponse{
+		Type:            "exec",
+		AffectedRows:    tx.RowsAffected,
+		ExecutionTimeMs: executionTime,
+	}, nil
+}
+
+// ExecuteSQL 执行 SQL 查询
+// @Summary 执行 SQL 查询
+// @Description 在当前数据库中执行任意自定义 SQL，如果是查询语句将返回格式化后的列与数据集，否则返回受影响行数，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body db_manage.ExecuteSQLRequest true "SQL 请求参数"
+// @Success 200 {object} response.Any{data=db_manage.ExecuteSQLResponse} "执行完毕"
+// @Failure 400 {object} response.Any "SQL 语句错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/db-manage/query [post]
+func ExecuteSQL(c *gin.Context) {
+	var req ExecuteSQLRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	gormDB := db.DB(c.Request.Context())
+	if gormDB == nil {
+		response.AbortInternal(c, "数据库未初始化")
+		return
+	}
+
+	trimmedSQL := strings.TrimSpace(req.SQL)
+	if trimmedSQL == "" {
+		response.AbortBadRequest(c, "SQL 语句不能为空")
+		return
+	}
+
+	startTime := time.Now()
+
+	// 识别是否是查询语句（SELECT, SHOW, EXPLAIN 等）
+	isQuery := false
+	lowerSQL := strings.ToLower(trimmedSQL)
+	queryKeywords := []string{"select", "show", "explain", "describe", "pragma"}
+	for _, kw := range queryKeywords {
+		if strings.HasPrefix(lowerSQL, kw) {
+			isQuery = true
+			break
+		}
+	}
+
+	var resp ExecuteSQLResponse
+	var err error
+
+	if isQuery {
+		resp, err = executeSQLQuery(gormDB, trimmedSQL, startTime)
+	} else {
+		resp, err = executeSQLMutation(gormDB, trimmedSQL, startTime)
+	}
+
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(resp))
+}

Wavelet/internal/apps/admin/errs.go

@@ -0,0 +1,15 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package admin 提供管理后台功能
+package admin
+
+// 管理后台错误消息常量
+const (
+	AdminRequired          = "未经授权访问"
+	TokenAdminRequired     = "该访问令牌没有管理员权限，无法访问管理端点" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	InvalidAuthSourceID    = "认证源 ID 无效"
+	InvalidCursorParam     = "无效的 cursor 参数"
+	InvalidTaskExecutionID = "无效的任务执行记录 ID"
+)

Wavelet/internal/apps/admin/middlewares.go

@@ -0,0 +1,46 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package admin
+
+import (
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	otel_trace "github.com/Rain-kl/Wavelet/pkg/trace"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	"github.com/gin-gonic/gin"
+)
+
+// LoginAdminRequired 返回管理员权限校验中间件
+func LoginAdminRequired() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// init trace
+		ctx, span := otel_trace.Start(c.Request.Context(), "LoginAdminRequired")
+		defer span.End()
+
+		user, _ := oauth.GetFromContext[*model.User](c, oauth.UserObjKey)
+
+		// 如果是通过 Access Token 鉴权，需要检查令牌本身是否具有管理员权限
+		if tokenAuth, _ := oauth.GetFromContext[bool](c, oauth.TokenAuthKey); tokenAuth {
+			tokenAdmin, _ := oauth.GetFromContext[bool](c, oauth.TokenAdminKey)
+			if !tokenAdmin {
+				response.AbortNotFound(c, TokenAdminRequired)
+				return
+			}
+		}
+
+		if !user.IsAdmin {
+			response.AbortNotFound(c, AdminRequired)
+			return
+		}
+
+		// log
+		logger.InfoF(ctx, "[LoginAdminRequired] %d %s", user.ID, user.Username)
+
+		// next
+		c.Next()
+	}
+}

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)
+	}
+}

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

@@ -0,0 +1,355 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package status 提供系统状态查询接口
+package status
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"math"
+	"net/http"
+	"os"
+	"os/exec"
+	"runtime"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/config"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+// startTime 记录服务启动时间
+var startTime = time.Now()
+
+const (
+	hoursInDay      = 24
+	minutesInHour   = 60
+	secondsInMinute = 60
+	nanosPerSecond  = 1e9
+	binaryKB        = 0
+	binaryMB        = 1
+	binaryGB        = 2
+	valueThreshold  = 10 // 格式化时区分整数显示的阈值
+)
+
+// SystemStatusResponse 系统状态响应结构体
+type SystemStatusResponse struct {
+	Uptime       string `json:"uptime"`
+	NumGoroutine int    `json:"num_goroutine"`
+	Alloc        string `json:"alloc"`
+	TotalAlloc   string `json:"total_alloc"`
+	Sys          string `json:"sys"`
+	Lookups      uint64 `json:"lookups"`
+	Mallocs      uint64 `json:"mallocs"`
+	Frees        uint64 `json:"frees"`
+	HeapAlloc    string `json:"heap_alloc"`
+	HeapSys      string `json:"heap_sys"`
+	HeapIdle     string `json:"heap_idle"`
+	HeapInuse    string `json:"heap_inuse"`
+	HeapReleased string `json:"heap_released"`
+	HeapObjects  uint64 `json:"heap_objects"`
+	StackInuse   string `json:"stack_inuse"`
+	StackSys     string `json:"stack_sys"`
+	MSpanInuse   string `json:"mspan_inuse"`
+	MSpanSys     string `json:"mspan_sys"`
+	MCacheInuse  string `json:"mcache_inuse"`
+	MCacheSys    string `json:"mcache_sys"`
+	BuckHashSys  string `json:"buck_hash_sys"`
+	GCSys        string `json:"gc_sys"`
+	OtherSys     string `json:"other_sys"`
+	NextGC       string `json:"next_gc"`
+	LastGCTime   string `json:"last_gc_time"`
+	PauseTotalNs string `json:"pause_total_ns"`
+	LastPause    string `json:"last_pause"`
+	NumGC        uint32 `json:"num_gc"`
+}
+
+// formatBytes 格式化字节大小
+func formatBytes(bytes uint64) string {
+	const unit = 1024
+	if bytes < unit {
+		return fmt.Sprintf("%d B", bytes)
+	}
+	div, exp := int64(unit), 0
+	for n := bytes / unit; n >= unit; n /= unit {
+		div *= unit
+		exp++
+	}
+	value := float64(bytes) / float64(div)
+	var suffix string
+	switch exp {
+	case binaryKB:
+		suffix = "KiB"
+	case binaryMB:
+		suffix = "MiB"
+	case binaryGB:
+		suffix = "GiB"
+	default:
+		suffix = "TiB"
+	}
+
+	// 格式化规则：
+	// - 如果是整数（如 16, 73, 105, 986, 112）：
+	//   - 如果 >= 10，则格式化为 "%.0f" (e.g. "16 KiB")
+	//   - 如果 < 10，则格式化为 "%.1f" (e.g. "9.0 KiB")
+	// - 如果不是整数（如 5.8, 9.1, 7.6, 4.8）：格式化为 "%.1f"
+	if value == math.Trunc(value) {
+		if value >= valueThreshold {
+			return fmt.Sprintf("%.0f %s", value, suffix)
+		}
+		return fmt.Sprintf("%.1f %s", value, suffix)
+	}
+	return fmt.Sprintf("%.1f %s", value, suffix)
+}
+
+// formatDuration 格式化时间持续时间
+func formatDuration(d time.Duration) string {
+	days := int(d.Hours()) / hoursInDay
+	hours := int(d.Hours()) % hoursInDay
+	minutes := int(d.Minutes()) % minutesInHour
+	seconds := int(d.Seconds()) % secondsInMinute
+
+	var res string
+	if days > 0 {
+		res += fmt.Sprintf("%d天", days)
+	}
+	if hours > 0 {
+		res += fmt.Sprintf("%d小时", hours)
+	}
+	if minutes > 0 {
+		res += fmt.Sprintf("%d分钟", minutes)
+	}
+	if seconds > 0 || res == "" {
+		res += fmt.Sprintf("%d秒钟", seconds)
+	}
+	return res
+}
+
+// GetSystemStatus 获取系统状态信息
+// @Summary 获取系统状态信息
+// @Description 获取后端服务运行状态、Goroutine、内存指标等详细统计数据，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=status.SystemStatusResponse} "获取成功"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Router /api/v1/admin/status [get]
+func GetSystemStatus(c *gin.Context) {
+	var m runtime.MemStats
+	runtime.ReadMemStats(&m)
+
+	uptime := formatDuration(time.Since(startTime))
+	numGoroutine := runtime.NumGoroutine()
+
+	var lastGCTime string
+	switch {
+	case m.LastGC > 0 && m.LastGC <= math.MaxInt64:
+		lastGCTime = formatDuration(time.Since(time.Unix(0, int64(m.LastGC))))
+	case m.LastGC > 0:
+		lastGCTime = "未知"
+	default:
+		lastGCTime = "无"
+	}
+
+	var lastPause string
+	if m.NumGC > 0 {
+		lastPause = fmt.Sprintf("%.3fs", float64(m.PauseNs[(m.NumGC-1)%256])/nanosPerSecond)
+	} else {
+		lastPause = "0.000s"
+	}
+
+	res := SystemStatusResponse{
+		Uptime:       uptime,
+		NumGoroutine: numGoroutine,
+		Alloc:        formatBytes(m.Alloc),
+		TotalAlloc:   formatBytes(m.TotalAlloc),
+		Sys:          formatBytes(m.Sys),
+		Lookups:      m.Lookups,
+		Mallocs:      m.Mallocs,
+		Frees:        m.Frees,
+		HeapAlloc:    formatBytes(m.HeapAlloc),
+		HeapSys:      formatBytes(m.HeapSys),
+		HeapIdle:     formatBytes(m.HeapIdle),
+		HeapInuse:    formatBytes(m.HeapInuse),
+		HeapReleased: formatBytes(m.HeapReleased),
+		HeapObjects:  m.HeapObjects,
+		StackInuse:   formatBytes(m.StackInuse),
+		StackSys:     formatBytes(m.StackSys),
+		MSpanInuse:   formatBytes(m.MSpanInuse),
+		MSpanSys:     formatBytes(m.MSpanSys),
+		MCacheInuse:  formatBytes(m.MCacheInuse),
+		MCacheSys:    formatBytes(m.MCacheSys),
+		BuckHashSys:  formatBytes(m.BuckHashSys),
+		GCSys:        formatBytes(m.GCSys),
+		OtherSys:     formatBytes(m.OtherSys),
+		NextGC:       formatBytes(m.NextGC),
+		LastGCTime:   lastGCTime,
+		PauseTotalNs: fmt.Sprintf("%.1fs", float64(m.PauseTotalNs)/nanosPerSecond),
+		LastPause:    lastPause,
+		NumGC:        m.NumGC,
+	}
+
+	c.JSON(http.StatusOK, response.OK(res))
+}
+
+// DatabaseInfoResponse 数据库信息响应结构体
+type DatabaseInfoResponse struct {
+	Type    string `json:"type"`
+	Name    string `json:"name"`
+	Version string `json:"version"`
+}
+
+// getSQLiteInfo 返回 SQLite 数据库信息
+func getSQLiteInfo(ctx context.Context) DatabaseInfoResponse {
+	info := DatabaseInfoResponse{
+		Type:    "sqlite",
+		Name:    config.Config.Database.SQLitePath,
+		Version: "SQLite",
+	}
+	if info.Name == "" {
+		info.Name = "./data/wavelet.db"
+	}
+	gormDB := db.DB(ctx)
+	if gormDB == nil {
+		return info
+	}
+	var ver string
+	if err := gormDB.Raw("SELECT sqlite_version()").Scan(&ver).Error; err == nil && ver != "" {
+		info.Version = "SQLite " + ver
+	}
+	return info
+}
+
+// getPostgresInfo 返回 PostgreSQL 数据库信息
+func getPostgresInfo(ctx context.Context) DatabaseInfoResponse {
+	info := DatabaseInfoResponse{
+		Type:    "postgres",
+		Name:    config.Config.Database.Database,
+		Version: "PostgreSQL",
+	}
+	gormDB := db.DB(ctx)
+	if gormDB == nil {
+		return info
+	}
+	var ver string
+	if err := gormDB.Raw("SELECT version()").Scan(&ver).Error; err == nil && ver != "" {
+		info.Version = ver
+	}
+	return info
+}
+
+// GetDatabaseInfo 获取当前数据库类型及版本信息
+// @Summary 获取数据库信息
+// @Description 返回当前使用的数据库类型（sqlite/postgres）、名称/路径及版本字符串，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=status.DatabaseInfoResponse} "获取成功"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Router /api/v1/admin/db-info [get]
+func GetDatabaseInfo(c *gin.Context) {
+	var info DatabaseInfoResponse
+	if !config.Config.Database.Enabled {
+		info = getSQLiteInfo(c.Request.Context())
+	} else {
+		info = getPostgresInfo(c.Request.Context())
+	}
+	c.JSON(http.StatusOK, response.OK(info))
+}
+
+// ExportDatabase 导出数据库
+// @Summary 导出数据库
+// @Description SQLite 时直接下载 .db 文件；PostgreSQL 时执行 pg_dump 并流式下载 .sql 文件，需要管理员权限
+// @Tags admin
+// @Produce application/octet-stream
+// @Security SessionCookie
+// @Success 200 {file} binary "数据库文件"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "导出失败"
+// @Router /api/v1/admin/db-export [get]
+func ExportDatabase(c *gin.Context) {
+	if !config.Config.Database.Enabled {
+		exportSQLite(c)
+	} else {
+		exportPostgres(c)
+	}
+}
+
+// exportSQLite 以 HTTP 附件方式下载 SQLite .db 文件
+func exportSQLite(c *gin.Context) {
+	path := config.Config.Database.SQLitePath
+	if path == "" {
+		path = "./data/wavelet.db"
+	}
+
+	f, err := os.Open(path) //nolint:gosec // path is loaded from server startup configuration, not user input
+	if err != nil {
+		response.AbortInternal(c, "无法打开数据库文件: "+err.Error())
+		return
+	}
+	defer func() {
+		if closeErr := f.Close(); closeErr != nil {
+			_ = closeErr
+		}
+	}()
+
+	fi, err := f.Stat()
+	if err != nil {
+		response.AbortInternal(c, "无法读取数据库文件信息: "+err.Error())
+		return
+	}
+
+	c.Header("Content-Disposition", `attachment; filename="wavelet.db"`)
+	c.Header("Content-Type", "application/octet-stream")
+	c.Header("Content-Length", fmt.Sprintf("%d", fi.Size()))
+	c.Status(http.StatusOK)
+	http.ServeContent(c.Writer, c.Request, "wavelet.db", fi.ModTime(), f)
+}
+
+// exportPostgres 执行 pg_dump 并将输出流式传输给客户端
+func exportPostgres(c *gin.Context) {
+	dbCfg := config.Config.Database
+
+	// 检查 pg_dump 是否可用
+	pgDumpPath, err := exec.LookPath("pg_dump")
+	if err != nil {
+		response.AbortInternal(c, "pg_dump 不可用，请确保服务器已安装 PostgreSQL 客户端工具")
+		return
+	}
+
+	args := []string{
+		"--no-password",
+		"-h", dbCfg.Host,
+		"-p", fmt.Sprintf("%d", dbCfg.Port),
+		"-U", dbCfg.Username,
+		dbCfg.Database,
+	}
+
+	cmd := exec.CommandContext(c.Request.Context(), pgDumpPath, args...) //nolint:gosec // pgDumpPath is a looked up command path, args are from database configuration
+	if dbCfg.Password != "" {
+		cmd.Env = append(os.Environ(), "PGPASSWORD="+dbCfg.Password)
+	} else {
+		cmd.Env = os.Environ()
+	}
+
+	fileName := fmt.Sprintf("wavelet_%s.sql", time.Now().Format("20060102_150405"))
+	c.Header("Content-Disposition", `attachment; filename="`+fileName+`"`)
+	c.Header("Content-Type", "application/octet-stream")
+	c.Status(http.StatusOK)
+
+	cmd.Stdout = c.Writer
+	cmd.Stderr = nil // 忽略 stderr 以避免污染输出流
+
+	if err := cmd.Run(); err != nil {
+		// 响应头已发出，无法再写 JSON 错误，记录到服务器日志
+		log.Printf("[db-export] pg_dump failed: %v\n", err)
+	}
+}

Wavelet/internal/apps/admin/system_config/errs.go

@@ -0,0 +1,15 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package system_config 提供系统配置管理功能
+package system_config
+
+// 系统配置错误消息常量
+const (
+	SystemConfigNotFound                 = "系统配置不存在"
+	ConfigKeyRequired                    = "配置键不能为空"
+	ConfigValueRequired                  = "配置值不能为空"
+	ConfigKeyExists                      = "配置键已存在"
+	StorageDriverSwitchRequiresMigration = "存在存量文件，请通过存储迁移任务切换存储引擎"
+)

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

@@ -0,0 +1,128 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package system_config
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/storage"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"gorm.io/gorm"
+)
+
+func createSystemConfig(ctx context.Context, req CreateSystemConfigRequest) error {
+	exists, err := repository.SystemConfigExists(ctx, req.Key)
+	if err != nil {
+		return err
+	}
+	if exists {
+		return errors.New(ConfigKeyExists)
+	}
+
+	config := model.SystemConfig{
+		Key:         req.Key,
+		Value:       req.Value,
+		Type:        req.Type,
+		Visibility:  req.Visibility,
+		Description: req.Description,
+	}
+	if err := repository.CreateSystemConfig(ctx, &config); err != nil {
+		return err
+	}
+
+	invalidateSystemConfigCaches(ctx, req.Key)
+	if err := repository.InvalidateVisibleSystemConfigsCache(ctx); err != nil {
+		logger.WarnF(ctx, "清理公共配置列表缓存失败: %v", err)
+	}
+	return nil
+}
+
+func listSystemConfigs(ctx context.Context, configType string) ([]model.SystemConfig, error) {
+	return repository.ListAdminSystemConfigs(ctx, configType)
+}
+
+func getSystemConfig(ctx context.Context, key string) (model.SystemConfig, error) {
+	return repository.GetAdminSystemConfigByKey(ctx, key)
+}
+
+func updateSystemConfig(ctx context.Context, key string, req UpdateSystemConfigRequest) error {
+	config, err := repository.GetAdminSystemConfigByKey(ctx, key)
+	if err != nil {
+		return err
+	}
+
+	var originalDriver storage.Driver
+	if key == model.ConfigKeyStorageConfig {
+		var currentCfg storage.Config
+		if err := json.Unmarshal([]byte(config.Value), &currentCfg); err == nil {
+			originalDriver = currentCfg.Driver
+		}
+
+		validatedVal, err := validateAndMergeStorageConfig(ctx, req.Value, config.Value)
+		if err != nil {
+			return err
+		}
+		req.Value = validatedVal
+	}
+
+	if err := db.DB(ctx).Transaction(func(tx *gorm.DB) error {
+		updates := map[string]any{
+			"description": req.Description,
+		}
+		if req.Visibility != nil {
+			updates["visibility"] = *req.Visibility
+			config.Visibility = *req.Visibility
+		}
+		if key != model.ConfigKeySMTPPassword || req.Value != maskedConfigValue {
+			updates["value"] = req.Value
+			config.Value = req.Value
+		}
+		if err := tx.Model(&config).Updates(updates).Error; err != nil {
+			return err
+		}
+		resolveStorageMigrationTasksOnDirectDriverUpdate(ctx, tx, key, originalDriver, req.Value)
+		return nil
+	}); err != nil {
+		return err
+	}
+
+	invalidateCachesAfterConfigUpdate(ctx, key)
+	return nil
+}
+
+func resolveStorageMigrationTasksOnDirectDriverUpdate(
+	ctx context.Context,
+	tx *gorm.DB,
+	key string,
+	originalDriver storage.Driver,
+	newValue string,
+) {
+	if key != model.ConfigKeyStorageConfig || originalDriver == "" {
+		return
+	}
+
+	var newCfg storage.Config
+	if err := json.Unmarshal([]byte(newValue), &newCfg); err != nil {
+		return
+	}
+	if newCfg.Driver != originalDriver {
+		return
+	}
+
+	if err := tx.Model(&model.TaskExecution{}).
+		Where("task_type = ? AND status = ?", "storage:migrate", model.TaskExecutionStatusFailed).
+		Updates(map[string]any{
+			"status":      model.TaskExecutionStatusSucceeded,
+			"result":      "存储配置直接更新，故障迁移任务自动标记为已解决",
+			"finished_at": time.Now(),
+		}).Error; err != nil {
+		logger.ErrorF(ctx, "自动更新迁移任务状态失败: %v", err)
+	}
+}

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

@@ -0,0 +1,365 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package system_config
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/cap"
+	"github.com/Rain-kl/Wavelet/internal/apps/upload"
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/storage"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	mail "github.com/Rain-kl/Wavelet/pkg/mail"
+)
+
+const maskedConfigValue = "******"
+
+// CreateSystemConfigRequest 创建系统配置请求
+type CreateSystemConfigRequest struct {
+	Key         string `json:"key" binding:"required,max=64"`
+	Value       string `json:"value" binding:"required"`
+	Type        string `json:"type" binding:"required,oneof=system business"`
+	Visibility  int    `json:"visibility" binding:"oneof=0 1"`
+	Description string `json:"description" binding:"max=255"`
+}
+
+// UpdateSystemConfigRequest 更新系统配置请求
+type UpdateSystemConfigRequest struct {
+	Value       string `json:"value" binding:"required"`
+	Visibility  *int   `json:"visibility" binding:"omitempty,oneof=0 1"`
+	Description string `json:"description" binding:"max=255"`
+}
+
+// CreateSystemConfig 创建系统配置
+// @Summary 创建系统配置
+// @Description 创建一条新的系统配置项，配置键不可重复，同时将新配置同步到 Redis，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body system_config.CreateSystemConfigRequest true "创建请求参数"
+// @Success 200 {object} response.Any{data=string} "创建成功"
+// @Failure 400 {object} response.Any "参数错误或配置键已存在"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/system-configs [post]
+func CreateSystemConfig(c *gin.Context) {
+	var req CreateSystemConfigRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if err := createSystemConfig(c.Request.Context(), req); err != nil {
+		if err.Error() == ConfigKeyExists {
+			response.AbortBadRequest(c, ConfigKeyExists)
+			return
+		}
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// ListSystemConfigs 获取系统配置列表
+// @Summary 获取系统配置列表
+// @Description 返回所有系统配置列表，支持按配置类型（system/business）过滤，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param type query string false "配置类型（system/business）"
+// @Success 200 {object} response.Any{data=[]model.SystemConfig} "系统配置列表"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/system-configs [get]
+func ListSystemConfigs(c *gin.Context) {
+	configs, err := listSystemConfigs(c.Request.Context(), c.Query("type"))
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	for i := range configs {
+		configs[i].Value = maskSensitiveConfig(configs[i].Key, configs[i].Value)
+	}
+
+	c.JSON(http.StatusOK, response.OK(configs))
+}
+
+// GetSystemConfig 获取单个系统配置
+// @Summary 获取单个系统配置
+// @Description 根据配置键获取对应的系统配置详情，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param key path string true "配置键"
+// @Success 200 {object} response.Any{data=model.SystemConfig} "系统配置详情"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 404 {object} response.Any "配置不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/system-configs/{key} [get]
+func GetSystemConfig(c *gin.Context) {
+	config, err := getSystemConfig(c.Request.Context(), c.Param("key"))
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			response.AbortNotFound(c, SystemConfigNotFound)
+		} else {
+			response.AbortInternal(c, err.Error())
+		}
+		return
+	}
+
+	config.Value = maskSensitiveConfig(config.Key, config.Value)
+
+	c.JSON(http.StatusOK, response.OK(config))
+}
+
+// UpdateSystemConfig 更新系统配置
+// @Summary 更新系统配置
+// @Description 根据配置键更新对应的配置内容，同时将更新同步到 Redis，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param key path string true "配置键"
+// @Param request body system_config.UpdateSystemConfigRequest true "更新请求参数"
+// @Success 200 {object} response.Any{data=string} "更新成功"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 404 {object} response.Any "配置不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/system-configs/{key} [put]
+func UpdateSystemConfig(c *gin.Context) {
+	var req UpdateSystemConfigRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	key := c.Param("key")
+	if err := updateSystemConfig(c.Request.Context(), key, req); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			response.AbortNotFound(c, SystemConfigNotFound)
+			return
+		}
+		if isStorageConfigValidationError(err) {
+			response.AbortBadRequest(c, err.Error())
+			return
+		}
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+func invalidateSystemConfigCaches(ctx context.Context, key string) {
+	if err := repository.InvalidateSystemConfigCache(ctx, key); err != nil {
+		logger.WarnF(ctx, "清理系统配置缓存失败: %v", err)
+	}
+	if cap.IsRuntimeConfigKey(key) {
+		cap.InvalidateRuntimeSettings()
+	}
+}
+
+func invalidateCachesAfterConfigUpdate(ctx context.Context, key string) {
+	invalidateSystemConfigCaches(ctx, key)
+
+	if key == model.ConfigKeyStorageConfig {
+		upload.ResetAccessCaches()
+		upload.PublishAccessCacheInvalidation(ctx)
+		storage.ResetCache()
+		storage.PublishCacheInvalidation(ctx)
+	}
+	if key == model.ConfigKeyFileAccessWhitelist {
+		upload.ResetAccessCaches()
+		upload.PublishAccessCacheInvalidation(ctx)
+	}
+
+	if err := repository.InvalidateVisibleSystemConfigsCache(ctx); err != nil {
+		logger.WarnF(ctx, "清理公共配置列表缓存失败: %v", err)
+	}
+}
+
+// TestSMTPRequest 测试 SMTP 配置请求
+type TestSMTPRequest struct {
+	SMTPHost     string `json:"smtp_host" binding:"required,max=255"`
+	SMTPPort     int    `json:"smtp_port" binding:"required"`
+	SMTPUsername string `json:"smtp_username" binding:"required,max=255"`
+	SMTPPassword string `json:"smtp_password" binding:"required,max=255"`
+	To           string `json:"to" binding:"required,email"`
+}
+
+// TestSMTPResponse 测试 SMTP 配置响应
+type TestSMTPResponse struct {
+	Success bool   `json:"success"`
+	Log     string `json:"log"`
+	Error   string `json:"error"`
+}
+
+// TestSMTP 测试 SMTP 邮件发送
+// @Summary 测试 SMTP 邮件发送
+// @Description 使用传入的配置进行 SMTP 邮件发送测试，支持使用 ****** 占位符使用保存的数据库密码
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body system_config.TestSMTPRequest true "测试请求参数"
+// @Success 200 {object} response.Any{data=system_config.TestSMTPResponse} "测试执行完毕"
+// @Failure 400 {object} response.Any "参数错误"
+// @Router /api/v1/admin/system-configs/smtp/test [post]
+func TestSMTP(c *gin.Context) {
+	var req TestSMTPRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	password := req.SMTPPassword
+	if password == maskedConfigValue {
+		if sc, err := repository.GetSystemConfigByKey(c.Request.Context(), model.ConfigKeySMTPPassword); err == nil {
+			password = sc.Value
+		}
+	}
+
+	cfg := mail.Config{
+		Host:     req.SMTPHost,
+		Port:     req.SMTPPort,
+		Username: req.SMTPUsername,
+		Password: password,
+	}
+
+	subject := "Wavelet SMTP Test Mail"
+	body := `<h3>SMTP Mail Connection Test</h3>
+<p>If you received this message, your SMTP configuration is correct and mail sending is working properly.</p>
+<p>Sent from Wavelet.</p>`
+
+	logs, err := mail.SendMailWithLog(c.Request.Context(), cfg, req.To, subject, body)
+	resp := TestSMTPResponse{
+		Success: err == nil,
+		Log:     logs,
+	}
+	if err != nil {
+		resp.Error = err.Error()
+	}
+
+	c.JSON(http.StatusOK, response.OK(resp))
+}
+
+func isStorageConfigValidationError(err error) bool {
+	msg := err.Error()
+	return msg == StorageDriverSwitchRequiresMigration ||
+		strings.HasPrefix(msg, "解析") ||
+		strings.HasPrefix(msg, "验证") ||
+		strings.HasPrefix(msg, "初始化测试") ||
+		strings.HasPrefix(msg, "存储连通性") ||
+		strings.HasPrefix(msg, "序列化") ||
+		strings.HasPrefix(msg, "检查存量文件")
+}
+
+func maskSensitiveConfig(key, value string) string {
+	if value == "" {
+		return value
+	}
+	switch key {
+	case model.ConfigKeySMTPPassword:
+		return maskedConfigValue
+	case model.ConfigKeyStorageConfig:
+		var cfg storage.Config
+		if err := json.Unmarshal([]byte(value), &cfg); err == nil {
+			masked := storage.MaskSecrets(cfg)
+			if val, err := json.Marshal(masked); err == nil {
+				return string(val)
+			}
+		}
+	}
+	return value
+}
+
+// validateAndMergeStorageConfig parses, merges unmasked secrets, validates parameter values,
+// and tests connectivity of the new storage configuration.
+func validateAndMergeStorageConfig(ctx context.Context, value string, currentConfig string) (string, error) {
+	var currentCfg storage.Config
+	if err := json.Unmarshal([]byte(currentConfig), &currentCfg); err != nil {
+		return "", fmt.Errorf("解析当前存储配置失败: %w", err)
+	}
+
+	var newCfg storage.Config
+	if err := json.Unmarshal([]byte(value), &newCfg); err != nil {
+		return "", fmt.Errorf("解析目标存储配置失败: %w", err)
+	}
+
+	// 合并被掩码屏蔽的敏感信息，获取完整的真实配置
+	targetCfg := storage.MergeMaskedSecrets(newCfg, currentCfg)
+	if err := validateMergedStorageConfig(ctx, currentCfg, newCfg, targetCfg); err != nil {
+		return "", err
+	}
+
+	// 序列化为最终保存的真实明文配置，防止保存屏蔽的 ****** 字符
+	unmaskedVal, err := json.Marshal(targetCfg)
+	if err != nil {
+		return "", fmt.Errorf("序列化存储配置失败: %w", err)
+	}
+
+	return string(unmaskedVal), nil
+}
+
+func validateMergedStorageConfig(ctx context.Context, currentCfg, newCfg, targetCfg storage.Config) error {
+	if newCfg.Driver != "" && newCfg.Driver != currentCfg.Driver {
+		var uploadCount int64
+		if err := db.DB(ctx).Model(&model.Upload{}).
+			Where("status != ?", model.UploadStatusDeleted).
+			Count(&uploadCount).Error; err != nil {
+			return fmt.Errorf("检查存量文件失败: %w", err)
+		}
+		if uploadCount > 0 {
+			return errors.New(StorageDriverSwitchRequiresMigration)
+		}
+		if err := validateDriverConfig(targetCfg, newCfg.Driver); err != nil {
+			return fmt.Errorf("验证目标存储配置参数失败: %w", err)
+		}
+		pendingCfg := targetCfg
+		pendingCfg.Driver = newCfg.Driver
+		return testStorageBackend(ctx, pendingCfg, newCfg.Driver)
+	}
+
+	if err := storage.ValidateConfig(targetCfg); err != nil {
+		return fmt.Errorf("验证存储配置参数失败: %w", err)
+	}
+	return testStorageBackend(ctx, targetCfg, targetCfg.Driver)
+}
+
+func validateDriverConfig(cfg storage.Config, driver storage.Driver) error {
+	cfg.Driver = driver
+	return storage.ValidateConfig(cfg)
+}
+
+func testStorageBackend(ctx context.Context, cfg storage.Config, driver storage.Driver) error {
+	testBackend, err := storage.NewBackend(ctx, cfg, driver)
+	if err != nil {
+		return fmt.Errorf("初始化测试存储实例失败: %w", err)
+	}
+	if err := testBackend.Test(ctx); err != nil {
+		return fmt.Errorf("存储连通性测试失败: %w", err)
+	}
+	return nil
+}

Wavelet/internal/apps/admin/system_config/routers_test.go

@@ -0,0 +1,543 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package system_config
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"net/textproto"
+	"strings"
+	"testing"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/storage"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+const expectedDefaultConfigsCount = 30
+
+func setupTestRouter(authUser *model.User) *gin.Engine {
+	r := testhelper.NewTestGinEngine()
+	adminGroup := r.Group("/api/v1/admin")
+
+	// Mock authentication middleware
+	adminGroup.Use(func(c *gin.Context) {
+		if authUser != nil {
+			oauth.SetToContext(c, oauth.UserObjKey, authUser)
+		}
+		c.Next()
+	})
+
+	adminGroup.POST("/system-configs", CreateSystemConfig)
+	adminGroup.GET("/system-configs", ListSystemConfigs)
+
+	systemConfigRouter := adminGroup.Group("/system-configs/:key")
+	{
+		systemConfigRouter.GET("", GetSystemConfig)
+		systemConfigRouter.PUT("", UpdateSystemConfig)
+	}
+
+	return r
+}
+
+func TestCreateSystemConfig(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("create successfully", func(t *testing.T) {
+		payload := CreateSystemConfigRequest{
+			Key:         "custom_key",
+			Value:       "custom_value",
+			Type:        "system",
+			Visibility:  model.ConfigVisibilityVisible,
+			Description: "desc",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/system-configs", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		// Verify database
+		var cfg model.SystemConfig
+		err := dbConn.Where("key = ?", "custom_key").First(&cfg).Error
+		if err != nil {
+			t.Fatalf("failed to find system config in DB: %v", err)
+		}
+
+		// Verify caches are invalidated after create and repopulate on read
+		_, err = db.Redis.HGet(
+			context.Background(),
+			db.PrefixedKey(repository.SystemConfigRedisHashKey),
+			"custom_key",
+		).Result()
+		if err == nil {
+			t.Fatal("expected redis cache miss immediately after create")
+		}
+
+		loaded, err := repository.GetSystemConfigByKey(context.Background(), "custom_key")
+		if err != nil {
+			t.Fatalf("GetSystemConfigByKey(custom_key) error = %v", err)
+		}
+		if loaded.Value != "custom_value" {
+			t.Errorf("GetSystemConfigByKey(custom_key).Value = %q, want %q", loaded.Value, "custom_value")
+		}
+		if loaded.Visibility != model.ConfigVisibilityVisible {
+			t.Errorf("GetSystemConfigByKey(custom_key).Visibility = %d, want %d", loaded.Visibility, model.ConfigVisibilityVisible)
+		}
+	})
+
+	t.Run("create duplicate key error", func(t *testing.T) {
+		// Key "custom_key" already exists from previous test
+		payload := CreateSystemConfigRequest{
+			Key:         "custom_key",
+			Value:       "another_value",
+			Type:        "system",
+			Description: "desc",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/system-configs", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request on duplicate key, got %d", w.Code)
+		}
+	})
+}
+
+func TestListSystemConfigs(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("list all seeded configurations", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/system-configs", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d", w.Code)
+		}
+
+		var resp response.Any
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var configs []model.SystemConfig
+		_ = json.Unmarshal(dataBytes, &configs)
+
+		// Defaults seed configurations
+		if len(configs) != expectedDefaultConfigsCount {
+			t.Errorf("expected %d default configs, got %d", expectedDefaultConfigsCount, len(configs))
+		}
+	})
+
+	t.Run("filter by type business", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/system-configs?type=business", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		var resp response.Any
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var configs []model.SystemConfig
+		_ = json.Unmarshal(dataBytes, &configs)
+
+		if len(configs) != 1 || configs[0].Key != model.ConfigKeyMaxAPIKeysPerUser {
+			t.Errorf("expected 1 business config (max_api_keys_per_user), got %d: %v", len(configs), configs)
+		}
+	})
+}
+
+func TestGetSystemConfig(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("get existing configuration", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/system-configs/"+model.ConfigKeySiteName, nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("expected 200 OK, got %d", w.Code)
+		}
+
+		var resp response.Any
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var cfg model.SystemConfig
+		_ = json.Unmarshal(dataBytes, &cfg)
+
+		if cfg.Value != "Wavelet" {
+			t.Errorf("expected 'Wavelet', got '%s'", cfg.Value)
+		}
+	})
+
+	t.Run("get non-existent config", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/system-configs/non_existent_key", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusNotFound {
+			t.Errorf("expected 404 Not Found, got %d", w.Code)
+		}
+	})
+}
+
+func TestUpdateSystemConfig(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("update successfully", func(t *testing.T) {
+		hidden := model.ConfigVisibilityHidden
+		payload := UpdateSystemConfigRequest{
+			Value:       "Super Site Name",
+			Visibility:  &hidden,
+			Description: "Updated Description",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/system-configs/"+model.ConfigKeySiteName, bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		// Verify database
+		var cfg model.SystemConfig
+		dbConn.Where("key = ?", model.ConfigKeySiteName).First(&cfg)
+		if cfg.Value != "Super Site Name" || cfg.Description != "Updated Description" || cfg.Visibility != model.ConfigVisibilityHidden {
+			t.Errorf("database values not updated: %+v", cfg)
+		}
+
+		// Verify caches are invalidated after update and repopulate on read
+		_, err := db.Redis.HGet(
+			context.Background(),
+			db.PrefixedKey(repository.SystemConfigRedisHashKey),
+			model.ConfigKeySiteName,
+		).Result()
+		if err == nil {
+			t.Fatal("expected redis cache miss immediately after update")
+		}
+
+		loaded, err := repository.GetSystemConfigByKey(context.Background(), model.ConfigKeySiteName)
+		if err != nil {
+			t.Fatalf("GetSystemConfigByKey(site_name) error = %v", err)
+		}
+		if loaded.Value != "Super Site Name" {
+			t.Errorf("GetSystemConfigByKey(site_name).Value = %q, want %q", loaded.Value, "Super Site Name")
+		}
+		if loaded.Visibility != model.ConfigVisibilityHidden {
+			t.Errorf("GetSystemConfigByKey(site_name).Visibility = %d, want %d", loaded.Visibility, model.ConfigVisibilityHidden)
+		}
+	})
+
+	t.Run("update non-existent config", func(t *testing.T) {
+		payload := UpdateSystemConfigRequest{
+			Value: "New Value",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/system-configs/invalid_key", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusNotFound {
+			t.Errorf("expected 404 Not Found, got %d", w.Code)
+		}
+	})
+}
+
+func TestTestSMTP(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	r := setupTestRouter(adminUser)
+	r.POST("/api/v1/admin/system-configs/smtp/test", TestSMTP)
+
+	// Start a mock SMTP server
+	l, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("failed to start mock smtp server: %v", err)
+	}
+	defer func() { _ = l.Close() }()
+
+	port := l.Addr().(*net.TCPAddr).Port
+
+	go func() {
+		conn, err := l.Accept()
+		if err != nil {
+			return
+		}
+		defer func() { _ = conn.Close() }()
+
+		writer := bufio.NewWriter(conn)
+		reader := bufio.NewReader(conn)
+		tp := textproto.NewReader(reader)
+
+		// 220 Ready
+		_, _ = writer.WriteString("220 mock.smtp.com SMTP Ready\r\n")
+		_ = writer.Flush()
+
+		// Read HELO/EHLO
+		_, _ = tp.ReadLine()
+		_, _ = writer.WriteString("250-mock.smtp.com\r\n250 AUTH PLAIN\r\n")
+		_ = writer.Flush()
+
+		// Read AUTH PLAIN
+		_, _ = tp.ReadLine()
+		_, _ = writer.WriteString("235 Authentication successful\r\n")
+		_ = writer.Flush()
+
+		// Read MAIL FROM
+		_, _ = tp.ReadLine()
+		_, _ = writer.WriteString("250 OK\r\n")
+		_ = writer.Flush()
+
+		// Read RCPT TO
+		_, _ = tp.ReadLine()
+		_, _ = writer.WriteString("250 OK\r\n")
+		_ = writer.Flush()
+
+		// Read DATA
+		_, _ = tp.ReadLine()
+		_, _ = writer.WriteString("354 Start mail input\r\n")
+		_ = writer.Flush()
+
+		// Read body lines until dot
+		for {
+			line, err := tp.ReadLine()
+			if err != nil || line == "." {
+				break
+			}
+		}
+		_, _ = writer.WriteString("250 OK\r\n")
+		_ = writer.Flush()
+
+		// Read QUIT
+		_, _ = tp.ReadLine()
+		_, _ = writer.WriteString("221 Bye\r\n")
+		_ = writer.Flush()
+	}()
+
+	payload := TestSMTPRequest{
+		SMTPHost:     "127.0.0.1",
+		SMTPPort:     port,
+		SMTPUsername: "sender@example.com",
+		SMTPPassword: "password",
+		To:           "recipient@example.com",
+	}
+
+	body, _ := json.Marshal(payload)
+	req, _ := http.NewRequest("POST", "/api/v1/admin/system-configs/smtp/test", bytes.NewBuffer(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	var resp response.Any
+	json.Unmarshal(w.Body.Bytes(), &resp)
+
+	dataBytes, _ := json.Marshal(resp.Data)
+	var testResp TestSMTPResponse
+	json.Unmarshal(dataBytes, &testResp)
+
+	if !testResp.Success {
+		t.Errorf("expected test success, got failed: %s. Log: %s", testResp.Error, testResp.Log)
+	}
+}
+
+func TestUpdateStorageConfigValidation(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("update storage config successfully", func(t *testing.T) {
+		tempDir := t.TempDir()
+		cfg := storage.DefaultConfig()
+		cfg.Local.Root = tempDir
+
+		cfgBytes, _ := json.Marshal(cfg)
+		payload := UpdateSystemConfigRequest{
+			Value: string(cfgBytes),
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/system-configs/storage_config", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		// Verify database
+		var dbCfg model.SystemConfig
+		dbConn.Where("key = ?", "storage_config").First(&dbCfg)
+		var savedCfg storage.Config
+		_ = json.Unmarshal([]byte(dbCfg.Value), &savedCfg)
+		if savedCfg.Local.Root != tempDir {
+			t.Errorf("expected local root to be updated to %s, got %s", tempDir, savedCfg.Local.Root)
+		}
+	})
+
+	t.Run("update storage config failed connectivity check", func(t *testing.T) {
+		cfg := storage.DefaultConfig()
+		cfg.Driver = storage.DriverS3
+		cfg.S3.Bucket = "non-existent-bucket"
+		cfg.S3.Endpoint = "http://127.0.0.1:9999" // Will fail connectivity check
+
+		cfgBytes, _ := json.Marshal(cfg)
+		payload := UpdateSystemConfigRequest{
+			Value: string(cfgBytes),
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/system-configs/storage_config", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request, got %d. Body: %s", w.Code, w.Body.String())
+		}
+	})
+
+	t.Run("reject driver switch when uploads exist", func(t *testing.T) {
+		upload := model.Upload{
+			ID:        88001,
+			UserID:    1,
+			FileName:  "keep.txt",
+			FilePath:  "uploads/keep.txt",
+			FileSize:  4,
+			MimeType:  "text/plain",
+			Extension: "txt",
+			Type:      "attachment",
+			Status:    model.UploadStatusUsed,
+		}
+		if err := dbConn.Create(&upload).Error; err != nil {
+			t.Fatalf("seed upload failed: %v", err)
+		}
+
+		tempDir := t.TempDir()
+		cfg := storage.DefaultConfig()
+		cfg.Driver = storage.DriverS3
+		cfg.S3.Endpoint = "http://127.0.0.1:19998"
+		cfg.S3.Region = "us-east-1"
+		cfg.S3.Bucket = "wavelet"
+		cfg.S3.AccessKeyID = "test"
+		cfg.S3.SecretAccessKey = "test"
+		cfg.Local.Root = tempDir
+
+		cfgBytes, _ := json.Marshal(cfg)
+		payload := UpdateSystemConfigRequest{Value: string(cfgBytes)}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/system-configs/storage_config", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Fatalf("expected 400 Bad Request, got %d. Body: %s", w.Code, w.Body.String())
+		}
+		if !strings.Contains(w.Body.String(), StorageDriverSwitchRequiresMigration) {
+			t.Fatalf("expected migration-required error, got: %s", w.Body.String())
+		}
+	})
+
+	t.Run("switch to local while active s3 is unreachable", func(t *testing.T) {
+		if err := dbConn.Where("1 = 1").Delete(&model.Upload{}).Error; err != nil {
+			t.Fatalf("clear uploads failed: %v", err)
+		}
+
+		activeCfg := storage.DefaultConfig()
+		activeCfg.Driver = storage.DriverS3
+		activeCfg.S3.Endpoint = "http://127.0.0.1:9999"
+		activeCfg.S3.Region = "us-east-1"
+		activeCfg.S3.Bucket = "wavelet"
+		activeCfg.S3.AccessKeyID = "test"
+		activeCfg.S3.SecretAccessKey = "test"
+		activeBytes, _ := json.Marshal(activeCfg)
+		seedCfg := model.SystemConfig{
+			Key:   "storage_config",
+			Value: string(activeBytes),
+			Type:  "system",
+		}
+		if err := dbConn.Where("key = ?", "storage_config").
+			Assign(map[string]any{"value": seedCfg.Value, "type": seedCfg.Type}).
+			FirstOrCreate(&seedCfg).Error; err != nil {
+			t.Fatalf("seed active storage config failed: %v", err)
+		}
+
+		tempDir := t.TempDir()
+		stagedCfg := activeCfg
+		stagedCfg.Driver = storage.DriverLocal
+		stagedCfg.Local.Root = tempDir
+
+		cfgBytes, _ := json.Marshal(stagedCfg)
+		payload := UpdateSystemConfigRequest{Value: string(cfgBytes)}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/system-configs/storage_config", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var dbCfg model.SystemConfig
+		if err := dbConn.Where("key = ?", "storage_config").First(&dbCfg).Error; err != nil {
+			t.Fatalf("load saved storage config failed: %v", err)
+		}
+		var savedCfg storage.Config
+		if err := json.Unmarshal([]byte(dbCfg.Value), &savedCfg); err != nil {
+			t.Fatalf("parse saved storage config failed: %v", err)
+		}
+		if savedCfg.Driver != storage.DriverLocal {
+			t.Fatalf("active driver = %q, want %q after save", savedCfg.Driver, storage.DriverLocal)
+		}
+		if savedCfg.Local.Root != tempDir {
+			t.Fatalf("staged local root = %q, want %q", savedCfg.Local.Root, tempDir)
+		}
+	})
+}

Wavelet/internal/apps/admin/task/errs.go

@@ -0,0 +1,23 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package task 提供任务管理接口
+package task
+
+// 任务管理相关错误消息
+const (
+	InvalidTaskType       = "无效的任务类型"
+	InvalidTimeRange      = "无效的时间范围"
+	TaskDispatchFailed    = "任务下发失败"
+	UserIDRequired        = "用户ID必填"
+	TaskNotFound          = "任务执行记录不存在"
+	TaskNotRetryable      = "该任务不支持重试"
+	TaskNotFailed         = "只有失败的任务才能重试"
+	TaskMaxRetryExceeded  = "已达到最大重试次数"
+	TaskRetryFailed       = "任务重试失败"
+	InvalidCronExpression = "无效的 Cron 表达式"
+	ScheduleNotFound      = "定时任务不存在"
+	ScheduleSaveFailed    = "保存定时任务失败"
+	ScheduleDeleteFailed  = "删除定时任务失败"
+)

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

@@ -0,0 +1,416 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package task
+
+import (
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/admin"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/task"
+	"github.com/Rain-kl/Wavelet/internal/task/scheduler"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"github.com/gin-gonic/gin"
+	"github.com/robfig/cron/v3"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+// ListTaskTypes 获取支持的任务类型列表
+// @Summary 获取支持的任务类型
+// @Description 返回系统支持的所有可调度任务类型列表，包括任务名称、描述、是否支持时间范围等元数据，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]task.TaskMeta} "任务类型列表"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Router /api/v1/admin/tasks/types [get]
+func ListTaskTypes(c *gin.Context) {
+	c.JSON(http.StatusOK, response.OK(task.GetDispatchableTasks()))
+}
+
+// DispatchTaskRequest 下发任务请求
+type DispatchTaskRequest struct {
+	TaskType  string     `json:"task_type" binding:"required"`
+	StartTime *time.Time `json:"start_time"`
+	EndTime   *time.Time `json:"end_time"`
+	UserID    *uint64    `json:"user_id"`
+	Payload   string     `json:"payload"`
+}
+
+// DispatchTask 下发任务
+// @Summary 下发异步任务
+// @Description 手动触发指定类型的异步任务，支持指定时间范围和用户，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body DispatchTaskRequest true "任务请求参数"
+// @Success 200 {object} response.Any{data=string} "任务已入队"
+// @Failure 400 {object} response.Any "任务类型不存在或参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "任务入队失败"
+// @Router /api/v1/admin/tasks/dispatch [post]
+func DispatchTask(c *gin.Context) {
+	var req DispatchTaskRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	meta := task.GetTaskMeta(req.TaskType)
+	if meta == nil {
+		response.AbortBadRequest(c, InvalidTaskType)
+		return
+	}
+
+	var payloadBytes []byte
+	if strings.TrimSpace(req.Payload) != "" {
+		payloadBytes = []byte(req.Payload)
+	}
+
+	validated, err := task.ValidateAndNormalizePayload(meta.AsynqTask, payloadBytes)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	taskID, err := task.DispatchTask(c.Request.Context(), req.TaskType, validated, "manual")
+	if err != nil {
+		response.AbortInternal(c, fmt.Sprintf("%s: %v", TaskDispatchFailed, err))
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(taskID))
+}
+
+// ListTaskExecutions 查询任务执行记录列表
+// @Summary 查询任务执行记录
+// @Description 分页查询任务执行记录，支持按状态和任务类型筛选，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param status query string false "状态筛选 (pending/running/succeeded/failed)"
+// @Param task_type query string false "任务类型筛选"
+// @Param page query int false "页码" default(1)
+// @Param page_size query int false "每页条数" default(20)
+// @Success 200 {object} response.Any{data=object} "任务执行记录列表"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Router /api/v1/admin/tasks/executions [get]
+func ListTaskExecutions(c *gin.Context) {
+	var req model.ListTaskExecutionsRequest
+	if err := c.ShouldBindQuery(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if req.TaskType != "" {
+		if meta := task.GetTaskMeta(req.TaskType); meta != nil {
+			req.TaskType = meta.AsynqTask
+		}
+	}
+
+	executions, total, err := model.ListTaskExecutions(c.Request.Context(), req)
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(gin.H{
+		"items":     executions,
+		"total":     total,
+		"page":      req.Page,
+		"page_size": req.PageSize,
+	}))
+}
+
+// GetTaskExecution 查询单条任务执行详情
+// @Summary 查询任务执行详情
+// @Description 根据 ID 查询任务执行记录详情，包含完整执行日志，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "任务执行记录 ID"
+// @Success 200 {object} response.Any{data=model.TaskExecution} "任务执行详情"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 404 {object} response.Any "记录不存在"
+// @Router /api/v1/admin/tasks/executions/{id} [get]
+func GetTaskExecution(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, admin.InvalidTaskExecutionID)
+		return
+	}
+
+	execution, err := model.GetTaskExecutionByID(c.Request.Context(), id)
+	if err != nil {
+		response.AbortNotFound(c, TaskNotFound)
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(execution))
+}
+
+// RetryTask 重试失败的任务
+// @Summary 重试失败任务
+// @Description 重新下发一条失败的任务，创建新的执行记录，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "任务执行记录 ID"
+// @Success 200 {object} response.Any{data=string} "新任务的 TaskID"
+// @Failure 400 {object} response.Any "任务不支持重试或参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 404 {object} response.Any "记录不存在"
+// @Failure 500 {object} response.Any "重试失败"
+// @Router /api/v1/admin/tasks/executions/{id}/retry [post]
+func RetryTask(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, admin.InvalidTaskExecutionID)
+		return
+	}
+
+	newTaskID, err := task.RetryTask(c.Request.Context(), id)
+	if err != nil {
+		errMsg := err.Error()
+		switch {
+		case strings.Contains(errMsg, "不存在"):
+			response.AbortNotFound(c, errMsg)
+		case strings.Contains(errMsg, "只有失败的任务") || strings.Contains(errMsg, "不支持重试") || strings.Contains(errMsg, "已达到最大重试"):
+			response.AbortBadRequest(c, errMsg)
+		default:
+			response.AbortInternal(c, fmt.Sprintf("%s: %v", TaskRetryFailed, err))
+		}
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(newTaskID))
+}
+
+// ListSchedules 获取定时任务列表
+// @Summary 获取定时任务列表
+// @Description 返回系统所有的定时任务配置列表，包括名称、关联的异步任务类型、Cron 表达式和启用状态，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]model.Schedule} "定时任务列表"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Router /api/v1/admin/tasks/schedules [get]
+func ListSchedules(c *gin.Context) {
+	schedules, err := model.ListSchedules(c.Request.Context())
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(schedules))
+}
+
+// CreateScheduleRequest 创建定时任务请求
+type CreateScheduleRequest struct {
+	Name     string `json:"name" binding:"required"`
+	TaskType string `json:"task_type" binding:"required"`
+	Cron     string `json:"cron" binding:"required"`
+	Payload  string `json:"payload"`
+	IsActive *bool  `json:"is_active" binding:"required"`
+}
+
+// CreateSchedule 创建定时任务
+// @Summary 创建定时任务
+// @Description 新增一个动态定时任务配置，关联已有的异步任务，配置 Cron 表达式和执行参数，并触发调度器热加载，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body CreateScheduleRequest true "创建定时任务请求参数"
+// @Success 200 {object} response.Any{data=model.Schedule} "创建成功的定时任务信息"
+// @Failure 400 {object} response.Any "Cron 表达式无效、异步任务类型不存在或参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "保存定时任务失败"
+// @Router /api/v1/admin/tasks/schedules [post]
+func CreateSchedule(c *gin.Context) {
+	var req CreateScheduleRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	// 校验 Cron 表达式
+	if _, err := cron.ParseStandard(req.Cron); err != nil {
+		response.AbortBadRequest(c, InvalidCronExpression)
+		return
+	}
+
+	// 校验关联的异步任务类型
+	meta := task.GetTaskMeta(req.TaskType)
+	if meta == nil {
+		response.AbortBadRequest(c, InvalidTaskType)
+		return
+	}
+
+	// 校验并规范化 Payload
+	var payloadBytes []byte
+	if strings.TrimSpace(req.Payload) != "" {
+		payloadBytes = []byte(req.Payload)
+	}
+	validated, err := task.ValidateAndNormalizePayload(meta.AsynqTask, payloadBytes)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	schedule := &model.Schedule{
+		Name:     req.Name,
+		TaskType: req.TaskType,
+		Cron:     req.Cron,
+		Payload:  string(validated),
+		IsActive: *req.IsActive,
+	}
+
+	if err := model.CreateSchedule(c.Request.Context(), schedule); err != nil {
+		response.AbortInternal(c, fmt.Sprintf("%s: %v", ScheduleSaveFailed, err))
+		return
+	}
+
+	// 触发调度服务重载
+	if err := scheduler.ReloadScheduler(); err != nil {
+		logger.ErrorF(c.Request.Context(), "[TaskAdmin] 重载调度器失败: %v", err)
+	}
+
+	c.JSON(http.StatusOK, response.OK(schedule))
+}
+
+// UpdateScheduleRequest 修改定时任务请求
+type UpdateScheduleRequest struct {
+	Name     string `json:"name" binding:"required"`
+	TaskType string `json:"task_type" binding:"required"`
+	Cron     string `json:"cron" binding:"required"`
+	Payload  string `json:"payload"`
+	IsActive *bool  `json:"is_active" binding:"required"`
+}
+
+// UpdateSchedule 修改定时任务
+// @Summary 修改定时任务
+// @Description 修改一个定时任务的配置（名称、Cron 表达式、异步任务参数和是否启用等），并触发调度器热加载，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "定时任务 ID"
+// @Param request body UpdateScheduleRequest true "修改定时任务请求参数"
+// @Success 200 {object} response.Any{data=model.Schedule} "修改后的定时任务信息"
+// @Failure 400 {object} response.Any "Cron 表达式无效、参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 404 {object} response.Any "定时任务不存在"
+// @Failure 500 {object} response.Any "修改定时任务失败"
+// @Router /api/v1/admin/tasks/schedules/{id} [put]
+func UpdateSchedule(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, "无效的定时任务ID")
+		return
+	}
+
+	var req UpdateScheduleRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	// 检查定时任务是否存在
+	schedule, err := model.GetScheduleByID(c.Request.Context(), id)
+	if err != nil {
+		response.AbortNotFound(c, ScheduleNotFound)
+		return
+	}
+
+	// 校验 Cron 表达式
+	if _, err := cron.ParseStandard(req.Cron); err != nil {
+		response.AbortBadRequest(c, InvalidCronExpression)
+		return
+	}
+
+	// 校验关联的异步任务类型
+	meta := task.GetTaskMeta(req.TaskType)
+	if meta == nil {
+		response.AbortBadRequest(c, InvalidTaskType)
+		return
+	}
+
+	// 校验并规范化 Payload
+	var payloadBytes []byte
+	if strings.TrimSpace(req.Payload) != "" {
+		payloadBytes = []byte(req.Payload)
+	}
+	validated, err := task.ValidateAndNormalizePayload(meta.AsynqTask, payloadBytes)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	schedule.Name = req.Name
+	schedule.TaskType = req.TaskType
+	schedule.Cron = req.Cron
+	schedule.Payload = string(validated)
+	schedule.IsActive = *req.IsActive
+
+	if err := model.UpdateSchedule(c.Request.Context(), schedule); err != nil {
+		response.AbortInternal(c, fmt.Sprintf("%s: %v", ScheduleSaveFailed, err))
+		return
+	}
+
+	// 触发调度服务重载
+	if err := scheduler.ReloadScheduler(); err != nil {
+		logger.ErrorF(c.Request.Context(), "[TaskAdmin] 重载调度器失败: %v", err)
+	}
+
+	c.JSON(http.StatusOK, response.OK(schedule))
+}
+
+// DeleteSchedule 删除定时任务
+// @Summary 删除定时任务
+// @Description 删除指定的定时任务配置，并触发调度器热加载，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "定时任务 ID"
+// @Success 200 {object} response.Any{data=string} "删除结果"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "删除定时任务失败"
+// @Router /api/v1/admin/tasks/schedules/{id} [delete]
+func DeleteSchedule(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, "无效的定时任务ID")
+		return
+	}
+
+	if err := model.DeleteSchedule(c.Request.Context(), id); err != nil {
+		response.AbortInternal(c, fmt.Sprintf("%s: %v", ScheduleDeleteFailed, err))
+		return
+	}
+
+	// 触发调度服务重载
+	if err := scheduler.ReloadScheduler(); err != nil {
+		logger.ErrorF(c.Request.Context(), "[TaskAdmin] 重载调度器失败: %v", err)
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}

Wavelet/internal/apps/admin/task/routers_test.go

@@ -0,0 +1,495 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package task
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	uploadtask "github.com/Rain-kl/Wavelet/internal/apps/upload/task"
+	"github.com/Rain-kl/Wavelet/internal/apps/user"
+	"github.com/Rain-kl/Wavelet/internal/bootstrap"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/task"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+	"github.com/gin-gonic/gin"
+	"github.com/hibiken/asynq"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+func setupTaskTestEnvironment(t *testing.T) func() {
+	_, mr, cleanup := testhelper.SetupTestEnvironment(t)
+	bootstrap.RegisterTasks()
+	task.AsynqClient = asynq.NewClient(asynq.RedisClientOpt{
+		Addr: mr.Addr(),
+	})
+	return func() {
+		if task.AsynqClient != nil {
+			_ = task.AsynqClient.Close()
+			task.AsynqClient = nil
+		}
+		cleanup()
+	}
+}
+
+func setupTestRouter(authUser *model.User) *gin.Engine {
+	r := testhelper.NewTestGinEngine()
+	adminGroup := r.Group("/api/v1/admin")
+
+	// Mock authentication middleware
+	adminGroup.Use(func(c *gin.Context) {
+		if authUser != nil {
+			oauth.SetToContext(c, oauth.UserObjKey, authUser)
+		}
+		c.Next()
+	})
+
+	adminGroup.GET("/tasks/types", ListTaskTypes)
+	adminGroup.POST("/tasks/dispatch", DispatchTask)
+	adminGroup.GET("/tasks/executions", ListTaskExecutions)
+	adminGroup.GET("/tasks/executions/:id", GetTaskExecution)
+	adminGroup.POST("/tasks/executions/:id/retry", RetryTask)
+	return r
+}
+
+func TestListTaskTypes(t *testing.T) {
+	cleanup := setupTaskTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	req, _ := http.NewRequest("GET", "/api/v1/admin/tasks/types", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200 OK, got %d", w.Code)
+	}
+
+	var resp response.Any
+	_ = json.Unmarshal(w.Body.Bytes(), &resp)
+
+	dataBytes, _ := json.Marshal(resp.Data)
+	var taskMetas []task.TaskMeta
+	_ = json.Unmarshal(dataBytes, &taskMetas)
+
+	if len(taskMetas) == 0 {
+		t.Error("expected at least one dispatchable task type")
+	}
+
+	foundCleanup := false
+	foundWarmImageCache := false
+	for _, m := range taskMetas {
+		if m.Type == uploadtask.TaskTypeSystemCleanup {
+			foundCleanup = true
+		}
+		if m.Type == uploadtask.TaskTypeWarmImageCache {
+			foundWarmImageCache = true
+		}
+	}
+	if !foundCleanup {
+		t.Errorf("expected task type %s to be listed", uploadtask.TaskTypeSystemCleanup)
+	}
+	if !foundWarmImageCache {
+		t.Errorf("expected task type %s to be listed", uploadtask.TaskTypeWarmImageCache)
+	}
+}
+
+func TestDispatchTask(t *testing.T) {
+	cleanup := setupTaskTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("dispatch valid task successfully", func(t *testing.T) {
+		payload := DispatchTaskRequest{
+			TaskType: uploadtask.TaskTypeSystemCleanup,
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/tasks/dispatch", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code, "Body: %s", w.Body.String())
+
+		var resp response.Any
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+		assert.Empty(t, resp.ErrorMsg)
+		assert.NotNil(t, resp.Data)
+
+		// 返回的 data 应该是 taskID
+		taskID, ok := resp.Data.(string)
+		assert.True(t, ok)
+		assert.NotEmpty(t, taskID)
+	})
+
+	t.Run("dispatch send_email task successfully with valid payload", func(t *testing.T) {
+		payload := DispatchTaskRequest{
+			TaskType: user.TaskTypeSendEmail,
+			Payload:  `{"to":"receiver@example.com","subject":"Test Subject","body":"Test Body"}`,
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/tasks/dispatch", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code, "Body: %s", w.Body.String())
+
+		var resp response.Any
+		json.Unmarshal(w.Body.Bytes(), &resp)
+		assert.Empty(t, resp.ErrorMsg)
+		assert.NotNil(t, resp.Data)
+	})
+
+	t.Run("dispatch send_email task failure with invalid payload json", func(t *testing.T) {
+		payload := DispatchTaskRequest{
+			TaskType: user.TaskTypeSendEmail,
+			Payload:  `{"to":`,
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/tasks/dispatch", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusBadRequest, w.Code)
+		var resp response.Any
+		json.Unmarshal(w.Body.Bytes(), &resp)
+		assert.Contains(t, resp.ErrorMsg, "无效的 JSON 格式")
+	})
+
+	t.Run("dispatch send_email task failure with missing fields", func(t *testing.T) {
+		payload := DispatchTaskRequest{
+			TaskType: user.TaskTypeSendEmail,
+			Payload:  `{"to":"","subject":"Test","body":"Test"}`,
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/tasks/dispatch", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusBadRequest, w.Code)
+		var resp response.Any
+		json.Unmarshal(w.Body.Bytes(), &resp)
+		assert.Contains(t, resp.ErrorMsg, "不能为空")
+	})
+
+	t.Run("dispatch invalid task type failure", func(t *testing.T) {
+		payload := DispatchTaskRequest{
+			TaskType: "invalid_task_type",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/tasks/dispatch", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusBadRequest, w.Code)
+
+		var resp response.Any
+		json.Unmarshal(w.Body.Bytes(), &resp)
+		assert.Equal(t, InvalidTaskType, resp.ErrorMsg)
+	})
+
+	t.Run("dispatch with empty body failure", func(t *testing.T) {
+		req, _ := http.NewRequest("POST", "/api/v1/admin/tasks/dispatch", bytes.NewBuffer([]byte("{}")))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusBadRequest, w.Code)
+	})
+}
+
+func TestListTaskExecutions(t *testing.T) {
+	cleanup := setupTaskTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+	ctx := context.Background()
+
+	// 准备测试数据
+	now := time.Now()
+	records := []*model.TaskExecution{
+		{TaskID: "exec_001", TaskType: "system:cleanup", TaskName: "系统垃圾清理", Status: model.TaskExecutionStatusSucceeded, TriggeredBy: "manual", Duration: 1500, Result: "清理完成", StartedAt: &now, FinishedAt: &now},
+		{TaskID: "exec_002", TaskType: "system:cleanup", TaskName: "系统垃圾清理", Status: model.TaskExecutionStatusFailed, TriggeredBy: "system", ErrorMessage: "连接超时", StartedAt: &now, FinishedAt: &now},
+		{TaskID: "exec_003", TaskType: "system:cleanup", TaskName: "系统垃圾清理", Status: model.TaskExecutionStatusPending, TriggeredBy: "manual", Retryable: true, MaxRetry: 3},
+	}
+	for _, r := range records {
+		err := model.CreateTaskExecution(ctx, r)
+		require.NoError(t, err)
+	}
+
+	t.Run("list all executions", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/tasks/executions", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		var resp response.Any
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var data map[string]interface{}
+		json.Unmarshal(dataBytes, &data)
+
+		assert.Equal(t, float64(3), data["total"])
+	})
+
+	t.Run("filter by status", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/tasks/executions?status=failed", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		var resp response.Any
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var data map[string]interface{}
+		json.Unmarshal(dataBytes, &data)
+
+		assert.Equal(t, float64(1), data["total"])
+	})
+
+	t.Run("filter by task_type (asynq task name)", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/tasks/executions?task_type=system:cleanup", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		var resp response.Any
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var data map[string]interface{}
+		json.Unmarshal(dataBytes, &data)
+
+		assert.Equal(t, float64(3), data["total"])
+	})
+
+	t.Run("filter by task_type (management task type)", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/tasks/executions?task_type=system_cleanup", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		var resp response.Any
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var data map[string]interface{}
+		json.Unmarshal(dataBytes, &data)
+
+		assert.Equal(t, float64(3), data["total"])
+	})
+
+	t.Run("pagination", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/tasks/executions?page=1&page_size=2", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		var resp response.Any
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var data map[string]interface{}
+		json.Unmarshal(dataBytes, &data)
+
+		assert.Equal(t, float64(3), data["total"])
+	})
+}
+
+func TestGetTaskExecution(t *testing.T) {
+	cleanup := setupTaskTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+	ctx := context.Background()
+
+	// 创建测试记录
+	execution := &model.TaskExecution{
+		TaskID:      "detail_001",
+		TaskType:    "system:cleanup",
+		TaskName:    "系统垃圾清理",
+		Status:      model.TaskExecutionStatusSucceeded,
+		Log:         "[10:00:01] 开始扫描\n[10:00:02] 找到 50 个文件\n[10:00:03] 清理完成",
+		Result:      "共清理 50 个文件",
+		Duration:    2000,
+		Retryable:   true,
+		MaxRetry:    3,
+		TriggeredBy: "manual",
+	}
+	err := model.CreateTaskExecution(ctx, execution)
+	require.NoError(t, err)
+
+	t.Run("get existing execution", func(t *testing.T) {
+		url := fmt.Sprintf("/api/v1/admin/tasks/executions/%d", execution.ID)
+		req, _ := http.NewRequest("GET", url, nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		var resp response.Any
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var detail model.TaskExecution
+		json.Unmarshal(dataBytes, &detail)
+
+		assert.Equal(t, "detail_001", detail.TaskID)
+		assert.Equal(t, model.TaskExecutionStatusSucceeded, detail.Status)
+		assert.Contains(t, detail.Log, "开始扫描")
+		assert.Contains(t, detail.Log, "清理完成")
+		assert.Equal(t, int64(2000), detail.Duration)
+	})
+
+	t.Run("get non-existent execution", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/tasks/executions/99999999", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusNotFound, w.Code)
+	})
+
+	t.Run("invalid ID format", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/tasks/executions/invalid", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusBadRequest, w.Code)
+	})
+}
+
+func TestRetryTask(t *testing.T) {
+	cleanup := setupTaskTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+	ctx := context.Background()
+
+	t.Run("retry failed task successfully", func(t *testing.T) {
+		now := time.Now()
+		execution := &model.TaskExecution{
+			TaskID:       "retry_api_001",
+			TaskType:     "system:cleanup",
+			TaskName:     "系统垃圾清理",
+			Status:       model.TaskExecutionStatusFailed,
+			ErrorMessage: "S3 连接超时",
+			Retryable:    true,
+			MaxRetry:     3,
+			RetryCount:   0,
+			TriggeredBy:  "manual",
+			StartedAt:    &now,
+			FinishedAt:   &now,
+		}
+		err := model.CreateTaskExecution(ctx, execution)
+		require.NoError(t, err)
+
+		url := fmt.Sprintf("/api/v1/admin/tasks/executions/%d/retry", execution.ID)
+		req, _ := http.NewRequest("POST", url, nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		var resp response.Any
+		json.Unmarshal(w.Body.Bytes(), &resp)
+		assert.Empty(t, resp.ErrorMsg)
+		assert.NotNil(t, resp.Data)
+
+		// 验证新记录
+		newTaskID, ok := resp.Data.(string)
+		assert.True(t, ok)
+		assert.NotEmpty(t, newTaskID)
+
+		newExecution, err := model.GetTaskExecutionByTaskID(ctx, newTaskID)
+		require.NoError(t, err)
+		assert.Equal(t, 1, newExecution.RetryCount)
+		assert.Equal(t, "retry", newExecution.TriggeredBy)
+	})
+
+	t.Run("retry succeeded task fails", func(t *testing.T) {
+		execution := &model.TaskExecution{
+			TaskID:      "retry_succeeded_001",
+			TaskType:    "system:cleanup",
+			TaskName:    "系统垃圾清理",
+			Status:      model.TaskExecutionStatusSucceeded,
+			Retryable:   true,
+			MaxRetry:    3,
+			TriggeredBy: "manual",
+		}
+		err := model.CreateTaskExecution(ctx, execution)
+		require.NoError(t, err)
+
+		url := fmt.Sprintf("/api/v1/admin/tasks/executions/%d/retry", execution.ID)
+		req, _ := http.NewRequest("POST", url, nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusBadRequest, w.Code)
+	})
+
+	t.Run("retry non-retryable task fails", func(t *testing.T) {
+		execution := &model.TaskExecution{
+			TaskID:      "retry_not_allowed_001",
+			TaskType:    "system:cleanup",
+			TaskName:    "系统垃圾清理",
+			Status:      model.TaskExecutionStatusFailed,
+			Retryable:   false,
+			TriggeredBy: "manual",
+		}
+		err := model.CreateTaskExecution(ctx, execution)
+		require.NoError(t, err)
+
+		url := fmt.Sprintf("/api/v1/admin/tasks/executions/%d/retry", execution.ID)
+		req, _ := http.NewRequest("POST", url, nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusBadRequest, w.Code)
+	})
+
+	t.Run("retry non-existent task", func(t *testing.T) {
+		req, _ := http.NewRequest("POST", "/api/v1/admin/tasks/executions/99999999/retry", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusNotFound, w.Code)
+	})
+
+	t.Run("retry with invalid ID", func(t *testing.T) {
+		req, _ := http.NewRequest("POST", "/api/v1/admin/tasks/executions/invalid/retry", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusBadRequest, w.Code)
+	})
+}

Wavelet/internal/apps/admin/template/errs.go

@@ -0,0 +1,16 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package template 提供模板管理功能
+package template
+
+// 模板管理相关错误消息
+const (
+	TemplateNotFound              = "模板不存在"
+	TemplateKeyRequired           = "模板标识符不能为空"
+	TemplateNameRequired          = "模板名称不能为空"
+	TemplateContentRequired       = "模板内容不能为空"
+	TemplateKeyExists             = "模板标识符已存在"
+	SystemTemplateCannotDelete    = "系统预置模板不可删除"
+	SystemTemplateCannotModifyKey = "系统预置模板不可修改标识符"
+)

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

@@ -0,0 +1,78 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package template
+
+import (
+	"context"
+	"errors"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+)
+
+func createTemplate(ctx context.Context, req CreateTemplateRequest) (model.Template, error) {
+	exists, err := repository.TemplateExistsByKey(ctx, req.Key)
+	if err != nil {
+		return model.Template{}, err
+	}
+	if exists {
+		return model.Template{}, errors.New(TemplateKeyExists)
+	}
+
+	tmpl := model.Template{
+		Key:         req.Key,
+		Name:        req.Name,
+		Type:        req.Type,
+		Subject:     req.Subject,
+		Content:     req.Content,
+		Description: req.Description,
+		IsSystem:    false,
+	}
+	if err := tmpl.Validate(); err != nil {
+		return model.Template{}, err
+	}
+	if err := repository.CreateTemplate(ctx, &tmpl); err != nil {
+		return model.Template{}, err
+	}
+	return tmpl, nil
+}
+
+func listTemplates(ctx context.Context) ([]model.Template, error) {
+	return repository.ListTemplates(ctx)
+}
+
+func getTemplate(ctx context.Context, key string) (model.Template, error) {
+	return repository.GetTemplateByKey(ctx, key)
+}
+
+func updateTemplate(ctx context.Context, key string, req UpdateTemplateRequest) (model.Template, error) {
+	tmpl, err := repository.GetTemplateByKey(ctx, key)
+	if err != nil {
+		return model.Template{}, err
+	}
+
+	tmpl.Name = req.Name
+	tmpl.Type = req.Type
+	tmpl.Subject = req.Subject
+	tmpl.Content = req.Content
+	tmpl.Description = req.Description
+	if err := tmpl.Validate(); err != nil {
+		return model.Template{}, err
+	}
+	if err := repository.SaveTemplate(ctx, &tmpl); err != nil {
+		return model.Template{}, err
+	}
+	return tmpl, nil
+}
+
+func deleteTemplate(ctx context.Context, key string) error {
+	tmpl, err := repository.GetTemplateByKey(ctx, key)
+	if err != nil {
+		return err
+	}
+	if tmpl.IsSystem {
+		return errors.New(SystemTemplateCannotDelete)
+	}
+	return repository.DeleteTemplate(ctx, &tmpl)
+}

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

@@ -0,0 +1,176 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package template
+
+import (
+	"errors"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+// CreateTemplateRequest 创建模板请求
+type CreateTemplateRequest struct {
+	Key         string `json:"key" binding:"required,max=80"`
+	Name        string `json:"name" binding:"required,max=100"`
+	Type        string `json:"type" binding:"required,max=20"`
+	Subject     string `json:"subject" binding:"max=255"`
+	Content     string `json:"content" binding:"required"`
+	Description string `json:"description" binding:"max=255"`
+}
+
+// UpdateTemplateRequest 更新模板请求
+type UpdateTemplateRequest struct {
+	Name        string `json:"name" binding:"required,max=100"`
+	Type        string `json:"type" binding:"required,max=20"`
+	Subject     string `json:"subject" binding:"max=255"`
+	Content     string `json:"content" binding:"required"`
+	Description string `json:"description" binding:"max=255"`
+}
+
+func abortTemplateLogicError(c *gin.Context, err error) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		response.AbortNotFound(c, TemplateNotFound)
+		return true
+	}
+	msg := err.Error()
+	switch msg {
+	case TemplateKeyExists, SystemTemplateCannotDelete:
+		response.AbortBadRequest(c, msg)
+		return true
+	}
+	response.AbortInternal(c, msg)
+	return true
+}
+
+// CreateTemplate 创建模板
+// @Summary 创建模板
+// @Description 创建一条新的自定义通知模板，模板标识符（Key）不可重复，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body template.CreateTemplateRequest true "创建请求参数"
+// @Success 200 {object} response.Any{data=string} "创建成功"
+// @Failure 400 {object} response.Any "参数错误或模板标识符已存在"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/templates [post]
+func CreateTemplate(c *gin.Context) {
+	var req CreateTemplateRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	tmpl, err := createTemplate(c.Request.Context(), req)
+	if abortTemplateLogicError(c, err) {
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(tmpl))
+}
+
+// ListTemplates 获取模板列表
+// @Summary 获取模板列表
+// @Description 返回所有通知模板列表，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]model.Template} "模板列表"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/templates [get]
+func ListTemplates(c *gin.Context) {
+	templates, err := listTemplates(c.Request.Context())
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(templates))
+}
+
+// GetTemplate 获取单个模板
+// @Summary 获取单个模板
+// @Description 根据模板标识符获取对应的模板详情，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param key path string true "模板标识符"
+// @Success 200 {object} response.Any{data=model.Template} "模板详情"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 404 {object} response.Any "模板不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/templates/{key} [get]
+func GetTemplate(c *gin.Context) {
+	tmpl, err := getTemplate(c.Request.Context(), c.Param("key"))
+	if abortTemplateLogicError(c, err) {
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(tmpl))
+}
+
+// UpdateTemplate 更新模板
+// @Summary 更新模板
+// @Description 根据模板标识符更新对应的模板内容，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param key path string true "模板标识符"
+// @Param request body template.UpdateTemplateRequest true "更新请求参数"
+// @Success 200 {object} response.Any{data=model.Template} "更新成功"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 404 {object} response.Any "模板不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/templates/{key} [put]
+func UpdateTemplate(c *gin.Context) {
+	var req UpdateTemplateRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	tmpl, err := updateTemplate(c.Request.Context(), c.Param("key"), req)
+	if abortTemplateLogicError(c, err) {
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(tmpl))
+}
+
+// DeleteTemplate 删除模板
+// @Summary 删除模板
+// @Description 根据模板标识符删除对应模板，系统预置模板不可删除，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param key path string true "模板标识符"
+// @Success 200 {object} response.Any{data=string} "删除成功"
+// @Failure 400 {object} response.Any "不可删除系统模板"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 404 {object} response.Any "模板不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/templates/{key} [delete]
+func DeleteTemplate(c *gin.Context) {
+	if err := deleteTemplate(c.Request.Context(), c.Param("key")); abortTemplateLogicError(c, err) {
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}

Wavelet/internal/apps/admin/template/routers_test.go

@@ -0,0 +1,242 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package template
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+func setupTestRouter(authUser *model.User) *gin.Engine {
+	r := testhelper.NewTestGinEngine()
+	adminGroup := r.Group("/api/v1/admin")
+
+	// Mock authentication middleware
+	adminGroup.Use(func(c *gin.Context) {
+		if authUser != nil {
+			oauth.SetToContext(c, oauth.UserObjKey, authUser)
+		}
+		c.Next()
+	})
+
+	adminGroup.GET("/templates", ListTemplates)
+	adminGroup.POST("/templates", CreateTemplate)
+
+	templateRouter := adminGroup.Group("/templates/:key")
+	{
+		templateRouter.GET("", GetTemplate)
+		templateRouter.PUT("", UpdateTemplate)
+		templateRouter.DELETE("", DeleteTemplate)
+	}
+
+	return r
+}
+
+func TestCreateTemplate(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("create successfully", func(t *testing.T) {
+		payload := CreateTemplateRequest{
+			Key:         "test_template",
+			Name:        "Test Template",
+			Type:        "email",
+			Subject:     "Test Subject",
+			Content:     "Hello {{.Name}}",
+			Description: "Test Desc",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/templates", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var tmpl model.Template
+		err := dbConn.Where("key = ?", "test_template").First(&tmpl).Error
+		if err != nil {
+			t.Fatalf("failed to find template in DB: %v", err)
+		}
+		if tmpl.Name != "Test Template" {
+			t.Errorf("expected Name 'Test Template', got '%s'", tmpl.Name)
+		}
+	})
+
+	t.Run("create duplicate key error", func(t *testing.T) {
+		payload := CreateTemplateRequest{
+			Key:         "test_template",
+			Name:        "Another Name",
+			Type:        "email",
+			Subject:     "Another Subject",
+			Content:     "Hello",
+			Description: "desc",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/templates", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request on duplicate key, got %d", w.Code)
+		}
+	})
+}
+
+func TestListTemplates(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	// Seed system templates manually for testing
+	t1 := model.Template{Key: "login_email", Name: "Login Code", Type: "email", Content: "code {{.Code}}", IsSystem: true}
+	t2 := model.Template{Key: "register_email", Name: "Register Code", Type: "email", Content: "code {{.Code}}", IsSystem: true}
+	dbConn.Create(&t1)
+	dbConn.Create(&t2)
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("list templates", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/templates", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d", w.Code)
+		}
+
+		var resp response.Any
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var templates []model.Template
+		_ = json.Unmarshal(dataBytes, &templates)
+
+		if len(templates) != 2 {
+			t.Errorf("expected 2 templates, got %d", len(templates))
+		}
+	})
+}
+
+func TestGetTemplate(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	t1 := model.Template{Key: "login_email", Name: "Login Code", Type: "email", Content: "code {{.Code}}", IsSystem: true}
+	dbConn.Create(&t1)
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("get existing", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/templates/login_email", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("expected 200 OK, got %d", w.Code)
+		}
+	})
+
+	t.Run("get non-existent", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/templates/non_existent", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusNotFound {
+			t.Errorf("expected 404 Not Found, got %d", w.Code)
+		}
+	})
+}
+
+func TestUpdateTemplate(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	t1 := model.Template{Key: "login_email", Name: "Login Code", Type: "email", Content: "code {{.Code}}", IsSystem: true}
+	dbConn.Create(&t1)
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("update successfully", func(t *testing.T) {
+		payload := UpdateTemplateRequest{
+			Name:        "Updated Login Code",
+			Type:        "email",
+			Subject:     "New Subject",
+			Content:     "new code {{.Code}}",
+			Description: "new desc",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/templates/login_email", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var tmpl model.Template
+		dbConn.Where("key = ?", "login_email").First(&tmpl)
+		if tmpl.Name != "Updated Login Code" || tmpl.Subject != "New Subject" {
+			t.Errorf("database values not updated: %+v", tmpl)
+		}
+	})
+}
+
+func TestDeleteTemplate(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	t1 := model.Template{Key: "login_email", Name: "Login Code", Type: "email", Content: "code {{.Code}}", IsSystem: true}
+	t2 := model.Template{Key: "custom_tmpl", Name: "Custom", Type: "email", Content: "hi", IsSystem: false}
+	dbConn.Create(&t1)
+	dbConn.Create(&t2)
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("delete system template should fail", func(t *testing.T) {
+		req, _ := http.NewRequest("DELETE", "/api/v1/admin/templates/login_email", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request when deleting system template, got %d", w.Code)
+		}
+	})
+
+	t.Run("delete custom template should succeed", func(t *testing.T) {
+		req, _ := http.NewRequest("DELETE", "/api/v1/admin/templates/custom_tmpl", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d", w.Code)
+		}
+
+		var count int64
+		dbConn.Model(&model.Template{}).Where("key = ?", "custom_tmpl").Count(&count)
+		if count != 0 {
+			t.Error("custom template was not deleted from DB")
+		}
+	})
+}

Wavelet/internal/apps/admin/updater/errs.go

@@ -0,0 +1,17 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package updater manages GitHub Release checks and in-place application upgrades.
+package updater
+
+const (
+	errInvalidRepository       = "上游仓库地址无效"
+	errReleaseRequestFailed    = "获取上游版本失败"
+	errReleaseResponseInvalid  = "上游版本响应无效"
+	errNoCompatibleRelease     = "未找到兼容的 Release"
+	errNoCompatibleAsset       = "未找到当前系统对应的 Release 资产"
+	errDevelopmentBuild        = "开发版本无法执行自动升级"
+	errAlreadyUpToDate         = "当前已是最新版本"
+	errUpgradeAlreadyRunning   = "已有升级任务正在执行"
+	errAutomaticUpgradeBlocked = "当前平台暂不支持自动替换二进制"
+)

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

@@ -0,0 +1,647 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package updater
+
+import (
+	"archive/tar"
+	"archive/zip"
+	"compress/gzip"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/buildinfo"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"golang.org/x/mod/semver"
+)
+
+const (
+	githubAPIBaseURL = "https://api.github.com"
+	maxArchiveSize   = int64(1024 * 1024 * 1024)
+	maxReleaseSize   = int64(4 * 1024 * 1024)
+	repositoryParts  = 2
+	windowsOS        = "windows"
+	archiveFileMode  = 0o600
+	stagedBinaryMode = 0o700
+)
+
+type releaseAsset struct {
+	Name               string `json:"name"`
+	BrowserDownloadURL string `json:"browser_download_url"`
+	Size               int64  `json:"size"`
+	State              string `json:"state"`
+}
+
+type githubRelease struct {
+	TagName    string         `json:"tag_name"`
+	Name       string         `json:"name"`
+	Body       string         `json:"body"`
+	HTMLURL    string         `json:"html_url"`
+	Draft      bool           `json:"draft"`
+	Prerelease bool           `json:"prerelease"`
+	Published  time.Time      `json:"published_at"`
+	Assets     []releaseAsset `json:"assets"`
+}
+
+// Status describes the current build and the newest compatible upstream release.
+type Status struct {
+	CurrentVersion     string `json:"current_version"`
+	BuildTime          string `json:"build_time"`
+	LatestVersion      string `json:"latest_version"`
+	UpdateAvailable    bool   `json:"update_available"`
+	CanUpgrade         bool   `json:"can_upgrade"`
+	Prerelease         bool   `json:"prerelease"`
+	ReleaseName        string `json:"release_name"`
+	ReleaseNotes       string `json:"release_notes"`
+	ReleaseURL         string `json:"release_url"`
+	PublishedAt        string `json:"published_at"`
+	UpstreamRepository string `json:"upstream_repository"`
+	AssetName          string `json:"asset_name"`
+	Platform           string `json:"platform"`
+}
+
+type releaseClient interface {
+	Do(req *http.Request) (*http.Response, error)
+}
+
+type manager struct {
+	client    releaseClient
+	mu        sync.Mutex
+	upgrading bool
+}
+
+var defaultManager = &manager{
+	client: &http.Client{Timeout: 10 * time.Minute},
+}
+
+func normalizeVersion(version string) string {
+	version = strings.TrimSpace(version)
+	if version == "" || version == "dev" {
+		return ""
+	}
+	if !strings.HasPrefix(version, "v") {
+		version = "v" + version
+	}
+	if !semver.IsValid(version) {
+		return ""
+	}
+	return version
+}
+
+func parseRepository(raw string) (string, error) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return "", errors.New(errInvalidRepository)
+	}
+
+	if !strings.Contains(raw, "://") {
+		repo := strings.TrimSuffix(strings.Trim(raw, "/"), ".git")
+		if len(strings.Split(repo, "/")) == repositoryParts {
+			return repo, nil
+		}
+		return "", errors.New(errInvalidRepository)
+	}
+
+	parsed, err := url.Parse(raw)
+	if err != nil || !strings.EqualFold(parsed.Hostname(), "github.com") {
+		return "", errors.New(errInvalidRepository)
+	}
+	repo := strings.TrimSuffix(strings.Trim(parsed.Path, "/"), ".git")
+	if len(strings.Split(repo, "/")) != repositoryParts {
+		return "", errors.New(errInvalidRepository)
+	}
+	return repo, nil
+}
+
+func expectedAssetName(tag string) string {
+	extension := "tar.gz"
+	if runtime.GOOS == windowsOS {
+		extension = "zip"
+	}
+	return fmt.Sprintf("wavelet_%s_%s_%s.%s", tag, runtime.GOOS, runtime.GOARCH, extension)
+}
+
+func expectedAssetNames(repository, tag string) []string {
+	names := []string{expectedAssetName(tag)}
+	if parts := strings.Split(repository, "/"); len(parts) == repositoryParts {
+		repoName := parts[1]
+		if repoName != "wavelet" {
+			extension := "tar.gz"
+			if runtime.GOOS == windowsOS {
+				extension = "zip"
+			}
+			names = append(names, fmt.Sprintf("%s_%s_%s_%s.%s", repoName, tag, runtime.GOOS, runtime.GOARCH, extension))
+		}
+	}
+	return names
+}
+
+func selectLatestRelease(repository string, releases []githubRelease) (githubRelease, releaseAsset, error) {
+	var selected githubRelease
+	var selectedAsset releaseAsset
+	selectedVersion := ""
+
+	for _, release := range releases {
+		version := normalizeVersion(release.TagName)
+		if release.Draft || version == "" {
+			continue
+		}
+		expectedNames := expectedAssetNames(repository, release.TagName)
+		for _, asset := range release.Assets {
+			matched := false
+			for _, name := range expectedNames {
+				if asset.Name == name {
+					matched = true
+					break
+				}
+			}
+			if !matched || asset.BrowserDownloadURL == "" || asset.State != "uploaded" {
+				continue
+			}
+			if selectedVersion == "" || semver.Compare(version, selectedVersion) > 0 {
+				selected = release
+				selectedAsset = asset
+				selectedVersion = version
+			}
+		}
+	}
+
+	if selectedVersion == "" {
+		return githubRelease{}, releaseAsset{}, errors.New(errNoCompatibleRelease)
+	}
+	return selected, selectedAsset, nil
+}
+
+func (m *manager) fetchRelease(ctx context.Context, repository string) (githubRelease, releaseAsset, error) {
+	req, err := http.NewRequestWithContext(
+		ctx,
+		http.MethodGet,
+		fmt.Sprintf("%s/repos/%s/releases?per_page=30", githubAPIBaseURL, repository),
+		nil,
+	)
+	if err != nil {
+		return githubRelease{}, releaseAsset{}, fmt.Errorf("%s: %w", errReleaseRequestFailed, err)
+	}
+	req.Header.Set("Accept", "application/vnd.github+json")
+	req.Header.Set("User-Agent", "Wavelet-Updater")
+	req.Header.Set("X-GitHub-Api-Version", "2022-11-28")
+
+	resp, err := m.client.Do(req)
+	if err != nil {
+		return githubRelease{}, releaseAsset{}, fmt.Errorf("%s: %w", errReleaseRequestFailed, err)
+	}
+	defer func() {
+		// The response body is read-only; close errors cannot affect the parsed result.
+		_ = resp.Body.Close()
+	}()
+	if resp.StatusCode != http.StatusOK {
+		return githubRelease{}, releaseAsset{}, fmt.Errorf("%s: HTTP %d", errReleaseRequestFailed, resp.StatusCode)
+	}
+
+	var releases []githubRelease
+	decoder := json.NewDecoder(io.LimitReader(resp.Body, maxReleaseSize))
+	if err := decoder.Decode(&releases); err != nil {
+		return githubRelease{}, releaseAsset{}, fmt.Errorf("%s: %w", errReleaseResponseInvalid, err)
+	}
+
+	release, asset, err := selectLatestRelease(repository, releases)
+	if err != nil {
+		return githubRelease{}, releaseAsset{}, err
+	}
+	logger.InfoF(ctx, "[Updater] Selected latest compatible release: %s (Asset: %s)", release.TagName, asset.Name)
+	return release, asset, nil
+}
+
+func loadRepository(ctx context.Context) (string, error) {
+	config, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeyUpdateUpstreamRepository)
+	if err != nil {
+		return "", fmt.Errorf("%s: %w", errInvalidRepository, err)
+	}
+	return parseRepository(config.Value)
+}
+
+func (m *manager) status(ctx context.Context) (Status, releaseAsset, error) {
+	upstreamRepo, err := loadRepository(ctx)
+	if err != nil {
+		return Status{}, releaseAsset{}, err
+	}
+	release, asset, err := m.fetchRelease(ctx, upstreamRepo)
+	if err != nil {
+		return Status{}, releaseAsset{}, err
+	}
+
+	currentVersion := normalizeVersion(buildinfo.Version)
+	latestVersion := normalizeVersion(release.TagName)
+	updateAvailable := currentVersion != "" && semver.Compare(latestVersion, currentVersion) > 0
+
+	logger.InfoF(ctx, "[Updater] Check update complete. current: %s, latest: %s, update_available: %t", buildinfo.Version, release.TagName, updateAvailable)
+
+	return Status{
+		CurrentVersion:     buildinfo.Version,
+		BuildTime:          buildinfo.BuildTime,
+		LatestVersion:      release.TagName,
+		UpdateAvailable:    updateAvailable,
+		CanUpgrade:         updateAvailable && runtime.GOOS != windowsOS,
+		Prerelease:         release.Prerelease,
+		ReleaseName:        release.Name,
+		ReleaseNotes:       release.Body,
+		ReleaseURL:         release.HTMLURL,
+		PublishedAt:        release.Published.Format(time.RFC3339),
+		UpstreamRepository: upstreamRepo,
+		AssetName:          asset.Name,
+		Platform:           runtime.GOOS + "/" + runtime.GOARCH,
+	}, asset, nil
+}
+
+func downloadArchive(ctx context.Context, client releaseClient, asset releaseAsset, destination string) error {
+	if asset.Size <= 0 || asset.Size > maxArchiveSize {
+		return fmt.Errorf("release 资产大小无效: %d", asset.Size)
+	}
+	logger.InfoF(ctx, "[Updater] Downloading release asset: %s", asset.Name)
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, asset.BrowserDownloadURL, nil)
+	if err != nil {
+		return fmt.Errorf("创建升级下载请求失败: %w", err)
+	}
+	req.Header.Set("User-Agent", "Wavelet-Updater")
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return fmt.Errorf("下载升级资产失败: %w", err)
+	}
+	defer func() {
+		// The downloaded body has already been validated by size before use.
+		_ = resp.Body.Close()
+	}()
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("下载升级资产失败: HTTP %d", resp.StatusCode)
+	}
+
+	file, err := os.OpenFile(destination, os.O_CREATE|os.O_EXCL|os.O_WRONLY, archiveFileMode) //nolint:gosec // destination is created inside the verified executable directory.
+	if err != nil {
+		return fmt.Errorf("创建升级归档失败: %w", err)
+	}
+
+	written, err := io.Copy(file, io.LimitReader(resp.Body, maxArchiveSize+1))
+	if err != nil {
+		_ = file.Close()
+		return fmt.Errorf("写入升级归档失败: %w", err)
+	}
+	if err := file.Close(); err != nil {
+		return fmt.Errorf("关闭升级归档失败: %w", err)
+	}
+	if written > maxArchiveSize || written != asset.Size {
+		return fmt.Errorf("升级归档大小不匹配: got %d, want %d", written, asset.Size)
+	}
+	logger.InfoF(ctx, "[Updater] Successfully downloaded release asset to %s", destination)
+	return nil
+}
+
+func safeArchivePath(destination, name string) (string, error) {
+	cleanName := filepath.Clean(name)
+	if filepath.IsAbs(cleanName) || cleanName == "." || strings.HasPrefix(cleanName, ".."+string(filepath.Separator)) {
+		return "", fmt.Errorf("归档包含非法路径: %s", name)
+	}
+	target := filepath.Join(destination, cleanName)
+	relative, err := filepath.Rel(destination, target)
+	if err != nil || relative == ".." || strings.HasPrefix(relative, ".."+string(filepath.Separator)) {
+		return "", fmt.Errorf("归档路径越界: %s", name)
+	}
+	return target, nil
+}
+
+func matchBinaryName(name string, candidates []string) bool {
+	for _, candidate := range candidates {
+		if runtime.GOOS == windowsOS {
+			if strings.EqualFold(name, candidate) {
+				return true
+			}
+		} else {
+			if name == candidate {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func getCandidateBinaryNames(executable string, repository string) []string {
+	execName := filepath.Base(executable)
+	names := []string{execName}
+
+	addName := func(base string) {
+		name := base
+		if runtime.GOOS == windowsOS && !strings.HasSuffix(strings.ToLower(name), ".exe") {
+			name += ".exe"
+		}
+		for _, existing := range names {
+			if existing == name {
+				return
+			}
+		}
+		names = append(names, name)
+	}
+
+	if parts := strings.Split(repository, "/"); len(parts) == repositoryParts {
+		addName(parts[1])
+	}
+	addName("wavelet")
+
+	return names
+}
+
+func isLikelyBinary(name string, isDir bool, mode os.FileMode) bool {
+	if isDir {
+		return false
+	}
+	base := strings.ToLower(filepath.Base(name))
+
+	// Exclude typical non-binary metadata files
+	exclusions := []string{
+		"license", "licence", "copying", "notice", "readme", "changelog",
+	}
+	for _, excl := range exclusions {
+		if strings.HasPrefix(base, excl) {
+			return false
+		}
+	}
+
+	if runtime.GOOS == windowsOS {
+		return filepath.Ext(base) == ".exe"
+	}
+
+	// On Unix, it should either have the executable permission bit set, OR have no extension
+	return (mode.Perm()&0111 != 0) || (filepath.Ext(base) == "")
+}
+
+func findBinaryInTarGz(archivePath string, candidates []string) (string, error) {
+	file, err := os.Open(archivePath) //nolint:gosec // archivePath is created by prepareUpgrade in the executable directory.
+	if err != nil {
+		return "", err
+	}
+	defer func() {
+		_ = file.Close()
+	}()
+
+	gzipReader, err := gzip.NewReader(file)
+	if err != nil {
+		return "", err
+	}
+	defer func() {
+		_ = gzipReader.Close()
+	}()
+
+	reader := tar.NewReader(gzipReader)
+	var binaries []string
+	for {
+		header, err := reader.Next()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			return "", err
+		}
+		if header.Typeflag == tar.TypeReg && isLikelyBinary(header.Name, false, header.FileInfo().Mode()) {
+			binaries = append(binaries, header.Name)
+		}
+	}
+
+	if len(binaries) == 1 {
+		return binaries[0], nil
+	}
+
+	// Fallback to candidate match if multiple or zero likely binaries found
+	for _, name := range binaries {
+		if matchBinaryName(filepath.Base(name), candidates) {
+			return name, nil
+		}
+	}
+
+	return "", errors.New(errNoCompatibleAsset)
+}
+
+func findBinaryInZip(archivePath string, candidates []string) (string, error) {
+	reader, err := zip.OpenReader(archivePath)
+	if err != nil {
+		return "", err
+	}
+	defer func() {
+		_ = reader.Close()
+	}()
+
+	var binaries []string
+	for _, file := range reader.File {
+		if !file.FileInfo().IsDir() && isLikelyBinary(file.Name, false, file.FileInfo().Mode()) {
+			binaries = append(binaries, file.Name)
+		}
+	}
+
+	if len(binaries) == 1 {
+		return binaries[0], nil
+	}
+
+	// Fallback to candidate match if multiple or zero likely binaries found
+	for _, name := range binaries {
+		if matchBinaryName(filepath.Base(name), candidates) {
+			return name, nil
+		}
+	}
+
+	return "", errors.New(errNoCompatibleAsset)
+}
+
+func extractTarGz(ctx context.Context, archivePath, destination, targetName string, candidates []string) (string, error) {
+	binaryPathInArchive, err := findBinaryInTarGz(archivePath, candidates)
+	if err != nil {
+		return "", err
+	}
+
+	logger.InfoF(ctx, "[Updater] Extracting tar.gz archive: %s (extracting: %s)", archivePath, binaryPathInArchive)
+	file, err := os.Open(archivePath) //nolint:gosec // archivePath is created by prepareUpgrade in the executable directory.
+	if err != nil {
+		return "", err
+	}
+	defer func() {
+		// Read-only archive close errors do not change extraction validity.
+		_ = file.Close()
+	}()
+	gzipReader, err := gzip.NewReader(file)
+	if err != nil {
+		return "", err
+	}
+	defer func() {
+		// The gzip checksum is verified while reading the selected file.
+		_ = gzipReader.Close()
+	}()
+
+	reader := tar.NewReader(gzipReader)
+	for {
+		header, err := reader.Next()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			return "", err
+		}
+		if header.Name != binaryPathInArchive {
+			continue
+		}
+		target, err := safeArchivePath(destination, targetName)
+		if err != nil {
+			return "", err
+		}
+		output, err := os.OpenFile(target, os.O_CREATE|os.O_EXCL|os.O_WRONLY, stagedBinaryMode) //nolint:gosec // target is constrained by safeArchivePath.
+		if err != nil {
+			return "", err
+		}
+		written, copyErr := io.Copy(output, io.LimitReader(reader, maxArchiveSize+1))
+		closeErr := output.Close()
+		if copyErr != nil {
+			return "", copyErr
+		}
+		if closeErr != nil {
+			return "", closeErr
+		}
+		if written > maxArchiveSize {
+			return "", errors.New("解压后的程序文件超过大小限制")
+		}
+		logger.InfoF(ctx, "[Updater] Successfully extracted binary to %s", target)
+		return target, nil
+	}
+	return "", errors.New(errNoCompatibleAsset)
+}
+
+func extractZip(ctx context.Context, archivePath, destination, targetName string, candidates []string) (string, error) {
+	binaryPathInArchive, err := findBinaryInZip(archivePath, candidates)
+	if err != nil {
+		return "", err
+	}
+
+	logger.InfoF(ctx, "[Updater] Extracting zip archive: %s (extracting: %s)", archivePath, binaryPathInArchive)
+	reader, err := zip.OpenReader(archivePath)
+	if err != nil {
+		return "", err
+	}
+	defer func() {
+		// Read-only archive close errors do not change extraction validity.
+		_ = reader.Close()
+	}()
+	for _, file := range reader.File {
+		if file.Name != binaryPathInArchive {
+			continue
+		}
+		target, err := safeArchivePath(destination, targetName)
+		if err != nil {
+			return "", err
+		}
+		input, err := file.Open()
+		if err != nil {
+			return "", err
+		}
+		output, err := os.OpenFile(target, os.O_CREATE|os.O_EXCL|os.O_WRONLY, stagedBinaryMode) //nolint:gosec // target is constrained by safeArchivePath.
+		if err != nil {
+			_ = input.Close()
+			return "", err
+		}
+		written, copyErr := io.Copy(output, io.LimitReader(input, maxArchiveSize+1))
+		inputCloseErr := input.Close()
+		outputCloseErr := output.Close()
+		if copyErr != nil {
+			return "", copyErr
+		}
+		if inputCloseErr != nil {
+			return "", inputCloseErr
+		}
+		if outputCloseErr != nil {
+			return "", outputCloseErr
+		}
+		if written > maxArchiveSize {
+			return "", errors.New("解压后的程序文件超过大小限制")
+		}
+		logger.InfoF(ctx, "[Updater] Successfully extracted binary to %s", target)
+		return target, nil
+	}
+	return "", errors.New(errNoCompatibleAsset)
+}
+
+func (m *manager) prepareUpgrade(ctx context.Context) (string, string, error) {
+	if runtime.GOOS == windowsOS {
+		return "", "", errors.New(errAutomaticUpgradeBlocked)
+	}
+	if normalizeVersion(buildinfo.Version) == "" {
+		return "", "", errors.New(errDevelopmentBuild)
+	}
+
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.upgrading {
+		return "", "", errors.New(errUpgradeAlreadyRunning)
+	}
+
+	status, asset, err := m.status(ctx)
+	if err != nil {
+		return "", "", err
+	}
+	if !status.UpdateAvailable {
+		return "", "", errors.New(errAlreadyUpToDate)
+	}
+
+	logger.InfoF(ctx, "[Updater] Preparing upgrade. current: %s, latest: %s", status.CurrentVersion, status.LatestVersion)
+
+	executable, err := os.Executable()
+	if err != nil {
+		return "", "", fmt.Errorf("定位当前程序失败: %w", err)
+	}
+	executable, err = filepath.EvalSymlinks(executable)
+	if err != nil {
+		return "", "", fmt.Errorf("解析当前程序路径失败: %w", err)
+	}
+
+	tempDir, err := os.MkdirTemp(filepath.Dir(executable), ".wavelet-update-*")
+	if err != nil {
+		return "", "", fmt.Errorf("创建升级目录失败: %w", err)
+	}
+
+	archivePath := filepath.Join(tempDir, asset.Name)
+	if err := downloadArchive(ctx, m.client, asset, archivePath); err != nil {
+		// Cleanup is best effort because the download error is the actionable failure.
+		_ = os.RemoveAll(tempDir)
+		return "", "", err
+	}
+
+	targetName := filepath.Base(executable)
+	candidates := getCandidateBinaryNames(executable, status.UpstreamRepository)
+
+	var stagedBinary string
+	if strings.HasSuffix(asset.Name, ".zip") {
+		stagedBinary, err = extractZip(ctx, archivePath, tempDir, targetName, candidates)
+	} else {
+		stagedBinary, err = extractTarGz(ctx, archivePath, tempDir, targetName, candidates)
+	}
+	if err != nil {
+		// Cleanup is best effort because the extraction error is the actionable failure.
+		_ = os.RemoveAll(tempDir)
+		return "", "", fmt.Errorf("解压升级资产失败: %w", err)
+	}
+	logger.InfoF(ctx, "[Updater] Staged binary successfully prepared: %s", stagedBinary)
+	m.upgrading = true
+	return executable, stagedBinary, nil
+}
+
+func (m *manager) finishUpgrade() {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.upgrading = false
+}

Wavelet/internal/apps/admin/updater/logics_test.go

@@ -0,0 +1,130 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package updater
+
+import (
+	"runtime"
+	"testing"
+	"time"
+)
+
+func TestParseRepository(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   string
+		want    string
+		wantErr bool
+	}{
+		{name: "short form", input: "Rain-kl/Wavelet", want: "Rain-kl/Wavelet"},
+		{name: "GitHub URL", input: "https://github.com/Rain-kl/Wavelet.git", want: "Rain-kl/Wavelet"},
+		{name: "unsupported host", input: "https://example.com/Rain-kl/Wavelet", wantErr: true},
+		{name: "missing owner", input: "Wavelet", wantErr: true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := parseRepository(tt.input)
+			if gotErr := err != nil; gotErr != tt.wantErr {
+				t.Errorf("parseRepository(%q) error = %v, want error presence = %t", tt.input, err, tt.wantErr)
+			}
+			if got != tt.want {
+				t.Errorf("parseRepository(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestSelectLatestRelease(t *testing.T) {
+	assetNameV1 := expectedAssetName("v1.0.0")
+	assetNameV2 := expectedAssetName("v2.0.0")
+	releases := []githubRelease{
+		{
+			TagName:   "v1.0.0",
+			Published: time.Date(2026, time.June, 1, 0, 0, 0, 0, time.UTC),
+			Assets: []releaseAsset{{
+				Name:               assetNameV1,
+				BrowserDownloadURL: "https://example.com/v1",
+				State:              "uploaded",
+			}},
+		},
+		{
+			TagName:   "v2.0.0",
+			Published: time.Date(2026, time.June, 2, 0, 0, 0, 0, time.UTC),
+			Assets: []releaseAsset{{
+				Name:               assetNameV2,
+				BrowserDownloadURL: "https://example.com/v2",
+				State:              "uploaded",
+			}},
+		},
+		{
+			TagName: "v3.0.0",
+			Assets: []releaseAsset{{
+				Name:               "wavelet_v3.0.0_other_platform.tar.gz",
+				BrowserDownloadURL: "https://example.com/v3",
+				State:              "uploaded",
+			}},
+		},
+	}
+
+	release, asset, err := selectLatestRelease("Rain-kl/Wavelet", releases)
+	if err != nil {
+		t.Fatalf("selectLatestRelease() error = %v", err)
+	}
+	if release.TagName != "v2.0.0" {
+		t.Errorf("selectLatestRelease() tag = %q, want %q", release.TagName, "v2.0.0")
+	}
+	if asset.Name != assetNameV2 {
+		t.Errorf("selectLatestRelease() asset = %q, want %q", asset.Name, assetNameV2)
+	}
+}
+
+func TestSelectLatestReleaseWithCustomRepo(t *testing.T) {
+	extension := "tar.gz"
+	if runtime.GOOS == "windows" {
+		extension = "zip"
+	}
+	releases := []githubRelease{
+		{
+			TagName:   "v1.0.0",
+			Published: time.Date(2026, time.June, 1, 0, 0, 0, 0, time.UTC),
+			Assets: []releaseAsset{{
+				Name:               "wavelet_v1.0.0_" + runtime.GOOS + "_" + runtime.GOARCH + "." + extension,
+				BrowserDownloadURL: "https://example.com/v1",
+				State:              "uploaded",
+			}},
+		},
+		{
+			TagName:   "v2.0.0",
+			Published: time.Date(2026, time.June, 2, 0, 0, 0, 0, time.UTC),
+			Assets: []releaseAsset{{
+				Name:               "PixezSync_v2.0.0_" + runtime.GOOS + "_" + runtime.GOARCH + "." + extension,
+				BrowserDownloadURL: "https://example.com/v2",
+				State:              "uploaded",
+			}},
+		},
+	}
+
+	release, asset, err := selectLatestRelease("Rain-kl/PixezSync", releases)
+	if err != nil {
+		t.Fatalf("selectLatestRelease() error = %v", err)
+	}
+	if release.TagName != "v2.0.0" {
+		t.Errorf("selectLatestRelease() tag = %q, want %q", release.TagName, "v2.0.0")
+	}
+	expectedName := "PixezSync_v2.0.0_" + runtime.GOOS + "_" + runtime.GOARCH + "." + extension
+	if asset.Name != expectedName {
+		t.Errorf("selectLatestRelease() asset = %q, want %q", asset.Name, expectedName)
+	}
+}
+
+func TestExpectedAssetName(t *testing.T) {
+	extension := "tar.gz"
+	if runtime.GOOS == "windows" {
+		extension = "zip"
+	}
+	want := "wavelet_v1.2.3_" + runtime.GOOS + "_" + runtime.GOARCH + "." + extension
+	if got := expectedAssetName("v1.2.3"); got != want {
+		t.Errorf("expectedAssetName(%q) = %q, want %q", "v1.2.3", got, want)
+	}
+}

Wavelet/internal/apps/admin/updater/restart_unix.go

@@ -0,0 +1,50 @@
+//go:build !windows
+
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package updater
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"syscall"
+
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+)
+
+const installedBinaryMode = 0o755
+
+func replaceAndRestart(executable, stagedBinary string) error {
+	ctx := context.Background()
+	logger.InfoF(ctx, "[Updater] Swapping executable: %s -> %s", executable, stagedBinary)
+	backup := executable + ".old"
+
+	if err := os.Remove(backup); err != nil && !os.IsNotExist(err) {
+		return fmt.Errorf("删除旧备份失败: %w", err)
+	}
+
+	if err := os.Rename(executable, backup); err != nil {
+		return fmt.Errorf("备份当前程序失败: %w", err)
+	}
+
+	if err := os.Rename(stagedBinary, executable); err != nil {
+		_ = os.Rename(backup, executable)
+		return fmt.Errorf("替换当前程序失败: %w", err)
+	}
+
+	if err := os.Chmod(executable, installedBinaryMode); err != nil { //nolint:gosec // the installed application binary must be executable.
+		_ = os.Remove(executable)
+		_ = os.Rename(backup, executable)
+		return fmt.Errorf("设置程序执行权限失败: %w", err)
+	}
+
+	stagingDir := filepath.Dir(stagedBinary)
+	// Cleanup is best effort; a leftover staging directory must not block restart.
+	_ = os.RemoveAll(stagingDir)
+
+	logger.InfoF(ctx, "[Updater] Executing syscall.Exec to restart service: %s %v", executable, os.Args)
+	return syscall.Exec(executable, os.Args, os.Environ()) //nolint:gosec // executable is resolved from os.Executable and never supplied by a request.
+}

Wavelet/internal/apps/admin/updater/restart_windows.go

@@ -0,0 +1,12 @@
+//go:build windows
+
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package updater
+
+import "errors"
+
+func replaceAndRestart(_, _ string) error {
+	return errors.New(errAutomaticUpgradeBlocked)
+}

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

@@ -0,0 +1,68 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package updater
+
+import (
+	"context"
+	"net/http"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+// GetUpdateStatus 获取应用更新状态
+// @Summary 获取应用更新状态
+// @Description 从系统配置指定的 GitHub 上游仓库查询最新兼容 Release，并与当前服务版本比较
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=updater.Status} "更新状态"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "查询失败"
+// @Router /api/v1/admin/update [get]
+func GetUpdateStatus(c *gin.Context) {
+	status, _, err := defaultManager.status(c.Request.Context())
+	if err != nil {
+		logger.ErrorF(c.Request.Context(), "[Updater] check release failed: %v", err)
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(status))
+}
+
+// ApplyUpdate 下载并应用应用更新
+// @Summary 下载并应用应用更新
+// @Description 下载当前平台对应的 GitHub Actions Release 资产，替换当前二进制并重启进程
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any "升级已准备并即将重启"
+// @Failure 400 {object} response.Any "当前版本不可升级"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "升级准备失败"
+// @Router /api/v1/admin/update/apply [post]
+func ApplyUpdate(c *gin.Context) {
+	executable, stagedBinary, err := defaultManager.prepareUpgrade(c.Request.Context())
+	if err != nil {
+		logger.ErrorF(c.Request.Context(), "[Updater] prepare upgrade failed: %v", err)
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	logger.InfoF(c.Request.Context(), "[Updater] upgrade prepared; restarting with %s", stagedBinary)
+	c.JSON(http.StatusOK, response.OKNil())
+
+	go func() {
+		time.Sleep(time.Second)
+		if err := replaceAndRestart(executable, stagedBinary); err != nil {
+			defaultManager.finishUpgrade()
+			logger.ErrorF(context.Background(), "[Updater] replace and restart failed: %v", err)
+		}
+	}()
+}

Wavelet/internal/apps/admin/user/errs.go

@@ -0,0 +1,21 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package user 提供用户管理功能
+package user
+
+const (
+	userNotFound     = "用户不存在"
+	cannotDisable    = "不能禁用管理员用户"
+	cannotDelete     = "不能删除管理员用户"
+	cannotDeleteSelf = "不能删除当前登录用户"
+	updateUserFailed = "更新用户状态失败"
+	deleteUserFailed = "删除用户失败"
+	usernameExists   = "用户名已存在"
+	usernameRequired = "用户名不能为空"
+	passwordTooShort = "密码长度不能少于 8 位" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	createUserFailed = "创建用户失败"
+	emailRequired    = "邮箱不能为空"
+	emailExists      = "邮箱已被注册"
+)

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

@@ -0,0 +1,106 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/db/idgen"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+)
+
+func listUsers(ctx context.Context, req listUsersRequest) (int64, []model.User, error) {
+	return repository.ListAdminUsers(ctx, repository.AdminUserListFilter{
+		UserID:   req.UserID,
+		Username: strings.TrimSpace(req.Username),
+		Page:     req.Page,
+		PageSize: req.PageSize,
+	})
+}
+
+func getUserDetail(ctx context.Context, id uint64) (model.User, error) {
+	return repository.GetAdminUserDetail(ctx, id)
+}
+
+func updateUserStatus(ctx context.Context, id uint64, active bool) error {
+	flags, err := repository.GetUserAdminFlags(ctx, id)
+	if err != nil {
+		return err
+	}
+	if !active && flags.IsAdmin {
+		return errors.New(cannotDisable)
+	}
+	return repository.UpdateUserActive(ctx, id, active)
+}
+
+func deleteUser(ctx context.Context, currentUserID, targetID uint64) error {
+	if currentUserID == targetID {
+		return errors.New(cannotDeleteSelf)
+	}
+	flags, err := repository.GetUserAdminFlags(ctx, targetID)
+	if err != nil {
+		return err
+	}
+	if flags.IsAdmin {
+		return errors.New(cannotDelete)
+	}
+	return repository.DeleteUserWithRelations(ctx, targetID)
+}
+
+func createUser(ctx context.Context, req createUserRequest) (model.User, error) {
+	req.Username = strings.TrimSpace(req.Username)
+	req.Nickname = strings.TrimSpace(req.Nickname)
+	req.Password = strings.TrimSpace(req.Password)
+	req.Email = strings.TrimSpace(req.Email)
+
+	if req.Username == "" {
+		return model.User{}, errors.New(usernameRequired)
+	}
+	if req.Email == "" {
+		return model.User{}, errors.New(emailRequired)
+	}
+	if len(req.Password) < minPasswordLength {
+		return model.User{}, errors.New(passwordTooShort)
+	}
+
+	count, err := repository.CountUsersByUsername(ctx, req.Username)
+	if err != nil {
+		return model.User{}, err
+	}
+	if count > 0 {
+		return model.User{}, errors.New(usernameExists)
+	}
+
+	emailCount, err := repository.CountUsersByEmail(ctx, req.Email)
+	if err != nil {
+		return model.User{}, err
+	}
+	if emailCount > 0 {
+		return model.User{}, errors.New(emailExists)
+	}
+
+	newUser := model.User{
+		ID:          idgen.NextUint64ID(),
+		Username:    req.Username,
+		Nickname:    req.Nickname,
+		Email:       req.Email,
+		IsActive:    req.IsActive,
+		IsAdmin:     req.IsAdmin,
+		LastLoginAt: time.Time{},
+	}
+	if newUser.Nickname == "" {
+		newUser.Nickname = req.Username
+	}
+	if err := newUser.SetEncryptedPassword(req.Password); err != nil {
+		return model.User{}, err
+	}
+	if err := repository.CreateUser(ctx, &newUser); err != nil {
+		return model.User{}, err
+	}
+	return newUser, nil
+}

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

@@ -0,0 +1,288 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+import (
+	"errors"
+	"net/http"
+	"strconv"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+// minPasswordLength 密码最小长度
+const minPasswordLength = 8
+
+// listUsersRequest 用户列表查询请求
+type listUsersRequest struct {
+	Page     int     `form:"page" binding:"min=1"`
+	PageSize int     `form:"page_size" binding:"min=1,max=100"`
+	UserID   *uint64 `form:"user_id" binding:"omitempty,gt=0"`
+	Username string  `form:"username"`
+}
+
+type user struct {
+	ID          uint64    `json:"id,string"`
+	Username    string    `json:"username"`
+	Nickname    string    `json:"nickname"`
+	Email       string    `json:"email"`
+	AvatarURL   string    `json:"avatar_url"`
+	IsActive    bool      `json:"is_active"`
+	IsAdmin     bool      `json:"is_admin"`
+	Bio         string    `json:"bio"`
+	Phone       string    `json:"phone"`
+	Gender      string    `json:"gender"`
+	Website     string    `json:"website"`
+	Location    string    `json:"location"`
+	LastLoginAt time.Time `json:"last_login_at"`
+	CreatedAt   time.Time `json:"created_at"`
+	UpdatedAt   time.Time `json:"updated_at"`
+}
+
+// listUsersResponse 用户列表响应
+type listUsersResponse struct {
+	Users []user `json:"users"`
+	Total int64  `json:"total"`
+}
+
+func parseUserID(c *gin.Context) (uint64, bool) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil || id == 0 {
+		response.AbortBadRequest(c, userNotFound)
+		return 0, false
+	}
+	return id, true
+}
+
+func toUser(u model.User) user {
+	return user{
+		ID:          u.ID,
+		Username:    u.Username,
+		Nickname:    u.Nickname,
+		Email:       u.Email,
+		AvatarURL:   u.AvatarURL,
+		IsActive:    u.IsActive,
+		IsAdmin:     u.IsAdmin,
+		Bio:         u.Bio,
+		Phone:       u.Phone,
+		Gender:      u.Gender,
+		Website:     u.Website,
+		Location:    u.Location,
+		LastLoginAt: u.LastLoginAt,
+		CreatedAt:   u.CreatedAt,
+		UpdatedAt:   u.UpdatedAt,
+	}
+}
+
+func abortUserLogicError(c *gin.Context, err error, notFoundMsg string, forbiddenMsgs, badRequestMsgs []string) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		response.AbortNotFound(c, notFoundMsg)
+		return true
+	}
+	msg := err.Error()
+	for _, m := range badRequestMsgs {
+		if msg == m {
+			response.AbortBadRequest(c, msg)
+			return true
+		}
+	}
+	for _, m := range forbiddenMsgs {
+		if msg == m {
+			response.AbortForbidden(c, msg)
+			return true
+		}
+	}
+	response.AbortInternal(c, msg)
+	return true
+}
+
+// ListUsers 获取用户列表
+// @Summary 获取用户列表
+// @Description 分页返回用户列表，支持按用户 ID 和用户名筛选，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param request query listUsersRequest true "查询参数"
+// @Success 200 {object} response.Any{data=user.listUsersResponse} "用户列表"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/users [get]
+func ListUsers(c *gin.Context) {
+	var req listUsersRequest
+	if err := c.ShouldBindQuery(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	total, modelUsers, err := listUsers(c.Request.Context(), req)
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	users := make([]user, 0, len(modelUsers))
+	for _, modelUser := range modelUsers {
+		users = append(users, toUser(modelUser))
+	}
+
+	c.JSON(http.StatusOK, response.OK(listUsersResponse{
+		Users: users,
+		Total: total,
+	}))
+}
+
+// GetUser 获取用户详情
+// @Summary 获取用户详情
+// @Description 返回指定用户的完整个人资料和系统状态，需要管理员权限，不返回密码等敏感字段
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "用户 ID"
+// @Success 200 {object} response.Any{data=user.user} "用户详情"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 404 {object} response.Any "用户不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/users/{id} [get]
+func GetUser(c *gin.Context) {
+	id, ok := parseUserID(c)
+	if !ok {
+		return
+	}
+
+	targetUser, err := getUserDetail(c.Request.Context(), id)
+	if abortUserLogicError(c, err, userNotFound, nil, nil) {
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(toUser(targetUser)))
+}
+
+// updateUserStatusRequest 更新用户状态请求
+type updateUserStatusRequest struct {
+	IsActive bool `json:"is_active"`
+}
+
+// UpdateUserStatus 更新用户状态（启用/禁用）
+// @Summary 更新用户状态
+// @Description 启用或禁用指定用户，管理员账号无法被禁用，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "用户 ID"
+// @Param request body updateUserStatusRequest true "状态参数"
+// @Success 200 {object} response.Any{data=string} "更新成功"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限或尝试禁用管理员"
+// @Failure 404 {object} response.Any "用户不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/users/{id}/status [put]
+func UpdateUserStatus(c *gin.Context) {
+	var req updateUserStatusRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	id, ok := parseUserID(c)
+	if !ok {
+		return
+	}
+
+	if err := updateUserStatus(c.Request.Context(), id, req.IsActive); err != nil {
+		if abortUserLogicError(c, err, userNotFound, []string{cannotDisable}, nil) {
+			return
+		}
+		response.AbortInternal(c, updateUserFailed)
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// DeleteUser 删除用户
+// @Summary 删除用户
+// @Description 删除指定非管理员用户，需要管理员权限，不能删除当前登录用户
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "用户 ID"
+// @Success 200 {object} response.Any{data=string} "删除成功"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限、尝试删除管理员或当前用户"
+// @Failure 404 {object} response.Any "用户不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/users/{id} [delete]
+func DeleteUser(c *gin.Context) {
+	id, ok := parseUserID(c)
+	if !ok {
+		return
+	}
+
+	currUser, _ := oauth.GetFromContext[*model.User](c, oauth.UserObjKey)
+	if err := deleteUser(c.Request.Context(), currUser.ID, id); err != nil {
+		if abortUserLogicError(c, err, userNotFound, []string{cannotDelete, cannotDeleteSelf}, nil) {
+			return
+		}
+		response.AbortInternal(c, deleteUserFailed)
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// createUserRequest 创建用户请求
+type createUserRequest struct {
+	Username string `json:"username" binding:"required,min=3,max=64"`
+	Password string `json:"password" binding:"required,min=8,max=64"`
+	Nickname string `json:"nickname" binding:"omitempty,max=64"`
+	Email    string `json:"email" binding:"required,email,max=255"`
+	IsActive bool   `json:"is_active"`
+	IsAdmin  bool   `json:"is_admin"`
+}
+
+// CreateUser 创建用户
+// @Summary 创建用户
+// @Description 创建一个本地密码登录的新用户，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body user.createUserRequest true "创建用户参数"
+// @Success 200 {object} response.Any{data=user.user} "创建成功"
+// @Failure 400 {object} response.Any "参数错误或用户名已存在"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/users [post]
+func CreateUser(c *gin.Context) {
+	var req createUserRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	newUser, err := createUser(c.Request.Context(), req)
+	if abortUserLogicError(c, err, "", nil, []string{usernameRequired, emailRequired, passwordTooShort, usernameExists, emailExists}) {
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(toUser(newUser)))
+}

Wavelet/internal/apps/admin/user/routers_test.go

@@ -0,0 +1,582 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+func setupTestRouter(authUser *model.User) *gin.Engine {
+	r := testhelper.NewTestGinEngine()
+	adminGroup := r.Group("/api/v1/admin")
+
+	// Mock authentication middleware
+	adminGroup.Use(func(c *gin.Context) {
+		if authUser != nil {
+			oauth.SetToContext(c, oauth.UserObjKey, authUser)
+		}
+		c.Next()
+	})
+
+	adminGroup.GET("/users", ListUsers)
+	adminGroup.POST("/users", CreateUser)
+	adminGroup.GET("/users/:id", GetUser)
+	adminGroup.PUT("/users/:id/status", UpdateUserStatus)
+	adminGroup.DELETE("/users/:id", DeleteUser)
+	return r
+}
+
+func TestListUsers(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	// Seed users
+	users := []model.User{
+		{
+			ID:          1001,
+			Username:    "alice",
+			Nickname:    "Alice Nickname",
+			IsActive:    true,
+			IsAdmin:     false,
+			LastLoginAt: time.Now(),
+		},
+		{
+			ID:          1002,
+			Username:    "bob",
+			Nickname:    "Bob Nickname",
+			IsActive:    true,
+			IsAdmin:     false,
+			LastLoginAt: time.Now(),
+		},
+		{
+			ID:          1003,
+			Username:    "charlie",
+			Nickname:    "Charlie Nickname",
+			IsActive:    false,
+			IsAdmin:     true,
+			LastLoginAt: time.Now(),
+		},
+	}
+
+	for _, u := range users {
+		if err := dbConn.Create(&u).Error; err != nil {
+			t.Fatalf("failed to seed user: %v", err)
+		}
+	}
+
+	adminUser := &model.User{ID: 1003, Username: "charlie", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("basic pagination list", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/users?page=1&page_size=2", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var resp response.Any
+		if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("failed to parse response: %v", err)
+		}
+
+		// Parse data map to our structure
+		dataBytes, _ := json.Marshal(resp.Data)
+		var listResp listUsersResponse
+		if err := json.Unmarshal(dataBytes, &listResp); err != nil {
+			t.Fatalf("failed to parse list response: %v", err)
+		}
+
+		if len(listResp.Users) != 2 {
+			t.Errorf("expected 2 users, got %d", len(listResp.Users))
+		}
+		if listResp.Total != 3 {
+			t.Errorf("expected total 3, got %d", listResp.Total)
+		}
+		// Ordered by ID ASC
+		if listResp.Users[0].ID != 1001 || listResp.Users[1].ID != 1002 {
+			t.Errorf("expected ordered ASC, got first ID %d, second ID %d", listResp.Users[0].ID, listResp.Users[1].ID)
+		}
+	})
+
+	t.Run("filter by user_id", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/users?page=1&page_size=10&user_id=1001", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		var resp response.Any
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var listResp listUsersResponse
+		_ = json.Unmarshal(dataBytes, &listResp)
+
+		if len(listResp.Users) != 1 || listResp.Users[0].ID != 1001 {
+			t.Errorf("expected 1 user with ID 1001, got total %d", len(listResp.Users))
+		}
+	})
+
+	t.Run("filter by username prefix", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/users?page=1&page_size=10&username=bo", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		var resp response.Any
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var listResp listUsersResponse
+		_ = json.Unmarshal(dataBytes, &listResp)
+
+		if len(listResp.Users) != 1 || listResp.Users[0].Username != "bob" {
+			t.Errorf("expected bob, got %v", listResp.Users)
+		}
+	})
+
+	t.Run("invalid pagination parameter", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/users?page=0&page_size=10", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request, got %d", w.Code)
+		}
+	})
+}
+
+func TestGetUser(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	targetUser := model.User{
+		ID:        1001,
+		Username:  "alice",
+		Password:  "secret-hash",
+		Nickname:  "Alice Nickname",
+		Email:     "alice@example.com",
+		AvatarURL: "https://example.com/avatar.png",
+		IsActive:  true,
+		IsAdmin:   false,
+		Bio:       "hello",
+		Phone:     "123456",
+		Gender:    "female",
+		Website:   "https://example.com",
+		Location:  "Shanghai",
+	}
+	if err := dbConn.Create(&targetUser).Error; err != nil {
+		t.Fatalf("failed to seed user: %v", err)
+	}
+
+	adminUser := &model.User{ID: 1003, Username: "charlie", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("get full user profile", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/users/1001", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var resp response.Any
+		if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("failed to parse response: %v", err)
+		}
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var resUser user
+		if err := json.Unmarshal(dataBytes, &resUser); err != nil {
+			t.Fatalf("failed to parse response data: %v", err)
+		}
+
+		if resUser.Email != targetUser.Email || resUser.Bio != targetUser.Bio || resUser.Phone != targetUser.Phone ||
+			resUser.Gender != targetUser.Gender || resUser.Website != targetUser.Website || resUser.Location != targetUser.Location {
+			t.Errorf("profile fields were not returned correctly: %+v", resUser)
+		}
+		if bytes.Contains(dataBytes, []byte("secret-hash")) {
+			t.Error("response should not include password")
+		}
+	})
+
+	t.Run("get non-existent user", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/users/9999", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusNotFound {
+			t.Errorf("expected 404 Not Found, got %d. Body: %s", w.Code, w.Body.String())
+		}
+	})
+}
+
+func TestUpdateUserStatus(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	// Seed users
+	regularUser := model.User{
+		ID:       1001,
+		Username: "alice",
+		IsActive: true,
+		IsAdmin:  false,
+	}
+	adminUser := model.User{
+		ID:       1002,
+		Username: "bob",
+		IsActive: true,
+		IsAdmin:  true,
+	}
+
+	dbConn.Create(&regularUser)
+	dbConn.Create(&adminUser)
+
+	router := setupTestRouter(&adminUser)
+
+	t.Run("disable regular user successfully", func(t *testing.T) {
+		payload := updateUserStatusRequest{IsActive: false}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/users/1001/status", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		// Verify DB status
+		var u model.User
+		dbConn.First(&u, 1001)
+		if u.IsActive {
+			t.Error("user should be deactivated in the database")
+		}
+	})
+
+	t.Run("cannot disable admin user", func(t *testing.T) {
+		payload := updateUserStatusRequest{IsActive: false}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/users/1002/status", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusForbidden {
+			t.Errorf("expected 403 Forbidden, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var resp response.Any
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+		if resp.ErrorMsg != cannotDisable {
+			t.Errorf("expected error message '%s', got '%s'", cannotDisable, resp.ErrorMsg)
+		}
+	})
+
+	t.Run("cannot enable/disable non-existent user", func(t *testing.T) {
+		payload := updateUserStatusRequest{IsActive: false}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/users/9999/status", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusNotFound {
+			t.Errorf("expected 404 Not Found, got %d. Body: %s", w.Code, w.Body.String())
+		}
+	})
+}
+
+func TestCreateUser(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1003, Username: "charlie", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("create user successfully", func(t *testing.T) {
+		payload := createUserRequest{
+			Username: "newuser",
+			Password: "newpassword123",
+			Nickname: "New Nickname",
+			Email:    "newuser@example.com",
+			IsActive: true,
+			IsAdmin:  false,
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/users", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var resp response.Any
+		if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("failed to parse response: %v", err)
+		}
+
+		if resp.ErrorMsg != "" {
+			t.Errorf("expected empty error message, got '%s'", resp.ErrorMsg)
+		}
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var resUser user
+		if err := json.Unmarshal(dataBytes, &resUser); err != nil {
+			t.Fatalf("failed to parse response data: %v", err)
+		}
+
+		if resUser.Username != "newuser" || resUser.Nickname != "New Nickname" || !resUser.IsActive || resUser.IsAdmin {
+			t.Errorf("unexpected user values: %+v", resUser)
+		}
+
+		// Verify in DB
+		var dbUser model.User
+		if err := dbConn.Where("username = ?", "newuser").First(&dbUser).Error; err != nil {
+			t.Fatalf("failed to find user in db: %v", err)
+		}
+		if dbUser.Email != "newuser@example.com" {
+			t.Errorf("expected email 'newuser@example.com', got '%s'", dbUser.Email)
+		}
+		if !dbUser.CheckPassword("newpassword123") {
+			t.Error("password was not hashed correctly")
+		}
+	})
+
+	t.Run("create user with duplicate username", func(t *testing.T) {
+		// Create the first user
+		existing := model.User{
+			ID:       2001,
+			Username: "dupuser",
+			Nickname: "Dup User",
+			Email:    "dupuser@example.com",
+		}
+		dbConn.Create(&existing)
+
+		payload := createUserRequest{
+			Username: "dupuser",
+			Password: "password123",
+			Nickname: "Another Nick",
+			Email:    "another@example.com",
+			IsActive: true,
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/users", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var resp response.Any
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+		if resp.ErrorMsg != usernameExists {
+			t.Errorf("expected error '%s', got '%s'", usernameExists, resp.ErrorMsg)
+		}
+	})
+
+	t.Run("create user with duplicate email", func(t *testing.T) {
+		existing := model.User{
+			ID:       2002,
+			Username: "existingemail",
+			Nickname: "Existing Email",
+			Email:    "dupemail@example.com",
+		}
+		dbConn.Create(&existing)
+
+		payload := createUserRequest{
+			Username: "newuser2",
+			Password: "password123",
+			Nickname: "New User 2",
+			Email:    "dupemail@example.com",
+			IsActive: true,
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/users", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var resp response.Any
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+		if resp.ErrorMsg != emailExists {
+			t.Errorf("expected error '%s', got '%s'", emailExists, resp.ErrorMsg)
+		}
+	})
+
+	t.Run("validation error - password too short", func(t *testing.T) {
+		payload := createUserRequest{
+			Username: "shortpass",
+			Password: "123",
+			Email:    "shortpass@example.com",
+			IsActive: true,
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/users", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request, got %d. Body: %s", w.Code, w.Body.String())
+		}
+	})
+
+	t.Run("validation error - invalid email format", func(t *testing.T) {
+		payload := map[string]interface{}{
+			"username":  "bademail",
+			"password":  "password123",
+			"email":     "not-an-email",
+			"is_active": true,
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/users", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request, got %d. Body: %s", w.Code, w.Body.String())
+		}
+	})
+}
+
+func TestDeleteUser(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	if err := dbConn.AutoMigrate(&model.AccessToken{}, &model.ExternalAccount{}); err != nil {
+		t.Fatalf("failed to migrate delete-related tables: %v", err)
+	}
+
+	regularUser := model.User{
+		ID:       1001,
+		Username: "alice",
+		IsActive: true,
+		IsAdmin:  false,
+	}
+	adminUser := model.User{
+		ID:       1002,
+		Username: "bob",
+		IsActive: true,
+		IsAdmin:  true,
+	}
+	selfUser := model.User{
+		ID:       1003,
+		Username: "charlie",
+		IsActive: true,
+		IsAdmin:  false,
+	}
+
+	if err := dbConn.Create(&regularUser).Error; err != nil {
+		t.Fatalf("failed to seed regular user: %v", err)
+	}
+	if err := dbConn.Create(&adminUser).Error; err != nil {
+		t.Fatalf("failed to seed admin user: %v", err)
+	}
+	if err := dbConn.Create(&selfUser).Error; err != nil {
+		t.Fatalf("failed to seed self user: %v", err)
+	}
+	if err := dbConn.Create(&model.AccessToken{
+		UserID:      regularUser.ID,
+		Name:        "api",
+		TokenHash:   "hash-for-delete-user-test",
+		MaskedToken: "at_****test",
+	}).Error; err != nil {
+		t.Fatalf("failed to seed access token: %v", err)
+	}
+	if err := dbConn.Create(&model.ExternalAccount{
+		ID:           5001,
+		AuthSourceID: 1,
+		UserID:       regularUser.ID,
+		ExternalID:   "external-alice",
+	}).Error; err != nil {
+		t.Fatalf("failed to seed external account: %v", err)
+	}
+
+	router := setupTestRouter(&selfUser)
+
+	t.Run("delete regular user successfully", func(t *testing.T) {
+		req, _ := http.NewRequest("DELETE", "/api/v1/admin/users/1001", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var count int64
+		if err := dbConn.Model(&model.User{}).Where("id = ?", 1001).Count(&count).Error; err != nil {
+			t.Fatalf("failed to count deleted user: %v", err)
+		}
+		if count != 0 {
+			t.Errorf("expected deleted user count 0, got %d", count)
+		}
+
+		if err := dbConn.Model(&model.AccessToken{}).Where("user_id = ?", 1001).Count(&count).Error; err != nil {
+			t.Fatalf("failed to count deleted access tokens: %v", err)
+		}
+		if count != 0 {
+			t.Errorf("expected deleted access token count 0, got %d", count)
+		}
+
+		if err := dbConn.Model(&model.ExternalAccount{}).Where("user_id = ?", 1001).Count(&count).Error; err != nil {
+			t.Fatalf("failed to count deleted external accounts: %v", err)
+		}
+		if count != 0 {
+			t.Errorf("expected deleted external account count 0, got %d", count)
+		}
+	})
+
+	t.Run("cannot delete admin user", func(t *testing.T) {
+		req, _ := http.NewRequest("DELETE", "/api/v1/admin/users/1002", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusForbidden {
+			t.Fatalf("expected 403 Forbidden, got %d. Body: %s", w.Code, w.Body.String())
+		}
+	})
+
+	t.Run("cannot delete current user", func(t *testing.T) {
+		req, _ := http.NewRequest("DELETE", "/api/v1/admin/users/1003", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusForbidden {
+			t.Fatalf("expected 403 Forbidden, got %d. Body: %s", w.Code, w.Body.String())
+		}
+	})
+
+	t.Run("delete non-existent user", func(t *testing.T) {
+		req, _ := http.NewRequest("DELETE", "/api/v1/admin/users/9999", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusNotFound {
+			t.Errorf("expected 404 Not Found, got %d. Body: %s", w.Code, w.Body.String())
+		}
+	})
+}

Wavelet/internal/apps/cap/errs.go

@@ -0,0 +1,10 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package cap 提供人机验证中间件
+package cap
+
+const (
+	errCapTokenMissing          = "验证码验证失败，缺少验证码凭证" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errCapTokenInvalidOrExpired = "验证码校验失败或已过期，请重试" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+)

Wavelet/internal/apps/cap/manager.go

@@ -0,0 +1,196 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package cap provides CAPTCHA and proof-of-work (PoW) verification services.
+package cap
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/config"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	pkgcap "github.com/Rain-kl/Wavelet/pkg/cap"
+)
+
+const (
+	redeemTokenIDLength  = 8  // 兑换 Token ID 字节长度
+	redeemVerTokenLength = 15 // 兑换验证 Token 字节长度
+	tokenPartsCount      = 2  // 兑换 Token 由两部分组成
+	valuePartsCount      = 2  // 存储值由 scope 和过期时间组成
+)
+
+// Manager orchestrates challenge generation and solution validation.
+type Manager struct {
+	secret []byte
+	store  pkgcap.Store
+}
+
+// NewManager creates a new CAPTCHA Manager.
+func NewManager(secret []byte, store pkgcap.Store) *Manager {
+	return &Manager{
+		secret: secret,
+		store:  store,
+	}
+}
+
+// Generate creates a challenge response.
+func (m *Manager) Generate(ctx context.Context, scope string) (*pkgcap.ChallengeResponse, error) {
+	settings, err := CurrentSettings(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	challengeConfig := pkgcap.ChallengeConfig{
+		Count:      settings.ChallengeCount,
+		Size:       settings.ChallengeSize,
+		Difficulty: settings.ChallengeDifficulty,
+		Expires:    settings.ChallengeTTL,
+	}
+	return pkgcap.GenerateChallenge(m.secret, challengeConfig, scope)
+}
+
+// RedeemResponse is returned to the client on redeem.
+type RedeemResponse struct {
+	Success bool   `json:"success"`
+	Token   string `json:"token,omitempty"`
+	Expires int64  `json:"expires,omitempty"`
+	Error   string `json:"error,omitempty"`
+}
+
+// Redeem verifies PoW solutions and returns a one-time redeem token.
+func (m *Manager) Redeem(ctx context.Context, token string, solutions []int, scope string) (*RedeemResponse, error) {
+	sigHex := pkgcap.JwtSigHex(token)
+	if sigHex == "" {
+		return &RedeemResponse{Success: false, Error: "invalid_token"}, nil
+	}
+
+	nonceKey := "cap:nonce:" + sigHex
+
+	payload, err := pkgcap.VerifyChallengeSolutions(token, solutions, m.secret, scope)
+	if err != nil {
+		return &RedeemResponse{Success: false, Error: err.Error()}, nil //nolint:nilerr // validation errors are returned as response, not system errors
+	}
+
+	now := time.Now().UnixNano() / int64(time.Millisecond)
+	nonceTTL := time.Duration(payload.Expires-now) * time.Millisecond
+	if nonceTTL < time.Second {
+		nonceTTL = time.Second
+	}
+
+	set, err := m.store.SetNX(ctx, nonceKey, "1", nonceTTL)
+	if err != nil {
+		return &RedeemResponse{Success: false, Error: "nonce_store_error"}, err
+	}
+	if !set {
+		return &RedeemResponse{Success: false, Error: "already_redeemed"}, nil
+	}
+
+	settings, err := CurrentSettings(ctx)
+	if err != nil {
+		return &RedeemResponse{Success: false, Error: "settings_load_error"}, err
+	}
+
+	id := pkgcap.RandomHex(redeemTokenIDLength)
+	verToken := pkgcap.RandomHex(redeemVerTokenLength)
+	verHashBytes := sha256.Sum256([]byte(verToken))
+	verHashHex := hex.EncodeToString(verHashBytes[:])
+
+	tokenKey := "cap:token:" + id + ":" + verHashHex
+	tokenExpires := time.Now().Add(settings.TokenTTL)
+	storeVal := strconv.FormatInt(tokenExpires.UnixNano(), 10) + "|" + scope
+
+	if err := m.store.Set(ctx, tokenKey, storeVal, settings.TokenTTL); err != nil {
+		return &RedeemResponse{Success: false, Error: "token_store_error"}, err
+	}
+
+	return &RedeemResponse{
+		Success: true,
+		Token:   id + ":" + verToken,
+		Expires: tokenExpires.UnixNano() / int64(time.Millisecond),
+	}, nil
+}
+
+// VerifyToken validates and consumes the redeem token (single-use).
+func (m *Manager) VerifyToken(ctx context.Context, token string, expectedScope string) (bool, error) {
+	if token == "" {
+		return false, nil
+	}
+	parts := strings.Split(token, ":")
+	if len(parts) != tokenPartsCount {
+		return false, nil
+	}
+	id := parts[0]
+	verToken := parts[1]
+
+	verHashBytes := sha256.Sum256([]byte(verToken))
+	verHashHex := hex.EncodeToString(verHashBytes[:])
+
+	tokenKey := "cap:token:" + id + ":" + verHashHex
+
+	val, exists, err := sGetAndDelete(ctx, m.store, tokenKey)
+	if err != nil {
+		return false, err
+	}
+	if !exists {
+		return false, nil
+	}
+
+	valParts := strings.Split(val, "|")
+	if len(valParts) != valuePartsCount {
+		return false, nil
+	}
+
+	expNano, err := strconv.ParseInt(valParts[0], 10, 64)
+	if err != nil {
+		return false, nil //nolint:nilerr // invalid format is treated as validation failure
+	}
+	tokenScope := valParts[1]
+
+	if expectedScope != "" && tokenScope != expectedScope {
+		return false, nil
+	}
+
+	if time.Now().UnixNano() > expNano {
+		return false, nil
+	}
+
+	return true, nil
+}
+
+func sGetAndDelete(ctx context.Context, store pkgcap.Store, key string) (string, bool, error) {
+	if store == nil {
+		return "", false, nil
+	}
+	return store.GetAndDelete(ctx, key)
+}
+
+var (
+	defaultManager *Manager
+	once           sync.Once
+)
+
+// GetDefaultManager yields the global singleton CAPTCHA manager.
+func GetDefaultManager() *Manager {
+	once.Do(func() {
+		secret := []byte("default-captcha-secret-key-at-least-16-bytes")
+		if config.Config != nil && config.Config.App.SessionSecret != "" {
+			secret = []byte(config.Config.App.SessionSecret)
+		}
+
+		var store pkgcap.Store
+		if config.Config != nil && config.Config.Redis.Enabled && db.Redis != nil {
+			store = pkgcap.NewRedisStore(db.Redis)
+		} else {
+			store = pkgcap.NewMemoryStore(1 * time.Minute)
+		}
+
+		defaultManager = NewManager(secret, store)
+	})
+	return defaultManager
+}

Wavelet/internal/apps/cap/manager_test.go

@@ -0,0 +1,162 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+import (
+	"context"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	pkgcap "github.com/Rain-kl/Wavelet/pkg/cap"
+)
+
+func installTestManagerSettings(t *testing.T) func() {
+	t.Helper()
+	return InstallTestRuntimeSettings(RuntimeSettings{
+		ChallengeCount:      3,
+		ChallengeSize:       32,
+		ChallengeDifficulty: 3,
+		ChallengeTTL:        5 * time.Second,
+		TokenTTL:            10 * time.Second,
+	})
+}
+
+func TestCapFullFlow(t *testing.T) {
+	cleanup := installTestManagerSettings(t)
+	defer cleanup()
+
+	secret := []byte("a-very-long-secret-key-at-least-16-bytes")
+	store := pkgcap.NewMemoryStore(1 * time.Minute)
+	manager := NewManager(secret, store)
+
+	scope := "test-scope"
+	ctx := context.Background()
+	resp, err := manager.Generate(ctx, scope)
+	if err != nil {
+		t.Fatalf("Generate() error = %v", err)
+	}
+
+	if resp.Challenge.C != 3 {
+		t.Fatalf("Generate().Challenge.C = %d, want %d", resp.Challenge.C, 3)
+	}
+
+	solutions := pkgcap.Solve(resp.Token, resp.Challenge.C, resp.Challenge.S, resp.Challenge.D)
+
+	redeemResp, err := manager.Redeem(ctx, resp.Token, solutions, scope)
+	if err != nil {
+		t.Fatalf("Redeem() error = %v", err)
+	}
+	if !redeemResp.Success {
+		t.Fatalf("Redeem().Success = false, error = %s", redeemResp.Error)
+	}
+	if redeemResp.Token == "" {
+		t.Fatal("Redeem().Token is empty")
+	}
+
+	valid, err := manager.VerifyToken(ctx, redeemResp.Token, scope)
+	if err != nil {
+		t.Fatalf("VerifyToken() error = %v", err)
+	}
+	if !valid {
+		t.Fatal("VerifyToken() = false, want true")
+	}
+
+	validAgain, err := manager.VerifyToken(ctx, redeemResp.Token, scope)
+	if err != nil {
+		t.Fatalf("VerifyToken() second call error = %v", err)
+	}
+	if validAgain {
+		t.Fatal("VerifyToken() second call = true, want false")
+	}
+}
+
+func TestRedeemConcurrentRace(t *testing.T) {
+	const goroutines = 50
+
+	cleanup := installTestManagerSettings(t)
+	defer cleanup()
+
+	secret := []byte("race-test-secret-key-at-least-16-bytes")
+	store := pkgcap.NewMemoryStore(1 * time.Minute)
+	manager := NewManager(secret, store)
+
+	ctx := context.Background()
+	resp, err := manager.Generate(ctx, "login")
+	if err != nil {
+		t.Fatalf("Generate() error = %v", err)
+	}
+	solutions := pkgcap.Solve(resp.Token, resp.Challenge.C, resp.Challenge.S, resp.Challenge.D)
+
+	var (
+		wg      sync.WaitGroup
+		success atomic.Int32
+		barrier = make(chan struct{})
+	)
+
+	for range goroutines {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			<-barrier
+			r, _ := manager.Redeem(ctx, resp.Token, solutions, "login")
+			if r != nil && r.Success {
+				success.Add(1)
+			}
+		}()
+	}
+	close(barrier)
+	wg.Wait()
+
+	if got := success.Load(); got != 1 {
+		t.Fatalf("successful Redeem count = %d, want %d", got, 1)
+	}
+}
+
+func TestVerifyTokenConcurrentRace(t *testing.T) {
+	const goroutines = 50
+
+	cleanup := installTestManagerSettings(t)
+	defer cleanup()
+
+	secret := []byte("race-test-secret-key-at-least-16-bytes")
+	store := pkgcap.NewMemoryStore(1 * time.Minute)
+	manager := NewManager(secret, store)
+
+	ctx := context.Background()
+	resp, err := manager.Generate(ctx, "login")
+	if err != nil {
+		t.Fatalf("Generate() error = %v", err)
+	}
+	solutions := pkgcap.Solve(resp.Token, resp.Challenge.C, resp.Challenge.S, resp.Challenge.D)
+	redeemResp, err := manager.Redeem(ctx, resp.Token, solutions, "login")
+	if err != nil || !redeemResp.Success {
+		t.Fatalf("Redeem() error = %v, resp = %+v", err, redeemResp)
+	}
+
+	var (
+		wg      sync.WaitGroup
+		success atomic.Int32
+		barrier = make(chan struct{})
+	)
+
+	for range goroutines {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			<-barrier
+			ok, _ := manager.VerifyToken(ctx, redeemResp.Token, "login")
+			if ok {
+				success.Add(1)
+			}
+		}()
+	}
+	close(barrier)
+	wg.Wait()
+
+	if got := success.Load(); got != 1 {
+		t.Fatalf("successful VerifyToken count = %d, want %d", got, 1)
+	}
+}

Wavelet/internal/apps/cap/middleware.go

@@ -0,0 +1,34 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+import (
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+// VerifyMiddleware returns a Gin middleware that checks and consumes the X-Cap-Token header.
+func VerifyMiddleware(mgr *Manager, scope string) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if !ProtectionEnabled(c.Request.Context()) {
+			c.Next()
+			return
+		}
+
+		token := c.GetHeader("X-Cap-Token")
+		if token == "" {
+			response.AbortUnauthorized(c, errCapTokenMissing)
+			return
+		}
+
+		valid, err := mgr.VerifyToken(c.Request.Context(), token, scope)
+		if err != nil || !valid {
+			response.AbortUnauthorized(c, errCapTokenInvalidOrExpired)
+			return
+		}
+
+		c.Next()
+	}
+}

Wavelet/internal/apps/cap/routers.go

@@ -0,0 +1,94 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+type challengeRequest struct {
+	Scope string `json:"scope" form:"scope"`
+}
+
+type redeemRequest struct {
+	Token     string `json:"token" binding:"required"`
+	Solutions []int  `json:"solutions" binding:"required"`
+	Scope     string `json:"scope" form:"scope"`
+}
+
+// Challenge 生成 PoW 人机验证难题
+// @Summary 生成人机验证难题
+// @Description 客户端获取 PoW 难题和签名的 JWT Token，并在后台计算。
+// @Tags cap
+// @Accept json
+// @Produce json
+// @Param request body challengeRequest false "可选范围限制参数"
+// @Success 200 {object} cap.ChallengeResponse "成功返回 PoW 难题"
+// @Failure 500 {object} RedeemResponse "内部服务错误"
+// @Router /api/cap/challenge [post]
+func Challenge(c *gin.Context) {
+	var req challengeRequest
+	_ = c.ShouldBind(&req) // 允许不传 body，默认使用 login scope
+
+	if req.Scope == "" {
+		req.Scope = "login"
+	}
+
+	mgr := GetDefaultManager()
+	resp, err := mgr.Generate(c.Request.Context(), req.Scope)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, RedeemResponse{
+			Success: false,
+			Error:   err.Error(),
+		})
+		return
+	}
+
+	c.JSON(http.StatusOK, resp)
+}
+
+// Redeem 提交 PoW 解答并兑换一次性凭证 Token
+// @Summary 校验人机验证解答
+// @Description 提交 PoW 解答进行核销，成功后返回一次性 X-Cap-Token 凭证
+// @Tags cap
+// @Accept json
+// @Produce json
+// @Param request body redeemRequest true "难题 Token 与解答 solutions 数组"
+// @Success 200 {object} RedeemResponse "核销成功，返回 X-Cap-Token"
+// @Failure 400 {object} RedeemResponse "参数错误或核销失败"
+// @Failure 500 {object} RedeemResponse "内部服务错误"
+// @Router /api/cap/redeem [post]
+func Redeem(c *gin.Context) {
+	var req redeemRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, RedeemResponse{
+			Success: false,
+			Error:   "无效的参数",
+		})
+		return
+	}
+
+	if req.Scope == "" {
+		req.Scope = "login"
+	}
+
+	mgr := GetDefaultManager()
+	resp, err := mgr.Redeem(c.Request.Context(), req.Token, req.Solutions, req.Scope)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, RedeemResponse{
+			Success: false,
+			Error:   err.Error(),
+		})
+		return
+	}
+
+	if !resp.Success {
+		c.JSON(http.StatusBadRequest, resp)
+		return
+	}
+
+	c.JSON(http.StatusOK, resp)
+}

Wavelet/internal/apps/cap/routers_test.go

@@ -0,0 +1,128 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+	pkgcap "github.com/Rain-kl/Wavelet/pkg/cap"
+)
+
+func TestCapEndpointsAndMiddleware(t *testing.T) {
+	sqliteDB, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	r := testhelper.NewTestGinEngine()
+
+	// Mount CAPTCHA API endpoints
+	capGroup := r.Group("/api/cap")
+	{
+		capGroup.POST("/challenge", Challenge)
+		capGroup.POST("/redeem", Redeem)
+	}
+
+	r.POST("/api/v1/user/login", VerifyMiddleware(GetDefaultManager(), "login"), func(c *gin.Context) {
+		c.JSON(http.StatusOK, response.OK("login success"))
+	})
+
+	// 1. Test challenge generation
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest("POST", "/api/cap/challenge", nil)
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	var challengeResp pkgcap.ChallengeResponse
+	if err := json.Unmarshal(w.Body.Bytes(), &challengeResp); err != nil {
+		t.Fatalf("failed to unmarshal challenge response: %v", err)
+	}
+
+	if challengeResp.Token == "" {
+		t.Fatalf("expected token in challenge response")
+	}
+
+	// 2. Test login with CAPTCHA disabled (should pass)
+	w = httptest.NewRecorder()
+	req, _ = http.NewRequest("POST", "/api/v1/user/login", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200 OK when CAPTCHA is disabled, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	// 3. Enable CAPTCHA in DB and invalidate runtime snapshot
+	err := sqliteDB.Model(&model.SystemConfig{}).Where("key = ?", model.ConfigKeyCapLoginEnabled).Update("value", "true").Error
+	if err != nil {
+		t.Fatalf("failed to enable cap_login_enabled in DB: %v", err)
+	}
+	if err := repository.InvalidateSystemConfigCache(context.Background(), model.ConfigKeyCapLoginEnabled); err != nil {
+		t.Fatalf("InvalidateSystemConfigCache() error = %v", err)
+	}
+	InvalidateRuntimeSettings()
+
+	// 4. Test login with CAPTCHA enabled but no header (should be blocked)
+	w = httptest.NewRecorder()
+	req, _ = http.NewRequest("POST", "/api/v1/user/login", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusUnauthorized {
+		t.Fatalf("expected 401 Unauthorized, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	// 5. Solve the challenge
+	solutions := pkgcap.Solve(challengeResp.Token, challengeResp.Challenge.C, challengeResp.Challenge.S, challengeResp.Challenge.D)
+
+	// 6. Redeem solutions
+	redeemReqPayload := redeemRequest{
+		Token:     challengeResp.Token,
+		Solutions: solutions,
+	}
+	bodyBytes, _ := json.Marshal(redeemReqPayload)
+	w = httptest.NewRecorder()
+	req, _ = http.NewRequest("POST", "/api/cap/redeem", bytes.NewBuffer(bodyBytes))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200 OK for redeem, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	var redeemResp RedeemResponse
+	if err := json.Unmarshal(w.Body.Bytes(), &redeemResp); err != nil {
+		t.Fatalf("failed to unmarshal redeem response: %v", err)
+	}
+
+	if !redeemResp.Success || redeemResp.Token == "" {
+		t.Fatalf("redeem failed or returned empty token: %+v", redeemResp)
+	}
+
+	// 7. Login with valid redeem token (should pass)
+	w = httptest.NewRecorder()
+	req, _ = http.NewRequest("POST", "/api/v1/user/login", nil)
+	req.Header.Set("X-Cap-Token", redeemResp.Token)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200 OK with valid cap token, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	// 8. Replay attack: Login with the same redeem token again (should be blocked as it is single-use)
+	w = httptest.NewRecorder()
+	req, _ = http.NewRequest("POST", "/api/v1/user/login", nil)
+	req.Header.Set("X-Cap-Token", redeemResp.Token)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusUnauthorized {
+		t.Fatalf("expected 401 Unauthorized on replayed token, got %d. Body: %s", w.Code, w.Body.String())
+	}
+}

Wavelet/internal/apps/cap/runtime_settings.go

@@ -0,0 +1,212 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strconv"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"golang.org/x/sync/singleflight"
+
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+)
+
+const (
+	defaultChallengeCount      = 1
+	defaultChallengeSize       = 32
+	defaultChallengeDifficulty = 4
+	defaultChallengeTTL        = 10 * time.Minute
+	defaultTokenTTL            = 20 * time.Minute
+)
+
+// RuntimeSettings is the parsed CAPTCHA runtime configuration loaded from system_configs.
+type RuntimeSettings struct {
+	LoginEnabled        bool
+	ChallengeCount      int
+	ChallengeSize       int
+	ChallengeDifficulty int
+	ChallengeTTL        time.Duration
+	TokenTTL            time.Duration
+}
+
+var runtimeConfigKeys = []string{
+	model.ConfigKeyCapLoginEnabled,
+	model.ConfigKeyCapChallengeCount,
+	model.ConfigKeyCapChallengeSize,
+	model.ConfigKeyCapChallengeDifficulty,
+	model.ConfigKeyCapChallengeTTL,
+	model.ConfigKeyCapTokenTTL,
+}
+
+var runtimeConfigKeySet = func() map[string]struct{} {
+	set := make(map[string]struct{}, len(runtimeConfigKeys))
+	for _, key := range runtimeConfigKeys {
+		set[key] = struct{}{}
+	}
+	return set
+}()
+
+type runtimeSettingsStore struct {
+	snapshot     atomic.Pointer[RuntimeSettings]
+	loadGroup    singleflight.Group
+	listenerOnce sync.Once
+}
+
+var settingsStore = &runtimeSettingsStore{}
+
+// IsRuntimeConfigKey reports whether a system config key affects CAPTCHA runtime settings.
+func IsRuntimeConfigKey(key string) bool {
+	_, ok := runtimeConfigKeySet[key]
+	return ok
+}
+
+// CurrentSettings returns the cached CAPTCHA runtime settings snapshot.
+func CurrentSettings(ctx context.Context) (RuntimeSettings, error) {
+	return settingsStore.current(ctx)
+}
+
+// ProtectionEnabled reports whether CAPTCHA verification is required for protected routes.
+func ProtectionEnabled(ctx context.Context) bool {
+	settings, err := CurrentSettings(ctx)
+	if err != nil {
+		return false
+	}
+	return settings.LoginEnabled
+}
+
+// InvalidateRuntimeSettings drops the in-process CAPTCHA settings snapshot.
+func InvalidateRuntimeSettings() {
+	settingsStore.snapshot.Store(nil)
+}
+
+// ResetRuntimeSettingsForTest clears the CAPTCHA runtime snapshot.
+func ResetRuntimeSettingsForTest() {
+	InvalidateRuntimeSettings()
+}
+
+// InstallTestRuntimeSettings installs a fixed snapshot for unit tests.
+func InstallTestRuntimeSettings(settings RuntimeSettings) func() {
+	snapshot := settings
+	settingsStore.snapshot.Store(&snapshot)
+	return InvalidateRuntimeSettings
+}
+
+func (s *runtimeSettingsStore) current(ctx context.Context) (RuntimeSettings, error) {
+	s.ensureInvalidationListener()
+
+	if snapshot := s.snapshot.Load(); snapshot != nil {
+		return *snapshot, nil
+	}
+
+	loaded, err, _ := s.loadGroup.Do("cap-runtime-settings", func() (any, error) {
+		if snapshot := s.snapshot.Load(); snapshot != nil {
+			return *snapshot, nil
+		}
+
+		settings, loadErr := loadRuntimeSettings(ctx)
+		if loadErr != nil {
+			return RuntimeSettings{}, loadErr
+		}
+
+		s.snapshot.Store(&settings)
+		return settings, nil
+	})
+	if err != nil {
+		return RuntimeSettings{}, err
+	}
+
+	settings, ok := loaded.(RuntimeSettings)
+	if !ok {
+		return RuntimeSettings{}, errors.New("cap runtime settings loader returned unexpected type")
+	}
+	return settings, nil
+}
+
+func loadRuntimeSettings(ctx context.Context) (RuntimeSettings, error) {
+	configs, err := repository.ListSystemConfigsByKeys(ctx, runtimeConfigKeys)
+	if err != nil {
+		return RuntimeSettings{}, err
+	}
+	return parseRuntimeSettings(configs), nil
+}
+
+func parseRuntimeSettings(configs map[string]model.SystemConfig) RuntimeSettings {
+	settings := RuntimeSettings{
+		ChallengeCount:      defaultChallengeCount,
+		ChallengeSize:       defaultChallengeSize,
+		ChallengeDifficulty: defaultChallengeDifficulty,
+		ChallengeTTL:        defaultChallengeTTL,
+		TokenTTL:            defaultTokenTTL,
+	}
+
+	if sc, ok := configs[model.ConfigKeyCapLoginEnabled]; ok {
+		if enabled, err := strconv.ParseBool(sc.Value); err == nil {
+			settings.LoginEnabled = enabled
+		}
+	}
+	if sc, ok := configs[model.ConfigKeyCapChallengeCount]; ok {
+		if count, err := strconv.Atoi(sc.Value); err == nil && count > 0 {
+			settings.ChallengeCount = count
+		}
+	}
+	if sc, ok := configs[model.ConfigKeyCapChallengeSize]; ok {
+		if size, err := strconv.Atoi(sc.Value); err == nil && size > 0 {
+			settings.ChallengeSize = size
+		}
+	}
+	if sc, ok := configs[model.ConfigKeyCapChallengeDifficulty]; ok {
+		if difficulty, err := strconv.Atoi(sc.Value); err == nil && difficulty > 0 {
+			settings.ChallengeDifficulty = difficulty
+		}
+	}
+	if sc, ok := configs[model.ConfigKeyCapChallengeTTL]; ok {
+		if ttlSeconds, err := strconv.Atoi(sc.Value); err == nil && ttlSeconds > 0 {
+			settings.ChallengeTTL = time.Duration(ttlSeconds) * time.Second
+		}
+	}
+	if sc, ok := configs[model.ConfigKeyCapTokenTTL]; ok {
+		if ttlSeconds, err := strconv.Atoi(sc.Value); err == nil && ttlSeconds > 0 {
+			settings.TokenTTL = time.Duration(ttlSeconds) * time.Second
+		}
+	}
+
+	return settings
+}
+
+func (s *runtimeSettingsStore) ensureInvalidationListener() {
+	s.listenerOnce.Do(startRuntimeSettingsInvalidationListener)
+}
+
+func startRuntimeSettingsInvalidationListener() {
+	if db.Redis == nil {
+		return
+	}
+
+	go func() {
+		pubsub := db.Redis.Subscribe(context.Background(), repository.SystemConfigInvalidationChannel)
+		defer func() {
+			_ = pubsub.Close()
+		}()
+
+		for msg := range pubsub.Channel() {
+			var payload struct {
+				Key string `json:"key"`
+			}
+			if err := json.Unmarshal([]byte(msg.Payload), &payload); err != nil {
+				InvalidateRuntimeSettings()
+				continue
+			}
+			if payload.Key == "" || payload.Key == "*" || IsRuntimeConfigKey(payload.Key) {
+				InvalidateRuntimeSettings()
+			}
+		}
+	}()
+}

Wavelet/internal/apps/cap/runtime_settings_test.go

@@ -0,0 +1,119 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+)
+
+func TestCurrentSettingsLoadsSnapshotOnce(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	ResetRuntimeSettingsForTest()
+	repository.ResetSystemConfigRAMCacheForTest()
+
+	first, err := CurrentSettings(ctx)
+	if err != nil {
+		t.Fatalf("CurrentSettings() first error = %v", err)
+	}
+	if first.ChallengeCount != 1 {
+		t.Fatalf("CurrentSettings().ChallengeCount = %d, want %d", first.ChallengeCount, 1)
+	}
+
+	if err := db.DB(ctx).Model(&model.SystemConfig{}).
+		Where("key = ?", model.ConfigKeyCapChallengeCount).
+		Update("value", "4").Error; err != nil {
+		t.Fatalf("Update(cap_challenge_count) error = %v", err)
+	}
+	if err := repository.InvalidateSystemConfigCache(ctx, model.ConfigKeyCapChallengeCount); err != nil {
+		t.Fatalf("InvalidateSystemConfigCache() error = %v", err)
+	}
+	InvalidateRuntimeSettings()
+
+	second, err := CurrentSettings(ctx)
+	if err != nil {
+		t.Fatalf("CurrentSettings() second error = %v", err)
+	}
+	if second.ChallengeCount != 4 {
+		t.Fatalf("CurrentSettings().ChallengeCount = %d, want %d", second.ChallengeCount, 4)
+	}
+}
+
+func TestProtectionEnabledReflectsLoginSwitch(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	ResetRuntimeSettingsForTest()
+
+	if ProtectionEnabled(ctx) {
+		t.Fatal("ProtectionEnabled() = true, want false from seed defaults")
+	}
+
+	if err := db.DB(ctx).Model(&model.SystemConfig{}).
+		Where("key = ?", model.ConfigKeyCapLoginEnabled).
+		Update("value", "true").Error; err != nil {
+		t.Fatalf("Update(cap_login_enabled) error = %v", err)
+	}
+	if err := repository.InvalidateSystemConfigCache(ctx, model.ConfigKeyCapLoginEnabled); err != nil {
+		t.Fatalf("InvalidateSystemConfigCache() error = %v", err)
+	}
+	InvalidateRuntimeSettings()
+
+	if !ProtectionEnabled(ctx) {
+		t.Fatal("ProtectionEnabled() = false, want true after config update")
+	}
+}
+
+func TestParseRuntimeSettingsUsesDefaultsForMissingKeys(t *testing.T) {
+	settings := parseRuntimeSettings(map[string]model.SystemConfig{})
+
+	if settings.ChallengeCount != defaultChallengeCount {
+		t.Fatalf("ChallengeCount = %d, want %d", settings.ChallengeCount, defaultChallengeCount)
+	}
+	if settings.ChallengeTTL != defaultChallengeTTL {
+		t.Fatalf("ChallengeTTL = %s, want %s", settings.ChallengeTTL, defaultChallengeTTL)
+	}
+	if settings.TokenTTL != defaultTokenTTL {
+		t.Fatalf("TokenTTL = %s, want %s", settings.TokenTTL, defaultTokenTTL)
+	}
+}
+
+func TestIsRuntimeConfigKey(t *testing.T) {
+	if !IsRuntimeConfigKey(model.ConfigKeyCapChallengeCount) {
+		t.Fatalf("IsRuntimeConfigKey(%s) = false, want true", model.ConfigKeyCapChallengeCount)
+	}
+	if IsRuntimeConfigKey(model.ConfigKeySiteName) {
+		t.Fatalf("IsRuntimeConfigKey(%s) = true, want false", model.ConfigKeySiteName)
+	}
+}
+
+func TestInstallTestRuntimeSettings(t *testing.T) {
+	cleanup := InstallTestRuntimeSettings(RuntimeSettings{
+		LoginEnabled:   true,
+		ChallengeCount: 2,
+		TokenTTL:       30 * time.Minute,
+	})
+	defer cleanup()
+
+	settings, err := CurrentSettings(context.Background())
+	if err != nil {
+		t.Fatalf("CurrentSettings() error = %v", err)
+	}
+	if !settings.LoginEnabled {
+		t.Fatal("LoginEnabled = false, want true")
+	}
+	if settings.ChallengeCount != 2 {
+		t.Fatalf("ChallengeCount = %d, want %d", settings.ChallengeCount, 2)
+	}
+}

Wavelet/internal/apps/cap/testhelper_hook.go

@@ -0,0 +1,10 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+import "github.com/Rain-kl/Wavelet/internal/testhelper"
+
+func init() {
+	testhelper.RegisterCleanup(ResetRuntimeSettingsForTest)
+}

Wavelet/internal/apps/config/public_config_cache_test.go

@@ -0,0 +1,76 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package config
+
+import (
+	"context"
+	"testing"
+
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+)
+
+func TestListVisibleSystemConfigsUsesRedisCache(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	if err := repository.InvalidateVisibleSystemConfigsCache(ctx); err != nil {
+		t.Fatalf("InvalidateVisibleSystemConfigsCache() error = %v", err)
+	}
+
+	if _, err := repository.ListVisibleSystemConfigs(ctx); err != nil {
+		t.Fatalf("ListVisibleSystemConfigs() warm cache error = %v", err)
+	}
+
+	if err := dbConn.Create(&model.SystemConfig{
+		Key:         "cache_probe_public_key",
+		Value:       "cache_probe_public_value",
+		Type:        "system",
+		Visibility:  model.ConfigVisibilityVisible,
+		Description: "cache probe",
+	}).Error; err != nil {
+		t.Fatalf("Create(cache_probe_public_key) error = %v", err)
+	}
+
+	cached, err := repository.ListVisibleSystemConfigs(ctx)
+	if err != nil {
+		t.Fatalf("ListVisibleSystemConfigs() cached call error = %v", err)
+	}
+	for _, item := range cached {
+		if item.Key == "cache_probe_public_key" {
+			t.Fatal("cached visible config list should be stale before invalidation")
+		}
+	}
+
+	exists, err := db.Redis.Exists(ctx, db.PrefixedKey(repository.SystemConfigVisibleListRedisKey)).Result()
+	if err != nil {
+		t.Fatalf("Redis.Exists() error = %v", err)
+	}
+	if exists == 0 {
+		t.Fatal("expected visible config list cache key to exist")
+	}
+
+	if err := repository.InvalidateVisibleSystemConfigsCache(ctx); err != nil {
+		t.Fatalf("InvalidateVisibleSystemConfigsCache() error = %v", err)
+	}
+
+	refreshed, err := repository.ListVisibleSystemConfigs(ctx)
+	if err != nil {
+		t.Fatalf("ListVisibleSystemConfigs() refreshed call error = %v", err)
+	}
+
+	var found bool
+	for _, item := range refreshed {
+		if item.Key == "cache_probe_public_key" {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatal("refreshed visible config list should include newly created public config")
+	}
+}

Wavelet/internal/apps/config/routers.go

@@ -0,0 +1,57 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package config 提供公开配置查询接口
+package config
+
+import (
+	"net/http"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+// GetPublicConfig 获取公共配置
+// @Summary 获取公共配置
+// @Description 返回系统配置表中 visibility 为 1 的配置键值集合
+// @Tags config
+// @Accept json
+// @Produce json
+// @Success 200 {object} response.Any
+// @Router /api/v1/config/public [get]
+func GetPublicConfig(c *gin.Context) {
+	ctx := c.Request.Context()
+	configs, err := repository.ListVisibleSystemConfigs(ctx)
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	resp := make(map[string]string, len(configs))
+	for _, config := range configs {
+		resp[config.Key] = config.Value
+	}
+
+	c.JSON(http.StatusOK, response.OK(resp))
+}
+
+// GetRobotsTXT 动态生成 robots.txt
+// @Summary 获取 robots.txt
+// @Description 根据系统配置决定是否允许搜索引擎检索，并返回相应的 robots.txt 文件内容
+// @Tags config
+// @Produce text/plain
+// @Success 200 {string} string "robots.txt 内容"
+// @Router /robots.txt [get]
+func GetRobotsTXT(c *gin.Context) {
+	ctx := c.Request.Context()
+	enabled, err := repository.GetBoolByKey(ctx, model.ConfigKeySearchEngineIndexingEnabled)
+	content := "User-Agent: *\nDisallow: /\n"
+	if err == nil && enabled {
+		content = "User-Agent: *\nAllow: /\n"
+	}
+	c.Data(http.StatusOK, "text/plain; charset=utf-8", []byte(content))
+}

Wavelet/internal/apps/config/routers_test.go

@@ -0,0 +1,70 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package config
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+func TestGetPublicConfigUsesVisibility(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	if err := dbConn.Create(&model.SystemConfig{
+		Key:         "custom_public_key",
+		Value:       "custom_public_value",
+		Type:        "system",
+		Visibility:  model.ConfigVisibilityVisible,
+		Description: "custom public config",
+	}).Error; err != nil {
+		t.Fatalf("Create(custom_public_key) error = %v", err)
+	}
+	if err := dbConn.Model(&model.SystemConfig{}).
+		Where("key = ?", model.ConfigKeySiteName).
+		Update("visibility", model.ConfigVisibilityHidden).Error; err != nil {
+		t.Fatalf("Update(%s.visibility) error = %v", model.ConfigKeySiteName, err)
+	}
+
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	router.GET("/api/v1/config/public", GetPublicConfig)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/config/public", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("GetPublicConfig() status = %d, want %d; body = %s", w.Code, http.StatusOK, w.Body.String())
+	}
+
+	var resp response.Any
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("json.Unmarshal(GetPublicConfig()) error = %v", err)
+	}
+	dataBytes, err := json.Marshal(resp.Data)
+	if err != nil {
+		t.Fatalf("json.Marshal(GetPublicConfig().data) error = %v", err)
+	}
+	var configs map[string]string
+	if err := json.Unmarshal(dataBytes, &configs); err != nil {
+		t.Fatalf("json.Unmarshal(GetPublicConfig().data) error = %v", err)
+	}
+
+	if got := configs["custom_public_key"]; got != "custom_public_value" {
+		t.Errorf("GetPublicConfig()[custom_public_key] = %q, want %q", got, "custom_public_value")
+	}
+	if _, ok := configs[model.ConfigKeySiteName]; ok {
+		t.Errorf("GetPublicConfig()[%s] is present, want hidden", model.ConfigKeySiteName)
+	}
+}

Wavelet/internal/apps/config/system_config_cache_test.go

@@ -0,0 +1,108 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package config
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/redis/go-redis/v9"
+
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+)
+
+func TestSystemConfigRAMCacheServesUntilInvalidated(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	repository.ResetSystemConfigRAMCacheForTest()
+	if err := repository.InvalidateAllSystemConfigCaches(ctx); err != nil {
+		t.Fatalf("InvalidateAllSystemConfigCaches() error = %v", err)
+	}
+
+	warm, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeySiteName)
+	if err != nil {
+		t.Fatalf("GetSystemConfigByKey(site_name) warm error = %v", err)
+	}
+	if warm.Value != "Wavelet" {
+		t.Fatalf("GetSystemConfigByKey(site_name).Value = %q, want %q", warm.Value, "Wavelet")
+	}
+
+	if err := dbConn.Model(&model.SystemConfig{}).
+		Where("key = ?", model.ConfigKeySiteName).
+		Update("value", "ram_probe_value").Error; err != nil {
+		t.Fatalf("Update(site_name) error = %v", err)
+	}
+	if err := db.HDel(ctx, repository.SystemConfigRedisHashKey, model.ConfigKeySiteName); err != nil {
+		t.Fatalf("HDel(site_name) error = %v", err)
+	}
+
+	cached, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeySiteName)
+	if err != nil {
+		t.Fatalf("GetSystemConfigByKey(site_name) cached error = %v", err)
+	}
+	if cached.Value != "Wavelet" {
+		t.Fatalf("GetSystemConfigByKey(site_name).Value = %q, want stale RAM value %q", cached.Value, "Wavelet")
+	}
+
+	if err := repository.InvalidateSystemConfigCache(ctx, model.ConfigKeySiteName); err != nil {
+		t.Fatalf("InvalidateSystemConfigCache(site_name) error = %v", err)
+	}
+
+	refreshed, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeySiteName)
+	if err != nil {
+		t.Fatalf("GetSystemConfigByKey(site_name) refreshed error = %v", err)
+	}
+	if refreshed.Value != "ram_probe_value" {
+		t.Fatalf("GetSystemConfigByKey(site_name).Value = %q, want %q", refreshed.Value, "ram_probe_value")
+	}
+
+	exists, err := db.Redis.HExists(ctx, db.PrefixedKey(repository.SystemConfigRedisHashKey), model.ConfigKeySiteName).Result()
+	if err != nil {
+		t.Fatalf("HExists(site_name) error = %v", err)
+	}
+	if !exists {
+		t.Fatal("expected redis hash field to be repopulated after refresh")
+	}
+}
+
+func TestInvalidateSystemConfigCacheClearsRedisField(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	sc, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeySiteName)
+	if err != nil {
+		t.Fatalf("GetSystemConfigByKey(site_name) error = %v", err)
+	}
+	_ = sc
+
+	if err := repository.InvalidateSystemConfigCache(ctx, model.ConfigKeySiteName); err != nil {
+		t.Fatalf("InvalidateSystemConfigCache(site_name) error = %v", err)
+	}
+
+	_, err = db.Redis.HGet(ctx, db.PrefixedKey(repository.SystemConfigRedisHashKey), model.ConfigKeySiteName).Result()
+	if !errors.Is(err, redis.Nil) {
+		t.Fatalf("HGet(site_name) error = %v, want redis.Nil", err)
+	}
+
+	if err := dbConn.Model(&model.SystemConfig{}).
+		Where("key = ?", model.ConfigKeySiteName).
+		Update("value", "after_invalidate").Error; err != nil {
+		t.Fatalf("Update(site_name) error = %v", err)
+	}
+
+	refreshed, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeySiteName)
+	if err != nil {
+		t.Fatalf("GetSystemConfigByKey(site_name) refreshed error = %v", err)
+	}
+	if refreshed.Value != "after_invalidate" {
+		t.Fatalf("GetSystemConfigByKey(site_name).Value = %q, want %q", refreshed.Value, "after_invalidate")
+	}
+}

Wavelet/internal/apps/custom/routers.go

@@ -0,0 +1,24 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package custom provides custom business handlers
+package custom
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+// Hello is a sample handler for custom business logic
+// @Summary Sample Hello API
+// @Description A sample business API for customization
+// @Tags custom
+// @Produce json
+// @Success 200 {object} response.Any{data=string} "成功"
+// @Router /api/v1/custom/hello [get]
+func Hello(c *gin.Context) {
+	c.JSON(http.StatusOK, response.OK("Hello from custom business module!"))
+}

Wavelet/internal/apps/health/routers.go

@@ -0,0 +1,25 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package health 提供健康检查端点
+package health
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+// Health 健康检查
+// @Summary 健康检查
+// @Description 检查服务是否正常运行，可用于负载均衡存活探测
+// @Tags health
+// @Produce json
+// @Success 200 {object} response.Any{data=string} "服务正常"
+// @Router /api/health [get]
+func Health(c *gin.Context) {
+	c.JSON(http.StatusOK, response.OKNil())
+}

Wavelet/internal/apps/oauth/audit.go

@@ -0,0 +1,36 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package oauth 提供 OAuth/OIDC 认证与会话管理
+package oauth
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"github.com/gin-gonic/gin"
+)
+
+// LogForAudit 将登录鉴权审计日志写入 Logger
+func LogForAudit(ctx context.Context, user *model.User, c *gin.Context) {
+	auditLog := loginRequiredAuditLog{
+		UserID:     user.ID,
+		Username:   user.Username,
+		ClientIP:   c.ClientIP(),
+		Method:     c.Request.Method,
+		Path:       c.Request.URL.Path,
+		RequestURI: c.Request.RequestURI,
+		UserAgent:  c.Request.UserAgent(),
+		Referer:    c.Request.Referer(),
+	}
+	auditJSON, err := json.Marshal(auditLog)
+	if err != nil {
+		logger.ErrorF(ctx, "[LoginRequiredAudit] marshal failed: %v", err)
+		logger.DebugF(ctx, "[LoginRequiredAudit] %s %d %s", c.ClientIP(), user.ID, user.Username)
+	} else {
+		logger.DebugF(ctx, "[LoginRequiredAudit] %s", auditJSON)
+	}
+}

Wavelet/internal/apps/oauth/auth_source_resolver.go

@@ -0,0 +1,118 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package oauth
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/coreos/go-oidc/v3/oidc"
+	"golang.org/x/oauth2"
+)
+
+func isOIDCLoginEnabled(ctx context.Context) bool {
+	enabled, err := repository.GetBoolByKey(ctx, model.ConfigKeyOIDCLoginEnabled)
+	if err != nil {
+		return true
+	}
+	return enabled
+}
+
+func resolveAuthSource(ctx context.Context, sourceName string) (*model.AuthSource, error) {
+	name := strings.TrimSpace(strings.ToLower(sourceName))
+	if name == "" {
+		sources, err := model.GetActiveAuthSources(ctx)
+		if err != nil {
+			return nil, err
+		}
+		if len(sources) == 0 {
+			return nil, errors.New(errNoActiveAuthSource)
+		}
+		return &sources[0], nil
+	}
+	return model.GetAuthSourceByName(ctx, name)
+}
+
+func activeLoginSources(ctx context.Context) []AuthSourceView {
+	enabled, err := repository.GetBoolByKey(ctx, model.ConfigKeyOIDCLoginEnabled)
+	if err == nil && !enabled {
+		return nil
+	}
+
+	dbSources, err := model.GetActiveAuthSources(ctx)
+	if err != nil {
+		return nil
+	}
+	sources := make([]AuthSourceView, 0, len(dbSources))
+	for _, source := range dbSources {
+		sources = append(sources, AuthSourceView{
+			ID:                     source.ID,
+			Name:                   source.Name,
+			Type:                   source.Type,
+			DisplayName:            source.DisplayName,
+			IsActive:               source.IsActive,
+			IconURL:                source.IconURL,
+			ClientSecretConfigured: source.ClientSecretConfigured,
+		})
+	}
+	return sources
+}
+
+func getFrontendLoginRedirectURL(ctx context.Context) (string, error) {
+	sc, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeyServerAddress)
+	if err != nil || strings.TrimSpace(sc.Value) == "" {
+		return "", errors.New(errServerAddressMissing)
+	}
+	return strings.TrimRight(sc.Value, "/") + "/login", nil
+}
+
+func buildOAuthConfig(ctx context.Context, source *model.AuthSource, redirectURL string) (*oauth2.Config, *oidc.IDTokenVerifier, error) {
+	if source == nil {
+		return nil, nil, errors.New(errAuthSourceRequired)
+	}
+
+	if source.OpenIDDiscoveryURL == "" {
+		return nil, nil, errors.New(errDiscoveryURLRequired)
+	}
+
+	// Clean the issuer URL (trim /.well-known/openid-configuration if configured by mistake)
+	issuer := strings.TrimSuffix(strings.TrimSpace(source.OpenIDDiscoveryURL), "/")
+	issuer = strings.TrimSuffix(issuer, "/.well-known/openid-configuration")
+	issuer = strings.TrimSuffix(issuer, "/.well-known/oauth-authorization-server")
+
+	// 使用进程级缓存获取 provider，避免每次调用都向 issuer 发起
+	// /.well-known/openid-configuration HTTP 请求。
+	provider, err := globalOIDCProviderCache.get(ctx, issuer)
+	if err != nil {
+		return nil, nil, err
+	}
+	verifier := provider.Verifier(&oidc.Config{ClientID: source.ClientID})
+	scopes := strings.Fields(source.Scopes)
+	if len(scopes) == 0 {
+		scopes = []string{oidc.ScopeOpenID, "profile", "email"}
+	}
+	if !containsScope(scopes, oidc.ScopeOpenID) {
+		scopes = append([]string{oidc.ScopeOpenID}, scopes...)
+	}
+
+	return &oauth2.Config{
+		ClientID:     source.ClientID,
+		ClientSecret: source.ClientSecret,
+		RedirectURL:  redirectURL,
+		Scopes:       scopes,
+		Endpoint:     provider.Endpoint(),
+	}, verifier, nil
+}
+
+func containsScope(scopes []string, scope string) bool {
+	for _, item := range scopes {
+		if item == scope {
+			return true
+		}
+	}
+	return false
+}

Wavelet/internal/apps/oauth/constants.go

@@ -0,0 +1,56 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package oauth
+
+import (
+	"encoding/json"
+	"time"
+)
+
+// Session 用户信息字段 Key
+const (
+	UserNameKey     = "username"
+	UserIDKey       = "user_id"
+	UserObjKey      = "user_obj"
+	TokenAuthKey    = "token_auth"          // 标记当前请求是否通过 Access Token 鉴权
+	TokenAdminKey   = "token_admin"         // Access Token 本身是否具有管理员权限
+	SessionTokenKey = "oauth_session_token" //nolint:gosec // false positive: this is a session key, not hardcoded credentials
+	PasswordHashKey = "password_hash"
+)
+
+// OAuth State 缓存 Key 格式与过期时间
+const (
+	OAuthStateCacheKeyFormat     = "oauth:state:%s"
+	OAuthStateCacheKeyExpiration = 10 * time.Minute
+)
+
+// OAuth 授权用途常量
+const (
+	OAuthPurposeLogin = "login"
+	OAuthPurposeBind  = "bind"
+)
+
+type oauthStatePayload struct {
+	SourceName  string `json:"source_name"`
+	Purpose     string `json:"purpose"`
+	UserID      uint64 `json:"user_id,omitempty"`
+	SessionHash string `json:"session_hash"`
+}
+
+func encodeOAuthStatePayload(payload oauthStatePayload) (string, error) {
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return "", err
+	}
+	return string(data), nil
+}
+
+func decodeOAuthStatePayload(value string) (oauthStatePayload, error) {
+	var payload oauthStatePayload
+	if err := json.Unmarshal([]byte(value), &payload); err != nil {
+		return oauthStatePayload{}, err
+	}
+	return payload, nil
+}

Wavelet/internal/apps/oauth/errs.go

@@ -0,0 +1,22 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package oauth
+
+// OAuth 认证相关错误消息
+const (
+	errInvalidState                    = "非法登录请求"
+	errIDTokenVerifyFailed             = "ID Token 验证失败" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errIDTokenVerifyFailedFormat       = "%s: %w"
+	errNonceMismatch                   = "nonce 不匹配，可能存在重放攻击"
+	errNoActiveAuthSource              = "未配置可用认证源"
+	errServerAddressMissing            = "服务器地址 (server_address) 未配置或配置为空，请在后台系统设置中配置后再试"
+	errAuthSourceRequired              = "认证源不能为空"
+	errDiscoveryURLRequired            = "OIDC 认证源必须配置 Discovery URL"
+	errUsernameGenerateFailed          = "无法生成可用用户名"
+	errUsernameFromSourceFailed        = "无法从认证源获取用户名"
+	errAuthSourceDisabled              = "认证源未启用"
+	errInvalidExternalAccountBindingID = "绑定记录 ID 无效"
+	ErrTokenAuthNotAllowed             = "该端点不允许使用访问令牌进行身份验证" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+)

Wavelet/internal/apps/oauth/gin_context.go

@@ -0,0 +1,22 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package oauth
+
+import "github.com/gin-gonic/gin"
+
+// GetFromContext 从 Gin 请求上下文获取指定类型的值。
+func GetFromContext[T any](c *gin.Context, key string) (T, bool) {
+	value, exists := c.Get(key)
+	if !exists {
+		var zero T
+		return zero, false
+	}
+	typed, ok := value.(T)
+	return typed, ok
+}
+
+// SetToContext 设置值到 Gin 请求上下文。
+func SetToContext[T any](c *gin.Context, key string, value T) {
+	c.Set(key, value)
+}

Wavelet/internal/apps/oauth/handler_authorize.go

@@ -0,0 +1,173 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package oauth
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/internal/common"
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/coreos/go-oidc/v3/oidc"
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+)
+
+// GetLoginURL 获取登录授权地址
+// @Summary 获取登录授权地址
+// @Description 根据指定认证源生成 OAuth 授权 URL，前端跳转到该 URL 完成 OAuth 登录授权。source 参数为空时使用第一个启用的认证源。
+// @Tags oauth
+// @Produce json
+// @Param source query string false "认证源名称，为空使用第一个启用的认证源"
+// @Success 200 {object} response.Any{data=oauth.OAuthAuthorizeResponse} "授权 URL"
+// @Failure 400 {object} response.Any "认证源不存在或未配置"
+// @Failure 500 {object} response.Any "Redis 异常 or 构造 URL 失败"
+// @Router /api/v1/oauth/login [get]
+func GetLoginURL(c *gin.Context) {
+	ctx := c.Request.Context()
+	if !isOIDCLoginEnabled(ctx) {
+		response.AbortBadRequest(c, errAuthSourceDisabled)
+		return
+	}
+
+	source, err := resolveAuthSource(ctx, c.Query("source"))
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if !source.IsActive {
+		response.AbortBadRequest(c, errAuthSourceDisabled)
+		return
+	}
+
+	session := sessions.Default(c)
+	token, isNew := ensureSessionToken(session)
+	if isNew {
+		if err := session.Save(); err != nil {
+			response.AbortInternal(c, err.Error())
+			return
+		}
+	}
+
+	userID := GetUserIDFromSession(session)
+	sessionHash := hashSessionToken(token)
+
+	state := uuid.NewString()
+	payloadValue, err := encodeOAuthStatePayload(oauthStatePayload{
+		SourceName:  source.Name,
+		Purpose:     OAuthPurposeLogin,
+		UserID:      userID,
+		SessionHash: sessionHash,
+	})
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	if err := db.Redis.Set(c.Request.Context(), db.PrefixedKey(fmt.Sprintf(OAuthStateCacheKeyFormat, state)), payloadValue, OAuthStateCacheKeyExpiration).Err(); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	authorizeURL, err := buildAuthorizeURL(c.Request.Context(), source, state)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(OAuthAuthorizeResponse{AuthorizeURL: authorizeURL}))
+}
+
+func buildAuthorizeURL(ctx context.Context, source *model.AuthSource, state string) (string, error) {
+	redirectURL, err := getFrontendLoginRedirectURL(ctx)
+	if err != nil {
+		return "", err
+	}
+	authConfig, verifier, err := buildOAuthConfig(ctx, source, redirectURL)
+	if err != nil {
+		return "", err
+	}
+	if verifier != nil {
+		return authConfig.AuthCodeURL(state, oidc.Nonce(state)), nil
+	}
+	return authConfig.AuthCodeURL(state), nil
+}
+
+// Authorize 发起指定认证源授权
+// @Summary 发起指定认证源授权
+// @Description 根据指定认证源名称发起 OAuth 授权，支持 purpose 参数用于区分登录和账号绑定场景。认证源必须已启用。
+// @Tags oauth
+// @Produce json
+// @Param source path string true "认证源名称"
+// @Param purpose query string false "授权目的：login（登录）或 bind（绑定账号），默认 login"
+// @Success 200 {object} response.Any{data=oauth.OAuthAuthorizeResponse} "授权 URL"
+// @Failure 400 {object} response.Any "认证源不存在或未启用"
+// @Failure 500 {object} response.Any "Redis 异常或构造 URL 失败"
+// @Router /api/v1/oauth/{source}/authorize [get]
+func Authorize(c *gin.Context) {
+	ctx := c.Request.Context()
+	if !isOIDCLoginEnabled(ctx) {
+		response.AbortBadRequest(c, errAuthSourceDisabled)
+		return
+	}
+
+	source, err := resolveAuthSource(ctx, c.Param("source"))
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if !source.IsActive {
+		response.AbortBadRequest(c, errAuthSourceDisabled)
+		return
+	}
+	purpose := strings.ToLower(strings.TrimSpace(c.Query("purpose")))
+	if purpose != OAuthPurposeBind {
+		purpose = OAuthPurposeLogin
+	}
+
+	session := sessions.Default(c)
+	userID := GetUserIDFromSession(session)
+	if purpose == OAuthPurposeBind && userID == 0 {
+		response.AbortUnauthorized(c, common.UnAuthorized)
+		return
+	}
+
+	token, isNew := ensureSessionToken(session)
+	if isNew {
+		if err := session.Save(); err != nil {
+			response.AbortInternal(c, err.Error())
+			return
+		}
+	}
+
+	sessionHash := hashSessionToken(token)
+
+	state := uuid.NewString()
+	payloadValue, err := encodeOAuthStatePayload(oauthStatePayload{
+		SourceName:  source.Name,
+		Purpose:     purpose,
+		UserID:      userID,
+		SessionHash: sessionHash,
+	})
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	if err := db.Redis.Set(c.Request.Context(), db.PrefixedKey(fmt.Sprintf(OAuthStateCacheKeyFormat, state)), payloadValue, OAuthStateCacheKeyExpiration).Err(); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	authorizeURL, err := buildAuthorizeURL(c.Request.Context(), source, state)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(OAuthAuthorizeResponse{AuthorizeURL: authorizeURL}))
+}

Wavelet/internal/apps/oauth/handler_callback.go

@@ -0,0 +1,227 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package oauth
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/common"
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/listener"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+)
+
+// Callback OAuth 回调处理
+// @Summary OAuth 回调处理
+// @Description 接收前端传回的 state 和 code，完成 OAuth/OIDC 认证并建立会话。支持登录（login）和账号绑定（bind）两种场景。
+// @Tags oauth
+// @Accept json
+// @Produce json
+// @Param request body oauth.CallbackRequest true "回调请求参数"
+// @Success 200 {object} response.Any{data=oauth.OAuthCallbackResult} "登录或绑定成功"
+// @Failure 400 {object} response.Any "state 无效、参数错误或认证源错误"
+// @Failure 401 {object} response.Any "绑定场景未登录"
+// @Failure 500 {object} response.Any "OAuth 认证失败或内部错误"
+// @Router /api/v1/oauth/callback [post]
+func Callback(c *gin.Context) {
+	var req CallbackRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	ctx := c.Request.Context()
+	stateKey := db.PrefixedKey(fmt.Sprintf(OAuthStateCacheKeyFormat, req.State))
+	payloadRaw, err := db.Redis.Get(ctx, stateKey).Result()
+	if err != nil {
+		response.AbortBadRequest(c, errInvalidState)
+		return
+	}
+	_ = db.Redis.Del(ctx, stateKey)
+
+	payload, err := decodeOAuthStatePayload(payloadRaw)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	session := sessions.Default(c)
+	currentUserID := GetUserIDFromSession(session)
+
+	if payload.Purpose == OAuthPurposeBind && currentUserID == 0 {
+		response.AbortUnauthorized(c, common.UnAuthorized)
+		return
+	}
+
+	token, ok := session.Get(SessionTokenKey).(string)
+	if !ok || token == "" {
+		response.AbortBadRequest(c, "invalid session context")
+		return
+	}
+
+	if hashSessionToken(token) != payload.SessionHash {
+		response.AbortBadRequest(c, "session mismatch for oauth state")
+		return
+	}
+
+	if payload.Purpose == OAuthPurposeBind && currentUserID != payload.UserID {
+		response.AbortBadRequest(c, "user context mismatch for oauth binding")
+		return
+	}
+
+	if !isOIDCLoginEnabled(ctx) {
+		response.AbortBadRequest(c, errAuthSourceDisabled)
+		return
+	}
+
+	source, err := resolveAuthSource(ctx, payload.SourceName)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if !source.IsActive {
+		response.AbortBadRequest(c, errAuthSourceDisabled)
+		return
+	}
+
+	redirectURL, err := getFrontendLoginRedirectURL(ctx)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	userInfo, err := buildOAuthUserInfo(ctx, source, req.Code, req.State, redirectURL)
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	if err := normalizeOAuthUserInfo(userInfo); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	if userInfo.Sub == "" {
+		userInfo.Sub = userInfo.Username
+	}
+
+	if payload.Purpose == OAuthPurposeBind {
+		handleCallbackBind(ctx, c, source, userInfo)
+		return
+	}
+
+	handleCallbackLogin(ctx, c, source, userInfo)
+}
+
+// handleCallbackBind 处理 OAuth 回调中的帐号绑定流程
+func handleCallbackBind(ctx context.Context, c *gin.Context, source *model.AuthSource, userInfo *model.OAuthUserInfo) {
+	userID := GetUserIDFromContext(c)
+	if userID == 0 {
+		response.AbortUnauthorized(c, common.UnAuthorized)
+		return
+	}
+	var user model.User
+	if err := db.DB(ctx).First(&user, "id = ?", userID).Error; err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	if err := model.BindExternalAccount(ctx, &model.ExternalAccount{
+		AuthSourceID:     source.ID,
+		UserID:           user.ID,
+		ExternalID:       userInfo.Sub,
+		ExternalUsername: userInfo.Username,
+		Email:            userInfo.Email,
+	}); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	user.LastLoginAt = time.Now()
+	_ = db.DB(ctx).Model(&user).Update("last_login_at", user.LastLoginAt).Error
+	c.JSON(http.StatusOK, response.OK(buildCallbackResult(&user, "bound")))
+}
+
+// handleCallbackLogin 处理 OAuth 回调中的登录流程（查找已有帐号或自动注册）
+func handleCallbackLogin(ctx context.Context, c *gin.Context, source *model.AuthSource, userInfo *model.OAuthUserInfo) {
+	var user model.User
+
+	account, err := model.FindExternalAccount(ctx, source.ID, userInfo.Sub)
+	switch {
+	case err == nil:
+		if err := db.DB(ctx).First(&user, "id = ?", account.UserID).Error; err != nil {
+			response.AbortInternal(c, err.Error())
+			return
+		}
+	case errors.Is(err, gorm.ErrRecordNotFound):
+		newUser, ok := handleCallbackRegister(ctx, c, source, userInfo)
+		if !ok {
+			return
+		}
+		user = newUser
+	default:
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	user.LastLoginAt = time.Now()
+	_ = db.DB(ctx).Model(&user).Update("last_login_at", user.LastLoginAt).Error
+	if err := setLoginSession(ctx, c, &user); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	logger.InfoF(ctx, "[LoginAudit] successful OAuth login via source: %s, external ID: %s, user: %s, ID: %d, IP: %s", source.Name, userInfo.Sub, user.Username, user.ID, c.ClientIP())
+
+	listener.EmitAdminLoggedIn(ctx, &user, c.ClientIP())
+
+	c.JSON(http.StatusOK, response.OK(buildCallbackResult(&user, "logged_in")))
+}
+
+// handleCallbackRegister 处理 OAuth 回调中的自动注册流程
+// 若注册被禁用则保存 pending 信息并返回 false；若注册成功则返回新用户；若出错则返回 false
+func handleCallbackRegister(ctx context.Context, c *gin.Context, source *model.AuthSource, userInfo *model.OAuthUserInfo) (model.User, bool) {
+	registrationEnabled, regErr := repository.GetBoolByKey(ctx, model.ConfigKeyRegistrationEnabled)
+	if regErr != nil {
+		registrationEnabled = true
+	}
+
+	if !registrationEnabled {
+		c.JSON(http.StatusOK, response.OK(buildCallbackResult(nil, "need_bind")))
+		return model.User{}, false
+	}
+
+	username, uniqueErr := uniqueUsername(ctx, userInfo.Username)
+	if uniqueErr != nil {
+		response.AbortInternal(c, uniqueErr.Error())
+		return model.User{}, false
+	}
+	userInfo.Username = username
+
+	var user model.User
+	if err := user.CreateUser(ctx, db.DB(ctx), userInfo); err != nil {
+		response.AbortInternal(c, err.Error())
+		return model.User{}, false
+	}
+	if err := model.BindExternalAccount(ctx, &model.ExternalAccount{
+		AuthSourceID:     source.ID,
+		UserID:           user.ID,
+		ExternalID:       userInfo.Sub,
+		ExternalUsername: userInfo.Username,
+		Email:            userInfo.Email,
+	}); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return model.User{}, false
+	}
+	logger.InfoF(ctx, "[LoginAudit] successful OAuth registration via source: %s, external ID: %s, user: %s, ID: %d, IP: %s", source.Name, userInfo.Sub, user.Username, user.ID, c.ClientIP())
+
+	return user, true
+}

Wavelet/internal/apps/oauth/handler_external_accounts.go

@@ -0,0 +1,65 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package oauth
+
+import (
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/internal/common"
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/gin-gonic/gin"
+)
+
+// ListExternalAccounts 获取当前用户的外部帐号绑定列表
+// @Summary 获取外部帐号列表
+// @Description 返回当前登录用户已绑定的所有外部 OAuth 帐号信息，需要登录
+// @Tags oauth
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]model.ExternalAccountView} "外部帐号列表"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/oauth/external-accounts [get]
+func ListExternalAccounts(c *gin.Context) {
+	userID := GetUserIDFromContext(c)
+	accounts, err := model.ListExternalAccountsByUserID(c.Request.Context(), userID)
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(accounts))
+}
+
+// DeleteExternalAccount 解除外部帐号绑定
+// @Summary 解除外部帐号绑定
+// @Description 解除当前登录用户与指定外部帐号的绑定关系，需要登录
+// @Tags oauth
+// @Produce json
+// @Security SessionCookie
+// @Param id path uint64 true "外部帐号绑定记录 ID"
+// @Success 200 {object} response.Any{data=string} "解除绑定成功"
+// @Failure 400 {object} response.Any "ID 无效或解除失败"
+// @Failure 401 {object} response.Any "未登录"
+// @Router /api/v1/oauth/external-accounts/{id}/delete [post]
+func DeleteExternalAccount(c *gin.Context) {
+	userID := GetUserIDFromContext(c)
+	if userID == 0 {
+		response.AbortUnauthorized(c, common.UnAuthorized)
+		return
+	}
+	rawID := strings.TrimSpace(c.Param("id"))
+	id, err := strconv.ParseUint(rawID, 10, 64)
+	if err != nil || id == 0 {
+		response.AbortBadRequest(c, errInvalidExternalAccountBindingID)
+		return
+	}
+	if err := model.DeleteExternalAccountForUser(c.Request.Context(), id, userID); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}

Wavelet/internal/apps/oauth/handler_sources.go

@@ -0,0 +1,22 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package oauth
+
+import (
+	"net/http"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+	"github.com/gin-gonic/gin"
+)
+
+// GetLoginSources 获取可用登录源列表
+// @Summary 获取可用登录源
+// @Description 返回当前系统已启用的所有 OAuth 登录源，前端展示登录按钮列表时调用
+// @Tags oauth
+// @Produce json
+// @Success 200 {object} response.Any{data=[]oauth.AuthSourceView} "登录源列表"
+// @Router /api/v1/oauth/sources [get]
+func GetLoginSources(c *gin.Context) {
+	c.JSON(http.StatusOK, response.OK(activeLoginSources(c.Request.Context())))
+}

Wavelet/internal/apps/oauth/middlewares.go

@@ -0,0 +1,138 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package oauth
+
+import (
+	"context"
+	"errors"
+
+	"github.com/Rain-kl/Wavelet/internal/common"
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+
+	otel_trace "github.com/Rain-kl/Wavelet/pkg/trace"
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-gonic/gin"
+)
+
+type loginRequiredAuditLog struct {
+	UserID     uint64 `json:"user_id"`
+	Username   string `json:"username"`
+	ClientIP   string `json:"client_ip"`
+	Method     string `json:"method"`
+	Path       string `json:"path"`
+	RequestURI string `json:"request_uri"`
+	UserAgent  string `json:"user_agent"`
+	Referer    string `json:"referer"`
+}
+
+func getUserByToken(ctx context.Context, tokenStr string) (*model.User, *model.AccessToken, error) {
+	tokenHash := model.HashToken(tokenStr)
+	var tokenRecord model.AccessToken
+	if err := db.DB(ctx).Where("token_hash = ?", tokenHash).First(&tokenRecord).Error; err != nil {
+		return nil, nil, err
+	}
+	var user model.User
+	if err := db.DB(ctx).Where("id = ? AND is_active = ?", tokenRecord.UserID, true).First(&user).Error; err != nil {
+		return nil, nil, err
+	}
+	return &user, &tokenRecord, nil
+}
+
+// GetUserFromRequest 校验 Access Token 或 Session 并返回用户对象，如果未登录或用户失效则返回 error
+func GetUserFromRequest(c *gin.Context) (*model.User, error) {
+	ctx := c.Request.Context()
+
+	// check token in headers
+	tokenStr := c.GetHeader("X-Access-Token")
+	if tokenStr == "" {
+		authHeader := c.GetHeader("Authorization")
+		if len(authHeader) > 7 && authHeader[:7] == "Bearer " {
+			tokenStr = authHeader[7:]
+		}
+	}
+
+	// 优先使用 Access Token 鉴权
+	if tokenStr != "" {
+		if user, tokenRecord, err := getUserByToken(ctx, tokenStr); err == nil {
+			// 强行阻止 system 用户任何会话/Token 鉴权通过
+			if user.Username == "system" {
+				return nil, errors.New("system user is not allowed to login")
+			}
+			SetToContext(c, TokenAuthKey, true)
+			SetToContext(c, TokenAdminKey, tokenRecord.IsAdmin)
+			return user, nil
+		}
+	}
+
+	// 降级使用 Session 鉴权
+	userID := GetUserIDFromContext(c)
+	if userID <= 0 {
+		return nil, errors.New("unauthorized")
+	}
+
+	var user model.User
+	// load user from db to make sure is active
+	tx := db.DB(ctx).Where("id = ? AND is_active = ?", userID, true).First(&user)
+	if tx.Error != nil {
+		return nil, tx.Error
+	}
+
+	// 密码哈希校验：当用户存在本地密码时，要求 Session 中的密码哈希必须与当前数据库中一致
+	if user.Password != "" {
+		session := sessions.Default(c)
+		sessionHash, _ := session.Get(PasswordHashKey).(string)
+		if sessionHash != user.Password {
+			return nil, errors.New("session expired due to password change")
+		}
+	}
+
+	// set keys in context for session auth
+	SetToContext(c, TokenAuthKey, false)
+	SetToContext(c, TokenAdminKey, false)
+
+	// 强行阻止 system 用户任何会话/Token 鉴权通过
+	if user.Username == "system" {
+		return nil, errors.New("system user is not allowed to login")
+	}
+
+	return &user, nil
+}
+
+// LoginRequired 返回登录鉴权中间件，校验 Access Token 或 Session
+func LoginRequired() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// init trace
+		ctx, span := otel_trace.Start(c.Request.Context(), "LoginRequired")
+		defer span.End()
+
+		user, err := GetUserFromRequest(c)
+		if err != nil {
+			response.AbortUnauthorized(c, common.UnAuthorized)
+			return
+		}
+
+		// log
+		LogForAudit(ctx, user, c)
+
+		// set user info
+		SetToContext(c, UserObjKey, user)
+
+		// next
+		c.Next()
+	}
+}
+
+// DisallowTokenAuth 拒绝使用 Access Token 进行身份验证的请求访问该端点
+func DisallowTokenAuth() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if tokenAuth, _ := GetFromContext[bool](c, TokenAuthKey); tokenAuth {
+			response.AbortForbidden(c, ErrTokenAuthNotAllowed)
+			return
+		}
+		c.Next()
+	}
+}

Wavelet/internal/apps/oauth/oauth_types.go

@@ -0,0 +1,36 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package oauth
+
+// AuthSourceView 登录源展示信息
+type AuthSourceView struct {
+	ID                     uint64 `json:"id"`
+	Name                   string `json:"name"`
+	Type                   string `json:"type"`
+	DisplayName            string `json:"display_name"`
+	IsActive               bool   `json:"is_active"`
+	IconURL                string `json:"icon_url"`
+	ClientSecretConfigured bool   `json:"client_secret_configured"`
+}
+
+// OAuthAuthorizeResponse 授权 URL 响应
+//
+//nolint:revive // OAuth 前缀保持包内语义清晰
+type OAuthAuthorizeResponse struct {
+	AuthorizeURL string `json:"authorize_url"`
+}
+
+// OAuthCallbackResult 回调处理结果
+//
+//nolint:revive // OAuth 前缀保持包内语义清晰
+type OAuthCallbackResult struct {
+	Status string         `json:"status"`
+	User   *BasicUserInfo `json:"user,omitempty"`
+}
+
+// CallbackRequest OAuth 回调请求参数
+type CallbackRequest struct {
+	State string `json:"state" binding:"required"`
+	Code  string `json:"code" binding:"required"`
+}

Wavelet/internal/apps/oauth/oauth_userinfo.go

@@ -0,0 +1,141 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package oauth
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/coreos/go-oidc/v3/oidc"
+	"golang.org/x/oauth2"
+)
+
+func uniqueUsername(ctx context.Context, base string) (string, error) {
+	base = strings.TrimSpace(base)
+	if base == "" {
+		base = "user"
+	}
+
+	var existingUsernames []string
+	if err := db.DB(ctx).Model(&model.User{}).
+		Where("username = ? OR username LIKE ?", base, base+"-%").
+		Pluck("username", &existingUsernames).Error; err != nil {
+		return "", err
+	}
+
+	// 将现有的用户名放入 map 中，以便 O(1) 查找
+	exists := make(map[string]bool, len(existingUsernames))
+	for _, u := range existingUsernames {
+		exists[strings.ToLower(u)] = true
+	}
+
+	// 检查 base 是否被占用
+	if !exists[strings.ToLower(base)] {
+		return base, nil
+	}
+
+	// 顺序查找第一个可用的带后缀用户名
+	for i := 1; i <= 1000; i++ {
+		candidate := fmt.Sprintf("%s-%d", base, i)
+		if !exists[strings.ToLower(candidate)] {
+			return candidate, nil
+		}
+	}
+
+	return "", errors.New(errUsernameGenerateFailed)
+}
+
+func buildOAuthUserInfo(ctx context.Context, source *model.AuthSource, code string, nonce string, redirectURL string) (*model.OAuthUserInfo, error) {
+	authConfig, verifier, err := buildOAuthConfig(ctx, source, redirectURL)
+	if err != nil {
+		return nil, err
+	}
+
+	token, err := authConfig.Exchange(ctx, code)
+	if err != nil {
+		return nil, err
+	}
+
+	userInfo := &model.OAuthUserInfo{Active: true}
+	if verifier != nil {
+		if verifyErr := verifyIDToken(ctx, verifier, token, nonce, userInfo); verifyErr != nil {
+			return nil, verifyErr
+		}
+	}
+
+	if userInfo.Username == "" && userInfo.PreferredUsername != "" {
+		userInfo.Username = userInfo.PreferredUsername
+	}
+	if userInfo.Username == "" && userInfo.Email != "" {
+		userInfo.Username = strings.Split(userInfo.Email, "@")[0]
+	}
+	if userInfo.Username == "" && userInfo.Sub != "" {
+		userInfo.Username = userInfo.Sub
+	}
+	if userInfo.Name == "" {
+		userInfo.Name = userInfo.Username
+	}
+
+	return userInfo, nil
+}
+
+// verifyIDToken 验证 OIDC ID Token 并将 Claims 解析到 userInfo
+func verifyIDToken(ctx context.Context, verifier *oidc.IDTokenVerifier, token *oauth2.Token, nonce string, userInfo *model.OAuthUserInfo) error {
+	rawIDToken, ok := token.Extra("id_token").(string)
+	if !ok {
+		return nil
+	}
+	idToken, verifyErr := verifier.Verify(ctx, rawIDToken)
+	if verifyErr != nil {
+		return fmt.Errorf(errIDTokenVerifyFailedFormat, errIDTokenVerifyFailed, verifyErr)
+	}
+	if nonce != "" && idToken.Nonce != nonce {
+		return errors.New(errNonceMismatch)
+	}
+	if claimsErr := idToken.Claims(userInfo); claimsErr != nil {
+		return claimsErr
+	}
+	return nil
+}
+
+func normalizeOAuthUserInfo(userInfo *model.OAuthUserInfo) error {
+	userInfo.Username = strings.TrimSpace(userInfo.Username)
+	userInfo.PreferredUsername = strings.TrimSpace(userInfo.PreferredUsername)
+	userInfo.Email = strings.TrimSpace(userInfo.Email)
+	userInfo.Name = strings.TrimSpace(userInfo.Name)
+	userInfo.AvatarURL = strings.TrimSpace(userInfo.AvatarURL)
+
+	if userInfo.Username == "" && userInfo.PreferredUsername != "" {
+		userInfo.Username = userInfo.PreferredUsername
+	}
+	if userInfo.Username == "" && userInfo.Email != "" {
+		userInfo.Username = strings.Split(userInfo.Email, "@")[0]
+	}
+	if userInfo.Username == "" && userInfo.Sub != "" {
+		userInfo.Username = userInfo.Sub
+	}
+	if userInfo.Username == "" {
+		return errors.New(errUsernameFromSourceFailed)
+	}
+	if userInfo.Name == "" {
+		userInfo.Name = userInfo.Username
+	}
+	if !userInfo.Active {
+		userInfo.Active = true
+	}
+	return nil
+}
+
+func buildCallbackResult(user *model.User, status string) OAuthCallbackResult {
+	result := OAuthCallbackResult{Status: status}
+	if user != nil {
+		info := BuildBasicUserInfo(user, false)
+		result.User = &info
+	}
+	return result
+}

Wavelet/internal/apps/oauth/provider_cache.go

@@ -0,0 +1,99 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package oauth
+
+import (
+	"context"
+	"net/http"
+	"sync"
+
+	"github.com/coreos/go-oidc/v3/oidc"
+	"golang.org/x/oauth2"
+	"golang.org/x/sync/singleflight"
+)
+
+// oidcProviderCache 进程级 OIDC provider 缓存。
+//
+// oidc.NewProvider 每次调用都会向远端 issuer 的
+// /.well-known/openid-configuration 发起 HTTP 请求拉取元数据。
+// 由于 provider 元数据极少变动，将其缓存后可消除登录发起与回调时的
+// 重复外部 HTTP 往返。
+//
+// 并发安全性：
+//   - mu + entries 防止并发读写 map。
+//   - sfGroup 保证同一 issuer 同时只有一次在途的 NewProvider 调用
+//     （singleflight），后续等待者复用同一结果，彻底消除 thundering herd。
+type oidcProviderCache struct {
+	mu      sync.RWMutex
+	entries map[string]*oidc.Provider // key: normalized issuer URL
+	sfGroup singleflight.Group
+}
+
+// globalOIDCProviderCache 是包级单例缓存，与进程同生命周期。
+var globalOIDCProviderCache = &oidcProviderCache{
+	entries: make(map[string]*oidc.Provider),
+}
+
+// discoveryContext 从请求 ctx 提取 HTTP 客户端，并绑定到不可取消的 Background ctx。
+// 这样既能在测试中注入 mock 客户端，又避免请求取消导致 provider 拉取失败。
+func discoveryContext(ctx context.Context) context.Context {
+	bg := context.Background()
+	if client, ok := ctx.Value(oauth2.HTTPClient).(*http.Client); ok && client != nil {
+		bg = oidc.ClientContext(bg, client)
+	}
+	return bg
+}
+
+// get 返回缓存的 provider；若无则通过 oidc.NewProvider 获取并写入缓存。
+// 同一 issuer 并发调用时，singleflight 保证只有一次实际 HTTP 请求。
+func (c *oidcProviderCache) get(ctx context.Context, issuer string) (*oidc.Provider, error) {
+	// 快路径：已有缓存则直接返回。
+	c.mu.RLock()
+	if p, ok := c.entries[issuer]; ok {
+		c.mu.RUnlock()
+		return p, nil
+	}
+	c.mu.RUnlock()
+
+	// 慢路径：通过 singleflight 合并并发的首次请求。
+	discCtx := discoveryContext(ctx)
+	v, err, _ := c.sfGroup.Do(issuer, func() (any, error) {
+		// 双检：singleflight 内再次检查，前一个并发组可能已写入缓存。
+		c.mu.RLock()
+		if p, ok := c.entries[issuer]; ok {
+			c.mu.RUnlock()
+			return p, nil
+		}
+		c.mu.RUnlock()
+
+		p, err := oidc.NewProvider(discCtx, issuer)
+		if err != nil {
+			return nil, err
+		}
+
+		c.mu.Lock()
+		c.entries[issuer] = p
+		c.mu.Unlock()
+		return p, nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return v.(*oidc.Provider), nil //nolint:forcetypeassert // singleflight value 由同函数写入，类型确定
+}
+
+// invalidate 从缓存中移除指定 issuer 对应的 provider。
+// 在认证源的 Discovery URL 被修改时调用，强制下次请求重新拉取元数据。
+func (c *oidcProviderCache) invalidate(issuer string) {
+	c.mu.Lock()
+	delete(c.entries, issuer)
+	c.mu.Unlock()
+}
+
+// InvalidateOIDCProviderCache 从进程级缓存中清除指定 issuer 的 provider 条目。
+// 当管理员更新认证源的 Discovery URL 后调用，以确保下次登录时重新拉取最新元数据。
+// issuer 值应为去掉 /.well-known/openid-configuration 后缀的规范化 URL。
+func InvalidateOIDCProviderCache(issuer string) {
+	globalOIDCProviderCache.invalidate(issuer)
+}

Wavelet/internal/apps/oauth/routers.go

@@ -0,0 +1,106 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package oauth
+
+import (
+	"net/http"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+// BasicUserInfo 用户基本信息结构体
+type BasicUserInfo struct {
+	ID                 uint64 `json:"id"`
+	Username           string `json:"username"`
+	Nickname           string `json:"nickname"`
+	Email              string `json:"email"`
+	AvatarURL          string `json:"avatar_url"`
+	IsAdmin            bool   `json:"is_admin"`
+	NeedChangePassword bool   `json:"need_change_password"`
+	Bio                string `json:"bio"`
+	Phone              string `json:"phone"`
+	Gender             string `json:"gender"`
+	Website            string `json:"website"`
+	Location           string `json:"location"`
+}
+
+// BuildBasicUserInfo 将 User 模型转换为 BasicUserInfo
+func BuildBasicUserInfo(user *model.User, needChange bool) BasicUserInfo {
+	return BasicUserInfo{
+		ID:                 user.ID,
+		Username:           user.Username,
+		Nickname:           user.Nickname,
+		Email:              user.Email,
+		AvatarURL:          user.AvatarURL,
+		IsAdmin:            user.IsAdmin,
+		NeedChangePassword: needChange,
+		Bio:                user.Bio,
+		Phone:              user.Phone,
+		Gender:             user.Gender,
+		Website:            user.Website,
+		Location:           user.Location,
+	}
+}
+
+// UserInfo 获取当前登录用户信息
+// @Summary 获取当前登录用户信息
+// @Description 返回当前登录用户的基本信息及余额数据，需要登录。包括用户 ID、用户名、信任等级、各类余额信息等。
+// @Tags oauth
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=oauth.BasicUserInfo} "用户信息"
+// @Failure 401 {object} response.Any "未登录"
+// @Router /api/v1/oauth/user-info [get]
+// @Router /api/v1/user-info [get]
+// @Router /api/v1/user/self [get]
+func UserInfo(c *gin.Context) {
+	user, _ := GetFromContext[*model.User](c, UserObjKey)
+	session := sessions.Default(c)
+	needChange := session.Get("need_change_password") == true
+
+	c.JSON(
+		http.StatusOK,
+		response.OK(BuildBasicUserInfo(user, needChange)),
+	)
+}
+
+// GetLoginURL 获取登录地址
+// @Summary 获取登录地址
+// @Description 生成 OAuth 登录 URL，前端跳转至该地址完成授权。返回的 URL 中包含 state 参数用于 CSRF 防护。
+// @Tags oauth
+// @Produce json
+// @Success 200 {object} response.Any{data=string} "OAuth 登录 URL"
+// @Failure 500 {object} response.Any "Redis 异常或内部错误"
+// @Router /api/v1/oauth/login [get]
+
+// Logout 退出登录
+// @Summary 退出登录
+// @Description 清除当前用户的登录会话，完成退出。清除 Cookie 中的 Session 数据。
+// @Tags oauth
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=string} "退出成功"
+// @Failure 500 {object} response.Any "Session 清除失败"
+// @Router /api/v1/oauth/logout [get]
+func Logout(c *gin.Context) {
+	session := sessions.Default(c)
+	userID := session.Get(UserIDKey)
+	username := session.Get(UserNameKey)
+	if userID != nil {
+		logger.InfoF(c.Request.Context(), "[LoginAudit] user logged out: %v, ID: %v, IP: %s", username, userID, c.ClientIP())
+	}
+	session.Options(GetSessionOptions(-1))
+	session.Clear()
+	if err := session.Save(); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}

Wavelet/internal/apps/oauth/session.go

@@ -0,0 +1,53 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package oauth provides authentication and OAuth integration.
+package oauth
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/internal/config"
+	"github.com/gin-contrib/sessions"
+)
+
+// GetSessionOptions 根据配置构建 Session 选项
+func GetSessionOptions(maxAge int) sessions.Options {
+	return sessions.Options{
+		Path:     "/",
+		Domain:   config.Config.App.SessionDomain,
+		MaxAge:   maxAge,
+		HttpOnly: config.Config.App.SessionHTTPOnly,
+		Secure:   config.Config.App.SessionSecure,
+		SameSite: http.SameSiteLaxMode,
+	}
+}
+
+// StripCookieMaxAgeAndExpires 从 Set-Cookie 响应头中移除 Max-Age 和 Expires，从而使其成为浏览器会话 Cookie
+func StripCookieMaxAgeAndExpires(header http.Header, cookieName string) {
+	headers := header["Set-Cookie"]
+	if len(headers) == 0 {
+		return
+	}
+
+	newHeaders := make([]string, 0, len(headers))
+	for _, h := range headers {
+		if strings.HasPrefix(h, cookieName+"=") {
+			parts := strings.Split(h, ";")
+			newParts := make([]string, 0, len(parts))
+			for _, p := range parts {
+				trimmed := strings.TrimSpace(p)
+				lower := strings.ToLower(trimmed)
+				if strings.HasPrefix(lower, "max-age=") || strings.HasPrefix(lower, "expires=") {
+					continue
+				}
+				newParts = append(newParts, p)
+			}
+			newHeaders = append(newHeaders, strings.Join(newParts, ";"))
+		} else {
+			newHeaders = append(newHeaders, h)
+		}
+	}
+	header["Set-Cookie"] = newHeaders
+}

Wavelet/internal/apps/oauth/session_context.go

@@ -0,0 +1,83 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package oauth
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+
+	"github.com/Rain-kl/Wavelet/internal/config"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+)
+
+// GetUserIDFromSession 从 Session 中提取用户 ID
+func GetUserIDFromSession(s sessions.Session) uint64 {
+	userID, ok := s.Get(UserIDKey).(uint64)
+	if !ok {
+		return 0
+	}
+	return userID
+}
+
+// GetUserIDFromContext 从 Gin Context 的 Session 中提取用户 ID
+func GetUserIDFromContext(c *gin.Context) uint64 {
+	session := sessions.Default(c)
+	return GetUserIDFromSession(session)
+}
+
+func ensureSessionToken(s sessions.Session) (string, bool) {
+	token, ok := s.Get(SessionTokenKey).(string)
+	if !ok || token == "" {
+		token = uuid.NewString()
+		s.Set(SessionTokenKey, token)
+		return token, true
+	}
+	return token, false
+}
+
+func hashSessionToken(token string) string {
+	h := sha256.New()
+	h.Write([]byte(token))
+	return hex.EncodeToString(h.Sum(nil))
+}
+
+func setLoginSession(ctx context.Context, c *gin.Context, user *model.User) error {
+	session := sessions.Default(c)
+	session.Set(UserIDKey, user.ID)
+	session.Set(UserNameKey, user.Username)
+	session.Set(PasswordHashKey, user.Password)
+
+	// 根据系统配置动态设置 Session 过期时间
+	maxAge := config.Config.App.SessionAge
+	isSessionCookie := false
+
+	ttlHours, err := repository.GetIntByKey(ctx, model.ConfigKeyLoginSessionTTLHours)
+	if err == nil {
+		switch {
+		case ttlHours == -1:
+			// 永不过期，设置为 10 年
+			maxAge = 10 * 365 * 24 * 3600
+		case ttlHours > 0:
+			maxAge = ttlHours * 3600
+		case ttlHours == 0:
+			isSessionCookie = true
+		}
+	}
+	session.Options(GetSessionOptions(maxAge))
+
+	if err := session.Save(); err != nil {
+		return err
+	}
+
+	if isSessionCookie {
+		StripCookieMaxAgeAndExpires(c.Writer.Header(), config.Config.App.SessionCookieName)
+	}
+
+	return nil
+}

Wavelet/internal/apps/risk_control/logics.go

@@ -0,0 +1,116 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package risk_control
+
+import (
+	"context"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/config"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+)
+
+var logChan chan *UserAccessLog
+
+const (
+	defaultQueueSize = 10000
+	maxBatchSize     = 1000
+	flushInterval    = 1 * time.Second
+)
+
+// InitLogWriter 初始化日志写入通道和后台写入协程
+func InitLogWriter(ctx context.Context) {
+	if !config.Config.ClickHouse.Enabled {
+		return
+	}
+
+	logChan = make(chan *UserAccessLog, defaultQueueSize)
+	go startBatchWorker(context.WithoutCancel(ctx))
+}
+
+// IsBufferFull 检查当前本地缓冲队列是否已满
+// 如果没有启用 ClickHouse，默认返回 false，不触发限流
+func IsBufferFull() bool {
+	if !config.Config.ClickHouse.Enabled || logChan == nil {
+		return false
+	}
+	return len(logChan) >= cap(logChan)
+}
+
+// QueueAccessLog 异步非阻塞地将日志推入缓冲队列
+func QueueAccessLog(logItem *UserAccessLog) {
+	if !config.Config.ClickHouse.Enabled || logChan == nil {
+		return
+	}
+
+	select {
+	case logChan <- logItem:
+	default:
+		logger.WarnF(context.Background(), "[RiskControl] Log queue full, dropping log item for path: %s", logItem.Path)
+	}
+}
+
+func startBatchWorker(ctx context.Context) {
+	ticker := time.NewTicker(flushInterval)
+	defer ticker.Stop()
+
+	var batch []*UserAccessLog
+
+	flush := func() {
+		if len(batch) == 0 {
+			return
+		}
+		if db.ChConn == nil {
+			batch = nil
+			return
+		}
+
+		b, err := db.ChConn.PrepareBatch(ctx, "INSERT INTO w_user_access_logs (id, user_id, path, method, ip, user_agent, headers, status, latency, created_at)")
+		if err != nil {
+			logger.ErrorF(ctx, "[RiskControl] Prepare ClickHouse batch failed: %v", err)
+			batch = nil
+			return
+		}
+
+		for _, item := range batch {
+			err = b.Append(
+				item.ID,
+				item.UserID,
+				item.Path,
+				item.Method,
+				item.IP,
+				item.UserAgent,
+				item.Headers,
+				item.Status,
+				item.Latency,
+				item.CreatedAt,
+			)
+			if err != nil {
+				logger.ErrorF(ctx, "[RiskControl] Append item to ClickHouse batch failed: %v", err)
+			}
+		}
+
+		if err := b.Send(); err != nil {
+			logger.ErrorF(ctx, "[RiskControl] Send ClickHouse batch failed: %v", err)
+		}
+		batch = nil
+	}
+
+	for {
+		select {
+		case item, ok := <-logChan:
+			if !ok {
+				flush()
+				return
+			}
+			batch = append(batch, item)
+			if len(batch) >= maxBatchSize {
+				flush()
+			}
+		case <-ticker.C:
+			flush()
+		}
+	}
+}

Wavelet/internal/apps/risk_control/middleware.go

@@ -0,0 +1,87 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package risk_control 提供风险控制中间件
+package risk_control
+
+import (
+	"encoding/json"
+	"net/http"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+	"github.com/Rain-kl/Wavelet/internal/config"
+	"github.com/Rain-kl/Wavelet/internal/db/idgen"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/gin-gonic/gin"
+)
+
+// RiskControlMiddleware 全局日志采集中间件
+func RiskControlMiddleware() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// 如果未启用 ClickHouse，直接放行
+		if !config.Config.ClickHouse.Enabled {
+			c.Next()
+			return
+		}
+
+		// 1. 限流背压检测（检测本地缓冲队列是否已满）
+		if IsBufferFull() {
+			response.AbortTooManyRequests(c, "系统繁忙，请稍后再试")
+			return
+		}
+
+		start := time.Now()
+
+		// 2. 执行后续请求（穿过业务处理和认证中间件）
+		c.Next()
+
+		// 3. 后置身份检查：仅记录通过认证的请求
+		userObj, exists := oauth.GetFromContext[*model.User](c, oauth.UserObjKey)
+		if !exists || userObj == nil {
+			return
+		}
+
+		// 4. 计算耗时并异步推送到缓冲队列
+		latency := time.Since(start).Milliseconds()
+
+		var headersStr string
+		if c.Request.Header != nil {
+			// 克隆 Header，避免污染原 HTTP 请求的 Header 对象
+			clonedHeaders := make(http.Header)
+			for k, v := range c.Request.Header {
+				clonedHeaders[k] = v
+			}
+			clonedHeaders.Del("Cookie")
+
+			if headersBytes, err := json.Marshal(clonedHeaders); err == nil {
+				headersStr = string(headersBytes)
+			}
+		}
+
+		const maxHTTPStatus = 999
+		status := c.Writer.Status()
+		if status < 0 {
+			status = 0
+		} else if status > maxHTTPStatus {
+			status = maxHTTPStatus
+		}
+
+		logItem := &UserAccessLog{
+			ID:        idgen.NextUint64ID(),
+			UserID:    userObj.ID, // 直接从 Context 获取已登录用户ID，避免数据库查询
+			Path:      c.Request.URL.Path,
+			Method:    c.Request.Method,
+			IP:        c.ClientIP(),
+			UserAgent: c.Request.UserAgent(),
+			Headers:   headersStr,
+			Status:    int32(status),
+			Latency:   latency,
+			CreatedAt: time.Now(),
+		}
+
+		// 非阻塞地推入缓存队列
+		QueueAccessLog(logItem)
+	}
+}

Wavelet/internal/apps/risk_control/middleware_test.go

@@ -0,0 +1,143 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package risk_control
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	"github.com/Rain-kl/Wavelet/internal/config"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestRiskControlMiddleware(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	t.Run("ClickHouse disabled", func(t *testing.T) {
+		config.Config.ClickHouse.Enabled = false
+		defer func() { config.Config.ClickHouse.Enabled = false }()
+
+		r := testhelper.NewTestGinEngine(RiskControlMiddleware())
+		r.GET("/test", func(c *gin.Context) {
+			c.String(http.StatusOK, "ok")
+		})
+
+		w := httptest.NewRecorder()
+		req, _ := http.NewRequest(http.MethodGet, "/test", nil)
+		r.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+		assert.Equal(t, "ok", w.Body.String())
+	})
+
+	t.Run("ClickHouse enabled - Normal Authenticated Request", func(t *testing.T) {
+		config.Config.ClickHouse.Enabled = true
+		logChan = make(chan *UserAccessLog, defaultQueueSize)
+		defer func() {
+			config.Config.ClickHouse.Enabled = false
+			logChan = nil
+		}()
+
+		r := gin.New()
+		r.Use(func(c *gin.Context) {
+			// Mock authentication middleware placing user in context
+			user := &model.User{ID: 12345}
+			oauth.SetToContext(c, oauth.UserObjKey, user)
+			c.Next()
+		})
+		r.Use(RiskControlMiddleware())
+		r.GET("/test", func(c *gin.Context) {
+			c.String(http.StatusOK, "ok")
+		})
+
+		w := httptest.NewRecorder()
+		req, _ := http.NewRequest(http.MethodGet, "/test", nil)
+		req.Header.Set("X-Test-Header", "hello")
+		req.Header.Set("Cookie", "session_id=abcdef123456")
+		r.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+		assert.Equal(t, "ok", w.Body.String())
+
+		// Verify log is enqueued
+		select {
+		case logItem := <-logChan:
+			assert.Equal(t, uint64(12345), logItem.UserID)
+			assert.Equal(t, "/test", logItem.Path)
+			assert.Equal(t, http.MethodGet, logItem.Method)
+			assert.Equal(t, int32(http.StatusOK), logItem.Status)
+			assert.NotEmpty(t, logItem.Headers)
+			assert.Contains(t, logItem.Headers, "X-Test-Header")
+			assert.NotContains(t, logItem.Headers, "Cookie")
+		case <-time.After(100 * time.Millisecond):
+			t.Fatal("expected log item in logChan, but got none")
+		}
+	})
+
+	t.Run("ClickHouse enabled - Unauthenticated Request", func(t *testing.T) {
+		config.Config.ClickHouse.Enabled = true
+		logChan = make(chan *UserAccessLog, defaultQueueSize)
+		defer func() {
+			config.Config.ClickHouse.Enabled = false
+			logChan = nil
+		}()
+
+		r := testhelper.NewTestGinEngine(RiskControlMiddleware())
+		r.GET("/test", func(c *gin.Context) {
+			c.String(http.StatusOK, "ok")
+		})
+
+		w := httptest.NewRecorder()
+		req, _ := http.NewRequest(http.MethodGet, "/test", nil)
+		r.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+		assert.Equal(t, "ok", w.Body.String())
+
+		// Verify no log is enqueued
+		select {
+		case <-logChan:
+			t.Fatal("expected no log item for unauthenticated request")
+		case <-time.After(50 * time.Millisecond):
+			// Success
+		}
+	})
+
+	t.Run("ClickHouse enabled - Buffer Full Rate Limiting", func(t *testing.T) {
+		config.Config.ClickHouse.Enabled = true
+		logChan = make(chan *UserAccessLog, 2) // small capacity for quick fill
+		defer func() {
+			config.Config.ClickHouse.Enabled = false
+			logChan = nil
+		}()
+
+		// fill logChan up to cap to simulate buffer full
+		for len(logChan) < cap(logChan) {
+			logChan <- &UserAccessLog{}
+		}
+
+		r := testhelper.NewTestGinEngine(RiskControlMiddleware())
+		r.GET("/test", func(c *gin.Context) {
+			c.String(http.StatusOK, "ok")
+		})
+
+		w := httptest.NewRecorder()
+		req, _ := http.NewRequest(http.MethodGet, "/test", nil)
+		r.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusTooManyRequests, w.Code)
+
+		var resp map[string]interface{}
+		err := json.Unmarshal(w.Body.Bytes(), &resp)
+		assert.NoError(t, err)
+		assert.Contains(t, resp["error_msg"], "系统繁忙")
+	})
+}

Wavelet/internal/apps/risk_control/model.go

@@ -0,0 +1,22 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package risk_control
+
+import (
+	"time"
+)
+
+// UserAccessLog 用户访问记录
+type UserAccessLog struct {
+	ID        uint64    `json:"id,string"`
+	UserID    uint64    `json:"user_id,string"`
+	Path      string    `json:"path"`
+	Method    string    `json:"method"`
+	IP        string    `json:"ip"`
+	UserAgent string    `json:"user_agent"`
+	Headers   string    `json:"headers"`
+	Status    int32     `json:"status"`
+	Latency   int64     `json:"latency"` // 耗时毫秒
+	CreatedAt time.Time `json:"created_at"`
+}

Wavelet/internal/apps/user/access_tokens.go

@@ -0,0 +1,218 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package user 提供用户认证与帐户管理功能
+package user
+
+import (
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+type createTokenRequest struct {
+	Name    string `json:"name"`
+	IsAdmin bool   `json:"is_admin"`
+}
+
+type tokenResponse struct {
+	Token  string            `json:"token"`
+	Record model.AccessToken `json:"record"`
+}
+
+// ListAccessTokens 获取当前用户的 AccessToken 列表
+// @Summary 获取当前用户的 AccessToken 列表
+// @Description 返回当前登录用户的所有 active access tokens（脱敏后）
+// @Tags user
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]model.AccessToken} "令牌列表"
+// @Failure 401 {object} response.Any "未登录"
+// @Router /api/v1/user/access-tokens [get]
+// ListAccessTokens 获取当前用户的 AccessToken 列表
+func ListAccessTokens(c *gin.Context) {
+	currUser, _ := oauth.GetFromContext[*model.User](c, oauth.UserObjKey)
+	ctx := c.Request.Context()
+
+	var tokens []model.AccessToken
+	if err := db.DB(ctx).Where("user_id = ?", currUser.ID).Order("created_at desc").Find(&tokens).Error; err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(tokens))
+}
+
+// CreateAccessToken 创建一个新的 AccessToken
+// @Summary 创建一个新的 AccessToken
+// @Description 为当前用户新建一个 API 访问令牌，仅在此接口返回一次明文令牌值，请妥善保存。可通过 is_admin 字段赋予令牌管理员权限（仅管理员用户可设置）。
+// @Tags user
+// @Accept json
+// @Produce json
+// @Param request body user.createTokenRequest true "令牌名称"
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=user.tokenResponse} "新建令牌成功"
+// @Failure 400 {object} response.Any "参数错误或超限"
+// @Router /api/v1/user/access-tokens [post]
+func CreateAccessToken(c *gin.Context) {
+	currUser, _ := oauth.GetFromContext[*model.User](c, oauth.UserObjKey)
+	ctx := c.Request.Context()
+
+	var req createTokenRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, errBindParamsFailed)
+		return
+	}
+
+	req.Name = strings.TrimSpace(req.Name)
+	if req.Name == "" {
+		response.AbortBadRequest(c, errTokenNameRequired)
+		return
+	}
+
+	// 只有管理员才能创建具有管理员权限的令牌
+	if req.IsAdmin && !currUser.IsAdmin {
+		response.AbortBadRequest(c, errAdminTokenRequiresAdmin)
+		return
+	}
+
+	// 检查最大限制（基于 ConfigKeyMaxAPIKeysPerUser 配置，默认值为 5）
+	maxLimit := 5
+	if val, err := repository.GetIntByKey(ctx, model.ConfigKeyMaxAPIKeysPerUser); err == nil {
+		maxLimit = val
+	}
+
+	var count int64
+	if err := db.DB(ctx).Model(&model.AccessToken{}).Where("user_id = ?", currUser.ID).Count(&count).Error; err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if int(count) >= maxLimit {
+		response.AbortBadRequest(c, errAccessTokenLimitReached)
+		return
+	}
+
+	// 生成 Token
+	tokenStr, err := model.GenerateTokenString()
+	if err != nil {
+		response.AbortBadRequest(c, errGenerateTokenFailed)
+		return
+	}
+
+	tokenHash := model.HashToken(tokenStr)
+	maskedToken := model.MaskTokenString(tokenStr)
+
+	tokenRecord := model.AccessToken{
+		UserID:      currUser.ID,
+		Name:        req.Name,
+		TokenHash:   tokenHash,
+		MaskedToken: maskedToken,
+		IsAdmin:     req.IsAdmin,
+	}
+
+	if err := db.DB(ctx).Create(&tokenRecord).Error; err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(tokenResponse{
+		Token:  tokenStr,
+		Record: tokenRecord,
+	}))
+}
+
+// DeleteAccessToken 删除一个 AccessToken
+// @Summary 删除一个 AccessToken
+// @Description 撤销并删除一个属于当前用户的 API 访问令牌
+// @Tags user
+// @Produce json
+// @Param id path string true "令牌ID"
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=string} "删除成功"
+// @Failure 400 {object} response.Any "参数错误"
+// @Router /api/v1/user/access-tokens/{id} [delete]
+func DeleteAccessToken(c *gin.Context) {
+	currUser, _ := oauth.GetFromContext[*model.User](c, oauth.UserObjKey)
+	ctx := c.Request.Context()
+
+	idStr := c.Param("id")
+	id, err := strconv.ParseUint(idStr, 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, errInvalidTokenID)
+		return
+	}
+
+	tx := db.DB(ctx).Where("id = ? AND user_id = ?", id, currUser.ID).Delete(&model.AccessToken{})
+	if tx.Error != nil {
+		response.AbortBadRequest(c, tx.Error.Error())
+		return
+	}
+
+	if tx.RowsAffected == 0 {
+		response.AbortBadRequest(c, errTokenNotFoundOrForbidden)
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK("删除成功"))
+}
+
+// RotateAccessToken 轮换一个 AccessToken
+// @Summary 轮换一个 AccessToken
+// @Description 轮换（重新生成）一个属于当前用户的 API 访问令牌的密钥，旧令牌将立即失效
+// @Tags user
+// @Produce json
+// @Param id path string true "令牌ID"
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=user.tokenResponse} "令牌轮换成功"
+// @Failure 400 {object} response.Any "参数错误"
+// @Router /api/v1/user/access-tokens/{id}/rotate [post]
+func RotateAccessToken(c *gin.Context) {
+	currUser, _ := oauth.GetFromContext[*model.User](c, oauth.UserObjKey)
+	ctx := c.Request.Context()
+
+	idStr := c.Param("id")
+	id, err := strconv.ParseUint(idStr, 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, errInvalidTokenID)
+		return
+	}
+
+	var tokenRecord model.AccessToken
+	if err := db.DB(ctx).Where("id = ? AND user_id = ?", id, currUser.ID).First(&tokenRecord).Error; err != nil {
+		response.AbortBadRequest(c, errTokenNotFoundOrForbidden)
+		return
+	}
+
+	// 生成新的 Token
+	newTokenStr, err := model.GenerateTokenString()
+	if err != nil {
+		response.AbortBadRequest(c, errGenerateTokenFailed)
+		return
+	}
+
+	newTokenHash := model.HashToken(newTokenStr)
+	newMaskedToken := model.MaskTokenString(newTokenStr)
+
+	tokenRecord.TokenHash = newTokenHash
+	tokenRecord.MaskedToken = newMaskedToken
+
+	if err := db.DB(ctx).Save(&tokenRecord).Error; err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(tokenResponse{
+		Token:  newTokenStr,
+		Record: tokenRecord,
+	}))
+}

Wavelet/internal/apps/user/constants.go

@@ -0,0 +1,15 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+import "time"
+
+const (
+	verificationCodeRange  = 900000           // 验证码随机范围
+	verificationCodeOffset = 100000           // 验证码偏移量（保证 6 位）
+	emailCodeExpiry        = 5 * time.Minute  // 验证码有效期
+	emailCodeCooldown      = 60 * time.Second // 验证码发送冷却时间
+	minPasswordLength      = 8                // 密码最小长度
+)

Wavelet/internal/apps/user/errs.go

@@ -0,0 +1,47 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+const (
+	errBindParamsFailed             = "参数绑定失败"
+	errInvalidParams                = "无效的参数"
+	errPasswordLoginDisabled        = "管理员关闭了密码登录" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errUsernameOrPasswordWrong      = "用户名或密码错误"   //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errLoginEmailMissing            = "该账号未绑定邮箱，请联系管理员绑定邮箱后再登录"
+	errNeedEmailCodePrefix          = "need_email_code:"
+	errSMTPInvalidUseTempCodePrefix = "smtp_invalid:"
+	errSMTPInvalidUseTempCode       = "smtp 配置无效，使用临时码登录"
+	errEmailCodeInvalidOrExpired    = "验证码错误或已过期"
+	errSaveSessionFailed            = "无法保存会话信息，请重试"
+	errRegistrationDisabled         = "管理员关闭了注册"
+	errPasswordTooShort             = "密码长度不能少于 8 位" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errEmailOrCodeRequired          = "邮箱或验证码未填写"
+	errNewPasswordTooShort          = "新密码长度不能少于 8 位" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errLoginRequired                = "请先登录"
+	errUserNotFound                 = "未找到该用户"
+	errOldPasswordIncorrect         = "原密码不正确"     //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errPasswordEncryptFailed        = "密码加密失败，请重试" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errEmailRequired                = "邮箱地址不能为空"
+	errUnsupportedEmailScene        = "不支持的验证场景"
+	errEmailAlreadyRegistered       = "该邮箱已被注册"
+	errEmailCodeCooldown            = "验证码发送频繁，请稍后再试"
+	errEmailFormatInvalid           = "邮箱格式不正确"
+	errEmailAlreadyBound            = "该邮箱已被其他账号绑定"
+	errRenderEmailTemplateFailed    = "渲染验证邮件模板失败：%w"
+	errGenerateEmailCodeFailed      = "生成验证码失败，请重试"
+	errDispatchEmailTaskFailed      = "投递验证邮件发送任务失败，请重试"
+	errTokenNameRequired            = "令牌名称不能为空"            //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errAccessTokenLimitReached      = "已达到访问令牌最大创建数量限制"     //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errGenerateTokenFailed          = "生成令牌失败"              //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errInvalidTokenID               = "无效的令牌ID"             //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errTokenNotFoundOrForbidden     = "令牌不存在或无权操作"          //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errAdminTokenRequiresAdmin      = "只有管理员才能创建具有管理员权限的令牌" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errTaskPayloadRequired          = "任务参数不能为空"
+	errInvalidJSONFormat            = "无效的 JSON 格式: %w"
+	errEmailTaskFieldsRequired      = "to、subject、body 不能为空"
+	errParseEmailPayloadFailed      = "解析邮件发送参数失败: %w"
+	errSMTPConfigIncomplete         = "系统 SMTP 邮件服务配置不完整"
+	errSendMailFailed               = "发送邮件失败: %w"
+)

Wavelet/internal/apps/user/logics.go

@@ -0,0 +1,287 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"math/big"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/task"
+	pkgu "github.com/Rain-kl/Wavelet/pkg/util"
+)
+
+// LoginEmailVerificationStatus 登录邮箱验证的处理结果。
+type LoginEmailVerificationStatus int
+
+const (
+	// LoginEmailVerificationPassed 验证通过，可继续登录流程。
+	LoginEmailVerificationPassed LoginEmailVerificationStatus = iota
+	// LoginEmailVerificationPending 需要用户输入邮箱验证码。
+	LoginEmailVerificationPending
+	// LoginEmailVerificationRejected 验证被拒绝（验证码错误、临时码提示等）。
+	LoginEmailVerificationRejected
+)
+
+// LoginEmailVerificationResult 登录邮箱验证的业务结果。
+type LoginEmailVerificationResult struct {
+	Status  LoginEmailVerificationStatus
+	Message string
+}
+
+type updateProfileInput struct {
+	Nickname  string
+	Email     string
+	AvatarURL string
+	Bio       string
+	Phone     string
+	Gender    string
+	Website   string
+	Location  string
+}
+
+func isPasswordLoginEnabled(ctx context.Context) bool {
+	enabled, err := repository.GetBoolByKey(ctx, model.ConfigKeyPasswordLoginEnabled)
+	if err != nil {
+		return true
+	}
+	return enabled
+}
+
+func isPasswordRegisterEnabled(ctx context.Context) bool {
+	enabled, err := repository.GetBoolByKey(ctx, model.ConfigKeyPasswordRegisterEnabled)
+	if err != nil {
+		return true
+	}
+	return enabled
+}
+
+func isRegistrationEnabled(ctx context.Context) bool {
+	enabled, err := repository.GetBoolByKey(ctx, model.ConfigKeyRegistrationEnabled)
+	if err != nil {
+		return true
+	}
+	return enabled
+}
+
+func isEmailLoginVerificationEnabled(ctx context.Context) bool {
+	enabled, err := repository.GetBoolByKey(ctx, model.ConfigKeyEmailLoginVerificationEnabled)
+	if err != nil {
+		return false
+	}
+	return enabled
+}
+
+func isEmailRegisterVerificationEnabled(ctx context.Context) bool {
+	enabled, err := repository.GetBoolByKey(ctx, model.ConfigKeyEmailRegisterVerificationEnabled)
+	if err != nil {
+		return false
+	}
+	return enabled
+}
+
+func isSMTPConfigured(ctx context.Context) bool {
+	scHost, errHost := repository.GetSystemConfigByKey(ctx, model.ConfigKeySMTPHost)
+	scPort, errPort := repository.GetSystemConfigByKey(ctx, model.ConfigKeySMTPPort)
+	scUser, errUser := repository.GetSystemConfigByKey(ctx, model.ConfigKeySMTPUsername)
+	scPass, errPass := repository.GetSystemConfigByKey(ctx, model.ConfigKeySMTPPassword)
+	if errHost != nil || errPort != nil || errUser != nil || errPass != nil {
+		return false
+	}
+	return scHost.Value != "" && scPort.Value != "" && scUser.Value != "" && scPass.Value != ""
+}
+
+func generateVerificationCode() (string, error) {
+	n, err := rand.Int(rand.Reader, big.NewInt(verificationCodeRange))
+	if err != nil {
+		return "", err
+	}
+	return fmt.Sprintf("%06d", n.Int64()+verificationCodeOffset), nil
+}
+
+func getEmailCodeKey(scene, email string) string {
+	return fmt.Sprintf("email_code:%s:%s", scene, email)
+}
+
+func getEmailCooldownKey(scene, email string) string {
+	return fmt.Sprintf("email_code:cooldown:%s:%s", scene, email)
+}
+
+func sendEmailVerificationCode(ctx context.Context, email, scene, templateName string) error {
+	if !isSMTPConfigured(ctx) {
+		return errors.New(errSMTPConfigIncomplete)
+	}
+
+	code, err := generateVerificationCode()
+	if err != nil {
+		return errors.New(errGenerateEmailCodeFailed)
+	}
+	codeKey := getEmailCodeKey(scene, email)
+	cooldownKey := getEmailCooldownKey(scene, email)
+
+	tmpl, err := repository.GetTemplateByKey(ctx, templateName)
+	if err != nil {
+		return fmt.Errorf("模板 %s 不存在或不可用: %w", templateName, err)
+	}
+	emailSubject, emailBody, err := tmpl.Render(map[string]any{"Code": code})
+	if err != nil {
+		return fmt.Errorf(errRenderEmailTemplateFailed, err)
+	}
+
+	if err := db.SetJSON(ctx, codeKey, code, emailCodeExpiry); err != nil {
+		return errors.New(errGenerateEmailCodeFailed)
+	}
+	_ = db.SetJSON(ctx, cooldownKey, "1", emailCodeCooldown)
+
+	payload := SendEmailPayload{
+		To:      email,
+		Subject: emailSubject,
+		Body:    emailBody,
+	}
+	payloadBytes, _ := json.Marshal(payload)
+	_, err = task.DispatchTask(ctx, TaskTypeSendEmail, payloadBytes, "system")
+	if err != nil {
+		return errors.New(errDispatchEmailTaskFailed)
+	}
+	return nil
+}
+
+func verifyEmailCode(ctx context.Context, email, scene, code string) bool {
+	codeKey := getEmailCodeKey(scene, email)
+	var storedCode string
+	if err := db.GetJSON(ctx, codeKey, &storedCode); err != nil {
+		return false
+	}
+	if storedCode != code {
+		return false
+	}
+	_ = db.Redis.Del(ctx, db.PrefixedKey(codeKey)).Err()
+	return true
+}
+
+func processLoginEmailVerification(ctx context.Context, code string, user *model.User) (LoginEmailVerificationResult, error) {
+	if code != "" {
+		if !verifyEmailCode(ctx, user.Email, "login", code) {
+			return LoginEmailVerificationResult{
+				Status:  LoginEmailVerificationRejected,
+				Message: errEmailCodeInvalidOrExpired,
+			}, nil
+		}
+		return LoginEmailVerificationResult{Status: LoginEmailVerificationPassed}, nil
+	}
+
+	// 如果 SMTP 未配置，或者用户没有绑定邮箱（无法发送验证码），则使用临时码 888888
+	if !isSMTPConfigured(ctx) || user.Email == "" {
+		codeKey := getEmailCodeKey("login", user.Email)
+		if err := db.SetJSON(ctx, codeKey, "888888", emailCodeExpiry); err != nil {
+			return LoginEmailVerificationResult{}, errors.New(errGenerateEmailCodeFailed)
+		}
+		var msg string
+		if !isSMTPConfigured(ctx) {
+			msg = errSMTPInvalidUseTempCodePrefix + errSMTPInvalidUseTempCode
+		} else {
+			msg = errSMTPInvalidUseTempCodePrefix + "该账号未绑定邮箱，使用临时码登录"
+		}
+		return LoginEmailVerificationResult{
+			Status:  LoginEmailVerificationRejected,
+			Message: msg,
+		}, nil
+	}
+
+	cooldownKey := getEmailCooldownKey("login", user.Email)
+	var temp string
+	if err := db.GetJSON(ctx, cooldownKey, &temp); err != nil {
+		if err := sendEmailVerificationCode(ctx, user.Email, "login", "login_email"); err != nil {
+			return LoginEmailVerificationResult{}, err
+		}
+	}
+
+	maskedEmail := pkgu.MaskEmail(user.Email)
+	return LoginEmailVerificationResult{
+		Status:  LoginEmailVerificationPending,
+		Message: errNeedEmailCodePrefix + maskedEmail,
+	}, nil
+}
+
+func sendRegisterEmailCode(ctx context.Context, email string) error {
+	email = strings.TrimSpace(email)
+	if email == "" {
+		return errors.New(errEmailRequired)
+	}
+
+	var count int64
+	if err := db.DB(ctx).Model(&model.User{}).Where("email = ?", email).Count(&count).Error; err != nil {
+		return err
+	}
+	if count > 0 {
+		return errors.New(errEmailAlreadyRegistered)
+	}
+
+	cooldownKey := getEmailCooldownKey("register", email)
+	var temp string
+	if err := db.GetJSON(ctx, cooldownKey, &temp); err == nil {
+		return errors.New(errEmailCodeCooldown)
+	}
+
+	return sendEmailVerificationCode(ctx, email, "register", "register_email")
+}
+
+func validateRegisterEmailVerification(ctx context.Context, email, code string) error {
+	if !isEmailRegisterVerificationEnabled(ctx) {
+		return nil
+	}
+	if email == "" || code == "" {
+		return errors.New(errEmailOrCodeRequired)
+	}
+	if !verifyEmailCode(ctx, email, "register", code) {
+		return errors.New(errEmailCodeInvalidOrExpired)
+	}
+	return nil
+}
+
+func updateUserProfile(ctx context.Context, userID uint64, input updateProfileInput) (*model.User, error) {
+	var dbUser model.User
+	if err := db.DB(ctx).Where("id = ?", userID).First(&dbUser).Error; err != nil {
+		return nil, errors.New(errUserNotFound)
+	}
+
+	input.Email = strings.TrimSpace(input.Email)
+	if input.Email != "" && input.Email != dbUser.Email {
+		if !strings.Contains(input.Email, "@") || !strings.Contains(input.Email, ".") {
+			return nil, errors.New(errEmailFormatInvalid)
+		}
+
+		var count int64
+		if err := db.DB(ctx).Model(&model.User{}).Where("email = ? AND id != ?", input.Email, dbUser.ID).Count(&count).Error; err != nil {
+			return nil, err
+		}
+		if count > 0 {
+			return nil, errors.New(errEmailAlreadyBound)
+		}
+	}
+
+	dbUser.Nickname = strings.TrimSpace(input.Nickname)
+	if dbUser.Nickname == "" {
+		dbUser.Nickname = dbUser.Username
+	}
+	dbUser.Email = input.Email
+	dbUser.AvatarURL = input.AvatarURL
+	dbUser.Bio = input.Bio
+	dbUser.Phone = strings.TrimSpace(input.Phone)
+	dbUser.Gender = strings.TrimSpace(input.Gender)
+	dbUser.Website = strings.TrimSpace(input.Website)
+	dbUser.Location = strings.TrimSpace(input.Location)
+
+	if err := db.DB(ctx).Save(&dbUser).Error; err != nil {
+		return nil, err
+	}
+	return &dbUser, nil
+}

Wavelet/internal/apps/user/logics_test.go

@@ -0,0 +1,152 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+)
+
+func TestProcessLoginEmailVerificationSMTPFallback(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	const email = "smtpuser@example.com"
+	now := time.Now()
+	user := model.User{
+		ID:          222,
+		Username:    "smtpuser",
+		Nickname:    "SMTP User",
+		Email:       email,
+		IsActive:    true,
+		LastLoginAt: now,
+	}
+	if err := user.SetEncryptedPassword("newpassword123"); err != nil {
+		t.Fatalf("set encrypted password failed: %v", err)
+	}
+	if err := dbConn.Create(&user).Error; err != nil {
+		t.Fatalf("create test user failed: %v", err)
+	}
+
+	if err := dbConn.Model(&model.SystemConfig{}).
+		Where("key = ?", model.ConfigKeySMTPHost).
+		Update("value", "").Error; err != nil {
+		t.Fatalf("clear SMTP host failed: %v", err)
+	}
+	if err := db.Redis.Del(context.Background(), db.PrefixedKey(repository.SystemConfigRedisHashKey)).Err(); err != nil {
+		t.Fatalf("invalidate system config cache failed: %v", err)
+	}
+
+	ctx := context.Background()
+	result, err := processLoginEmailVerification(ctx, "", &user)
+	if err != nil {
+		t.Fatalf("processLoginEmailVerification() error = %v, want nil", err)
+	}
+	expected := errSMTPInvalidUseTempCodePrefix + errSMTPInvalidUseTempCode
+	if result.Status != LoginEmailVerificationRejected || result.Message != expected {
+		t.Fatalf("processLoginEmailVerification() = %+v, want rejected with %q", result, expected)
+	}
+
+	codeKey := getEmailCodeKey("login", email)
+	var storedCode string
+	if err := db.GetJSON(ctx, codeKey, &storedCode); err != nil {
+		t.Fatalf("get stored verification code failed: %v", err)
+	}
+	if storedCode != "888888" {
+		t.Errorf("stored verification code = %q, want %q", storedCode, "888888")
+	}
+
+	passed, err := processLoginEmailVerification(ctx, "888888", &user)
+	if err != nil {
+		t.Fatalf("processLoginEmailVerification(valid code) error = %v, want nil", err)
+	}
+	if passed.Status != LoginEmailVerificationPassed {
+		t.Fatalf("processLoginEmailVerification(valid code) status = %v, want passed", passed.Status)
+	}
+}
+
+func TestProcessLoginEmailVerificationEmptyEmailFallback(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	now := time.Now()
+	user := model.User{
+		ID:          223,
+		Username:    "emptyemailuser",
+		Nickname:    "Empty Email User",
+		Email:       "",
+		IsActive:    true,
+		LastLoginAt: now,
+	}
+	if err := user.SetEncryptedPassword("newpassword123"); err != nil {
+		t.Fatalf("set encrypted password failed: %v", err)
+	}
+	if err := dbConn.Create(&user).Error; err != nil {
+		t.Fatalf("create test user failed: %v", err)
+	}
+
+	for _, cfg := range []struct {
+		key   string
+		value string
+	}{
+		{model.ConfigKeySMTPHost, "smtp.example.com"},
+		{model.ConfigKeySMTPPort, "587"},
+		{model.ConfigKeySMTPUsername, "smtpuser"},
+		{model.ConfigKeySMTPPassword, "smtppassword"},
+	} {
+		if err := dbConn.Model(&model.SystemConfig{}).Where("key = ?", cfg.key).Update("value", cfg.value).Error; err != nil {
+			t.Fatalf("set %s failed: %v", cfg.key, err)
+		}
+	}
+	if err := db.Redis.Del(context.Background(), db.PrefixedKey(repository.SystemConfigRedisHashKey)).Err(); err != nil {
+		t.Fatalf("invalidate system config cache failed: %v", err)
+	}
+
+	ctx := context.Background()
+	result, err := processLoginEmailVerification(ctx, "", &user)
+	if err != nil {
+		t.Fatalf("processLoginEmailVerification() error = %v, want nil", err)
+	}
+	expected := errSMTPInvalidUseTempCodePrefix + "该账号未绑定邮箱，使用临时码登录"
+	if result.Status != LoginEmailVerificationRejected || result.Message != expected {
+		t.Fatalf("processLoginEmailVerification() = %+v, want rejected with %q", result, expected)
+	}
+}
+
+func TestProcessLoginEmailVerificationInvalidCode(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	const email = "codeduser@example.com"
+	now := time.Now()
+	user := model.User{
+		ID:          224,
+		Username:    "codeduser",
+		Email:       email,
+		IsActive:    true,
+		LastLoginAt: now,
+	}
+	if err := dbConn.Create(&user).Error; err != nil {
+		t.Fatalf("create test user failed: %v", err)
+	}
+
+	ctx := context.Background()
+	if err := db.SetJSON(ctx, getEmailCodeKey("login", email), "123456", emailCodeExpiry); err != nil {
+		t.Fatalf("seed verification code failed: %v", err)
+	}
+
+	result, err := processLoginEmailVerification(ctx, "000000", &user)
+	if err != nil {
+		t.Fatalf("processLoginEmailVerification() error = %v, want nil", err)
+	}
+	if result.Status != LoginEmailVerificationRejected || result.Message != errEmailCodeInvalidOrExpired {
+		t.Fatalf("processLoginEmailVerification() = %+v, want rejected invalid code", result)
+	}
+}

Wavelet/internal/apps/user/routers.go

@@ -0,0 +1,439 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	"github.com/Rain-kl/Wavelet/internal/common"
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+	"github.com/Rain-kl/Wavelet/internal/config"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/db/idgen"
+	"github.com/Rain-kl/Wavelet/internal/listener"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-gonic/gin"
+)
+
+type loginRequest struct {
+	Username string `json:"username"`
+	Password string `json:"password"`
+	Code     string `json:"code"`
+}
+
+type registerRequest struct {
+	Username    string `json:"username"`
+	Password    string `json:"password"`
+	Nickname    string `json:"nickname"`
+	DisplayName string `json:"display_name"`
+	Email       string `json:"email"`
+	Code        string `json:"code"`
+}
+
+type sendEmailCodeRequest struct {
+	Email string `json:"email" binding:"required,email"`
+	Scene string `json:"scene" binding:"required"`
+}
+
+type updateProfileRequest struct {
+	Nickname  string `json:"nickname"`
+	Email     string `json:"email"`
+	AvatarURL string `json:"avatar_url"`
+	Bio       string `json:"bio"`
+	Phone     string `json:"phone"`
+	Gender    string `json:"gender"`
+	Website   string `json:"website"`
+	Location  string `json:"location"`
+}
+
+func setLoginSession(ctx context.Context, c *gin.Context, user *model.User) error {
+	session := sessions.Default(c)
+	session.Set(oauth.UserIDKey, user.ID)
+	session.Set(oauth.UserNameKey, user.Username)
+	session.Set(oauth.PasswordHashKey, user.Password)
+
+	// 根据系统配置动态设置 Session 过期时间
+	maxAge := config.Config.App.SessionAge
+	isSessionCookie := false
+
+	ttlHours, err := repository.GetIntByKey(ctx, model.ConfigKeyLoginSessionTTLHours)
+	if err == nil {
+		switch {
+		case ttlHours == -1:
+			// 永不过期，设置为 10 年
+			maxAge = 10 * 365 * 24 * 3600
+		case ttlHours > 0:
+			maxAge = ttlHours * 3600
+		case ttlHours == 0:
+			isSessionCookie = true
+		}
+	}
+	session.Options(oauth.GetSessionOptions(maxAge))
+
+	if err := session.Save(); err != nil {
+		return err
+	}
+
+	if isSessionCookie {
+		oauth.StripCookieMaxAgeAndExpires(c.Writer.Header(), config.Config.App.SessionCookieName)
+	}
+
+	return nil
+}
+
+// Login 用户密码登录
+// @Summary 用户密码登录
+// @Description 使用用户名和密码登录，登录成功后建立 Session。若管理员已关闭密码登录功能则返回错误。
+// @Tags user
+// @Accept json
+// @Produce json
+// @Param request body user.loginRequest true "登录请求参数"
+// @Success 200 {object} response.Any{data=oauth.BasicUserInfo} "登录成功，返回用户信息"
+// @Failure 400 {object} response.Any "用户名或密码错误、帐号已禁用等"
+// @Failure 500 {object} response.Any "服务内部错误"
+// @Router /api/v1/user/login [post]
+func Login(c *gin.Context) {
+	ctx := c.Request.Context()
+	if !isPasswordLoginEnabled(ctx) {
+		response.AbortBadRequest(c, errPasswordLoginDisabled)
+		return
+	}
+	var req loginRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	req.Username = strings.TrimSpace(req.Username)
+	if req.Username == "" || req.Password == "" {
+		response.AbortBadRequest(c, errInvalidParams)
+		return
+	}
+
+	var user model.User
+	if err := db.DB(ctx).Where("username = ? OR email = ?", req.Username, req.Username).First(&user).Error; err != nil {
+		logger.WarnF(ctx, "[LoginAudit] failed login attempt (username not found) for input: %s, IP: %s", req.Username, c.ClientIP())
+		response.AbortBadRequest(c, errUsernameOrPasswordWrong)
+		return
+	}
+	if !user.IsActive {
+		logger.WarnF(ctx, "[LoginAudit] banned user login attempt for username: %s, ID: %d, IP: %s", user.Username, user.ID, c.ClientIP())
+		response.AbortBadRequest(c, common.BannedAccount)
+		return
+	}
+
+	// 判定是否是明文密码存储
+	isPlaintext := !user.IsPasswordEncrypted()
+
+	if !user.CheckPassword(req.Password) {
+		logger.WarnF(ctx, "[LoginAudit] failed login attempt (incorrect password) for username: %s, ID: %d, IP: %s", user.Username, user.ID, c.ClientIP())
+		response.AbortBadRequest(c, errUsernameOrPasswordWrong)
+		return
+	}
+
+	if isEmailLoginVerificationEnabled(ctx) {
+		result, err := processLoginEmailVerification(ctx, req.Code, &user)
+		if err != nil {
+			response.AbortBadRequest(c, err.Error())
+			return
+		}
+		if result.Status != LoginEmailVerificationPassed {
+			response.AbortBadRequest(c, result.Message)
+			return
+		}
+	}
+
+	session := sessions.Default(c)
+	needChangePassword := isPlaintext
+
+	if isPlaintext {
+		session.Set("need_change_password", true)
+	} else {
+		session.Delete("need_change_password")
+	}
+
+	user.LastLoginAt = time.Now()
+	if err := db.DB(ctx).Model(&user).Update("last_login_at", user.LastLoginAt).Error; err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	if err := setLoginSession(ctx, c, &user); err != nil {
+		response.AbortBadRequest(c, errSaveSessionFailed)
+		return
+	}
+
+	logger.InfoF(ctx, "[LoginAudit] successful login for user: %s, ID: %d, IP: %s", user.Username, user.ID, c.ClientIP())
+
+	listener.EmitAdminLoggedIn(ctx, &user, c.ClientIP())
+
+	c.JSON(http.StatusOK, response.OK(oauth.BuildBasicUserInfo(&user, needChangePassword)))
+}
+
+// Register 用户注册
+// @Summary 用户注册
+// @Description 使用用户名和密码注册新账号，注册成功后自动登录并建立 Session。密码长度不能少于 8 位。
+// @Tags user
+// @Accept json
+// @Produce json
+// @Param request body user.registerRequest true "注册请求参数"
+// @Success 200 {object} response.Any{data=oauth.BasicUserInfo} "注册并登录成功，返回用户信息"
+// @Failure 400 {object} response.Any "参数错误、用户名已存在或注册已关闭"
+// @Failure 500 {object} response.Any "服务内部错误"
+// @Router /api/v1/user/register [post]
+func Register(c *gin.Context) {
+	ctx := c.Request.Context()
+	if !isRegistrationEnabled(ctx) || !isPasswordRegisterEnabled(ctx) {
+		response.AbortBadRequest(c, errRegistrationDisabled)
+		return
+	}
+
+	var req registerRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	req.Username = strings.TrimSpace(req.Username)
+	req.Password = strings.TrimSpace(req.Password)
+	req.Nickname = strings.TrimSpace(req.Nickname)
+	req.DisplayName = strings.TrimSpace(req.DisplayName)
+	req.Email = strings.TrimSpace(req.Email)
+	req.Code = strings.TrimSpace(req.Code)
+
+	if req.Username == "" || req.Password == "" {
+		response.AbortBadRequest(c, errInvalidParams)
+		return
+	}
+	if req.Email == "" {
+		response.AbortBadRequest(c, errEmailRequired)
+		return
+	}
+	if len(req.Password) < minPasswordLength {
+		response.AbortBadRequest(c, errPasswordTooShort)
+		return
+	}
+
+	// 邮箱注册验证校验
+	if err := validateRegisterEmailVerification(ctx, req.Email, req.Code); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	user := model.User{
+		ID:          idgen.NextUint64ID(),
+		Username:    req.Username,
+		Nickname:    req.Nickname,
+		Email:       req.Email,
+		AvatarURL:   "",
+		IsActive:    true,
+		IsAdmin:     false,
+		LastLoginAt: time.Now(),
+	}
+	if user.Nickname == "" {
+		user.Nickname = req.DisplayName
+	}
+	if user.Nickname == "" {
+		user.Nickname = req.Username
+	}
+	if err := user.SetEncryptedPassword(req.Password); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if err := user.RegisterUser(ctx, db.DB(ctx)); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if err := setLoginSession(ctx, c, &user); err != nil {
+		response.AbortBadRequest(c, errSaveSessionFailed)
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(oauth.BuildBasicUserInfo(&user, false)))
+}
+
+// Logout 用户退出登录
+// @Summary 用户退出登录
+// @Description 清除用户登录 Session，完成退出
+// @Tags user
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=string} "退出成功"
+// @Failure 500 {object} response.Any "Session 清除失败"
+// @Router /api/v1/user/logout [get]
+func Logout(c *gin.Context) {
+	session := sessions.Default(c)
+	userID := session.Get(oauth.UserIDKey)
+	username := session.Get(oauth.UserNameKey)
+	if userID != nil {
+		logger.InfoF(c.Request.Context(), "[LoginAudit] user logged out: %v, ID: %v, IP: %s", username, userID, c.ClientIP())
+	}
+	session.Options(oauth.GetSessionOptions(-1))
+	session.Clear()
+	if err := session.Save(); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(""))
+}
+
+type changePasswordRequest struct {
+	OldPassword string `json:"old_password"`
+	NewPassword string `json:"new_password"`
+}
+
+// ChangePassword 修改用户密码
+// @Summary 修改用户密码
+// @Description 修改当前登录用户的密码。修改成功后，如果是首次明文登录的升级提示，则清除修改密码的提示状态。
+// @Tags user
+// @Accept json
+// @Produce json
+// @Param request body user.changePasswordRequest true "修改密码请求参数"
+// @Success 200 {object} response.Any{data=string} "修改密码成功"
+// @Failure 400 {object} response.Any "原密码错误或新密码不符合要求"
+// @Failure 401 {object} response.Any "请先登录"
+// @Router /api/v1/user/change-password [post]
+func ChangePassword(c *gin.Context) {
+	var req changePasswordRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	req.OldPassword = strings.TrimSpace(req.OldPassword)
+	req.NewPassword = strings.TrimSpace(req.NewPassword)
+
+	if req.OldPassword == "" || req.NewPassword == "" {
+		response.AbortBadRequest(c, errInvalidParams)
+		return
+	}
+	if len(req.NewPassword) < minPasswordLength {
+		response.AbortBadRequest(c, errNewPasswordTooShort)
+		return
+	}
+
+	userObj, _ := oauth.GetFromContext[*model.User](c, oauth.UserObjKey)
+	if userObj == nil {
+		response.AbortUnauthorized(c, errLoginRequired)
+		return
+	}
+
+	ctx := c.Request.Context()
+	var dbUser model.User
+	if err := db.DB(ctx).Where("id = ?", userObj.ID).First(&dbUser).Error; err != nil {
+		response.AbortBadRequest(c, errUserNotFound)
+		return
+	}
+
+	// 校验旧密码
+	if !dbUser.CheckPassword(req.OldPassword) {
+		response.AbortBadRequest(c, errOldPasswordIncorrect)
+		return
+	}
+
+	// 加密并更新为新密码
+	if err := dbUser.SetEncryptedPassword(req.NewPassword); err != nil {
+		response.AbortBadRequest(c, errPasswordEncryptFailed)
+		return
+	}
+
+	if err := db.DB(ctx).Model(&dbUser).Update("password", dbUser.Password).Error; err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	// 吊销该用户所有的 Access Token
+	if err := db.DB(ctx).Where("user_id = ?", dbUser.ID).Delete(&model.AccessToken{}).Error; err != nil {
+		response.AbortBadRequest(c, "吊销 Access Token 失败: "+err.Error())
+		return
+	}
+
+	// 销毁当前活跃会话以强制重新登录
+	session := sessions.Default(c)
+	session.Clear()
+	_ = session.Save()
+
+	c.JSON(http.StatusOK, response.OK("密码修改成功"))
+}
+
+// SendEmailCode 发送邮箱验证码
+// @Summary 发送邮箱验证码
+// @Description 向指定邮箱发送验证码（用于注册场景）
+// @Tags user
+// @Accept json
+// @Produce json
+// @Param request body user.sendEmailCodeRequest true "发送验证码请求参数"
+// @Success 200 {object} response.Any "发送成功"
+// @Failure 400 {object} response.Any "参数错误"
+// @Router /api/v1/user/send-email-code [post]
+func SendEmailCode(c *gin.Context) {
+	var req sendEmailCodeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	req.Email = strings.TrimSpace(req.Email)
+	if req.Email == "" {
+		response.AbortBadRequest(c, errEmailRequired)
+		return
+	}
+
+	if req.Scene != "register" {
+		response.AbortBadRequest(c, errUnsupportedEmailScene)
+		return
+	}
+
+	ctx := c.Request.Context()
+	if err := sendRegisterEmailCode(ctx, req.Email); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// UpdateProfile 修改当前登录用户的个人资料
+// @Summary 修改当前登录用户的个人资料
+// @Description 修改当前登录用户的昵称、邮箱、头像、简介、电话、性别、个人网站和所在地。
+// @Tags user
+// @Accept json
+// @Produce json
+// @Param request body user.updateProfileRequest true "更新请求参数"
+// @Success 200 {object} response.Any{data=oauth.BasicUserInfo} "修改成功，返回更新后的用户信息"
+// @Failure 400 {object} response.Any "邮箱已被占用或参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Router /api/v1/user/profile [put]
+func UpdateProfile(c *gin.Context) {
+	var req updateProfileRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	userObj, _ := oauth.GetFromContext[*model.User](c, oauth.UserObjKey)
+	if userObj == nil {
+		response.AbortUnauthorized(c, errLoginRequired)
+		return
+	}
+
+	ctx := c.Request.Context()
+	dbUser, err := updateUserProfile(ctx, userObj.ID, updateProfileInput(req))
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	session := sessions.Default(c)
+	needChange := session.Get("need_change_password") == true
+
+	c.JSON(http.StatusOK, response.OK(oauth.BuildBasicUserInfo(dbUser, needChange)))
+}

Wavelet/internal/apps/user/routers_test.go

@@ -0,0 +1,684 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	"github.com/Rain-kl/Wavelet/internal/config"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-contrib/sessions/cookie"
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+func setupUserTestRouter(t *testing.T) *gin.Engine {
+	t.Helper()
+
+	oldCookieName := config.Config.App.SessionCookieName
+	oldSecret := config.Config.App.SessionSecret
+	oldDomain := config.Config.App.SessionDomain
+	oldSecure := config.Config.App.SessionSecure
+	oldHTTPOnly := config.Config.App.SessionHTTPOnly
+	t.Cleanup(func() {
+		config.Config.App.SessionCookieName = oldCookieName
+		config.Config.App.SessionSecret = oldSecret
+		config.Config.App.SessionDomain = oldDomain
+		config.Config.App.SessionSecure = oldSecure
+		config.Config.App.SessionHTTPOnly = oldHTTPOnly
+	})
+
+	config.Config.App.SessionCookieName = "test_session_id"
+	config.Config.App.SessionSecret = "test_session_secret"
+	config.Config.App.SessionDomain = ""
+	config.Config.App.SessionSecure = false
+	config.Config.App.SessionHTTPOnly = true
+
+	store := cookie.NewStore([]byte(config.Config.App.SessionSecret))
+	store.Options(oauth.GetSessionOptions(3600))
+	r := testhelper.NewTestGinEngine(sessions.Sessions(config.Config.App.SessionCookieName, store))
+
+	api := r.Group("/api/v1")
+	api.POST("/user/register", Register)
+	api.POST("/user/login", Login)
+	api.GET("/user-info", oauth.LoginRequired(), oauth.UserInfo)
+	return r
+}
+
+func performUserRequest(r http.Handler, method, path string, body []byte, cookies []*http.Cookie) *httptest.ResponseRecorder {
+	var reader *bytes.Reader
+	if body != nil {
+		reader = bytes.NewReader(body)
+	} else {
+		reader = bytes.NewReader(nil)
+	}
+
+	req, _ := http.NewRequest(method, path, reader)
+	req.Header.Set("Content-Type", "application/json")
+	for _, c := range cookies {
+		req.AddCookie(c)
+	}
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+	return w
+}
+
+func sessionCookieFromResponse(t *testing.T, w *httptest.ResponseRecorder) *http.Cookie {
+	t.Helper()
+
+	for _, c := range w.Result().Cookies() {
+		if c.Name == config.Config.App.SessionCookieName {
+			return c
+		}
+	}
+	t.Fatalf("sessionCookieFromResponse() did not find %q cookie", config.Config.App.SessionCookieName)
+	return nil
+}
+
+func basicUserInfoFromResponse(t *testing.T, w *httptest.ResponseRecorder) oauth.BasicUserInfo {
+	t.Helper()
+
+	var resp response.Any
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("basicUserInfoFromResponse() decode response failed: %v", err)
+	}
+	if resp.ErrorMsg != "" {
+		t.Fatalf("basicUserInfoFromResponse() error_msg = %q, want empty", resp.ErrorMsg)
+	}
+	data, _ := json.Marshal(resp.Data)
+	var info oauth.BasicUserInfo
+	if err := json.Unmarshal(data, &info); err != nil {
+		t.Fatalf("basicUserInfoFromResponse() decode data failed: %v", err)
+	}
+	return info
+}
+
+func TestEmailCooldownKeyIncludesScene(t *testing.T) {
+	email := "user@example.com"
+
+	loginKey := getEmailCooldownKey("login", email)
+	registerKey := getEmailCooldownKey("register", email)
+	if loginKey == registerKey {
+		t.Errorf("getEmailCooldownKey(%q, %q) = %q, want different key from register scene", "login", email, loginKey)
+	}
+	if want := "email_code:cooldown:login:user@example.com"; loginKey != want {
+		t.Errorf("getEmailCooldownKey(%q, %q) = %q, want %q", "login", email, loginKey, want)
+	}
+}
+
+func TestGenerateVerificationCode(t *testing.T) {
+	code, err := generateVerificationCode()
+	if err != nil {
+		t.Fatalf("generateVerificationCode() error = %v, want nil", err)
+	}
+	if len(code) != 6 {
+		t.Fatalf("generateVerificationCode() length = %d, want 6. Code: %q", len(code), code)
+	}
+	for _, r := range code {
+		if r < '0' || r > '9' {
+			t.Fatalf("generateVerificationCode() = %q, want only digits", code)
+		}
+	}
+}
+
+func TestRegisterCreatesAuthenticatedEncryptedUser(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	router := setupUserTestRouter(t)
+	payload := registerRequest{
+		Username: "newuser",
+		Password: "newpassword123",
+		Nickname: "New User",
+		Email:    "newuser@example.com",
+	}
+	body, _ := json.Marshal(payload)
+
+	w := performUserRequest(router, http.MethodPost, "/api/v1/user/register", body, nil)
+	if w.Code != http.StatusOK {
+		t.Fatalf("Register(%q) status = %d, want %d. Body: %s", payload.Username, w.Code, http.StatusOK, w.Body.String())
+	}
+	info := basicUserInfoFromResponse(t, w)
+	if info.NeedChangePassword {
+		t.Errorf("Register(%q) need_change_password = true, want false", payload.Username)
+	}
+
+	var dbUser model.User
+	if err := dbConn.Where("username = ?", payload.Username).First(&dbUser).Error; err != nil {
+		t.Fatalf("Register(%q) db lookup failed: %v", payload.Username, err)
+	}
+	if dbUser.ID < 1000 {
+		t.Errorf("Register(%q) user ID = %d, want generated snowflake ID", payload.Username, dbUser.ID)
+	}
+	if !dbUser.IsPasswordEncrypted() {
+		t.Errorf("Register(%q) stored plaintext password, want encrypted password", payload.Username)
+	}
+	if !dbUser.CheckPassword(payload.Password) {
+		t.Errorf("Register(%q) stored password does not match original password", payload.Username)
+	}
+
+	sessionCookie := sessionCookieFromResponse(t, w)
+	w = performUserRequest(router, http.MethodGet, "/api/v1/user-info", nil, []*http.Cookie{sessionCookie})
+	if w.Code != http.StatusOK {
+		t.Fatalf("UserInfo() after Register(%q) status = %d, want %d. Body: %s", payload.Username, w.Code, http.StatusOK, w.Body.String())
+	}
+}
+
+func TestLoginRequiresPasswordChangeForInitialPlaintextAdmin(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	const (
+		adminID       = uint64(1)
+		adminUsername = "admin"
+		adminPassword = "12345678"
+	)
+	now := time.Now()
+	if err := dbConn.Exec(
+		`INSERT INTO w_users (id, username, password, nickname, is_active, is_admin, last_login_at, created_at, updated_at)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		adminID,
+		adminUsername,
+		adminPassword,
+		"Administrator",
+		true,
+		true,
+		now,
+		now,
+		now,
+	).Error; err != nil {
+		t.Fatalf("seed initial admin failed: %v", err)
+	}
+
+	router := setupUserTestRouter(t)
+	payload := loginRequest{
+		Username: adminUsername,
+		Password: adminPassword,
+	}
+	body, _ := json.Marshal(payload)
+
+	w := performUserRequest(router, http.MethodPost, "/api/v1/user/login", body, nil)
+	if w.Code != http.StatusOK {
+		t.Fatalf("Login(%q) status = %d, want %d. Body: %s", adminUsername, w.Code, http.StatusOK, w.Body.String())
+	}
+	info := basicUserInfoFromResponse(t, w)
+	if !info.NeedChangePassword {
+		t.Errorf("Login(%q) need_change_password = false, want true", adminUsername)
+	}
+
+	var dbUser model.User
+	if err := dbConn.Where("username = ?", adminUsername).First(&dbUser).Error; err != nil {
+		t.Fatalf("Login(%q) db lookup failed: %v", adminUsername, err)
+	}
+	if dbUser.ID != adminID {
+		t.Errorf("Login(%q) user ID = %d, want %d", adminUsername, dbUser.ID, adminID)
+	}
+	if dbUser.IsPasswordEncrypted() {
+		t.Errorf("Login(%q) encrypted password during login, want plaintext until password change", adminUsername)
+	}
+	if !dbUser.CheckPassword(adminPassword) {
+		t.Errorf("Login(%q) stored password does not match original password", adminUsername)
+	}
+
+	sessionCookie := sessionCookieFromResponse(t, w)
+	w = performUserRequest(router, http.MethodGet, "/api/v1/user-info", nil, []*http.Cookie{sessionCookie})
+	if w.Code != http.StatusOK {
+		t.Fatalf("UserInfo() after Login(%q) status = %d, want %d. Body: %s", adminUsername, w.Code, http.StatusOK, w.Body.String())
+	}
+	info = basicUserInfoFromResponse(t, w)
+	if !info.NeedChangePassword {
+		t.Errorf("UserInfo() after Login(%q) need_change_password = false, want true", adminUsername)
+	}
+}
+
+func TestLoginEmailVerificationFallbackWhenSMTPUnconfigured(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	const (
+		userID   = uint64(222)
+		username = "smtpuser"
+		password = "newpassword123"
+		email    = "smtpuser@example.com"
+	)
+	now := time.Now()
+	user := model.User{
+		ID:          userID,
+		Username:    username,
+		Nickname:    "SMTP User",
+		Email:       email,
+		IsActive:    true,
+		IsAdmin:     false,
+		LastLoginAt: now,
+	}
+	if err := user.SetEncryptedPassword(password); err != nil {
+		t.Fatalf("set encrypted password failed: %v", err)
+	}
+	if err := dbConn.Create(&user).Error; err != nil {
+		t.Fatalf("create test user failed: %v", err)
+	}
+
+	// 1. Enable email login verification
+	if err := dbConn.Model(&model.SystemConfig{}).Where("key = ?", model.ConfigKeyEmailLoginVerificationEnabled).Update("value", "true").Error; err != nil {
+		t.Fatalf("enable email login verification failed: %v", err)
+	}
+	// 2. Clear SMTP host to simulate unconfigured SMTP
+	if err := dbConn.Model(&model.SystemConfig{}).Where("key = ?", model.ConfigKeySMTPHost).Update("value", "").Error; err != nil {
+		t.Fatalf("clear SMTP host failed: %v", err)
+	}
+
+	// 2.5 Invalidate the system config cache in Redis
+	if err := db.Redis.Del(context.Background(), db.PrefixedKey(repository.SystemConfigRedisHashKey)).Err(); err != nil {
+		t.Fatalf("invalidate system config cache failed: %v", err)
+	}
+
+	router := setupUserTestRouter(t)
+
+	// 3. Perform login request without verification code
+	payload := loginRequest{
+		Username: username,
+		Password: password,
+	}
+	body, _ := json.Marshal(payload)
+
+	w := performUserRequest(router, http.MethodPost, "/api/v1/user/login", body, nil)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("Login(%q) status = %d, want %d. Body: %s", username, w.Code, http.StatusBadRequest, w.Body.String())
+	}
+
+	// Check response error msg
+	var resp struct {
+		ErrorMsg string `json:"error_msg"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("unmarshal response failed: %v", err)
+	}
+	expectedError := errSMTPInvalidUseTempCodePrefix + errSMTPInvalidUseTempCode
+	if resp.ErrorMsg != expectedError {
+		t.Errorf("expected error %q, got %q", expectedError, resp.ErrorMsg)
+	}
+
+	// 4. Check that verification code stored in Redis is "888888"
+	ctx := context.Background()
+	codeKey := getEmailCodeKey("login", email)
+	var storedCode string
+	if err := db.GetJSON(ctx, codeKey, &storedCode); err != nil {
+		t.Fatalf("get stored verification code failed: %v", err)
+	}
+	if storedCode != "888888" {
+		t.Errorf("expected verification code '888888', got %q", storedCode)
+	}
+
+	// 5. Retry login with code "888888"
+	payload.Code = "888888"
+	bodyWithCode, _ := json.Marshal(payload)
+	w = performUserRequest(router, http.MethodPost, "/api/v1/user/login", bodyWithCode, nil)
+	if w.Code != http.StatusOK {
+		t.Fatalf("Login with code status = %d, want %d. Body: %s", w.Code, http.StatusOK, w.Body.String())
+	}
+
+	var successResp struct {
+		ErrorMsg string `json:"error_msg"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &successResp); err != nil {
+		t.Fatalf("unmarshal success response failed: %v", err)
+	}
+	if successResp.ErrorMsg != "" {
+		t.Errorf("expected login success, got error %q", successResp.ErrorMsg)
+	}
+}
+
+func TestLoginEmailVerificationFallbackForEmptyEmail(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	const (
+		userID   = uint64(223)
+		username = "emptyemailuser"
+		password = "newpassword123"
+		email    = ""
+	)
+	now := time.Now()
+	user := model.User{
+		ID:          userID,
+		Username:    username,
+		Nickname:    "Empty Email User",
+		Email:       email,
+		IsActive:    true,
+		IsAdmin:     true,
+		LastLoginAt: now,
+	}
+	if err := user.SetEncryptedPassword(password); err != nil {
+		t.Fatalf("set encrypted password failed: %v", err)
+	}
+	if err := dbConn.Create(&user).Error; err != nil {
+		t.Fatalf("create test user failed: %v", err)
+	}
+
+	// 1. Enable email login verification
+	if err := dbConn.Model(&model.SystemConfig{}).Where("key = ?", model.ConfigKeyEmailLoginVerificationEnabled).Update("value", "true").Error; err != nil {
+		t.Fatalf("enable email login verification failed: %v", err)
+	}
+	// 2. Make sure SMTP is configured so we only trigger empty email check
+	if err := dbConn.Model(&model.SystemConfig{}).Where("key = ?", model.ConfigKeySMTPHost).Update("value", "smtp.example.com").Error; err != nil {
+		t.Fatalf("set SMTP host failed: %v", err)
+	}
+	if err := dbConn.Model(&model.SystemConfig{}).Where("key = ?", model.ConfigKeySMTPPort).Update("value", "587").Error; err != nil {
+		t.Fatalf("set SMTP port failed: %v", err)
+	}
+	if err := dbConn.Model(&model.SystemConfig{}).Where("key = ?", model.ConfigKeySMTPUsername).Update("value", "smtpuser").Error; err != nil {
+		t.Fatalf("set SMTP username failed: %v", err)
+	}
+	if err := dbConn.Model(&model.SystemConfig{}).Where("key = ?", model.ConfigKeySMTPPassword).Update("value", "smtppassword").Error; err != nil {
+		t.Fatalf("set SMTP password failed: %v", err)
+	}
+
+	// Invalidate the system config cache in Redis
+	if err := db.Redis.Del(context.Background(), db.PrefixedKey(repository.SystemConfigRedisHashKey)).Err(); err != nil {
+		t.Fatalf("invalidate system config cache failed: %v", err)
+	}
+
+	router := setupUserTestRouter(t)
+
+	// 3. Perform login request without verification code
+	payload := loginRequest{
+		Username: username,
+		Password: password,
+	}
+	body, _ := json.Marshal(payload)
+
+	w := performUserRequest(router, http.MethodPost, "/api/v1/user/login", body, nil)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("Login(%q) status = %d, want %d. Body: %s", username, w.Code, http.StatusBadRequest, w.Body.String())
+	}
+
+	// Check response error msg
+	var resp struct {
+		ErrorMsg string `json:"error_msg"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("unmarshal response failed: %v", err)
+	}
+	expectedError := errSMTPInvalidUseTempCodePrefix + "该账号未绑定邮箱，使用临时码登录"
+	if resp.ErrorMsg != expectedError {
+		t.Errorf("expected error %q, got %q", expectedError, resp.ErrorMsg)
+	}
+
+	// 4. Check that verification code stored in Redis is "888888"
+	ctx := context.Background()
+	codeKey := getEmailCodeKey("login", email)
+	var storedCode string
+	if err := db.GetJSON(ctx, codeKey, &storedCode); err != nil {
+		t.Fatalf("get stored verification code failed: %v", err)
+	}
+	if storedCode != "888888" {
+		t.Errorf("expected verification code '888888', got %q", storedCode)
+	}
+
+	// 5. Retry login with code "888888"
+	payload.Code = "888888"
+	bodyWithCode, _ := json.Marshal(payload)
+	w = performUserRequest(router, http.MethodPost, "/api/v1/user/login", bodyWithCode, nil)
+	if w.Code != http.StatusOK {
+		t.Fatalf("Login with code status = %d, want %d. Body: %s", w.Code, http.StatusOK, w.Body.String())
+	}
+
+	var successResp struct {
+		ErrorMsg string `json:"error_msg"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &successResp); err != nil {
+		t.Fatalf("unmarshal success response failed: %v", err)
+	}
+	if successResp.ErrorMsg != "" {
+		t.Errorf("expected login success, got error %q", successResp.ErrorMsg)
+	}
+}
+
+func TestAccessTokenEndpointsDisallowTokenAuth(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	// 1. Seed a user
+	const (
+		userID   = uint64(500)
+		username = "tokenuser"
+		password = "tokenpassword123"
+	)
+	now := time.Now()
+	userRecord := model.User{
+		ID:          userID,
+		Username:    username,
+		Nickname:    "Token User",
+		Email:       "tokenuser@example.com",
+		IsActive:    true,
+		IsAdmin:     true, // Make them an admin so we can test with is_admin=true token requests if needed
+		LastLoginAt: now,
+	}
+	if err := userRecord.SetEncryptedPassword(password); err != nil {
+		t.Fatalf("set encrypted password failed: %v", err)
+	}
+	if err := dbConn.Create(&userRecord).Error; err != nil {
+		t.Fatalf("create test user failed: %v", err)
+	}
+
+	// Seed an active AccessToken for this user
+	tokenStr, err := model.GenerateTokenString()
+	if err != nil {
+		t.Fatalf("generate token string failed: %v", err)
+	}
+	tokenHash := model.HashToken(tokenStr)
+	tokenRecord := model.AccessToken{
+		UserID:      userID,
+		Name:        "Test Token",
+		TokenHash:   tokenHash,
+		MaskedToken: model.MaskTokenString(tokenStr),
+		IsAdmin:     false,
+	}
+	if err := dbConn.Create(&tokenRecord).Error; err != nil {
+		t.Fatalf("create test access token failed: %v", err)
+	}
+
+	// 2. Set up router with access-token routes and oauth middlewares
+	store := cookie.NewStore([]byte("test_session_secret"))
+	r := testhelper.NewTestGinEngine(sessions.Sessions("test_session_id", store))
+
+	apiV1Router := r.Group("/api/v1")
+	userRouter := apiV1Router.Group("/user")
+	tokenRouter := userRouter.Group("/access-tokens")
+	tokenRouter.Use(oauth.LoginRequired(), oauth.DisallowTokenAuth())
+	{
+		tokenRouter.GET("", ListAccessTokens)
+		tokenRouter.POST("", CreateAccessToken)
+		tokenRouter.DELETE("/:id", DeleteAccessToken)
+		tokenRouter.POST("/:id/rotate", RotateAccessToken)
+	}
+
+	// 3. Test that accessing using an Access Token fails with 403 Forbidden
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/user/access-tokens", nil)
+	req.Header.Set("X-Access-Token", tokenStr)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusForbidden {
+		t.Errorf("expected status 403 Forbidden when accessing with Access Token, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	var resp struct {
+		ErrorMsg string `json:"error_msg"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode response failed: %v", err)
+	}
+	if resp.ErrorMsg != oauth.ErrTokenAuthNotAllowed {
+		t.Errorf("expected error message %q, got %q", oauth.ErrTokenAuthNotAllowed, resp.ErrorMsg)
+	}
+
+	// 4. Test that accessing using a Session succeeds
+	sessionCookieStore := cookie.NewStore([]byte("test_session_secret"))
+	rSession := testhelper.NewTestGinEngine(sessions.Sessions("test_session_id", sessionCookieStore))
+	rSession.GET("/api/v1/user/access-tokens", oauth.LoginRequired(), oauth.DisallowTokenAuth(), ListAccessTokens)
+
+	// We can login/register or just mock the session handler to set user ID
+	rSession.GET("/mock-login", func(c *gin.Context) {
+		session := sessions.Default(c)
+		session.Set(oauth.UserIDKey, userID)
+		session.Set(oauth.UserNameKey, username)
+		session.Set(oauth.PasswordHashKey, userRecord.Password)
+		_ = session.Save()
+		c.String(http.StatusOK, "ok")
+	})
+
+	wMock := httptest.NewRecorder()
+	reqMock, _ := http.NewRequest(http.MethodGet, "/mock-login", nil)
+	rSession.ServeHTTP(wMock, reqMock)
+	cookieVal := wMock.Header().Get("Set-Cookie")
+
+	reqSession, _ := http.NewRequest(http.MethodGet, "/api/v1/user/access-tokens", nil)
+	reqSession.Header.Set("Cookie", cookieVal)
+	wSession := httptest.NewRecorder()
+	rSession.ServeHTTP(wSession, reqSession)
+
+	if wSession.Code != http.StatusOK {
+		t.Errorf("expected status 200 OK when accessing with Session, got %d. Body: %s", wSession.Code, wSession.Body.String())
+	}
+}
+
+func TestChangePasswordRevocation(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	// 1. Seed a user with a password
+	user := model.User{
+		ID:       uint64(888),
+		Username: "revoketest",
+		Nickname: "Revoke Test",
+		IsActive: true,
+	}
+	if err := user.SetEncryptedPassword("oldpassword123"); err != nil {
+		t.Fatalf("set encrypted password failed: %v", err)
+	}
+	if err := dbConn.Create(&user).Error; err != nil {
+		t.Fatalf("create test user failed: %v", err)
+	}
+
+	// 2. Seed an active AccessToken for this user
+	tokenStr, err := model.GenerateTokenString()
+	if err != nil {
+		t.Fatalf("generate token string failed: %v", err)
+	}
+	tokenHash := model.HashToken(tokenStr)
+	tokenRecord := model.AccessToken{
+		UserID:      user.ID,
+		Name:        "Test Token",
+		TokenHash:   tokenHash,
+		MaskedToken: model.MaskTokenString(tokenStr),
+	}
+	if err := dbConn.Create(&tokenRecord).Error; err != nil {
+		t.Fatalf("create test access token failed: %v", err)
+	}
+
+	// 3. Set up router
+	store := cookie.NewStore([]byte("test_session_secret"))
+	r := testhelper.NewTestGinEngine(sessions.Sessions("test_session_id", store))
+
+	r.GET("/mock-login", func(c *gin.Context) {
+		session := sessions.Default(c)
+		session.Set(oauth.UserIDKey, user.ID)
+		session.Set(oauth.UserNameKey, user.Username)
+		session.Set(oauth.PasswordHashKey, user.Password)
+		_ = session.Save()
+		c.String(http.StatusOK, "ok")
+	})
+
+	r.GET("/mock-old-session-login", func(c *gin.Context) {
+		session := sessions.Default(c)
+		session.Set(oauth.UserIDKey, user.ID)
+		session.Set(oauth.UserNameKey, user.Username)
+		session.Set(oauth.PasswordHashKey, "invalid_old_password_hash")
+		_ = session.Save()
+		c.String(http.StatusOK, "ok")
+	})
+
+	r.POST("/api/v1/user/change-password", oauth.LoginRequired(), ChangePassword)
+	r.GET("/api/v1/user/access-tokens", oauth.LoginRequired(), ListAccessTokens)
+
+	// 4. Perform mock login to get cookie
+	wMock := httptest.NewRecorder()
+	reqMock, _ := http.NewRequest(http.MethodGet, "/mock-login", nil)
+	r.ServeHTTP(wMock, reqMock)
+	cookieVal := wMock.Header().Get("Set-Cookie")
+
+	// 5. Test that session and token work initially
+	reqSession, _ := http.NewRequest(http.MethodGet, "/api/v1/user/access-tokens", nil)
+	reqSession.Header.Set("Cookie", cookieVal)
+	wSession := httptest.NewRecorder()
+	r.ServeHTTP(wSession, reqSession)
+	if wSession.Code != http.StatusOK {
+		t.Errorf("expected 200, got %d", wSession.Code)
+	}
+
+	reqToken, _ := http.NewRequest(http.MethodGet, "/api/v1/user/access-tokens", nil)
+	reqToken.Header.Set("X-Access-Token", tokenStr)
+	wToken := httptest.NewRecorder()
+	r.ServeHTTP(wToken, reqToken)
+	if wToken.Code != http.StatusOK {
+		t.Errorf("expected 200 for token, got %d", wToken.Code)
+	}
+
+	// 6. Change password using the active session
+	reqBody := `{"old_password": "oldpassword123", "new_password": "newpassword12345"}`
+	reqChange, _ := http.NewRequest(http.MethodPost, "/api/v1/user/change-password", strings.NewReader(reqBody))
+	reqChange.Header.Set("Content-Type", "application/json")
+	reqChange.Header.Set("Cookie", cookieVal)
+	wChange := httptest.NewRecorder()
+	r.ServeHTTP(wChange, reqChange)
+	if wChange.Code != http.StatusOK {
+		t.Fatalf("expected change password to return 200, got %d. Body: %s", wChange.Code, wChange.Body.String())
+	}
+
+	// 7. Verification: The active session that performed change-password is now cleared (401)
+	reqSessionAfter, _ := http.NewRequest(http.MethodGet, "/api/v1/user/access-tokens", nil)
+	reqSessionAfter.Header.Set("Cookie", cookieVal)
+	wSessionAfter := httptest.NewRecorder()
+	r.ServeHTTP(wSessionAfter, reqSessionAfter)
+	if wSessionAfter.Code != http.StatusUnauthorized {
+		t.Errorf("expected session to be revoked (401), got %d", wSessionAfter.Code)
+	}
+
+	// 8. Verification: An old session (holding an outdated password hash) should be rejected (401)
+	wMockOld := httptest.NewRecorder()
+	reqMockOld, _ := http.NewRequest(http.MethodGet, "/mock-old-session-login", nil)
+	r.ServeHTTP(wMockOld, reqMockOld)
+	oldCookieVal := wMockOld.Header().Get("Set-Cookie")
+
+	reqOldSession, _ := http.NewRequest(http.MethodGet, "/api/v1/user/access-tokens", nil)
+	reqOldSession.Header.Set("Cookie", oldCookieVal)
+	wOldSession := httptest.NewRecorder()
+	r.ServeHTTP(wOldSession, reqOldSession)
+	if wOldSession.Code != http.StatusUnauthorized {
+		t.Errorf("expected old session with invalid hash to return 401, got %d", wOldSession.Code)
+	}
+
+	// 9. Verification: The Access Token should be deleted from DB and rejected (401)
+	reqTokenAfter, _ := http.NewRequest(http.MethodGet, "/api/v1/user/access-tokens", nil)
+	reqTokenAfter.Header.Set("X-Access-Token", tokenStr)
+	wTokenAfter := httptest.NewRecorder()
+	r.ServeHTTP(wTokenAfter, reqTokenAfter)
+	if wTokenAfter.Code != http.StatusUnauthorized {
+		t.Errorf("expected access token to be revoked (401), got %d", wTokenAfter.Code)
+	}
+}

Wavelet/internal/apps/user/tasks.go

@@ -0,0 +1,161 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strconv"
+	"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/mail"
+)
+
+// 异步任务名称与管理类型定义
+const (
+	// SendEmailTask 发送邮件任务标识
+	SendEmailTask = "mail:send"
+	// TaskTypeSendEmail 发送邮件管理类型
+	TaskTypeSendEmail = "send_email"
+)
+
+// SendEmailMeta represents the task metadata.
+var SendEmailMeta = task.TaskMeta{
+	Type:         TaskTypeSendEmail,
+	AsynqTask:    SendEmailTask,
+	Name:         "发送邮件",
+	Description:  "异步发送系统邮件",
+	SupportsTime: false,
+	MaxRetry:     task.DefaultMaxRetry,
+	Queue:        task.QueueDefault,
+	Retryable:    true,
+	Params: []task.TaskParam{
+		{
+			Name:        "to",
+			Label:       "接收邮箱 (To)",
+			Type:        "string",
+			Required:    true,
+			Placeholder: "receiver@example.com",
+			Description: "接收邮件的目标邮箱地址",
+		},
+		{
+			Name:        "subject",
+			Label:       "邮件主题 (Subject)",
+			Type:        "string",
+			Required:    true,
+			Placeholder: "请输入邮件主题",
+			Description: "发送邮件的主题标题",
+		},
+		{
+			Name:        "body",
+			Label:       "邮件内容 (Body)",
+			Type:        "text",
+			Required:    true,
+			Placeholder: "请输入邮件内容（支持 HTML 格式）",
+			Description: "发送邮件的内容主体",
+		},
+	},
+}
+
+// SendEmailPayload 邮件发送任务载荷
+type SendEmailPayload struct {
+	To      string `json:"to"`
+	Subject string `json:"subject"`
+	Body    string `json:"body"`
+}
+
+// SendEmailHandler 发送验证码邮件的异步任务处理器
+type SendEmailHandler struct{}
+
+// ValidatePayload 实现 task.PayloadValidator 接口
+// 校验并标准化邮件发送参数，框架在 Admin 下发时自动调用
+func (h *SendEmailHandler) ValidatePayload(payload []byte) ([]byte, error) {
+	if len(payload) == 0 {
+		return nil, errors.New(errTaskPayloadRequired)
+	}
+
+	var req SendEmailPayload
+	if err := json.Unmarshal(payload, &req); err != nil {
+		return nil, fmt.Errorf(errInvalidJSONFormat, err)
+	}
+
+	req.To = strings.TrimSpace(req.To)
+	req.Subject = strings.TrimSpace(req.Subject)
+	req.Body = strings.TrimSpace(req.Body)
+
+	if req.To == "" || req.Subject == "" || req.Body == "" {
+		return nil, errors.New(errEmailTaskFieldsRequired)
+	}
+
+	return json.Marshal(req)
+}
+
+// Execute 执行邮件异步发送逻辑
+func (h *SendEmailHandler) Execute(ctx context.Context, payload []byte) (*task.TaskResult, error) {
+	var req SendEmailPayload
+	if err := json.Unmarshal(payload, &req); err != nil {
+		task.AppendLog(ctx, "解析邮件发送参数失败: %v", err)
+		return nil, fmt.Errorf(errParseEmailPayloadFailed, err)
+	}
+
+	task.AppendLog(ctx, "开始准备发送邮件到: %s, 主题: %s", req.To, req.Subject)
+
+	// 从数据库读取最新的 SMTP 系统配置
+	var smtpHost string
+	var smtpPortVal string
+	var smtpUsername string
+	var smtpPassword string
+
+	if sc, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeySMTPHost); err == nil {
+		smtpHost = sc.Value
+	}
+	if sc, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeySMTPPort); err == nil {
+		smtpPortVal = sc.Value
+	}
+	if sc, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeySMTPUsername); err == nil {
+		smtpUsername = sc.Value
+	}
+	if sc, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeySMTPPassword); err == nil {
+		smtpPassword = sc.Value
+	}
+
+	if smtpHost == "" || smtpPortVal == "" || smtpUsername == "" {
+		err := errors.New(errSMTPConfigIncomplete)
+		task.AppendLog(ctx, "发送失败: %v", err)
+		return nil, err
+	}
+
+	smtpPort, err := strconv.Atoi(smtpPortVal)
+	if err != nil {
+		smtpPort = 587
+	}
+
+	cfg := mail.Config{
+		Host:     smtpHost,
+		Port:     smtpPort,
+		Username: smtpUsername,
+		Password: smtpPassword,
+	}
+
+	task.AppendLog(ctx, "连接 SMTP 服务器: %s:%d, 用户名: %s", smtpHost, smtpPort, smtpUsername)
+
+	// 调用 SendMailHTML 执行邮件发送，这里会有 5s 拨号超时和 10s 读写限制
+	err = mail.SendMailHTML(ctx, cfg, req.To, req.Subject, req.Body)
+	if err != nil {
+		task.AppendLog(ctx, "邮件发送失败: %v", err)
+		return nil, fmt.Errorf(errSendMailFailed, err)
+	}
+
+	msg := fmt.Sprintf("邮件成功发送至: %s", req.To)
+	task.AppendLog(ctx, "%s", msg)
+
+	return &task.TaskResult{
+		Message: msg,
+	}, nil
+}

Wavelet/internal/bootstrap/bootstrap.go

@@ -0,0 +1,93 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package bootstrap wires cross-module integrations and process-level subsystem initialization.
+// All registrations use sync.Once so entry points can call them safely without import-order side effects.
+package bootstrap
+
+import (
+	"context"
+	"sync"
+
+	admin_push "github.com/Rain-kl/Wavelet/internal/apps/admin/push"
+	"github.com/Rain-kl/Wavelet/internal/apps/admin/push/custom_events"
+	"github.com/Rain-kl/Wavelet/internal/apps/risk_control"
+	taskhandlers "github.com/Rain-kl/Wavelet/internal/task/handlers"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+)
+
+// Options selects role-specific runtime bootstrap steps for the current process.
+type Options struct {
+	// API enables HTTP-only subsystems such as the ClickHouse access-log writer.
+	API bool
+}
+
+var (
+	registerTasksOnce            sync.Once
+	registerPushDomainEventsOnce sync.Once
+	registerTaskListenersOnce    sync.Once
+	initRuntimeOnce              sync.Once
+)
+
+// RegisterTasks registers all built-in task handlers and metadata.
+func RegisterTasks() {
+	registerTasksOnce.Do(func() {
+		taskhandlers.Register()
+	})
+}
+
+// RegisterPushDomainEvents wires push notification handlers for domain events.
+func RegisterPushDomainEvents() {
+	registerPushDomainEventsOnce.Do(func() {
+		custom_events.Register()
+	})
+}
+
+// RegisterTaskListeners wires operational listeners to task framework hooks.
+func RegisterTaskListeners() {
+	registerTaskListenersOnce.Do(func() {
+		admin_push.RegisterTaskListeners()
+	})
+}
+
+// RegisterAPI wires integrations required by the HTTP API process.
+func RegisterAPI() {
+	RegisterTasks()
+	RegisterPushDomainEvents()
+}
+
+// RegisterWorker wires integrations required by the task worker process.
+func RegisterWorker() {
+	RegisterTasks()
+	RegisterTaskListeners()
+}
+
+// RegisterScheduler wires integrations required by the task scheduler process.
+func RegisterScheduler() {
+	RegisterTasks()
+}
+
+// RegisterAll wires integrations for fused mode (API + Worker + Scheduler).
+func RegisterAll() {
+	RegisterTasks()
+	RegisterPushDomainEvents()
+	RegisterTaskListeners()
+}
+
+// Init runs shared runtime bootstrap exactly once per process.
+// Call from cmd entry points after wiring registration and database migration, not from router.
+func Init(ctx context.Context, opts Options) {
+	initRuntimeOnce.Do(func() {
+		if err := admin_push.SyncEvents(ctx); err != nil {
+			logger.ErrorF(ctx, "[Bootstrap] sync push events failed: %v", err)
+		}
+		if opts.API {
+			risk_control.InitLogWriter(ctx)
+		}
+	})
+}
+
+// ResetInitRuntimeOnceForTest clears initRuntimeOnce so Init can run again in unit tests.
+func ResetInitRuntimeOnceForTest() {
+	initRuntimeOnce = sync.Once{}
+}

Wavelet/internal/bootstrap/bootstrap_test.go

@@ -0,0 +1,52 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package bootstrap
+
+import (
+	"context"
+	"testing"
+
+	admin_push "github.com/Rain-kl/Wavelet/internal/apps/admin/push"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+)
+
+func TestInitSyncsPushEventsOnce(t *testing.T) {
+	ResetInitRuntimeOnceForTest()
+	t.Cleanup(ResetInitRuntimeOnceForTest)
+
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	if err := dbConn.AutoMigrate(&model.PushEvent{}); err != nil {
+		t.Fatalf("auto migrate push events failed: %v", err)
+	}
+
+	RegisterPushDomainEvents()
+
+	wantCount := len(admin_push.BuiltInEvents)
+	if wantCount < 1 {
+		t.Fatalf("built-in push events = %d, want at least 1", wantCount)
+	}
+
+	ctx := context.Background()
+	Init(ctx, Options{API: true})
+	Init(ctx, Options{}) // second Init must not duplicate events (initRuntimeOnce)
+
+	var count int64
+	if err := dbConn.Model(&model.PushEvent{}).Count(&count).Error; err != nil {
+		t.Fatalf("count push events failed: %v", err)
+	}
+	if count != int64(wantCount) {
+		t.Fatalf("push event count = %d, want %d", count, wantCount)
+	}
+
+	var adminLogin model.PushEvent
+	if err := dbConn.Where("event_key = ?", "admin_login").First(&adminLogin).Error; err != nil {
+		t.Fatalf("admin_login event not found after Init: %v", err)
+	}
+	if adminLogin.Name != "管理员登录" {
+		t.Fatalf("admin_login name = %q, want %q", adminLogin.Name, "管理员登录")
+	}
+}

Wavelet/internal/buildinfo/buildinfo.go

@@ -0,0 +1,12 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package buildinfo exposes metadata injected by the release workflow.
+package buildinfo
+
+var (
+	// Version is the application version.
+	Version = "dev"
+	// BuildTime is the UTC release build timestamp.
+	BuildTime = ""
+)

Wavelet/internal/cmd/all.go

@@ -0,0 +1,59 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package cmd 提供 CLI 命令入口
+package cmd
+
+import (
+	"log"
+	"sync"
+
+	"github.com/Rain-kl/Wavelet/internal/bootstrap"
+	"github.com/Rain-kl/Wavelet/internal/router"
+	"github.com/Rain-kl/Wavelet/internal/task/scheduler"
+	"github.com/Rain-kl/Wavelet/internal/task/worker"
+	"github.com/spf13/cobra"
+)
+
+var allCmd = &cobra.Command{
+	Use:   "all",
+	Short: "以融合模式同时启动 API、Worker 和 Scheduler",
+	Run: func(_ *cobra.Command, _ []string) {
+		log.Println("[All] 融合模式启动")
+		bootstrap.RegisterAll()
+		runBootstrap(bootstrap.Options{API: true})
+
+		var wg sync.WaitGroup
+
+		// 启动 API HTTP 服务
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			log.Println("[All] 启动 API 服务")
+			router.Serve()
+		}()
+
+		// 启动 Asynq Worker 任务处理服务
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			log.Println("[All] 启动 Worker 服务")
+			if err := worker.StartWorker(); err != nil {
+				log.Printf("[All] Worker 启动失败: %v\n", err)
+			}
+		}()
+
+		// 启动 Asynq 定时任务调度器
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			log.Println("[All] 启动 Scheduler 服务")
+			if err := scheduler.StartScheduler(); err != nil {
+				log.Printf("[All] Scheduler 启动失败: %v\n", err)
+			}
+		}()
+
+		wg.Wait()
+	},
+}

Wavelet/internal/cmd/api.go

@@ -0,0 +1,21 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"github.com/Rain-kl/Wavelet/internal/bootstrap"
+	"github.com/Rain-kl/Wavelet/internal/router"
+	"github.com/spf13/cobra"
+)
+
+var apiCmd = &cobra.Command{
+	Use:   "api",
+	Short: "wavelet API",
+	Run: func(_ *cobra.Command, _ []string) {
+		bootstrap.RegisterAPI()
+		runBootstrap(bootstrap.Options{API: true})
+		router.Serve()
+	},
+}

Wavelet/internal/cmd/bootstrap.go

@@ -0,0 +1,17 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"context"
+
+	"github.com/Rain-kl/Wavelet/internal/bootstrap"
+	"github.com/Rain-kl/Wavelet/pkg/trace"
+)
+
+func runBootstrap(opts bootstrap.Options) {
+	ctx, span := trace.Start(context.Background(), "bootstrap.Init")
+	defer span.End()
+	bootstrap.Init(ctx, opts)
+}

Wavelet/internal/cmd/root.go

@@ -0,0 +1,85 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"context"
+	"log"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/buildinfo"
+	"github.com/Rain-kl/Wavelet/internal/config"
+	"github.com/Rain-kl/Wavelet/internal/db/migrator"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"github.com/Rain-kl/Wavelet/pkg/trace"
+	"github.com/spf13/cobra"
+)
+
+const traceShutdownTimeout = 10 * time.Second
+
+var rootCmd = &cobra.Command{
+	Use: "wavelet",
+	PersistentPreRun: func(_ *cobra.Command, _ []string) {
+		logger.Init(logger.Config{
+			Level:      config.Config.Log.Level,
+			Format:     config.Config.Log.Format,
+			Output:     config.Config.Log.Output,
+			FilePath:   config.Config.Log.FilePath,
+			MaxSize:    config.Config.Log.MaxSize,
+			MaxAge:     config.Config.Log.MaxAge,
+			MaxBackups: config.Config.Log.MaxBackups,
+			Compress:   config.Config.Log.Compress,
+		})
+		trace.Init(trace.Config{
+			AppName:      config.Config.App.AppName,
+			SamplingRate: config.Config.Otel.SamplingRate,
+			TracerName:   config.Config.Otel.TracerName,
+		})
+	},
+	PreRun: func(_ *cobra.Command, _ []string) {
+		migrator.Migrate()
+	},
+	PersistentPostRun: func(_ *cobra.Command, _ []string) {
+		shutdownTraceProvider()
+	},
+	Run: func(_ *cobra.Command, args []string) {
+		// 无参数时默认以融合模式启动所有服务
+		if len(args) == 0 {
+			allCmd.Run(allCmd, args)
+			return
+		}
+		appMode := args[0]
+		switch appMode {
+		case "api":
+			apiCmd.Run(apiCmd, args)
+		case "scheduler":
+			schedulerCmd.Run(schedulerCmd, args)
+		case "worker":
+			workerCmd.Run(workerCmd, args)
+		case "all":
+			allCmd.Run(allCmd, args)
+		default:
+			log.Fatal("[CMD] unknown app mode\n")
+		}
+	},
+}
+
+func shutdownTraceProvider() {
+	ctx, cancel := context.WithTimeout(context.Background(), traceShutdownTimeout)
+	defer cancel()
+	trace.Shutdown(ctx)
+}
+
+func init() {
+	rootCmd.Version = buildinfo.Version
+	rootCmd.CompletionOptions.DisableDefaultCmd = true
+}
+
+// Execute 执行根命令
+func Execute() {
+	if err := rootCmd.Execute(); err != nil {
+		log.Fatalf("[CMD] execute failed; %s\n", err)
+	}
+}

Wavelet/internal/cmd/scheduler.go

@@ -0,0 +1,26 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"log"
+
+	"github.com/Rain-kl/Wavelet/internal/bootstrap"
+	"github.com/Rain-kl/Wavelet/internal/task/scheduler"
+
+	"github.com/spf13/cobra"
+)
+
+var schedulerCmd = &cobra.Command{
+	Use:   "scheduler",
+	Short: "wavelet Scheduler",
+	Run: func(_ *cobra.Command, _ []string) {
+		runBootstrap(bootstrap.Options{})
+		log.Println("[Scheduler] 启动定时任务调度服务")
+		if err := scheduler.StartScheduler(); err != nil {
+			log.Fatalf("[调度器] 启动失败: %v", err)
+		}
+	},
+}

Wavelet/internal/cmd/worker.go

@@ -0,0 +1,26 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"log"
+
+	"github.com/Rain-kl/Wavelet/internal/bootstrap"
+	"github.com/Rain-kl/Wavelet/internal/task/worker"
+
+	"github.com/spf13/cobra"
+)
+
+var workerCmd = &cobra.Command{
+	Use:   "worker",
+	Short: "wavelet Worker",
+	Run: func(_ *cobra.Command, _ []string) {
+		runBootstrap(bootstrap.Options{})
+		log.Println("[Worker] 启动任务处理服务")
+		if err := worker.StartWorker(); err != nil {
+			log.Fatalf("[工作器] 启动失败: %v", err)
+		}
+	},
+}

Wavelet/internal/common/constants.go

@@ -0,0 +1,6 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package common 提供跨模块共享的常量、错误定义和通用工具函数。
+package common

Wavelet/internal/common/errs.go

@@ -0,0 +1,11 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package common
+
+// 通用业务错误消息常量
+const (
+	BannedAccount = "账号已被封禁"
+	UnAuthorized  = "未登录"
+)

Wavelet/internal/common/response/abort.go

@@ -0,0 +1,45 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package response
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+// AbortBadRequest 以 400 中断请求并将错误挂载到 Gin Error 链，供全局中间件统一记录 Trace 并响应。
+func AbortBadRequest(c *gin.Context, msg string) {
+	AbortWithError(c, http.StatusBadRequest, msg)
+}
+
+// AbortUnauthorized 以 401 中断请求并将错误挂载到 Gin Error 链。
+func AbortUnauthorized(c *gin.Context, msg string) {
+	AbortWithError(c, http.StatusUnauthorized, msg)
+}
+
+// AbortForbidden 以 403 中断请求并将错误挂载到 Gin Error 链。
+func AbortForbidden(c *gin.Context, msg string) {
+	AbortWithError(c, http.StatusForbidden, msg)
+}
+
+// AbortNotFound 以 404 中断请求并将错误挂载到 Gin Error 链。
+func AbortNotFound(c *gin.Context, msg string) {
+	AbortWithError(c, http.StatusNotFound, msg)
+}
+
+// AbortInternal 以 500 中断请求并将错误挂载到 Gin Error 链。
+func AbortInternal(c *gin.Context, msg string) {
+	AbortWithError(c, http.StatusInternalServerError, msg)
+}
+
+// AbortTooManyRequests 以 429 中断请求并将错误挂载到 Gin Error 链。
+func AbortTooManyRequests(c *gin.Context, msg string) {
+	AbortWithError(c, http.StatusTooManyRequests, msg)
+}
+
+// AbortConflict 以 409 中断请求并将错误挂载到 Gin Error 链。
+func AbortConflict(c *gin.Context, msg string) {
+	AbortWithError(c, http.StatusConflict, msg)
+}

Wavelet/internal/common/response/middleware.go

@@ -0,0 +1,40 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package response
+
+import (
+	"errors"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"go.opentelemetry.io/otel/codes"
+	"go.opentelemetry.io/otel/trace"
+)
+
+// ErrorHandlerMiddleware 捕获 c.Errors 并统一格式化为 JSON 返回给客户端，同时将其记录到 Span 异常中。
+// 与 AbortWithError / AbortBadRequest 等配合使用，是全局 OTel 友好错误响应的唯一出口。
+func ErrorHandlerMiddleware() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		c.Next()
+
+		if len(c.Errors) == 0 || c.Writer.Written() {
+			return
+		}
+
+		err := c.Errors.Last().Err
+		span := trace.SpanFromContext(c.Request.Context())
+		if span.IsRecording() {
+			span.RecordError(err)
+			span.SetStatus(codes.Error, err.Error())
+		}
+
+		var apiErr *APIError
+		if errors.As(err, &apiErr) {
+			c.JSON(apiErr.Code, Err(apiErr.Msg))
+			return
+		}
+
+		c.JSON(http.StatusInternalServerError, Err("内部系统错误"))
+	}
+}

Wavelet/internal/common/response/middleware_test.go

@@ -0,0 +1,168 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package response
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/codes"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	"go.opentelemetry.io/otel/sdk/trace/tracetest"
+	"go.opentelemetry.io/otel/trace"
+)
+
+func init() {
+	gin.SetMode(gin.TestMode)
+}
+
+func TestAbortWithError(t *testing.T) {
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+
+	AbortWithError(c, http.StatusBadRequest, "invalid input")
+
+	require.Len(t, c.Errors, 1)
+
+	var apiErr *APIError
+	require.True(t, errors.As(c.Errors.Last().Err, &apiErr))
+	assert.Equal(t, http.StatusBadRequest, apiErr.Code)
+	assert.Equal(t, "invalid input", apiErr.Msg)
+	assert.True(t, c.IsAborted())
+}
+
+func TestErrorHandlerMiddleware_APIErrorStatusCodes(t *testing.T) {
+	cases := []struct {
+		name       string
+		statusCode int
+		message    string
+		abort      func(*gin.Context, string)
+	}{
+		{"400 Bad Request", http.StatusBadRequest, "bad request", AbortBadRequest},
+		{"401 Unauthorized", http.StatusUnauthorized, "unauthorized", AbortUnauthorized},
+		{"403 Forbidden", http.StatusForbidden, "forbidden", AbortForbidden},
+		{"404 Not Found", http.StatusNotFound, "not found", AbortNotFound},
+		{"409 Conflict", http.StatusConflict, "conflict", AbortConflict},
+		{"429 Too Many Requests", http.StatusTooManyRequests, "too many requests", AbortTooManyRequests},
+		{"500 Internal Server Error", http.StatusInternalServerError, "internal error", AbortInternal},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			r := gin.New()
+			r.Use(ErrorHandlerMiddleware())
+			r.GET("/test", func(c *gin.Context) {
+				tc.abort(c, tc.message)
+			})
+
+			req := httptest.NewRequest(http.MethodGet, "/test", nil)
+			w := httptest.NewRecorder()
+			r.ServeHTTP(w, req)
+
+			assert.Equal(t, tc.statusCode, w.Code)
+			assert.Equal(t, "application/json; charset=utf-8", w.Header().Get("Content-Type"))
+
+			var body Response[any]
+			require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body))
+			assert.Equal(t, tc.message, body.ErrorMsg)
+			assert.Nil(t, body.Data)
+		})
+	}
+}
+
+func TestErrorHandlerMiddleware_SkipsWhenNoErrors(t *testing.T) {
+	r := gin.New()
+	r.Use(ErrorHandlerMiddleware())
+	r.GET("/ok", func(c *gin.Context) {
+		c.JSON(http.StatusOK, OK("success"))
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/ok", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	var body Response[string]
+	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body))
+	assert.Equal(t, "success", body.Data)
+	assert.Empty(t, body.ErrorMsg)
+}
+
+func TestErrorHandlerMiddleware_SkipsWhenResponseAlreadyWritten(t *testing.T) {
+	r := gin.New()
+	r.Use(ErrorHandlerMiddleware())
+	r.GET("/written", func(c *gin.Context) {
+		c.JSON(http.StatusOK, OKNil())
+		_ = c.Error(NewError(http.StatusBadRequest, "should not overwrite"))
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/written", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	var body Response[any]
+	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body))
+	assert.Empty(t, body.ErrorMsg)
+	assert.Nil(t, body.Data)
+}
+
+func TestErrorHandlerMiddleware_FallbackForNonAPIError(t *testing.T) {
+	r := gin.New()
+	r.Use(ErrorHandlerMiddleware())
+	r.GET("/plain", func(c *gin.Context) {
+		_ = c.Error(errors.New("plain error"))
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/plain", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusInternalServerError, w.Code)
+
+	var body Response[any]
+	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body))
+	assert.Equal(t, "内部系统错误", body.ErrorMsg)
+	assert.Nil(t, body.Data)
+}
+
+func TestErrorHandlerMiddleware_RecordsSpanOnAPIError(t *testing.T) {
+	sr := tracetest.NewSpanRecorder()
+	tp := sdktrace.NewTracerProvider(sdktrace.WithSpanProcessor(sr))
+	otel.SetTracerProvider(tp)
+	defer otel.SetTracerProvider(trace.NewNoopTracerProvider())
+
+	tracer := tp.Tracer("test")
+	ctx, span := tracer.Start(context.Background(), "request")
+
+	r := gin.New()
+	r.Use(ErrorHandlerMiddleware())
+	r.GET("/err", func(c *gin.Context) {
+		c.Request = c.Request.WithContext(ctx)
+		AbortBadRequest(c, "bad request")
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/err", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+	span.End()
+
+	require.Equal(t, http.StatusBadRequest, w.Code)
+
+	spans := sr.Ended()
+	require.Len(t, spans, 1)
+	assert.Equal(t, codes.Error, spans[0].Status().Code)
+	assert.Equal(t, "bad request", spans[0].Status().Description)
+	require.NotEmpty(t, spans[0].Events())
+}

Wavelet/internal/common/response/response.go

@@ -0,0 +1,57 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package response provides shared HTTP API response structures.
+package response
+
+import "github.com/gin-gonic/gin"
+
+// Response 通用响应体
+type Response[T any] struct {
+	ErrorMsg string `json:"error_msg"`
+	Data     T      `json:"data"`
+}
+
+// Any 用于 Swagger 文档的响应类型（非泛型）
+// swag 不支持泛型，使用此类型替代 Response[T]
+type Any struct {
+	ErrorMsg string      `json:"error_msg" example:""`
+	Data     interface{} `json:"data"`
+}
+
+// APIError 统一的 API 业务错误类型，可被全局错误处理中间件捕获
+type APIError struct {
+	Code int
+	Msg  string
+}
+
+func (e *APIError) Error() string {
+	return e.Msg
+}
+
+// NewError 实例化一个 APIError
+func NewError(code int, msg string) *APIError {
+	return &APIError{Code: code, Msg: msg}
+}
+
+// AbortWithError 将 API 错误挂载到 Gin Context 并中断执行流
+func AbortWithError(c *gin.Context, code int, msg string) {
+	_ = c.Error(NewError(code, msg))
+	c.Abort()
+}
+
+// OK 构造成功响应
+func OK[T any](data T) Response[T] {
+	return Response[T]{Data: data}
+}
+
+// OKNil 构造成功响应（data 为 null）
+func OKNil() Response[any] {
+	return Response[any]{Data: nil}
+}
+
+// Err 构造错误响应
+func Err(msg string) Response[any] {
+	return Response[any]{ErrorMsg: msg, Data: nil}
+}