feat(ops): add object storage management and site-mapping CSV import/export

Ship the Ops backstage 对象存储 page (browse / upload / move / delete /
folder ops) backed by a new object-storage service + handler, with the
shared storage client extended with List/Stat/Copy/Usage/DownloadURL so
both MinIO and Aliyun providers cover the new surface. Add
ForcePathStyle to the object-storage config and treat r2/s3/custom_s3
as external providers so Cloudflare R2 and other S3-compatibles can
share the MinIO client path without spinning up the bundled MinIO.

Also add CSV import/export + template download to the site-domain
mappings page, raise gin MaxMultipartMemory to 8 MiB for the new
multipart endpoints, register Ops swagger routes, and extend the
descriptions-parity test to cover the ops router.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

server/internal/ops/transport/object_storage_handler.go

@@ -0,0 +1,235 @@
+package transport
+
+import (
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/geo-platform/tenant-api/internal/ops/app"
+	"github.com/geo-platform/tenant-api/internal/shared/objectstorage"
+	"github.com/geo-platform/tenant-api/internal/shared/response"
+)
+
+const (
+	maxObjectStorageUploadBytes    = 500 * 1024 * 1024
+	maxObjectStorageMultipartBytes = maxObjectStorageUploadBytes + 1*1024*1024
+)
+
+type moveObjectStorageObjectRequest struct {
+	SourceKey      string `json:"source_key" binding:"required"`
+	DestinationKey string `json:"destination_key" binding:"required"`
+	Overwrite      bool   `json:"overwrite"`
+	DeleteSource   *bool  `json:"delete_source"`
+}
+
+type createObjectStorageFolderRequest struct {
+	Prefix string `json:"prefix" binding:"required"`
+}
+
+func listObjectStorageObjectsHandler(svc *app.ObjectStorageService) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		size, _ := strconv.Atoi(c.DefaultQuery("size", "100"))
+		result, err := svc.List(c.Request.Context(), app.ObjectStorageListInput{
+			Prefix:            c.Query("prefix"),
+			Keyword:           c.Query("keyword"),
+			ContinuationToken: c.Query("continuation_token"),
+			StartAfter:        c.Query("start_after"),
+			Recursive:         c.Query("recursive") == "true",
+			Size:              size,
+		})
+		if err != nil {
+			response.Error(c, err)
+			return
+		}
+		response.Success(c, result)
+	}
+}
+
+func getObjectStorageUsageHandler(svc *app.ObjectStorageService) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		result, err := svc.Usage(c.Request.Context())
+		if err != nil {
+			response.Error(c, err)
+			return
+		}
+		response.Success(c, result)
+	}
+}
+
+func getObjectStorageObjectHandler(svc *app.ObjectStorageService) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		result, err := svc.Get(c.Request.Context(), c.Query("key"))
+		if err != nil {
+			response.Error(c, err)
+			return
+		}
+		response.Success(c, result)
+	}
+}
+
+func resolveObjectStorageObjectURLHandler(svc *app.ObjectStorageService) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		urlValue, err := svc.ResolvePublicURL(c.Request.Context(), c.Query("key"))
+		if err != nil {
+			response.Error(c, err)
+			return
+		}
+		response.Success(c, gin.H{"url": urlValue})
+	}
+}
+
+func resolveObjectStorageObjectDownloadURLHandler(svc *app.ObjectStorageService) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		urlValue, err := svc.ResolveDownloadURL(c.Request.Context(), c.Query("key"))
+		if err != nil {
+			response.Error(c, err)
+			return
+		}
+		response.Success(c, gin.H{"url": urlValue})
+	}
+}
+
+func downloadObjectStorageObjectHandler(svc *app.ObjectStorageService) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		key := c.Query("key")
+		content, info, err := svc.Download(c.Request.Context(), key)
+		if err != nil {
+			response.Error(c, err)
+			return
+		}
+		c.Header("Cache-Control", "no-store")
+		c.Header("Content-Disposition", objectStorageDownloadDisposition(key))
+		c.Data(http.StatusOK, objectStorageDownloadContentType(info, content), content)
+	}
+}
+
+func uploadObjectStorageObjectHandler(svc *app.ObjectStorageService) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if c.Request.ContentLength > maxObjectStorageMultipartBytes {
+			response.Error(c, response.ErrBadRequest(40095, "object_storage_file_too_large", "单个对象不能超过 500MB"))
+			return
+		}
+		c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, maxObjectStorageMultipartBytes)
+
+		fileHeader, err := c.FormFile("file")
+		if err != nil {
+			if strings.Contains(err.Error(), "request body too large") {
+				response.Error(c, response.ErrBadRequest(40095, "object_storage_file_too_large", "单个对象不能超过 500MB"))
+				return
+			}
+			response.Error(c, response.ErrBadRequest(40094, "object_storage_file_required", "请选择要上传的文件"))
+			return
+		}
+		file, err := fileHeader.Open()
+		if err != nil {
+			response.Error(c, response.ErrBadRequest(40094, "object_storage_file_open_failed", "文件读取失败"))
+			return
+		}
+		defer file.Close()
+
+		content, err := io.ReadAll(io.LimitReader(file, maxObjectStorageUploadBytes+1))
+		if err != nil {
+			response.Error(c, response.ErrBadRequest(40094, "object_storage_file_read_failed", "文件读取失败"))
+			return
+		}
+		if len(content) > maxObjectStorageUploadBytes {
+			response.Error(c, response.ErrBadRequest(40095, "object_storage_file_too_large", "单个对象不能超过 500MB"))
+			return
+		}
+		result, err := svc.Upload(c.Request.Context(), actorFromGin(c), app.ObjectStorageUploadInput{
+			ObjectKey:   c.PostForm("key"),
+			FileName:    fileHeader.Filename,
+			Content:     content,
+			ContentType: c.PostForm("content_type"),
+			Overwrite:   c.PostForm("overwrite") == "true",
+		})
+		if err != nil {
+			response.Error(c, err)
+			return
+		}
+		response.Success(c, result)
+	}
+}
+
+func moveObjectStorageObjectHandler(svc *app.ObjectStorageService) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		var body moveObjectStorageObjectRequest
+		if err := c.ShouldBindJSON(&body); err != nil {
+			response.Error(c, response.ErrBadRequest(40000, "invalid_payload", err.Error()))
+			return
+		}
+		deleteSource := true
+		if body.DeleteSource != nil {
+			deleteSource = *body.DeleteSource
+		}
+		result, err := svc.Move(c.Request.Context(), actorFromGin(c), app.ObjectStorageMoveInput{
+			SourceKey:      body.SourceKey,
+			DestinationKey: body.DestinationKey,
+			Overwrite:      body.Overwrite,
+			DeleteSource:   deleteSource,
+		})
+		if err != nil {
+			response.Error(c, err)
+			return
+		}
+		response.Success(c, result)
+	}
+}
+
+func deleteObjectStorageObjectHandler(svc *app.ObjectStorageService) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		key := c.Query("key")
+		if err := svc.Delete(c.Request.Context(), actorFromGin(c), key); err != nil {
+			response.Error(c, err)
+			return
+		}
+		response.Success(c, gin.H{"key": key})
+	}
+}
+
+func createObjectStorageFolderHandler(svc *app.ObjectStorageService) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		var body createObjectStorageFolderRequest
+		if err := c.ShouldBindJSON(&body); err != nil {
+			response.Error(c, response.ErrBadRequest(40000, "invalid_payload", err.Error()))
+			return
+		}
+		result, err := svc.CreateFolder(c.Request.Context(), actorFromGin(c), app.ObjectStorageFolderCreateInput{
+			Prefix: body.Prefix,
+		})
+		if err != nil {
+			response.Error(c, err)
+			return
+		}
+		response.Success(c, result)
+	}
+}
+
+func deleteObjectStorageFolderHandler(svc *app.ObjectStorageService) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		prefix := c.Query("prefix")
+		result, err := svc.DeleteFolder(c.Request.Context(), actorFromGin(c), prefix)
+		if err != nil {
+			response.Error(c, err)
+			return
+		}
+		response.Success(c, result)
+	}
+}
+
+func objectStorageDownloadDisposition(key string) string {
+	return objectstorage.DownloadContentDisposition(key)
+}
+
+func objectStorageDownloadContentType(info *objectstorage.ObjectInfo, content []byte) string {
+	if info != nil && strings.TrimSpace(info.ContentType) != "" {
+		return info.ContentType
+	}
+	if len(content) > 0 {
+		return http.DetectContentType(content)
+	}
+	return "application/octet-stream"
+}

