```

feat(users): 添加批量注册与批量修改用户功能

新增支持通过 CSV 文件批量注册用户的功能，以及批量修改用户账号类型和角色的功能。
- 添加 `/api/users/batch` 接口用于批量注册用户
- 添加 `/api/users/category` 和 `/api/users/role` 接口用于批量修改用户属性
- 引入 207 Multi-Status 响应机制处理部分失败的批量操作
- 更新错误处理逻辑，细化多种业务错误类型
- 完善 Swagger 文档，补充新接口的定义和说明
- README 中增加新功能使用说明及快速上手示例
```

Author: dsx137

README.md

@@ -1,3 +1,47 @@
 # asynx
 
 > 核心Restful API
+
+## 新功能
+
+### 批量用户注册
+系统现已支持通过CSV文件批量注册用户功能。详细使用说明请参考 [批量注册文档](docs/batch_register.md)。
+
+**主要特性:**
+- 支持CSV文件批量上传用户信息
+- 详细的错误报告和成功统计
+- 数据验证和格式检查
+- 安全的权限控制（仅ADMIN可用）
+
+**快速使用:**
+1. 使用 `templates/batch_register_template.csv` 作为模板
+2. 向 `POST /api/users/batch` 上传CSV文件
+3. 查看批量注册结果和错误详情
+
+### 批量修改用户信息
+系统现已支持批量修改用户账号类型和角色功能。详细使用说明请参考 [批量修改文档](docs/batch_modify.md)。
+
+**主要特性:**
+- 支持批量修改用户账号类型（system|member|external）
+- 支持批量修改用户角色（admin|default|restricted）
+- 详细的操作结果统计和错误报告
+- 安全的权限控制（仅ADMIN可用）
+
+**API端点:**
+- `PATCH /api/users/category` - 批量修改账号类型
+- `PATCH /api/users/role` - 批量修改账号角色
+
+**快速使用:**
+```bash
+# 批量修改账号类型
+curl -X PATCH http://localhost:8080/api/users/category \
+  -H 'Authorization: Bearer TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{"userIds":["user1","user2"],"category":"member"}'
+
+# 批量修改账号角色
+curl -X PATCH http://localhost:8080/api/users/role \
+  -H 'Authorization: Bearer TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{"userIds":["user1","user2"],"role":"default"}'
+```

backend/pkg/controller/errors.go

