refactor(plugins): restructure admin and message_gateway into standard layered sub-packages

backend/plugins/domain/admin/handler/auth_source.go

@@ -0,0 +1,106 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/response"
+	"Wavelet/plugins/domain/admin/errs"
+	"Wavelet/plugins/domain/admin/service"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+)
+
+// ListAuthSources lists all configured authentication sources.
+func ListAuthSources(c *gin.Context) {
+	views, err := service.ListAuthSources(c.Request.Context())
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(views))
+}
+
+// CreateAuthSource creates a new authentication source.
+func CreateAuthSource(c *gin.Context) {
+	var source contracts.AuthSourceDTO
+	if err := c.ShouldBindJSON(&source); err != nil {
+		response.AbortBadRequest(c, errs.InvalidParams)
+		return
+	}
+
+	created, err := service.CreateAuthSource(c.Request.Context(), source)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(created))
+}
+
+// UpdateAuthSource updates an authentication source.
+func UpdateAuthSource(c *gin.Context) {
+	id, ok := parseAuthSourceID(c)
+	if !ok {
+		return
+	}
+
+	var req contracts.AuthSourceDTO
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, errs.InvalidParams)
+		return
+	}
+
+	updated, err := service.UpdateAuthSource(c.Request.Context(), id, req)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(updated))
+}
+
+// ToggleAuthSource toggles the active state of an auth source.
+func ToggleAuthSource(c *gin.Context) {
+	id, ok := parseAuthSourceID(c)
+	if !ok {
+		return
+	}
+
+	toggled, err := service.ToggleAuthSource(c.Request.Context(), id)
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(gin.H{"is_active": toggled.IsActive}))
+}
+
+// DeleteAuthSource deletes an authentication source.
+func DeleteAuthSource(c *gin.Context) {
+	id, ok := parseAuthSourceID(c)
+	if !ok {
+		return
+	}
+
+	if err := service.DeleteAuthSource(c.Request.Context(), id); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// parseAuthSourceID reads the numeric auth source path parameter.
+func parseAuthSourceID(c *gin.Context) (uint64, bool) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, errs.ErrInvalidAuthSourceID)
+		return 0, false
+	}
+	return id, true
+}

backend/plugins/domain/admin/handler/cache.go

@@ -0,0 +1,76 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"Wavelet/pkg/response"
+	"Wavelet/plugins/domain/admin/model"
+	"Wavelet/plugins/domain/admin/service"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+// GetCacheStatus 获取磁盘缓存状态与当前统计数据
+// @Summary 获取缓存状态
+// @Description 获取当前系统磁盘缓存的使用情况（已占用字节、Key 数量等）与策略配置
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=disk.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) {
+	c.JSON(http.StatusOK, response.OK(service.DiskCacheStatus()))
+}
+
+// UpdateCacheConfig 更新磁盘缓存策略配置
+// @Summary 更新缓存配置
+// @Description 更改磁盘缓存最大容量限制、文件生存时间（TTL）以及是否启用 LRU 淘汰淘汰算法，并进行热更新
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Param request body model.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 model.UpdateCacheConfigRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if err := service.UpdateDiskCachePolicy(c.Request.Context(), req); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	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 := service.ClearDiskCache(); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}

backend/plugins/domain/admin/handler/config.go

