实施业务用户组成员管理

internal/model/dto/business_user_group_dto.go

@@ -46,6 +46,7 @@ type BusinessUserGroupResponse struct {
 	Sort             int64  `json:"sort" description:"排序值"`
 	Enabled          bool   `json:"enabled" description:"是否启用；停用后不得新增成员，也不得作为批量目标"`
 	Remark           string `json:"remark" description:"备注"`
+	MemberCount      int64  `json:"member_count" description:"当前保留成员关系数量，包含禁用或已删除账号"`
 	CreatedAt        string `json:"created_at" description:"创建时间"`
 	UpdatedAt        string `json:"updated_at" description:"更新时间"`
 }
@@ -58,20 +59,92 @@ type BusinessUserGroupPageResult struct {
 	Size  int                          `json:"size" description:"每页数量"`
 }
 
-// SetBusinessUserGroupMembersRequest 批量设置平台用户业务用户组归属请求。
-// 设置直接替换每个账号的原归属；任一账号不是启用平台用户或目标组未启用时整批不修改。
-type SetBusinessUserGroupMembersRequest struct {
-	AccountIDs []uint `json:"account_ids" validate:"required,min=1,dive,min=1" required:"true" description:"平台用户账号ID列表，至少一个；每个账号必须是启用平台用户"`
+// BusinessUserGroupMemberListRequest 业务用户组成员分页查询请求。
+type BusinessUserGroupMemberListRequest struct {
+	Page          int    `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码，默认 1"`
+	PageSize      int    `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量，默认 20，最大 100"`
+	Keyword       string `json:"keyword" query:"keyword" validate:"omitempty,max=100" maxLength:"100" description:"按用户名或手机号模糊搜索，最多 100 字符"`
+	AccountStatus string `json:"account_status" query:"account_status" validate:"omitempty,oneof=enabled disabled deleted" enum:"enabled,disabled,deleted" description:"账号状态筛选 (enabled:启用, disabled:禁用, deleted:已删除)"`
 }
 
-// ClearBusinessUserGroupMembersRequest 批量清空平台用户业务用户组归属请求。
-type ClearBusinessUserGroupMembersRequest struct {
-	AccountIDs []uint `json:"account_ids" validate:"required,min=1,dive,min=1" required:"true" description:"平台用户账号ID列表，至少一个；每个账号必须是启用平台用户"`
+// BusinessUserGroupMemberListParams 业务用户组成员分页查询路径与查询参数。
+type BusinessUserGroupMemberListParams struct {
+	BusinessUserGroupMemberRequest
+	BusinessUserGroupMemberListRequest
+}
+
+// BusinessUserGroupMemberResponse 业务用户组成员响应。
+type BusinessUserGroupMemberResponse struct {
+	AccountID           uint   `json:"account_id" description:"平台用户账号ID"`
+	Username            string `json:"username" description:"平台用户用户名"`
+	Phone               string `json:"phone" description:"脱敏手机号，仅保留前3位和后4位"`
+	Enabled             bool   `json:"enabled" description:"账号是否启用"`
+	StatusName          string `json:"status_name" description:"账号启停状态名称"`
+	Deleted             bool   `json:"deleted" description:"账号是否已软删除"`
+	MemberCreatedAt     string `json:"member_created_at" description:"成员关系创建时间"`
+	CurrentGroupID      uint   `json:"current_group_id" description:"当前业务用户组ID"`
+	CurrentGroupCode    string `json:"current_group_code" description:"当前业务用户组稳定编码"`
+	CurrentGroupName    string `json:"current_group_name" description:"当前业务用户组名称"`
+	CurrentGroupEnabled bool   `json:"current_group_enabled" description:"当前业务用户组是否启用"`
+}
+
+// BusinessUserGroupMemberPageResult 业务用户组成员分页响应。
+type BusinessUserGroupMemberPageResult struct {
+	Items []*BusinessUserGroupMemberResponse `json:"items" description:"成员列表"`
+	Total int64                              `json:"total" description:"总记录数"`
+	Page  int                                `json:"page" description:"当前页码"`
+	Size  int                                `json:"size" description:"每页数量"`
+}
+
+// BusinessUserGroupMemberCandidateRequest 业务用户组成员候选分页查询请求。
+type BusinessUserGroupMemberCandidateRequest struct {
+	Page        int    `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码，默认 1"`
+	PageSize    int    `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量，默认 20，最大 100"`
+	Keyword     string `json:"keyword" query:"keyword" validate:"omitempty,max=100" maxLength:"100" description:"按用户名或脱敏手机号模糊搜索，最多 100 字符"`
+	GroupFilter string `json:"group_filter" query:"group_filter" validate:"omitempty,oneof=all ungrouped current other" enum:"all,ungrouped,current,other" description:"归属筛选 (all:全部, ungrouped:未分组, current:当前组, other:其他组)"`
+}
+
+// BusinessUserGroupMemberCandidateParams 业务用户组成员候选路径与查询参数。
+type BusinessUserGroupMemberCandidateParams struct {
+	BusinessUserGroupMemberRequest
+	BusinessUserGroupMemberCandidateRequest
+}
+
+// BusinessUserGroupMemberCandidateResponse 业务用户组成员候选响应。
+type BusinessUserGroupMemberCandidateResponse struct {
+	AccountID           uint   `json:"account_id" description:"平台用户账号ID"`
+	Username            string `json:"username" description:"平台用户用户名"`
+	Phone               string `json:"phone" description:"脱敏手机号，仅保留前3位和后4位"`
+	CurrentGroupID      *uint  `json:"current_group_id" description:"当前业务用户组ID，未分组时为空"`
+	CurrentGroupCode    string `json:"current_group_code" description:"当前业务用户组稳定编码"`
+	CurrentGroupName    string `json:"current_group_name" description:"当前业务用户组名称"`
+	CurrentGroupEnabled bool   `json:"current_group_enabled" description:"当前业务用户组是否启用"`
+	Action              string `json:"action" enum:"add,already_member,move" description:"稳定操作提示 (add:新增, already_member:已在目标组, move:迁入)"`
+	CanAdd              bool   `json:"can_add" description:"当前目标组是否允许新增成员"`
+}
+
+// BusinessUserGroupMemberCandidatePageResult 业务用户组成员候选分页响应。
+type BusinessUserGroupMemberCandidatePageResult struct {
+	Items []*BusinessUserGroupMemberCandidateResponse `json:"items" description:"成员候选列表"`
+	Total int64                                       `json:"total" description:"总记录数"`
+	Page  int                                         `json:"page" description:"当前页码"`
+	Size  int                                         `json:"size" description:"每页数量"`
+}
+
+// AddBusinessUserGroupMembersRequest 增量增加业务用户组成员请求。
+// account_ids 去重后必须非空，且全部是启用且未删除的平台用户账号。
+type AddBusinessUserGroupMembersRequest struct {
+	AccountIDs []uint `json:"account_ids" validate:"required,min=1,dive,min=1" required:"true" description:"平台用户账号ID列表，去重后至少一个；全部必须是启用且未删除的平台用户"`
+}
+
+// RemoveBusinessUserGroupMembersRequest 组作用域增量移除成员请求。
+type RemoveBusinessUserGroupMembersRequest struct {
+	AccountIDs []uint `json:"account_ids" validate:"required,min=1,dive,min=1" required:"true" description:"当前业务用户组成员账号ID列表，去重后至少一个；任一不属于目标组时整批拒绝"`
 }
 
 // BusinessUserGroupMemberRequest 业务用户组成员维护路径参数。
 type BusinessUserGroupMemberRequest struct {
-	ID uint `path:"id" required:"true" description:"业务用户组ID"`
+	ID uint `json:"-" path:"id" validate:"required,min=1" required:"true" description:"业务用户组ID"`
 }
 
 // BusinessUserGroupDeleteRequest 业务用户组删除二次确认请求。
@@ -91,18 +164,21 @@ type BusinessUserGroupDeleteParams struct {
 	BusinessUserGroupDeleteRequest
 }
 
-// ClearBusinessUserGroupMembersParams 清空平台用户分组归属请求（用于 DELETE 显式请求体）。
-type ClearBusinessUserGroupMembersParams struct {
-	ClearBusinessUserGroupMembersRequest
+// BusinessUserGroupMemberMutationResult 成员增量维护结果。
+type BusinessUserGroupMemberMutationResult struct {
+	GroupID             uint   `json:"group_id" description:"目标业务用户组ID"`
+	AccountIDs          []uint `json:"account_ids" description:"本次请求去重后的账号ID列表"`
+	RequestedCount      int    `json:"requested_count" description:"本次请求账号数"`
+	AddedCount          int    `json:"added_count" description:"实际新增成员数"`
+	AddedAccountIDs     []uint `json:"added_account_ids" description:"实际新增成员账号ID集合"`
+	MovedCount          int    `json:"moved_count" description:"从其他组迁入的成员数"`
+	MovedAccountIDs     []uint `json:"moved_account_ids" description:"从其他组迁入的成员账号ID集合"`
+	UnchangedCount      int    `json:"unchanged_count" description:"已在目标组而未变化的成员数"`
+	UnchangedAccountIDs []uint `json:"unchanged_account_ids" description:"已在目标组而未变化的成员账号ID集合"`
+	RemovedCount        int    `json:"removed_count" description:"实际移除成员数"`
+	RemovedAccountIDs   []uint `json:"removed_account_ids" description:"实际移除成员账号ID集合"`
 }
 
-// BusinessUserGroupMembersResult 成员维护结果。
-type BusinessUserGroupMembersResult struct {
-	GroupID    uint   `json:"group_id" description:"目标业务用户组ID；清空操作为 0"`
-	AccountIDs []uint `json:"account_ids" description:"本次成功维护归属的平台用户账号ID列表"`
-}
-
-// BatchUpdateShopBusinessOwnerRequest 勾选店铺批量设置或清空负责人请求。
 // business_owner_account_id 缺失时请求非法；显式 null 表示清空负责人。
 type BatchUpdateShopBusinessOwnerRequest struct {
 	ShopIDs                   []uint `json:"shop_ids" validate:"required,min=1,max=500,dive,min=1" required:"true" minItems:"1" maxItems:"500" description:"店铺ID列表，至少一个且去重，最多 500 个"`