Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

104 KB
Raw Blame
package handler

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"net"
	"net/http"
	"net/url"
	"os"
	"regexp"
	"strconv"
	"strings"
	"time"
	"unicode/utf8"

	"github.com/Tencent/WeKnora/internal/application/repository"
	"github.com/Tencent/WeKnora/internal/application/service"
	"github.com/Tencent/WeKnora/internal/application/service/file"
	"github.com/Tencent/WeKnora/internal/config"
	"github.com/Tencent/WeKnora/internal/database"
	apperrors "github.com/Tencent/WeKnora/internal/errors"
	"github.com/Tencent/WeKnora/internal/infrastructure/docparser"
	"github.com/Tencent/WeKnora/internal/logger"
	modellimiter "github.com/Tencent/WeKnora/internal/models/limiter"
	"github.com/Tencent/WeKnora/internal/runtime"
	"github.com/Tencent/WeKnora/internal/types"
	"github.com/Tencent/WeKnora/internal/types/interfaces"
	secutils "github.com/Tencent/WeKnora/internal/utils"
	"github.com/gin-gonic/gin"
	"github.com/neo4j/neo4j-go-driver/v6/neo4j"
)

type runtimeKnowledgeCanceller interface {
	CancelKnowledgeParse(ctx context.Context, knowledgeID string) (*types.Knowledge, error)
}

// SystemHandler handles system-related requests
type SystemHandler struct {
	cfg              *config.Config
	neo4jDriver      neo4j.Driver
	documentReader   interfaces.DocumentReader
	tenantSvc        interfaces.TenantService
	userSvc          interfaces.UserService
	modelCatalogSvc  *service.ModelCatalogService
	systemSettingSvc interfaces.SystemSettingService
	apiKeySvc        interfaces.TenantAPIKeyService
	// auditSvc is optional — when nil, emitAdminAudit no-ops so unit
	// tests that wire a partial container still compile. In production
	// the dig graph always provides one.
	auditSvc interfaces.AuditLogService
	// taskInspector backs the SystemAdmin runtime queue dashboard. Always
	// provided by the container (asynq-backed in Redis mode, a no-op in
	// Lite mode), so GetRuntimeQueues can distinguish "no queues in this
	// deployment" from "queues are empty".
	taskInspector interfaces.TaskInspector
	// knowledgeSvc supplies the domain-level cancellation path used by the
	// runtime task console. It updates business state and tracing before queue
	// records are removed, unlike a raw Redis deletion.
	knowledgeSvc runtimeKnowledgeCanceller
	// storageBackendRepo lets GetStorageEngineStatus report multi-instance
	// storage backends (Settings → Storage) as "available", not just the legacy
	// singleton tenant.StorageEngineConfig. Optional — nil in partially-wired
	// unit tests, in which case only the legacy config is consulted.
	storageBackendRepo interfaces.StorageBackendRepository
	sandboxConfigSvc   sandboxConfigService
	// startup snapshot for GET /system/capabilities; bound in router.NewRouter.
	deploymentCapabilities DeploymentCapabilitiesData
}

// NewSystemHandler creates a new system handler
func NewSystemHandler(cfg *config.Config,
	neo4jDriver neo4j.Driver,
	documentReader interfaces.DocumentReader,
	tenantSvc interfaces.TenantService,
	userSvc interfaces.UserService,
	systemSettingSvc interfaces.SystemSettingService,
	modelCatalogSvc *service.ModelCatalogService,
	apiKeySvc interfaces.TenantAPIKeyService,
	auditSvc interfaces.AuditLogService,
	taskInspector interfaces.TaskInspector,
	knowledgeSvc interfaces.KnowledgeService,
	storageBackendRepo interfaces.StorageBackendRepository,
	sandboxConfigSvc *service.TenantSandboxConfigService,
) *SystemHandler {
	return &SystemHandler{
		cfg:                cfg,
		neo4jDriver:        neo4jDriver,
		documentReader:     documentReader,
		tenantSvc:          tenantSvc,
		userSvc:            userSvc,
		systemSettingSvc:   systemSettingSvc,
		modelCatalogSvc:    modelCatalogSvc,
		apiKeySvc:          apiKeySvc,
		auditSvc:           auditSvc,
		taskInspector:      taskInspector,
		knowledgeSvc:       knowledgeSvc,
		storageBackendRepo: storageBackendRepo,
		sandboxConfigSvc:   sandboxConfigSvc,
	}
}

type platformAPIKeyCreateRequest struct {
	Name         string   `json:"name"`
	Capabilities []string `json:"capabilities"`
	ExpiresAt    *int64   `json:"expires_at_unix"`
}

// ListPlatformAPIKeys godoc
// @Summary      List platform API keys
// @Description  Lists non-workspace API keys. Full tokens are always masked. Human SystemAdmin only.
// @Tags         System Admin
// @Produce      json
// @Success      200 {object} handler.DataResponse{data=[]handler.tenantAPIKeyResponse}
// @Security     Bearer
// @Router       /system/admin/api-keys [get]
func (h *SystemHandler) ListPlatformAPIKeys(c *gin.Context) {
	keys, err := h.apiKeySvc.ListPlatformAPIKeys(c.Request.Context())
	if err != nil {
		c.Error(apperrors.NewInternalServerError("Failed to list platform API keys").WithDetails(err.Error()))
		return
	}
	response := make([]tenantAPIKeyResponse, 0, len(keys))
	for _, key := range keys {
		item := tenantAPIKeyForResponse(key)
		item.APIKey = maskManagedAPIKey(key.APIKey)
		response = append(response, item)
	}
	c.JSON(http.StatusOK, gin.H{"success": true, "data": response})
}

// CreatePlatformAPIKey godoc
// @Summary      Create a platform API key
// @Description  Creates a capability-scoped key that may target any workspace through X-Tenant-ID. The plaintext token is returned once. Human SystemAdmin only.
// @Tags         System Admin
// @Accept       json
// @Produce      json
// @Param        request body platformAPIKeyCreateRequest true "Platform API key"
// @Success      201 {object} handler.DataResponse{data=handler.tenantAPIKeyCreateResponse}
// @Security     Bearer
// @Router       /system/admin/api-keys [post]
func (h *SystemHandler) CreatePlatformAPIKey(c *gin.Context) {
	var req platformAPIKeyCreateRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.Error(apperrors.NewValidationError("Invalid request data").WithDetails(err.Error()))
		return
	}
	if strings.TrimSpace(req.Name) == "" {
		c.Error(apperrors.NewValidationError("name is required"))
		return
	}
	capabilities := types.NormalizeAPIKeyCapabilities(types.StringArray(req.Capabilities))
	if len(capabilities) == 0 || len(capabilities) != len(req.Capabilities) {
		c.Error(apperrors.NewValidationError("valid capabilities are required"))
		return
	}
	var expiresAt *time.Time
	if req.ExpiresAt != nil {
		value := time.Unix(*req.ExpiresAt, 0).UTC()
		if !value.After(time.Now().UTC()) {
			c.Error(apperrors.NewValidationError("expires_at_unix must be in the future"))
			return
		}
		expiresAt = &value
	}
	result, err := h.apiKeySvc.CreateAPIKey(c.Request.Context(), interfaces.TenantAPIKeyCreateRequest{
		ScopeType:    types.APIKeyScopePlatform,
		Name:         req.Name,
		Capabilities: []string(capabilities),
		ExpiresAt:    expiresAt,
	})
	if err != nil {
		c.Error(apperrors.NewInternalServerError("Failed to create platform API key").WithDetails(err.Error()))
		return
	}
	item := tenantAPIKeyForResponse(result.APIKey)
	item.APIKey = maskManagedAPIKey(result.Token)
	h.emitAPIKeyAudit(c.Request.Context(), types.AuditActionSystemAPIKeyCreated, result.APIKey)
	c.JSON(http.StatusCreated, gin.H{
		"success": true,
		"data":    tenantAPIKeyCreateResponse{tenantAPIKeyResponse: item, Token: result.Token},
	})
}

// DeletePlatformAPIKey godoc
// @Summary      Revoke a platform API key
// @Description  Immediately revokes a platform API key. Human SystemAdmin only.
// @Tags         System Admin
// @Produce      json
// @Param        key_id path int true "API key ID"
// @Success      200 {object} handler.SuccessResponse
// @Security     Bearer
// @Router       /system/admin/api-keys/{key_id} [delete]
func (h *SystemHandler) DeletePlatformAPIKey(c *gin.Context) {
	id, err := strconv.ParseUint(c.Param("key_id"), 10, 64)
	if err != nil || id == 0 {
		c.Error(apperrors.NewBadRequestError("Invalid API key ID"))
		return
	}
	if err := h.apiKeySvc.RevokePlatformAPIKey(c.Request.Context(), id); err != nil {
		c.Error(apperrors.NewNotFoundError("Platform API key not found"))
		return
	}
	h.emitAPIKeyAudit(c.Request.Context(), types.AuditActionSystemAPIKeyRevoked, &types.TenantAPIKey{ID: id})
	c.JSON(http.StatusOK, gin.H{"success": true})
}

func maskManagedAPIKey(token string) string {
	token = strings.TrimSpace(token)
	if len(token) <= 12 {
		return "***"
	}
	return token[:7] + "..." + token[len(token)-4:]
}

func (h *SystemHandler) emitAPIKeyAudit(ctx context.Context, action types.AuditAction, key *types.TenantAPIKey) {
	if h.auditSvc == nil || key == nil {
		return
	}
	actorID, _ := types.UserIDFromContext(ctx)
	details, _ := json.Marshal(map[string]any{
		"scope_type":   types.APIKeyScopePlatform,
		"capabilities": key.Capabilities,
	})
	_ = h.auditSvc.Log(ctx, &types.AuditLog{
		TenantID: 0, ActorUserID: actorID, ActorRole: systemAuditActorRole(ctx),
		Action: action, TargetType: "api_key", TargetID: strconv.FormatUint(key.ID, 10),
		Outcome: types.AuditOutcomeSuccess, Details: types.JSON(details),
	})
}

func systemAuditActorRole(ctx context.Context) string {
	if scope, ok := types.TenantAPIKeyScopeFromContext(ctx); ok && scope.IsPlatform() {
		return "platform_api_key"
	}
	return "system_admin"
}

// emitAdminAudit writes one audit row for a system-admin lifecycle event
// (promote / revoke). Best-effort — a nil audit service or a write
// failure does not bubble up to the caller. Mirrors the failure
// semantics of tenantMemberService.emitAudit and the system settings
// audit hook.
//
// `details` may be nil; the JSON `{}` default applies.
func (h *SystemHandler) emitAdminAudit(
	ctx context.Context,
	action types.AuditAction,
	target *types.User,
	details map[string]any,
) {
	if h.auditSvc == nil {
		return
	}
	actorID, _ := types.UserIDFromContext(ctx)
	var detailsJSON types.JSON
	if details != nil {
		if b, err := json.Marshal(details); err == nil {
			detailsJSON = types.JSON(b)
		}
	}
	entry := &types.AuditLog{
		// tenant_id=0 marks the row as system-scope. The audit_logs
		// table is tenant-scoped; 0 is the convention for platform-wide
		// events (matches AuditActionSystemSettingChanged).
		TenantID:    0,
		ActorUserID: actorID,
		ActorRole:   systemAuditActorRole(ctx),
		Action:      action,
		TargetType:  "user",
		Outcome:     types.AuditOutcomeSuccess,
		Details:     detailsJSON,
	}
	if target != nil {
		entry.TargetID = target.ID
		entry.TargetUserID = target.ID
	}
	_ = h.auditSvc.Log(ctx, entry)
}

// GetSystemInfoResponse defines the response structure for system info
type GetSystemInfoResponse struct {
	Version             string `json:"version" extensions:"x-agent"`
	Edition             string `json:"edition" extensions:"x-agent"`
	CommitID            string `json:"commit_id,omitempty" extensions:"x-agent"`
	BuildTime           string `json:"build_time,omitempty" extensions:"x-agent"`
	GoVersion           string `json:"go_version,omitempty" extensions:"x-agent"`
	KeywordIndexEngine  string `json:"keyword_index_engine,omitempty" extensions:"x-agent"`
	VectorStoreEngine   string `json:"vector_store_engine,omitempty" extensions:"x-agent"`
	GraphDatabaseEngine string `json:"graph_database_engine,omitempty" extensions:"x-agent"`
	MinioEnabled        bool   `json:"minio_enabled,omitempty" extensions:"x-agent"`
	DBVersion           string `json:"db_version,omitempty" extensions:"x-agent"`
	DBMigrationFailed   bool   `json:"db_migration_failed" extensions:"x-agent"`
	// DBMigrationError carries the human-readable error message recorded when
	// the most recent startup migration attempt failed. Empty when migrations
	// succeeded; non-empty values let the frontend surface a troubleshooting
	// banner instead of silently hiding the DB version row (see issue #1319).
	DBMigrationError string `json:"db_migration_error,omitempty"`
	// StartedAt is the server process boot time (RFC3339, UTC).
	StartedAt string `json:"started_at,omitempty" extensions:"x-agent"`
	// UptimeSeconds is seconds elapsed since process start.
	UptimeSeconds int64 `json:"uptime_seconds,omitempty" extensions:"x-agent"`
}

// 编译时注入的版本信息
var (
	Version   = "unknown"
	Edition   = "standard"
	CommitID  = "unknown"
	BuildTime = "unknown"
	GoVersion = "unknown"
)

