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密钥

调用示例：

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

响应示例：

{
  "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}

请求示例（抖音获取用户视频）：

{
  "sec_user_id": "MS4wLjABAAAAnxkX6qJBxkyBnNhE__dpuYxdNFzihx1UoxfoKKkAlO8",
  "max_cursor": 0,
  "count": 20
}

响应示例：

{
  "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

请求示例：

{
  "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

响应示例：

{
  "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 配置

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