10 | 代码小库

### 技术选型

前端技术栈

React 18.2 - 最新的React框架
TypeScript 5.3 - 类型安全
Ant Design 5.x - 企业级UI组件库
Zustand 4.x - 轻量级状态管理
React Router 6.x - 路由管理
Axios - HTTP请求
Markdown编辑器 - 富文本支持

后端技术栈

NestJS 10.x - 企业级Node.js框架
TypeORM 0.3+ - ORM框架
MySQL 8.0 - 关系型数据库
Redis 7.0 - 缓存与排行榜
JWT - 身份认证
Swagger - API文档
Socket.io - 实时通知（预留）

核心特性

热门算法 - 基于点赞、浏览、评论的智能排序
匿名系统 - 支持匿名发帖和评论，保护隐私
板块管理 - 多级板块分类
评论系统 - 多级评论、@提醒
搜索功能 - 全文搜索、标签搜索
用户等级 - 经验值、勋章系统
数据统计 - 实时统计、可视化图表
内容审核 - 敏感词过滤、举报系统

🎯 功能模块详解

1. 用户系统

1.1 用户认证

登录功能

支持用户名/邮箱登录
JWT Token认证
记住密码（7天有效期）
登录日志记录

注册功能

用户名验证（4-20位字母数字下划线）
邮箱验证
密码强度检查（6-20位）
邮箱验证码（可选）

第三方登录（预留接口）

微信登录
QQ登录
GitHub登录

1.2 个人中心

基本信息

头像上传（支持裁剪）
昵称修改
个人简介编辑
联系方式管理

我的内容

我的帖子列表
我的评论列表
收藏列表
点赞记录

社交关系

关注列表
粉丝列表
关注/取消关注

消息通知

系统通知
回复通知
点赞通知
关注通知
@提醒通知

1.3 用户等级系统

等级划分

等级	名称	所需经验	权限
0	新人	0	基础功能
1-2	新手用户	50	发帖、评论
3-4	进阶用户	200	上传图片
5-7	普通用户	500	发起话题
8-9	活跃用户	1000	创建板块
10+	论坛大神	2000+	申请版主

经验值获取

发帖：+10经验
评论：+5经验
收到点赞：+2经验
精华帖：+50经验
每日登录：+5经验

勋章系统

新人勋章：注册成功
活跃勋章：连续登录7天
作家勋章：发帖超过100篇
大神勋章：等级达到10级

2. 帖子系统

2.1 发帖功能

编辑器功能

Markdown语法支持
实时预览
图片上传（拖拽上传）
代码高亮
表情包插入

帖子属性

标题（5-100字符）
内容（Markdown格式）
所属板块（必选）
标签（最多5个）
匿名发帖（可选）

草稿箱

自动保存草稿（每30秒）
草稿列表
恢复草稿
删除草稿

2.2 帖子展示

列表展示

卡片式布局
响应式设计
懒加载（滚动加载）
分页切换

排序方式

最新：按发布时间降序
最热：按热度分数降序
精华：仅显示精华帖

帖子状态

正常
置顶（红色标签）
精华（金色标签）
匿名（紫色标签）
已锁定（不可评论）

2.3 帖子详情

内容展示

Markdown渲染
代码高亮显示
图片点击放大
外链跳转确认

互动数据

浏览次数
点赞数量
评论数量
收藏数量
分享次数

相关推荐

同板块热门帖子
相似标签帖子
相同作者帖子

3. 评论系统

3.1 评论功能

评论层级

一级评论：直接回复帖子
二级评论：回复一级评论
三级评论：回复二级评论

评论内容

纯文本评论
表情包支持
@用户提醒
图片评论（可选）

匿名评论

可选择匿名
生成随机昵称
同一帖子内保持一致

3.2 评论展示

排序方式

按时间：最新在前
按热度：点赞数降序

评论操作

点赞评论
回复评论
举报评论
删除评论（作者/管理员）

4. 板块系统

4.1 板块结构

板块分类

├── 技术交流
│   ├── 前端开发
│   ├── 后端开发
│   └── 移动开发
├── 校园生活
│   ├── 表白墙
│   ├── 树洞
│   └── 失物招领
├── 学习资料
│   ├── 考研资料
│   ├── 英语学习
│   └── 课程资源
└── 休闲娱乐
    ├── 影视推荐
    ├── 游戏交流
    └── 美食分享

4.2 板块管理

板块信息

板块名称
板块描述
板块图标
排序权重
版主列表

板块统计

帖子总数
今日发帖
活跃用户
热门话题

5. 热门算法 ⭐核心功能

