[ API DOCS ]

# API 文档

所有 API 端点。响应格式为 { success: boolean, data?: T, error?: { code, message } }。

// 兼容性说明

所有端点标记为 ALL 的均接受任意 HTTP 方法（GET/POST/PUT/DELETE/PATCH）。这是为了兼容部分服务器环境下 OpenResty / WAF 对非 GET 请求的拦截。

需要传递 JSON 数据时，除了标准 Content-Type: application/json 的 POST/PUT 外，也支持 GET 查询参数：?data=URL_ENCODED_JSON。删除操作支持 ?action=delete。

示例：创建冰山图 → GET /api/icebergs?data=%7B%22title%22%3A%22%E6%B5%8B%E8%AF%95%22%7D

冰山图

GET /api/icebergs 冰山图列表（?q=&status=&topic=&cursor=&limit=）；也支持 ?data=<JSON> 创建（GET 兼容）

ALL /api/icebergs 创建冰山图。JSON body 或 GET ?data=<JSON>

GET /api/icebergs/:id 冰山图详情；?data=<JSON> 更新；?action=delete 删除

ALL /api/icebergs/:id/submit 提交审核。?data={<JSON>}

精选

ALL /api/icebergs/[id]/featured 切换精选状态（ADMIN）

层级与词条

GET /api/icebergs/:id/tiers 层级列表；?data=<JSON> 创建

ALL /api/tiers/:id 更新/删除层级。?data=<JSON> 或 ?action=delete

ALL /api/tiers/:id/items 创建词条。?data=<JSON>

ALL /api/items/:id 更新/删除词条。?data=<JSON> 或 ?action=delete

ALL /api/items/read 标记词条已读。?data={<JSON>}

交互

ALL /api/icebergs/:id/vote 投票。?data={<JSON>}

GET /api/icebergs/:id/comments 评论列表（?sort=time|hot）；?data=<JSON> 发表评论

ALL /api/comments/:id/like 点赞评论

ALL /api/comments/:id 删除评论。?action=delete

ALL /api/icebergs/:id/watchlist 切换收藏状态

用户

GET /api/auth/me 当前用户信息

ALL /api/auth/register 邮箱注册。GET ?email=&password=&username=&nickname= 或 JSON body

ALL /api/auth/login 邮箱登录（?email=&password=）或 OAuth（?provider=github|google）

GET /api/auth/logout 登出

ALL /api/auth/change-password 修改密码。?data={<JSON>}

ALL /api/auth/reset-password 重置密码。?email=&newPassword=

ALL /api/auth/email/send-code 发送验证码。?data={<JSON>}

ALL /api/auth/unlink-provider 解除第三方登录绑定。?data={<JSON>}

ALL /api/auth/sessions 管理会话。?action=delete&data=<JSON>

ALL /api/auth/achievements/ack 确认成就通知

GET /api/users/:id 用户资料；?data=<JSON> 更新

ALL /api/users/:id/follow 关注/取关（toggle）

ALL /api/users/:id/warn 警告用户（ADMIN）。?data={<JSON>}

ALL /api/users/:id/restrict 设为只读（ADMIN）。?data={<JSON>}

ALL /api/users/:id/ban 封禁用户（ADMIN）。?data={<JSON>}

ALL /api/users/:id/unban 解除封禁（ADMIN）。?data={<JSON>}

ALL /api/users/:id/role 变更角色（ADMIN）。?data={<JSON>}

ALL /api/users/:id/delete 删除用户及其冰山图（ADMIN）。?data=<JSON>

ALL /api/users/:id/appeal 提交申述。?data={<JSON>}

ALL /api/users/:id/awards 授予勋章。?data=<JSON> 或 ?action=delete&awardId=

ALL /api/users/:id/userboxes 更新用户框。?data={<JSON>}

ALL /api/users/:id/avatar 上传头像（multipart）

搜索与发现

GET /api/search?q= 全文搜索（?cursor= 分页）

GET /api/features 功能开关列表

GET /api/announcements 公告列表；?data=<JSON> 创建（ADMIN）

