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

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

@@ -0,0 +1,139 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"Wavelet/pkg/response"
+	"Wavelet/plugins/domain/message_gateway/errs"
+	"Wavelet/plugins/domain/message_gateway/service"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+)
+
+// ListAdminChannelDefinitions returns form schemas for supported channel types.
+// @Summary List message gateway channel definitions
+// @Description Returns form field definitions for Telegram and QQ channels
+// @Tags admin-message-gateway
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]model.Definition}
+// @Router /api/v1/admin/message-gateway/channels/definitions [get]
+func ListAdminChannelDefinitions(c *gin.Context) {
+	c.JSON(http.StatusOK, response.OK(service.ListDefinitions()))
+}
+
+// ListAdminChannels lists configured messaging channels with secrets masked.
+// @Summary List message gateway channels
+// @Description Returns all messaging channels; secrets are masked
+// @Tags admin-message-gateway
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]model.ChannelDTO}
+// @Router /api/v1/admin/message-gateway/channels [get]
+func ListAdminChannels(c *gin.Context) {
+	rows, err := service.ListChannels(c.Request.Context())
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(rows))
+}
+
+func parseAdminChannelID(c *gin.Context) (uint64, bool) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, errs.ErrInvalidChannelID)
+		return 0, false
+	}
+	return id, true
+}
+
+func handleAdminChannelError(c *gin.Context, err error, fallback func(c *gin.Context, msg string)) {
+	if err.Error() == errs.ErrChannelNotFound {
+		response.AbortNotFound(c, err.Error())
+		return
+	}
+	fallback(c, err.Error())
+}
+
+// CreateAdminChannel creates a messaging channel.
+// @Summary Create message gateway channel
+// @Description Creates a Telegram or QQ channel with encrypted credentials
+// @Tags admin-message-gateway
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body model.CreateChannelRequest true "create body"
+// @Success 200 {object} response.Any{data=model.ChannelDTO}
+// @Failure 400 {object} response.Any
+// @Router /api/v1/admin/message-gateway/channels [post]
+func CreateAdminChannel(c *gin.Context) {
+	handleJSONRequest(c, service.CreateChannel)
+}
+
+// UpdateAdminChannel patches a messaging channel. Empty secrets keep the previous values.
+// @Summary Update message gateway channel
+// @Description Updates a channel; empty secrets keep the current ciphertext
+// @Tags admin-message-gateway
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "channel id"
+// @Param request body model.UpdateChannelRequest true "update body"
+// @Success 200 {object} response.Any{data=model.ChannelDTO}
+// @Failure 400 {object} response.Any
+// @Failure 404 {object} response.Any
+// @Router /api/v1/admin/message-gateway/channels/{id} [patch]
+func UpdateAdminChannel(c *gin.Context) {
+	handleEntityUpdate(c, parseAdminChannelID, service.UpdateChannel, func(c *gin.Context, err error) {
+		handleAdminChannelError(c, err, response.AbortBadRequest)
+	})
+}
+
+// DeleteAdminChannel removes a channel and its bindings/pairing codes.
+// @Summary Delete message gateway channel
+// @Description Deletes a channel and cascaded bindings and pairing codes
+// @Tags admin-message-gateway
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "channel id"
+// @Success 200 {object} response.Any
+// @Failure 404 {object} response.Any
+// @Router /api/v1/admin/message-gateway/channels/{id} [delete]
+func DeleteAdminChannel(c *gin.Context) {
+	id, ok := parseAdminChannelID(c)
+	if !ok {
+		return
+	}
+	if err := service.DeleteChannel(c.Request.Context(), id); err != nil {
+		handleAdminChannelError(c, err, response.AbortInternal)
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// TestAdminChannel probes stored credentials (Telegram getMe or QQ token).
+// @Summary Test message gateway channel
+// @Description Probes stored credentials without returning secrets
+// @Tags admin-message-gateway
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "channel id"
+// @Success 200 {object} response.Any
+// @Failure 400 {object} response.Any
+// @Failure 404 {object} response.Any
+// @Router /api/v1/admin/message-gateway/channels/{id}/test [post]
+func TestAdminChannel(c *gin.Context) {
+	id, ok := parseAdminChannelID(c)
+	if !ok {
+		return
+	}
+	if err := service.ProbeChannel(c.Request.Context(), id); err != nil {
+		handleAdminChannelError(c, err, response.AbortBadRequest)
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}

backend/plugins/domain/message_gateway/handler/handlers.go

@@ -0,0 +1,182 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package handler provides HTTP endpoints for message_gateway.
+package handler
+
+import (
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/ginutil"
+	"Wavelet/pkg/response"
+	"Wavelet/plugins/domain/message_gateway/errs"
+	"Wavelet/plugins/domain/message_gateway/model"
+	"Wavelet/plugins/domain/message_gateway/service"
+	"context"
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+)
+
+func currentUser(c *gin.Context) (*contracts.UserDTO, bool) {
+	return ginutil.GetFromContext[*contracts.UserDTO](c, contracts.AuthUserObjKey)
+}
+
+// handleJSONRequest binds a JSON body, runs the service use case and writes the
+// standard success envelope; any service error surfaces as a bad request.
+func handleJSONRequest[Req any, Res any](c *gin.Context, handler func(ctx context.Context, req Req) (Res, error)) {
+	var req Req
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	res, err := handler(c.Request.Context(), req)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(res))
+}
+
+// handleEntityUpdate resolves a path identifier plus JSON body, runs the updater
+// use case and writes the success envelope; error classification is delegated to onErr.
+func handleEntityUpdate[Req any, Res any](
+	c *gin.Context,
+	parseID func(*gin.Context) (uint64, bool),
+	updater func(ctx context.Context, id uint64, req Req) (Res, error),
+	onErr func(*gin.Context, error),
+) {
+	id, ok := parseID(c)
+	if !ok {
+		return
+	}
+	var req Req
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	dto, err := updater(c.Request.Context(), id, req)
+	if err != nil {
+		onErr(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(dto))
+}
+
+// ListChannels lists enabled channels a user can bind.
+// @Summary List enabled messaging channels
+// @Description Returns enabled system bots the current user can pair with
+// @Tags message-gateway
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]model.PublicChannelDTO}
+// @Failure 401 {object} response.Any
+// @Router /api/v1/message-gateway/channels [get]
+func ListChannels(c *gin.Context) {
+	if user, ok := currentUser(c); !ok || user == nil {
+		response.AbortUnauthorized(c, errs.ErrLoginRequired)
+		return
+	}
+	rows, err := service.ListEnabledPublicChannels(c.Request.Context())
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(rows))
+}
+
+// ListBindings lists the current user's bot bindings.
+// @Summary List message gateway bindings
+// @Description Returns the current user's bound messaging channels
+// @Tags message-gateway
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any{data=[]model.BindingDTO}
+// @Failure 401 {object} response.Any
+// @Router /api/v1/message-gateway/bindings [get]
+func ListBindings(c *gin.Context) {
+	user, ok := currentUser(c)
+	if !ok || user == nil {
+		response.AbortUnauthorized(c, errs.ErrLoginRequired)
+		return
+	}
+	rows, err := service.ListUserBindings(c.Request.Context(), user.ID)
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(rows))
+}
+
+// BindBinding consumes a pairing code and binds the platform identity.
+// @Summary Bind a messaging channel
+// @Description Binds the current user to a platform identity using a one-time pairing code
+// @Tags message-gateway
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body model.BindRequest true "bind body"
+// @Success 200 {object} response.Any{data=model.BindingDTO}
+// @Failure 400 {object} response.Any
+// @Failure 409 {object} response.Any
+// @Router /api/v1/message-gateway/bindings [post]
+func BindBinding(c *gin.Context) {
+	user, ok := currentUser(c)
+	if !ok || user == nil {
+		response.AbortUnauthorized(c, errs.ErrLoginRequired)
+		return
+	}
+	var req model.BindRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	dto, err := service.BindChannel(c.Request.Context(), user.ID, req)
+	if err != nil {
+		if errors.Is(err, errs.ErrPlatformAlreadyBound) {
+			response.AbortConflict(c, err.Error())
+			return
+		}
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(dto))
+}
+
+// UnbindBinding removes the current user's binding.
+// @Summary Unbind a messaging channel
+// @Description Removes a binding owned by the current user
+// @Tags message-gateway
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "binding id"
+// @Success 200 {object} response.Any
+// @Failure 403 {object} response.Any
+// @Failure 404 {object} response.Any
+// @Router /api/v1/message-gateway/bindings/{id} [delete]
+func UnbindBinding(c *gin.Context) {
+	user, ok := currentUser(c)
+	if !ok || user == nil {
+		response.AbortUnauthorized(c, errs.ErrLoginRequired)
+		return
+	}
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, errs.ErrInvalidBindingID)
+		return
+	}
+	if err := service.UnbindChannel(c.Request.Context(), user.ID, id); err != nil {
+		if errors.Is(err, errs.ErrBindingNotFound) {
+			response.AbortNotFound(c, err.Error())
+			return
+		}
+		if errors.Is(err, errs.ErrBindingForbidden) {
+			response.AbortForbidden(c, err.Error())
+			return
+		}
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}

