1818web-hoduan/docs/tool-service-api.md

# 工具服务模块 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 |