// GetSystemInfo godoc
// @Summary      获取系统信息
// @Description  获取系统版本、构建信息和引擎配置
// @Tags         系统
// @Accept       json
// @Produce      json
// @Success      200  {object}  DataResponse{data=GetSystemInfoResponse}  "系统信息"
// @x-agent {"id":"system.get_info","risk":"read"}
// @x-agent-hint "Reads the backend version, edition, build, runtime, database migration status and configured engines. Empty or unknown means unavailable information. Engine configuration does not prove connectivity. Raw migration errors are omitted. Frontend build/version is separate and is not reported by this API; do not infer frontend/backend version agreement or available upgrades."
// @Router       /system/info [get]
func (h *SystemHandler) GetSystemInfo(c *gin.Context) {
	ctx := logger.CloneContext(c.Request.Context())

	// Get keyword index engine from RETRIEVE_DRIVER
	keywordIndexEngine := h.getKeywordIndexEngine()

	// Get vector store engine from config or RETRIEVE_DRIVER
	vectorStoreEngine := h.getVectorStoreEngine()

	// Get graph database engine from NEO4J_ENABLE
	graphDatabaseEngine := h.getGraphDatabaseEngine()

	// Get MinIO enabled status
	minioEnabled := h.isMinioConfigured(c)

	dbMigrationErr := database.CachedMigrationError()
	var dbVersion string
	if ver, dirty, ok := database.CachedMigrationVersion(); ok {
		dbVersion = fmt.Sprintf("%d", ver)
		if dirty {
			dbVersion += " (dirty)"
		}
		if dbMigrationErr != "" {
			dbVersion += " (failed)"
		}
	} else if dbMigrationErr != "" {
		// Failure happened before m.Version() could be read (e.g. could not
		// open the database). Still emit a placeholder so the frontend renders
		// the row and shows the troubleshooting banner.
		dbVersion = "unknown"
	}

	var startedAt string
	var uptimeSec int64
	if boot := runtime.ServerStartedAt(); !boot.IsZero() {
		startedAt = boot.UTC().Format(time.RFC3339)
		uptimeSec = int64(runtime.ServerUptime().Seconds())
	}

	response := GetSystemInfoResponse{
		Version:             Version,
		Edition:             Edition,
		CommitID:            CommitID,
		BuildTime:           BuildTime,
		GoVersion:           GoVersion,
		KeywordIndexEngine:  keywordIndexEngine,
		VectorStoreEngine:   vectorStoreEngine,
		GraphDatabaseEngine: graphDatabaseEngine,
		MinioEnabled:        minioEnabled,
		DBVersion:           dbVersion,
		DBMigrationError:    dbMigrationErr,
		DBMigrationFailed:   dbMigrationErr != "",
		StartedAt:           startedAt,
		UptimeSeconds:       uptimeSec,
	}

	logger.Info(ctx, "System info retrieved successfully")
	c.JSON(200, gin.H{
		"code": 0,
		"msg":  "success",
		"data": response,
	})
}

func (h *SystemHandler) getDocReaderConnInfo() (addr, transport string) {
	addr = strings.TrimSpace(os.Getenv("DOCREADER_ADDR"))
	transport = strings.TrimSpace(os.Getenv("DOCREADER_TRANSPORT"))
	if transport == "" {
		transport = "grpc"
	}
	transport = strings.ToLower(transport)
	return addr, transport
}

// ListParserEngines returns available document parser engines.
// Merges Go-native static engines with engines discovered from the remote
// docreader service, so newly added Python engines are auto-discovered.
// @Summary      列出可用的文档解析引擎
// @Tags         系统
// @Produce      json
// @Success      200  {object}  handler.ListParserEnginesResponse  "解析引擎列表"
// @x-agent {"id":"knowledge_base.list_parser_engines","risk":"read"}
// @x-agent-hint "Lists parser engine names, supported file extensions and availability. Choose an available engine supporting every requested file type before setting parser_engine in knowledge_base.update. Never guess an engine name."
// @Router       /system/parser-engines [get]
func (h *SystemHandler) ListParserEngines(c *gin.Context) {
	var overrides map[string]string
	if v, exists := c.Get(types.TenantInfoContextKey.String()); exists {
		if tenant, ok := v.(*types.Tenant); ok && tenant != nil {
			if tenant.ParserEngineConfig != nil {
				overrides = tenant.ParserEngineConfig.ToOverridesMap()
			}
			if creds := tenant.Credentials.GetWeKnoraCloud(); creds != nil {
				if overrides == nil {
					overrides = make(map[string]string)
				}
				overrides["weknoracloud_app_id"] = creds.AppID
			}
		}
	}

	reader, docreaderAddr, docreaderTransport := h.resolveDocReader(c.Request.Context(), overrides)
	connected := reader != nil && reader.IsConnected()
	remoteEngines := h.fetchRemoteEngines(c.Request.Context(), reader, overrides)
	engines := docparser.ListAllEngines(connected, overrides, remoteEngines)
	c.JSON(200, gin.H{"code": 0, "msg": "success", "data": engines, "docreader_addr": docreaderAddr, "docreader_transport": docreaderTransport, "connected": connected})
}

// ReconnectDocReader reconnects the document converter to a new (or same) DocReader address.
// @Summary      重连文档解析服务
// @Tags         系统
// @Accept       json
// @Produce      json
// @Param        request  body  object{addr string} true "DocReader 地址"
// @Success      200
// @Router       /system/docreader/reconnect [post]
func (h *SystemHandler) ReconnectDocReader(c *gin.Context) {
	var req struct {
		Addr string `json:"addr" binding:"required"`
	}
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(400, gin.H{"code": 1, "msg": "请提供 addr 参数"})
		return
	}
	addr := strings.TrimSpace(req.Addr)
	if addr == "" {
		c.JSON(400, gin.H{"code": 1, "msg": "addr 不能为空"})
		return
	}

	// SSRF validation for docreader address
	if err := secutils.ValidateURLForSSRF(addr); err != nil {
		logger.Warnf(c.Request.Context(), "SSRF validation failed for docreader addr: %v", err)
		c.JSON(400, gin.H{"code": 1, "msg": secutils.FormatSSRFError("DocReader 地址", addr, err)})
		return
	}

	if h.documentReader == nil {
		c.JSON(500, gin.H{"code": 1, "msg": "document converter not initialized"})
		return
	}

	if err := h.documentReader.Reconnect(addr); err != nil {
		logger.Errorf(c.Request.Context(), "Failed to reconnect docreader to %s: %v", addr, err)
		c.JSON(200, gin.H{"code": 1, "msg": fmt.Sprintf("连接失败: %v", err)})
		return
	}

	var overrides map[string]string
	if v, exists := c.Get(types.TenantInfoContextKey.String()); exists {
		if tenant, ok := v.(*types.Tenant); ok && tenant != nil {
			if tenant.ParserEngineConfig != nil {
				overrides = tenant.ParserEngineConfig.ToOverridesMap()
			}
			if creds := tenant.Credentials.GetWeKnoraCloud(); creds != nil {
				if overrides == nil {
					overrides = make(map[string]string)
				}
				overrides["weknoracloud_app_id"] = creds.AppID
			}
		}
	}
	remoteEngines := h.fetchRemoteEngines(c.Request.Context(), h.documentReader, overrides)
	engines := docparser.ListAllEngines(true, overrides, remoteEngines)

	_, docreaderTransport := h.getDocReaderConnInfo()
	c.JSON(200, gin.H{"code": 0, "msg": "连接成功", "data": engines, "docreader_addr": addr, "docreader_transport": docreaderTransport, "connected": true})
}

// CheckParserEngines runs availability check with the given config overrides (e.g. current form values).
// Used to test engine availability without saving; body shape matches ParserEngineConfig.
// @Summary      使用当前参数检测解析引擎可用性
// @Tags         系统
// @Accept       json
// @Produce      json
// @Param        body  body  object  true  "解析引擎配置(与保存接口同结构)"
// @Success      200
// @Router       /system/parser-engines/check [post]
func (h *SystemHandler) CheckParserEngines(c *gin.Context) {
	var body types.ParserEngineConfig
	if err := c.ShouldBindJSON(&body); err != nil {
		c.JSON(400, gin.H{"code": 1, "msg": "请求体格式错误"})
		return
	}
	var existing *types.ParserEngineConfig
	var tenant *types.Tenant
	if v, exists := c.Get(types.TenantInfoContextKey.String()); exists {
		if t, ok := v.(*types.Tenant); ok && t != nil {
			tenant = t
			existing = t.ParserEngineConfig
		}
	}
	merged := types.MergeParserEngineConfigForUpdate(&body, existing)
	overrides := merged.ToOverridesMap()
	if tenant != nil {
		if creds := tenant.Credentials.GetWeKnoraCloud(); creds != nil {
			if overrides == nil {
				overrides = make(map[string]string)
			}
			overrides["weknoracloud_app_id"] = creds.AppID
		}
	}
	reader, docreaderAddr, docreaderTransport := h.resolveDocReader(c.Request.Context(), overrides)
	connected := reader != nil && reader.IsConnected()
	remoteEngines := h.fetchRemoteEngines(c.Request.Context(), reader, overrides)
	engines := docparser.ListAllEngines(connected, overrides, remoteEngines)
	c.JSON(200, gin.H{"code": 0, "msg": "success", "data": engines, "docreader_addr": docreaderAddr, "docreader_transport": docreaderTransport, "connected": connected})
}

func (h *SystemHandler) resolveDocReader(ctx context.Context, overrides map[string]string) (interfaces.DocumentReader, string, string) {
	if len(overrides) > 0 {
		if addr := strings.TrimSpace(overrides["docreader_addr"]); addr != "" && service.IsWeKnoraCloudDocReaderAddr(addr) {
			reader := h.ResolveDocumentReader(ctx, addr)
			return reader, addr, transportFromDocReaderAddr(addr)
		}
	}

	addr, transport := h.getDocReaderConnInfo()
	return h.documentReader, addr, transport
}

func transportFromDocReaderAddr(addr string) string {
	if strings.HasPrefix(strings.ToLower(strings.TrimSpace(addr)), "https://") {
		return "https"
	}
	return "http"
}

// fetchRemoteEngines queries the remote docreader for its engine list.
// Returns nil on any error (e.g. not connected), letting the caller
// fall back to Go's static registry only.
func (h *SystemHandler) fetchRemoteEngines(ctx context.Context, reader interfaces.DocumentReader, overrides map[string]string) []types.ParserEngineInfo {
	if reader == nil || !reader.IsConnected() {
		return nil
	}
	engines, err := reader.ListEngines(ctx, overrides)
	if err != nil {
		logger.Warnf(ctx, "Failed to fetch remote engines from docreader: %v", err)
		return nil
	}
	return engines
}

// getKeywordIndexEngine returns the keyword index engine name
func (h *SystemHandler) getKeywordIndexEngine() string {
	retrieveDriver := os.Getenv("RETRIEVE_DRIVER")
	if retrieveDriver == "" {
		return "未配置"
	}

	drivers := strings.Split(retrieveDriver, ",")
	// Filter out engines that support keyword retrieval
	keywordEngines := []string{}
	for _, driver := range drivers {
		driver = strings.TrimSpace(driver)
		if h.supportsRetrieverType(driver, types.KeywordsRetrieverType) {
			keywordEngines = append(keywordEngines, driver)
		}
	}

	if len(keywordEngines) == 0 {
		return "未配置"
	}
	return strings.Join(keywordEngines, ", ")
}

// getVectorStoreEngine returns the vector store engine name
func (h *SystemHandler) getVectorStoreEngine() string {
	// First check config.yaml
	if h.cfg != nil && h.cfg.VectorDatabase != nil && h.cfg.VectorDatabase.Driver != "" {
		return h.cfg.VectorDatabase.Driver
	}

	// Fallback to RETRIEVE_DRIVER for vector support
	retrieveDriver := os.Getenv("RETRIEVE_DRIVER")
	if retrieveDriver == "" {
		return "未配置"
	}

	drivers := strings.Split(retrieveDriver, ",")
	// Filter out engines that support vector retrieval
	vectorEngines := []string{}
	for _, driver := range drivers {
		driver = strings.TrimSpace(driver)
		if h.supportsRetrieverType(driver, types.VectorRetrieverType) {
			vectorEngines = append(vectorEngines, driver)
		}
	}

	if len(vectorEngines) == 0 {
		return "未配置"
	}
	return strings.Join(vectorEngines, ", ")
}

// getGraphDatabaseEngine returns the graph database engine name
func (h *SystemHandler) getGraphDatabaseEngine() string {
	if h.neo4jDriver == nil {
		return "Not Enabled"
	}
	return "Neo4j"
}

// supportsRetrieverType checks if a driver supports a specific retriever type
// by looking up the retrieverEngineMapping from types package
func (h *SystemHandler) supportsRetrieverType(driver string, retrieverType types.RetrieverType) bool {
	// Get the mapping of all supported drivers and their capabilities
	mapping := types.GetRetrieverEngineMapping()

	// Check if the driver exists in the mapping
	engines, exists := mapping[driver]
	if !exists {
		return false
	}

	// Check if any of the engine configurations support the requested retriever type
	for _, engine := range engines {
		if engine.RetrieverType == retrieverType {
			return true
		}
	}
	return false
}

// getMinioConfig resolves MinIO connection parameters from tenant config (if mode=remote) or env vars (mode=docker/default).
func (h *SystemHandler) getMinioConfig(c *gin.Context) (endpoint, accessKeyID, secretAccessKey string) {
	if v, exists := c.Get(types.TenantInfoContextKey.String()); exists {
		if tenant, ok := v.(*types.Tenant); ok && tenant != nil && tenant.StorageEngineConfig != nil && tenant.StorageEngineConfig.MinIO != nil {
			m := tenant.StorageEngineConfig.MinIO
			if m.Mode == "remote" {
				return m.Endpoint, m.AccessKeyID, m.SecretAccessKey
			}
		}
	}
	endpoint = os.Getenv("MINIO_ENDPOINT")
	accessKeyID = os.Getenv("MINIO_ACCESS_KEY_ID")
	secretAccessKey = os.Getenv("MINIO_SECRET_ACCESS_KEY")
	return
}

