photography/backend/api/desc/admin/users.api

syntax = "v1"

import "common.api"

// 管理后台用户管理接口

// 获取用户列表请求
type GetAdminUserListRequest {
    PageRequest
    Keyword string `form:"keyword,optional"`
    Status  int    `form:"status,optional"`  // 用户状态筛选
    SortBy  string `form:"sort_by,optional,default=created_at_desc"` // 排序方式
}

// 获取用户列表响应
type GetAdminUserListResponse {
    BaseResponse
    Data AdminUserListData `json:"data"`
}

type AdminUserListData {
    PageResponse
    Users []AdminUser `json:"users"`
}

// 获取用户详情请求
type GetAdminUserRequest {
    Id int64 `path:"id"`
}

// 获取用户详情响应
type GetAdminUserResponse {
    BaseResponse
    Data AdminUserDetail `json:"data"`
}

// 创建用户请求
type CreateAdminUserRequest {
    Username string `json:"username" validate:"required"`
    Email    string `json:"email" validate:"required,email"`
    Password string `json:"password" validate:"required,min=6"`
    Status   int    `json:"status,optional,default=1"`  // 用户状态
    Role     string `json:"role,optional,default=user"` // 用户角色
}

// 创建用户响应
type CreateAdminUserResponse {
    BaseResponse
    Data AdminUser `json:"data"`
}

// 更新用户请求
type UpdateAdminUserRequest {
    Id       int64  `path:"id"`
    Username string `json:"username,optional"`
    Email    string `json:"email,optional"`
    Avatar   string `json:"avatar,optional"`
    Status   int    `json:"status,optional"`
    Role     string `json:"role,optional"`
}

// 更新用户响应
type UpdateAdminUserResponse {
    BaseResponse
    Data AdminUser `json:"data"`
}

// 删除用户请求
type DeleteAdminUserRequest {
    Id int64 `path:"id"`
}

// 删除用户响应
type DeleteAdminUserResponse {
    BaseResponse
}

// 更新用户状态请求
type UpdateAdminUserStatusRequest {
    Id     int64 `path:"id"`
    Status int   `json:"status" validate:"required"` // 1:启用 0:禁用
}

// 更新用户状态响应
type UpdateAdminUserStatusResponse {
    BaseResponse
    Data AdminUser `json:"data"`
}

// 重置用户密码请求
type ResetAdminUserPasswordRequest {
    Id          int64  `path:"id"`
    NewPassword string `json:"new_password" validate:"required,min=6"`
}

// 重置用户密码响应
type ResetAdminUserPasswordResponse {
    BaseResponse
}

// 上传用户头像请求
type UploadAdminUserAvatarRequest {
    Id int64 `path:"id"`
}

// 上传用户头像响应
type UploadAdminUserAvatarResponse {
    BaseResponse
    Data UploadAdminUserAvatarData `json:"data"`
}

type UploadAdminUserAvatarData {
    AvatarUrl string `json:"avatar_url"`
}

// 批量操作用户请求
type BatchAdminUserOperationRequest {
    UserIds   []int64 `json:"user_ids" validate:"required"`
    Operation string  `json:"operation" validate:"required"` // enable, disable, delete
}

// 批量操作用户响应
type BatchAdminUserOperationResponse {
    BaseResponse
    Data BatchAdminUserOperationData `json:"data"`
}

type BatchAdminUserOperationData {
    SuccessCount int     `json:"success_count"`
    FailedCount  int     `json:"failed_count"`
    FailedIds    []int64 `json:"failed_ids"`
}

// 用户统计请求
type GetAdminUserStatsRequest {
    DateRange string `form:"date_range,optional,default=7d"` // 7d, 30d, 90d
}

// 用户统计响应
type GetAdminUserStatsResponse {
    BaseResponse
    Data AdminUserStatsData `json:"data"`
}

type AdminUserStatsData {
    TotalUsers    int64 `json:"total_users"`
    ActiveUsers   int64 `json:"active_users"`
    InactiveUsers int64 `json:"inactive_users"`
    NewUsers      int64 `json:"new_users"`      // 指定时间范围内新增用户
    GrowthRate    float64 `json:"growth_rate"`  // 增长率
}

// 管理后台用户管理接口组 - 需要管理员认证
@server(
    group: admin_users
    prefix: /admin/users
    jwt: AdminAuth
)
service photography-api {
    @doc "获取用户列表"
    @handler getAdminUserList
    get / (GetAdminUserListRequest) returns (GetAdminUserListResponse)
    
    @doc "创建用户"
    @handler createAdminUser
    post / (CreateAdminUserRequest) returns (CreateAdminUserResponse)
    
    @doc "获取用户详情"
    @handler getAdminUser
    get /:id (GetAdminUserRequest) returns (GetAdminUserResponse)
    
    @doc "更新用户"
    @handler updateAdminUser
    put /:id (UpdateAdminUserRequest) returns (UpdateAdminUserResponse)
    
    @doc "删除用户"
    @handler deleteAdminUser
    delete /:id (DeleteAdminUserRequest) returns (DeleteAdminUserResponse)
    
    @doc "更新用户状态"
    @handler updateAdminUserStatus
    put /:id/status (UpdateAdminUserStatusRequest) returns (UpdateAdminUserStatusResponse)
    
    @doc "重置用户密码"
    @handler resetAdminUserPassword
    post /:id/reset-password (ResetAdminUserPasswordRequest) returns (ResetAdminUserPasswordResponse)
    
    @doc "上传用户头像"
    @handler uploadAdminUserAvatar
    post /:id/avatar (UploadAdminUserAvatarRequest) returns (UploadAdminUserAvatarResponse)
    
    @doc "批量操作用户"
    @handler batchAdminUserOperation
    post /batch (BatchAdminUserOperationRequest) returns (BatchAdminUserOperationResponse)
    
    @doc "获取用户统计"
    @handler getAdminUserStats
    get /stats (GetAdminUserStatsRequest) returns (GetAdminUserStatsResponse)
}