nxxmdata/backend/swagger-users.js

/**
 * 用户管理模块 Swagger 文档
 * @file swagger-users.js
 */

const usersPaths = {
  // 获取所有用户
  '/users': {
    get: {
      tags: ['用户管理'],
      summary: '获取用户列表',
      description: '分页获取系统中的所有用户',
      parameters: [
        {
          name: 'page',
          in: 'query',
          schema: { type: 'integer', default: 1 },
          description: '页码'
        },
        {
          name: 'limit',
          in: 'query',
          schema: { type: 'integer', default: 10 },
          description: '每页数量'
        },
        {
          name: 'search',
          in: 'query',
          schema: { type: 'string' },
          description: '搜索关键词（用户名、邮箱、手机号）'
        },
        {
          name: 'status',
          in: 'query',
          schema: { type: 'string', enum: ['active', 'inactive', 'banned'] },
          description: '用户状态筛选'
        },
        {
          name: 'role',
          in: 'query',
          schema: { type: 'string' },
          description: '角色筛选'
        }
      ],
      responses: {
        '200': {
          description: '获取成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  data: {
                    type: 'array',
                    items: { $ref: '#/components/schemas/User' }
                  },
                  pagination: {
                    type: 'object',
                    properties: {
                      page: { type: 'integer' },
                      limit: { type: 'integer' },
                      total: { type: 'integer' },
                      totalPages: { type: 'integer' }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    post: {
      tags: ['用户管理'],
      summary: '创建新用户',
      description: '管理员创建新用户账号',
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: {
              type: 'object',
              required: ['username', 'email', 'password'],
              properties: {
                username: { type: 'string', description: '用户名' },
                email: { type: 'string', format: 'email', description: '邮箱' },
                password: { type: 'string', minLength: 6, description: '密码' },
                phone: { type: 'string', description: '手机号' },
                realName: { type: 'string', description: '真实姓名' },
                avatar: { type: 'string', description: '头像URL' },
                status: { type: 'string', enum: ['active', 'inactive'], default: 'active' },
                roleIds: { type: 'array', items: { type: 'integer' }, description: '角色ID列表' }
              }
            }
          }
        }
      },
      responses: {
        '201': {
          description: '创建成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  message: { type: 'string', example: '用户创建成功' },
                  data: { $ref: '#/components/schemas/User' }
                }
              }
            }
          }
        },
        '400': {
          description: '请求参数错误或用户已存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    }
  },

  // 根据用户名搜索用户
  '/users/search': {
    get: {
      tags: ['用户管理'],
      summary: '搜索用户',
      description: '根据用户名、邮箱或手机号搜索用户',
      parameters: [
        {
          name: 'q',
          in: 'query',
          required: true,
          schema: { type: 'string' },
          description: '搜索关键词'
        },
        {
          name: 'limit',
          in: 'query',
          schema: { type: 'integer', default: 10 },
          description: '返回结果数量限制'
        }
      ],
      responses: {
        '200': {
          description: '搜索成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  data: {
                    type: 'array',
                    items: { $ref: '#/components/schemas/User' }
                  }
                }
              }
            }
          }
        }
      }
    }
  },

  // 获取指定用户详情
  '/users/{id}': {
    get: {
      tags: ['用户管理'],
      summary: '获取用户详情',
      description: '根据用户ID获取用户详细信息',
      parameters: [
        {
          name: 'id',
          in: 'path',
          required: true,
          schema: { type: 'integer' },
          description: '用户ID'
        }
      ],
      responses: {
        '200': {
          description: '获取成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  data: { $ref: '#/components/schemas/User' }
                }
              }
            }
          }
        },
        '404': {
          description: '用户不存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    },
    put: {
      tags: ['用户管理'],
      summary: '更新用户信息',
      description: '更新指定用户的信息',
      parameters: [
        {
          name: 'id',
          in: 'path',
          required: true,
          schema: { type: 'integer' },
          description: '用户ID'
        }
      ],
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: {
              type: 'object',
              properties: {
                username: { type: 'string', description: '用户名' },
                email: { type: 'string', format: 'email', description: '邮箱' },
                phone: { type: 'string', description: '手机号' },
                realName: { type: 'string', description: '真实姓名' },
                avatar: { type: 'string', description: '头像URL' },
                status: { type: 'string', enum: ['active', 'inactive', 'banned'] },
                roleIds: { type: 'array', items: { type: 'integer' }, description: '角色ID列表' }
              }
            }
          }
        }
      },
      responses: {
        '200': {
          description: '更新成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  message: { type: 'string', example: '用户信息更新成功' },
                  data: { $ref: '#/components/schemas/User' }
                }
              }
            }
          }
        },
        '400': {
          description: '请求参数错误',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        },
        '404': {
          description: '用户不存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    },
    delete: {
      tags: ['用户管理'],
      summary: '删除用户',
      description: '删除指定用户（软删除）',
      parameters: [
        {
          name: 'id',
          in: 'path',
          required: true,
          schema: { type: 'integer' },
          description: '用户ID'
        }
      ],
      responses: {
        '200': {
          description: '删除成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  message: { type: 'string', example: '用户删除成功' }
                }
              }
            }
          }
        },
        '404': {
          description: '用户不存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    }
  },

  // 重置用户密码
  '/users/{id}/reset-password': {
    post: {
      tags: ['用户管理'],
      summary: '重置用户密码',
      description: '管理员重置指定用户的密码',
      parameters: [
        {
          name: 'id',
          in: 'path',
          required: true,
          schema: { type: 'integer' },
          description: '用户ID'
        }
      ],
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: {
              type: 'object',
              required: ['newPassword'],
              properties: {
                newPassword: {
                  type: 'string',
                  minLength: 6,
                  description: '新密码'
                }
              }
            }
          }
        }
      },
      responses: {
        '200': {
          description: '密码重置成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  message: { type: 'string', example: '密码重置成功' }
                }
              }
            }
          }
        },
        '404': {
          description: '用户不存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    }
  },

  // 批量操作用户
  '/users/batch': {
    post: {
      tags: ['用户管理'],
      summary: '批量操作用户',
      description: '批量启用、禁用或删除用户',
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: {
              type: 'object',
              required: ['userIds', 'action'],
              properties: {
                userIds: {
                  type: 'array',
                  items: { type: 'integer' },
                  description: '用户ID列表'
                },
                action: {
                  type: 'string',
                  enum: ['activate', 'deactivate', 'ban', 'delete'],
                  description: '操作类型'
                }
              }
            }
          }
        }
      },
      responses: {
        '200': {
          description: '批量操作成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  message: { type: 'string', example: '批量操作完成' },
                  data: {
                    type: 'object',
                    properties: {
                      successCount: { type: 'integer', description: '成功处理的用户数量' },
                      failedCount: { type: 'integer', description: '处理失败的用户数量' },
                      errors: { type: 'array', items: { type: 'string' }, description: '错误信息列表' }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },

  // 导出用户数据
  '/users/export': {
    get: {
      tags: ['用户管理'],
      summary: '导出用户数据',
      description: '导出用户数据为Excel文件',
      parameters: [
        {
          name: 'format',
          in: 'query',
          schema: { type: 'string', enum: ['xlsx', 'csv'], default: 'xlsx' },
          description: '导出格式'
        },
        {
          name: 'status',
          in: 'query',
          schema: { type: 'string', enum: ['active', 'inactive', 'banned'] },
          description: '用户状态筛选'
        },
        {
          name: 'role',
          in: 'query',
          schema: { type: 'string' },
          description: '角色筛选'
        }
      ],
      responses: {
        '200': {
          description: '导出成功',
          content: {
            'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': {
              schema: {
                type: 'string',
                format: 'binary'
              }
            },
            'text/csv': {
              schema: {
                type: 'string',
                format: 'binary'
              }
            }
          }
        }
      }
    }
  }
};

// 用户数据模型
const userSchemas = {
  User: {
    type: 'object',
    properties: {
      id: { type: 'integer', description: '用户ID' },
      username: { type: 'string', description: '用户名' },
      email: { type: 'string', format: 'email', description: '邮箱' },
      phone: { type: 'string', description: '手机号' },
      realName: { type: 'string', description: '真实姓名' },
      avatar: { type: 'string', description: '头像URL' },
      status: { 
        type: 'string', 
        enum: ['active', 'inactive', 'banned'],
        description: '用户状态：active-活跃，inactive-未激活，banned-已封禁'
      },
      roles: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            id: { type: 'integer' },
            name: { type: 'string' },
            description: { type: 'string' }
          }
        },
        description: '用户角色列表'
      },
      permissions: {
        type: 'array',
        items: { type: 'string' },
        description: '用户权限列表'
      },
      lastLoginAt: { type: 'string', format: 'date-time', description: '最后登录时间' },
      createdAt: { type: 'string', format: 'date-time', description: '创建时间' },
      updatedAt: { type: 'string', format: 'date-time', description: '更新时间' }
    }
  }
};

module.exports = { usersPaths, userSchemas };