server/internal/ops/transport/router.go

@@ -9,25 +9,27 @@ import (
 	sharedconfig "github.com/geo-platform/tenant-api/internal/shared/config"
 	"github.com/geo-platform/tenant-api/internal/shared/middleware"
 	"github.com/geo-platform/tenant-api/internal/shared/response"
+	"github.com/geo-platform/tenant-api/internal/shared/swagger"
 )
 
 type Deps struct {
-	Engine       *gin.Engine
-	Server       sharedconfig.ServerConfig
-	Logger       *zap.Logger
-	DB           *pgxpool.Pool
-	MonitoringDB *pgxpool.Pool
-	Issuer       *app.TokenIssuer
-	Auth         *app.AuthService
-	Accounts     *app.AccountService
-	AdminUsers   *app.AdminUserService
-	Jobs         *app.JobService
-	KolSubs      *app.KolSubscriptionService
-	Audits       *app.AuditService
-	SiteDomains  *app.SiteDomainMappingService
-	Releases     *app.DesktopClientReleaseService
-	Compliance   *app.ComplianceService
-	Scheduler    *app.SchedulerService
+	Engine        *gin.Engine
+	Server        sharedconfig.ServerConfig
+	Logger        *zap.Logger
+	DB            *pgxpool.Pool
+	MonitoringDB  *pgxpool.Pool
+	Issuer        *app.TokenIssuer
+	Auth          *app.AuthService
+	Accounts      *app.AccountService
+	AdminUsers    *app.AdminUserService
+	Jobs          *app.JobService
+	KolSubs       *app.KolSubscriptionService
+	Audits        *app.AuditService
+	SiteDomains   *app.SiteDomainMappingService
+	Releases      *app.DesktopClientReleaseService
+	ObjectStorage *app.ObjectStorageService
+	Compliance    *app.ComplianceService
+	Scheduler     *app.SchedulerService
 }
 
 func (d Deps) ServerAllowedOrigins() []string {
@@ -132,11 +134,25 @@ func RegisterRoutes(d Deps) {
 		authed.GET("/scheduler/instances", listSchedulerInstancesHandler(d.Scheduler))
 
 		authed.GET("/site-domain-mappings", listSiteDomainMappingsHandler(d.SiteDomains))
+		authed.GET("/site-domain-mappings/export", exportSiteDomainMappingsHandler(d.SiteDomains))
+		authed.POST("/site-domain-mappings/import", importSiteDomainMappingsHandler(d.SiteDomains))
 		authed.POST("/site-domain-mappings", createSiteDomainMappingHandler(d.SiteDomains))
 		authed.PATCH("/site-domain-mappings/:id", updateSiteDomainMappingHandler(d.SiteDomains))
 		authed.POST("/site-domain-mappings/:id/active", setSiteDomainMappingActiveHandler(d.SiteDomains))
 		authed.DELETE("/site-domain-mappings/:id", deleteSiteDomainMappingHandler(d.SiteDomains))
 
+		authed.GET("/object-storage/objects", listObjectStorageObjectsHandler(d.ObjectStorage))
+		authed.GET("/object-storage/usage", getObjectStorageUsageHandler(d.ObjectStorage))
+		authed.GET("/object-storage/objects/detail", getObjectStorageObjectHandler(d.ObjectStorage))
+		authed.GET("/object-storage/objects/url", resolveObjectStorageObjectURLHandler(d.ObjectStorage))
+		authed.GET("/object-storage/objects/download-url", resolveObjectStorageObjectDownloadURLHandler(d.ObjectStorage))
+		authed.GET("/object-storage/objects/download", downloadObjectStorageObjectHandler(d.ObjectStorage))
+		authed.POST("/object-storage/objects/upload", uploadObjectStorageObjectHandler(d.ObjectStorage))
+		authed.POST("/object-storage/objects/move", moveObjectStorageObjectHandler(d.ObjectStorage))
+		authed.DELETE("/object-storage/objects", deleteObjectStorageObjectHandler(d.ObjectStorage))
+		authed.POST("/object-storage/folders", createObjectStorageFolderHandler(d.ObjectStorage))
+		authed.DELETE("/object-storage/folders", deleteObjectStorageFolderHandler(d.ObjectStorage))
+
 		authed.GET("/desktop-client/releases", listDesktopClientReleasesHandler(d.Releases))
 		authed.POST("/desktop-client/releases/upload", uploadDesktopClientReleaseHandler(d.Releases))
 		authed.POST("/desktop-client/releases", createDesktopClientReleaseHandler(d.Releases))
@@ -166,4 +182,11 @@ func RegisterRoutes(d Deps) {
 		compliance.GET("/stats", complianceStatsHandler(d.Compliance))
 		compliance.GET("/records", listComplianceRecordsHandler(d.Compliance))
 	}
+
+	if swagger.EnabledForMode(d.Server.Mode) {
+		swagger.Register(d.Engine, swagger.Config{
+			Title:   "省心推 Ops API",
+			Version: "dev",
+		})
+	}
 }

server/internal/ops/transport/site_domain_mapping_handler.go

@@ -1,7 +1,11 @@
 package transport
 
 import (
+	"fmt"
+	"io"
+	"net/http"
 	"strconv"
+	"time"
 
 	"github.com/gin-gonic/gin"
 
@@ -38,6 +42,58 @@ func listSiteDomainMappingsHandler(svc *app.SiteDomainMappingService) gin.Handle
 	}
 }
 
