# API模块

## 前台API（无需认证）

### GET /api/health
健康检查端点（Docker HEALTHCHECK 使用）。
- 返回: `{ status: "ok", timestamp, checks: { database: { status: "ok", latencyMs } } }`
- 用于 Docker 容器健康检查 + 负载均衡探测

### GET /api/homepage
获取首页数据（含嵌套分类结构，一级分类+二级子分类）。
- 返回: `{ categories: CategoryWithChildren[], skillCategories: SkillCategoryWithChildren[] }`

### GET /api/categories
获取工具分类树形结构（含子分类），按sortOrder排序。

### GET /api/skill-categories
获取技能分类树形结构（含子分类），按sortOrder排序。

### GET /api/tools
获取已发布工具列表。
- Query: `categoryId`, `pricingModel`, `search`, `page`(默认1), `pageSize`(默认20)
- 返回: `{ tools: Tool[], total, page, pageSize }`

### GET /api/tools/[slug]
获取工具详情（by slug），浏览计数+1。

### GET /api/skills
获取已发布技能列表。
- Query: `category`, `search`, `page`, `pageSize`
- 返回: `{ skills: Skill[], total, page, pageSize }`

### GET /api/skills/[slug]
获取技能详情（by slug），浏览计数+1。

### GET /api/skills/[slug]/review
获取技能的五维评测数据（仅返回PUBLISHED状态）。
- 返回: `{ capability, devExp, costLicense, community, performance, overall, reviews, longArticle?, videoScript?, socialCards?, reviewedAt }`

### GET/POST /api/auth/[...nextauth]
NextAuth认证端点（登录/回调/CSRF等）。

### POST /api/auth/register
用户注册（邮箱+密码）。

### GET /api/categories/[slug]
获取分类详情。

### GET /api/daily-reports
获取AI日报列表。

### GET /api/recommendations
获取推荐内容。

### 评测榜单API（公开）

| 路由 | 方法 | 功能 |
|------|------|------|
| /api/skill-reviews | GET | 获取评测列表（分页，仅PUBLISHED） |
| /api/skill-reviews/rankings | GET | 获取评测榜单：topByRating(评测分TOP10) + topByStarsChange(Stars涨幅周榜TOP10) |

---

## 用户相关API（需NextAuth用户认证）

### /api/user/profile
- GET: 获取当前用户资料
- PUT: 更新用户资料

### /api/user/favorites
| 路由 | 方法 | 功能 |
|------|------|------|
| /api/user/favorites/status | GET | 获取收藏状态 |
| /api/user/favorites | GET | 获取当前用户收藏列表（工具+技能） |
| /api/user/favorites | POST | 添加收藏（body: { targetType, targetId }） |
| /api/user/favorites | DELETE | 取消收藏（body: { targetType, targetId }） |

### /api/user/history
| 路由 | 方法 | 功能 |
|------|------|------|
| /api/user/history | GET | 获取浏览历史 |
| /api/user/history | POST | 记录浏览历史 |

### /api/user/collections
| 路由 | 方法 | 功能 |
|------|------|------|
| /api/user/collections | GET | 获取收藏夹列表 |
| /api/user/collections | POST | 创建收藏夹 |
| /api/user/collections/[id] | GET | 获取单个收藏夹详情 |
| /api/user/collections/[id] | PUT | 更新收藏夹 |
| /api/user/collections/[id] | DELETE | 删除收藏夹 |
| /api/user/collections/[id]/items | GET | 获取收藏夹项目 |
| /api/user/collections/[id]/items | POST | 添加收藏夹项目 |
| /api/user/collections/[id]/items/[itemId] | PUT | 更新收藏夹项目 |
| /api/user/collections/[id]/items/[itemId] | DELETE | 删除收藏夹项目 |

---

## 后台API（需NextAuth认证）

### 分类管理