// activeBackendProviders returns the set of storage providers that have at
// least one active multi-instance backend registered for the caller's
// workspace. Used to keep GetStorageEngineStatus in sync with the new Storage
// settings UI, which writes to storage_backends rather than the legacy
// tenant.StorageEngineConfig singleton. Best-effort and nil-safe: a missing
// repo, missing tenant, or query error yields an empty set so callers fall
// back to the legacy config checks.
func (h *SystemHandler) activeBackendProviders(c *gin.Context) map[string]bool {
	result := map[string]bool{}
	if h.storageBackendRepo == nil {
		return result
	}
	v, exists := c.Get(types.TenantInfoContextKey.String())
	if !exists {
		return result
	}
	tenant, ok := v.(*types.Tenant)
	if !ok || tenant == nil {
		return result
	}
	backends, err := h.storageBackendRepo.List(c.Request.Context(), tenant.ID)
	if err != nil {
		logger.Warnf(c.Request.Context(), "[storage] list backends for status failed: tenant=%d err=%v", tenant.ID, err)
		return result
	}
	for _, backend := range backends {
		if backend == nil || backend.Status != types.StorageBackendStatusActive {
			continue
		}
		result[strings.ToLower(strings.TrimSpace(backend.Provider))] = true
	}
	return result
}

// isMinioConfigured checks whether MinIO connection info is available (from tenant config or env).
func (h *SystemHandler) isMinioConfigured(c *gin.Context) bool {
	endpoint, accessKeyID, secretAccessKey := h.getMinioConfig(c)
	return endpoint != "" && accessKeyID != "" && secretAccessKey != ""
}

// isMinioEnvAvailable checks whether MinIO env vars (MINIO_ENDPOINT etc.) are set.
func (h *SystemHandler) isMinioEnvAvailable() bool {
	return os.Getenv("MINIO_ENDPOINT") != "" &&
		os.Getenv("MINIO_ACCESS_KEY_ID") != "" &&
		os.Getenv("MINIO_SECRET_ACCESS_KEY") != ""
}

// isCOSConfigured checks whether COS connection info is available from tenant config.
func (h *SystemHandler) isCOSConfigured(c *gin.Context) bool {
	if v, exists := c.Get(types.TenantInfoContextKey.String()); exists {
		if tenant, ok := v.(*types.Tenant); ok && tenant != nil && tenant.StorageEngineConfig != nil && tenant.StorageEngineConfig.COS != nil {
			cosConf := tenant.StorageEngineConfig.COS
			return cosConf.SecretID != "" && cosConf.SecretKey != "" && cosConf.Region != "" && cosConf.BucketName != ""
		}
	}
	return false
}

// isTOSConfigured checks whether TOS connection info is available from tenant config or env.
func (h *SystemHandler) isTOSConfigured(c *gin.Context) bool {
	if v, exists := c.Get(types.TenantInfoContextKey.String()); exists {
		if tenant, ok := v.(*types.Tenant); ok && tenant != nil && tenant.StorageEngineConfig != nil && tenant.StorageEngineConfig.TOS != nil {
			tosConf := tenant.StorageEngineConfig.TOS
			return tosConf.Endpoint != "" && tosConf.Region != "" && tosConf.AccessKey != "" && tosConf.SecretKey != "" && tosConf.BucketName != ""
		}
	}
	return h.isTOSEnvAvailable()
}

// isOSSConfigured checks whether OSS connection info is available from tenant config.
func (h *SystemHandler) isOSSConfigured(c *gin.Context) bool {
	if v, exists := c.Get(types.TenantInfoContextKey.String()); exists {
		if tenant, ok := v.(*types.Tenant); ok && tenant != nil && tenant.StorageEngineConfig != nil && tenant.StorageEngineConfig.OSS != nil {
			ossConf := tenant.StorageEngineConfig.OSS
			return ossConf.Endpoint != "" && ossConf.Region != "" && ossConf.AccessKey != "" && ossConf.SecretKey != "" && ossConf.BucketName != ""
		}
	}
	return false
}

// isKS3Configured checks whether KS3 connection info is available from tenant config.
func (h *SystemHandler) isKS3Configured(c *gin.Context) bool {
	if v, exists := c.Get(types.TenantInfoContextKey.String()); exists {
		if tenant, ok := v.(*types.Tenant); ok && tenant != nil && tenant.StorageEngineConfig != nil && tenant.StorageEngineConfig.KS3 != nil {
			ks3Conf := tenant.StorageEngineConfig.KS3
			return ks3Conf.Endpoint != "" && ks3Conf.Region != "" && ks3Conf.AccessKey != "" && ks3Conf.SecretKey != "" && ks3Conf.BucketName != ""
		}
	}
	return false
}

// isOBSConfigured checks whether OBS connection info is available from tenant config or env.
func (h *SystemHandler) isOBSConfigured(c *gin.Context) bool {
	if v, exists := c.Get(types.TenantInfoContextKey.String()); exists {
		if tenant, ok := v.(*types.Tenant); ok && tenant != nil && tenant.StorageEngineConfig != nil && tenant.StorageEngineConfig.OBS != nil {
			obsConf := tenant.StorageEngineConfig.OBS
			return obsConf.Endpoint != "" && obsConf.Region != "" && obsConf.AccessKey != "" && obsConf.SecretKey != "" && obsConf.BucketName != ""
		}
	}
	return h.isOBSEnvAvailable()
}

// isTOSEnvAvailable checks whether TOS env vars are set.
func (h *SystemHandler) isTOSEnvAvailable() bool {
	return os.Getenv("TOS_ENDPOINT") != "" &&
		os.Getenv("TOS_REGION") != "" &&
		os.Getenv("TOS_ACCESS_KEY") != "" &&
		os.Getenv("TOS_SECRET_KEY") != "" &&
		os.Getenv("TOS_BUCKET_NAME") != ""
}

// isOBSEnvAvailable checks whether OBS env vars are set.
func (h *SystemHandler) isOBSEnvAvailable() bool {
	return os.Getenv("OBS_ENDPOINT") != "" &&
		os.Getenv("OBS_REGION") != "" &&
		os.Getenv("OBS_ACCESS_KEY") != "" &&
		os.Getenv("OBS_SECRET_KEY") != "" &&
		os.Getenv("OBS_BUCKET_NAME") != ""
}

// StorageEngineStatusItem describes one storage engine's availability and description.
type StorageEngineStatusItem struct {
	Name        string `json:"name"` // "local", "minio", "cos", "tos", "s3", "oss", "ks3", "obs"
	Allowed     bool   `json:"allowed"`
	Available   bool   `json:"available"`   // whether the engine can be used
	Description string `json:"description"` // short description for UI
}

// GetStorageEngineStatusResponse is the response for GET /system/storage-engine-status.
type GetStorageEngineStatusResponse struct {
	Engines           []StorageEngineStatusItem `json:"engines"`
	AllowedProviders  []string                  `json:"allowed_providers"`
	MinioEnvAvailable bool                      `json:"minio_env_available"`
}

// GetStorageEngineStatus godoc
// @Summary      获取存储引擎状态
// @Description  返回 Local、MinIO、COS 各存储引擎的可用状态及说明,供全局设置与知识库选择使用
// @Tags         系统
// @Produce      json
// @Success      200  {object}  GetStorageEngineStatusResponse
// @Router       /system/storage-engine-status [get]
func (h *SystemHandler) GetStorageEngineStatus(c *gin.Context) {
	// Providers that already have an active multi-instance backend registered
	// (Settings → Storage). These are authoritative and independent of the
	// legacy singleton tenant.StorageEngineConfig, so a workspace that only
	// configured storage through the new UI is still reported as available.
	activeBackend := h.activeBackendProviders(c)
	minioConfigured := h.isMinioConfigured(c) || activeBackend["minio"]
	minioEnvAvailable := h.isMinioEnvAvailable()
	cosConfigured := h.isCOSConfigured(c) || activeBackend["cos"]
	tosConfigured := h.isTOSConfigured(c) || activeBackend["tos"]
	s3Configured := h.isS3Configured(c) || activeBackend["s3"]
	ossConfigured := h.isOSSConfigured(c) || activeBackend["oss"]
	ks3Configured := h.isKS3Configured(c) || activeBackend["ks3"]
	obsConfigured := h.isOBSConfigured(c) || activeBackend["obs"]
	allowed := getAllowedStorageProviders()
	allowedProviders := make([]string, 0, len(getSupportedStorageProviders()))
	for _, provider := range getSupportedStorageProviders() {
		if allowed[provider] {
			allowedProviders = append(allowedProviders, provider)
		}
	}
	engines := []StorageEngineStatusItem{
		{Name: "local", Allowed: allowed["local"], Available: true, Description: "本地文件系统存储,仅适合单机部署"},
		{Name: "minio", Allowed: allowed["minio"], Available: minioConfigured || minioEnvAvailable, Description: "S3 兼容的自托管对象存储,适合内网和私有云部署"},
		{Name: "cos", Allowed: allowed["cos"], Available: cosConfigured, Description: "腾讯云对象存储服务,适合公有云部署,支持 CDN 加速"},
		{Name: "tos", Allowed: allowed["tos"], Available: tosConfigured, Description: "火山引擎对象存储服务,适合公有云部署"},
		{Name: "s3", Allowed: allowed["s3"], Available: s3Configured, Description: "AWS S3 与兼容对象存储服务,适合公有云与混合云部署"},
		{Name: "oss", Allowed: allowed["oss"], Available: ossConfigured, Description: "阿里云对象存储服务,适合公有云部署,支持 S3 兼容协议"},
		{Name: "ks3", Allowed: allowed["ks3"], Available: ks3Configured, Description: "金山云对象存储服务,适合公有云部署"},
		{Name: "obs", Allowed: allowed["obs"], Available: obsConfigured, Description: "华为云对象存储服务,适合公有云部署"},
	}
	c.JSON(200, gin.H{
		"code": 0,
		"msg":  "success",
		"data": GetStorageEngineStatusResponse{Engines: engines, AllowedProviders: allowedProviders, MinioEnvAvailable: minioEnvAvailable},
	})
}

// --- Storage engine helpers ---
// cosFieldPattern validates COS region and bucket name format to prevent URL injection.
var cosFieldPattern = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9._-]{0,62}$`)

// ossFieldPattern validates OSS region and bucket name format to prevent URL injection.
var ossFieldPattern = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9._-]{0,62}$`)

// sanitizeStorageCheckError converts a raw storage connectivity error into a safe
// user-facing message that does not leak internal network details (hostnames, IPs, ports).
// The concrete mapping lives in internal/utils so the service layer can share it.
func sanitizeStorageCheckError(err error) string {
	return secutils.SanitizeStorageConnectivityError(err)
}

// storageEndpointHost extracts the hostname from a storage endpoint string.
// Endpoints may be bare host:port, hostnames, or full URLs with a scheme
// (e.g. "http://127.0.0.1:9000" for S3-compatible stores).
func storageEndpointHost(endpoint string) string {
	endpoint = strings.TrimSpace(endpoint)
	if endpoint == "" {
		return ""
	}
	if strings.Contains(endpoint, "://") {
		if u, err := url.Parse(endpoint); err == nil {
			if h := u.Hostname(); h != "" {
				return h
			}
		}
	}
	if host, _, err := net.SplitHostPort(endpoint); err == nil {
		return host
	}
	return endpoint
}

// isBlockedStorageEndpoint keeps the legacy handler contract while delegating
// to the same fail-closed SSRF policy used by the storage clients themselves.
// Private storage endpoints must be explicitly whitelisted by an operator.
func isBlockedStorageEndpoint(endpoint string) (bool, string) {
	endpoint = strings.TrimSpace(endpoint)
	if endpoint == "" {
		return true, "无效的地址"
	}
	if err := secutils.ValidateURLForSSRF(endpoint); err != nil {
		return true, secutils.FormatSSRFError("存储 Endpoint", endpoint, err)
	}
	return false, ""
}

// --- Storage engine connectivity check ---

// StorageCheckRequest is the body for POST /system/storage-engine-check.
type StorageCheckRequest struct {
	Provider string                   `json:"provider"` // "minio", "cos", "tos", "s3", "oss", "ks3", "obs"
	MinIO    *types.MinIOEngineConfig `json:"minio,omitempty"`
	COS      *types.COSEngineConfig   `json:"cos,omitempty"`
	TOS      *types.TOSEngineConfig   `json:"tos,omitempty"`
	S3       *types.S3EngineConfig    `json:"s3,omitempty"`
	OSS      *types.OSSEngineConfig   `json:"oss,omitempty"`
	KS3      *types.KS3EngineConfig   `json:"ks3,omitempty"`
	OBS      *types.OBSEngineConfig   `json:"obs,omitempty"`
}

// StorageCheckResponse is the response for a single-engine connectivity check.
type StorageCheckResponse struct {
	OK            bool   `json:"ok"`
	Message       string `json:"message"`
	BucketCreated bool   `json:"bucket_created,omitempty"`
}