+func exportSiteDomainMappingsHandler(svc *app.SiteDomainMappingService) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		data, err := svc.ExportCSV(c.Request.Context(), actorFromGin(c), app.SiteDomainMappingListInput{
+			Keyword:  c.Query("keyword"),
+			IsActive: parseOptionalBoolQuery(c.Query("is_active")),
+		})
+		if err != nil {
+			response.Error(c, err)
+			return
+		}
+		fileName := fmt.Sprintf("site-domain-mappings-%s.csv", time.Now().Format("20060102150405"))
+		c.Header("Content-Type", "text/csv; charset=utf-8")
+		c.Header("Content-Disposition", fmt.Sprintf(`attachment; filename="%s"`, fileName))
+		c.Data(http.StatusOK, "text/csv; charset=utf-8", data)
+	}
+}
+
+func importSiteDomainMappingsHandler(svc *app.SiteDomainMappingService) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		fileHeader, err := c.FormFile("file")
+		if err != nil {
+			response.Error(c, response.ErrBadRequest(40057, "missing_site_domain_mapping_import_file", "请选择 CSV 文件"))
+			return
+		}
+		file, err := fileHeader.Open()
+		if err != nil {
+			response.Error(c, err)
+			return
+		}
+		defer file.Close()
+
+		content, err := io.ReadAll(io.LimitReader(file, 2*1024*1024+1))
+		if err != nil {
+			response.Error(c, err)
+			return
+		}
+		if len(content) > 2*1024*1024 {
+			response.Error(c, response.ErrBadRequest(40058, "site_domain_mapping_import_file_too_large", "CSV 文件不能超过 2MB"))
+			return
+		}
+
+		result, err := svc.ImportCSV(c.Request.Context(), actorFromGin(c), app.SiteDomainMappingImportInput{
+			Content: content,
+		})
+		if err != nil {
+			response.Error(c, err)
+			return
+		}
+		response.Success(c, result)
+	}
+}
+
 func createSiteDomainMappingHandler(svc *app.SiteDomainMappingService) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		var body siteDomainMappingRequest