backend/plugins/domain/message_gateway/handler/push_channel.go

@@ -0,0 +1,96 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"Wavelet/pkg/response"
+	"Wavelet/plugins/domain/message_gateway/errs"
+	"Wavelet/plugins/domain/message_gateway/model"
+	"Wavelet/plugins/domain/message_gateway/service"
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+)
+
+// ListPushChannelDefinitions returns channel definitions.
+func ListPushChannelDefinitions(c *gin.Context) {
+	c.JSON(http.StatusOK, response.OK(model.ListPushDefinitions()))
+}
+
+// ListPushChannels lists configured push channels.
+func ListPushChannels(c *gin.Context) {
+	channels, err := service.ListPushChannels(c.Request.Context())
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(channels))
+}
+
+// parsePushChannelID reads the path identifier of a push channel.
+func parsePushChannelID(c *gin.Context) (uint64, bool) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, errs.ErrInvalidChannelID)
+		return 0, false
+	}
+	return id, true
+}
+
+// handlePushChannelNotFoundError maps a missing channel row to 404, others to fallback.
+func handlePushChannelNotFoundError(c *gin.Context, err error, fallback func(c *gin.Context, msg string)) {
+	if errors.Is(err, errs.ErrRecordNotFound) {
+		response.AbortNotFound(c, errs.ErrChannelNotFound)
+		return
+	}
+	fallback(c, err.Error())
+}
+
+// CreatePushChannel creates a push channel.
+func CreatePushChannel(c *gin.Context) {
+	handleJSONRequest(c, service.CreatePushChannel)
+}
+
+// UpdatePushChannel updates a push channel.
+func UpdatePushChannel(c *gin.Context) {
+	handleEntityUpdate(c, parsePushChannelID, service.UpdatePushChannel, func(c *gin.Context, err error) {
+		handlePushChannelNotFoundError(c, err, response.AbortInternal)
+	})
+}
+
+// DeletePushChannel deletes a push channel.
+func DeletePushChannel(c *gin.Context) {
+	id, ok := parsePushChannelID(c)
+	if !ok {
+		return
+	}
+
+	if err := service.DeletePushChannel(c.Request.Context(), id); err != nil {
+		handlePushChannelNotFoundError(c, err, response.AbortInternal)
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// TestPushChannel tests connectivity of a push channel.
+func TestPushChannel(c *gin.Context) {
+	var req model.TestPushChannelRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	payload, err := service.PreparePushChannelTest(c.Request.Context(), req)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	if err := service.EnqueuePushTask(c.Request.Context(), payload); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}

backend/plugins/domain/message_gateway/handler/push_event.go

@@ -0,0 +1,148 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"Wavelet/pkg/response"
+	"Wavelet/plugins/domain/message_gateway/errs"
+	"Wavelet/plugins/domain/message_gateway/model"
+	"Wavelet/plugins/domain/message_gateway/service"
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+)
+
+// ListPushEvents lists configured push events.
+func ListPushEvents(c *gin.Context) {
+	ctx := c.Request.Context()
+	events, err := service.ListPushEvents(ctx)
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(events))
+}
+
+// ListBuiltInPushEvents lists system built-in push event definitions.
+func ListBuiltInPushEvents(c *gin.Context) {
+	c.JSON(http.StatusOK, response.OK(service.GetBuiltInEvents()))
+}
+
+// parsePushEventID reads the path identifier of a push event.
+func parsePushEventID(c *gin.Context) (uint64, bool) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, errs.ErrInvalidEventID)
+		return 0, false
+	}
+	return id, true
+}
+
+// handlePushEventNotFoundError maps a missing event row to 404, others to fallback.
+func handlePushEventNotFoundError(c *gin.Context, err error, fallback func(c *gin.Context, msg string)) {
+	if errors.Is(err, errs.ErrRecordNotFound) {
+		response.AbortNotFound(c, errs.ErrEventNotFound)
+		return
+	}
+	fallback(c, err.Error())
+}
+
+// CreatePushEvent creates a new push event configuration.
+func CreatePushEvent(c *gin.Context) {
+	handleJSONRequest(c, service.CreatePushEvent)
+}
+
+// DeletePushEvent deletes a push event configuration by ID.
+func DeletePushEvent(c *gin.Context) {
+	id, ok := parsePushEventID(c)
+	if !ok {
+		return
+	}
+
+	if err := service.DeletePushEvent(c.Request.Context(), id); err != nil {
+		handlePushEventNotFoundError(c, err, response.AbortInternal)
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// UpdatePushEvent updates an existing push event.
+func UpdatePushEvent(c *gin.Context) {
+	id, ok := parsePushEventID(c)
+	if !ok {
+		return
+	}
+
+	var req model.UpdatePushEventRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if err := service.UpdatePushEvent(c.Request.Context(), id, req); err != nil {
+		handlePushEventNotFoundError(c, err, response.AbortBadRequest)
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// TogglePushEvent toggles the enabled state of a push event.
+func TogglePushEvent(c *gin.Context) {
+	id, ok := parsePushEventID(c)
+	if !ok {
+		return
+	}
+
+	enabled, err := service.TogglePushEvent(c.Request.Context(), id)
+	if err != nil {
+		handlePushEventNotFoundError(c, err, response.AbortBadRequest)
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(enabled))
+}
+
+// ListPushHistories returns paginated push notification delivery histories.
+func ListPushHistories(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 := service.ListPushHistories(c.Request.Context(), model.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 executes a synchronous push test using the specified config.
+func TestPush(c *gin.Context) {
+	var req model.TestPushRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if err := service.RunPushTest(c.Request.Context(), req.Config, req.Target); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}

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

@@ -0,0 +1,63 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package handler
+
+import (
+	"Wavelet/core/extpoints"
+
+	"github.com/gin-gonic/gin"
+)
+
+// RegisterUserRoutes mounts user-facing message gateway endpoints.
+func RegisterUserRoutes(r extpoints.RouterExtension, loginMW gin.HandlerFunc) {
+	mg := r.Group("/message-gateway", loginMW)
+	{
+		mg.GET("/channels", ListChannels)
+		mg.GET("/bindings", ListBindings)
+		mg.POST("/bindings", BindBinding)
+		mg.DELETE("/bindings/:id", UnbindBinding)
+	}
+}
+
+// RegisterAdminRoutes mounts admin message-gateway APIs under /admin.
+func RegisterAdminRoutes(adminRouter extpoints.RouterExtension, loginMW, adminMW gin.HandlerFunc) {
+	g := adminRouter.Group("/message-gateway", loginMW, adminMW)
+	{
+		g.GET("/channels/definitions", ListAdminChannelDefinitions)
+		g.GET("/channels", ListAdminChannels)
+		g.POST("/channels", CreateAdminChannel)
+		g.PATCH("/channels/:id", UpdateAdminChannel)
+		g.DELETE("/channels/:id", DeleteAdminChannel)
+		g.POST("/channels/:id/test", TestAdminChannel)
+	}
+}
+
+// RegisterAdminPushRoutes mounts admin push notification APIs under /admin.
+func RegisterAdminPushRoutes(adminRouter extpoints.RouterExtension, loginMW, adminMW gin.HandlerFunc) {
+	adminPushGroup := adminRouter.Group("/push", loginMW, adminMW)
+	{
+		events := adminPushGroup.Group("/events")
+		{
+			events.GET("", ListPushEvents)
+			events.GET("/builtin", ListBuiltInPushEvents)
+			events.POST("", CreatePushEvent)
+			events.PUT("/:id", UpdatePushEvent)
+			events.DELETE("/:id", DeletePushEvent)
+			events.POST("/:id/toggle", TogglePushEvent)
+		}
+
+		adminPushGroup.GET("/histories", ListPushHistories)
+		adminPushGroup.POST("/test", TestPush)
+
+		channels := adminPushGroup.Group("/channels")
+		{
+			channels.GET("/definitions", ListPushChannelDefinitions)
+			channels.GET("", ListPushChannels)
+			channels.POST("", CreatePushChannel)
+			channels.PUT("/:id", UpdatePushChannel)
+			channels.DELETE("/:id", DeletePushChannel)
+			channels.POST("/test", TestPushChannel)
+		}
+	}
+}