5.1 算法原理

热度分数计算公式

热度分数 = (点赞数 × 5 + 浏览数 × 1 + 评论数 × 10) × 时间衰减系数

时间衰减系数 = 0.999 ^ 小时数

权重说明

点赞权重：5分/次（用户主动认可）
浏览权重：1分/次（基础指标）
评论权重：10分/次（最高价值，代表讨论度）

时间衰减

每小时衰减0.1%
保证新内容有机会进入热榜
老内容逐渐降低权重

5.2 热榜类型

1小时热榜

展示最近1小时的热门内容
更新频率：每5分钟
适合查看实时热点

24小时热榜

展示最近24小时的热门内容
更新频率：每小时
最常用的热榜

7天热榜

展示最近7天的热门内容
更新频率：每4小时
适合周度回顾

30天热榜

展示最近30天的热门内容
更新频率：每天
适合月度精选

5.3 实现细节

定时任务

// 每小时更新所有帖子的热度分数
@Cron('0 * * * *')
async updateAllHotScores() {
  // 只更新最近30天的帖子（性能优化）
  const posts = await this.postRepository.find({
    where: { createdAt: MoreThan(thirtyDaysAgo) }
  })
  
  for (const post of posts) {
    const hotScore = this.calculateHotScore(post)
    await this.postRepository.update(post.id, { hotScore })
  }
}

Redis缓存

// 热榜结果缓存5分钟
const cacheKey = `hot_posts_${timeRange}`
await redis.setex(cacheKey, 300, JSON.stringify(posts))

6. 匿名系统 ⭐核心功能

6.1 匿名规则

匿名身份生成

// 格式：颜色 + 动物 + 随机数
// 示例：红色的熊猫123、蓝色的狐狸456
generateAnonymousName(): string {
  const colors = ['红色', '橙色', '黄色', '绿色', '青色', '蓝色', '紫色']
  const animals = ['熊猫', '考拉', '企鹅', '狐狸', '猫咪', '兔子']
  
  return `${randomColor}的${randomAnimal}${randomNumber}`
}

身份保持

同一帖子内，同一用户的匿名身份保持一致
不同帖子，同一用户的匿名身份不同
管理员可查看真实身份

6.2 隐私保护

隐藏信息

用户名 → 匿名昵称
头像 → 默认头像
用户等级 → 隐藏
发帖数 → 隐藏

限制功能

无法@匿名用户
无法查看匿名用户主页
无法关注匿名用户

7. 搜索系统

7.1 搜索类型

全文搜索

搜索帖子标题
搜索帖子内容
高亮显示关键词

标签搜索

点击标签查看相关帖子
标签热度排序
标签云展示

用户搜索

搜索用户昵称
搜索用户名
显示用户资料卡片

7.2 搜索优化

搜索建议

输入时显示建议
热门搜索词
历史搜索记录

搜索结果

按相关度排序
关键词高亮
分页加载

8. 管理后台

8.1 内容管理

帖子管理

查看所有帖子
设置精华帖
设置置顶帖
删除违规帖
锁定帖子

评论管理

查看所有评论
删除违规评论
批量操作

8.2 用户管理

用户列表

查看所有用户
按等级筛选
按注册时间排序

用户操作

封禁用户
解除封禁
设置版主
查看用户详情

8.3 板块管理

板块操作

创建板块
编辑板块
删除板块
排序板块

版主管理

指定版主
移除版主
版主权限设置

8.4 系统设置

敏感词管理

添加敏感词
删除敏感词
导入敏感词库
敏感词替换规则

举报管理

查看举报列表
处理举报
标记已处理
举报统计

🔌 API接口文档

认证接口

POST /api/auth/register

注册新用户

请求体

{
  "username": "testuser",
  "email": "test@example.com",
  "password": "123456",
  "nickname": "测试用户"
}

响应