// CheckStorageEngine tests connectivity for a single storage engine using the provided config.
// @Summary      测试存储引擎连通性
// @Description  使用当前填写的参数测试 MinIO/COS 连通性,不保存配置
// @Tags         系统
// @Accept       json
// @Produce      json
// @Param        body  body  StorageCheckRequest  true  "存储引擎配置"
// @Success      200   {object}  StorageCheckResponse
// @Router       /system/storage-engine-check [post]
func (h *SystemHandler) CheckStorageEngine(c *gin.Context) {
	ctx := logger.CloneContext(c.Request.Context())

	var req StorageCheckRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(400, gin.H{"code": 1, "msg": "请求体格式错误"})
		return
	}
	if !isStorageProviderAllowed(req.Provider) {
		c.JSON(403, gin.H{"code": 1, "msg": "该存储引擎已被禁用"})
		return
	}

	switch req.Provider {
	case "minio":
		h.checkMinio(c, ctx, req.MinIO)
	case "cos":
		h.checkCOS(c, ctx, req.COS)
	case "tos":
		h.checkTOS(c, ctx, req.TOS)
	case "s3":
		h.checkS3(c, ctx, req.S3)
	case "oss":
		h.checkOSS(c, ctx, req.OSS)
	case "ks3":
		h.checkKS3(c, ctx, req.KS3)
	case "obs":
		h.checkOBS(c, ctx, req.OBS)
	default:
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, Message: "本地存储无需检测"}})
	}
}

func (h *SystemHandler) isS3Configured(c *gin.Context) bool {
	if v, exists := c.Get(types.TenantInfoContextKey.String()); exists {
		if tenant, ok := v.(*types.Tenant); ok && tenant != nil && tenant.StorageEngineConfig != nil && tenant.StorageEngineConfig.S3 != nil {
			s3Conf := tenant.StorageEngineConfig.S3
			return s3Conf.Region != "" && s3Conf.BucketName != "" && (s3Conf.AccessKey == "") == (s3Conf.SecretKey == "")
		}
	}
	return false
}

func (h *SystemHandler) checkMinio(c *gin.Context, ctx context.Context, cfg *types.MinIOEngineConfig) {
	if cfg == nil {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "未提供 MinIO 配置"}})
		return
	}

	if cfg.BucketName != "" && !cosFieldPattern.MatchString(cfg.BucketName) {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Bucket 名称格式不正确,仅允许字母、数字、点、连字符"}})
		return
	}

	endpoint, accessKeyID, secretAccessKey := cfg.Endpoint, cfg.AccessKeyID, cfg.SecretAccessKey
	if cfg.Mode != "remote" {
		endpoint = os.Getenv("MINIO_ENDPOINT")
		accessKeyID = os.Getenv("MINIO_ACCESS_KEY_ID")
		secretAccessKey = os.Getenv("MINIO_SECRET_ACCESS_KEY")
	}
	if endpoint == "" || accessKeyID == "" || secretAccessKey == "" {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Endpoint、Access Key、Secret Key 不能为空"}})
		return
	}

	if cfg.Mode == "remote" {
		if blocked, reason := isBlockedStorageEndpoint(endpoint); blocked {
			logger.Warnf(ctx, "Storage check: MinIO endpoint blocked by SSRF protection, endpoint: %s", endpoint)
			c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: reason}})
			return
		}
	}

	err := file.CheckMinioConnectivity(ctx, endpoint, accessKeyID, secretAccessKey, cfg.BucketName, cfg.UseSSL)
	if err != nil {
		errMsg := err.Error()
		// If bucket does not exist, auto-create it
		if strings.Contains(errMsg, "does not exist") && cfg.BucketName != "" {
			logger.Info(ctx, "Storage check: bucket does not exist, attempting auto-creation", "bucket", cfg.BucketName)
			if _, mkErr := file.NewMinioFileService(endpoint, accessKeyID, secretAccessKey, cfg.BucketName, cfg.UseSSL); mkErr != nil {
				logger.Error(ctx, "Storage check: failed to create bucket", "bucket", cfg.BucketName, "error", mkErr)
				c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: fmt.Sprintf("Failed to auto-create Bucket '%s': %s", cfg.BucketName, sanitizeStorageCheckError(mkErr))}})
				return
			}
			logger.Info(ctx, "Storage check: bucket created", "bucket", cfg.BucketName)
			c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, BucketCreated: true, Message: fmt.Sprintf("Bucket '%s' does not exist, and has been automatically created", cfg.BucketName)}})
			return
		}
		logger.Error(ctx, "Storage check: MinIO connectivity failed", "error", err)
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: sanitizeStorageCheckError(err)}})
		return
	}

	msg := "连接成功"
	if cfg.BucketName != "" {
		msg = fmt.Sprintf("连接成功,Bucket「%s」已确认存在", cfg.BucketName)
	}
	c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, Message: msg}})
}

func (h *SystemHandler) checkCOS(c *gin.Context, ctx context.Context, cfg *types.COSEngineConfig) {
	if cfg == nil {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "未提供 COS 配置"}})
		return
	}
	if cfg.SecretID == "" || cfg.SecretKey == "" || cfg.Region == "" || cfg.BucketName == "" {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Secret ID、Secret Key、Region、Bucket 名称不能为空"}})
		return
	}
	if !cosFieldPattern.MatchString(cfg.Region) {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Region 格式不正确,仅允许字母、数字、点、连字符"}})
		return
	}
	if !cosFieldPattern.MatchString(cfg.BucketName) {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Bucket 名称格式不正确,仅允许字母、数字、点、连字符"}})
		return
	}

	err := file.CheckCosConnectivity(ctx, cfg.BucketName, cfg.Region, cfg.SecretID, cfg.SecretKey)
	if err != nil {
		logger.Errorf(ctx, "Storage check: COS connectivity failed, bucket: %s, error: %v", cfg.BucketName, err)
		errMsg := err.Error()
		if strings.Contains(errMsg, "403") {
			c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "认证失败,请检查 Secret ID / Secret Key 是否正确"}})
			return
		}
		if strings.Contains(errMsg, "404") || strings.Contains(errMsg, "NoSuchBucket") {
			c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: fmt.Sprintf("Bucket「%s」不存在,请检查名称和 Region", cfg.BucketName)}})
			return
		}
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: sanitizeStorageCheckError(err)}})
		return
	}
	c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, Message: fmt.Sprintf("连接成功,Bucket「%s」已确认存在", cfg.BucketName)}})
}

func (h *SystemHandler) checkTOS(c *gin.Context, ctx context.Context, cfg *types.TOSEngineConfig) {
	if cfg == nil {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "未提供 TOS 配置"}})
		return
	}
	if cfg.Endpoint == "" || cfg.Region == "" || cfg.AccessKey == "" || cfg.SecretKey == "" || cfg.BucketName == "" {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Endpoint、Region、Access Key、Secret Key、Bucket 名称不能为空"}})
		return
	}

	if blocked, reason := isBlockedStorageEndpoint(cfg.Endpoint); blocked {
		logger.Warnf(ctx, "Storage check: TOS endpoint blocked by SSRF protection, endpoint: %s", cfg.Endpoint)
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: reason}})
		return
	}

	err := file.CheckTosConnectivity(ctx, cfg.Endpoint, cfg.Region, cfg.AccessKey, cfg.SecretKey, cfg.BucketName)
	if err != nil {
		logger.Errorf(ctx, "Storage check: TOS connectivity failed, bucket: %s, error: %v", cfg.BucketName, err)
		errMsg := err.Error()
		if strings.Contains(errMsg, "403") {
			c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "认证失败,请检查 Access Key / Secret Key 是否正确"}})
			return
		}
		if strings.Contains(errMsg, "404") {
			c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: fmt.Sprintf("Bucket「%s」不存在,请检查名称和 Region", cfg.BucketName)}})
			return
		}
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: sanitizeStorageCheckError(err)}})
		return
	}
	c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, Message: fmt.Sprintf("连接成功,Bucket「%s」已确认存在", cfg.BucketName)}})
}

func (h *SystemHandler) checkS3(c *gin.Context, ctx context.Context, cfg *types.S3EngineConfig) {
	if cfg == nil {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "未提供 S3 配置"}})
		return
	}
	if cfg.Region == "" || cfg.BucketName == "" {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Region、Bucket 名称不能为空"}})
		return
	}
	if (cfg.AccessKey == "") != (cfg.SecretKey == "") {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Access Key 与 Secret Key 必须同时填写或同时留空(使用 AWS 默认凭证链)"}})
		return
	}

	if cfg.Endpoint != "" {
		if blocked, reason := isBlockedStorageEndpoint(cfg.Endpoint); blocked {
			logger.Warnf(ctx, "Storage check: S3 endpoint blocked by SSRF protection, endpoint: %s", cfg.Endpoint)
			c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: reason}})
			return
		}
	}

	err := file.CheckS3Connectivity(ctx, cfg.Endpoint, cfg.AccessKey, cfg.SecretKey, cfg.BucketName, cfg.Region)
	if err != nil {
		logger.Errorf(ctx, "Storage check: S3 connectivity failed, bucket: %s, error: %v", cfg.BucketName, err)
		errMsg := err.Error()
		if strings.Contains(errMsg, "403") {
			c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "认证失败,请检查静态密钥或 AWS IAM Role / 默认凭证链权限"}})
			return
		}
		if strings.Contains(errMsg, "404") || strings.Contains(errMsg, "NotFound") {
			c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: fmt.Sprintf("Bucket「%s」不存在,请检查名称和 Region", cfg.BucketName)}})
			return
		}
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: sanitizeStorageCheckError(err)}})
		return
	}
	c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, Message: fmt.Sprintf("连接成功,Bucket「%s」已确认存在", cfg.BucketName)}})
}

func (h *SystemHandler) checkOSS(c *gin.Context, ctx context.Context, cfg *types.OSSEngineConfig) {
	if cfg == nil {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "未提供 OSS 配置"}})
		return
	}

	endpoint, accessKey, secretKey := cfg.Endpoint, cfg.AccessKey, cfg.SecretKey
	if endpoint == "" || accessKey == "" || secretKey == "" || cfg.BucketName == "" {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Endpoint、Access Key、Secret Key、Bucket Name 不能为空"}})
		return
	}

	// Strip URL scheme before SSRF check — OSS endpoint may include http:// or https://
	ssrfEndpoint := strings.TrimPrefix(strings.TrimPrefix(endpoint, "https://"), "http://")
	if blocked, reason := isBlockedStorageEndpoint(ssrfEndpoint); blocked {
		logger.Warnf(ctx, "Storage check: OSS endpoint blocked by SSRF protection, endpoint: %s", endpoint)
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: reason}})
		return
	}
	if !ossFieldPattern.MatchString(cfg.Region) {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Region 格式不正确,仅允许字母、数字、点、连字符"}})
		return
	}
	if !ossFieldPattern.MatchString(cfg.BucketName) {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Bucket 名称格式不正确,仅允许字母、数字、点、连字符"}})
		return
	}

	err := file.CheckOssConnectivity(ctx, endpoint, cfg.Region, accessKey, secretKey, cfg.BucketName)
	if err != nil {
		errMsg := err.Error()
		if strings.Contains(errMsg, "403") || strings.Contains(errMsg, "AccessDenied") {
			logger.Errorf(ctx, "Storage check: OSS auth failed, endpoint: %s, bucket: %s", endpoint, cfg.BucketName)
			c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "认证失败,请检查 Access Key / Secret Key 是否正确"}})
			return
		}
		if strings.Contains(errMsg, "404") || strings.Contains(errMsg, "NoSuchBucket") {
			logger.Errorf(ctx, "Storage check: OSS bucket not found, bucket: %s", cfg.BucketName)
			c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: fmt.Sprintf("Bucket「%s」不存在", cfg.BucketName)}})
			return
		}
		logger.Errorf(ctx, "Storage check: OSS connectivity failed, endpoint: %s, bucket: %s, error: %v", endpoint, cfg.BucketName, err)
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: fmt.Sprintf("OSS 连通性检测失败: %s", sanitizeStorageCheckError(err))}})
		return
	}

	c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, Message: fmt.Sprintf("连接成功,Bucket「%s」已确认存在", cfg.BucketName)}})
}

func (h *SystemHandler) checkKS3(c *gin.Context, ctx context.Context, cfg *types.KS3EngineConfig) {
	if cfg == nil {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "未提供 KS3 配置"}})
		return
	}

	endpoint, region, accessKey, secretKey := cfg.Endpoint, cfg.Region, cfg.AccessKey, cfg.SecretKey
	if endpoint == "" || region == "" || accessKey == "" || secretKey == "" || cfg.BucketName == "" {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Endpoint、Region、Access Key、Secret Key、Bucket 名称不能为空"}})
		return
	}

	if blocked, reason := isBlockedStorageEndpoint(endpoint); blocked {
		logger.Warnf(ctx, "Storage check: KS3 endpoint blocked by SSRF protection, endpoint: %s", endpoint)
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: reason}})
		return
	}

	err := file.CheckKS3Connectivity(ctx, endpoint, region, accessKey, secretKey, cfg.BucketName)
	if err != nil {
		logger.Errorf(ctx, "Storage check: KS3 connectivity failed, bucket: %s, error: %v", cfg.BucketName, err)
		errMsg := err.Error()
		if strings.Contains(errMsg, "403") || strings.Contains(errMsg, "AccessDenied") {
			c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "认证失败,请检查 Access Key / Secret Key 是否正确"}})
			return
		}
		if strings.Contains(errMsg, "404") || strings.Contains(errMsg, "NoSuchBucket") {
			c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: fmt.Sprintf("Bucket「%s」不存在,请检查名称和 Region", cfg.BucketName)}})
			return
		}
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: sanitizeStorageCheckError(err)}})
		return
	}
	c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, Message: fmt.Sprintf("连接成功,Bucket「%s」已确认存在", cfg.BucketName)}})
}

