海口龙华志愿者后端管理页面
edit | blame | history | raw

管理员管理Web接口文档

基础信息

  • 接口前缀: /web/api/admins
  • 接口版本: v1.0
  • 作者: 韩天尊
  • 日期: 2024-01-15

统一返回格式

所有接口返回统一格式：

{
  "code": 0,        // 返回码：0-成功，-1-失败，101-用户未登录/失效/无权限，102-无效数据，103-数据覆盖，104-数据不存在，105-数据唯一性，106-数据多样性
  "msg": "请求成功", // 提示信息
  "data": {}        // 返回数据，根据接口不同而变化
}

接口列表

1. 管理员登录

接口描述: 管理员通过手机号和密码登录

请求地址: /web/api/admins/login

请求方式: POST

请求头:
Content-Type: application/json

请求参数:

参数名 类型 必填 说明
phone String 是 手机号码
password String 是 密码

请求示例:
json { "phone": "13800138000", "password": "123456" }

响应示例:

成功响应：
json { "code": 0, "msg": "登录成功", "data": { "id": 1, "username": "admin", "name": "管理员", "phone": "13800138000", "role": "admin", "status": "1", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } }

失败响应：
json { "code": -1, "msg": "账号不存在", "data": null }

错误码说明:
- code: -1, msg: "用户名和密码不能为空" - 参数为空
- code: -1, msg: "账号不存在" - 账号不存在或已禁用
- code: -1, msg: "请求失败" - 系统异常

2. 管理员列表查询（分页）

接口描述: 分页查询管理员列表，支持多条件筛选

请求地址: /web/api/admins/pageQuery

请求方式: GET

请求参数:

参数名 类型 必填 说明
page int 是 页码（从1开始）
size int 是 每页数量
username String 否 用户名（模糊查询）
name String 否 姓名（模糊查询）
role String 否 角色
status String 否 状态（0:禁用,1:正常）
createStart String 否 创建开始时间（格式：yyyy-MM-dd HH:mm:ss）
createEnd String 否 创建结束时间（格式：yyyy-MM-dd HH:mm:ss）

请求示例:
GET /web/api/admins/pageQuery?page=1&size=10&username=admin&status=1

响应示例:

成功响应：
json { "code": 0, "msg": "处理成功", "data": { "content": [ { "id": 1, "username": "admin", "name": "管理员", "phone": "13800138000", "role": "admin", "status": "1", "lastLoginTime": "2024-01-15 10:30:00", "communityCode": "001", "communityName": "XX社区", "subdistrictCode": "001", "subdistrictName": "XX街道", "districtCode": "001", "districtName": "XX区", "updateTime": "2024-01-15 10:30:00", "createTime": "2024-01-01 09:00:00" } ], "pageable": { "sort": { "sorted": true, "unsorted": false, "empty": false }, "pageNumber": 0, "pageSize": 10, "offset": 0, "paged": true, "unpaged": false }, "totalElements": 100, "totalPages": 10, "last": false, "first": true, "numberOfElements": 10, "size": 10, "number": 0, "sort": { "sorted": true, "unsorted": false, "empty": false }, "empty": false } }

失败响应：
json { "code": -1, "msg": "错误信息", "data": null }

说明:
- 默认按创建时间倒序排列
- 支持用户名、姓名的模糊查询
- 支持多条件组合查询

3. 根据ID查询管理员详情

接口描述: 根据管理员ID查询详细信息

请求地址: /web/api/admins/getById

请求方式: GET

请求参数:

参数名 类型 必填 说明
id String 是 管理员ID

请求示例:
GET /web/api/admins/getById?id=1

响应示例:

成功响应：
json { "code": 0, "msg": "请求成功", "data": { "id": 1, "username": "admin", "name": "管理员", "phone": "13800138000", "role": "admin", "status": "1", "lastLoginTime": "2024-01-15 10:30:00", "communityCode": "001", "communityName": "XX社区", "subdistrictCode": "001", "subdistrictName": "XX街道", "districtCode": "001", "districtName": "XX区", "updateTime": "2024-01-15 10:30:00", "createTime": "2024-01-01 09:00:00", "password": null } }

失败响应（数据不存在）：
json { "code": 0, "msg": "请求成功", "data": null }

说明:
- 返回数据中不包含密码字段（password为null）

