first commit

2026-02-13 18:18:20 +08:00
parent 0f7bc05697
commit e3e6f1f29d
136 changed files with 68018 additions and 17982 deletions
--- a/docs/admin-tool-config-api.md
+++ b/docs/admin-tool-config-api.md
@@ -0,0 +1,501 @@
+# 工具配置管理（管理端）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 | 启用 |