zhuiguang-ai/.trae/specs/modules/08-community.md

社区功能模块

概述

社区功能模块包含评论系统、收藏系统、浏览历史、收藏夹、通知系统和论坛板块，为用户提供完整的互动体验。

数据模型

PointsHistory (积分历史) 🆕

字段	类型	说明
id	Int @id @default(autoincrement())	主键
userId	Int @map("user_id")	用户ID
points	Int	积分变动
reason	String @db.VarChar(50)	积分原因
detail	String? @db.VarChar(200)	详细信息
refType	String? @map("ref_type") @db.VarChar(50)	关联类型
refId	Int? @map("ref_id")	关联ID
createdAt	DateTime @default(now()) @map("created_at")	创建时间

关系: user → User

索引: [userId, createdAt]

Comment (评论/回复)

• 支持对Tool和Skill进行评论
• 支持嵌套回复（通过parentId自引用）
• 支持评分（1-5星）
• 支持点赞和置顶

字段: id, userId, toolId, skillId, parentId, content, rating, likeCount, isPinned, status, createdAt, updatedAt

关系:

• user: User — 用户评论
• tool: Tool — 工具评论
• skill: Skill — 技能评论
• parent/replies: Comment → Comment — 嵌套回复（自引用）
• likes: CommentLike[] — 点赞列表

CommentLike (评论点赞) - 联合唯一约束 [commentId, userId]

Notification (通知)

通知类型:

• COMMENT_REPLY — 评论回复通知
• COMMENT_LIKE — 评论点赞通知
• TOPIC_REPLY — 话题回复通知
• SYSTEM — 系统通知

ForumCategory (论坛板块) - 二级分类结构 🆕

• 自引用关系: parent/children (CategoryHierarchy)
• 6个父分类 + 24个子分类
• 种子脚本: scripts/seed-forum-categories.mjs, scripts/fix-forum-categories.mjs

父分类:

板块	Slug	图标	说明
综合讨论区	general	💬	AI话题综合交流
AI工具	ai-tools	🤖	AI工具推荐、测评与讨论
开源技能	skills	⚡	开源AI框架、模型与工具技能
技术深度	tech	🔧	AI技术深度探讨
教程与分享	tutorials	📚	教程、指南与经验分享
社区互动	social	🎪	社区活动与交流

AI工具子分类: 聊天写作/图像创作/视频音频/代码编程/效率办公/数据分析/教育学习 开源技能子分类: LLM框架/Agent框架/RAG技术/模型训练/部署推理/多模态/数据工程 综合讨论子分类: 新手入门/AI资讯/观点讨论 技术深度子分类: 算法原理/模型评测/安全对齐/硬件加速 教程与分享子分类: 入门教程/实战项目/最佳实践 社区互动子分类: 求助问答/求职招聘/闲聊灌水/反馈建议

ForumTopic (论坛话题)

• 字段: categoryId, userId, title, slug, content, isPinned, isLocked, viewCount, replyCount, lastReplyAt
• 全文索引: [title]，联合索引: [categoryId, lastReplyAt]

ForumPost (论坛回复) 🆕

• 字段: topicId, userId, content, isAnswer (标记最佳回答), createdAt, updatedAt
• onDelete: Cascade（话题删除时自动清理回复）

Favorite (收藏) - 联合唯一约束 [userId, toolId], [userId, skillId]

BrowsingHistory (浏览历史) - 自动记录浏览的Tool和Skill

Collection (收藏夹) / CollectionItem (收藏夹项目) - 用户可创建多个收藏夹

---

🆕 积分体系

积分规则

行为	积分	每日上限
发表评论	+5	50
评论被点赞	+2	20
发布论坛话题	+10	无限制
论坛回复	+5	30
发表评价	+8	20
每日登录	+1	1

等级系统 - 20级成长体系 🆕 (类似QQ)

等级	最低积分	徽章	每日限额
LV01	0	⭐	50
LV02	10	⭐	80
LV03	30	⭐⭐	100
LV04	60	⭐⭐	120
LV05	100	⭐⭐	150
LV06	200	⭐⭐⭐	180
LV07	400	⭐⭐⭐	200
LV08	700	⭐⭐⭐	250
LV09	1000	⭐⭐⭐	300
LV10	1500	🌟	400
LV11	2000	🌟	500
LV12	3000	🌟	600
LV13	4500	🌟	700
LV14	6000	🌟🌟	800
LV15	8000	🌟🌟	1000
LV16	11000	🌟🌟	1200
LV17	15000	🌟🌟	1500
LV18	20000	🌟🌟🌟	1800
LV19	30000	🌟🌟🌟	2000
LV20	50000	🌟🌟🌟	3000

旧等级迁移映射: BRONZE→LV01, SILVER→LV03, GOLD→LV06, PLATINUM→LV10

积分奖励系统

