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