| 路由 | 方法 | 功能 |
|------|------|------|
| /api/admin/categories | GET | 获取所有分类（含工具数/子分类数） |
| /api/admin/categories | POST | 创建分类 |
| /api/admin/categories/[id] | PUT | 更新分类 |
| /api/admin/categories/[id] | DELETE | 删除分类（有工具/子分类时拒绝） |
| /api/admin/skill-categories | GET | 获取技能分类列表 |
| /api/admin/skill-categories | POST | 创建技能分类 |
| /api/admin/skill-categories/[id] | PUT | 更新技能分类 |
| /api/admin/skill-categories/[id] | DELETE | 删除技能分类 |

### 工具管理

| 路由 | 方法 | 功能 |
|------|------|------|
| /api/admin/tools | GET | 获取所有工具（分页） |
| /api/admin/tools | POST | 创建工具（requireAdmin + 输入校验 + categoryId有效性校验 + slug自动去重） |
| /api/admin/tools/[id] | PUT | 更新工具 |
| /api/admin/tools/[id] | DELETE | 删除工具 |

### 技能管理

| 路由 | 方法 | 功能 |
|------|------|------|
| /api/admin/skills | GET | 获取所有技能（分页） |
| /api/admin/skills/[id] | PUT | 更新技能 |
| /api/admin/skills/[id] | DELETE | 删除技能 |

### 待审核工具

| 路由 | 方法 | 功能 |
|------|------|------|
| /api/admin/pending | GET | 获取待审核工具列表（分页） |
| /api/admin/pending | DELETE | 清空所有待审核工具 |
| /api/admin/pending/[id] | PUT | 编辑待审核工具（websiteUrl变更时自动抓Logo） |
| /api/admin/pending/[id] | DELETE | 删除单个待审核工具 |
| /api/admin/pending/[id]/publish | POST | 发布为正式工具 |
| /api/admin/pending/batch | POST | 批量导入（去重+自动抓Logo） |
| /api/admin/pending/batch-publish | POST | 批量发布（ids数组，最多500条，categoryId动态回退） |
| /api/admin/pending/batch-reject | POST | 批量拒绝（ids数组） |
| /api/admin/pending/fetch-logos | POST | 批量抓取Logo（body: {scope, refetch?}） |

### 待审核技能

| 路由 | 方法 | 功能 |
|------|------|------|
| /api/admin/pending-skills | GET | 获取待审核技能列表（分页） |
| /api/admin/pending-skills | DELETE | 清空所有待审核技能 |
| /api/admin/pending-skills/[id] | PUT | 编辑待审核技能 |
| /api/admin/pending-skills/[id] | DELETE | 删除单个待审核技能 |
| /api/admin/pending-skills/[id]/publish | POST | 发布为正式技能 |
| /api/admin/pending-skills/batch | POST | 批量导入（去重） |
| /api/admin/pending-skills/batch-publish | POST | 批量发布（ids数组，最多500条，categoryId动态回退） |
| /api/admin/pending-skills/batch-reject | POST | 批量拒绝（ids数组） |
| /api/admin/pending-skills/publish-all | POST | 一键发布所有待审核技能（categoryId动态回退） |

### AI发现与检测（提示词+JSON粘贴模式，不调用外部AI API）

| 路由 | 方法 | 功能 |
|------|------|------|
| /api/admin/discover-tools | POST | 导入工具JSON数组（body: {tools: [...], categoryId}），自动去重导入待审核列表 |
| /api/admin/discover-skills | POST | 导入技能JSON数组（body: {skills: [...], categoryId}），自动去重导入待审核列表 |
| /api/admin/discover-skills/run | POST | 一键运行技能探索 |
| /api/admin/discover-news | POST | 导入新闻JSON数组（body: {items: [...]}），自动生成今日AI日报 |
| /api/admin/discover-news | GET | 获取今日AI日报 |
| /api/admin/check-tools | POST | 检测工具网站可访问性+抓取缺失Logo（body: {type: "published"/"pending"}），返回logoFetched/logoMethod/logoUrl |
| /api/admin/update-stars | POST | 更新GitHub Star数（body: {type: "published"/"pending"}） |

### 评测管理