func (h *SystemHandler) checkOBS(c *gin.Context, ctx context.Context, cfg *types.OBSEngineConfig) {
	if cfg == nil {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "未提供 OBS 配置"}})
		return
	}

	endpoint, region, accessKey, secretKey := cfg.Endpoint, cfg.Region, cfg.AccessKey, cfg.SecretKey
	if endpoint == "" || region == "" || accessKey == "" || secretKey == "" || cfg.BucketName == "" {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Endpoint、Region、Access Key、Secret Key、Bucket 名称不能为空"}})
		return
	}

	ssrfEndpoint := strings.TrimPrefix(strings.TrimPrefix(endpoint, "https://"), "http://")
	if blocked, reason := isBlockedStorageEndpoint(ssrfEndpoint); blocked {
		logger.Warnf(ctx, "Storage check: OBS endpoint blocked by SSRF protection, endpoint: %s", endpoint)
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: reason}})
		return
	}

	if !ossFieldPattern.MatchString(cfg.Region) {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Region 格式不正确,仅允许字母、数字、点、连字符"}})
		return
	}
	if !ossFieldPattern.MatchString(cfg.BucketName) {
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "Bucket 名称格式不正确,仅允许字母、数字、点、连字符"}})
		return
	}

	err := file.CheckObsConnectivity(ctx, endpoint, region, accessKey, secretKey, cfg.BucketName)
	if err != nil {
		logger.Errorf(ctx, "Storage check: OBS connectivity failed, bucket: %s, error: %v", cfg.BucketName, err)
		errMsg := err.Error()
		if strings.Contains(errMsg, "403") || strings.Contains(errMsg, "AccessDenied") {
			c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: "认证失败,请检查 Access Key / Secret Key 是否正确"}})
			return
		}
		if strings.Contains(errMsg, "404") || strings.Contains(errMsg, "NoSuchBucket") {
			c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: fmt.Sprintf("Bucket「%s」不存在,请检查名称和 Region", cfg.BucketName)}})
			return
		}
		c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: false, Message: sanitizeStorageCheckError(err)}})
		return
	}
	c.JSON(200, gin.H{"code": 0, "data": StorageCheckResponse{OK: true, Message: fmt.Sprintf("连接成功,Bucket「%s」已确认存在", cfg.BucketName)}})
}

func (h *SystemHandler) ResolveDocumentReader(ctx context.Context, addr string) interfaces.DocumentReader {
	if addr == "" {
		return h.documentReader
	}

	if service.IsWeKnoraCloudDocReaderAddr(addr) {
		creds := h.tenantSvc.GetWeKnoraCloudCredentials(ctx)
		if creds == nil {
			return nil
		}
		reader, err := docparser.NewWeKnoraCloudSignedDocumentReader(creds.AppID, creds.AppSecret)
		if err != nil {
			return nil
		}
		return reader
	}

	reader, err := docparser.NewHTTPDocumentReader(addr)
	if err != nil || reader == nil {
		return reader
	}
	return reader
}

// PromoteUserToSystemAdminRequest defines the request for promoting a user to system admin.
//
// Either user_id (UUID) or email must be supplied. When both are present
// user_id wins — explicit IDs are unambiguous, an email collision (extremely
// rare in practice but possible during a tenant merge) would otherwise
// silently target the wrong row.
//
// We don't expose a `binding:"required"` tag on either field because gin's
// validator can't express the OR constraint; the handler does the check
// manually and returns 400 with a specific message for each branch.
type PromoteUserToSystemAdminRequest struct {
	UserID string `json:"user_id"`
	Email  string `json:"email"`
}

// PromoteUserToSystemAdmin godoc
// @Summary      Promote a user to system administrator
// @Description  Grant system administrator privileges to a user (SystemAdmin only).
// @Description  Idempotent: re-promoting an existing system admin returns 200 with no DB write.
// @Description  Identify the user by email (preferred for human operators) or user_id (UUID, for API clients).
// @Tags         System Admin
// @Accept       json
// @Produce      json
// @Param        request body PromoteUserToSystemAdminRequest true "User promotion request"
// @Success      200  {object}  types.UserInfo  "User promoted successfully"
// @Failure      400  {object}  map[string]interface{}  "Bad request"
// @Failure      403  {object}  map[string]interface{}  "Forbidden: not a system admin"
// @Failure      404  {object}  map[string]interface{}  "User not found"
// @Router       /system/admin/promote [post]
func (h *SystemHandler) PromoteUserToSystemAdmin(c *gin.Context) {
	ctx := logger.CloneContext(c.Request.Context())

	var req PromoteUserToSystemAdminRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid request: " + err.Error()})
		return
	}

	userID := strings.TrimSpace(req.UserID)
	email := strings.TrimSpace(req.Email)
	if userID == "" && email == "" {
		c.JSON(http.StatusBadRequest, gin.H{"error": "Either user_id or email is required"})
		return
	}

	// Resolve user. user_id takes priority when both are sent (see request
	// struct doc); otherwise we look up by email. Both branches funnel
	// into the same {nil-user / error} 404 so we don't leak whether a
	// given email exists in the system to non-admins — though SystemAdmin
	// is already a high-trust role, the parity keeps the surface clean.
	var (
		user *types.User
		err  error
	)
	switch {
	case userID != "":
		user, err = h.userSvc.GetUserByID(ctx, userID)
	default:
		user, err = h.userSvc.GetUserByEmail(ctx, email)
	}
	if err != nil {
		logger.Errorf(ctx, "Error fetching user (id=%q email=%q): %v", userID, email, err)
		c.JSON(http.StatusNotFound, gin.H{"error": "User not found"})
		return
	}
	if user == nil {
		c.JSON(http.StatusNotFound, gin.H{"error": "User not found"})
		return
	}

	if user.IsSystemAdmin {
		// Idempotent: re-promoting an existing system admin is a no-op
		// success. We still emit an audit row so probing the endpoint
		// leaves a forensic trail (idempotent=true marks it as noop).
		h.emitAdminAudit(ctx, types.AuditActionSystemAdminPromoted, user, map[string]any{
			"target_email":    user.Email,
			"target_username": user.Username,
			"idempotent":      true,
		})
		c.JSON(http.StatusOK, user.ToUserInfo())
		return
	}
	user.IsSystemAdmin = true
	if err := h.userSvc.UpdateUser(ctx, user); err != nil {
		logger.Errorf(ctx, "Error promoting user %s to system admin: %v", req.UserID, err)
		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to promote user"})
		return
	}

	logger.Infof(ctx, "User %s (ID: %s) promoted to system admin", user.Username, user.ID)
	h.emitAdminAudit(ctx, types.AuditActionSystemAdminPromoted, user, map[string]any{
		"target_email":    user.Email,
		"target_username": user.Username,
		"idempotent":      false,
	})
	c.JSON(http.StatusOK, user.ToUserInfo())
}

// RevokeSystemAdminRequest defines the request for revoking system admin privileges
type RevokeSystemAdminRequest struct {
	UserID string `json:"user_id" binding:"required"`
}

// RevokeSystemAdmin godoc
// @Summary      Revoke system administrator privileges from a user
// @Description  Remove system administrator privileges from a user (SystemAdmin only).
// @Description  Two safety guards: the caller cannot revoke their own privileges,
// @Description  and revoking the last remaining system admin is rejected — both
// @Description  prevent a SystemAdmin from accidentally locking the platform out
// @Description  of system-level administration. Idempotent on already-non-admin users.
// @Tags         System Admin
// @Accept       json
// @Produce      json
// @Param        request body RevokeSystemAdminRequest true "User revocation request"
// @Success      200  {object}  types.UserInfo  "Privileges revoked successfully"
// @Failure      400  {object}  map[string]interface{}  "Bad request / would remove last admin / self-revoke"
// @Failure      403  {object}  map[string]interface{}  "Forbidden: not a system admin"
// @Failure      404  {object}  map[string]interface{}  "User not found"
// @Router       /system/admin/revoke [post]
func (h *SystemHandler) RevokeSystemAdmin(c *gin.Context) {
	ctx := logger.CloneContext(c.Request.Context())

	var req RevokeSystemAdminRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid request: " + err.Error()})
		return
	}

	callerID, _ := types.UserIDFromContext(ctx)
	user, err := h.userSvc.RevokeSystemAdmin(ctx, req.UserID, callerID)
	switch {
	case err == nil:
		// Real revoke — privileges were actually removed.
		logger.Infof(ctx, "System admin privileges revoked from user %s (ID: %s)", user.Username, user.ID)
		h.emitAdminAudit(ctx, types.AuditActionSystemAdminRevoked, user, map[string]any{
			"target_email":    user.Email,
			"target_username": user.Username,
			"changed":         true,
		})
		c.JSON(http.StatusOK, user.ToUserInfo())
		return
	case errors.Is(err, repository.ErrUserNotSystemAdmin):
		// Idempotent: target was already not an admin. Return 200 so
		// callers that re-issue the request after a partial failure
		// don't get a confusing 4xx, but mark `changed=false` in the
		// audit row so a forensic reader can tell a real revoke from a
		// noop probe.
		if user == nil {
			logger.Errorf(ctx, "RevokeSystemAdmin returned nil user with ErrUserNotSystemAdmin for %s", req.UserID)
			c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to revoke system admin privileges"})
			return
		}
		logger.Infof(ctx, "Revoke noop (user %s was not a system admin)", user.ID)
		h.emitAdminAudit(ctx, types.AuditActionSystemAdminRevoked, user, map[string]any{
			"target_email":    user.Email,
			"target_username": user.Username,
			"changed":         false,
		})
		c.JSON(http.StatusOK, user.ToUserInfo())
		return
	case errors.Is(err, repository.ErrCannotRevokeSelf):
		c.JSON(http.StatusBadRequest, gin.H{
			"error": "Cannot revoke your own system admin privileges",
		})
		return
	case errors.Is(err, repository.ErrLastSystemAdmin):
		c.JSON(http.StatusBadRequest, gin.H{
			"error": "Cannot revoke the last remaining system administrator",
		})
		return
	case errors.Is(err, repository.ErrUserNotFound):
		c.JSON(http.StatusNotFound, gin.H{"error": "User not found"})
		return
	default:
		logger.Errorf(ctx, "Error revoking system admin from user %s: %v", req.UserID, err)
		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to revoke system admin privileges"})
		return
	}
}

// ListSystemAdminsResponse defines the response structure for listing system admins.
// Total reflects the underlying COUNT(*), not just the page size, so the front
// end can render pagination metadata without a follow-up call.
type ListSystemAdminsResponse struct {
	Total  int64             `json:"total" extensions:"x-agent"`
	Admins []*types.UserInfo `json:"admins"`
}

// ListSystemAdmins godoc
// @Summary      查询系统管理员(List system administrators)
// @Description  Retrieve a paginated list of users with system administrator
// @Description  privileges (SystemAdmin only). Supports `offset` (default 0)
// @Description  and `limit` (default 50, max 200) query parameters. Walks the
// @Description  partial-friendly idx_users_is_system_admin index.
// @Tags         System Admin
// @Produce      json
// @Param        offset query int false "Page offset" default(0) minimum(0) extensions(x-agent,x-agent-maximum=1000000)
// @Param        limit  query int false "Page size (max 200)" default(50) minimum(1) maximum(200) extensions(x-agent,x-agent-maximum=50)
// @Success      200  {object}  ListSystemAdminsResponse  "System admins retrieved successfully"
// @Failure      403  {object}  map[string]interface{}  "Forbidden: not a system admin"
// @x-agent {"id":"system_admin.list_admins","risk":"read","system_admin":true,"root":"admins","max_items":50}
// @x-agent-hint "Lists platform system administrators across workspaces. Paginate with offset/limit until total is covered. These privileges differ from workspace roles."
// @Router       /system/admin/list [get]
func (h *SystemHandler) ListSystemAdmins(c *gin.Context) {
	ctx := logger.CloneContext(c.Request.Context())

	// Best-effort pagination parsing — a malformed `limit=foo` falls back
	// to defaults rather than 400-ing, since the call is still safe and a
	// failed-page is more user-hostile than a soft default.
	offset := 0
	limit := 50
	if v := c.Query("offset"); v != "" {
		if n, err := strconv.Atoi(v); err == nil && n >= 0 {
			offset = n
		}
	}
	if v := c.Query("limit"); v != "" {
		if n, err := strconv.Atoi(v); err == nil && n > 0 {
			limit = n
		}
	}
	// Cap so a client can't ask for the entire table.
	if limit > 200 {
		limit = 200
	}

	users, total, err := h.userSvc.ListSystemAdmins(ctx, offset, limit)
	if err != nil {
		logger.Errorf(ctx, "Error listing system admins: %v", err)
		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to list system admins"})
		return
	}

	// Always emit a non-nil slice so the JSON serialises to `[]` rather
	// than `null` for an empty page — front-end iteration is safer.
	infos := make([]*types.UserInfo, 0, len(users))
	for _, u := range users {
		infos = append(infos, u.ToUserInfo())
	}

	c.JSON(http.StatusOK, ListSystemAdminsResponse{
		Total:  total,
		Admins: infos,
	})
}

// ListAllUsersResponse is the paginated payload for the platform user list.
// Unlike the system-admin list there is no total COUNT; HasMore tells the UI
// whether a next page exists (derived by fetching limit+1 rows).
type ListAllUsersResponse struct {
	Users   []*types.UserInfo `json:"users"`
	Offset  int               `json:"offset" extensions:"x-agent"`
	Limit   int               `json:"limit" extensions:"x-agent"`
	HasMore bool              `json:"has_more" extensions:"x-agent"`
}