@@ -0,0 +1,187 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"Wavelet/pkg/response"
+	"Wavelet/plugins/domain/admin/errs"
+	"Wavelet/plugins/domain/admin/model"
+	"Wavelet/plugins/domain/admin/service"
+	"errors"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+// 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) {
+	resp, err := service.PublicSystemConfigs(c.Request.Context())
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	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) {
+	c.Data(http.StatusOK, "text/plain; charset=utf-8", []byte(service.RobotsTxtBody(c.Request.Context())))
+}
+
+// CreateSystemConfig 创建系统配置
+// @Summary 创建系统配置
+// @Description 创建一条新的系统配置项，配置键不可重复，同时将新配置同步到 Redis，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body model.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 model.CreateSystemConfigRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if err := service.CreateAdminSystemConfig(c.Request.Context(), req); err != nil {
+		if errors.Is(err, errs.ErrProtectedConfigKey) || errors.Is(err, errs.ErrConfigKeyExists) {
+			response.AbortBadRequest(c, err.Error())
+			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 := service.ListAdminSystemConfigs(c.Request.Context(), c.Query("type"))
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	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 := service.GetAdminSystemConfig(c.Request.Context(), c.Param("key"))
+	if err != nil {
+		if errors.Is(err, errs.ErrSystemConfigNotFound) {
+			response.AbortNotFound(c, errs.SystemConfigNotFound)
+			return
+		}
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	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 model.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 model.UpdateSystemConfigRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	key := c.Param("key")
+	if err := service.UpdateAdminSystemConfig(c.Request.Context(), key, req); err != nil {
+		if errors.Is(err, errs.ErrSystemConfigNotFound) {
+			response.AbortNotFound(c, errs.SystemConfigNotFound)
+			return
+		}
+		if errors.Is(err, errs.ErrProtectedConfigKey) || errs.IsStorageConfigValidationError(err) {
+			response.AbortBadRequest(c, err.Error())
+			return
+		}
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// TestSMTP 测试 SMTP 邮件发送
+// @Summary 测试 SMTP 邮件发送
+// @Description 使用传入的配置进行 SMTP 邮件发送测试，支持使用 ****** 占位符使用保存的数据库密码
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body model.TestSMTPRequest true "测试请求参数"
+// @Success 200 {object} response.Any{data=model.TestSMTPResponse} "测试执行完毕"
+// @Failure 400 {object} response.Any "参数错误"
+// @Router /api/v1/admin/system-configs/smtp/test [post]
+func TestSMTP(c *gin.Context) {
+	var req model.TestSMTPRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(service.TestSMTP(c.Request.Context(), req)))
+}

backend/plugins/domain/admin/handler/db.go

@@ -0,0 +1,190 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"Wavelet/pkg/config"
+	"Wavelet/pkg/logger"
+	"Wavelet/pkg/response"
+	"Wavelet/plugins/domain/admin/errs"
+	"Wavelet/plugins/domain/admin/model"
+	"Wavelet/plugins/domain/admin/service"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+// GetDBOverview 获取数据库运行概览
+// @Summary 获取数据库运行概览
+// @Description 获取数据库类型、版本、名称、文件大小、表数量及当前连接数，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=model.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) {
+	overview, err := service.DatabaseOverview(c.Request.Context())
+	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) {
+	tables, err := service.DatabaseTableNames(c.Request.Context())
+	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 model.GetTableDataRequest
+	if err := c.ShouldBindQuery(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	data, err := service.DatabaseTableData(c.Request.Context(), req)
+	if err != nil {
+		if msg, ok := errs.AsInvalidInput(err); ok {
+			response.AbortBadRequest(c, msg)
+			return
+		}
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(data))
+}
+
+// ExecuteSQL 执行 SQL 查询
+// @Summary 执行 SQL 查询
+// @Description 在当前数据库中执行任意自定义 SQL，如果是查询语句将返回格式化后的列与数据集，否则返回受影响行数，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body model.ExecuteSQLRequest true "SQL 请求参数"
+// @Success 200 {object} response.Any{data=model.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 model.ExecuteSQLRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	trimmedSQL := strings.TrimSpace(req.SQL)
+	if trimmedSQL == "" {
+		response.AbortBadRequest(c, errs.InvalidSQLStatement)
+		return
+	}
+
+	resp, err := service.ExecuteCustomSQL(c.Request.Context(), trimmedSQL)
+	if err != nil {
+		if err == errs.ErrDatabaseUninitialized {
+			response.AbortInternal(c, err.Error())
+			return
+		}
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(resp))
+}
+
+// GetDatabaseInfo 获取当前数据库类型及版本信息
+// @Summary 获取数据库信息
+// @Description 返回当前使用的数据库类型（sqlite/postgres）、名称/路径及版本字符串，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=model.DatabaseInfoResponse} "获取成功"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Router /api/v1/admin/db-info [get]
+func GetDatabaseInfo(c *gin.Context) {
+	c.JSON(http.StatusOK, response.OK(service.DatabaseInfo(c.Request.Context())))
+}
+
+// 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)
+	}
+}
+
+func exportSQLite(c *gin.Context) {
+	f, fi, err := service.OpenSQLiteExportFile()
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	defer func() {
+		_ = f.Close()
+	}()
+
+	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)
+}
+
+func exportPostgres(c *gin.Context) {
+	cmd, fileName, err := service.NewPgDumpCommand(c.Request.Context())
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	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
+
+	if err := cmd.Run(); err != nil {
+		logger.ErrorF(c.Request.Context(), "[db-export] pg_dump failed: %v", err)
+	}
+}