4. 保存/更新管理员

接口描述: 新增或更新管理员信息（有ID则更新，无ID则新增）

请求地址: /web/api/admins/saveAdmin

请求方式: POST

请求头:
Content-Type: application/json

请求参数:

参数名 类型 必填 说明
id Integer 否 管理员ID（更新时必填）
username String 否 用户名
password String 否 密码（加密）
name String 否 姓名
phone String 否 手机号码
role String 否 角色
status String 否 状态（0:禁用,1:正常）
communityCode String 否 社区code
communityName String 否 社区名
subdistrictCode String 否 街道乡镇code
subdistrictName String 否 街道乡镇名
districtCode String 否 区code
districtName String 否 区名

请求示例:

新增管理员：
json { "username": "test", "password": "123456", "name": "测试用户", "phone": "13900139000", "role": "user", "status": "1", "communityCode": "001", "communityName": "XX社区" }

更新管理员：
json { "id": 1, "name": "更新后的名称", "status": "1" }

响应示例:

成功响应（新增）：
json { "code": 0, "msg": "请求成功", "data": "保存成功" }

成功响应（更新）：
json { "code": 0, "msg": "请求成功", "data": "1" }

失败响应（用户名已存在）：
json { "code": -1, "msg": "用户名已存在", "data": null }

说明:
- 新增时，如果username已存在，会返回"用户名已存在"
- 更新时，如果username与已有记录重复（排除自身），会返回"用户名已存在"
- 密码需要前端进行加密后再传输

5. 删除管理员

接口描述: 根据ID删除管理员（支持批量删除）

请求地址: /web/api/admins/removeByIds

请求方式: GET

请求参数:

参数名 类型 必填 说明
ids String 是 管理员ID，多个用逗号分隔

请求示例:

单条删除：
GET /web/api/admins/removeByIds?ids=1

批量删除：
GET /web/api/admins/removeByIds?ids=1,2,3

响应示例:

成功响应：
json { "code": 0, "msg": "请求成功", "data": "删除成功" }

失败响应：
json { "code": -1, "msg": "请求失败", "data": null }

说明:
- 支持单个删除和批量删除
- 多个ID用英文逗号分隔

6. 重置密码

接口描述: 重置指定管理员的密码

请求地址: /web/api/admins/resetPassword

请求方式: POST

请求参数:

参数名 类型 必填 说明
id String 是 管理员ID
newPassword String 是 新密码

请求示例:
POST /web/api/admins/resetPassword?id=1&newPassword=123456

响应示例:

成功响应：
json { "code": 0, "msg": "请求成功", "data": "密码重置成功" }

失败响应（参数为空）：
json { "code": -1, "msg": "新密码不能为空", "data": null }

失败响应（系统异常）：
json { "code": -1, "msg": "请求失败", "data": null }

说明:
- 新密码需要前端进行加密后再传输
- 注意：当前实现中密码未加密，建议后端添加加密逻辑

数据模型

VolAdmins（管理员对象）

字段名 类型 说明
id Integer 管理员ID（主键，自增）
username String 用户名
password String 密码（加密）
name String 姓名
phone String 手机号码
role String 角色
status String 状态（0:禁用,1:正常）
lastLoginTime Date 最后登录时间
communityCode String 社区code
communityName String 社区名
subdistrictCode String 街道乡镇code
subdistrictName String 街道乡镇名
districtCode String 区code
districtName String 区名
updateTime Date 更新时间
createTime Date 创建时间

注意事项

  1. 认证机制: 登录接口返回的token需要在前端保存，后续接口可能需要携带token进行身份验证（具体以实际网关配置为准）

  2. 密码加密:

  • 当前登录接口的密码验证逻辑被注释，需要根据实际加密方式实现
  • 保存和重置密码接口需要前端或后端进行密码加密
  1. 分页查询:
  • page参数从1开始，后端会自动转换为从0开始的索引
  • 默认按创建时间倒序排列

  1. 时间格式: 所有时间字段格式为：yyyy-MM-dd HH:mm:ss

  2. 状态值:

  • 0: 禁用
  • 1: 正常
  1. 异常处理: 所有接口都有统一的异常处理，返回标准的错误格式

更新日志

  • 2024-01-15: 初始版本，包含管理员管理的基础CRUD接口