ALL /api/announcements/:id 编辑（?data=<JSON>）或删除（?action=delete）。ADMIN

创意板

GET /api/ideas 创意列表（?status=&topic=&cursor=）；?data=<JSON> 提交

ALL /api/ideas/:id 更新/删除创意。?data=<JSON> 或 ?action=delete

ALL /api/ideas/:id/vote 创意投票。?data={<JSON>}

ALL /api/ideas/[id]/comments 发表创意评论。?data=<JSON>

ALL /api/ideas/[id]/claimants 加入/退出认领。?data=<JSON>

专题协作

GET /api/projects 项目列表；?data=<JSON> 创建

ALL /api/projects/[slug] 编辑/删除项目。?data=<JSON> 或 ?action=delete

ALL /api/projects/[slug]/members 加入/管理成员。?data=<JSON>

ALL /api/projects/[slug]/tasks 创建/更新/删除任务。?data=<JSON> 或 ?action=delete

ALL /api/projects/[slug]/task-comments 发表任务评论。?data=<JSON>

ALL /api/projects/[slug]/discussions 发送讨论消息。?data=<JSON>

ALL /api/projects/[slug]/link 关联/取消关联。?data=<JSON>

收藏集

GET /api/collections 收藏集列表；?data=<JSON> 创建

ALL /api/collections/:id 编辑/删除收藏集。?data=<JSON> 或 ?action=delete

ALL /api/collections/:id/items 添加/移除冰山图。?data=<JSON> 或 ?action=delete

通知

GET /api/notifications 通知列表

ALL /api/notifications/:id 标记已读

ALL /api/notifications/read-all 全部已读

治理

ALL /api/elections 创建选举。?data=<JSON>

ALL /api/elections/:id 编辑选举。?data=<JSON>

ALL /api/elections/:id/confirm 确认选举结果。?data=<JSON>

ALL /api/elections/:id/vote 选举投票。?data=<JSON>

ALL /api/elections/:id/candidates 候选人操作。?data=<JSON> 或 ?action=delete

ALL /api/rfa 提交 RfA 申请。?data=<JSON>

ALL /api/rfa/:id 取消 RfA。?action=delete

ALL /api/rfa/:id/vote RfA 投票。?data=<JSON>

ALL /api/impeach 发起弹劾。?data=<JSON>

ALL /api/impeach/:id 取消弹劾。?action=delete

ALL /api/impeach/:id/vote 弹劾投票。?data=<JSON>

管理

ALL /api/admin/users 用户列表（ADMIN）

ALL /api/admin/settings 系统配置读写（ADMIN）。GET 读取，?data=<JSON> 写入

ALL /api/admin/reviews/:id 审核操作（approve/reject）。?data=<JSON>

ALL /api/admin/reviews/:id/override 审核覆写。?data=<JSON>

ALL /api/admin/reports/:id 处理举报。?data=<JSON>

ALL /api/admin/reports/batch 批量处理举报。?data=<JSON>

ALL /api/admin/appeals/:id 处理申述。?data=<JSON>

ALL /api/admin/promotions/:id 处理晋升。?data=<JSON>

ALL /api/admin/feedback/:id 处理反馈。?data=<JSON> 或 ?action=delete

ALL /api/admin/achievements 创建成就配置。?data=<JSON>

ALL /api/admin/achievements/:id 编辑/删除成就。?data=<JSON> 或 ?action=delete

ALL /api/admin/achievements/reset-all 重置创始人成就数据

ALL /api/achievements/recheck 复核成就解锁条件

ALL /api/promotion/request 提交晋升申请。?data=<JSON>

其他

ALL /api/reports 提交举报。?data={<JSON>}

ALL /api/upload 图片上传（multipart, ≤2MB）

ALL /api/import/icebergthreads 导入 icebergthreads 数据。?data=<JSON>

ALL /api/icebergs/:id/transfer 转让冰山图所有权。?data=<JSON>

ALL /api/drafts 草稿管理。?data=<JSON> 或 ?action=delete

GET /api/feed 关注流（关注用户的最近动态）