refactor(openflare): migrate console APIs to v1 and centralize routing

Move OpenFlare management endpoints to /api/v1/custom/openflare with
Wavelet response envelopes and Abort* error handling. Keep agent, relay,
and flared protocol routes on /api/* with the legacy compat format.

- Add apiutil helpers and Swagger annotations for console handlers
- Register all OpenFlare routes in internal/router/openflare (not apps)
- Switch frontend services to OpenFlareBaseService and v1 paths
- Remove dead auth/compat code and legacy-base.service.ts
- Update integration tests and changelog

Wavelet/internal/apps/openflare/update/routers.go

@@ -10,7 +10,8 @@ import (
 	"net/http"
 	"time"
 
-	"github.com/Rain-kl/Wavelet/internal/apps/openflare/compat"
+	"github.com/Rain-kl/Wavelet/internal/apps/openflare/apiutil"
+	"github.com/Rain-kl/Wavelet/internal/common/response"
 	"github.com/gin-gonic/gin"
 	"github.com/gorilla/websocket"
 )
@@ -19,50 +20,101 @@ var upgradeLogsUpgrader = websocket.Upgrader{
 	CheckOrigin: func(_ *http.Request) bool { return true },
 }
 
-// GetLatestReleaseHandler returns the newest GitHub release for the legacy update UI.
+
+// GetLatestReleaseHandler 获取最新 GitHub 发布版本。
+// @Summary 获取最新服务端发布版本
+// @Description 查询 OpenFlare 服务端最新 GitHub Release 及升级状态，需要管理员权限
+// @Tags openflare-update
+// @Produce json
+// @Security SessionCookie
+// @Param channel query string false "发布渠道（stable/preview）"
+// @Success 200 {object} response.Any{data=update.LatestReleaseView} "最新发布信息"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/custom/openflare/update/latest-release [get]
 func GetLatestReleaseHandler(c *gin.Context) {
 	release, err := GetLatestRelease(c.Request.Context(), c.Query("channel"))
-	if err != nil {
-		compat.Fail(c, err.Error())
+	if apiutil.AbortBadRequestOnError(c, err) {
 		return
 	}
-	compat.OK(c, release)
+	c.JSON(http.StatusOK, response.OK(release))
 }
 
-// UpgradeServerHandler schedules an automatic upgrade from the latest release.
+// UpgradeServerHandler 调度自动升级任务。
+// @Summary 触发服务端自动升级
+// @Description 从最新 Release 调度 OpenFlare 服务端自动升级，需要管理员权限
+// @Tags openflare-update
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body update.upgradeRequest false "升级参数"
+// @Success 200 {object} response.Any{data=update.LatestReleaseView} "升级任务已调度"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/custom/openflare/update/upgrade [post]
 func UpgradeServerHandler(c *gin.Context) {
 	var request upgradeRequest
 	if err := bindOptionalJSON(c.Request.Body, &request); err != nil {
-		compat.Fail(c, "无效的参数")
+		response.AbortBadRequest(c, "无效的参数")
 		return
 	}
 
 	release, err := ScheduleUpgrade(c.Request.Context(), request.Channel)
-	if err != nil {
-		compat.Fail(c, err.Error())
+	if apiutil.AbortBadRequestOnError(c, err) {
 		return
 	}
 
-	okWithMessage(c, release, "服务升级任务已启动，下载完成后将自动重启。")
+	c.JSON(http.StatusOK, response.OK(release))
 }
 
-// UploadManualServerBinaryHandler rejects manual uploads (feature disabled upstream).
+// UploadManualServerBinaryHandler 上传手动升级二进制（已禁用）。
+// @Summary 上传手动升级二进制
+// @Description 上传服务端二进制以进行手动升级（当前功能已禁用），需要管理员权限
+// @Tags openflare-update
+// @Accept multipart/form-data
+// @Produce json
+// @Security SessionCookie
+// @Param binary formData file true "服务端二进制文件"
+// @Failure 400 {object} response.Any "功能已禁用或参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Router /api/v1/custom/openflare/update/manual-upload [post]
 func UploadManualServerBinaryHandler(c *gin.Context) {
-	if err := UploadManualBinary(); err != nil {
-		compat.Fail(c, err.Error())
+	if apiutil.AbortBadRequestOnError(c, UploadManualBinary()) {
 		return
 	}
 }
 
-// ConfirmManualServerUpgradeHandler rejects manual upgrades (feature disabled upstream).
+// ConfirmManualServerUpgradeHandler 确认手动升级（已禁用）。
+// @Summary 确认手动服务端升级
+// @Description 确认并执行手动上传的服务端升级（当前功能已禁用），需要管理员权限
+// @Tags openflare-update
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Failure 400 {object} response.Any "功能已禁用或参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Router /api/v1/custom/openflare/update/manual-upgrade [post]
 func ConfirmManualServerUpgradeHandler(c *gin.Context) {
-	if err := ConfirmManualUpgrade(); err != nil {
-		compat.Fail(c, err.Error())
+	if apiutil.AbortBadRequestOnError(c, ConfirmManualUpgrade()) {
 		return
 	}
 }
 
-// StreamServerUpgradeLogsHandler streams upgrade progress snapshots over WebSocket.
+// StreamServerUpgradeLogsHandler 通过 WebSocket 推送升级日志。
+// @Summary 流式获取服务端升级日志
+// @Description 通过 WebSocket 推送升级进度快照，需要管理员权限
+// @Tags openflare-update
+// @Security SessionCookie
+// @Success 101 {object} update.StreamSnapshot "WebSocket 升级日志流"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Router /api/v1/custom/openflare/update/logs/ws [get]
 func StreamServerUpgradeLogsHandler(c *gin.Context) {
 	conn, err := upgradeLogsUpgrader.Upgrade(c.Writer, c.Request, nil)
 	if err != nil {
@@ -97,17 +149,9 @@ func StreamServerUpgradeLogsHandler(c *gin.Context) {
 	}
 }
 
-func okWithMessage(c *gin.Context, data any, message string) {
-	c.JSON(http.StatusOK, gin.H{
-		"success": true,
-		"message": message,
-		"data":    data,
-	})
-}
-
 func bindOptionalJSON(body io.Reader, target any) error {
 	if err := json.NewDecoder(body).Decode(target); err != nil && !errors.Is(err, io.EOF) {
 		return err
 	}
 	return nil
-}
+}