[ 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
// 版本协作接口约定
版本协作写操作统一使用 POST /api/icebergs/:id/repository，
JSON body 通过 action 区分行为。工作副本必须携带当前
revision，提交和合并必须携带预期的分支头；服务端使用乐观锁和可串行化事务，绝不以最后写入静默覆盖并发修改。
WORKSPACE_CONFLICT同一用户的另一个标签页已推进工作副本 revision。
BRANCH_BEHIND分支头已变化，需要载入或合并最新提交。
MERGE_CONFLICT三方合并发现必须人工选择的字段或结构冲突。
REVIEW_REQUIRED缺少有效批准，或仍存在未解除的“要求修改”。
VERSION_CONTROL_ENABLED该冰山图已启用新版本协议；旧编辑页面必须刷新，旧写接口不能绕过提交历史修改主版本。
冰山图
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 切换精选状态（需要 CONTENT_CURATION） 能力、认证与贡献
GET
/api/capabilities 读取当前能力状态、申请记录与发布审核员认证进度；站点管理员可读取待决申请和当前能力 POST
/api/capabilities 提交能力申请或申诉。JSON body: action=apply|appeal POST
/api/capabilities/:id 双人决策、72 小时紧急暂停、永久撤销申请与创始人 break-glass 处置 GET
/api/capabilities/audit 读取不可变能力审计记录（需要 SITE_ADMINISTRATION） GET
/api/contributions/:userId 读取按创作、协作、审阅和服务拆分的贡献档案；旧质量分仅本人可见 POST
/api/review-audits 提交发布决定抽查结果；严重问题会从发布层下架，不修改版本历史 层级与词条
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>} 冰山图版本协作
GET
/api/icebergs/:id/repository?view=state 仓库、当前分支、工作副本 revision、领先/落后与权限状态 GET
/api/icebergs/:id/repository?view=history&limit=50 提交历史；访客仅能读取公开版本可追溯的提交 GET
/api/icebergs/:id/repository?view=diff&base=&head= 任意两次提交的结构化差异 GET
/api/icebergs/:id/repository?view=pulls 合并请求列表；?view=pull&number=N 读取详情 GET
/api/icebergs/:id/repository?view=collaborators 协作者列表与待接受邀请（需仓库权限） POST
/api/icebergs/:id/repository 分支与工作副本：create-branch / archive-branch / save-workspace POST
/api/icebergs/:id/repository 提交与冲突：commit / revert / resolve-conflicts POST
/api/icebergs/:id/repository 审阅与合并：create-pull / review / comment / resolve-comment / merge POST
/api/icebergs/:id/repository 协作者：invite / respond-invite / update-collaborator 交互
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 警告用户（需要 COMMUNITY_MODERATION）。?data={<JSON>} ALL
/api/users/:id/restrict 设为只读（需要 COMMUNITY_MODERATION）。?data={<JSON>} ALL
/api/users/:id/ban 封禁用户（需要 COMMUNITY_MODERATION）。?data={<JSON>} ALL
/api/users/:id/unban 解除封禁（需要 COMMUNITY_MODERATION）。?data={<JSON>} ALL
/api/users/:id/role 旧角色写入口已退役，返回 LEGACY_GOVERNANCE_RETIRED ALL
/api/users/:id/delete 删除用户及其冰山图（需要 SITE_ADMINISTRATION）。?data=<JSON> ALL
/api/users/:id/appeal 提交申述。?data={<JSON>} ALL
/api/users/:id/awards 授予勋章（需要 SITE_ADMINISTRATION）。?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 全部已读 治理
GET
/api/elections 读取旧选举历史；创建、候选、投票和确认写操作已退役 GET
/api/rfa 读取旧 RfA 历史；申请、取消和投票写操作已退役 GET
/api/impeach 读取旧弹劾历史；发起、取消和投票写操作已退役 管理
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 旧晋升写入口已退役；历史读取继续可用 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/achievements/recheck 复核成就解锁条件 ALL
/api/promotion/request 旧晋升申请入口已退役，返回 LEGACY_GOVERNANCE_RETIRED 其他
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 关注流（关注用户的最近动态）