282 lines
7.2 KiB
Markdown
282 lines
7.2 KiB
Markdown
# 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许可证开源。 |