docs: 更新项目文档，完善需求和技术细节
This commit is contained in:
ylweng
285
docs/后台管理系统API文档.md
Normal file
285
docs/后台管理系统API文档.md
Normal file
@@ -0,0 +1,285 @@
|
||||
# 爱鉴花后台管理系统 API 接口文档
|
||||
|
||||
基于 OpenAPI 3.0 规范
|
||||
|
||||
## 基础信息
|
||||
|
||||
- **Base URL**: `http://localhost:3200/api/v1`
|
||||
- **认证方式**: Bearer Token (JWT)
|
||||
- **响应格式**: JSON
|
||||
|
||||
## 统一响应格式
|
||||
|
||||
所有接口都遵循以下响应格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "操作成功",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
## 认证接口
|
||||
|
||||
### 管理员登录
|
||||
|
||||
**POST** `/auth/login`
|
||||
|
||||
**请求参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| login | string | 是 | 用户名/手机号/邮箱 |
|
||||
| password | string | 是 | 密码 |
|
||||
|
||||
**响应示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "登录成功",
|
||||
"data": {
|
||||
"user_id": 1,
|
||||
"username": "admin",
|
||||
"user_type": "admin",
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 用户管理接口
|
||||
|
||||
### 获取用户列表
|
||||
|
||||
**GET** `/users`
|
||||
|
||||
**权限要求**: 管理员
|
||||
|
||||
**查询参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| page | number | 否 | 页码，默认1 |
|
||||
| limit | number | 否 | 每页数量，默认10 |
|
||||
| keyword | string | 否 | 搜索关键词 |
|
||||
| user_type | string | 否 | 用户类型过滤 |
|
||||
|
||||
**响应示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "获取成功",
|
||||
"data": {
|
||||
"users": [
|
||||
{
|
||||
"id": 1,
|
||||
"username": "testuser",
|
||||
"phone": "13800138000",
|
||||
"email": "test@example.com",
|
||||
"user_type": "farmer",
|
||||
"created_at": "2024-01-01T00:00:00.000Z"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 10,
|
||||
"total": 100,
|
||||
"pages": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 获取用户详情
|
||||
|
||||
**GET** `/users/{id}`
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| id | number | 是 | 用户ID |
|
||||
|
||||
### 删除用户
|
||||
|
||||
**DELETE** `/users/{id}`
|
||||
|
||||
**权限要求**: 管理员
|
||||
|
||||
## 商品管理接口
|
||||
|
||||
### 获取商品列表
|
||||
|
||||
**GET** `/products`
|
||||
|
||||
**查询参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| page | number | 否 | 页码，默认1 |
|
||||
| limit | number | 否 | 每页数量，默认10 |
|
||||
| category_id | number | 否 | 分类ID过滤 |
|
||||
| min_price | number | 否 | 最低价格 |
|
||||
| max_price | number | 否 | 最高价格 |
|
||||
| status | number | 否 | 状态过滤 |
|
||||
|
||||
### 创建商品
|
||||
|
||||
**POST** `/products`
|
||||
|
||||
**权限要求**: 管理员
|
||||
|
||||
**请求体**:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "玫瑰花",
|
||||
"category_id": 1,
|
||||
"price": 29.9,
|
||||
"stock": 100,
|
||||
"image": "/uploads/roses.jpg",
|
||||
"description": "新鲜玫瑰花束"
|
||||
}
|
||||
```
|
||||
|
||||
## 订单管理接口
|
||||
|
||||
### 获取订单列表
|
||||
|
||||
**GET** `/orders`
|
||||
|
||||
**权限要求**: 管理员
|
||||
|
||||
**查询参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| page | number | 否 | 页码，默认1 |
|
||||
| limit | number | 否 | 每页数量，默认10 |
|
||||
| status | number | 否 | 订单状态过滤 |
|
||||
| start_date | string | 否 | 开始日期 |
|
||||
| end_date | string | 否 | 结束日期 |
|
||||
|
||||
### 更新订单状态
|
||||
|
||||
**PUT** `/orders/{id}/status`
|
||||
|
||||
**权限要求**: 管理员
|
||||
|
||||
**请求体**:
|
||||
|
||||
```json
|
||||
{
|
||||
"payment_status": 1,
|
||||
"shipping_status": 2
|
||||
}
|
||||
```
|
||||
|
||||
## 识别记录管理接口
|
||||
|
||||
### 获取识别记录列表
|
||||
|
||||
**GET** `/identifications`
|
||||
|
||||
**权限要求**: 管理员
|
||||
|
||||
**查询参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| page | number | 否 | 页码，默认1 |
|
||||
| limit | number | 否 | 每页数量，默认10 |
|
||||
| start_date | string | 否 | 开始日期 |
|
||||
| end_date | string | 否 | 结束日期 |
|
||||
| min_confidence | number | 否 | 最低置信度 |
|
||||
|
||||
## 数据统计接口
|
||||
|
||||
### 获取系统统计概览
|
||||
|
||||
**GET** `/admin/statistics/overview`
|
||||
|
||||
**权限要求**: 管理员
|
||||
|
||||
**响应示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "获取成功",
|
||||
"data": {
|
||||
"total_users": 1000,
|
||||
"new_users_today": 10,
|
||||
"total_orders": 500,
|
||||
"total_revenue": 15000.50,
|
||||
"total_identifications": 2000,
|
||||
"active_users_today": 50
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 获取趋势数据
|
||||
|
||||
**GET** `/admin/statistics/trend`
|
||||
|
||||
**查询参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| days | number | 否 | 天数，默认7 |
|
||||
| type | string | 否 | 统计类型（users/orders/revenue/identifications） |
|
||||
|
||||
## 系统配置接口
|
||||
|
||||
### 获取系统配置
|
||||
|
||||
**GET** `/admin/config`
|
||||
|
||||
**权限要求**: 管理员
|
||||
|
||||
### 更新系统配置
|
||||
|
||||
**PUT** `/admin/config/{key}`
|
||||
|
||||
**权限要求**: 管理员
|
||||
|
||||
**请求体**:
|
||||
|
||||
```json
|
||||
{
|
||||
"value": "new_value"
|
||||
}
|
||||
```
|
||||
|
||||
## 错误码说明
|
||||
|
||||
| 错误码 | 错误信息 | 说明 |
|
||||
|--------|----------|------|
|
||||
| 200 | 成功 | 请求成功 |
|
||||
| 201 | 创建成功 | 资源创建成功 |
|
||||
| 400 | 参数错误 | 请求参数验证失败 |
|
||||
| 401 | 未授权 | 需要登录认证 |
|
||||
| 403 | 禁止访问 | 权限不足 |
|
||||
| 404 | 资源不存在 | 请求的资源不存在 |
|
||||
| 409 | 资源冲突 | 资源已存在或状态冲突 |
|
||||
| 500 | 服务器内部错误 | 服务器内部处理错误 |
|
||||
| 1001 | 识别失败 | 植物识别处理失败 |
|
||||
| 1002 | 图片格式不支持 | 上传的图片格式不支持 |
|
||||
| 2001 | 推广奖励不足 | 可提现余额不足50元 |
|
||||
| 2002 | 提现频率限制 | 24小时内只能提现一次 |
|
||||
| 3001 | 库存不足 | 商品库存不足 |
|
||||
| 3002 | 订单状态异常 | 订单状态不允许此操作 |
|
||||
|
||||
## 安全要求
|
||||
|
||||
1. 所有敏感操作需要管理员权限
|
||||
2. API请求需要携带有效的JWT Token
|
||||
3. 密码传输需要加密
|
||||
4. 文件上传需要验证文件类型和大小
|
||||
|
||||
---
|
||||
|
||||
*文档版本: 1.0.0*
|
||||
*最后更新: 2024-03-15*
|
||||
Reference in New Issue
Block a user