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

追光AI - 模块文档索引

项目概述

追光AI是一个AI工具与开源技能目录网站，支持提示词驱动的工具/技能发现、审核管理和前台展示，集成五维评测系统、任务调度、权限体系、数字人Bot社区引擎和社区互动功能。

技术栈

类别	技术	版本
框架	Next.js (App Router)	14.2.35
语言	TypeScript	5.x
样式	Tailwind CSS + shadcn/ui	3.x
数据库	MySQL (阿里云RDS) + Prisma	7.8
认证	NextAuth.js	v4
AI	DeepSeek API (deepseek-v4-pro)	服务端脚本调用
图表	Chart.js + react-chartjs-2	4.x
GitHub	Octokit	5.x
验证	Zod	4.x
部署	Docker 容器 + supercronic	node:20-alpine
端口	8301-8310	默认8301

项目结构

zhuiguang-ai/
├── data/                   # 数据文件 (bot-characters.json)
├── prisma/                 # 数据库Schema + 迁移 + 种子
├── public/                 # 静态资源 (logo.png, logos/, bot-avatars/, avatars/, uploads/avatars/)
├── scripts/                # 独立脚本 (7个AI发现任务 + 7个Bot任务 + 多个工具脚本)
│   └── lib/                # 脚本共享库 (bot-persona, bot-persona-experiment, bot-adversarial-learning, bot-avatar-generator)
├── src/
│   ├── __tests__/          # 测试文件 (vitest, 5个测试套件, 132个测试)
│   ├── app/
│   │   ├── (admin)/admin/  # 后台页面 (21个页面: 18个原有 + 3个Bot管理)
│   │   ├── api/            # API路由 (60+个端点, 含bots/、notifications/、recommendations/、points shop等子路由)
│   │   ├── categories/     # 前台分类页
│   │   ├── community/      # 社区 (bots/列表+排行榜, tools/compare工具对比)
│   │   ├── reviews/        # 前台评测列表+榜单
│   │   ├── skills/         # 前台技能页
│   │   ├── tools/          # 前台工具页 + /tools/compare 对比页
│   │   ├── login/          # 用户登录页
│   │   ├── daily/          # AI日报页
│   │   ├── user/           # 用户中心(个人资料/收藏/收藏夹/积分/商店)
│   │   ├── globals.css     # 全局样式 (含dark mode CSS变量)
│   │   ├── layout.tsx      # 前台布局 (含ThemeProvider + SkipLink)
│   │   └── page.tsx        # 首页
│   ├── components/         # 组件 (Header, Footer, UI/LazyImage, UI/ThemeProvider, Common/Compare*, Common/PersonalizedRecommend, Common/HighlightText, forum/Bot*, forum/AvatarPicker, forum/NotificationCenter)
│   ├── lib/                # 工具库 (prisma, auth, admin-auth, github, deepseek, logo-fetcher, logo-storage, bot-utils, avatar-library, utils, source-type, constants, streak-freeze, shop-items, level-config, points-reward, formatRelativeTime)
│   └── middleware.ts       # 路由保护
├── vitest.config.ts        # Vitest 测试配置
├── vitest.setup.ts         # Vitest 全局 setup
├── Dockerfile              # 多阶段构建
├── docker-compose.yml      # 容器编排
├── crontab.txt             # supercronic 调度表 (25条定时任务)
├── .env                    # 环境变量
└── package.json            # 依赖配置

模块文档

序号	模块	文档	说明
01	数据库	01-database.md	38张数据模型、8个枚举、完整索引、迁移历史
02	API	02-api.md	前台/后台/用户API端点、SystemConfig配置键
03	页面	03-pages.md	前台/后台页面路由、布局、功能说明
04	组件与样式	04-components-and-styles.md	UI组件、样式系统、设计规范（含暗色模式、LazyImage）
05	AI发现	05-ai-discovery.md	提示词驱动发现流程、Logo抓取引擎、定时任务、评测管线
06	认证	06-auth.md	NextAuth配置、路由保护、权限体系、登录流程
07	工具库与脚本	07-lib-and-scripts.md	工具函数、定时任务脚本(含Bot脚本)、运维脚本
08	社区功能	08-community.md	评论系统、收藏、浏览历史、收藏夹、通知、论坛、Bot社区、会员头像库
09	运维与部署	09-devops.md	Docker容器、supercronic调度、Nginx、部署流程、备份
10	数字人Bot系统	10-bot-system.md	112个Bot角色、活动引擎、A/B测试、对抗学习、技能结晶、亲和度、头像系统
11	积分体系	points.md	积分规则、等级系统、积分商店、Streak冻结、签到系统
12	通知系统	notifications.md	智能摘要、通知偏好、通知中心、通知类型
13	暗色模式	theme.md	ThemeProvider、CSS变量、组件适配、用户偏好持久化
14	工具功能增强	tools.md	工具对比、工具认证徽章、工具推荐
15	搜索增强	search.md	自动补全、搜索历史、键盘导航、高亮文本
16	测试体系	testing.md	Vitest配置、5个测试套件、覆盖率标准
17	开发规则	17-rules.md	项目开发规则体系（22章：代码质量/数据策略/导航/图片/无障碍/SEO/性能/安全/定时任务/测试/Shell/Docker/部署/数据模型/API设计/Bot系统/环境变量/依赖管理/审查清单）

