1818web-hoduan/docs/admin-tool-config-api.md

# 工具配置管理（管理端）API 文档

## 概述

管理端工具配置API，用于管理工具配置和查看使用统计。

- **Base URL**: `/admin/tools`
- **认证方式**: 需要管理员权限（`ROLE_ADMIN`）
- **请求头**: `Authorization: Bearer {admin_jwt_token}`

---

## 一、工具配置管理

### 1.1 获取所有工具配置

获取所有工具配置列表。

**请求**
```
GET /admin/tools/configs
```

**响应**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "toolCode": "douyin_user_videos",
      "toolName": "获取用户主页视频",
      "category": "douyin",
      "description": "根据sec_user_id获取用户发布的视频列表",
      "apiEndpoint": "/api/v1/douyin/app/v3/fetch_user_post_videos",
      "requestMethod": "GET",
      "pointsCost": 5,
      "isEnabled": 1,
      "sortOrder": 1,
      "createTime": "2026-01-02T10:00:00",
      "updateTime": "2026-01-02T10:00:00"
    }
  ]
}
```

---

### 1.2 获取工具配置详情

根据ID获取工具配置详情。

**请求**
```
GET /admin/tools/configs/{id}
```

**路径参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 工具ID |

**响应**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "toolCode": "douyin_user_videos",
    "toolName": "获取用户主页视频",
    "category": "douyin",
    "description": "根据sec_user_id获取用户发布的视频列表",
    "apiEndpoint": "/api/v1/douyin/app/v3/fetch_user_post_videos",
    "requestMethod": "GET",
    "pointsCost": 5,
    "isEnabled": 1,
    "sortOrder": 1,
    "createTime": "2026-01-02T10:00:00",
    "updateTime": "2026-01-02T10:00:00"
  }
}
```

---

### 1.3 创建工具配置

创建新的工具配置。

**请求**
```
POST /admin/tools/configs
Content-Type: application/json
```

**请求体**
```json
{
  "toolCode": "douyin_user_videos",
  "toolName": "获取用户主页视频",
  "category": "douyin",
  "description": "根据sec_user_id获取用户发布的视频列表",
  "apiEndpoint": "/api/v1/douyin/app/v3/fetch_user_post_videos",
  "requestMethod": "GET",
  "pointsCost": 5,
  "isEnabled": 1,
  "sortOrder": 1
}
```

**请求体参数说明**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| toolCode | String | 是 | 工具编码（唯一标识） |
| toolName | String | 是 | 工具名称 |
| category | String | 是 | 工具分类（douyin/xiaohongshu/wechat_mp） |
| description | String | 否 | 工具描述 |
| apiEndpoint | String | 是 | API端点路径 |
| requestMethod | String | 否 | 请求方法（GET/POST），默认GET |
| pointsCost | Integer | 否 | 积分消耗，默认1 |
| isEnabled | Integer | 否 | 是否启用（0禁用/1启用），默认1 |
| sortOrder | Integer | 否 | 排序顺序，默认0 |

**响应**
```json
{
  "code": 200,
  "message": "创建成功",
  "data": {
    "id": 1,
    "toolCode": "douyin_user_videos",
    "toolName": "获取用户主页视频",
    "category": "douyin",
    "description": "根据sec_user_id获取用户发布的视频列表",
    "apiEndpoint": "/api/v1/douyin/app/v3/fetch_user_post_videos",
    "requestMethod": "GET",
    "pointsCost": 5,
    "isEnabled": 1,
    "sortOrder": 1,
    "createTime": "2026-01-02T10:00:00",
    "updateTime": "2026-01-02T10:00:00"
  }
}
```

---

### 1.4 更新工具配置

更新指定工具配置。

**请求**
```
PUT /admin/tools/configs/{id}
Content-Type: application/json
```

**路径参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 工具ID |

**请求体**
```json
{
  "toolCode": "douyin_user_videos",
  "toolName": "获取用户主页视频",
  "category": "douyin",
  "description": "根据sec_user_id获取用户发布的视频列表",
  "apiEndpoint": "/api/v1/douyin/app/v3/fetch_user_post_videos",
  "requestMethod": "GET",
  "pointsCost": 10,
  "isEnabled": 1,
  "sortOrder": 1
}
```

**响应**
```json
{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "toolCode": "douyin_user_videos",
    "toolName": "获取用户主页视频",
    "category": "douyin",
    "description": "根据sec_user_id获取用户发布的视频列表",
    "apiEndpoint": "/api/v1/douyin/app/v3/fetch_user_post_videos",
    "requestMethod": "GET",
    "pointsCost": 10,
    "isEnabled": 1,
    "sortOrder": 1,
    "createTime": "2026-01-02T10:00:00",
    "updateTime": "2026-01-02T11:00:00"
  }
}
```

---

### 1.5 更新积分消耗

单独更新工具的积分消耗配置。

**请求**
```
PATCH /admin/tools/configs/{id}/points-cost?pointsCost={pointsCost}
```

**参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 工具ID（路径参数） |
| pointsCost | Integer | 是 | 积分消耗（查询参数） |

**响应**
```json
{
  "code": 200,
  "message": "更新成功",
  "data": null
}
```

---

### 1.6 更新工具状态

启用或禁用工具。