backend/plugins/domain/admin/handler/logs.go

@@ -0,0 +1,197 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"Wavelet/pkg/logger"
+	"Wavelet/pkg/response"
+	"Wavelet/pkg/util"
+	"Wavelet/plugins/domain/admin/errs"
+	"Wavelet/plugins/domain/admin/model"
+	"Wavelet/plugins/domain/admin/service"
+	"encoding/json"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+	"github.com/gorilla/websocket"
+)
+
+const (
+	defaultLimit = 200
+	maxLimit     = 500
+	maxPageSize  = 100
+)
+
+// wsMessage WebSocket 消息格式
+type wsMessage struct {
+	Type string          `json:"type"` // "log" | "error"
+	Data json.RawMessage `json:"data"`
+}
+
+// GetLogs 获取历史日志
+// @Summary 获取系统日志
+// @Description 分页获取系统历史日志，cursor=0 获取最新日志，cursor>0 获取更早日志
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param cursor query int false "日志游标，0=获取最新" default(0)
+// @Param limit query int false "每页条数" default(200)
+// @Success 200 {object} response.Any{data=model.LogsResponse} "日志列表"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Router /api/v1/admin/logs [get]
+func GetLogs(c *gin.Context) {
+	cursorStr := c.DefaultQuery("cursor", "0")
+	limitStr := c.DefaultQuery("limit", "200")
+
+	var cursor, limit int
+	if _, err := parsePositiveInt(cursorStr, &cursor); err != nil {
+		response.AbortWithError(c, http.StatusBadRequest, errs.InvalidCursorParam)
+		return
+	}
+	if _, err := parsePositiveInt(limitStr, &limit); err != nil || limit <= 0 {
+		limit = defaultLimit
+	}
+	if limit > maxLimit {
+		limit = maxLimit
+	}
+
+	c.JSON(http.StatusOK, response.OK(service.RecentSystemLogs(cursor, limit)))
+}
+
+// HandleLogWebSocket WebSocket 端点，实时推送系统日志
+// @Summary 系统日志实时推送
+// @Description 通过 WebSocket 实时推送系统日志，需要管理员权限
+// @Tags admin
+// @Router /api/v1/admin/logs/ws [get]
+func HandleLogWebSocket(c *gin.Context) {
+	upgrader := getUpgrader()
+
+	conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
+	if err != nil {
+		return
+	}
+	defer func() { _ = conn.Close() }()
+
+	ch := logger.GlobalRingBuffer.Subscribe()
+	defer logger.GlobalRingBuffer.Unsubscribe(ch)
+
+	done := make(chan struct{})
+	util.Go(func() {
+		defer close(done)
+		for {
+			_, _, err := conn.ReadMessage()
+			if err != nil {
+				return
+			}
+		}
+	})
+
+	for {
+		select {
+		case <-done:
+			return
+		case entry, ok := <-ch:
+			if !ok {
+				return
+			}
+			data, _ := json.Marshal(entry)
+			msg := wsMessage{Type: "log", Data: data}
+			payload, _ := json.Marshal(msg)
+			if err := conn.WriteMessage(1, payload); err != nil {
+				return
+			}
+		}
+	}
+}
+
+// GetAccessLogs 获取 ClickHouse 异步采集的访问日志
+// @Summary 获取用户访问日志
+// @Description 分页并按照用户、接口路径、时间范围等维度检索用户访问日志列表（需要管理员权限）
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param page query int false "页码" default(1)
+// @Param page_size query int false "每页条数" default(20)
+// @Param username query string false "用户名模糊搜索"
+// @Param path query string false "接口路径模糊搜索"
+// @Param start_time query string false "起始时间（RFC3339 或 YYYY-MM-DD HH:MM:SS）"
+// @Param end_time query string false "结束时间（RFC3339 或 YYYY-MM-DD HH:MM:SS）"
+// @Success 200 {object} response.Any{data=model.AccessLogsResponse} "访问日志列表"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/logs/access [get]
+func GetAccessLogs(c *gin.Context) {
+	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+	if page < 1 {
+		page = 1
+	}
+	pageSize, _ := strconv.Atoi(c.DefaultQuery("page_size", "20"))
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageSize > maxPageSize {
+		pageSize = maxPageSize
+	}
+
+	resp, err := service.AccessLogs(c.Request.Context(), model.AccessLogQuery{
+		Username:  c.Query("username"),
+		Path:      c.Query("path"),
+		StartTime: c.Query("start_time"),
+		EndTime:   c.Query("end_time"),
+		Page:      page,
+		PageSize:  pageSize,
+	})
+	if err != nil {
+		response.AbortWithError(c, http.StatusInternalServerError, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(resp))
+}
+
+// GetLogsAnalytics 获取 ClickHouse 访问日志图表聚合指标
+// @Summary 获取访问日志分析数据
+// @Description 聚合统计最近 7 天的每日访问趋势、浏览器分布以及前 10 名最活跃用户排行（需要管理员权限）
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=model.LogsAnalyticsResponse} "分析统计数据"
+// @Failure 500 {object} response.Any "内部错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Router /api/v1/admin/logs/analytics [get]
+func GetLogsAnalytics(c *gin.Context) {
+	resp, err := service.AccessLogAnalytics(c.Request.Context())
+	if err != nil {
+		response.AbortWithError(c, http.StatusInternalServerError, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(resp))
+}
+
+func getUpgrader() *websocket.Upgrader {
+	return &websocket.Upgrader{
+		CheckOrigin: func(r *http.Request) bool {
+			return service.IsAllowedLogOrigin(r.Context(), r.Header.Get("Origin"), r.Host)
+		},
+	}
+}
+
+func parsePositiveInt(s string, result *int) (bool, error) {
+	if s == "" {
+		*result = 0
+		return true, nil
+	}
+	n, err := strconv.Atoi(s)
+	if err != nil || n < 0 {
+		return false, err
+	}
+	*result = n
+	return true, nil
+}

backend/plugins/domain/admin/handler/middleware.go

@@ -0,0 +1,46 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/ginutil"
+	"Wavelet/pkg/logger"
+	"Wavelet/pkg/response"
+	"Wavelet/pkg/trace"
+	"Wavelet/plugins/domain/admin/errs"
+
+	"github.com/gin-gonic/gin"
+)
+
+// LoginAdminRequired 返回管理员权限校验中间件
+func LoginAdminRequired() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		ctx, span := trace.Start(c.Request.Context(), "LoginAdminRequired")
+		defer span.End()
+
+		user, _ := ginutil.GetFromContext[*contracts.UserDTO](c, contracts.AuthUserObjKey)
+		if user == nil {
+			response.AbortNotFound(c, errs.AdminRequired)
+			return
+		}
+
+		// 如果是通过 Access Token 鉴权，需要检查令牌本身是否具有管理员权限
+		if tokenAuth, _ := ginutil.GetFromContext[bool](c, contracts.AuthTokenAuthKey); tokenAuth {
+			tokenAdmin, _ := ginutil.GetFromContext[bool](c, contracts.AuthTokenAdminKey)
+			if !tokenAdmin {
+				response.AbortNotFound(c, errs.TokenAdminRequired)
+				return
+			}
+		}
+
+		if !user.IsAdmin {
+			response.AbortNotFound(c, errs.AdminRequired)
+			return
+		}
+
+		logger.InfoF(ctx, "[LoginAdminRequired] %d %s", user.ID, user.Username)
+		c.Next()
+	}
+}

