docs(swagger): restore gold @Router comments on platform APIs

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

@@ -15,12 +15,26 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
-// ListPushChannelDefinitions returns channel definitions.
+// ListPushChannelDefinitions 获取各种消息通道的表单配置定义列表
+// @Summary 获取所有消息通道配置字段定义
+// @Description 返回系统支持的所有消息通道类型的动态表单定义，需要管理员权限
+// @Tags admin-push
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any "通道配置定义列表"
+// @Router /api/v1/admin/push/channels/definitions [get]
 func ListPushChannelDefinitions(c *gin.Context) {
 	c.JSON(http.StatusOK, response.OK(model.ListPushDefinitions()))
 }
 
-// ListPushChannels lists configured push channels.
+// ListPushChannels 获取消息通道列表
+// @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 ListPushChannels(c *gin.Context) {
 	channels, err := service.ListPushChannels(c.Request.Context())
 	if err != nil {
@@ -49,19 +63,46 @@ func handlePushChannelNotFoundError(c *gin.Context, err error, fallback func(c *
 	fallback(c, err.Error())
 }
 
-// CreatePushChannel creates a push channel.
+// CreatePushChannel 创建消息通道
+// @Summary 创建消息通道
+// @Description 新建一个消息通道配置，需要管理员权限
+// @Tags admin-push
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body model.CreatePushChannelRequest true "创建参数"
+// @Success 200 {object} response.Any{data=model.PushChannel} "创建成功"
+// @Router /api/v1/admin/push/channels [post]
 func CreatePushChannel(c *gin.Context) {
 	handleJSONRequest(c, service.CreatePushChannel)
 }
 
-// UpdatePushChannel updates a push channel.
+// UpdatePushChannel 更新消息通道
+// @Summary 更新消息通道
+// @Description 修改消息通道配置，需要管理员权限
+// @Tags admin-push
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param id path uint64 true "通道ID"
+// @Param request body model.UpdatePushChannelRequest true "更新参数"
+// @Success 200 {object} response.Any{data=model.PushChannel} "更新成功"
+// @Router /api/v1/admin/push/channels/{id} [put]
 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.
+// DeletePushChannel 删除消息通道
+// @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 DeletePushChannel(c *gin.Context) {
 	id, ok := parsePushChannelID(c)
 	if !ok {
@@ -75,7 +116,16 @@ func DeletePushChannel(c *gin.Context) {
 	c.JSON(http.StatusOK, response.OKNil())
 }
 
-// TestPushChannel tests connectivity of a push channel.
+// TestPushChannel 测试通道连通性
+// @Summary 测试通道连通性
+// @Description 触发一次临时的或现有的通道连通性推送测试，需要管理员权限
+// @Tags admin-push
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body model.TestPushChannelRequest true "测试参数"
+// @Success 200 {object} response.Any "测试触发成功"
+// @Router /api/v1/admin/push/channels/test [post]
 func TestPushChannel(c *gin.Context) {
 	var req model.TestPushChannelRequest
 	if err := c.ShouldBindJSON(&req); err != nil {

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

@@ -15,7 +15,14 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
-// ListPushEvents lists configured push events.
+// ListPushEvents 获取通知事件列表
+// @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 ListPushEvents(c *gin.Context) {
 	ctx := c.Request.Context()
 	events, err := service.ListPushEvents(ctx)
@@ -26,7 +33,14 @@ func ListPushEvents(c *gin.Context) {
 	c.JSON(http.StatusOK, response.OK(events))
 }
 
-// ListBuiltInPushEvents lists system built-in push event definitions.
+// ListBuiltInPushEvents 获取内置通知事件列表
+// @Summary 获取所有内置通知事件
+// @Description 返回系统定义的所有内置通知事件元数据，供前端下拉框选择，需要管理员权限
+// @Tags admin-push
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} response.Any "内置通知事件列表"
+// @Router /api/v1/admin/push/events/builtin [get]
 func ListBuiltInPushEvents(c *gin.Context) {
 	c.JSON(http.StatusOK, response.OK(service.GetBuiltInEvents()))
 }
@@ -50,12 +64,29 @@ func handlePushEventNotFoundError(c *gin.Context, err error, fallback func(c *gi
 	fallback(c, err.Error())
 }
 
-// CreatePushEvent creates a new push event configuration.
+// CreatePushEvent 创建通知事件
+// @Summary 创建通知事件
+// @Description 绑定系统内置事件或异步任务、推送渠道、接收目标并创建通知事件配置，需要管理员权限
+// @Tags admin-push
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body model.CreatePushEventRequest true "创建参数"
+// @Success 200 {object} response.Any{data=model.PushEvent} "创建成功"
+// @Router /api/v1/admin/push/events [post]
 func CreatePushEvent(c *gin.Context) {
 	handleJSONRequest(c, service.CreatePushEvent)
 }
 
-// DeletePushEvent deletes a push event configuration by ID.
+// DeletePushEvent 删除通知事件配置
+// @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 DeletePushEvent(c *gin.Context) {
 	id, ok := parsePushEventID(c)
 	if !ok {
@@ -69,7 +100,17 @@ func DeletePushEvent(c *gin.Context) {
 	c.JSON(http.StatusOK, response.OKNil())
 }
 
-// UpdatePushEvent updates an existing push event.
+// UpdatePushEvent 更新通知事件
+// @Summary 更新通知事件
+// @Description 更新已有通知事件的推送渠道、接收目标和内容模板，需要管理员权限
+// @Tags admin-push
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "事件 ID"
+// @Param request body model.UpdatePushEventRequest true "更新参数"
+// @Success 200 {object} response.Any{data=string} "修改成功"
+// @Router /api/v1/admin/push/events/{id} [put]
 func UpdatePushEvent(c *gin.Context) {
 	id, ok := parsePushEventID(c)
 	if !ok {
@@ -89,7 +130,15 @@ func UpdatePushEvent(c *gin.Context) {
 	c.JSON(http.StatusOK, response.OKNil())
 }
 
-// TogglePushEvent toggles the enabled state of a push event.
+// TogglePushEvent 快捷切换通知事件启用状态
+// @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 TogglePushEvent(c *gin.Context) {
 	id, ok := parsePushEventID(c)
 	if !ok {
@@ -104,7 +153,18 @@ func TogglePushEvent(c *gin.Context) {
 	c.JSON(http.StatusOK, response.OK(enabled))
 }
 
-// ListPushHistories returns paginated push notification delivery histories.
+// ListPushHistories 分页获取通知推送历史
+// @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 "推送历史列表"
+// @Router /api/v1/admin/push/histories [get]
 func ListPushHistories(c *gin.Context) {
 	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
 	pageSize, _ := strconv.Atoi(c.DefaultQuery("page_size", "20"))
@@ -132,7 +192,16 @@ func ListPushHistories(c *gin.Context) {
 	}))
 }
 
-// TestPush executes a synchronous push test using the specified config.
+// TestPush 测试推送通道发送
+// @Summary 测试推送通道发送
+// @Description 接收临时通知渠道配置并在本地同步调用 Pusher.Send 发送测试消息
+// @Tags admin-push
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body model.TestPushRequest true "测试请求体"
+// @Success 200 {object} response.Any{data=string} "测试成功"
+// @Router /api/v1/admin/push/test [post]
 func TestPush(c *gin.Context) {
 	var req model.TestPushRequest
 	if err := c.ShouldBindJSON(&req); err != nil {