oauth

internal/apps/admin/auth_source/routers.go

@@ -0,0 +1,215 @@
+package auth_source
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/linux-do/credit/internal/model"
+	"github.com/linux-do/credit/internal/util"
+)
+
+type AuthSourceRequest struct {
+	Name               string `json:"name"`
+	Type               string `json:"type"`
+	DisplayName        string `json:"display_name"`
+	IsActive           bool   `json:"is_active"`
+	ClientID           string `json:"client_id"`
+	ClientSecret       string `json:"client_secret"`
+	OpenIDDiscoveryURL string `json:"openid_discovery_url"`
+	Scopes             string `json:"scopes"`
+	IconURL            string `json:"icon_url"`
+}
+
+type ToggleAuthSourceRequest struct {
+	IsActive bool `json:"is_active"`
+}
+
+// ListAuthSources 获取认证源列表
+// @Summary 获取认证源列表
+// @Description 返回所有已配置的 OAuth/OIDC 认证源列表，包括已启用和未启用的，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Success 200 {object} util.ResponseAny{data=[]model.AuthSource} "认证源列表"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限"
+// @Failure 500 {object} util.ResponseAny "内部错误"
+// @Router /api/v1/admin/auth-sources [get]
+func ListAuthSources(c *gin.Context) {
+	sources, err := model.GetAuthSources()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, util.Err(err.Error()))
+		return
+	}
+	c.JSON(http.StatusOK, util.OK(sources))
+}
+
+// CreateAuthSource 创建认证源
+// @Summary 创建认证源
+// @Description 创建一个新的 OAuth/OIDC 认证源配置，认证源名称必须唯一且符合命名规范，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body auth_source.AuthSourceRequest true "创建认证源参数"
+// @Success 200 {object} util.ResponseAny{data=model.AuthSource} "创建成功，返回认证源信息"
+// @Failure 400 {object} util.ResponseAny "参数错误或验证失败"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限"
+// @Router /api/v1/admin/auth-sources [post]
+func CreateAuthSource(c *gin.Context) {
+	var req AuthSourceRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, util.Err(err.Error()))
+		return
+	}
+
+	source := model.AuthSource{
+		Name:               req.Name,
+		Type:               req.Type,
+		DisplayName:        req.DisplayName,
+		IsActive:           req.IsActive,
+		ClientID:           req.ClientID,
+		ClientSecret:       req.ClientSecret,
+		OpenIDDiscoveryURL: req.OpenIDDiscoveryURL,
+		Scopes:             req.Scopes,
+		IconURL:            req.IconURL,
+	}
+	if err := model.CreateAuthSource(&source); err != nil {
+		c.JSON(http.StatusBadRequest, util.Err(err.Error()))
+		return
+	}
+	source.Sanitize()
+	c.JSON(http.StatusOK, util.OK(source))
+}
+
+// UpdateAuthSource 更新认证源
+// @Summary 更新认证源
+// @Description 更新指定 ID 的认证源配置。若 client_secret 字段为空，则保留原有密钥不变，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param id path uint64 true "认证源 ID 或名称"
+// @Param request body auth_source.AuthSourceRequest true "更新认证源参数"
+// @Success 200 {object} util.ResponseAny{data=model.AuthSource} "更新成功，返回更新后的认证源信息"
+// @Failure 400 {object} util.ResponseAny "参数错误或验证失败"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限"
+// @Failure 500 {object} util.ResponseAny "内部错误"
+// @Router /api/v1/admin/auth-sources/{id} [put]
+func UpdateAuthSource(c *gin.Context) {
+	id, err := parseSourceID(c)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, util.Err(err.Error()))
+		return
+	}
+
+	var req AuthSourceRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, util.Err(err.Error()))
+		return
+	}
+
+	source := model.AuthSource{
+		ID:                 id,
+		Name:               req.Name,
+		Type:               req.Type,
+		DisplayName:        req.DisplayName,
+		IsActive:           req.IsActive,
+		ClientID:           req.ClientID,
+		ClientSecret:       req.ClientSecret,
+		OpenIDDiscoveryURL: req.OpenIDDiscoveryURL,
+		Scopes:             req.Scopes,
+		IconURL:            req.IconURL,
+	}
+	keepSecret := source.ClientSecret == ""
+	if err := model.UpdateAuthSource(&source, keepSecret); err != nil {
+		c.JSON(http.StatusBadRequest, util.Err(err.Error()))
+		return
+	}
+	updated, err := model.GetAuthSourceByID(id)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, util.Err(err.Error()))
+		return
+	}
+	updated.Sanitize()
+	c.JSON(http.StatusOK, util.OK(updated))
+}
+
+// ToggleAuthSource 切换认证源启用状态
+// @Summary 切换认证源启用状态
+// @Description 启用或禁用指定认证源。尝试启用时将验证 Client ID 和 Client Secret 是否已配置，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param id path uint64 true "认证源 ID 或名称"
+// @Param request body auth_source.ToggleAuthSourceRequest true "启用状态"
+// @Success 200 {object} util.ResponseAny{data=string} "切换成功"
+// @Failure 400 {object} util.ResponseAny "验证失败或认证源不存在"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限"
+// @Router /api/v1/admin/auth-sources/{id}/toggle [put]
+func ToggleAuthSource(c *gin.Context) {
+	id, err := parseSourceID(c)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, util.Err(err.Error()))
+		return
+	}
+
+	var req ToggleAuthSourceRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, util.Err(err.Error()))
+		return
+	}
+
+	if err := model.ToggleAuthSource(id, req.IsActive); err != nil {
+		c.JSON(http.StatusBadRequest, util.Err(err.Error()))
+		return
+	}
+	c.JSON(http.StatusOK, util.OKNil())
+}
+
+// DeleteAuthSource 删除认证源
+// @Summary 删除认证源
+// @Description 删除指定认证源及其关联的所有外部帐号绑定记录，警告：删除后相关用户将无法通过该源登录，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param id path uint64 true "认证源 ID 或名称"
+// @Success 200 {object} util.ResponseAny{data=string} "删除成功"
+// @Failure 400 {object} util.ResponseAny "ID 无效或删除失败"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限"
+// @Router /api/v1/admin/auth-sources/{id} [delete]
+func DeleteAuthSource(c *gin.Context) {
+	id, err := parseSourceID(c)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, util.Err(err.Error()))
+		return
+	}
+	if err := model.DeleteAuthSource(id); err != nil {
+		c.JSON(http.StatusBadRequest, util.Err(err.Error()))
+		return
+	}
+	c.JSON(http.StatusOK, util.OKNil())
+}
+
+func parseSourceID(c *gin.Context) (uint64, error) {
+	raw := c.Param("id")
+	if raw == "" {
+		return 0, errors.New("认证源 ID 无效")
+	}
+	source, err := model.GetAuthSourceByName(raw)
+	if err == nil {
+		return source.ID, nil
+	}
+	var id uint64
+	if _, scanErr := fmt.Sscanf(raw, "%d", &id); scanErr != nil || id == 0 {
+		return 0, errors.New("认证源 ID 无效")
+	}
+	return id, nil
+}