backend/plugins/domain/admin/handler/router.go

@@ -0,0 +1,122 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package handler provides HTTP routing and handlers for the admin domain.
+package handler
+
+import (
+	"Wavelet/core/extpoints"
+)
+
+// RegisterRoutes mounts all admin console endpoints under the provided admin router group.
+func RegisterRoutes(adminRouter extpoints.RouterExtension) {
+	// Status & Diagnostics
+	adminRouter.GET("/status", GetSystemStatus)
+	adminRouter.GET("/status/log-database", GetLogDatabaseStatus)
+	adminRouter.GET("/db-info", GetDatabaseInfo)
+	adminRouter.GET("/db-export", ExportDatabase)
+
+	// DB Management
+	dbGroup := adminRouter.Group("/db-manage")
+	{
+		dbGroup.GET("/overview", GetDBOverview)
+		dbGroup.GET("/tables", ListDBTables)
+		dbGroup.GET("/table-data", GetDBTableData)
+		dbGroup.POST("/query", ExecuteSQL)
+	}
+
+	// Cache Management
+	cacheGroup := adminRouter.Group("/cache")
+	{
+		cacheGroup.GET("/status", GetCacheStatus)
+		cacheGroup.POST("/config", UpdateCacheConfig)
+		cacheGroup.POST("/clear", ClearCache)
+	}
+
+	// Updater
+	updateGroup := adminRouter.Group("/update")
+	{
+		updateGroup.GET("", GetUpdateStatus)
+		updateGroup.POST("/apply", ApplyUpdate)
+	}
+
+	// Logs
+	logsGroup := adminRouter.Group("/logs")
+	{
+		logsGroup.GET("", GetLogs)
+		logsGroup.GET("/access", GetAccessLogs)
+		logsGroup.GET("/analytics", GetLogsAnalytics)
+		logsGroup.GET("/ws", HandleLogWebSocket)
+	}
+
+	// Users
+	usersGroup := adminRouter.Group("/users")
+	{
+		usersGroup.GET("", ListUsers)
+		usersGroup.POST("", CreateUser)
+		usersGroup.GET("/:id", GetUser)
+		usersGroup.PUT("/:id/status", UpdateUserStatus)
+		usersGroup.PUT("/:id", UpdateUser)
+		usersGroup.DELETE("/:id", DeleteUser)
+	}
+
+	// Auth Sources
+	authSourcesGroup := adminRouter.Group("/auth-sources")
+	{
+		authSourcesGroup.GET("", ListAuthSources)
+		authSourcesGroup.POST("", CreateAuthSource)
+		authSourcesGroup.PUT("/:id", UpdateAuthSource)
+		authSourcesGroup.PUT("/:id/toggle", ToggleAuthSource)
+		authSourcesGroup.DELETE("/:id", DeleteAuthSource)
+	}
+
+	// System Configs
+	configGroup := adminRouter.Group("/system-configs")
+	{
+		configGroup.GET("", ListSystemConfigs)
+		configGroup.POST("", CreateSystemConfig)
+		configGroup.POST("/smtp/test", TestSMTP)
+
+		keyGroup := configGroup.Group("/:key")
+		{
+			keyGroup.GET("", GetSystemConfig)
+			keyGroup.PUT("", UpdateSystemConfig)
+		}
+	}
+
+	// Templates
+	templateGroup := adminRouter.Group("/templates")
+	{
+		templateGroup.GET("", ListTemplates)
+		templateGroup.POST("", CreateTemplate)
+
+		keyGroup := templateGroup.Group("/:key")
+		{
+			keyGroup.GET("", GetTemplate)
+			keyGroup.PUT("", UpdateTemplate)
+			keyGroup.DELETE("", DeleteTemplate)
+		}
+	}
+
+	// Tasks
+	taskGroup := adminRouter.Group("/tasks")
+	{
+		taskGroup.GET("/types", ListTaskTypes)
+		taskGroup.POST("/dispatch", DispatchTask)
+
+		executions := taskGroup.Group("/executions")
+		{
+			executions.GET("", ListTaskExecutions)
+			executions.GET("/:id", GetTaskExecution)
+			executions.POST("/:id/retry", RetryTask)
+		}
+
+		schedules := taskGroup.Group("/schedules")
+		{
+			schedules.GET("", ListSchedules)
+			schedules.POST("", CreateSchedule)
+			schedules.PUT("/:id", UpdateSchedule)
+			schedules.DELETE("/:id", DeleteSchedule)
+		}
+	}
+}