**请求**
```
PATCH /admin/tools/configs/{id}/status?isEnabled={isEnabled}
```

**参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 工具ID（路径参数） |
| isEnabled | Integer | 是 | 是否启用（0禁用/1启用）（查询参数） |

**响应**
```json
{
  "code": 200,
  "message": "更新成功",
  "data": null
}
```

---

### 1.7 删除工具配置

删除指定工具配置（逻辑删除）。

**请求**
```
DELETE /admin/tools/configs/{id}
```

**路径参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 工具ID |

**响应**
```json
{
  "code": 200,
  "message": "删除成功",
  "data": null
}
```

---

## 二、使用统计

### 2.1 获取统计概览

获取工具数量和今日调用统计。

**请求**
```
GET /admin/tools/stats/info
```

**响应**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "totalTools": 8,
    "enabledTools": 8,
    "todayCalls": 156,
    "todayPointsCost": 780
  }
}
```

**响应字段说明**
| 字段 | 类型 | 说明 |
|------|------|------|
| totalTools | Long | 工具总数 |
| enabledTools | Long | 已启用工具数 |
| todayCalls | Long | 今日调用次数 |
| todayPointsCost | Long | 今日消耗积分 |

---

### 2.2 获取统计汇总

获取指定日期范围内的统计汇总。

**请求**
```
GET /admin/tools/stats/summary?startDate={startDate}&endDate={endDate}
```

**查询参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| startDate | String | 否 | 开始日期（yyyy-MM-dd），默认30天前 |
| endDate | String | 否 | 结束日期（yyyy-MM-dd），默认今天 |

**响应**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "totalCalls": 1560,
    "successCalls": 1500,
    "failedCalls": 60,
    "totalPointsCost": 7800,
    "uniqueUsers": null,
    "toolStats": [
      {
        "toolCode": "douyin_user_videos",
        "toolName": "获取用户主页视频",
        "category": null,
        "totalCalls": 500,
        "successCalls": 480,
        "totalPointsCost": 2500
      },
      {
        "toolCode": "xiaohongshu_search_notes",
        "toolName": "搜索笔记",
        "category": null,
        "totalCalls": 300,
        "successCalls": 290,
        "totalPointsCost": 1500
      }
    ]
  }
}
```

**响应字段说明**
| 字段 | 类型 | 说明 |
|------|------|------|
| totalCalls | Long | 总调用次数 |
| successCalls | Long | 成功次数 |
| failedCalls | Long | 失败次数 |
| totalPointsCost | Long | 总消耗积分 |
| uniqueUsers | Long | 独立用户数 |
| toolStats | Array | 按工具分类统计 |

---

### 2.3 获取每日统计

获取每日统计数据列表。

**请求**
```
GET /admin/tools/stats/daily?startDate={startDate}&endDate={endDate}&toolCode={toolCode}
```

**查询参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| startDate | String | 否 | 开始日期（yyyy-MM-dd），默认7天前 |
| endDate | String | 否 | 结束日期（yyyy-MM-dd），默认今天 |
| toolCode | String | 否 | 工具编码，用于筛选特定工具 |

**响应**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "statsDate": "2026-01-02",
      "toolCode": "douyin_user_videos",
      "toolName": "获取用户主页视频",
      "totalCalls": 100,
      "successCalls": 95,
      "failedCalls": 5,
      "totalPointsCost": 500,
      "uniqueUsers": 20
    },
    {
      "statsDate": "2026-01-01",
      "toolCode": "douyin_user_videos",
      "toolName": "获取用户主页视频",
      "totalCalls": 80,
      "successCalls": 78,
      "failedCalls": 2,
      "totalPointsCost": 400,
      "uniqueUsers": 15
    }
  ]
}
```

**响应字段说明**
| 字段 | 类型 | 说明 |
|------|------|------|
| statsDate | String | 统计日期 |
| toolCode | String | 工具编码 |
| toolName | String | 工具名称 |
| totalCalls | Integer | 调用总次数 |
| successCalls | Integer | 成功次数 |
| failedCalls | Integer | 失败次数 |
| totalPointsCost | Integer | 消耗总积分 |
| uniqueUsers | Integer | 独立用户数 |

---

### 2.4 刷新每日统计

手动刷新指定日期的统计数据。

**请求**
```
POST /admin/tools/stats/refresh?date={date}
```

**查询参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| date | String | 否 | 日期（yyyy-MM-dd），默认今天 |

**响应**
```json
{
  "code": 200,
  "message": "刷新成功",
  "data": null
}
```

---

## 三、错误响应

所有接口在发生错误时返回统一格式：

```json
{
  "code": 500,
  "message": "错误描述信息",
  "data": null
}
```

**常见错误码**
| 错误码 | 说明 |
|--------|------|
| 401 | 未认证或Token过期 |
| 403 | 无权限（非管理员） |
| 500 | 服务器内部错误 |

---

## 四、数据字典

### 工具分类（category）
| 值 | 说明 |
|------|------|
| douyin | 抖音 |
| xiaohongshu | 小红书 |
| wechat_mp | 微信公众号 |

### 请求方法（requestMethod）
| 值 | 说明 |
|------|------|
| GET | GET请求 |
| POST | POST请求 |

### 启用状态（isEnabled）
| 值 | 说明 |
|------|------|
| 0 | 禁用 |
| 1 | 启用 |