refactor(repo): consolidate openflare-server to root and move subprojects to internal/apps

- Merge all files inside openflare-server to the repository root directory.
- Relocate agent, relay, and flared subprojects from internal/ to internal/apps/.
- Combine docker-compose files and update build context paths to root.
- Update GitHub workflows and Dockerfiles to refer to new directories and package names.
- Rewrite Go package imports across all files.
- Resolve database renew test race condition and clean up docs.

internal/apps/admin/user/errs.go

@@ -0,0 +1,21 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package user 提供用户管理功能
+package user
+
+const (
+	userNotFound     = "用户不存在"
+	cannotDisable    = "不能禁用管理员用户"
+	cannotDelete     = "不能删除管理员用户"
+	cannotDeleteSelf = "不能删除当前登录用户"
+	updateUserFailed = "更新用户状态失败"
+	deleteUserFailed = "删除用户失败"
+	usernameExists   = "用户名已存在"
+	usernameRequired = "用户名不能为空"
+	passwordTooShort = "密码长度不能少于 8 位" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	createUserFailed = "创建用户失败"
+	emailRequired    = "邮箱不能为空"
+	emailExists      = "邮箱已被注册"
+)

internal/apps/admin/user/logics.go

@@ -0,0 +1,106 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/db/idgen"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+)
+
+func listUsers(ctx context.Context, req listUsersRequest) (int64, []model.User, error) {
+	return repository.ListAdminUsers(ctx, repository.AdminUserListFilter{
+		UserID:   req.UserID,
+		Username: strings.TrimSpace(req.Username),
+		Page:     req.Page,
+		PageSize: req.PageSize,
+	})
+}
+
+func getUserDetail(ctx context.Context, id uint64) (model.User, error) {
+	return repository.GetAdminUserDetail(ctx, id)
+}
+
+func updateUserStatus(ctx context.Context, id uint64, active bool) error {
+	flags, err := repository.GetUserAdminFlags(ctx, id)
+	if err != nil {
+		return err
+	}
+	if !active && flags.IsAdmin {
+		return errors.New(cannotDisable)
+	}
+	return repository.UpdateUserActive(ctx, id, active)
+}
+
+func deleteUser(ctx context.Context, currentUserID, targetID uint64) error {
+	if currentUserID == targetID {
+		return errors.New(cannotDeleteSelf)
+	}
+	flags, err := repository.GetUserAdminFlags(ctx, targetID)
+	if err != nil {
+		return err
+	}
+	if flags.IsAdmin {
+		return errors.New(cannotDelete)
+	}
+	return repository.DeleteUserWithRelations(ctx, targetID)
+}
+
+func createUser(ctx context.Context, req createUserRequest) (model.User, error) {
+	req.Username = strings.TrimSpace(req.Username)
+	req.Nickname = strings.TrimSpace(req.Nickname)
+	req.Password = strings.TrimSpace(req.Password)
+	req.Email = strings.TrimSpace(req.Email)
+
+	if req.Username == "" {
+		return model.User{}, errors.New(usernameRequired)
+	}
+	if req.Email == "" {
+		return model.User{}, errors.New(emailRequired)
+	}
+	if len(req.Password) < minPasswordLength {
+		return model.User{}, errors.New(passwordTooShort)
+	}
+
+	count, err := repository.CountUsersByUsername(ctx, req.Username)
+	if err != nil {
+		return model.User{}, err
+	}
+	if count > 0 {
+		return model.User{}, errors.New(usernameExists)
+	}
+
+	emailCount, err := repository.CountUsersByEmail(ctx, req.Email)
+	if err != nil {
+		return model.User{}, err
+	}
+	if emailCount > 0 {
+		return model.User{}, errors.New(emailExists)
+	}
+
+	newUser := model.User{
+		ID:          idgen.NextUint64ID(),
+		Username:    req.Username,
+		Nickname:    req.Nickname,
+		Email:       req.Email,
+		IsActive:    req.IsActive,
+		IsAdmin:     req.IsAdmin,
+		LastLoginAt: time.Time{},
+	}
+	if newUser.Nickname == "" {
+		newUser.Nickname = req.Username
+	}
+	if err := newUser.SetEncryptedPassword(req.Password); err != nil {
+		return model.User{}, err
+	}
+	if err := repository.CreateUser(ctx, &newUser); err != nil {
+		return model.User{}, err
+	}
+	return newUser, nil
+}