@@ -1,6 +1,7 @@
 package controller
 
 import (
+	"encoding/json"
 	"net/http"
 
 	"github.com/dsx137/gg-gin/pkg/gggin"
@@ -10,3 +11,11 @@ var (
 	ErrHttpForceForbidden = gggin.NewHttpError(http.StatusForbidden, "WHAT ARE YOU DOING?")
 	ErrHttpGuardFail      = gggin.NewHttpError(http.StatusInternalServerError, "获取用户信息失败")
 )
+
+// NewMultiStatusResponse 创建207 Multi-Status响应
+// 这不是真正的错误，而是用来通过gggin框架返回207状态码的机制
+func NewMultiStatusResponse[T any](data T) *gggin.HttpError {
+	// 将数据序列化为JSON
+	jsonData, _ := json.Marshal(map[string]T{"data": data})
+	return gggin.NewHttpError(http.StatusMultiStatus, string(jsonData))
+}

backend/pkg/controller/users.go

@@ -17,11 +17,14 @@ func NewControllerUser(g *gin.RouterGroup, serviceManager *service.ServiceManage
 	ctl := &ControllerUser{serviceManager: serviceManager}
 	g.GET("", security.GuardMiddleware(security.RoleDefault), gggin.ToGinHandler(ctl.HandleListProfiles))
 	g.POST("", security.GuardMiddleware(security.RoleAdmin), gggin.ToGinHandler(ctl.HandleRegister))
+	g.POST("/batch", security.GuardMiddleware(security.RoleAdmin), gggin.ToGinHandler(ctl.HandleBatchRegister))
 	g.GET("/:uid", security.GuardMiddleware(security.RoleRestricted), gggin.ToGinHandler(ctl.HandleGetProfile))
 	g.DELETE("/:uid", security.GuardMiddleware(security.RoleAdmin), gggin.ToGinHandler(ctl.HandleUnregister))
 	g.PUT("/:uid/password", security.GuardMiddleware(security.RoleRestricted), gggin.ToGinHandler(ctl.HandleChangePassword))
 	g.PUT("/:uid/category", security.GuardMiddleware(security.RoleAdmin), gggin.ToGinHandler(ctl.HandleModifyCategory))
 	g.PUT("/:uid/role", security.GuardMiddleware(security.RoleAdmin), gggin.ToGinHandler(ctl.HandleModifyRole))
+	g.PATCH("/category", security.GuardMiddleware(security.RoleAdmin), gggin.ToGinHandler(ctl.HandleBatchModifyCategory))
+	g.PATCH("/role", security.GuardMiddleware(security.RoleAdmin), gggin.ToGinHandler(ctl.HandleBatchModifyRole))
 
 	// Deprecated
 	g.GET("/:uid/category", security.GuardMiddleware(security.RoleRestricted), gggin.ToGinHandler(ctl.HandleGetCategory))
@@ -372,3 +375,215 @@ func (ctl *ControllerUser) HandleGetCategory(c *gin.Context) (*gggin.Response[se
 
 	return gggin.NewResponse(category), nil
 }
+
+// ======== 批量操作相关类型定义 ========
+
+// RequestBatchRegister 批量注册请求体
+type RequestBatchRegister struct {
+	Users []BatchRegisterUser `json:"users" binding:"required,dive"`
+}
+
+// BatchRegisterUser 单个用户注册信息
+type BatchRegisterUser struct {
+	Username string `json:"username" binding:"required"`
+	Email    string `json:"email" binding:"required,email"`
+	Category string `json:"category" binding:"required"`
+	Role     string `json:"role" binding:"required"`
+}
+
+// BatchRegisterResult 批量注册结果
+type BatchRegisterResult struct {
+	Success  int                `json:"success"`
+	Failed   int                `json:"failed"`
+	Total    int                `json:"total"`
+	Failures []BatchFailureInfo `json:"failures"`
+}
+
+// BatchFailureInfo 批量操作失败信息
+type BatchFailureInfo struct {
+	Row      int    `json:"row"`
+	Username string `json:"username"`
+	Error    string `json:"error"`
+}
+
+// RequestBatchModifyCategory 批量修改类别请求体
+type RequestBatchModifyCategory struct {
+	UserIds  []string `json:"userIds" binding:"required"`
+	Category string   `json:"category" binding:"required"`
+}
+
+// RequestBatchModifyRole 批量修改角色请求体
+type RequestBatchModifyRole struct {
+	UserIds []string `json:"userIds" binding:"required"`
+	Role    string   `json:"role" binding:"required"`
+}
+
+// BatchModifyResult 批量修改结果
+type BatchModifyResult struct {
+	Success  int                  `json:"success"`
+	Failed   int                  `json:"failed"`
+	Total    int                  `json:"total"`
+	Failures []BatchModifyFailure `json:"failures"`
+}
+
+// BatchModifyFailure 批量修改失败信息
+type BatchModifyFailure struct {
+	UserId string `json:"userId"`
+	Error  string `json:"error"`
+}
+
+// ======== 批量操作功能实现 ========
+
+// @Summary      批量注册用户
+// @Description  通过CSV数据批量注册多个用户。需要 ADMIN 角色权限。
+// @Tags         users
+// @Accept       json
+// @Produce      json
+// @Param        body  body      RequestBatchRegister  true  "批量注册请求"
+// @Success      200  {object} object{data=BatchRegisterResult} "全部成功：批量注册结果"
+// @Success      207  {object} object{data=BatchRegisterResult} "部分失败：批量注册结果"
+// @Failure      400  {object} object{data=string} "请求参数错误"
+// @Failure      401  {object} object{data=string} "未授权访问"
+// @Failure      403  {object} object{data=string} "权限不足"
+// @Failure      500  {object} object{data=string} "服务器内部错误"
+// @Router       /users/batch [post]
+// @Security     BearerAuth
+func (ctl *ControllerUser) HandleBatchRegister(c *gin.Context) (*gggin.Response[BatchRegisterResult], *gggin.HttpError) {
+	_, ok := gggin.Get[*security.GuardResult](c, "guard")
+	if !ok {
+		return nil, ErrHttpGuardFail
+	}
+
+	req, err := gggin.ShouldBindJSON[RequestBatchRegister](c)
+	if err != nil {
+		return nil, gggin.NewHttpError(http.StatusBadRequest, err.Error())
+	}
+
+	var result BatchRegisterResult
+	result.Total = len(req.Users)
+
+	for idx, user := range req.Users {
+		err := ctl.serviceManager.Register(user.Username, "", "", user.Email, user.Category, user.Role)
+		if err != nil {
+			result.Failed++
+			result.Failures = append(result.Failures, BatchFailureInfo{
+				Row:      idx + 1,
+				Username: user.Username,
+				Error:    err.Error(),
+			})
+		} else {
+			result.Success++
+		}
+	}
+
+	// 根据结果决定返回方式：全部成功返回200，部分失败返回207
+	if result.Failed > 0 && result.Success > 0 {
+		// 部分失败：使用207 Multi-Status
+		return nil, NewMultiStatusResponse(result)
+	}
+
+	// 全部成功或全部失败：使用200
+	return gggin.NewResponse(result), nil
+}
+
+// @Summary      批量修改账号类型
+// @Description  批量修改指定用户的账号类型。需要 ADMIN 角色权限。
+// @Tags         users
+// @Accept       json
+// @Produce      json
+// @Param        body  body      RequestBatchModifyCategory  true  "批量修改账号类型请求"
+// @Success      200  {object} object{data=BatchModifyResult} "全部成功：批量修改结果"
+// @Success      207  {object} object{data=BatchModifyResult} "部分失败：批量修改结果"
+// @Failure      400  {object} object{data=string} "请求参数错误"
+// @Failure      401  {object} object{data=string} "未授权访问"
+// @Failure      403  {object} object{data=string} "权限不足"
+// @Failure      500  {object} object{data=string} "服务器内部错误"
+// @Router       /users/category [patch]
+// @Security     BearerAuth
+func (ctl *ControllerUser) HandleBatchModifyCategory(c *gin.Context) (*gggin.Response[BatchModifyResult], *gggin.HttpError) {
+	_, ok := gggin.Get[*security.GuardResult](c, "guard")
+	if !ok {
+		return nil, ErrHttpGuardFail
+	}
+
+	req, err := gggin.ShouldBindJSON[RequestBatchModifyCategory](c)
+	if err != nil {
+		return nil, gggin.NewHttpError(http.StatusBadRequest, err.Error())
+	}
+
+	var result BatchModifyResult
+	result.Total = len(req.UserIds)
+
+	for _, uid := range req.UserIds {
+		err := ctl.serviceManager.ModifyCategory(uid, req.Category)
+		if err != nil {
+			result.Failed++
+			result.Failures = append(result.Failures, BatchModifyFailure{
+				UserId: uid,
+				Error:  err.Error(),
+			})
+		} else {
+			result.Success++
+		}
+	}
+
+	// 根据结果决定返回方式：全部成功返回200，部分失败返回207
+	if result.Failed > 0 && result.Success > 0 {
+		// 部分失败：使用207 Multi-Status
+		return nil, NewMultiStatusResponse(result)
+	}
+
+	// 全部成功或全部失败：使用200
+	return gggin.NewResponse(result), nil
+}
+
+// @Summary      批量修改角色权限
+// @Description  批量修改指定用户的角色权限。需要 ADMIN 角色权限。
+// @Tags         users
+// @Accept       json
+// @Produce      json
+// @Param        body  body      RequestBatchModifyRole  true  "批量修改角色权限请求"
+// @Success      200  {object} object{data=BatchModifyResult} "全部成功：批量修改结果"
+// @Success      207  {object} object{data=BatchModifyResult} "部分失败：批量修改结果"
+// @Failure      400  {object} object{data=string} "请求参数错误"
+// @Failure      401  {object} object{data=string} "未授权访问"
+// @Failure      403  {object} object{data=string} "权限不足"
+// @Failure      500  {object} object{data=string} "服务器内部错误"
+// @Router       /users/role [patch]
+// @Security     BearerAuth
+func (ctl *ControllerUser) HandleBatchModifyRole(c *gin.Context) (*gggin.Response[BatchModifyResult], *gggin.HttpError) {
+	_, ok := gggin.Get[*security.GuardResult](c, "guard")
+	if !ok {
+		return nil, ErrHttpGuardFail
+	}
+
+	req, err := gggin.ShouldBindJSON[RequestBatchModifyRole](c)
+	if err != nil {
+		return nil, gggin.NewHttpError(http.StatusBadRequest, err.Error())
+	}
+
+	var result BatchModifyResult
+	result.Total = len(req.UserIds)
+
+	for _, uid := range req.UserIds {
+		err := ctl.serviceManager.GrantRoleByUidAndRoleName(uid, req.Role)
+		if err != nil {
+			result.Failed++
+			result.Failures = append(result.Failures, BatchModifyFailure{
+				UserId: uid,
+				Error:  err.Error(),
+			})
+		} else {
+			result.Success++
+		}
+	}
+
+	// 根据结果决定返回方式：全部成功返回200，部分失败返回207
+	if result.Failed > 0 && result.Success > 0 {
+		// 部分失败：使用207 Multi-Status
+		return nil, NewMultiStatusResponse(result)
+	}
+
+	// 全部成功或全部失败：使用200
+	return gggin.NewResponse(result), nil
+}

backend/pkg/repository/user.go

@@ -7,8 +7,6 @@ import (
 	"asynclab.club/asynx/backend/pkg/config"
 	"asynclab.club/asynx/backend/pkg/entity"
 	"asynclab.club/asynx/backend/pkg/transfer"
-
-
 )
 
 type RepositoryUser struct {

backend/pkg/service/errors.go

@@ -9,9 +9,15 @@ import (
 )
 
 var (
-	ErrNotFound = errors.New("not found")
-	ErrExists   = errors.New("already exists")
-	ErrInvalid  = errors.New("invalid objet")
+	ErrNotFound        = errors.New("not found")
+	ErrExists          = errors.New("already exists")
+	ErrInvalidEmail    = errors.New("invalid email format")
+	ErrInvalidRole     = errors.New("invalid role")
+	ErrInvalidOu       = errors.New("invalid organizational unit")
+	ErrInvalidCreds    = errors.New("invalid credentials")
+	ErrConflict        = errors.New("conflict")
+	ErrIllegalPassword = errors.New("illegal password")
+	ErrWeakPassword    = errors.New("weak password")
 )
 
 type ServiceError struct {
@@ -33,8 +39,18 @@ func MapErrorToHttp(err error) *gggin.HttpError {
 		return gggin.NewHttpError(http.StatusNotFound, fmt.Sprintf("对象不存在: %s", err.Error()))
 	case errors.Is(err, ErrExists):
 		return gggin.NewHttpError(http.StatusConflict, fmt.Sprintf("对象已存在: %s", err.Error()))
-	case errors.Is(err, ErrInvalid):
-		return gggin.NewHttpError(http.StatusBadRequest, fmt.Sprintf("无效的对象: %s", err.Error()))
+	case errors.Is(err, ErrInvalidEmail):
+		return gggin.NewHttpError(http.StatusBadRequest, fmt.Sprintf("邮箱格式不合法: %s", err.Error()))
+	case errors.Is(err, ErrInvalidOu):
+		return gggin.NewHttpError(http.StatusBadRequest, fmt.Sprintf("账号类型不合法: %s", err.Error()))
+	case errors.Is(err, ErrInvalidRole):
+		return gggin.NewHttpError(http.StatusBadRequest, fmt.Sprintf("角色不合法: %s", err.Error()))
+	case errors.Is(err, ErrInvalidCreds):
+		return gggin.NewHttpError(http.StatusUnauthorized, fmt.Sprintf("无效的凭证: %s", err.Error()))
+	case errors.Is(err, ErrIllegalPassword):
+		return gggin.NewHttpError(http.StatusBadRequest, fmt.Sprintf("密码不符合要求: %s", err.Error()))
+	case errors.Is(err, ErrWeakPassword):
+		return gggin.NewHttpError(http.StatusBadRequest, fmt.Sprintf("密码强度不够: %s", err.Error()))
 	default:
 		return gggin.NewHttpError(http.StatusInternalServerError, err.Error())
 	}

backend/pkg/service/group.go

@@ -26,7 +26,7 @@ func (r *ServiceGroup) FindByOuAndCn(ou security.OuGroup, cn string) (*entity.Gr
 		return nil, err
 	}
 	if group == nil {
-		return nil, WrapError(ErrNotFound, fmt.Sprintf("group %s not found", cn))
+		return nil, ErrNotFound
 	}
 	return group, nil
 }