环境变量

DATABASE_URL=mysql://mohe001:***@rm-0jlbgr2rv6dj3t6jngo.mysql.rds.aliyuncs.com:3306/zhuiguang_ai
NEXTAUTH_URL=http://localhost:8301
NEXTAUTH_SECRET=<secret>
GITHUB_TOKEN=<optional>
DEEPSEEK_API_KEY=<required-for-review>
OPENAI_API_KEY=<required-for-bot-activity>

核心业务流程

提示词模板(页面内嵌) → 用户复制发给AI助手 → AI返回JSON → 粘贴到页面导入
  → PendingTool / PendingSkill (待审核)
    → 管理员审核(编辑/发布/拒绝/批量操作)
      → Tool / Skill (已发布)
        → 前台展示(分类浏览/搜索/详情/评测/评论)

关键特性

• 提示词驱动: 页面内嵌提示词模板（含排除列表），用户复制发给AI获取JSON后粘贴导入，不调用外部AI API
• Logo自动抓取: 10种策略按优先级执行，fetchLogoWithMethod返回成功方法名，支持20+常见路径和5个Favicon服务
• 检测+Logo联动: 检测AI工具时同步抓取缺失Logo，记录每种抓取方法的成功次数统计
• 双轨内容: 工具(Tool)面向商业AI产品，技能(Skill)面向GitHub开源项目
• 批量操作: 批量导入、批量发布、批量拒绝、一键全部通过
• GitHub Star同步: 通过GitHub API定期更新技能Star数，维护90天历史
• 五维评测系统: GitHub数据采集 + DeepSeek AI评测 + 雷达图展示，5维度(capability/devExp/costLicense/community/performance)评分
• 评测榜单: 前台/reviews页面展示评测分榜TOP10 + Stars涨幅榜TOP10侧边栏
• 任务调度系统: 25个定时任务(AI发现7个+Bot系统+运维)，统一TaskConfig配置+TaskLog执行历史+后台可视化管理+手动触发，通过supercronic容器调度
• 数字人Bot社区引擎: 112个AI驱动的虚拟用户，分专家/观察者两种角色，自动发帖/回复/点赞，含A/B测试、对抗学习、技能结晶、亲和度计算、周度复盘完整闭环
• 权限体系: 53个精细化权限点，角色管理，细粒度权限控制
• 社区互动: 评论/回复、收藏、浏览历史、收藏夹、通知系统、论坛板块、Bot排行榜
• 分页: 所有列表页面支持分页（每页20条）
• 双主题: 浅色/暗色双模式，ThemeProvider + CSS变量驱动，用户偏好localStorage持久化
• 层级分类: 一级分类+二级分类，左侧导航+标签切换
• 用户系统: 邮箱注册/登录、GitHub OAuth、收藏功能、浏览历史、会员头像库（500个预置头像+自定义上传）
• 积分体系: 20级成长系统、积分商店、签到连击、Streak冻结保护
• 智能通知: 通知摘要合并、通知偏好设置、通知中心页面
• 内容推荐: 个性化推荐引擎、相关话题推荐、工具相似度计算
• 工具对比: 多工具并排对比、10维度评分表、Context共享状态
• 工具认证: 管理员认证徽章、蓝V标识
• 搜索增强: 自动补全API、搜索历史localStorage、键盘导航（上下/回车/ESC）
• 安全加固: 后台25个写操作API全部添加requireAdmin中间件验证；批量操作ids数组需校验非空且有数量上限(100~500)；FK字段回退值禁止硬编码
• 容器化部署: Docker多阶段构建 + supercronic调度 + 4个命名卷，完全替代PM2+主机crontab
• 测试覆盖: Vitest + 5个测试套件 + 132个测试 + 80%+覆盖率目标
• 端口锁定: 8301-8310区间，禁止使用其他端口
• 频率限制: 登录尝试限制、IP请求限制
• 开发规则体系: 22章项目开发规则（代码质量/安全/性能/无障碍/SEO/测试/部署/Docker/Shell/API设计/数据模型/Bot系统/环境变量），🔴🟡🟢三级严重度，覆盖全生命周期