// ListUsers godoc
// @Summary      查询平台用户(List platform users)
// @Description  Retrieve a paginated list of every user across tenants (SystemAdmin only).
// @Description  Supports `offset` (default 0) and `limit` (default 50, max 200).
// @Description  Password/hashes are never serialised — only the redacted UserInfo shape.
// @Tags         System Admin
// @Produce      json
// @Param        offset query int false "Page offset" default(0) minimum(0) extensions(x-agent,x-agent-maximum=1000000)
// @Param        limit  query int false "Page size (max 200)" default(50) minimum(1) maximum(200) extensions(x-agent,x-agent-maximum=50)
// @Success      200  {object}  ListAllUsersResponse  "Users retrieved successfully"
// @Failure      403  {object}  map[string]interface{}  "Forbidden: not a system admin"
// @x-agent {"id":"system_admin.list_users","risk":"read","system_admin":true,"root":"users","max_items":50}
// @x-agent-hint "Lists platform users across workspaces, including account enabled state and system administrator flag. Follow has_more using offset + limit. tenant_id is the home workspace, not a list of memberships. No search or role filter is supported: paginate before drawing conclusions."
// @Router       /system/admin/users [get]
func (h *SystemHandler) ListUsers(c *gin.Context) {
	ctx := logger.CloneContext(c.Request.Context())

	offset := 0
	limit := 50
	if v := c.Query("offset"); v != "" {
		if n, err := strconv.Atoi(v); err == nil && n >= 0 {
			offset = n
		}
	}
	if v := c.Query("limit"); v != "" {
		if n, err := strconv.Atoi(v); err == nil && n > 0 {
			limit = n
		}
	}
	if limit > 200 {
		limit = 200
	}

	users, hasMore, err := h.userSvc.ListAllUsers(ctx, offset, limit)
	if err != nil {
		logger.Errorf(ctx, "Error listing users: %v", err)
		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to list users"})
		return
	}

	infos := make([]*types.UserInfo, 0, len(users))
	for _, u := range users {
		infos = append(infos, u.ToUserInfo())
	}

	c.JSON(http.StatusOK, ListAllUsersResponse{
		Users:   infos,
		Offset:  offset,
		Limit:   limit,
		HasMore: hasMore,
	})
}

// SetUserStatusRequest toggles a user account enabled/disabled (SystemAdmin only).
type SetUserStatusRequest struct {
	UserID   string `json:"user_id" binding:"required"`
	IsActive *bool  `json:"is_active" binding:"required"`
}

// SetUserStatus godoc
// @Summary      Enable or disable a user account
// @Description  Disable revokes the target's active sessions immediately.
// @Description  Self-disable and disabling the last active system administrator are rejected.
// @Tags         System Admin
// @Accept       json
// @Produce      json
// @Param        request body SetUserStatusRequest true "Account status request"
// @Success      200  {object}  handler.SetUserStatusResponse  "Status updated"
// @Failure      400  {object}  map[string]interface{}  "Self-disable / last-admin guard"
// @Failure      404  {object}  map[string]interface{}  "User not found"
// @Router       /system/admin/users/status [post]
func (h *SystemHandler) SetUserStatus(c *gin.Context) {
	ctx := logger.CloneContext(c.Request.Context())

	var req SetUserStatusRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid request"})
		return
	}

	callerID, _ := types.UserIDFromContext(ctx)
	user, err := h.userSvc.SetUserActive(ctx, strings.TrimSpace(req.UserID), callerID, *req.IsActive)
	if err != nil {
		switch {
		case errors.Is(err, service.ErrUserNotFound):
			c.JSON(http.StatusNotFound, gin.H{"error": "User not found"})
		case errors.Is(err, service.ErrCannotDisableSelf),
			errors.Is(err, service.ErrCannotDisableLastAdmin):
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		default:
			logger.Errorf(ctx, "Error setting user status: %v", err)
			c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to update user status"})
		}
		return
	}

	c.JSON(http.StatusOK, gin.H{
		"message":   "User status updated",
		"user":      user.ToUserInfo(),
		"is_active": user.IsActive,
	})
}

// ResetUserPasswordRequest defines the system-administrator password-reset
// payload. Email is intentionally the only user-facing identifier: the UI is
// an operator tool and emails are easier to verify than UUIDs. The password is
// never written to logs or audit details.
type ResetUserPasswordRequest struct {
	Email       string `json:"email" binding:"required,email"`
	NewPassword string `json:"new_password" binding:"required"`
}

// ResetUserPassword godoc
// @Summary      Reset another user's password
// @Description  Replace another user's local password and revoke all of their existing sessions (SystemAdmin only).
// @Description  A system administrator cannot reset their own password through this endpoint; self-service password change still requires the old password.
// @Tags         System Admin
// @Accept       json
// @Produce      json
// @Param        request body ResetUserPasswordRequest true "Password reset request"
// @Success      200  {object}  handler.ResetUserPasswordResponse  "Password reset successfully"
// @Failure      400  {object}  map[string]interface{}  "Invalid request, weak password, or self reset"
// @Failure      403  {object}  map[string]interface{}  "Forbidden: not a system admin"
// @Failure      404  {object}  map[string]interface{}  "User not found"
// @Router       /system/admin/users/reset-password [post]
func (h *SystemHandler) ResetUserPassword(c *gin.Context) {
	ctx := logger.CloneContext(c.Request.Context())

	var req ResetUserPasswordRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid password reset request"})
		return
	}
	req.Email = strings.TrimSpace(req.Email)

	if err := service.ValidatePasswordPolicy(req.NewPassword, h.complexPasswordEnabled(ctx)); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}

	user, err := h.userSvc.GetUserByEmail(ctx, req.Email)
	if err != nil || user == nil {
		c.JSON(http.StatusNotFound, gin.H{"error": "User not found"})
		return
	}
	callerID, _ := types.UserIDFromContext(ctx)
	if callerID == user.ID {
		c.JSON(http.StatusBadRequest, gin.H{"error": "Cannot reset your own password here"})
		return
	}

	if err := h.userSvc.AdminResetPassword(ctx, user.ID, req.NewPassword); err != nil {
		if service.IsPasswordPolicyError(err) {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}
		logger.Errorf(ctx, "Failed to reset password for user %s: %v", user.ID, err)
		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to reset user password"})
		return
	}

	logger.Infof(ctx, "Password reset by system administrator for user ID: %s", user.ID)
	h.emitAdminAudit(ctx, types.AuditActionSystemUserPasswordReset, user, map[string]any{
		"target_email":     user.Email,
		"target_username":  user.Username,
		"sessions_revoked": true,
	})
	c.JSON(http.StatusOK, gin.H{"message": "Password reset successfully"})
}

// CreateSystemUserResponse is the payload returned by
// POST /api/v1/system/admin/users/create. GeneratedPassword is populated
// exactly once, only when the server minted a random password (`password`
// omitted or null), and is never logged, audited, or retrievable again.
type CreateSystemUserResponse struct {
	User *types.UserInfo `json:"user"`
	// GeneratedPassword is the plaintext password when the server
	// auto-generated one. Absent when the caller supplied the password.
	GeneratedPassword string `json:"generated_password,omitempty"`
}

// CreateSystemUser godoc
// @Summary      Create a new user (SystemAdmin)
// @Description  Provision a new local user account (SystemAdmin only).
// @Description  When `password` is omitted or null, a cryptographically random
// @Description  password is generated (OIDC-style crypto/rand + base64url)
// @Description  and returned once in the response body. Any provided value,
// @Description  including empty string, is policy-checked. Tenant provisioning
// @Description  follows the shared auth.default_tenant_mode policy.
// @Tags         System Admin
// @Accept       json
// @Produce      json
// @Param        request body types.AdminCreateUserRequest true "User creation request"
// @Success      201  {object}  CreateSystemUserResponse  "User created successfully"
// @Success      200  {object}  CreateSystemUserResponse  "Identity already exists, returns the existing user"
// @Failure      400  {object}  map[string]interface{}  "Invalid request or weak password"
// @Failure      403  {object}  map[string]interface{}  "Forbidden: not a system admin"
// @Failure      409  {object}  map[string]interface{}  "Email and username refer to conflicting identities"
// @Failure      500  {object}  map[string]interface{}  "Internal error"
// @Router       /system/admin/users/create [post]
func (h *SystemHandler) CreateSystemUser(c *gin.Context) {
	ctx := logger.CloneContext(c.Request.Context())

	var req types.AdminCreateUserRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid user creation request"})
		return
	}
	req.Username = secutils.SanitizeForLog(strings.TrimSpace(req.Username))
	req.Email = secutils.SanitizeForLog(strings.TrimSpace(req.Email))
	// Password is intentionally NOT trimmed or sanitized.
	if req.Username == "" || req.Email == "" {
		c.JSON(http.StatusBadRequest, gin.H{"error": "Username and email are required"})
		return
	}
	// Binding's min=2/max=50 ran on the raw JSON, re-check the trimmed value.
	if n := utf8.RuneCountInString(req.Username); n < 2 || n > 50 {
		c.JSON(http.StatusBadRequest, gin.H{"error": "Username must be 2-50 characters"})
		return
	}

	user, generatedPassword, err := h.userSvc.AdminCreateUser(ctx, &req, h.resolveDefaultTenantMode(ctx))
	if err != nil {
		switch {
		case errors.Is(err, service.ErrUserEmailExists) || errors.Is(err, service.ErrUserUsernameExists):
			if user == nil {
				logger.Errorf(ctx, "Duplicate identity error without a resolved user: %v", err)
				c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to create user"})
				return
			}
			logger.Infof(ctx, "Create user noop (identity already exists, ID: %s)", user.ID)
			h.emitAdminAudit(ctx, types.AuditActionSystemUserCreated, user, map[string]any{
				"target_email":       user.Email,
				"target_username":    user.Username,
				"password_generated": false,
				"idempotent":         true,
			})
			c.JSON(http.StatusOK, CreateSystemUserResponse{User: user.ToUserInfo()})
		case errors.Is(err, service.ErrPasswordPolicy):
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		case errors.Is(err, service.ErrUserIdentityConflict):
			c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
		default:
			logger.Errorf(ctx, "Failed to create user: %v", err)
			c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to create user"})
		}
		return
	}

	logger.Infof(ctx, "System admin created user %s (ID: %s)", user.Username, user.ID)
	h.emitAdminAudit(ctx, types.AuditActionSystemUserCreated, user, map[string]any{
		"target_email":       user.Email,
		"target_username":    user.Username,
		"password_generated": generatedPassword != "",
		"idempotent":         false,
	})
	c.JSON(http.StatusCreated, CreateSystemUserResponse{
		User:              user.ToUserInfo(),
		GeneratedPassword: generatedPassword,
	})
}

// ============================================================================
// System Settings (P1)
// ----------------------------------------------------------------------------
// Endpoints below are mounted under /api/v1/system/admin/settings*, all
// gated to SystemAdmin via the route group's middleware. Every response
// is the raw model — no `gin.H{"data": ...}` wrapping — to match the
// project's axios interceptor contract (response.data is unwrapped at the
// HTTP layer; see frontend/src/utils/request.ts:97). The P0 ListSystemAdmins
// already follows this; do not break the convention.
// ============================================================================

// ListSystemSettings godoc
// @Summary      List all system settings
// @Description  Return every row in the system_settings table (system-scope,
// @Description  not workspace-scoped). SystemAdmin only.
// @Tags         System Admin
// @Produce      json
// @Success      200 {array} types.SystemSetting "list of settings"
// @Failure      403 {object} map[string]interface{} "Forbidden: not a system admin"
// @Router       /system/admin/settings [get]
// RuntimeQueuesResponse is the payload for the SystemAdmin runtime queue
// dashboard. `available` is false in Lite mode (no Redis/asynq) so the
// UI can render an "unavailable in this deployment" state instead of an
// empty table. Each pool reports configured per-process concurrency plus live
// cluster capacity/active workers aggregated from asynq server heartbeats.
type RuntimeWorkerPool struct {
	Name            string  `json:"name" extensions:"x-agent"`
	Concurrency     int     `json:"concurrency" extensions:"x-agent"` // configured per instance
	QueueCount      int     `json:"queue_count" extensions:"x-agent"`
	Instances       int     `json:"instances" extensions:"x-agent"`        // live asynq server heartbeats
	ClusterCapacity int     `json:"cluster_capacity" extensions:"x-agent"` // sum of live server concurrency
	Active          int     `json:"active" extensions:"x-agent"`           // live workers assigned to this pool
	Utilization     float64 `json:"utilization" extensions:"x-agent"`      // Active / ClusterCapacity
}

type RuntimeQueuesResponse struct {
	QueuesError           bool                       `json:"queues_error" extensions:"x-agent"`
	WorkersError          bool                       `json:"workers_error" extensions:"x-agent"`
	ModelsError           bool                       `json:"models_error" extensions:"x-agent"`
	Available             bool                       `json:"available" extensions:"x-agent"`
	UpstreamConcurrency   int                        `json:"upstream_concurrency" extensions:"x-agent"`
	ParseConcurrency      int                        `json:"parse_concurrency"` // compatibility alias for upstream_concurrency
	WikiConcurrency       int                        `json:"wiki_concurrency"`  // compatibility field
	Pools                 []RuntimeWorkerPool        `json:"pools" extensions:"x-agent"`
	Queues                []types.QueueStat          `json:"queues" extensions:"x-agent"`
	ModelLimiterAvailable bool                       `json:"model_limiter_available" extensions:"x-agent"`
	Models                []modellimiter.RuntimeStat `json:"models" extensions:"x-agent"`
	Timestamp             int64                      `json:"timestamp" extensions:"x-agent"`
}