• src/lib/level-config.ts — 等级配置（客户端安全，无Prisma依赖）
• src/lib/points-reward.ts — 积分奖励引擎（服务端，含Prisma操作）
  • rewardPoints() — 自动发放积分 + 日限额检查
  • getUserStats() — 获取用户综合统计（积分/评论数/话题数等）
  • getUserPointsHistory() — 积分历史分页查询

---

API接口

评论API (🆕 全新实现)

路由	方法	功能
/api/comments	GET	获取评论列表（支持 toolId/skillId 筛选，含用户等级/积分信息）
/api/comments	POST	创建评论（自动积分奖励，父评论作者自动通知）
/api/comments/[id]/like	POST	评论点赞/取消点赞（切换模式，被赞者+2分，自动通知）

论坛API (🆕 全新实现)

路由	方法	功能
/api/forum/categories	GET	获取论坛板块列表
/api/forum/topics	GET	话题列表（按板块/搜索/排序：latest/hot/active）
/api/forum/topics	POST	创建话题（+10分）
/api/forum/topics/[id]	GET	话题详情（浏览数+1）
/api/forum/topics/[id]	PUT	编辑话题（仅作者）
/api/forum/topics/[id]	DELETE	删除话题（仅作者）
/api/forum/topics/[id]/posts	GET	回复列表
/api/forum/topics/[id]/posts	POST	创建回复（+5分，话题作者自动通知）
/api/forum/topics/[id]/posts/[postId]	PUT	编辑回复（仅作者）
/api/forum/topics/[id]/posts/[postId]	DELETE	删除回复（仅作者）

通知API (🆕 全新实现)

路由	方法	功能
/api/notifications	GET	获取通知列表（含未读数）
/api/notifications	PUT	标记通知为已读（支持指定ids或全部已读）

用户积分API (🆕 全新实现)

路由	方法	功能
/api/user/points?type=stats	GET	获取用户综合统计（积分/评论/话题/评价数）
/api/user/points?type=history	GET	获取积分历史（分页）

---

🆕 组件

论坛组件

组件	文件	说明
ForumBoard	src/components/forum/ForumBoard.tsx	论坛板块卡片（图标/名称/话题数）
ForumTopicCard	src/components/forum/ForumTopicCard.tsx	话题卡片（作者/时间/回复数/浏览数/等级徽章）
ForumEditor	src/components/forum/ForumEditor.tsx	论坛编辑器（字数限制/登录检查/错误提示）
NotificationBell	src/components/forum/NotificationBell.tsx	通知铃铛（红点/下拉面板/未读数）

会员组件

组件	文件	说明
MemberBadge	src/components/common/MemberBadge.tsx	会员等级徽章（⭐🌟 + 积分显示，3种尺寸）
LevelProgress	src/components/common/LevelProgress.tsx	等级进度条（当前/下一级/进度百分比/最高级提示，动态变色）
ShareButton	src/components/common/ShareButton.tsx	分享按钮（支持原生分享/Twitter/QQ/复制链接，带成功反馈）

评论组件

组件	文件	说明
CommentCard	src/components/common/CommentCard.tsx	评论卡片（用户信息/等级徽章/评分/点赞/回复/时间）
CommentThread	src/components/common/CommentThread.tsx	评论列表（分页/点赞/嵌套回复/排序）

---

🆕 页面

/community (追光会 - 论坛首页)

• 板块网格（8个分类卡片）
• 最新话题列表（排序/分页）
• 活跃用户侧边栏

/community/[category] (板块页面)

• 话题列表（按板块筛选）
• 排序切换（最新/热门/活跃）
• 分页导航

/community/topic/[id] (话题详情)

• 话题完整内容展示
• 回复列表（作者标记）
• 回复表单（已登录可用）
• 锁定话题显示提示

/user (🆕 更新的用户中心)

• 个人简介bio展示与编辑 🆕
• 积分等级进度条
• 积分明细记录
• 统计卡片（评论数/话题数/评价数/积分）
• 会员等级徽章
• 快捷入口（收藏/浏览工具/浏览技能）
• 最近浏览历史

/user/[id] (🆕 会员个人空间)

• 用户资料展示（头像/昵称/简介/等级/积分）
• 统计面板（评论/话题/评价/积分）
• 发布的主题列表
• 评论历史列表
• 分享按钮（支持原生分享/Twitter/QQ/复制链接）

---

🔧 技术实现要点

积分自动奖励机制

所有评论/发帖/点赞操作自动通过 rewardPoints() 发放积分，包含：

• 每日上限检查（防刷分）
• 事务写入（积分变更 + 历史记录同时写入）
• 等级自动随积分变化更新

通知自动触发

以下操作自动生成通知：

• 回复评论 → 通知评论作者
• 点赞评论 → 通知评论作者
• 回复话题 → 通知话题作者

权限控制

• 所有写操作（评论/发帖/回复/点赞）需已登录
• 编辑/删除操作仅限作者本人
• 锁定话题禁止回复