235 lines
5.3 KiB
Markdown
235 lines
5.3 KiB
Markdown
# 工具服务模块 API 文档
|
||
|
||
## 概述
|
||
|
||
工具服务模块提供第三方数据采集工具的调用功能，支持抖音、小红书、微信公众号等平台的数据获取。
|
||
|
||
## 认证方式
|
||
|
||
工具接口支持两种认证方式：
|
||
|
||
### 1. JWT Token（Web端）
|
||
登录后自动使用，适合Web前端调用。
|
||
|
||
### 2. API Key（开发者）
|
||
在请求头添加 `Authorization: Bearer {your_api_key}`，适合后端服务或脚本调用。
|
||
|
||
**获取API Key**：
|
||
1. 登录系统
|
||
2. 进入个人中心 -> API密钥管理
|
||
3. 生成API密钥
|
||
|
||
**调用示例**：
|
||
```bash
|
||
curl -X POST "https://api.1818ai.com/user/tools/call/douyin_user_videos" \
|
||
-H "Authorization: Bearer ak_1234567890abcdef1234567890abcdef" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"sec_user_id": "MS4wLjABAAAA...", "max_cursor": 0, "count": 20}'
|
||
```
|
||
|
||
## 功能特性
|
||
|
||
1. **工具配置管理**：管理员可配置每个工具的积分消耗
|
||
2. **积分扣除**：用户调用工具时自动扣除积分
|
||
3. **调用记录**：完整记录每次工具调用
|
||
4. **使用统计**：按天统计每个工具的使用次数
|
||
|
||
## 数据库表
|
||
|
||
### tool_config（工具配置表）
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | bigint | 主键 |
|
||
| tool_code | varchar(64) | 工具编码（唯一） |
|
||
| tool_name | varchar(128) | 工具名称 |
|
||
| category | varchar(32) | 分类（douyin/xiaohongshu/wechat_mp） |
|
||
| api_endpoint | varchar(256) | API端点路径 |
|
||
| points_cost | int | 调用消耗积分 |
|
||
| is_enabled | tinyint | 是否启用 |
|
||
|
||
### tool_usage_log（调用记录表）
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | bigint | 主键 |
|
||
| usage_no | varchar(64) | 调用流水号 |
|
||
| user_id | bigint | 用户ID |
|
||
| tool_code | varchar(64) | 工具编码 |
|
||
| points_cost | int | 消耗积分 |
|
||
| status | varchar(20) | 状态（success/failed） |
|
||
| create_time | datetime | 调用时间 |
|
||
|
||
### tool_usage_daily_stats（每日统计表）
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| stats_date | date | 统计日期 |
|
||
| tool_code | varchar(64) | 工具编码 |
|
||
| total_calls | int | 调用总次数 |
|
||
| success_calls | int | 成功次数 |
|
||
| total_points_cost | int | 消耗总积分 |
|
||
|
||
---
|
||
|
||
## 用户端 API
|
||
|
||
### 1. 获取工具列表
|
||
```
|
||
GET /user/tools/list
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": [
|
||
{
|
||
"toolCode": "douyin_user_videos",
|
||
"toolName": "获取用户主页视频",
|
||
"category": "douyin",
|
||
"description": "根据sec_user_id获取用户发布的视频列表",
|
||
"pointsCost": 5
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2. 按分类获取工具
|
||
```
|
||
GET /user/tools/list/{category}
|
||
```
|
||
- category: douyin / xiaohongshu / wechat_mp
|
||
|
||
### 3. 调用工具
|
||
```
|
||
POST /user/tools/call/{toolCode}
|
||
```
|
||
|
||
**请求示例（抖音获取用户视频）：**
|
||
```json
|
||
{
|
||
"sec_user_id": "MS4wLjABAAAAnxkX6qJBxkyBnNhE__dpuYxdNFzihx1UoxfoKKkAlO8",
|
||
"max_cursor": 0,
|
||
"count": 20
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"usageNo": "TU1735789012345ABCD1234",
|
||
"pointsCost": 5,
|
||
"remainingPoints": 95,
|
||
"data": {
|
||
"aweme_list": [...],
|
||
"max_cursor": 1528366024000,
|
||
"has_more": 1
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 获取调用记录
|
||
```
|
||
GET /user/tools/usage/logs?page=1&size=10&toolCode=douyin_user_videos
|
||
```
|
||
|
||
---
|
||
|
||
## 管理端 API
|
||
|
||
### 1. 获取所有工具配置
|
||
```
|
||
GET /admin/tools/configs
|
||
```
|
||
|
||
### 2. 创建工具配置
|
||
```
|
||
POST /admin/tools/configs
|
||
```
|
||
|
||
**请求示例：**
|
||
```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
|
||
}
|
||
```
|
||
|
||
### 3. 更新积分消耗
|
||
```
|
||
PATCH /admin/tools/configs/{id}/points-cost?pointsCost=10
|
||
```
|
||
|
||
### 4. 启用/禁用工具
|
||
```
|
||
PATCH /admin/tools/configs/{id}/status?isEnabled=0
|
||
```
|
||
|
||
### 5. 获取统计概览
|
||
```
|
||
GET /admin/tools/stats/info
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"totalTools": 8,
|
||
"enabledTools": 8,
|
||
"todayCalls": 156,
|
||
"todayPointsCost": 780
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6. 获取统计汇总
|
||
```
|
||
GET /admin/tools/stats/summary?startDate=2026-01-01&endDate=2026-01-02
|
||
```
|
||
|
||
### 7. 获取每日统计
|
||
```
|
||
GET /admin/tools/stats/daily?startDate=2026-01-01&endDate=2026-01-07&toolCode=douyin_user_videos
|
||
```
|
||
|
||
---
|
||
|
||
## 配置说明
|
||
|
||
### application.yml 配置
|
||
```yaml
|
||
tikhub:
|
||
api:
|
||
base-url: https://api.tikhub.io
|
||
key: YOUR_TIKHUB_API_KEY
|
||
```
|
||
|
||
### 初始化数据库
|
||
执行 `src/main/resources/sql/tool_tables.sql` 创建表和初始数据。
|
||
|
||
---
|
||
|
||
## 预置工具列表
|
||
|
||
| 工具编码 | 名称 | 分类 | 积分 |
|
||
|---------|------|------|------|
|
||
| douyin_user_videos | 获取用户主页视频 | douyin | 5 |
|
||
| douyin_video_by_share | 根据分享链接获取视频 | douyin | 3 |
|
||
| xiaohongshu_user_notes | 获取用户笔记列表 | xiaohongshu | 5 |
|
||
| xiaohongshu_search_notes | 搜索笔记 | xiaohongshu | 5 |
|
||
| xiaohongshu_note_detail | 获取笔记详情 | xiaohongshu | 3 |
|
||
| wechat_mp_article_list | 获取文章列表 | wechat_mp | 5 |
|
||
| wechat_mp_article_json | 获取文章详情(JSON) | wechat_mp | 10 |
|
||
| wechat_mp_article_html | 获取文章详情(HTML) | wechat_mp | 100 |
|