func aggregateRuntimeWorkerPools(pools []RuntimeWorkerPool, servers []types.WorkerServerStat) {
	queueConfigs := map[string]map[string]int{
		types.WorkerPoolCore:        types.QueueWeightsForPool(types.WorkerPoolCore),
		types.WorkerPoolPostProcess: types.QueueWeightsForPool(types.WorkerPoolPostProcess),
		types.WorkerPoolEnrichment:  types.QueueWeightsForPool(types.WorkerPoolEnrichment),
		types.WorkerPoolMaintenance: types.QueueWeightsForPool(types.WorkerPoolMaintenance),
		types.WorkerPoolShared:      types.QueueWeightsForSharedPool(),
		types.WorkerPoolWiki:        types.QueueWeightsForPool(types.WorkerPoolWiki),
	}
	indexes := make(map[string]int, len(pools))
	for i := range pools {
		indexes[pools[i].Name] = i
	}
	for _, server := range servers {
		if server.Status != "active" {
			continue
		}
		for poolName, expectedQueues := range queueConfigs {
			if !sameQueueWeights(server.Queues, expectedQueues) {
				continue
			}
			idx, ok := indexes[poolName]
			if !ok {
				break
			}
			pools[idx].Instances++
			pools[idx].ClusterCapacity += server.Concurrency
			pools[idx].Active += server.Active
			break
		}
	}
	for i := range pools {
		if pools[i].ClusterCapacity > 0 {
			pools[i].Utilization = float64(pools[i].Active) / float64(pools[i].ClusterCapacity)
		}
	}
}

func sameQueueWeights(left, right map[string]int) bool {
	if len(left) != len(right) {
		return false
	}
	for name, weight := range left {
		if right[name] != weight {
			return false
		}
	}
	return true
}

// GetRuntimeQueues godoc
// @Summary      获取解析任务队列运行时状态
// @Description  返回各 asynq 队列的实时深度(pending/active/scheduled/retry 等)与 worker 并发配置,仅系统管理员可见
// @Tags         系统管理
// @Produce      json
// @Success      200  {object}  RuntimeQueuesResponse
// @x-agent {"id":"system_admin.get_queues","risk":"read","system_admin":true}
// @x-agent-hint "Reads platform-wide queue depth, worker pools and model concurrency. available false means unsupported, not healthy or empty. Check queues_error, workers_error and models_error before interpreting counts. failed is today's counter; retry/archived are current depths. Pool concurrency is per instance; cluster_capacity and active reflect live worker heartbeats. Does not control workers or retry tasks."
// @Router       /system/admin/runtime/queues [get]
func (h *SystemHandler) GetRuntimeQueues(c *gin.Context) {
	ctx := logger.CloneContext(c.Request.Context())
	var allocation types.WorkerPoolConcurrency
	if h.systemSettingSvc != nil {
		allocation = types.ResolveWorkerPoolConcurrency(func(key, env string, fallback int) int {
			configured := h.systemSettingSvc.GetInt(ctx, key, env, int64(fallback))
			return int(configured)
		})
	} else {
		allocation = types.DefaultWorkerPoolConcurrency()
	}
	queueCounts := make(map[string]int)
	for _, definition := range types.QueueDefinitions() {
		queueCounts[definition.Pool]++
	}
	resp := RuntimeQueuesResponse{
		UpstreamConcurrency: allocation.UpstreamTotal(),
		ParseConcurrency:    allocation.UpstreamTotal(),
		WikiConcurrency:     allocation.Wiki,
		Pools: []RuntimeWorkerPool{
			{Name: types.WorkerPoolCore, Concurrency: allocation.Core, QueueCount: queueCounts[types.WorkerPoolCore]},
			{Name: types.WorkerPoolPostProcess, Concurrency: allocation.PostProcess, QueueCount: queueCounts[types.WorkerPoolPostProcess]},
			{Name: types.WorkerPoolEnrichment, Concurrency: allocation.Enrichment, QueueCount: queueCounts[types.WorkerPoolEnrichment]},
			{Name: types.WorkerPoolMaintenance, Concurrency: allocation.Maintenance, QueueCount: queueCounts[types.WorkerPoolMaintenance]},
			{Name: types.WorkerPoolShared, Concurrency: allocation.Shared, QueueCount: len(types.QueueWeightsForSharedPool())},
			{Name: types.WorkerPoolWiki, Concurrency: allocation.Wiki, QueueCount: queueCounts[types.WorkerPoolWiki]},
		},
		Timestamp: time.Now().Unix(),
	}

	if h.taskInspector != nil {
		stats, supported, err := h.taskInspector.QueueStats(ctx)
		if err != nil {
			logger.Errorf(ctx, "get queue stats failed: %v", err)
		}
		resp.QueuesError = err != nil
		resp.Available = supported
		if stats != nil {
			resp.Queues = stats
		}
		serverStats, _, serverErr := h.taskInspector.WorkerServerStats(ctx)
		resp.WorkersError = serverErr != nil
		if serverErr != nil {
			logger.Errorf(ctx, "get worker server stats failed: %v", serverErr)
		} else {
			aggregateRuntimeWorkerPools(resp.Pools, serverStats)
		}
	}
	// Always emit a non-nil array so the JSON serialises to `[]` rather
	// than `null`, keeping the frontend iteration simple.
	if resp.Queues == nil {
		resp.Queues = []types.QueueStat{}
	}
	modelStats, modelSupported, modelErr := modellimiter.RuntimeStats(ctx)
	if modelErr != nil {
		logger.Errorf(ctx, "get model concurrency stats failed: %v", modelErr)
	}
	resp.ModelsError = modelErr != nil
	resp.ModelLimiterAvailable = modelSupported
	resp.Models = modelStats

	c.JSON(http.StatusOK, resp)
}

type RuntimeTasksResponse struct {
	Available  bool                    `json:"available" extensions:"x-agent"`
	Tasks      []types.RuntimeTaskInfo `json:"tasks"`
	PageSize   int                     `json:"page_size" extensions:"x-agent"`
	HasMore    bool                    `json:"has_more" extensions:"x-agent"`
	NextCursor string                  `json:"next_cursor,omitempty" extensions:"x-agent"`
}

func isKnownRuntimeQueue(name string) bool {
	for _, definition := range types.QueueDefinitions() {
		if definition.Name == name {
			return true
		}
	}
	return false
}

func runtimeTaskPageSize(c *gin.Context) int {
	pageSize, _ := strconv.Atoi(c.DefaultQuery("page_size", "20"))
	if pageSize < 1 {
		pageSize = 20
	}
	if pageSize > 100 {
		pageSize = 100
	}
	return pageSize
}

func (h *SystemHandler) listRuntimeTasks(c *gin.Context, state types.RuntimeTaskState) {
	queue := c.Param("queue")
	if !isKnownRuntimeQueue(queue) {
		c.JSON(http.StatusBadRequest, gin.H{"error": "Unknown task queue"})
		return
	}
	if !state.Valid() {
		c.JSON(http.StatusBadRequest, gin.H{"error": "Unknown task state"})
		return
	}
	pageSize := runtimeTaskPageSize(c)
	cursor := c.Query("cursor")
	inspector, ok := h.taskInspector.(interfaces.RuntimeTaskInspector)
	if !ok {
		c.JSON(http.StatusOK, RuntimeTasksResponse{
			Available: false,
			Tasks:     []types.RuntimeTaskInfo{},
			PageSize:  pageSize,
		})
		return
	}
	page, supported, err := inspector.ListRuntimeTasks(c.Request.Context(), queue, state, cursor, pageSize)
	if err != nil {
		if errors.Is(err, types.ErrInvalidRuntimeTaskCursor) {
			c.JSON(http.StatusBadRequest, gin.H{
				"error": "Invalid task list cursor",
				"code":  "runtime_task_cursor_invalid",
			})
			return
		}
		if errors.Is(err, types.ErrExpiredRuntimeTaskCursor) {
			c.JSON(http.StatusConflict, gin.H{
				"error": "Task list changed; refresh from the beginning",
				"code":  "runtime_task_cursor_expired",
			})
			return
		}
		logger.Errorf(c.Request.Context(), "list runtime queue tasks queue=%s state=%s: %v", queue, state, err)
		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to list queue tasks"})
		return
	}
	if page.Tasks == nil {
		page.Tasks = []types.RuntimeTaskInfo{}
	}
	for i := range page.Tasks {
		page.Tasks[i].ErrorCategory = runtimeErrorCategory(page.Tasks[i].LastError)
	}
	c.JSON(http.StatusOK, RuntimeTasksResponse{
		Available:  supported,
		Tasks:      page.Tasks,
		PageSize:   pageSize,
		HasMore:    page.HasMore,
		NextCursor: page.NextCursor,
	})
}

// ListRuntimeTasks returns one live task-state page for the unified operator
// drawer. Raw task payloads are never included.
// @Summary      查询队列任务与失败记录(List runtime queue tasks)
// @Tags         System Admin
// @Produce      json
// @Param        queue path string true "Queue name" extensions(x-agent)
// @Param        state query string true "Task state" Enums(pending,active,scheduled,retry,archived,completed) extensions(x-agent)
// @Param        cursor query string false "Opaque continuation cursor" extensions(x-agent)
// @Param        page_size query int false "Page size" default(20) minimum(1) maximum(100) extensions(x-agent,x-agent-maximum=50)
// @Success      200 {object} RuntimeTasksResponse
// @x-agent {"id":"system_admin.list_tasks","risk":"read","system_admin":true,"root":"tasks","max_items":50}
// @x-agent-hint "Lists platform-wide tasks in one queue and state. Choose queue from system_admin.get_queues, never guess. For failures inspect retry and archived; active/pending help diagnose backlog. available false means unsupported. Continue with next_cursor while has_more; on expired cursor restart from the first page. error_category is a heuristic, not the full cause; unknown needs the operator task page/logs. Raw errors, payloads, results and worker addresses are omitted. This operation cannot retry, cancel or delete tasks."
// @Router       /system/admin/runtime/queues/{queue}/tasks [get]
func (h *SystemHandler) ListRuntimeTasks(c *gin.Context) {
	h.listRuntimeTasks(c, types.RuntimeTaskState(c.Query("state")))
}

func (h *SystemHandler) emitQueueTaskAudit(
	ctx context.Context,
	action types.AuditAction,
	queue, taskID string,
	extra map[string]string,
) {
	if h.auditSvc == nil {
		return
	}
	actorID, _ := types.UserIDFromContext(ctx)
	detailMap := map[string]string{"queue": queue, "task_id": taskID}
	for key, value := range extra {
		detailMap[key] = value
	}
	details, _ := json.Marshal(detailMap)
	targetType := "queue_task"
	targetID := taskID
	if targetID == "" {
		targetType = "task_queue"
		targetID = queue
	}
	_ = h.auditSvc.Log(ctx, &types.AuditLog{
		TenantID:    0,
		ActorUserID: actorID,
		ActorRole:   systemAuditActorRole(ctx),
		Action:      action,
		TargetType:  targetType,
		TargetID:    targetID,
		Outcome:     types.AuditOutcomeSuccess,
		Details:     types.JSON(details),
	})
}

func runtimeTaskParams(c *gin.Context) (string, string, bool) {
	queue := c.Param("queue")
	taskID := c.Param("task_id")
	if !isKnownRuntimeQueue(queue) || taskID == "" {
		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid queue or task ID"})
		return "", "", false
	}
	return queue, taskID, true
}

func (h *SystemHandler) mutateRuntimeTask(c *gin.Context, action types.RuntimeTaskAction) {
	queue, taskID, ok := runtimeTaskParams(c)
	if !ok {
		return
	}
	inspector, supported := h.taskInspector.(interfaces.RuntimeTaskInspector)
	if !supported {
		c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Task queue is unavailable"})
		return
	}
	task, available, err := inspector.GetRuntimeTask(c.Request.Context(), queue, taskID)
	if !available {
		c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Task queue is unavailable"})
		return
	}
	if err != nil || task == nil {
		c.JSON(http.StatusConflict, gin.H{"error": "Task is no longer available"})
		return
	}
	if !task.Allows(action) {
		c.JSON(http.StatusConflict, gin.H{"error": "Action is not allowed for the current task state"})
		return
	}

	var auditAction types.AuditAction
	auditDetails := map[string]string{
		"task_type":  task.Type,
		"from_state": string(task.State),
		"action":     string(action),
	}
	switch action {
	case types.RuntimeTaskActionCancel:
		if h.knowledgeSvc == nil || task.TenantID == 0 || task.KnowledgeID == "" {
			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Business cancellation is unavailable"})
			return
		}
		cancelCtx := context.WithValue(c.Request.Context(), types.TenantIDContextKey, task.TenantID)
		if _, err = h.knowledgeSvc.CancelKnowledgeParse(cancelCtx, task.KnowledgeID); err != nil {
			if isKnowledgeGone(err) {
				if h.purgeOrphanRuntimeTask(c.Request.Context(), inspector, queue, taskID, task.KnowledgeID) {
					logger.Warnf(c.Request.Context(),
						"cancel runtime queue task queue=%s task=%s: knowledge gone, purged queue record",
						queue, taskID)
					auditDetails["orphan_purge"] = "true"
					auditAction = types.AuditActionSystemQueueTaskCancelled
					break
				}
			}
			logger.Errorf(c.Request.Context(), "cancel runtime queue task queue=%s task=%s: %v", queue, taskID, err)
			c.JSON(http.StatusConflict, gin.H{"error": "Task can no longer be cancelled"})
			return
		}
		auditAction = types.AuditActionSystemQueueTaskCancelled
	case types.RuntimeTaskActionRunNow:
		available, err = inspector.RunRuntimeTask(c.Request.Context(), queue, taskID)
		if !available {
			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Task queue is unavailable"})
			return
		}
		if err != nil {
			logger.Errorf(c.Request.Context(), "run queue task now queue=%s task=%s: %v", queue, taskID, err)
			c.JSON(http.StatusConflict, gin.H{"error": "Task is no longer available to run"})
			return
		}
		auditAction = types.AuditActionSystemQueueTaskRunNow
	case types.RuntimeTaskActionDelete:
		available, err = inspector.DeleteRuntimeTask(c.Request.Context(), queue, taskID)
		if !available {
			c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Task queue is unavailable"})
			return
		}
		if err != nil {
			logger.Errorf(c.Request.Context(), "delete queue task queue=%s task=%s: %v", queue, taskID, err)
			c.JSON(http.StatusConflict, gin.H{"error": "Task is no longer available for deletion"})
			return
		}
		auditAction = types.AuditActionSystemQueueTaskDeleted
	default:
		c.JSON(http.StatusBadRequest, gin.H{"error": "Unknown task action"})
		return
	}
	h.emitQueueTaskAudit(c.Request.Context(), auditAction, queue, taskID, auditDetails)
	c.JSON(http.StatusOK, gin.H{"success": true})
}

