# EveryPublish Web API（Web-only V1）

Base URL：`http://127.0.0.1:8090/api/v1`。成功响应为 `{code:0,message:"ok",data:...}`，失败响应包含业务 `code/message`。

## 认证

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/auth/register` | 注册并返回 token |
| POST | `/auth/login` | 登录并返回 access/refresh |
| POST | `/auth/refresh` | refresh 轮换 |
| POST | `/auth/logout` | 登出 |
| POST | `/auth/password` | 修改当前用户密码 |
| GET | `/auth/me` | 当前用户 |
| POST | `/auth/switch-workspace/:id` | 切换到本人所属工作空间并签发新 token |

## 核心业务

| 模块 | 路径 | 说明 |
|---|---|---|
| 工作区/成员 | `/workspaces`、`/members` | 工作区与角色权限 |
| 账号 | `/accounts`、`/accounts/:id/bind`、`/accounts/:id/credentials`、`/accounts/:id/check`、`/accounts/:id/unbind` | 网页本机账号、扫码登录、凭据导入和登录检查 |
| 素材 | `/materials`、`/materials/:id/url`、`/files/:token` | multipart、SHA-256 去重、一次性下载直链和 `?inline=1` 预览 |
| 任务 | `/tasks`、`/tasks/:id/events`、`submit`、`approve`、`reject`、`retry`、`cancel` | 状态机、时间线和审核 |
| 挑战 | `/challenges`、`/challenges/:id/solve`、`resend`、`suspend` | QR/验证码/APP 确认 |
| 通知 | `/notifications`、`/notifications/:id/read`、`read-all` | 站内通知 |
| 审计 | `/audit-logs` | 业务操作记录 |

### 账号绑定返回值

`POST /accounts/:id/bind` 对同一账号的已有 active challenge 幂等，返回 `challengeId、qrUrl、qrToken、prompt、expiresAt`。网页显示 `qrUrl`，服务端后台轮询平台状态；用户使用目标平台手机客户端扫码，不生成 EveryPublish 客户端配对码。真实二维码由适配器确认，不能调用 `/challenges/:id/solve` 伪造完成；只有显式 `mock://` 联调挑战允许使用 `value` 解决。

`POST /accounts/:id/credentials` 接收 `{ "cookies": "..." }`，仅在 `EXECUTOR_MODE=web` 且平台适配器已注册时可用。成功后只返回账号状态；Cookie 不进入响应、审计详情或 WebSocket payload。

`POST /accounts/:id/check` 调用平台适配器的凭据检查；有效时更新 `active/lastActiveAt`，失效时更新 `expired/lastError`，不会返回 Cookie。

写操作按 workspace member role 限制：账号资料、素材和任务由 owner/admin/operator 处理；解绑、删除和工作区成员管理需要 owner/admin；审核由 reviewer/admin 处理；viewer 只读。

## Browser WebSocket

`GET /ws/browser?token=<accessToken>`，浏览器连接后接收：

- `task.status`：任务状态/结果/错误。
- `challenge.status`：挑战创建、解决、过期。
- `notification.new`：新通知。

WebSocket 不是首屏数据源；页面必须先 REST 拉取，断线时通过 REST 轮询兜底。

## 本地 mock 执行

设置 `EXECUTOR_MODE=mock`（默认）后，审核通过的任务由 Go server 本机执行，状态依次为 `queued → dispatched → running → success`，结果 URL 使用 `mock://` 协议，仅用于自动化联调。

设置 `EXECUTOR_MODE=web` 后，已注册的平台适配器在 Go server 所在设备执行。当前已接入 B 站：二维码轮询、workspace/account 隔离加密凭据、UPOS 分片上传和投稿；其它未接入平台保留明确的 mock fallback，不能把 mock URL 当作真实平台结果。

B 站 adapter 的 `BILIBILI_MEMBER_BASE`、`BILIBILI_PASSPORT_BASE` 和 `BILIBILI_UPOS_SCHEME` 可在本地 stub 联调时覆盖；生产环境保持官方地址并遵守平台规则。