{
  "code": 200,
  "message": "注册成功",
  "data": {
    "user": { /* 用户信息 */ },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

POST /api/auth/login

用户登录

请求体

{
  "username": "testuser",
  "password": "123456"
}

帖子接口

GET /api/posts

获取帖子列表

查询参数

page: 页码（默认1）
limit: 每页数量（默认20）
boardId: 板块ID（可选）
sortBy: 排序方式（latest/hot）

响应

{
  "code": 200,
  "data": {
    "posts": [ /* 帖子列表 */ ],
    "total": 100,
    "page": 1,
    "limit": 20,
    "totalPages": 5
  }
}

GET /api/posts/:id

获取帖子详情

POST /api/posts

创建帖子（需要登录）

请求体

{
  "boardId": 1,
  "title": "帖子标题",
  "content": "帖子内容（Markdown）",
  "isAnonymous": false,
  "tags": ["标签1", "标签2"]
}

评论接口

GET /api/comments/post/:postId

获取帖子评论列表

POST /api/comments

创建评论（需要登录）

请求体

{
  "postId": 1,
  "content": "评论内容",
  "parentId": null,
  "replyToId": null,
  "isAnonymous": false
}

热榜接口

GET /api/hot

获取热榜

查询参数

timeRange: 时间范围（1h/24h/7d/30d）
limit: 数量限制（默认50）

🗄️ 数据库设计

核心表说明

users - 用户表

CREATE TABLE users (
  id INT PRIMARY KEY AUTO_INCREMENT,
  username VARCHAR(50) UNIQUE NOT NULL,
  password VARCHAR(255) NOT NULL,
  email VARCHAR(100) UNIQUE NOT NULL,
  nickname VARCHAR(50),
  avatar VARCHAR(255),
  bio TEXT,
  role ENUM('user', 'moderator', 'admin') DEFAULT 'user',
  level INT DEFAULT 0,
  exp INT DEFAULT 0,
  points INT DEFAULT 0,
  post_count INT DEFAULT 0,
  comment_count INT DEFAULT 0,
  status INT DEFAULT 1,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

posts - 帖子表

CREATE TABLE posts (
  id INT PRIMARY KEY AUTO_INCREMENT,
  user_id INT NOT NULL,
  board_id INT NOT NULL,
  title VARCHAR(200) NOT NULL,
  content TEXT NOT NULL,
  content_html TEXT,
  is_anonymous TINYINT DEFAULT 0,
  anonymous_name VARCHAR(50),
  view_count INT DEFAULT 0,
  like_count INT DEFAULT 0,
  comment_count INT DEFAULT 0,
  favorite_count INT DEFAULT 0,
  hot_score INT DEFAULT 0,
  is_essence TINYINT DEFAULT 0,
  is_top TINYINT DEFAULT 0,
  status VARCHAR(20) DEFAULT 'published',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id),
  FOREIGN KEY (board_id) REFERENCES boards(id)
);

完整ER图请查看：database/ER图设计.md

💡 开发指南

添加新功能

示例：添加举报功能

创建Entity

// backend/src/entities/report.entity.ts
@Entity('reports')
export class Report {
  @PrimaryGeneratedColumn()
  id: number
  
  @Column()
  userId: number
  
  @Column()
  targetId: number
  
  @Column()
  targetType: string
  
  @Column()
  reason: string
  
  @Column({ default: 'pending' })
  status: string
}

创建Module/Controller/Service

cd backend
nest g module reports
nest g controller reports
nest g service reports

实现Service逻辑
创建前端API接口
创建前端页面组件

性能优化建议

数据库优化
- 添加索引：title、created_at、hot_score
- 使用联合索引：(board_id, created_at)
缓存策略
- 热榜数据缓存5分钟
- 板块列表缓存1小时
- 用户信息缓存30分钟
前端优化
- 图片懒加载
- 虚拟滚动（长列表）
- 代码分割（按路由）

📞 技术支持

常见问题

参见：快速开始指南.md

文档更新

本文档持续更新中，如有疑问请查看：

Swagger API文档：http://localhost:3002/api-docs
项目README：../README.md

校园论坛系统

核心特性

🎯 功能模块详解

1. 用户系统

1.1 用户认证

1.2 个人中心

1.3 用户等级系统

2. 帖子系统

2.1 发帖功能

2.2 帖子展示

2.3 帖子详情

3. 评论系统

3.1 评论功能

3.2 评论展示

4. 板块系统

4.1 板块结构

4.2 板块管理

5. 热门算法 ⭐核心功能

5.1 算法原理

5.2 热榜类型

5.3 实现细节

6. 匿名系统 ⭐核心功能

6.1 匿名规则

6.2 隐私保护

7. 搜索系统

7.1 搜索类型

7.2 搜索优化

8. 管理后台

8.1 内容管理

8.2 用户管理

8.3 板块管理

8.4 系统设置

🔌 API接口文档

认证接口

POST /api/auth/register

POST /api/auth/login

帖子接口

GET /api/posts

GET /api/posts/:id

POST /api/posts

评论接口

GET /api/comments/post/:postId

POST /api/comments

热榜接口

GET /api/hot

🗄️ 数据库设计

核心表说明

users - 用户表

posts - 帖子表

💡 开发指南

添加新功能

性能优化建议

📞 技术支持

常见问题

文档更新

相关推荐