zhuiguang-ai/.trae/rules/project_rules.md

追光AI 项目开发规则

端口规范

• 开发端口: 8301-8310
• 默认端口: 8301
• 重启脚本仅扫描8301-8310范围
• 强制要求：本项目端口必须锁定在8301-8310区间内，禁止使用其他端口，因为本服务器同时运行其他产品

技术栈

• Next.js 14 (App Router) + TypeScript
• Tailwind CSS + shadcn/ui
• Prisma 7.8 + MySQL (阿里云RDS)
• NextAuth.js v4 (Credentials Provider)
• DeepSeek API (deepseek-v4-pro) — 用于技能五维评测生成（服务端脚本调用）

代码风格

• 不添加注释（除非明确要求）
• 使用中文作为UI文案和提示词语言
• TypeScript严格模式，零编译错误
• 组件使用 "use client" 标记客户端组件
• 路径别名: @/* → ./src/*
• 禁止在代码中硬编码任何AI API Key
• 禁止在代码中调用任何外部AI API（DeepSeek、OpenAI等） — 前台/后台页面代码中禁止调用；服务端脚本(scripts/)中允许通过环境变量调用DeepSeek API和GitHub API
• 所有发现/导入功能通过页面提示词+JSON粘贴方式完成，不调用外部接口

构建与检查

• 修改代码后必须运行 npx tsc --noEmit 确认零错误
• 重启服务使用 pwsh -ExecutionPolicy Bypass -File restart.ps1
• 开发服务器: npm run dev (端口8301)

数据库

• 云数据库: 阿里云RDS MySQL
• 连接: mysql://mohe001:***@rm-0jlbgr2rv6dj3t6jngo.mysql.rds.aliyuncs.com:3306/zhuiguang_ai
• Prisma单例模式防止热重载多实例
• 修改Schema后: npx prisma migrate dev --name <描述>

认证

• 管理员: admin@zhuiguang.ai / admin123
• JWT Session策略
• middleware.ts保护/admin路由（跳过/admin/login）
• 后台API需requireAdmin中间件验证（src/lib/admin-auth.ts）
• 用户注册/登录: NextAuth Credentials Provider，支持邮箱+密码

API约定

• 前台API: /api/ 前缀，无需认证
• 后台API: /api/admin/ 前缀，需NextAuth认证
• 分页参数: page(默认1), pageSize(默认20)
• 返回格式: { data, total, page, pageSize } 或 { success, error }
• 批量操作: body中传 ids 数组

页面路由

• 前台: /, /tools, /tools/[slug], /categories/[slug], /skills, /skills/[slug], /login, /user, /user/favorites
• 后台: /admin/login, /admin/pending, /admin/pending-skills, /admin/tools, /admin/skills, /admin/categories, /admin/skill-categories, /admin/discover-tools, /admin/check-tools, /admin/discover-skills, /admin/update-skills, /admin/discover-news, /admin/system-config

五大操作指令

用户使用以下五个命令时，必须跳转到对应页面理解流程并按流程执行。 所有页面均为"提示词+JSON粘贴导入"模式，不调用任何外部AI API。

探索AI工具

• 页面: /admin/discover-tools
• 流程: 选分类 → 复制提示词发给AI → 粘贴JSON → 导入审核列表 → 抓取Logo
• 导入API: POST /api/admin/discover-tools body: { tools: [...], categoryId }
• API接收前端提交的工具JSON数组，自动去重导入待审核列表
• Logo抓取API: POST /api/admin/pending/fetch-logos
• 工具分类(20个): 文本生成(165), 图像生成(174), 视频生成(183), 音频与语音(191), 代码开发(199), AI Agent(208), 办公效率(216), 设计与创意(224), 营销与SEO(231), 数据分析(238), 教育与学习(245), 搜索与信息(252), 安全与合规(258), 医疗健康(264), 金融与法律(270), 电商与零售(276), 3D与游戏(282), 科学研究(288), 模型与框架(294), 聊天机器人(302)

检测AI工具

• 页面: /admin/check-tools
• 流程: 选择范围(已发布/待审核) → 一键检测+抓取Logo → 处理失效工具
• 检测API: POST /api/admin/check-tools body: { type: "published" | "pending" }
• 系统自动逐一GET请求检测网站可访问性，同时自动抓取缺失Logo并记录成功方法名
• 删除API: DELETE /api/admin/tools/{id} / /api/admin/pending/{id}

探索AI技能

• 页面: /admin/discover-skills
• 流程: 选分类 → 复制提示词发给AI → 粘贴JSON → 导入审核列表
• 导入API: POST /api/admin/discover-skills body: { skills: [...], categoryId }
• API接收前端提交的技能JSON数组，自动去重导入待审核列表
• 技能分类(20个父分类): 代码生成(1), 测试(10), 代码质量与分析(20), 安全(29), 文档(36), 架构与设计(43), 需求工程(49), DevOps与部署(56), 调试与错误处理(62), 形式化验证(69), 维护与重构(76), 版本控制与协作(82), 开发工具(86), UI/UX设计(91), 科学研究(95), 金融(103), 云服务(109), 移动开发(115), AI/ML工程(120), 营销与增长(127)

更新Skill技能

• 页面: /admin/update-skills
• 流程: 选择范围(已发布/待审核) → 一键更新 → 自动同步星级
• 更新API: POST /api/admin/update-stars body: { type: "published" | "pending" }
• 系统自动从GitHub/Gitee/GitCode API获取最新星级评分并写入数据库

AI新闻发现

• 页面: /admin/discover-news
• 流程: 复制提示词发给AI → 粘贴JSON → 导入今日新闻
• 导入API: POST /api/admin/discover-news body: { items: [...] }
• API接收前端提交的新闻JSON数组，自动生成今日AI日报
• 新闻分类: 产品发布/融资投资/技术突破/政策法规/开源项目/行业事件

通用执行规则

1. 禁止调用任何外部AI API，所有发现/导入功能通过页面提示词+JSON粘贴方式完成
2. 页面提供提示词模板（含排除列表），用户复制发给AI助手获取JSON，粘贴到页面导入
3. 导入API接收JSON数组，自动去重（名称+网址），导入待审核列表
4. 导入工具后建议执行Logo抓取，确保所有工具有图标
5. 所有提示词要求: 优先推荐国产AI工具/技能，国内可直连，中文友好
6. 检测工具时：系统自动GET请求检测网站可访问性，同时抓取缺失Logo
7. 更新技能时：系统自动从GitHub/Gitee/GitCode API获取最新星级

设计系统

• 浅色主题，HSL CSS变量
• 圆角: rounded-xl / rounded-2xl
• 边框: border-border/40 (40%透明度)
• 背景: bg-white/80 (毛玻璃) / bg-white/60 (卡片) / bg-muted/50 (输入框)
• 阴影: shadow-sm (卡片) / shadow-md (悬浮)
• 动画: transition-all duration-200
• 自定义工具类: .glow-sm, .gradient-text, .glass, .card-shine, .dot-grid, .animate-fade-in
• 颜色规范: 文字用 -600/-700 (非-400)，背景用 -50 (非-500/10)，边框用 -200/60 (非-500/20)
• 输入框: bg-muted/50 focus:bg-white focus:ring-2 focus:ring-primary/10

环境变量

• GITHUB_TOKEN: GitHub Personal Access Token（可选，提升API限流从60→5000次/小时）
• DEEPSEEK_API_KEY: DeepSeek API Key（用于技能评测生成脚本）

踩坑记录

• Next.js 14不支持useActionState，登录页用原生表单POST
• Prisma MariaDB adapter需要连接字符串方式初始化
• 图片域名需在next.config.mjs中配置remotePatterns
• 热重载后需清除.next缓存: 删除.next目录后重启
• Chart.js组件需用dynamic import + ssr: false，不支持服务端渲染
• Prisma 7.8需通过PrismaMariaDb适配器初始化，不能直接new PrismaClient()
• 服务器环境SSL证书问题: 运行脚本需设置$env:NODE_TLS_REJECT_UNAUTHORIZED="0"