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

API模块

前台API（无需认证）

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/当前用户）

日报管理

路由	方法	功能
/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	技能探索脚本源码