| 路由 | 方法 | 功能 |
|------|------|------|
| /api/admin/reviews | GET | 获取评测列表 |
| /api/admin/reviews/[id] | GET | 获取单个评测详情 |
| /api/admin/reviews/[id] | PUT | 更新评测状态 |
| /api/admin/reviews/[id]/generate | POST | AI生成评测内容（长文+视频脚本+社交卡片） |

### 系统配置

| 路由 | 方法 | 功能 |
|------|------|------|
| /api/admin/system-config | GET | 获取所有配置 |
| /api/admin/system-config | PUT | 批量更新配置（upsert） |

### 角色权限管理

| 路由 | 方法 | 功能 |
|------|------|------|
| /api/admin/roles | GET | 获取所有角色列表 |
| /api/admin/roles | POST | 创建角色 |
| /api/admin/roles/[id] | PUT | 更新角色 |
| /api/admin/roles/[id] | DELETE | 删除角色 |
| /api/admin/permissions | GET | 获取全部权限点列表 |
| /api/admin/user-permissions | GET | 获取当前用户权限（roleId/userId/当前用户） |

### Bot管理API

| 路由 | 方法 | 功能 |
|------|------|------|
| /api/admin/bots/stats | GET | Bot表现统计（每日指标+汇总，支持?days和?botUserId） |
| /api/admin/bots/experiments | GET | A/B实验看板数据（变体/实验/每日指标聚合） |
| /api/admin/bots/experiments/run | POST | 手动触发A/B实验（body: {mode, lookback, noSwitch}） |
| /api/admin/bots/experiments/variants | PATCH | 更新变体（权重/启用/重置样本） |
| /api/admin/bots/experiments/variants | DELETE | 删除变体 |
| /api/admin/bots/adversarial-learning | GET | 对抗学习看板（支持?weeks和?botUserId） |
| /api/admin/bots/adversarial-learning/run | POST | 手动触发对抗学习（body: {weekKey, force, lookback, bot}） |

### 日报管理

| 路由 | 方法 | 功能 |
|------|------|------|
| /api/admin/daily-reports | GET | 获取日报列表 |
| /api/admin/daily-reports/[id] | GET | 获取单个日报详情 |
| /api/admin/daily-reports/[id] | PUT | 更新日报 |
| /api/admin/daily-reports/[id] | DELETE | 删除日报 |
| /api/admin/daily-reports/generate | POST | AI一键生成日报内容 |

### 任务调度API（需NextAuth认证）

| 路由 | 方法 | 功能 |
|------|------|------|
| /api/admin/tasks/configs | GET | 获取全部6个任务配置（合并TaskConfig+默认值） |
| /api/admin/tasks/configs | PUT | 更新/创建任务配置（body: { taskKey, enabled?, cronExpr?, config? }） |
| /api/admin/tasks/logs | GET | 获取任务执行日志（分页，query: taskKey?, page, pageSize） |
| /api/admin/tasks/run | POST | 手动触发任务执行（body: { taskKey }），通过child_process.exec运行对应脚本 |

---

## SystemConfig 配置键

| Key | 类型 | 说明 |
|-----|------|------|
| discoveryPromptConfig | JSON | AI发现提示词配置（含toolPrompt/skillPrompt/newsPrompt/tagPool等） |
| logoFetchConfig | JSON | Logo抓取策略配置 |
| discoverSkillsScript | string | 技能探索脚本源码 |

---

## 开发规则引用
> API 开发必须遵守 [开发规则第十七章 - API设计规范](file:///c:/SGP_KF/ZhuiGuangAI/zhuiguang-ai/.trae/rules/project_rules.md)：
> - 路由骨架：`export const dynamic = "force-dynamic"` + `Promise.all` 并行 + `Cache-Control` 头
> - 错误处理：使用 [api-error.ts](file:///c:/SGP_KF/ZhuiGuangAI/zhuiguang-ai/src/lib/api-error.ts) 的 `badRequest`/`notFound`/`serverError`
> - 响应格式：列表 `{ data, total, page, pageSize }`，统一使用 `total`
> - 状态码：200/201/400/401/403/404/409/500
> - 认证分层：middleware + `requireAdmin()` + `getServerSession()`
> - 分页上限：`Math.min(pageSize, 100)`