docs: 更新项目文档，完善需求和技术细节
This commit is contained in:
ylweng
372
admin-system/API接口文档.md
Normal file
372
admin-system/API接口文档.md
Normal file
@@ -0,0 +1,372 @@
|
||||
# 爱鉴花后台管理系统 API 接口文档
|
||||
|
||||
## 概述
|
||||
本文档描述了爱鉴花后台管理系统的 RESTful API 接口规范，基于 OpenAPI 3.0 标准。
|
||||
|
||||
## 基础信息
|
||||
- **Base URL**: `http://localhost:3200/api/v1`
|
||||
- **认证方式**: Bearer Token (JWT)
|
||||
- **响应格式**: JSON
|
||||
|
||||
## 通用响应格式
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "操作成功",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
## 错误码说明
|
||||
| 错误码 | 说明 |
|
||||
|--------|------|
|
||||
| 200 | 成功 |
|
||||
| 400 | 请求参数错误 |
|
||||
| 401 | 未授权访问 |
|
||||
| 403 | 权限不足 |
|
||||
| 404 | 资源不存在 |
|
||||
| 409 | 资源冲突 |
|
||||
| 500 | 服务器内部错误 |
|
||||
|
||||
## 用户管理接口
|
||||
|
||||
### 1. 获取用户列表
|
||||
|
||||
**接口摘要**: 获取用户列表（需要管理员权限）
|
||||
|
||||
**请求方法**: `GET`
|
||||
**请求路径**: `/users`
|
||||
|
||||
**请求参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| page | integer | 否 | 页码，默认1 |
|
||||
| limit | integer | 否 | 每页数量，默认10 |
|
||||
| keyword | string | 否 | 搜索关键词（用户名/手机号/邮箱） |
|
||||
| user_type | string | 否 | 用户类型（farmer/buyer/admin） |
|
||||
|
||||
**请求示例**:
|
||||
```http
|
||||
GET /api/v1/users?page=1&limit=10&keyword=test&user_type=farmer
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应示例 (200)**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "获取成功",
|
||||
"data": {
|
||||
"users": [
|
||||
{
|
||||
"id": 1,
|
||||
"username": "testuser",
|
||||
"phone": "13800138000",
|
||||
"email": "test@example.com",
|
||||
"user_type": "farmer",
|
||||
"avatar_url": null,
|
||||
"created_at": "2023-12-01 10:00:00",
|
||||
"last_login": "2023-12-15 15:30:00"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 10,
|
||||
"total": 100,
|
||||
"pages": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 创建用户
|
||||
|
||||
**接口摘要**: 创建新用户（需要管理员权限）
|
||||
|
||||
**请求方法**: `POST`
|
||||
**请求路径**: `/users`
|
||||
|
||||
**请求体**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| username | string | 是 | 用户名 |
|
||||
| phone | string | 是 | 手机号 |
|
||||
| email | string | 是 | 邮箱地址 |
|
||||
| user_type | string | 是 | 用户类型（farmer/buyer/admin） |
|
||||
| password | string | 是 | 密码（最少6位） |
|
||||
| real_name | string | 否 | 真实姓名 |
|
||||
| avatar_url | string | 否 | 头像URL |
|
||||
|
||||
**请求示例**:
|
||||
```http
|
||||
POST /api/v1/users
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"username": "newuser",
|
||||
"phone": "13900139000",
|
||||
"email": "newuser@example.com",
|
||||
"user_type": "buyer",
|
||||
"password": "123456",
|
||||
"real_name": "张三",
|
||||
"avatar_url": null
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例 (201)**:
|
||||
```json
|
||||
{
|
||||
"code": 201,
|
||||
"message": "用户创建成功",
|
||||
"data": {
|
||||
"id": 2,
|
||||
"username": "newuser",
|
||||
"phone": "13900139000",
|
||||
"email": "newuser@example.com",
|
||||
"user_type": "buyer",
|
||||
"avatar_url": null,
|
||||
"real_name": "张三"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应示例 (409)**:
|
||||
```json
|
||||
{
|
||||
"code": 409,
|
||||
"message": "用户名已存在",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 获取用户详情
|
||||
|
||||
**接口摘要**: 获取指定用户的详细信息
|
||||
|
||||
**请求方法**: `GET`
|
||||
**请求路径**: `/users/{id}`
|
||||
|
||||
**路径参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| id | integer | 是 | 用户ID |
|
||||
|
||||
**请求示例**:
|
||||
```http
|
||||
GET /api/v1/users/1
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应示例 (200)**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "获取成功",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"username": "testuser",
|
||||
"phone": "13800138000",
|
||||
"email": "test@example.com",
|
||||
"user_type": "farmer",
|
||||
"avatar_url": null,
|
||||
"real_name": "测试用户",
|
||||
"created_at": "2023-12-01 10:00:00",
|
||||
"last_login": "2023-12-15 15:30:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 更新用户信息
|
||||
|
||||
**接口摘要**: 更新用户信息
|
||||
|
||||
**请求方法**: `PUT`
|
||||
**请求路径**: `/users/{id}`
|
||||
|
||||
**路径参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| id | integer | 是 | 用户ID |
|
||||
|
||||
**请求体**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| username | string | 否 | 用户名 |
|
||||
| phone | string | 否 | 手机号 |
|
||||
| email | string | 否 | 邮箱地址 |
|
||||
| user_type | string | 否 | 用户类型 |
|
||||
| real_name | string | 否 | 真实姓名 |
|
||||
| avatar_url | string | 否 | 头像URL |
|
||||
|
||||
**请求示例**:
|
||||
```http
|
||||
PUT /api/v1/users/1
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"username": "updateduser",
|
||||
"phone": "13800138001",
|
||||
"email": "updated@example.com",
|
||||
"user_type": "admin",
|
||||
"real_name": "更新用户"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例 (200)**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "更新成功",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"username": "updateduser",
|
||||
"phone": "13800138001",
|
||||
"email": "updated@example.com",
|
||||
"user_type": "admin",
|
||||
"avatar_url": null,
|
||||
"real_name": "更新用户"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 删除用户
|
||||
|
||||
**接口摘要**: 删除用户（软删除，需要管理员权限）
|
||||
|
||||
**请求方法**: `DELETE`
|
||||
**请求路径**: `/users/{id}`
|
||||
|
||||
**路径参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| id | integer | 是 | 用户ID |
|
||||
|
||||
**请求示例**:
|
||||
```http
|
||||
DELETE /api/v1/users/1
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应示例 (200)**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "删除成功",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
### 6. 修改密码
|
||||
|
||||
**接口摘要**: 修改用户密码
|
||||
|
||||
**请求方法**: `PUT`
|
||||
**请求路径**: `/users/{id}/password`
|
||||
|
||||
**路径参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| id | integer | 是 | 用户ID |
|
||||
|
||||
**请求体**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| old_password | string | 是 | 原密码 |
|
||||
| new_password | string | 是 | 新密码（最少6位） |
|
||||
|
||||
**请求示例**:
|
||||
```http
|
||||
PUT /api/v1/users/1/password
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"old_password": "oldpassword123",
|
||||
"new_password": "newpassword456"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例 (200)**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "密码修改成功",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
## 认证接口
|
||||
|
||||
### 1. 用户登录
|
||||
|
||||
**接口摘要**: 用户登录获取访问令牌
|
||||
|
||||
**请求方法**: `POST`
|
||||
**请求路径**: `/auth/login`
|
||||
|
||||
**请求体**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| username | string | 是 | 用户名 |
|
||||
| password | string | 是 | 密码 |
|
||||
|
||||
**请求示例**:
|
||||
```http
|
||||
POST /api/v1/auth/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "admin123"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例 (200)**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "登录成功",
|
||||
"data": {
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"user": {
|
||||
"id": 1,
|
||||
"username": "admin",
|
||||
"user_type": "admin"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 获取当前用户信息
|
||||
|
||||
**接口摘要**: 获取当前登录用户信息
|
||||
|
||||
**请求方法**: `GET`
|
||||
**请求路径**: `/users/me`
|
||||
|
||||
**请求示例**:
|
||||
```http
|
||||
GET /api/v1/users/me
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应示例 (200)**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "获取成功",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"username": "admin",
|
||||
"phone": "13800138000",
|
||||
"email": "admin@example.com",
|
||||
"user_type": "admin",
|
||||
"avatar_url": null,
|
||||
"real_name": "管理员",
|
||||
"created_at": "2023-12-01 10:00:00",
|
||||
"last_login": "2023-12-15 15:30:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user