# fmode-tikhub-server 模块说明

## 1. 模块概述

`fmode-tikhub-server` 是一个独立的后端集成模块，旨在为项目提供 **TikTok 数据采集与交互能力**。它封装了 TikHub 第三方 API，通过标准化的 RESTful 接口对外提供服务，屏蔽了底层 API Key 管理、签名机制和请求细节。

### 核心作用

1.  **API 代理与封装**：将 TikHub 的原始 API 封装为本地服务接口，前端无需直接与第三方服务交互，避免了 API Key 泄露风险。
2.  **统一鉴权**：内置了 API Key 和 Token 管理，确保请求的合法性。
3.  **简化调用**：提供了语义化的接口（如 `/search`, `/users/:id`），比原始 API 更易于理解和使用。
4.  **易于集成**：设计为 Express 中间件/路由模块，可插拔式地集成到任何 Node.js/Express 主应用中。

---

## 2. 接口能力

模块当前开放了以下核心能力：

- **用户搜索** (`/search`): 根据关键词搜索 TikTok 用户。
- **用户详情** (`/users/:uniqueId`): 获取指定用户的详细 Profile 信息。
- **作品列表** (`/users/:secUid/posts`): 分页获取用户的视频作品。
- **评论采集** (`/posts/:videoId/comments`): 获取指定视频的评论数据。

---

## 3. 前端集成指南

### 3.1 前置条件

在主应用的前端调用此模块前，请确保：

1.  **后端服务已启动**：主应用（如 `server.ts`）必须已启动，并且已挂载了本模块的路由。
    - 默认挂载路径：`/api/tikhub`
    - 检查方法：访问 `http://localhost:10003/api/tikhub/search?keyword=test` 应返回 JSON 数据。
2.  **网络连通性**：前端环境（浏览器或 App）能够访问到后端服务的端口（默认 10003）。

### 3.2 调用注意事项

1.  **Base URL 配置**：
    - 前端请求的 Base URL 应指向主应用的地址，例如 `http://localhost:10003/api/tikhub`（开发环境）或 `https://api.yourdomain.com/api/tikhub`（生产环境）。
    - **不要**直接请求 `api.tikhub.io`，否则会跨域且暴露 API Key。

2.  **参数传递**：
    - 所有接口均为 `GET` 请求。
    - 参数通常通过 Query String（如 `?keyword=abc`）或 URL Path（如 `/users/elonmusk`）传递。
    - 分页参数 `cursor` 初始传 `0`，后续请求使用上一次接口返回的 `cursor` 值。

3.  **跨域 (CORS)**：
    - 如果前端与后端部署在不同域名/端口，后端主应用必须配置 CORS 中间件允许前端域名的访问。

### 3.3 示例代码 (Frontend Service)

建议在前端项目中封装一个 Service 层：

```typescript
// services/tiktok.service.ts

// 根据环境动态配置 API 地址
const API_ROOT = import.meta.env.VITE_API_URL || 'http://localhost:10003';
const TIKHUB_BASE = `${API_ROOT}/api/tikhub`;

export const TikTokService = {
  // 搜索用户
  async search(keyword: string) {
    const res = await fetch(`${TIKHUB_BASE}/search?keyword=${encodeURIComponent(keyword)}`);
    return await res.json();
  },

  // 获取详情
  async getProfile(uniqueId: string) {
    const res = await fetch(`${TIKHUB_BASE}/users/${uniqueId}`);
    return await res.json();
  }
};
```

---

## 4. 维护与扩展

- **API Key 更换**：如果 Key 失效，请在 `src/client.ts` 中更新 `API_KEY` 常量，或在初始化路由时传入新 Key。
- **新增接口**：如需支持更多 TikHub 功能，请参考 `src/api/users.ts` 扩展新的方法，并在 `src/routes.ts` 中添加对应路由。