promote/backend

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 - 轻量、高性能的Web框架
• 认证: Supabase Auth + JWT - 安全的用户认证
• 数据库:
  • Supabase (PostgreSQL) - 存储关系型数据
  • ClickHouse - 分析事件数据的列式数据库
• 缓存: Redis - 高性能内存数据存储
• 任务队列: BullMQ - 基于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. 克隆仓库

git clone <repository-url>
cd promote

2. 安装依赖

cd backend
pnpm install

3. 环境配置

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

# 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. 启动开发服务器

pnpm dev

数据库检查工具

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

# 一键运行所有数据库检查
./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 - 获取项目分析

开发

构建项目

pnpm build

启动生产服务器

pnpm start

Linting

pnpm lint

测试

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许可证开源。