internal/apps/admin/auth_source/routers_test.go

@@ -0,0 +1,345 @@
+/*
+Copyright 2026 linux.do
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package auth_source
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/linux-do/credit/internal/apps/oauth"
+	"github.com/linux-do/credit/internal/model"
+	"github.com/linux-do/credit/internal/testhelper"
+	"github.com/linux-do/credit/internal/util"
+)
+
+func setupTestRouter(authUser *model.User) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	adminGroup := r.Group("/api/v1/admin")
+
+	// Mock authentication middleware
+	adminGroup.Use(func(c *gin.Context) {
+		if authUser != nil {
+			util.SetToContext(c, oauth.UserObjKey, authUser)
+		}
+		c.Next()
+	})
+
+	adminGroup.GET("/auth-sources", ListAuthSources)
+	adminGroup.POST("/auth-sources", CreateAuthSource)
+	adminGroup.PUT("/auth-sources/:id", UpdateAuthSource)
+	adminGroup.PUT("/auth-sources/:id/toggle", ToggleAuthSource)
+	adminGroup.DELETE("/auth-sources/:id", DeleteAuthSource)
+	return r
+}
+
+func TestListAuthSources(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	// Seed source
+	source := model.AuthSource{
+		ID:                 1,
+		Name:               "google",
+		Type:               "oidc",
+		DisplayName:        "Google Auth",
+		IsActive:           true,
+		ClientID:           "client_id_123",
+		ClientSecret:       "client_secret_456",
+		OpenIDDiscoveryURL: "https://accounts.google.com",
+	}
+	dbConn.Create(&source)
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true, SignKey: "admin_key"}
+	router := setupTestRouter(adminUser)
+
+	req, _ := http.NewRequest("GET", "/api/v1/admin/auth-sources", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200 OK, got %d", w.Code)
+	}
+
+	var resp util.ResponseAny
+	json.Unmarshal(w.Body.Bytes(), &resp)
+
+	dataBytes, _ := json.Marshal(resp.Data)
+	var sources []model.AuthSource
+	json.Unmarshal(dataBytes, &sources)
+
+	if len(sources) != 1 {
+		t.Errorf("expected 1 auth source, got %d", len(sources))
+	}
+	if sources[0].Name != "google" {
+		t.Errorf("expected name 'google', got '%s'", sources[0].Name)
+	}
+	// Verify sanitize removed the secret
+	if sources[0].ClientSecret != "" {
+		t.Error("client secret should be sanitized")
+	}
+	if !sources[0].ClientSecretConfigured {
+		t.Error("client secret configured flag should be true")
+	}
+}
+
+func TestCreateAuthSource(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true, SignKey: "admin_key"}
+	router := setupTestRouter(adminUser)
+
+	t.Run("create successfully", func(t *testing.T) {
+		reqPayload := AuthSourceRequest{
+			Name:               "github",
+			Type:               "oidc",
+			DisplayName:        "GitHub OIDC",
+			IsActive:           true,
+			ClientID:           "client_id_gh",
+			ClientSecret:       "client_secret_gh",
+			OpenIDDiscoveryURL: "https://github.com",
+		}
+		body, _ := json.Marshal(reqPayload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/auth-sources", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		// Verify database
+		var src model.AuthSource
+		dbConn.Where("name = ?", "github").First(&src)
+		if src.ClientID != "client_id_gh" {
+			t.Errorf("expected client_id_gh, got '%s'", src.ClientID)
+		}
+	})
+
+	t.Run("create invalid validation failure", func(t *testing.T) {
+		reqPayload := AuthSourceRequest{
+			Name:               "invalid name!",
+			Type:               "oidc",
+			DisplayName:        "Invalid",
+			IsActive:           true,
+			ClientID:           "client_id_val",
+			ClientSecret:       "client_secret_val",
+			OpenIDDiscoveryURL: "https://discovery.url",
+		}
+		body, _ := json.Marshal(reqPayload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/auth-sources", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request, got %d", w.Code)
+		}
+	})
+}
+
+func TestUpdateAuthSource(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	// Seed source
+	source := model.AuthSource{
+		ID:                 1,
+		Name:               "microsoft",
+		Type:               "oidc",
+		DisplayName:        "Microsoft",
+		IsActive:           true,
+		ClientID:           "old_client_id",
+		ClientSecret:       "old_secret",
+		OpenIDDiscoveryURL: "https://login.microsoftonline.com",
+	}
+	dbConn.Create(&source)
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true, SignKey: "admin_key"}
+	router := setupTestRouter(adminUser)
+
+	t.Run("update keep client secret", func(t *testing.T) {
+		reqPayload := AuthSourceRequest{
+			Name:               "microsoft",
+			Type:               "oidc",
+			DisplayName:        "Microsoft Updated",
+			IsActive:           true,
+			ClientID:           "new_client_id",
+			ClientSecret:       "", // empty implies keeping existing secret
+			OpenIDDiscoveryURL: "https://login.microsoftonline.com",
+		}
+		body, _ := json.Marshal(reqPayload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/auth-sources/1", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var src model.AuthSource
+		dbConn.First(&src, 1)
+		if src.DisplayName != "Microsoft Updated" {
+			t.Errorf("expected display name update, got '%s'", src.DisplayName)
+		}
+		if src.ClientSecret != "old_secret" {
+			t.Errorf("expected old secret to be preserved, got '%s'", src.ClientSecret)
+		}
+	})
+
+	t.Run("update new client secret", func(t *testing.T) {
+		reqPayload := AuthSourceRequest{
+			Name:               "microsoft",
+			Type:               "oidc",
+			DisplayName:        "Microsoft Updated Again",
+			IsActive:           true,
+			ClientID:           "new_client_id",
+			ClientSecret:       "brand_new_secret",
+			OpenIDDiscoveryURL: "https://login.microsoftonline.com",
+		}
+		body, _ := json.Marshal(reqPayload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/auth-sources/microsoft", bytes.NewBuffer(body)) // Using Name instead of ID
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var src model.AuthSource
+		dbConn.First(&src, 1)
+		if src.ClientSecret != "brand_new_secret" {
+			t.Errorf("expected secret update, got '%s'", src.ClientSecret)
+		}
+	})
+}
+
+func TestToggleAuthSource(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	source := model.AuthSource{
+		ID:                 1,
+		Name:               "test_source",
+		Type:               "oidc",
+		DisplayName:        "Test Source",
+		IsActive:           false,
+		ClientID:           "",
+		ClientSecret:       "",
+		OpenIDDiscoveryURL: "https://test.discovery.url",
+	}
+	dbConn.Create(&source)
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true, SignKey: "admin_key"}
+	router := setupTestRouter(adminUser)
+
+	t.Run("cannot activate without credentials", func(t *testing.T) {
+		payload := ToggleAuthSourceRequest{IsActive: true}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/auth-sources/1/toggle", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request when activating without client_id/secret, got %d", w.Code)
+		}
+	})
+
+	t.Run("toggle success after setting credentials", func(t *testing.T) {
+		// Set credentials first
+		dbConn.Model(&model.AuthSource{}).Where("id = ?", 1).Updates(map[string]interface{}{
+			"client_id":     "id",
+			"client_secret": "secret",
+		})
+
+		payload := ToggleAuthSourceRequest{IsActive: true}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/auth-sources/1/toggle", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var src model.AuthSource
+		dbConn.First(&src, 1)
+		if !src.IsActive {
+			t.Error("auth source should be activated")
+		}
+	})
+}
+
+func TestDeleteAuthSource(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	source := model.AuthSource{
+		ID:                 1,
+		Name:               "delete_me",
+		Type:               "oidc",
+		DisplayName:        "Delete Me",
+		IsActive:           true,
+		ClientID:           "id",
+		ClientSecret:       "secret",
+		OpenIDDiscoveryURL: "https://delete.me",
+	}
+	dbConn.Create(&source)
+
+	externalAccount := model.ExternalAccount{
+		ID:           10,
+		AuthSourceID: 1,
+		UserID:       50,
+		ExternalID:   "ext_50",
+	}
+	dbConn.Create(&externalAccount)
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true, SignKey: "admin_key"}
+	router := setupTestRouter(adminUser)
+
+	req, _ := http.NewRequest("DELETE", "/api/v1/admin/auth-sources/1", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200 OK, got %d", w.Code)
+	}
+
+	// Verify AuthSource is deleted
+	var srcCount int64
+	dbConn.Model(&model.AuthSource{}).Where("id = ?", 1).Count(&srcCount)
+	if srcCount != 0 {
+		t.Error("AuthSource should be deleted from the database")
+	}
+
+	// Verify ExternalAccount bindings are also deleted
+	var extCount int64
+	dbConn.Model(&model.ExternalAccount{}).Where("auth_source_id = ?", 1).Count(&extCount)
+	if extCount != 0 {
+		t.Error("related ExternalAccount bindings should be deleted")
+	}
+}

internal/apps/admin/system_config/routers.go

@@ -47,8 +47,13 @@ type UpdateSystemConfigRequest struct {
 // @Tags admin
 // @Accept json
 // @Produce json
-// @Param request body CreateSystemConfigRequest true "创建请求参数"
-// @Success 200 {object} util.ResponseAny
+// @Security SessionCookie
+// @Param request body system_config.CreateSystemConfigRequest true "创建请求参数"
+// @Success 200 {object} util.ResponseAny{data=string} "创建成功"
+// @Failure 400 {object} util.ResponseAny "参数错误或配置键已存在"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限"
+// @Failure 500 {object} util.ResponseAny "内部错误"
 // @Router /api/v1/admin/system-configs [post]
 func CreateSystemConfig(c *gin.Context) {
 	var req CreateSystemConfigRequest
@@ -98,8 +103,12 @@ func CreateSystemConfig(c *gin.Context) {
 // @Description 返回所有系统配置列表，支持按配置类型（system/business）过滤，需要管理员权限
 // @Tags admin
 // @Produce json
+// @Security SessionCookie
 // @Param type query string false "配置类型（system/business）"
-// @Success 200 {object} util.ResponseAny
+// @Success 200 {object} util.ResponseAny{data=[]model.SystemConfig} "系统配置列表"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限"
+// @Failure 500 {object} util.ResponseAny "内部错误"
 // @Router /api/v1/admin/system-configs [get]
 func ListSystemConfigs(c *gin.Context) {
 	configType := c.Query("type")
@@ -122,8 +131,13 @@ func ListSystemConfigs(c *gin.Context) {
 // @Description 根据配置键获取对应的系统配置详情，需要管理员权限
 // @Tags admin
 // @Produce json
+// @Security SessionCookie
 // @Param key path string true "配置键"
-// @Success 200 {object} util.ResponseAny
+// @Success 200 {object} util.ResponseAny{data=model.SystemConfig} "系统配置详情"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限"
+// @Failure 404 {object} util.ResponseAny "配置不存在"
+// @Failure 500 {object} util.ResponseAny "内部错误"
 // @Router /api/v1/admin/system-configs/{key} [get]
 func GetSystemConfig(c *gin.Context) {
 	var config model.SystemConfig
@@ -145,9 +159,15 @@ func GetSystemConfig(c *gin.Context) {
 // @Tags admin
 // @Accept json
 // @Produce json
+// @Security SessionCookie
 // @Param key path string true "配置键"
-// @Param request body UpdateSystemConfigRequest true "更新请求参数"
-// @Success 200 {object} util.ResponseAny
+// @Param request body system_config.UpdateSystemConfigRequest true "更新请求参数"
+// @Success 200 {object} util.ResponseAny{data=string} "更新成功"
+// @Failure 400 {object} util.ResponseAny "参数错误"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限"
+// @Failure 404 {object} util.ResponseAny "配置不存在"
+// @Failure 500 {object} util.ResponseAny "内部错误"
 // @Router /api/v1/admin/system-configs/{key} [put]
 func UpdateSystemConfig(c *gin.Context) {
 	var req UpdateSystemConfigRequest
@@ -197,8 +217,13 @@ func UpdateSystemConfig(c *gin.Context) {
 // @Description 根据配置键删除对应配置，同时从 Redis 中移除对应缓存，需要管理员权限
 // @Tags admin
 // @Produce json
+// @Security SessionCookie
 // @Param key path string true "配置键"
-// @Success 200 {object} util.ResponseAny
+// @Success 200 {object} util.ResponseAny{data=string} "删除成功"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限"
+// @Failure 404 {object} util.ResponseAny "配置不存在"
+// @Failure 500 {object} util.ResponseAny "内部错误"
 // @Router /api/v1/admin/system-configs/{key} [delete]
 func DeleteSystemConfig(c *gin.Context) {
 	key := c.Param("key")

internal/apps/admin/system_config/routers_test.go

@@ -0,0 +1,302 @@
+/*
+Copyright 2026 linux.do
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package system_config
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/linux-do/credit/internal/apps/oauth"
+	"github.com/linux-do/credit/internal/db"
+	"github.com/linux-do/credit/internal/model"
+	"github.com/linux-do/credit/internal/testhelper"
+	"github.com/linux-do/credit/internal/util"
+)
+
+func setupTestRouter(authUser *model.User) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	adminGroup := r.Group("/api/v1/admin")
+
+	// Mock authentication middleware
+	adminGroup.Use(func(c *gin.Context) {
+		if authUser != nil {
+			util.SetToContext(c, oauth.UserObjKey, authUser)
+		}
+		c.Next()
+	})
+
+	adminGroup.POST("/system-configs", CreateSystemConfig)
+	adminGroup.GET("/system-configs", ListSystemConfigs)
+
+	systemConfigRouter := adminGroup.Group("/system-configs/:key")
+	{
+		systemConfigRouter.GET("", GetSystemConfig)
+		systemConfigRouter.PUT("", UpdateSystemConfig)
+		systemConfigRouter.DELETE("", DeleteSystemConfig)
+	}
+
+	return r
+}
+
+func TestCreateSystemConfig(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true, SignKey: "admin_key"}
+	router := setupTestRouter(adminUser)
+
+	t.Run("create successfully", func(t *testing.T) {
+		payload := CreateSystemConfigRequest{
+			Key:         "custom_key",
+			Value:       "custom_value",
+			Type:        "system",
+			Description: "desc",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/system-configs", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		// Verify database
+		var cfg model.SystemConfig
+		err := dbConn.Where("key = ?", "custom_key").First(&cfg).Error
+		if err != nil {
+			t.Fatalf("failed to find system config in DB: %v", err)
+		}
+
+		// Verify Redis Cache
+		var redisConfig model.SystemConfig
+		err = db.HGetJSON(context.Background(), model.SystemConfigRedisHashKey, "custom_key", &redisConfig)
+		if err != nil {
+			t.Fatalf("failed to find system config in Redis: %v", err)
+		}
+		if redisConfig.Value != "custom_value" {
+			t.Errorf("expected value 'custom_value', got '%s'", redisConfig.Value)
+		}
+	})
+
+	t.Run("create duplicate key error", func(t *testing.T) {
+		// Key "custom_key" already exists from previous test
+		payload := CreateSystemConfigRequest{
+			Key:         "custom_key",
+			Value:       "another_value",
+			Type:        "system",
+			Description: "desc",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/system-configs", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request on duplicate key, got %d", w.Code)
+		}
+	})
+}
+
+func TestListSystemConfigs(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true, SignKey: "admin_key"}
+	router := setupTestRouter(adminUser)
+
+	t.Run("list all seeded configurations", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/system-configs", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d", w.Code)
+		}
+
+		var resp util.ResponseAny
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var configs []model.SystemConfig
+		json.Unmarshal(dataBytes, &configs)
+
+		// Defaults seed 7 configurations
+		if len(configs) != 7 {
+			t.Errorf("expected 7 default configs, got %d", len(configs))
+		}
+	})
+
+	t.Run("filter by type business", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/system-configs?type=business", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		var resp util.ResponseAny
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var configs []model.SystemConfig
+		json.Unmarshal(dataBytes, &configs)
+
+		if len(configs) != 1 || configs[0].Key != model.ConfigKeyMaxAPIKeysPerUser {
+			t.Errorf("expected 1 business config (max_api_keys_per_user), got %d: %v", len(configs), configs)
+		}
+	})
+}
+
+func TestGetSystemConfig(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true, SignKey: "admin_key"}
+	router := setupTestRouter(adminUser)
+
+	t.Run("get existing configuration", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/system-configs/"+model.ConfigKeySiteName, nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("expected 200 OK, got %d", w.Code)
+		}
+
+		var resp util.ResponseAny
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var cfg model.SystemConfig
+		json.Unmarshal(dataBytes, &cfg)
+
+		if cfg.Value != "Antigravity Project" {
+			t.Errorf("expected 'Antigravity Project', got '%s'", cfg.Value)
+		}
+	})
+
+	t.Run("get non-existent config", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/system-configs/non_existent_key", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusNotFound {
+			t.Errorf("expected 404 Not Found, got %d", w.Code)
+		}
+	})
+}
+
+func TestUpdateSystemConfig(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true, SignKey: "admin_key"}
+	router := setupTestRouter(adminUser)
+
+	t.Run("update successfully", func(t *testing.T) {
+		payload := UpdateSystemConfigRequest{
+			Value:       "Super Site Name",
+			Description: "Updated Description",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/system-configs/"+model.ConfigKeySiteName, bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		// Verify database
+		var cfg model.SystemConfig
+		dbConn.Where("key = ?", model.ConfigKeySiteName).First(&cfg)
+		if cfg.Value != "Super Site Name" || cfg.Description != "Updated Description" {
+			t.Errorf("database values not updated: %+v", cfg)
+		}
+
+		// Verify Redis
+		var redisConfig model.SystemConfig
+		db.HGetJSON(context.Background(), model.SystemConfigRedisHashKey, model.ConfigKeySiteName, &redisConfig)
+		if redisConfig.Value != "Super Site Name" {
+			t.Errorf("redis cache value not updated, got '%s'", redisConfig.Value)
+		}
+	})
+
+	t.Run("update non-existent config", func(t *testing.T) {
+		payload := UpdateSystemConfigRequest{
+			Value: "New Value",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/system-configs/invalid_key", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusNotFound {
+			t.Errorf("expected 404 Not Found, got %d", w.Code)
+		}
+	})
+}
+
+func TestDeleteSystemConfig(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true, SignKey: "admin_key"}
+	router := setupTestRouter(adminUser)
+
+	t.Run("delete successfully", func(t *testing.T) {
+		req, _ := http.NewRequest("DELETE", "/api/v1/admin/system-configs/"+model.ConfigKeySiteName, nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		// Verify database
+		var count int64
+		dbConn.Model(&model.SystemConfig{}).Where("key = ?", model.ConfigKeySiteName).Count(&count)
+		if count != 0 {
+			t.Error("config still exists in DB")
+		}
+
+		// Verify Redis Cache removal
+		var redisConfig model.SystemConfig
+		err := db.HGetJSON(context.Background(), model.SystemConfigRedisHashKey, model.ConfigKeySiteName, &redisConfig)
+		if err == nil {
+			t.Error("config should have been deleted from Redis cache")
+		}
+	})
+
+	t.Run("delete non-existent config", func(t *testing.T) {
+		req, _ := http.NewRequest("DELETE", "/api/v1/admin/system-configs/invalid_key", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusNotFound {
+			t.Errorf("expected 404 Not Found, got %d", w.Code)
+		}
+	})
+}

internal/apps/admin/task/routers.go

@@ -30,10 +30,13 @@ import (
 
 // ListTaskTypes 获取支持的任务类型列表
 // @Summary 获取支持的任务类型
-// @Description 返回系统支持的所有可调度任务类型列表，需要管理员权限
+// @Description 返回系统支持的所有可调度任务类型列表，包括任务名称、描述、是否支持时间范围等元数据，需要管理员权限
 // @Tags admin
 // @Produce json
-// @Success 200 {object} util.ResponseAny
+// @Security SessionCookie
+// @Success 200 {object} util.ResponseAny{data=[]task.TaskMeta} "任务类型列表"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限"
 // @Router /api/v1/admin/tasks/types [get]
 func ListTaskTypes(c *gin.Context) {
 	c.JSON(http.StatusOK, util.OK(task.DispatchableTasks))
@@ -53,8 +56,13 @@ type DispatchTaskRequest struct {
 // @Tags admin
 // @Accept json
 // @Produce json
-// @Param request body DispatchTaskRequest true "任务请求参数"
-// @Success 200 {object} util.ResponseAny
+// @Security SessionCookie
+// @Param request body task.DispatchTaskRequest true "任务请求参数"
+// @Success 200 {object} util.ResponseAny{data=string} "任务已入队"
+// @Failure 400 {object} util.ResponseAny "任务类型不存在或参数错误"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限"
+// @Failure 500 {object} util.ResponseAny "任务入队失败"
 // @Router /api/v1/admin/tasks/dispatch [post]
 func DispatchTask(c *gin.Context) {
 	var req DispatchTaskRequest

internal/apps/admin/task/routers_test.go

@@ -0,0 +1,132 @@
+/*
+Copyright 2026 linux.do
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package task
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/linux-do/credit/internal/apps/oauth"
+	"github.com/linux-do/credit/internal/model"
+	"github.com/linux-do/credit/internal/task"
+	"github.com/linux-do/credit/internal/testhelper"
+	"github.com/linux-do/credit/internal/util"
+)
+
+func setupTestRouter(authUser *model.User) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	adminGroup := r.Group("/api/v1/admin")
+
+	// Mock authentication middleware
+	adminGroup.Use(func(c *gin.Context) {
+		if authUser != nil {
+			util.SetToContext(c, oauth.UserObjKey, authUser)
+		}
+		c.Next()
+	})
+
+	adminGroup.GET("/tasks/types", ListTaskTypes)
+	adminGroup.POST("/tasks/dispatch", DispatchTask)
+	return r
+}
+
+func TestListTaskTypes(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true, SignKey: "admin_key"}
+	router := setupTestRouter(adminUser)
+
+	req, _ := http.NewRequest("GET", "/api/v1/admin/tasks/types", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200 OK, got %d", w.Code)
+	}
+
+	var resp util.ResponseAny
+	json.Unmarshal(w.Body.Bytes(), &resp)
+
+	dataBytes, _ := json.Marshal(resp.Data)
+	var taskMetas []task.TaskMeta
+	json.Unmarshal(dataBytes, &taskMetas)
+
+	if len(taskMetas) == 0 {
+		t.Error("expected at least one dispatchable task type")
+	}
+
+	foundCleanup := false
+	for _, m := range taskMetas {
+		if m.Type == task.TaskTypeCleanupUploads {
+			foundCleanup = true
+			break
+		}
+	}
+	if !foundCleanup {
+		t.Errorf("expected task type %s to be listed", task.TaskTypeCleanupUploads)
+	}
+}
+
+func TestDispatchTask(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true, SignKey: "admin_key"}
+	router := setupTestRouter(adminUser)
+
+	t.Run("dispatch valid task successfully", func(t *testing.T) {
+		payload := DispatchTaskRequest{
+			TaskType: task.TaskTypeCleanupUploads,
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/tasks/dispatch", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+	})
+
+	t.Run("dispatch invalid task type failure", func(t *testing.T) {
+		payload := DispatchTaskRequest{
+			TaskType: "invalid_task_type",
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/tasks/dispatch", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request, got %d", w.Code)
+		}
+
+		var resp util.ResponseAny
+		json.Unmarshal(w.Body.Bytes(), &resp)
+		if resp.ErrorMsg != InvalidTaskType {
+			t.Errorf("expected error message '%s', got '%s'", InvalidTaskType, resp.ErrorMsg)
+		}
+	})
+}

internal/apps/admin/user/routers.go

@@ -68,8 +68,13 @@ type listUsersResponse struct {
 // @Description 分页返回用户列表，支持按用户 ID 和用户名筛选，需要管理员权限
 // @Tags admin
 // @Produce json
+// @Security SessionCookie
 // @Param request query listUsersRequest true "查询参数"
-// @Success 200 {object} util.ResponseAny
+// @Success 200 {object} util.ResponseAny{data=user.listUsersResponse} "用户列表"
+// @Failure 400 {object} util.ResponseAny "参数错误"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限"
+// @Failure 500 {object} util.ResponseAny "内部错误"
 // @Router /api/v1/admin/users [get]
 func ListUsers(c *gin.Context) {
 	var req listUsersRequest
@@ -129,9 +134,15 @@ type updateUserStatusRequest struct {
 // @Tags admin
 // @Accept json
 // @Produce json
-// @Param id path int true "用户ID"
+// @Security SessionCookie
+// @Param id path int true "用户 ID"
 // @Param request body updateUserStatusRequest true "状态参数"
-// @Success 200 {object} util.ResponseAny
+// @Success 200 {object} util.ResponseAny{data=string} "更新成功"
+// @Failure 400 {object} util.ResponseAny "参数错误"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限或尝试禁用管理员"
+// @Failure 404 {object} util.ResponseAny "用户不存在"
+// @Failure 500 {object} util.ResponseAny "内部错误"
 // @Router /api/v1/admin/users/{id}/status [put]
 func UpdateUserStatus(c *gin.Context) {
 	var req updateUserStatusRequest

internal/apps/admin/user/routers_test.go

@@ -0,0 +1,254 @@
+/*
+Copyright 2026 linux.do
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package user
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/linux-do/credit/internal/apps/oauth"
+	"github.com/linux-do/credit/internal/model"
+	"github.com/linux-do/credit/internal/testhelper"
+	"github.com/linux-do/credit/internal/util"
+	"github.com/shopspring/decimal"
+)
+
+func setupTestRouter(authUser *model.User) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	adminGroup := r.Group("/api/v1/admin")
+
+	// Mock authentication middleware
+	adminGroup.Use(func(c *gin.Context) {
+		if authUser != nil {
+			util.SetToContext(c, oauth.UserObjKey, authUser)
+		}
+		c.Next()
+	})
+
+	adminGroup.GET("/users", ListUsers)
+	adminGroup.PUT("/users/:id/status", UpdateUserStatus)
+	return r
+}
+
+func TestListUsers(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	// Seed users
+	users := []model.User{
+		{
+			ID:               1001,
+			Username:         "alice",
+			Nickname:         "Alice Nickname",
+			IsActive:         true,
+			IsAdmin:          false,
+			AvailableBalance: decimal.NewFromFloat(100.0),
+			LastLoginAt:      time.Now(),
+			SignKey:          "alice_sign_key",
+		},
+		{
+			ID:               1002,
+			Username:         "bob",
+			Nickname:         "Bob Nickname",
+			IsActive:         true,
+			IsAdmin:          false,
+			AvailableBalance: decimal.NewFromFloat(50.0),
+			LastLoginAt:      time.Now(),
+			SignKey:          "bob_sign_key",
+		},
+		{
+			ID:               1003,
+			Username:         "charlie",
+			Nickname:         "Charlie Nickname",
+			IsActive:         false,
+			IsAdmin:          true,
+			AvailableBalance: decimal.NewFromFloat(9999.0),
+			LastLoginAt:      time.Now(),
+			SignKey:          "charlie_sign_key",
+		},
+	}
+
+	for _, u := range users {
+		if err := dbConn.Create(&u).Error; err != nil {
+			t.Fatalf("failed to seed user: %v", err)
+		}
+	}
+
+	adminUser := &model.User{ID: 1003, Username: "charlie", IsAdmin: true, SignKey: "charlie_sign_key"}
+	router := setupTestRouter(adminUser)
+
+	t.Run("basic pagination list", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/users?page=1&page_size=2", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var resp util.ResponseAny
+		if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("failed to parse response: %v", err)
+		}
+
+		// Parse data map to our structure
+		dataBytes, _ := json.Marshal(resp.Data)
+		var listResp listUsersResponse
+		if err := json.Unmarshal(dataBytes, &listResp); err != nil {
+			t.Fatalf("failed to parse list response: %v", err)
+		}
+
+		if len(listResp.Users) != 2 {
+			t.Errorf("expected 2 users, got %d", len(listResp.Users))
+		}
+		if listResp.Total != 3 {
+			t.Errorf("expected total 3, got %d", listResp.Total)
+		}
+		// Ordered by ID DESC
+		if listResp.Users[0].ID != 1003 || listResp.Users[1].ID != 1002 {
+			t.Errorf("expected ordered DESC, got first ID %d, second ID %d", listResp.Users[0].ID, listResp.Users[1].ID)
+		}
+	})
+
+	t.Run("filter by user_id", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/users?page=1&page_size=10&user_id=1001", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		var resp util.ResponseAny
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var listResp listUsersResponse
+		json.Unmarshal(dataBytes, &listResp)
+
+		if len(listResp.Users) != 1 || listResp.Users[0].ID != 1001 {
+			t.Errorf("expected 1 user with ID 1001, got total %d", len(listResp.Users))
+		}
+	})
+
+	t.Run("filter by username prefix", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/users?page=1&page_size=10&username=bo", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		var resp util.ResponseAny
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var listResp listUsersResponse
+		json.Unmarshal(dataBytes, &listResp)
+
+		if len(listResp.Users) != 1 || listResp.Users[0].Username != "bob" {
+			t.Errorf("expected bob, got %v", listResp.Users)
+		}
+	})
+
+	t.Run("invalid pagination parameter", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/users?page=0&page_size=10", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("expected 400 Bad Request, got %d", w.Code)
+		}
+	})
+}
+
+func TestUpdateUserStatus(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	// Seed users
+	regularUser := model.User{
+		ID:       1001,
+		Username: "alice",
+		IsActive: true,
+		IsAdmin:  false,
+		SignKey:  "alice_sign_key",
+	}
+	adminUser := model.User{
+		ID:       1002,
+		Username: "bob",
+		IsActive: true,
+		IsAdmin:  true,
+		SignKey:  "bob_sign_key",
+	}
+
+	dbConn.Create(&regularUser)
+	dbConn.Create(&adminUser)
+
+	router := setupTestRouter(&adminUser)
+
+	t.Run("disable regular user successfully", func(t *testing.T) {
+		payload := updateUserStatusRequest{IsActive: false}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/users/1001/status", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		// Verify DB status
+		var u model.User
+		dbConn.First(&u, 1001)
+		if u.IsActive {
+			t.Error("user should be deactivated in the database")
+		}
+	})
+
+	t.Run("cannot disable admin user", func(t *testing.T) {
+		payload := updateUserStatusRequest{IsActive: false}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/users/1002/status", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusForbidden {
+			t.Errorf("expected 403 Forbidden, got %d. Body: %s", w.Code, w.Body.String())
+		}
+
+		var resp util.ResponseAny
+		json.Unmarshal(w.Body.Bytes(), &resp)
+		if resp.ErrorMsg != cannotDisable {
+			t.Errorf("expected error message '%s', got '%s'", cannotDisable, resp.ErrorMsg)
+		}
+	})
+
+	t.Run("cannot enable/disable non-existent user", func(t *testing.T) {
+		payload := updateUserStatusRequest{IsActive: false}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("PUT", "/api/v1/admin/users/9999/status", bytes.NewBuffer(body))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusNotFound {
+			t.Errorf("expected 404 Not Found, got %d. Body: %s", w.Code, w.Body.String())
+		}
+	})
+}