first commit
This commit is contained in:
Claude Workbench
234
docs/tool-service-api.md
Normal file
234
docs/tool-service-api.md
Normal file
@@ -0,0 +1,234 @@
|
||||
# 工具服务模块 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 |
|
||||
Reference in New Issue
Block a user