func isKnowledgeGone(err error) bool {
	if errors.Is(err, repository.ErrKnowledgeNotFound) {
		return true
	}
	var appErr *apperrors.AppError
	return errors.As(err, &appErr) && appErr.Code == apperrors.ErrNotFound
}

// purgeOrphanRuntimeTask removes queue records for a task whose knowledge row
// is already gone. CancelTasksForKnowledge sweeps sibling tasks best-effort;
// success is reported only once the requested task ID is gone.
func (h *SystemHandler) purgeOrphanRuntimeTask(
	ctx context.Context,
	inspector interfaces.RuntimeTaskInspector,
	queue, taskID, knowledgeID string,
) bool {
	if h.taskInspector != nil && knowledgeID != "" {
		if _, _, err := h.taskInspector.CancelTasksForKnowledge(ctx, knowledgeID); err != nil {
			logger.Warnf(ctx, "purge orphan tasks for knowledge %s: %v", knowledgeID, err)
		}
	}
	supported, err := inspector.ForceDeleteRuntimeTask(ctx, queue, taskID)
	if !supported {
		return false
	}
	if err == nil {
		return true
	}
	// The knowledge-wide sweep may have already removed this task ID.
	if _, available, getErr := inspector.GetRuntimeTask(ctx, queue, taskID); available && getErr != nil {
		return true
	}
	logger.Warnf(ctx, "force delete orphan task queue=%s task=%s: %v", queue, taskID, err)
	return false
}

// MutateRuntimeTask executes a backend-advertised action after re-reading the
// current task state to close click/race windows.
// @Summary      Run a safe runtime task action
// @Tags         System Admin
// @Produce      json
// @Param        queue path string true "Queue name"
// @Param        task_id path string true "Task ID"
// @Param        action path string true "Action" Enums(cancel,run_now,delete)
// @Success      200 {object} map[string]bool
// @Router       /system/admin/runtime/queues/{queue}/tasks/{task_id}/actions/{action} [post]
func (h *SystemHandler) MutateRuntimeTask(c *gin.Context) {
	h.mutateRuntimeTask(c, types.RuntimeTaskAction(c.Param("action")))
}

// PurgeArchivedRuntimeTasks clears every archived (finally-failed) task in one
// queue. It only touches the archived dead-letter set — live pending/active/
// scheduled/retry tasks are untouched — and mirrors single-record delete
// semantics by leaving business state as-is (archived tasks already had their
// document status flipped to "failed" on their last retry).
// @Summary      Purge all archived tasks in a queue
// @Tags         System Admin
// @Produce      json
// @Param        queue path string true "Queue name"
// @Success      200 {object} handler.PurgeArchivedRuntimeTasksResponse
// @Router       /system/admin/runtime/queues/{queue}/archived [delete]
func (h *SystemHandler) PurgeArchivedRuntimeTasks(c *gin.Context) {
	queue := c.Param("queue")
	if !isKnownRuntimeQueue(queue) {
		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid queue"})
		return
	}
	inspector, supported := h.taskInspector.(interfaces.RuntimeTaskInspector)
	if !supported {
		c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Task queue is unavailable"})
		return
	}
	deleted, available, err := inspector.PurgeArchivedRuntimeTasks(c.Request.Context(), queue)
	if !available {
		c.JSON(http.StatusServiceUnavailable, gin.H{"error": "Task queue is unavailable"})
		return
	}
	if err != nil {
		logger.Errorf(c.Request.Context(), "purge archived queue tasks queue=%s: %v", queue, err)
		c.JSON(http.StatusConflict, gin.H{"error": "Archived tasks could not be purged"})
		return
	}
	h.emitQueueTaskAudit(c.Request.Context(), types.AuditActionSystemQueueArchivedPurged, queue, "",
		map[string]string{"deleted": strconv.Itoa(deleted)})
	c.JSON(http.StatusOK, gin.H{"success": true, "deleted": deleted})
}

func (h *SystemHandler) ListSystemSettings(c *gin.Context) {
	ctx := logger.CloneContext(c.Request.Context())
	rows, err := h.systemSettingSvc.List(ctx)
	if err != nil {
		logger.Errorf(ctx, "list system settings failed: %v", err)
		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to list system settings"})
		return
	}
	if rows == nil {
		// Always emit a non-nil array so the JSON serialises to `[]`
		// rather than `null` on an empty table — front-end iteration
		// is safer.
		rows = []*types.SystemSetting{}
	}
	h.enrichSettingsModifiedBy(ctx, rows)
	c.JSON(http.StatusOK, rows)
}

// enrichSettingsModifiedBy resolves LastModifiedBy (UUID) → display name
// in a single batch lookup. Failures degrade silently: the UI already
// falls back to the UUID prefix when the name is empty, so a transient
// userSvc error must not break the settings page entirely.
func (h *SystemHandler) enrichSettingsModifiedBy(ctx context.Context, rows []*types.SystemSetting) {
	if len(rows) == 0 || h.userSvc == nil {
		return
	}
	idSet := make(map[string]struct{}, len(rows))
	for _, r := range rows {
		if r != nil && strings.TrimSpace(r.LastModifiedBy) != "" {
			idSet[r.LastModifiedBy] = struct{}{}
		}
	}
	if len(idSet) == 0 {
		return
	}
	ids := make([]string, 0, len(idSet))
	for id := range idSet {
		ids = append(ids, id)
	}
	users, err := h.userSvc.GetUsersByIDs(ctx, ids)
	if err != nil {
		logger.Warnf(ctx, "enrichSettingsModifiedBy: GetUsersByIDs failed: %v", err)
		return
	}
	for _, r := range rows {
		if r == nil {
			continue
		}
		u, ok := users[r.LastModifiedBy]
		if !ok || u == nil {
			continue
		}
		// Username is the canonical display label; fall back to email
		// for older rows where username may be empty (legacy seeded
		// admins). Both empty → leave LastModifiedByName empty so the
		// UI's UUID-prefix fallback kicks in.
		switch {
		case strings.TrimSpace(u.Username) != "":
			r.LastModifiedByName = u.Username
		case strings.TrimSpace(u.Email) != "":
			r.LastModifiedByName = u.Email
		}
	}
}

// GetSystemSetting godoc
// @Summary      Get a single system setting by key
// @Description  Returns the row matching :key. 404 when the key is unknown
// @Description  to the registry; 200 with the row when known.
// @Tags         System Admin
// @Produce      json
// @Param        key path string true "Setting key (e.g. file.max_size_mb)"
// @Success      200 {object} types.SystemSetting "the setting row"
// @Failure      400 {object} map[string]interface{} "Unknown key"
// @Failure      404 {object} map[string]interface{} "Key registered but DB row absent"
// @Router       /system/admin/settings/{key} [get]
func (h *SystemHandler) GetSystemSetting(c *gin.Context) {
	ctx := logger.CloneContext(c.Request.Context())
	key := c.Param("key")
	row, err := h.systemSettingSvc.Get(ctx, key)
	if err != nil {
		// Service-layer "unknown key" surfaces as a generic error here;
		// distinguish via the error string rather than typed errors so
		// we don't grow a sentinel package for a single error class.
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	if row == nil {
		c.JSON(http.StatusNotFound, gin.H{"error": "setting not yet persisted"})
		return
	}
	c.JSON(http.StatusOK, row)
}

// UpdateSystemSettingRequest is the body for PUT /system/admin/settings/:key.
// `value` carries the new value as raw JSON — int / string / bool depending
// on the registry-declared value_type. The service validates the type
// strictly and rejects mismatches with 400.
type UpdateSystemSettingRequest struct {
	// Value is intentionally `any` (decoded as float64 / string / bool /
	// etc. by the JSON unmarshaller). Service.encodeForType normalises
	// these against the registry's declared type and rejects mismatches.
	Value any `json:"value"`
}

// UpdateSystemSetting godoc
// @Summary      Update a system setting value
// @Description  Persist a new value for :key. Service validates the
// @Description  rawValue against the registry's declared value_type and
// @Description  rejects mismatches with 400. SystemAdmin only. Emits an
// @Description  audit row (action=system.setting_changed) on success.
// @Tags         System Admin
// @Accept       json
// @Produce      json
// @Param        key     path string                       true "Setting key"
// @Param        request body UpdateSystemSettingRequest   true "New value"
// @Success      200 {object} types.SystemSetting "the updated row"
// @Failure      400 {object} map[string]interface{} "Bad request / unknown key / type mismatch"
// @Failure      403 {object} map[string]interface{} "Forbidden: not a system admin"
// @Router       /system/admin/settings/{key} [put]
func (h *SystemHandler) UpdateSystemSetting(c *gin.Context) {
	ctx := logger.CloneContext(c.Request.Context())
	key := c.Param("key")

	var req UpdateSystemSettingRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid request: " + err.Error()})
		return
	}
	if req.Value == nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": "value is required"})
		return
	}

	row, err := h.systemSettingSvc.Update(ctx, key, req.Value)
	if err != nil {
		// Whether this is "unknown key" / "type mismatch" / "DB error"
		// is encoded in the error message at the service layer; surface
		// it verbatim. UI captures it as the toast text.
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	h.enrichSettingsModifiedBy(ctx, []*types.SystemSetting{row})
	c.JSON(http.StatusOK, row)
}

// ApplyDefaultStorageQuotaToAllTenants godoc
// @Summary      Apply the default storage quota to every existing workspace
// @Description  Resolves the MB override or legacy GB default (DB > ENV > default per setting)
// @Description  and writes the effective byte quota to every existing workspace. Bypasses
// @Description  the per-workspace PUT whitelist, which forbids storage_quota
// @Description  edits by Owners. SystemAdmin only.
// @Description  Idempotent — running twice with the same setting is a no-op.
// @Tags         System Admin
// @Produce      json
// @Success 200 {object} handler.ApplyDefaultStorageQuotaToAllTenantsResponse "{ affected: int64, quota_bytes: int64 }"
// @Failure      500 {object} map[string]interface{} "DB write failed"
// @Router       /system/admin/tenants/apply-default-storage-quota [post]
func (h *SystemHandler) ApplyDefaultStorageQuotaToAllTenants(c *gin.Context) {
	ctx := logger.CloneContext(c.Request.Context())

	quotaBytes := service.ResolveDefaultTenantStorageQuota(ctx, h.systemSettingSvc)
	gb := float64(quotaBytes) / float64(1024*1024*1024)

	affected, err := h.tenantSvc.BulkSetStorageQuota(ctx, quotaBytes)
	if err != nil {
		logger.Errorf(ctx, "BulkSetStorageQuota failed: %v", err)
		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to apply storage quota"})
		return
	}

	// Audit. We capture quota_bytes (the actual value written) rather
	// than the GB literal so the audit row is unambiguous if someone
	// later changes the setting's units.
	if h.auditSvc != nil {
		actorID, _ := types.UserIDFromContext(ctx)
		details, _ := json.Marshal(map[string]any{
			"quota_bytes": quotaBytes,
			"quota_gb":    gb,
			"affected":    affected,
		})
		_ = h.auditSvc.Log(ctx, &types.AuditLog{
			TenantID:    0,
			ActorUserID: actorID,
			ActorRole:   systemAuditActorRole(ctx),
			Action:      types.AuditActionSystemSettingChanged,
			TargetType:  "tenant_storage_quota",
			TargetID:    "all",
			Outcome:     types.AuditOutcomeSuccess,
			Details:     types.JSON(details),
		})
	}

	c.JSON(http.StatusOK, gin.H{
		"affected":    affected,
		"quota_bytes": quotaBytes,
		"quota_gb":    gb,
	})
}

// ResetSystemSetting godoc
// @Summary      Reset a system setting to ENV / built-in default
// @Description  Removes the DB override for :key so the 3-tier resolver
// @Description  falls back to the environment variable (when configured)
// @Description  or the in-code default. Idempotent — resetting a key
// @Description  that was never persisted returns 200.
// @Tags         System Admin
// @Param        key path string true "Setting key"
// @Success      200 {object} handler.SuccessResponse "Reset acknowledged"
// @Failure      400 {object} map[string]interface{} "Unknown key"
// @Failure      500 {object} map[string]interface{} "DB write failed"
// @Router       /system/admin/settings/{key} [delete]
func (h *SystemHandler) ResetSystemSetting(c *gin.Context) {
	ctx := logger.CloneContext(c.Request.Context())
	key := c.Param("key")
	if err := h.systemSettingSvc.Reset(ctx, key); err != nil {
		// Service surfaces "unknown key" as a plain error string; treat
		// every error as 400 so the UI captures it as a toast. A real
		// DB failure here is rare and indistinguishable from "bad key"
		// at this layer — operators see the message either way.
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	c.JSON(http.StatusOK, gin.H{"success": true})
}