Files

2025-03-11 18:06:01 +08:00

7.2 KiB

Raw Blame History

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账户

安装步骤

克隆仓库

git clone <repository-url>
cd promote

安装依赖

cd backend
pnpm install

环境配置

创建.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

启动开发服务器

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配置

数据流程

用户认证流程
- 用户通过API注册/登录
- 验证凭据并生成JWT令牌
- 令牌用于后续请求验证
内容创建流程
- 创建项目
- 添加网红到项目
- 跟踪网红发布的帖子
分析跟踪流程
- 通过API端点记录事件
- 事件写入ClickHouse
- 通过查询分析数据

许可

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

7.2 KiB Raw Blame History