backend/plugins/domain/admin/handler/status.go

@@ -0,0 +1,41 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"Wavelet/pkg/response"
+	"Wavelet/plugins/domain/admin/service"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+// GetSystemStatus 获取系统状态信息
+// @Summary 获取系统状态信息
+// @Description 获取后端服务运行状态、Goroutine、内存指标等详细统计数据，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=model.SystemStatusResponse} "获取成功"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Router /api/v1/admin/status [get]
+func GetSystemStatus(c *gin.Context) {
+	c.JSON(http.StatusOK, response.OK(service.CollectSystemStatus()))
+}
+
+// GetLogDatabaseStatus 返回当前日志库状态。
+// @Summary 获取日志数据库状态
+// @Description 返回当前日志主库、迁移状态、各库保留天数与合法迁移目标，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=model.LogDatabaseStatus} "获取成功"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/status/log-database [get]
+func GetLogDatabaseStatus(c *gin.Context) {
+	c.JSON(http.StatusOK, response.OK(service.LogDatabaseStatus(c.Request.Context())))
+}

backend/plugins/domain/admin/handler/tasks.go

@@ -0,0 +1,318 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"Wavelet/pkg/response"
+	"Wavelet/plugins/domain/admin/errs"
+	"Wavelet/plugins/domain/admin/model"
+	"Wavelet/plugins/domain/admin/service"
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+)
+
+// abortTaskLogicError maps a task service failure onto the unified response envelope.
+func abortTaskLogicError(c *gin.Context, err error) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, errs.ErrTaskServiceUnavailable) || errors.Is(err, errs.ErrScheduleNotFound) {
+		response.AbortInternal(c, err.Error())
+		return true
+	}
+	msg := err.Error()
+	if errors.Is(err, errs.ErrInvalidCronExpression) || errors.Is(err, errs.ErrInvalidTaskType) {
+		response.AbortBadRequest(c, msg)
+		return true
+	}
+	if text, ok := errs.AsInvalidInput(err); ok {
+		response.AbortBadRequest(c, text)
+		return true
+	}
+	response.AbortInternal(c, msg)
+	return true
+}
+
+// ListTaskTypes 获取支持的任务类型列表
+// @Summary 获取支持的任务类型
+// @Description 返回系统支持的所有可调度任务类型列表，包括任务名称、描述、是否支持时间范围等元数据，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]contracts.TaskMetaDTO} "任务类型列表"
+// @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(service.ListTaskTypes()))
+}
+
+// DispatchTask 下发任务
+// @Summary 下发异步任务
+// @Description 手动触发指定类型的异步任务，支持指定时间范围和用户，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body model.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 model.DispatchTaskRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	taskID, err := service.DispatchTask(c.Request.Context(), req)
+	if err != nil {
+		switch {
+		case errors.Is(err, errs.ErrTaskServiceUnavailable):
+			response.AbortInternal(c, err.Error())
+		case errors.Is(err, errs.ErrInvalidTaskType):
+			response.AbortBadRequest(c, errs.InvalidTaskType)
+		default:
+			if text, ok := errs.AsInvalidInput(err); ok {
+				response.AbortBadRequest(c, text)
+				return
+			}
+			response.AbortInternal(c, err.Error())
+		}
+		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
+	}
+
+	executions, total, err := service.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 := parseUintParam(c, errs.InvalidTaskExecutionID)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	execution, err := service.TaskExecution(c.Request.Context(), id)
+	if err != nil {
+		response.AbortNotFound(c, errs.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 := parseUintParam(c, errs.InvalidTaskExecutionID)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	newTaskID, err := service.RetryTask(c.Request.Context(), id)
+	if err != nil {
+		switch {
+		case errors.Is(err, errs.ErrTaskServiceUnavailable):
+			response.AbortInternal(c, err.Error())
+		case service.IsRetryMissingError(err):
+			response.AbortNotFound(c, err.Error())
+		case service.IsRetryConflictError(err):
+			response.AbortBadRequest(c, err.Error())
+		default:
+			response.AbortInternal(c, err.Error())
+		}
+		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 := service.ListSchedules(c.Request.Context())
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(schedules))
+}
+
+// CreateSchedule 创建定时任务
+// @Summary 创建定时任务
+// @Description 新增一个动态定时任务配置，关联已有的异步任务，配置 Cron 表达式和执行参数，并触发调度器热加载，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body model.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 model.CreateScheduleRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	schedule, err := service.CreateSchedule(c.Request.Context(), req)
+	if abortTaskLogicError(c, err) {
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(schedule))
+}
+
+// UpdateSchedule 修改定时任务
+// @Summary 修改定时任务
+// @Description 修改一个定时任务的配置（名称、Cron 表达式、异步任务参数和是否启用等），并触发调度器热加载，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "定时任务 ID"
+// @Param request body model.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 := parseUintParam(c, errs.InvalidScheduleID)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	var req model.UpdateScheduleRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	schedule, err := service.UpdateSchedule(c.Request.Context(), id, req)
+	if abortTaskLogicError(c, err) {
+		return
+	}
+
+	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 := parseUintParam(c, errs.InvalidScheduleID)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if err := service.DeleteSchedule(c.Request.Context(), id); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// parseUintParam reads a positive numeric path parameter.
+func parseUintParam(c *gin.Context, invalidMsg string) (uint64, error) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		return 0, errors.New(invalidMsg)
+	}
+	return id, nil
+}

