# Promote Backend API

Backend API for the Promote platform, built with Hono.js, Supabase, ClickHouse, Redis, and BullMQ. This platform facilitates influencer marketing campaigns management and analytics tracking.

## 功能概述

- **项目管理**: 创建和管理营销项目
- **KOL管理**: 跟踪和管理网红账号
- **帖子跟踪**: 监控营销内容表现
- **分析跟踪**: 实时追踪视图、点赞和关注者数据
- **用户认证**: 基于JWT的安全认证
- **数据缓存**: 使用Redis优化API响应时间
- **后台任务**: 使用BullMQ处理异步任务

## 技术栈

- **框架**: [Hono.js](https://honojs.dev/) - 轻量、高性能的Web框架
- **认证**: [Supabase Auth](https://supabase.com/docs/guides/auth) + JWT - 安全的用户认证
- **数据库**: 
  - [Supabase (PostgreSQL)](https://supabase.com/) - 存储关系型数据
  - [ClickHouse](https://clickhouse.com/) - 分析事件数据的列式数据库
- **缓存**: [Redis](https://redis.io/) - 高性能内存数据存储
- **任务队列**: [BullMQ](https://docs.bullmq.io/) - 基于Redis的分布式任务队列

## 数据库结构

### PostgreSQL数据库 - 关系型业务数据

#### 主要表

**projects** - 营销项目表
- `id` (uuid, PK): 项目唯一标识
- `name` (text): 项目名称
- `description` (text): 项目描述
- `created_by` (uuid): 创建者ID
- `created_at`, `updated_at`: 时间戳

**influencers** - 网红表
- `influencer_id` (uuid, PK): 网红唯一标识
- `name` (text): 网红名称
- `platform` (text): 所属平台(如youtube, instagram等)
- `profile_url` (text): 网红主页链接
- `external_id` (text): 外部平台ID
- `followers_count` (integer): 粉丝数
- `video_count` (integer): 视频数量
- `platform_count` (integer): 平台数量
- `created_at`, `updated_at`: 时间戳

**project_influencers** - 项目与网红关联表
- `id` (uuid, PK): 关联记录ID
- `project_id` (uuid, FK): 关联的项目ID
- `influencer_id` (uuid, FK): 关联的网红ID
- `created_at`, `updated_at`: 时间戳

**posts** - 帖子表
- `post_id` (uuid, PK): 帖子唯一标识
- `influencer_id` (uuid, FK): 发布者ID
- `platform` (text): 发布平台
- `post_url` (text): 帖子链接
- `title` (text): 帖子标题
- `description` (text): 帖子描述
- `published_at`: 发布时间
- `created_at`, `updated_at`: 时间戳

**其他表**
- `comments`: 评论数据
- `project_comments`: 项目评论
- `user_profiles`: 用户资料

### ClickHouse数据库 - 事件分析数据

#### 事件表

**events** - 通用事件表
- `event_id` (UUID): 事件唯一标识
- `user_id` (String): 用户ID
- `event_type` (String): 事件类型
- `value` (Float64): 事件值
- `timestamp` (DateTime): 事件时间

**follower_events** - 关注/取关事件表
- `follower_id` (String): 关注者ID
- `followed_id` (String): 被关注者ID
- `timestamp` (DateTime): 事件时间
- `action` (Enum): 'follow'或'unfollow'

**like_events** - 点赞/取消点赞事件表
- `user_id` (String): 用户ID
- `content_id` (String): 内容ID
- `timestamp` (DateTime): 事件时间
- `action` (Enum): 'like'或'unlike'

**view_events** - 内容查看事件表
- `user_id` (String): 用户ID
- `content_id` (String): 内容ID
- `timestamp` (DateTime): 查看时间
- `ip` (String): IP地址
- `user_agent` (String): 用户代理

## 环境要求

- Node.js 18+
- pnpm
- Redis
- ClickHouse
- Supabase账户

## 安装步骤

1. 克隆仓库

```bash
git clone <repository-url>
cd promote
```

2. 安装依赖

```bash
cd backend
pnpm install
```

3. 环境配置

创建`.env`文件，参考`.env.example`

```env
# Supabase配置
DATABASE_URL=postgres://postgres:password@localhost:5432/promote
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_key

# ClickHouse配置
CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=
CLICKHOUSE_DATABASE=promote

# Redis配置
REDIS_URL=redis://localhost:6379
```

4. 启动开发服务器

```bash
pnpm dev
```

## 数据库检查工具

项目包含数据库结构检查工具，位于`backend/scripts/db-inspector`目录：

```bash
# 一键运行所有数据库检查
./backend/scripts/db-inspector/run-all.sh

# 单独运行PostgreSQL检查
node backend/scripts/db-inspector/postgres-schema.js

# 单独运行ClickHouse检查
node backend/scripts/db-inspector/clickhouse-schema.js
```

检查结果保存在`backend/db-reports`目录。

## API端点

### 认证

- `POST /api/auth/register` - 注册新用户
- `POST /api/auth/login` - 用户登录
- `GET /api/auth/verify` - 验证Token

### 项目

- `GET /api/projects` - 获取所有项目
- `GET /api/projects/:id` - 获取单个项目
- `POST /api/projects` - 创建新项目
- `PUT /api/projects/:id` - 更新项目
- `DELETE /api/projects/:id` - 删除项目
- `GET /api/projects/:id/influencers` - 获取项目关联的网红

### 网红

- `GET /api/influencers` - 获取所有网红
- `GET /api/influencers/:id` - 获取单个网红信息
- `POST /api/influencers` - 添加新网红
- `PUT /api/influencers/:id` - 更新网红信息
- `DELETE /api/influencers/:id` - 删除网红
- `GET /api/influencers/:id/posts` - 获取网红的帖子

### 帖子

- `GET /api/posts` - 获取所有帖子
- `GET /api/posts/:id` - 获取单个帖子
- `POST /api/posts` - 创建新帖子
- `PUT /api/posts/:id` - 更新帖子
- `DELETE /api/posts/:id` - 删除帖子

### 分析

- `POST /api/analytics/view` - 记录内容查看事件
- `POST /api/analytics/like` - 记录点赞/取消点赞事件
- `POST /api/analytics/follow` - 记录关注/取消关注事件
- `GET /api/analytics/content/:id` - 获取内容分析
- `GET /api/analytics/user/:id` - 获取用户分析
- `GET /api/analytics/project/:id` - 获取项目分析

## 开发

### 构建项目

```bash
pnpm build
```

### 启动生产服务器

```bash
pnpm start
```

### Linting

```bash
pnpm lint
```

### 测试

```bash
pnpm test
```

## 项目结构

```
backend/
├── db-reports/         # 数据库结构检查报告
├── scripts/            # 脚本工具
│   └── db-inspector/   # 数据库检查工具
├── src/
│   ├── config/         # 配置文件
│   ├── controllers/    # 路由控制器
│   ├── middlewares/    # 中间件函数
│   ├── models/         # 数据模型
│   ├── routes/         # API路由
│   ├── services/       # 业务逻辑
│   │   ├── analytics/  # 分析服务
│   │   ├── auth/       # 认证服务
│   │   ├── influencer/ # 网红管理服务
│   │   ├── post/       # 帖子服务
│   │   └── project/    # 项目服务
│   ├── utils/          # 工具函数
│   └── index.ts        # 入口点
├── .env                # 环境变量
├── package.json        # 依赖和脚本
└── tsconfig.json       # TypeScript配置
```

## 数据流程

1. **用户认证流程**
   - 用户通过API注册/登录
   - 验证凭据并生成JWT令牌
   - 令牌用于后续请求验证

2. **内容创建流程**
   - 创建项目
   - 添加网红到项目
   - 跟踪网红发布的帖子

3. **分析跟踪流程**
   - 通过API端点记录事件
   - 事件写入ClickHouse
   - 通过查询分析数据

## 许可

本项目基于ISC许可证开源。