readme

2025-03-11 18:06:01 +08:00
parent 56b1844889
commit ae7ea3b567
1 changed files with 222 additions and 51 deletions
--- 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 <repository-url>
+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. 
+1. **用户认证流程**
+   - 用户通过API注册/登录
+   - 验证凭据并生成JWT令牌
+   - 令牌用于后续请求验证
+
+2. **内容创建流程**
+   - 创建项目
+   - 添加网红到项目
+   - 跟踪网红发布的帖子
+
+3. **分析跟踪流程**
+   - 通过API端点记录事件
+   - 事件写入ClickHouse
+   - 通过查询分析数据
+
+## 许可
+
+本项目基于ISC许可证开源。