backend/plugins/domain/admin/handler/templates.go

@@ -0,0 +1,159 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"Wavelet/pkg/response"
+	"Wavelet/plugins/domain/admin/errs"
+	"Wavelet/plugins/domain/admin/model"
+	"Wavelet/plugins/domain/admin/service"
+	"errors"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+// abortTemplateLogicError maps the template service outcome onto the response envelope.
+func abortTemplateLogicError(c *gin.Context, err error) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, errs.ErrTemplateNotFound) {
+		response.AbortNotFound(c, errs.TemplateNotFound)
+		return true
+	}
+	msg := err.Error()
+	switch msg {
+	case errs.TemplateKeyExists, errs.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 model.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 model.CreateTemplateRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	tmpl, err := service.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 := service.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 := service.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 model.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 model.UpdateTemplateRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	tmpl, err := service.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 := service.DeleteTemplate(c.Request.Context(), c.Param("key")); abortTemplateLogicError(c, err) {
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}

backend/plugins/domain/admin/handler/updater.go

@@ -0,0 +1,69 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"Wavelet/pkg/logger"
+	"Wavelet/pkg/response"
+	"Wavelet/pkg/util"
+	"Wavelet/plugins/domain/admin/service"
+	"context"
+	"net/http"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+// GetUpdateStatus 获取应用更新状态
+// @Summary 获取应用更新状态
+// @Description 从系统配置指定的 GitHub 上游仓库查询最新兼容 Release，并与当前服务版本比较
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=model.UpdaterStatus} "更新状态"
+// @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 := service.GetUpdateStatus(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 := service.DefaultUpdaterManager.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())
+
+	util.Go(func() {
+		time.Sleep(time.Second)
+		if err := service.ReplaceAndRestart(executable, stagedBinary); err != nil {
+			service.DefaultUpdaterManager.FinishUpgrade()
+			logger.ErrorF(context.Background(), "[Updater] replace and restart failed: %v", err)
+		}
+	})
+}

