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

追光AI - 模块文档索引

项目概述

追光AI是一个AI工具与开源技能目录网站，支持提示词驱动的工具/技能发现、审核管理和前台展示。

技术栈

类别	技术	版本
框架	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
部署	Node.js	18+
端口	8301-8310	默认8301

项目结构

zhuiguang-ai/
├── prisma/           # 数据库Schema + 迁移 + 种子
├── public/           # 静态资源 (logo.png, logos/)
├── scripts/          # 独立脚本 (discover-skills, import-tools)
├── src/
│   ├── app/
│   │   ├── (admin)/admin/  # 后台页面 (15个页面)
│   │   ├── api/            # API路由 (36+个端点)
│   │   ├── categories/     # 前台分类页
│   │   ├── skills/         # 前台技能页
│   │   ├── tools/          # 前台工具页
│   │   ├── login/          # 用户登录页
│   │   ├── user/           # 用户中心(个人资料/收藏)
│   │   ├── globals.css     # 全局样式
│   │   ├── layout.tsx      # 前台布局
│   │   └── page.tsx        # 首页
│   ├── components/   # 组件 (Header, Footer, UI, Common)
│   ├── lib/          # 工具库 (prisma, auth, admin-auth, github, deepseek, logo-fetcher, logo-storage, utils)
│   └── middleware.ts  # 路由保护
├── .env              # 环境变量
├── restart.ps1       # 服务重启脚本(端口8301-8310)
└── package.json      # 依赖配置

模块文档

序号	模块	文档	说明
01	数据库	01-database.md	数据模型、枚举、索引、迁移历史
02	API	02-api.md	前台/后台API端点、SystemConfig配置键
03	页面	03-pages.md	前台/后台页面路由、布局、功能说明
04	组件与样式	04-components-and-styles.md	UI组件、样式系统、设计规范
05	AI发现	05-ai-discovery.md	提示词驱动发现流程、Logo抓取引擎、新闻发现
06	认证	06-auth.md	NextAuth配置、路由保护、登录流程
07	工具库与脚本	07-lib-and-scripts.md	工具函数、独立脚本、运维脚本

环境变量

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>

核心业务流程

提示词模板(页面内嵌) → 用户复制发给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数
• AI新闻发现: 提示词驱动发现AI新闻，按日生成日报，6大分类+热度评分
• 五维评测系统: GitHub数据采集 + DeepSeek AI评测 + 雷达图展示，5维度(capability/devExp/costLicense/community/performance)评分
• 分页: 所有列表页面支持分页（每页20条）
• 浅色主题: 科技感浅色设计系统，毛玻璃效果+渐变文字+精致阴影
• 层级分类: 一级分类+二级分类，左侧导航+标签切换
• 用户系统: 邮箱注册/登录、收藏功能、浏览历史
• 安全加固: 28个后台API全部添加requireAdmin中间件验证
• 端口锁定: 8301-8310区间，禁止使用其他端口