# 管理员管理Web接口文档

## 基础信息

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

## 统一返回格式

所有接口返回统一格式：

```json
{
  "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. **密码加密**: 
   - 当前登录接口的密码验证逻辑被注释，需要根据实际加密方式实现
   - 保存和重置密码接口需要前端或后端进行密码加密

3. **分页查询**: 
   - page参数从1开始，后端会自动转换为从0开始的索引
   - 默认按创建时间倒序排列

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

5. **状态值**: 
   - `0`: 禁用
   - `1`: 正常

6. **异常处理**: 所有接口都有统一的异常处理，返回标准的错误格式

---

## 更新日志

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