# 追光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"