502 lines
10 KiB
Markdown
502 lines
10 KiB
Markdown
# 工具配置管理（管理端）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 | 启用 |
|