readme
This commit is contained in:
@@ -1,76 +1,222 @@
|
|||||||
# Promote Backend API
|
# Promote Backend API
|
||||||
|
|
||||||
Backend API for the Promote platform, built with Hono.js, Supabase, ClickHouse, Redis, and BullMQ.
|
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.
|
||||||
|
|
||||||
## Features
|
## 功能概述
|
||||||
|
|
||||||
- **Authentication**: JWT-based authentication with Supabase Auth
|
- **项目管理**: 创建和管理营销项目
|
||||||
- **Analytics Tracking**: Track views, likes, and followers using ClickHouse
|
- **KOL管理**: 跟踪和管理网红账号
|
||||||
- **Caching**: Redis for fast API responses
|
- **帖子跟踪**: 监控营销内容表现
|
||||||
- **Task Scheduling**: BullMQ for background processing
|
- **分析跟踪**: 实时追踪视图、点赞和关注者数据
|
||||||
|
- **用户认证**: 基于JWT的安全认证
|
||||||
|
- **数据缓存**: 使用Redis优化API响应时间
|
||||||
|
- **后台任务**: 使用BullMQ处理异步任务
|
||||||
|
|
||||||
## Tech Stack
|
## 技术栈
|
||||||
|
|
||||||
- **Framework**: [Hono.js](https://honojs.dev/)
|
- **框架**: [Hono.js](https://honojs.dev/) - 轻量、高性能的Web框架
|
||||||
- **Authentication**: [Supabase Auth](https://supabase.com/docs/guides/auth) + JWT
|
- **认证**: [Supabase Auth](https://supabase.com/docs/guides/auth) + JWT - 安全的用户认证
|
||||||
- **Database**:
|
- **数据库**:
|
||||||
- [Supabase (PostgreSQL)](https://supabase.com/) for main data
|
- [Supabase (PostgreSQL)](https://supabase.com/) - 存储关系型数据
|
||||||
- [ClickHouse](https://clickhouse.com/) for analytics events
|
- [ClickHouse](https://clickhouse.com/) - 分析事件数据的列式数据库
|
||||||
- **Caching**: [Redis](https://redis.io/)
|
- **缓存**: [Redis](https://redis.io/) - 高性能内存数据存储
|
||||||
- **Task Queue**: [BullMQ](https://docs.bullmq.io/)
|
- **任务队列**: [BullMQ](https://docs.bullmq.io/) - 基于Redis的分布式任务队列
|
||||||
|
|
||||||
## Getting Started
|
## 数据库结构
|
||||||
|
|
||||||
### Prerequisites
|
### 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+
|
- Node.js 18+
|
||||||
- pnpm
|
- pnpm
|
||||||
- Redis
|
- Redis
|
||||||
- ClickHouse
|
- ClickHouse
|
||||||
- Supabase account
|
- Supabase账户
|
||||||
|
|
||||||
### Installation
|
## 安装步骤
|
||||||
|
|
||||||
1. Clone the repository
|
1. 克隆仓库
|
||||||
2. Install dependencies:
|
|
||||||
|
```bash
|
||||||
|
git clone <repository-url>
|
||||||
|
cd promote
|
||||||
|
```
|
||||||
|
|
||||||
|
2. 安装依赖
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd backend
|
cd backend
|
||||||
pnpm install
|
pnpm install
|
||||||
```
|
```
|
||||||
|
|
||||||
3. Create a `.env` file based on the `.env.example` file
|
3. 环境配置
|
||||||
4. Start the development server:
|
|
||||||
|
创建`.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
|
```bash
|
||||||
pnpm dev
|
pnpm dev
|
||||||
```
|
```
|
||||||
|
|
||||||
## API Endpoints
|
## 数据库检查工具
|
||||||
|
|
||||||
### Authentication
|
项目包含数据库结构检查工具，位于`backend/scripts/db-inspector`目录：
|
||||||
|
|
||||||
- `POST /api/auth/register` - Register a new user
|
```bash
|
||||||
- `POST /api/auth/login` - Login a user
|
# 一键运行所有数据库检查
|
||||||
- `GET /api/auth/verify` - Verify a token
|
./backend/scripts/db-inspector/run-all.sh
|
||||||
|
|
||||||
### Analytics
|
# 单独运行PostgreSQL检查
|
||||||
|
node backend/scripts/db-inspector/postgres-schema.js
|
||||||
|
|
||||||
- `POST /api/analytics/view` - Track a view event
|
# 单独运行ClickHouse检查
|
||||||
- `POST /api/analytics/like` - Track a like/unlike event
|
node backend/scripts/db-inspector/clickhouse-schema.js
|
||||||
- `POST /api/analytics/follow` - Track a follow/unfollow event
|
```
|
||||||
- `GET /api/analytics/content/:id` - Get analytics for a content
|
|
||||||
- `GET /api/analytics/user/:id` - Get analytics for a user
|
|
||||||
|
|
||||||
## Development
|
检查结果保存在`backend/db-reports`目录。
|
||||||
|
|
||||||
### Build
|
## 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
|
```bash
|
||||||
pnpm build
|
pnpm build
|
||||||
```
|
```
|
||||||
|
|
||||||
### Start Production Server
|
### 启动生产服务器
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pnpm start
|
pnpm start
|
||||||
@@ -82,30 +228,55 @@ pnpm start
|
|||||||
pnpm lint
|
pnpm lint
|
||||||
```
|
```
|
||||||
|
|
||||||
### Testing
|
### 测试
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pnpm test
|
pnpm test
|
||||||
```
|
```
|
||||||
|
|
||||||
## Project Structure
|
## 项目结构
|
||||||
|
|
||||||
```
|
```
|
||||||
backend/
|
backend/
|
||||||
|
├── db-reports/ # 数据库结构检查报告
|
||||||
|
├── scripts/ # 脚本工具
|
||||||
|
│ └── db-inspector/ # 数据库检查工具
|
||||||
├── src/
|
├── src/
|
||||||
│ ├── config/ # Configuration files
|
│ ├── config/ # 配置文件
|
||||||
│ ├── controllers/ # Route controllers
|
│ ├── controllers/ # 路由控制器
|
||||||
│ ├── middlewares/ # Middleware functions
|
│ ├── middlewares/ # 中间件函数
|
||||||
│ ├── models/ # Data models
|
│ ├── models/ # 数据模型
|
||||||
│ ├── routes/ # API routes
|
│ ├── routes/ # API路由
|
||||||
│ ├── services/ # Business logic
|
│ ├── services/ # 业务逻辑
|
||||||
│ ├── utils/ # Utility functions
|
│ │ ├── analytics/ # 分析服务
|
||||||
│ └── index.ts # Entry point
|
│ │ ├── auth/ # 认证服务
|
||||||
├── .env # Environment variables
|
│ │ ├── influencer/ # 网红管理服务
|
||||||
├── package.json # Dependencies and scripts
|
│ │ ├── post/ # 帖子服务
|
||||||
└── tsconfig.json # TypeScript configuration
|
│ │ └── project/ # 项目服务
|
||||||
|
│ ├── utils/ # 工具函数
|
||||||
|
│ └── index.ts # 入口点
|
||||||
|
├── .env # 环境变量
|
||||||
|
├── package.json # 依赖和脚本
|
||||||
|
└── tsconfig.json # TypeScript配置
|
||||||
```
|
```
|
||||||
|
|
||||||
## License
|
## 数据流程
|
||||||
|
|
||||||
This project is licensed under the ISC License.
|
1. **用户认证流程**
|
||||||
|
- 用户通过API注册/登录
|
||||||
|
- 验证凭据并生成JWT令牌
|
||||||
|
- 令牌用于后续请求验证
|
||||||
|
|
||||||
|
2. **内容创建流程**
|
||||||
|
- 创建项目
|
||||||
|
- 添加网红到项目
|
||||||
|
- 跟踪网红发布的帖子
|
||||||
|
|
||||||
|
3. **分析跟踪流程**
|
||||||
|
- 通过API端点记录事件
|
||||||
|
- 事件写入ClickHouse
|
||||||
|
- 通过查询分析数据
|
||||||
|
|
||||||
|
## 许可
|
||||||
|
|
||||||
|
本项目基于ISC许可证开源。
|
||||||
Reference in New Issue
Block a user