backend/plugins/domain/admin/handler/user.go

@@ -0,0 +1,294 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/ginutil"
+	"Wavelet/pkg/logger"
+	"Wavelet/pkg/response"
+	"Wavelet/plugins/domain/admin/errs"
+	"Wavelet/plugins/domain/admin/model"
+	"Wavelet/plugins/domain/admin/service"
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+)
+
+func parseUserID(c *gin.Context) (uint64, bool) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil || id == 0 {
+		response.AbortBadRequest(c, errs.UserNotFound)
+		return 0, false
+	}
+	return id, true
+}
+
+// abortUserLogicError maps the user service outcome onto the unified response envelope.
+func abortUserLogicError(c *gin.Context, err error, notFoundMsg string, forbiddenMsgs, badRequestMsgs []string) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, errs.ErrUserServiceUnavailable) {
+		response.AbortInternal(c, err.Error())
+		return true
+	}
+	if errors.Is(err, errs.ErrUserNotFound) {
+		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
+		}
+	}
+	logger.ErrorF(c.Request.Context(), "Admin user error: %v", err)
+	response.AbortInternal(c, errs.InternalServerError)
+	return true
+}
+
+// ListUsers 获取用户列表
+// @Summary 获取用户列表
+// @Description 分页返回用户列表，支持按用户 ID 和用户名筛选，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param request query model.ListUsersRequest true "查询参数"
+// @Success 200 {object} response.Any{data=model.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 model.ListUsersRequest
+	if err := c.ShouldBindQuery(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	total, dtos, err := service.AdminListUsers(c.Request.Context(), contracts.AdminListUsersFilter{
+		Page:     req.Page,
+		PageSize: req.PageSize,
+		UserID:   req.UserID,
+		Username: req.Username,
+		Email:    req.Email,
+	})
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	users := make([]model.UserResponse, 0, len(dtos))
+	for _, dto := range dtos {
+		users = append(users, service.ToUserResponse(dto))
+	}
+
+	c.JSON(http.StatusOK, response.OK(model.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=model.UserResponse} "用户详情"
+// @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 := service.AdminGetUser(c.Request.Context(), id)
+	if abortUserLogicError(c, err, errs.UserNotFound, nil, nil) {
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(service.ToUserResponse(targetUser)))
+}
+
+// UpdateUserStatus 更新用户状态（启用/禁用）
+// @Summary 更新用户状态
+// @Description 启用或禁用指定用户，管理员账号无法被禁用，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "用户 ID"
+// @Param request body model.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 model.UpdateUserStatusRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	id, ok := parseUserID(c)
+	if !ok {
+		return
+	}
+
+	if err := service.AdminUpdateUserStatus(c.Request.Context(), id, req.IsActive); err != nil {
+		if abortUserLogicError(c, err, errs.UserNotFound, []string{errs.CannotDisable}, nil) {
+			return
+		}
+		response.AbortInternal(c, errs.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, _ := ginutil.GetFromContext[*contracts.UserDTO](c, contracts.AuthUserObjKey)
+	if currUser == nil {
+		response.AbortUnauthorized(c, errs.AdminRequired)
+		return
+	}
+
+	if err := service.AdminDeleteUser(c.Request.Context(), currUser.ID, id); err != nil {
+		if abortUserLogicError(c, err, errs.UserNotFound, []string{errs.CannotDelete, errs.CannotDeleteSelf}, nil) {
+			return
+		}
+		response.AbortInternal(c, errs.DeleteUserFailed)
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// CreateUser 创建用户
+// @Summary 创建用户
+// @Description 创建一个本地密码登录的新用户，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body model.CreateUserRequest true "创建用户参数"
+// @Success 200 {object} response.Any{data=model.UserResponse} "创建成功"
+// @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 model.CreateUserRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	newUser, err := service.AdminCreateUser(c.Request.Context(), contracts.AdminCreateUserRequest{
+		Username: req.Username,
+		Password: req.Password,
+		Nickname: req.Nickname,
+		Email:    req.Email,
+		IsActive: req.IsActive,
+		IsAdmin:  req.IsAdmin,
+	})
+	if abortUserLogicError(c, err, "", nil, []string{errs.UsernameRequired, errs.EmailRequired, errs.PasswordTooShort, errs.UsernameExists, errs.EmailExists}) {
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(service.ToUserResponse(newUser)))
+}
+
+// UpdateUser 更新用户信息
+// @Summary 更新用户信息
+// @Description 更新指定用户的昵称、邮箱、管理员权限，并可选重置密码，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "用户 ID"
+// @Param request body model.UpdateUserRequest 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} [put]
+func UpdateUser(c *gin.Context) {
+	var req model.UpdateUserRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	id, ok := parseUserID(c)
+	if !ok {
+		return
+	}
+
+	currUser, _ := ginutil.GetFromContext[*contracts.UserDTO](c, contracts.AuthUserObjKey)
+	if currUser == nil {
+		response.AbortUnauthorized(c, errs.AdminRequired)
+		return
+	}
+
+	err := service.AdminUpdateUser(c.Request.Context(), currUser.ID, contracts.AdminUpdateUserRequest{
+		ID:       id,
+		Nickname: req.Nickname,
+		Email:    req.Email,
+		IsAdmin:  req.IsAdmin,
+		Password: req.Password,
+	})
+	if err != nil {
+		if abortUserLogicError(c, err, errs.UserNotFound, []string{errs.CannotRevokeSelfAdmin}, []string{errs.EmailRequired, errs.EmailExists, errs.PasswordTooShort}) {
+			return
+		}
+		response.AbortInternal(c, errs.UpdateUserInfoFailed)
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}