EveryPublish/docs/api.md

EveryPublish 服务端接口文档（v1）

基地址：/api/v1 · 统一响应：{"code":0,"message":"ok","data":{...}}，code!=0 为业务错误。 认证：Authorization: Bearer <accessToken>（15min，前端自动用 refresh 轮换）。

业务错误码

code	含义
1001	参数不合法
1002	未登录/令牌无效
1003	无权限
1004	资源不存在
2001	邮箱已注册
2002	邮箱或密码错误
2003	刷新令牌无效
2004	已是成员
2005	邀请链接无效或过期
1006	需要两步验证（2FA，默认关）
3001-3005	业务冲突（账号不可删/已绑定/挑战已结束/链接过期/任务状态不允许）

认证 /auth

方法	路径	说明
POST	/auth/register	注册 {email,password,nickname} → 返回令牌对+用户+默认工作空间
POST	/auth/login	登录 {email,password} → 令牌对+用户
POST	/auth/refresh	{refreshToken} → 轮换新令牌对（旧 refresh 立即吊销）
POST	/auth/logout	登出（吊销 refresh）
GET	/auth/me	当前用户+工作空间+角色

工作空间 /workspaces（登录）

方法	路径	说明
POST	/workspaces	创建 {name}（创建者为 owner）
GET	/workspaces	我所在的工作空间列表
PUT	/workspaces/:id	改名（owner/admin）

成员 /members（登录）

方法	路径	说明
GET	/members	成员列表（含 email/nickname）
POST	/members/invite	邀请 {email,role} → {token,link}（owner/admin；role: admin/operator/reviewer/viewer）
POST	/members/join	接受邀请 {token}（须与登录邮箱一致）
PUT	/members/:id/role	改角色 {role}（不可改 owner）
DELETE	/members/:id	移除（不可移除 owner）

账号台账 /accounts（登录）

方法	路径	说明
GET	/accounts?platform=&status=&page=&size=	台账列表（状态：unbound/binding/active/suspended/expired）
POST	/accounts	新增 {platform(douyin/kuaishou/xiaohongshu/bilibili),accountName,avatarUrl?,ipProfile?}
PUT	/accounts/:id	改资料（名称/头像/IP 画像）
DELETE	/accounts/:id	删除（仅 unbound）
POST	/accounts/:id/bind	发起绑定 → 创建挑战记录（status→binding）→ {challengeId}

素材 /materials（登录）

方法	路径	说明
GET	/materials?kind=&group=&page=&size=	素材列表
POST	/materials	multipart 上传：file 字段 + 可选 group/tags；流式 sha256，同工作区去重（dedup:true 返回已有素材）
GET	/materials/:id/url	生成签名直链（10 分钟、一次性）→ {url,expiresAt}
DELETE	/materials/:id	删除素材及文件
GET	/files/:token	凭 token 下载文件（无鉴权，token 即凭证；一次性）

任务 /tasks（登录；状态机）

flowchart LR
  D[draft] -->|submit| P[pending_review]
  P -->|approve| Q[queued] -->|dispatch| DP[dispatched] -->|start| R[running]
  R -->|success| S[success]
  R -->|fail| F[failed] -->|retry| Q
  R -->|suspend| SU[suspended] -->|resume| Q
  P -->|reject| RJ[rejected] -->|resubmit| P
  D -->|cancel| C[cancelled]
  Q -->|cancel| C
  DP -->|cancel| C
  R -->|cancel| C
  SU -->|cancel| C

方法	路径	说明
GET	/tasks?status=&schedule=&page=&size=	任务列表
POST	/tasks	新建草稿 {title,content?,tags?,accountIds[],materialIds[],scheduleAt?(unix ms),priority?(1-10)}
GET	/tasks/:id	详情
PUT	/tasks/:id	编辑（仅 draft/rejected）
DELETE	/tasks/:id	删除（仅 draft）
POST	/tasks/:id/submit	提交审核
POST	/tasks/:id/approve	审核通过 → queued（通知创建人）
POST	/tasks/:id/reject	驳回 {note}（通知创建人）
POST	/tasks/:id/resubmit	驳回后重提
POST	/tasks/:id/retry	失败重试 → queued
POST	/tasks/:id/cancel	取消

挑战 /challenges（登录）

方法	路径	说明
GET	/challenges?status=&accountId=	挑战列表（过期自动置 expired）
POST	/challenges/:id/solve	人工完成 {value?}（验证码/APP 确认；扫码由 Agent 完成）
POST	/challenges/:id/resend	一键重发（expired/suspended → active，重置 30min）
POST	/challenges/:id/suspend	挂起

通知 /notifications（登录）

方法	路径	说明
GET	/notifications?kind=	我的通知 + unread 计数
POST	/notifications/:id/read	标记已读
POST	/notifications/read-all	全部已读

审计 /audit-logs（登录）

方法	路径	说明
GET	/audit-logs?userId=&action=&page=&size=	审计日志（中间件自动埋点：登录/登出/增删改/审核/挑战等）

设备配对 /agent

方法	路径	鉴权	说明
POST	/agent/pair-code	Bearer	生成配对码（6 位，5 分钟一次性）
POST	/agent/pair	无（凭码）	配对 {code,deviceName,os,version,publicKey(Ed25519 base64)} → {deviceId}
GET	/agent/devices	Bearer	设备列表（在线状态）

WSS 双通道

Agent 通道 /ws/agent（Ed25519 设备签名，无 JWT）

方向	消息	说明
C→S	hello	{deviceId,nonce,ts,sig(base64, 签名原文 nonce+|+ts),version}
S→C	hello.ack	{serverNonce,sessionId,serverTs,sig}
C→S	heartbeat(10-30s) / S→C heartbeat.ack	保活
S→C	task.push	任务下发 {taskId,platform,accountId,title,content,tags,materialUrls(一次性签名直链),priority}
C→S	task.ack	{taskId,accept,reason?}（accept→running）
C→S	task.result	{taskId,status(success/failed),publishedUrl,receipts,error,finishedAt}
S→C	challenge.new	绑定扫码挑战 {challengeId,accountId,platform,kind,qrToken,qrUrl,prompt,expiresAt}
C→S	challenge.ack / challenge.solve	应答 / 完成（solve 后账号→active）

浏览器通道 /ws/browser?token=<JWT>（只读订阅）

事件	说明
task.status	{taskId,status,errorMessage,publishedUrls}（下发/执行/成功/失败实时推送）
agent.status	{deviceId,online}
challenge.status	{challengeId,status,accountId}

实测：任务下发延迟（approve→task.push）≈ 28.7ms（本机，硬指标 <300ms）。

健康检查

方法	路径	说明
GET	/health	服务健康（db/redis 状态）