internal/apps/admin/user/routers.go

@@ -0,0 +1,288 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+import (
+	"errors"
+	"net/http"
+	"strconv"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+// minPasswordLength 密码最小长度
+const minPasswordLength = 8
+
+// listUsersRequest 用户列表查询请求
+type listUsersRequest struct {
+	Page     int     `form:"page" binding:"min=1"`
+	PageSize int     `form:"page_size" binding:"min=1,max=100"`
+	UserID   *uint64 `form:"user_id" binding:"omitempty,gt=0"`
+	Username string  `form:"username"`
+}
+
+type user struct {
+	ID          uint64    `json:"id,string"`
+	Username    string    `json:"username"`
+	Nickname    string    `json:"nickname"`
+	Email       string    `json:"email"`
+	AvatarURL   string    `json:"avatar_url"`
+	IsActive    bool      `json:"is_active"`
+	IsAdmin     bool      `json:"is_admin"`
+	Bio         string    `json:"bio"`
+	Phone       string    `json:"phone"`
+	Gender      string    `json:"gender"`
+	Website     string    `json:"website"`
+	Location    string    `json:"location"`
+	LastLoginAt time.Time `json:"last_login_at"`
+	CreatedAt   time.Time `json:"created_at"`
+	UpdatedAt   time.Time `json:"updated_at"`
+}
+
+// listUsersResponse 用户列表响应
+type listUsersResponse struct {
+	Users []user `json:"users"`
+	Total int64  `json:"total"`
+}
+
+func parseUserID(c *gin.Context) (uint64, bool) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil || id == 0 {
+		response.AbortBadRequest(c, userNotFound)
+		return 0, false
+	}
+	return id, true
+}
+
+func toUser(u model.User) user {
+	return user{
+		ID:          u.ID,
+		Username:    u.Username,
+		Nickname:    u.Nickname,
+		Email:       u.Email,
+		AvatarURL:   u.AvatarURL,
+		IsActive:    u.IsActive,
+		IsAdmin:     u.IsAdmin,
+		Bio:         u.Bio,
+		Phone:       u.Phone,
+		Gender:      u.Gender,
+		Website:     u.Website,
+		Location:    u.Location,
+		LastLoginAt: u.LastLoginAt,
+		CreatedAt:   u.CreatedAt,
+		UpdatedAt:   u.UpdatedAt,
+	}
+}
+
+func abortUserLogicError(c *gin.Context, err error, notFoundMsg string, forbiddenMsgs, badRequestMsgs []string) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		response.AbortNotFound(c, notFoundMsg)
+		return true
+	}
+	msg := err.Error()
+	for _, m := range badRequestMsgs {
+		if msg == m {
+			response.AbortBadRequest(c, msg)
+			return true
+		}
+	}
+	for _, m := range forbiddenMsgs {
+		if msg == m {
+			response.AbortForbidden(c, msg)
+			return true
+		}
+	}
+	response.AbortInternal(c, msg)
+	return true
+}
+
+// ListUsers 获取用户列表
+// @Summary 获取用户列表
+// @Description 分页返回用户列表，支持按用户 ID 和用户名筛选，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param request query listUsersRequest true "查询参数"
+// @Success 200 {object} response.Any{data=user.listUsersResponse} "用户列表"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/users [get]
+func ListUsers(c *gin.Context) {
+	var req listUsersRequest
+	if err := c.ShouldBindQuery(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	total, modelUsers, err := listUsers(c.Request.Context(), req)
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	users := make([]user, 0, len(modelUsers))
+	for _, modelUser := range modelUsers {
+		users = append(users, toUser(modelUser))
+	}
+
+	c.JSON(http.StatusOK, response.OK(listUsersResponse{
+		Users: users,
+		Total: total,
+	}))
+}
+
+// GetUser 获取用户详情
+// @Summary 获取用户详情
+// @Description 返回指定用户的完整个人资料和系统状态，需要管理员权限，不返回密码等敏感字段
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "用户 ID"
+// @Success 200 {object} response.Any{data=user.user} "用户详情"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 404 {object} response.Any "用户不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/users/{id} [get]
+func GetUser(c *gin.Context) {
+	id, ok := parseUserID(c)
+	if !ok {
+		return
+	}
+
+	targetUser, err := getUserDetail(c.Request.Context(), id)
+	if abortUserLogicError(c, err, userNotFound, nil, nil) {
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(toUser(targetUser)))
+}
+
+// updateUserStatusRequest 更新用户状态请求
+type updateUserStatusRequest struct {
+	IsActive bool `json:"is_active"`
+}
+
+// UpdateUserStatus 更新用户状态（启用/禁用）
+// @Summary 更新用户状态
+// @Description 启用或禁用指定用户，管理员账号无法被禁用，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "用户 ID"
+// @Param request body updateUserStatusRequest true "状态参数"
+// @Success 200 {object} response.Any{data=string} "更新成功"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限或尝试禁用管理员"
+// @Failure 404 {object} response.Any "用户不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/users/{id}/status [put]
+func UpdateUserStatus(c *gin.Context) {
+	var req updateUserStatusRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	id, ok := parseUserID(c)
+	if !ok {
+		return
+	}
+
+	if err := updateUserStatus(c.Request.Context(), id, req.IsActive); err != nil {
+		if abortUserLogicError(c, err, userNotFound, []string{cannotDisable}, nil) {
+			return
+		}
+		response.AbortInternal(c, updateUserFailed)
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// DeleteUser 删除用户
+// @Summary 删除用户
+// @Description 删除指定非管理员用户，需要管理员权限，不能删除当前登录用户
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "用户 ID"
+// @Success 200 {object} response.Any{data=string} "删除成功"
+// @Failure 400 {object} response.Any "参数错误"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限、尝试删除管理员或当前用户"
+// @Failure 404 {object} response.Any "用户不存在"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/users/{id} [delete]
+func DeleteUser(c *gin.Context) {
+	id, ok := parseUserID(c)
+	if !ok {
+		return
+	}
+
+	currUser, _ := oauth.GetFromContext[*model.User](c, oauth.UserObjKey)
+	if err := deleteUser(c.Request.Context(), currUser.ID, id); err != nil {
+		if abortUserLogicError(c, err, userNotFound, []string{cannotDelete, cannotDeleteSelf}, nil) {
+			return
+		}
+		response.AbortInternal(c, deleteUserFailed)
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// createUserRequest 创建用户请求
+type createUserRequest struct {
+	Username string `json:"username" binding:"required,min=3,max=64"`
+	Password string `json:"password" binding:"required,min=8,max=64"`
+	Nickname string `json:"nickname" binding:"omitempty,max=64"`
+	Email    string `json:"email" binding:"required,email,max=255"`
+	IsActive bool   `json:"is_active"`
+	IsAdmin  bool   `json:"is_admin"`
+}
+
+// CreateUser 创建用户
+// @Summary 创建用户
+// @Description 创建一个本地密码登录的新用户，需要管理员权限
+// @Tags admin
+// @Accept json
+// @Produce json
+// @Security SessionCookie
+// @Param request body user.createUserRequest true "创建用户参数"
+// @Success 200 {object} response.Any{data=user.user} "创建成功"
+// @Failure 400 {object} response.Any "参数错误或用户名已存在"
+// @Failure 401 {object} response.Any "未登录"
+// @Failure 403 {object} response.Any "无管理员权限"
+// @Failure 500 {object} response.Any "内部错误"
+// @Router /api/v1/admin/users [post]
+func CreateUser(c *gin.Context) {
+	var req createUserRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	newUser, err := createUser(c.Request.Context(), req)
+	if abortUserLogicError(c, err, "", nil, []string{usernameRequired, emailRequired, passwordTooShort, usernameExists, emailExists}) {
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(toUser(newUser)))
+}

internal/apps/admin/user/routers_test.go

@@ -0,0 +1,582 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+func setupTestRouter(authUser *model.User) *gin.Engine {
+	r := testhelper.NewTestGinEngine()
+	adminGroup := r.Group("/api/v1/admin")
+
+	// Mock authentication middleware
+	adminGroup.Use(func(c *gin.Context) {
+		if authUser != nil {
+			oauth.SetToContext(c, oauth.UserObjKey, authUser)
+		}
+		c.Next()
+	})
+
+	adminGroup.GET("/users", ListUsers)
+	adminGroup.POST("/users", CreateUser)
+	adminGroup.GET("/users/:id", GetUser)
+	adminGroup.PUT("/users/:id/status", UpdateUserStatus)
+	adminGroup.DELETE("/users/:id", DeleteUser)
+	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,
+			LastLoginAt: time.Now(),
+		},
+		{
+			ID:          1002,
+			Username:    "bob",
+			Nickname:    "Bob Nickname",
+			IsActive:    true,
+			IsAdmin:     false,
+			LastLoginAt: time.Now(),
+		},
+		{
+			ID:          1003,
+			Username:    "charlie",
+			Nickname:    "Charlie Nickname",
+			IsActive:    false,
+			IsAdmin:     true,
+			LastLoginAt: time.Now(),
+		},
+	}
+
+	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}
+	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 response.Any
+		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 ASC
+		if listResp.Users[0].ID != 1001 || listResp.Users[1].ID != 1002 {
+			t.Errorf("expected ordered ASC, 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 response.Any
+		_ = 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 response.Any
+		_ = 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 TestGetUser(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	targetUser := model.User{
+		ID:        1001,
+		Username:  "alice",
+		Password:  "secret-hash",
+		Nickname:  "Alice Nickname",
+		Email:     "alice@example.com",
+		AvatarURL: "https://example.com/avatar.png",
+		IsActive:  true,
+		IsAdmin:   false,
+		Bio:       "hello",
+		Phone:     "123456",
+		Gender:    "female",
+		Website:   "https://example.com",
+		Location:  "Shanghai",
+	}
+	if err := dbConn.Create(&targetUser).Error; err != nil {
+		t.Fatalf("failed to seed user: %v", err)
+	}
+
+	adminUser := &model.User{ID: 1003, Username: "charlie", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("get full user profile", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/users/1001", 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())
+		}
+
+		var resp response.Any
+		if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("failed to parse response: %v", err)
+		}
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var resUser user
+		if err := json.Unmarshal(dataBytes, &resUser); err != nil {
+			t.Fatalf("failed to parse response data: %v", err)
+		}
+
+		if resUser.Email != targetUser.Email || resUser.Bio != targetUser.Bio || resUser.Phone != targetUser.Phone ||
+			resUser.Gender != targetUser.Gender || resUser.Website != targetUser.Website || resUser.Location != targetUser.Location {
+			t.Errorf("profile fields were not returned correctly: %+v", resUser)
+		}
+		if bytes.Contains(dataBytes, []byte("secret-hash")) {
+			t.Error("response should not include password")
+		}
+	})
+
+	t.Run("get non-existent user", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/users/9999", nil)
+		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())
+		}
+	})
+}
+
+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,
+	}
+	adminUser := model.User{
+		ID:       1002,
+		Username: "bob",
+		IsActive: true,
+		IsAdmin:  true,
+	}
+
+	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 response.Any
+		_ = 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())
+		}
+	})
+}
+
+func TestCreateUser(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1003, Username: "charlie", IsAdmin: true}
+	router := setupTestRouter(adminUser)
+
+	t.Run("create user successfully", func(t *testing.T) {
+		payload := createUserRequest{
+			Username: "newuser",
+			Password: "newpassword123",
+			Nickname: "New Nickname",
+			Email:    "newuser@example.com",
+			IsActive: true,
+			IsAdmin:  false,
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/users", 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 resp response.Any
+		if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("failed to parse response: %v", err)
+		}
+
+		if resp.ErrorMsg != "" {
+			t.Errorf("expected empty error message, got '%s'", resp.ErrorMsg)
+		}
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var resUser user
+		if err := json.Unmarshal(dataBytes, &resUser); err != nil {
+			t.Fatalf("failed to parse response data: %v", err)
+		}
+
+		if resUser.Username != "newuser" || resUser.Nickname != "New Nickname" || !resUser.IsActive || resUser.IsAdmin {
+			t.Errorf("unexpected user values: %+v", resUser)
+		}
+
+		// Verify in DB
+		var dbUser model.User
+		if err := dbConn.Where("username = ?", "newuser").First(&dbUser).Error; err != nil {
+			t.Fatalf("failed to find user in db: %v", err)
+		}
+		if dbUser.Email != "newuser@example.com" {
+			t.Errorf("expected email 'newuser@example.com', got '%s'", dbUser.Email)
+		}
+		if !dbUser.CheckPassword("newpassword123") {
+			t.Error("password was not hashed correctly")
+		}
+	})
+
+	t.Run("create user with duplicate username", func(t *testing.T) {
+		// Create the first user
+		existing := model.User{
+			ID:       2001,
+			Username: "dupuser",
+			Nickname: "Dup User",
+			Email:    "dupuser@example.com",
+		}
+		dbConn.Create(&existing)
+
+		payload := createUserRequest{
+			Username: "dupuser",
+			Password: "password123",
+			Nickname: "Another Nick",
+			Email:    "another@example.com",
+			IsActive: true,
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/users", 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. Body: %s", w.Code, w.Body.String())
+		}
+
+		var resp response.Any
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+		if resp.ErrorMsg != usernameExists {
+			t.Errorf("expected error '%s', got '%s'", usernameExists, resp.ErrorMsg)
+		}
+	})
+
+	t.Run("create user with duplicate email", func(t *testing.T) {
+		existing := model.User{
+			ID:       2002,
+			Username: "existingemail",
+			Nickname: "Existing Email",
+			Email:    "dupemail@example.com",
+		}
+		dbConn.Create(&existing)
+
+		payload := createUserRequest{
+			Username: "newuser2",
+			Password: "password123",
+			Nickname: "New User 2",
+			Email:    "dupemail@example.com",
+			IsActive: true,
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/users", 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. Body: %s", w.Code, w.Body.String())
+		}
+
+		var resp response.Any
+		_ = json.Unmarshal(w.Body.Bytes(), &resp)
+		if resp.ErrorMsg != emailExists {
+			t.Errorf("expected error '%s', got '%s'", emailExists, resp.ErrorMsg)
+		}
+	})
+
+	t.Run("validation error - password too short", func(t *testing.T) {
+		payload := createUserRequest{
+			Username: "shortpass",
+			Password: "123",
+			Email:    "shortpass@example.com",
+			IsActive: true,
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/users", 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. Body: %s", w.Code, w.Body.String())
+		}
+	})
+
+	t.Run("validation error - invalid email format", func(t *testing.T) {
+		payload := map[string]interface{}{
+			"username":  "bademail",
+			"password":  "password123",
+			"email":     "not-an-email",
+			"is_active": true,
+		}
+		body, _ := json.Marshal(payload)
+		req, _ := http.NewRequest("POST", "/api/v1/admin/users", 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. Body: %s", w.Code, w.Body.String())
+		}
+	})
+}
+
+func TestDeleteUser(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	if err := dbConn.AutoMigrate(&model.AccessToken{}, &model.ExternalAccount{}); err != nil {
+		t.Fatalf("failed to migrate delete-related tables: %v", err)
+	}
+
+	regularUser := model.User{
+		ID:       1001,
+		Username: "alice",
+		IsActive: true,
+		IsAdmin:  false,
+	}
+	adminUser := model.User{
+		ID:       1002,
+		Username: "bob",
+		IsActive: true,
+		IsAdmin:  true,
+	}
+	selfUser := model.User{
+		ID:       1003,
+		Username: "charlie",
+		IsActive: true,
+		IsAdmin:  false,
+	}
+
+	if err := dbConn.Create(&regularUser).Error; err != nil {
+		t.Fatalf("failed to seed regular user: %v", err)
+	}
+	if err := dbConn.Create(&adminUser).Error; err != nil {
+		t.Fatalf("failed to seed admin user: %v", err)
+	}
+	if err := dbConn.Create(&selfUser).Error; err != nil {
+		t.Fatalf("failed to seed self user: %v", err)
+	}
+	if err := dbConn.Create(&model.AccessToken{
+		UserID:      regularUser.ID,
+		Name:        "api",
+		TokenHash:   "hash-for-delete-user-test",
+		MaskedToken: "at_****test",
+	}).Error; err != nil {
+		t.Fatalf("failed to seed access token: %v", err)
+	}
+	if err := dbConn.Create(&model.ExternalAccount{
+		ID:           5001,
+		AuthSourceID: 1,
+		UserID:       regularUser.ID,
+		ExternalID:   "external-alice",
+	}).Error; err != nil {
+		t.Fatalf("failed to seed external account: %v", err)
+	}
+
+	router := setupTestRouter(&selfUser)
+
+	t.Run("delete regular user successfully", func(t *testing.T) {
+		req, _ := http.NewRequest("DELETE", "/api/v1/admin/users/1001", 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())
+		}
+
+		var count int64
+		if err := dbConn.Model(&model.User{}).Where("id = ?", 1001).Count(&count).Error; err != nil {
+			t.Fatalf("failed to count deleted user: %v", err)
+		}
+		if count != 0 {
+			t.Errorf("expected deleted user count 0, got %d", count)
+		}
+
+		if err := dbConn.Model(&model.AccessToken{}).Where("user_id = ?", 1001).Count(&count).Error; err != nil {
+			t.Fatalf("failed to count deleted access tokens: %v", err)
+		}
+		if count != 0 {
+			t.Errorf("expected deleted access token count 0, got %d", count)
+		}
+
+		if err := dbConn.Model(&model.ExternalAccount{}).Where("user_id = ?", 1001).Count(&count).Error; err != nil {
+			t.Fatalf("failed to count deleted external accounts: %v", err)
+		}
+		if count != 0 {
+			t.Errorf("expected deleted external account count 0, got %d", count)
+		}
+	})
+
+	t.Run("cannot delete admin user", func(t *testing.T) {
+		req, _ := http.NewRequest("DELETE", "/api/v1/admin/users/1002", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusForbidden {
+			t.Fatalf("expected 403 Forbidden, got %d. Body: %s", w.Code, w.Body.String())
+		}
+	})
+
+	t.Run("cannot delete current user", func(t *testing.T) {
+		req, _ := http.NewRequest("DELETE", "/api/v1/admin/users/1003", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		if w.Code != http.StatusForbidden {
+			t.Fatalf("expected 403 Forbidden, got %d. Body: %s", w.Code, w.Body.String())
+		}
+	})
+
+	t.Run("delete non-existent user", func(t *testing.T) {
+		req, _ := http.NewRequest("DELETE", "/api/v1/admin/users/9999", nil)
+		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())
+		}
+	})
+}