# EveryPublish Web-only V1 方案

> 版本：V1-web · 2026-08-21
> 当前交付面只有网页端。macOS/Windows 客户端、Agent 配对、设备管理和 Agent WSS 暂停，不属于本阶段验收。

## 1. 目标

EveryPublish V1 是部署在当前设备上的本地 Web 控制台：用户打开浏览器登录，在同一个网页里管理平台账号、素材、发布任务、审核、挑战和结果。发布执行在服务器进程内的本地 worker 完成，不要求安装客户端、不要求生成配对码、不要求绑定设备。

```text
浏览器（React + TDesign）
          │ HTTPS/REST + Browser WebSocket
          ▼
Go server（认证、工作区、素材、任务、挑战、审计）
          │
          ├── WebExecutor（V1 本地模拟/联调，默认可用）
          └── PlatformAdapter（真实平台，按平台逐个接入）
                    │
                    └── 本机浏览器 profile / cookie vault / QR 登录
```

## 2. 明确停止项

- 暂停 `client/macos`、`client/desktop`、`client/ui` 的新功能、安装包和启动验收。
- 暂停网页端 Agent 配对码、Agent 设备列表、Agent 总览、远程吊销和客户端日志入口。
- 暂停依赖 Agent WSS 的任务下发；V1 任务由 WebExecutor/PlatformAdapter 在 Go server 所在设备执行。
- 不把当前已有的“假 Agent 在线”当作网页端完成证据。

旧客户端代码保留在仓库中作为后续迁移材料，但不得出现在 V1 菜单、默认流程和验收清单中。

## 3. V1 页面

| 页面 | 必须可用的功能 |
|---|---|
| 工作台 | 今日任务统计、成功/失败、待处理挑战、最近任务、执行器健康 |
| 账号管理 | 添加账号、平台选择、网页扫码登录、Cookie 导入、登录状态检查、重新登录、删除未绑定账号 |
| 素材库 | 视频/图片上传、进度、SHA-256 去重、预览、分组/标签、删除、下载直链 |
| 新建发布 | 选择素材、选择一个或多个账号、统一标题/正文/标签、封面、立即/定时、草稿保存 |
| 任务中心 | 队列/运行/成功/失败/取消、进度、失败原因、重试、取消、详情、状态时间线和结果链接 |
| 排期日历 | 按日期查看和编辑可编辑任务 |
| 审核中心 | 待审、通过、驳回和批注；可配置跳过审核的本地模式保留在设置 |
| 挑战中心 | QR 图片、验证码、APP 确认、过期、重发、解决记录 |
| 通知 | 任务失败、登录过期、挑战到达、审核结果 |
| 成员/工作区 | 单机 V1 保留基础工作区和成员模型，权限先保证 owner/admin/operator/reviewer 隔离，并支持成员切换工作区 |
| 设置 | 工作区资料、安全（密码修改）；通知统一使用站内通知页，外部通知渠道不进入 V1 |
| 审计日志 | 登录、素材、账号、任务、审核、挑战和设置操作 |

## 4. 连接与状态

V1 只使用网页到 Go server 的两种连接：REST 完成请求，Browser WebSocket 推送任务/挑战/通知。浏览器刷新后通过 REST 补齐状态，不能只依赖 WebSocket。

```text
打开网页
  ├─ 未登录 ──> 登录页 ──失败/限速──> 保留表单并说明原因
  └─ 已登录 ──> GET /auth/me + GET /tasks + GET /challenges
                  │
                  ├─ WebSocket 已连接 ──> 实时更新
                  └─ WebSocket 失败 ──> 顶部显示“实时连接断开”，REST 轮询兜底
```

任务状态统一为：`draft → pending_review → queued → dispatched → running → success/failed`，可从 `failed → queued` 重试，`draft/rejected → deleted`，可取消状态 → `cancelled`。

## 5. 执行器边界

`WebExecutor` 是 Go server 的稳定接口，先提供 `mock` 实现保证本地全链路，随后按平台接入真实执行器。真实执行器需要从参考仓库借鉴 Playwright/profile/cookie/QR/SSE 逻辑，但必须隔离在 adapter 目录，不能把 Python 示例代码直接散落到 API handler。

```text
TaskDispatcher
  ├─ 读取任务与账号
  ├─ 生成短时素材访问令牌
  ├─ WebExecutor.Submit(ctx, task)
  ├─ 记录 running / progress / result / error
  └─ 广播 task.status
```

当前实现状态：`mock` 固定走本机 mock executor；`web` 对已注册平台走本机 PlatformAdapter，未接入的平台明确保留 mock fallback。B站已接入 QR 登录、加密凭据、UPOS 分片上传和投稿；真实平台成功必须有平台返回的 URL/receipt，`mock://` 只能用于自动化测试。

真实平台登录需要用户在浏览器或手机完成扫码；当前无法人工扫码时，只能验证 QR 产生、挑战状态、超时、重发和 mock 解决，不能声称真实账号登录已验收。

## 6. 验收门槛

### 本地自动验收

1. 注册/登录/刷新/退出和过期 token。
2. 上传素材、重复 SHA-256 去重、预览和删除。
3. 创建草稿、提交审核、通过/驳回、重提、取消、重试。
4. mock executor 将任务推进到 success，并写入结果 URL/receipt。
5. Browser WebSocket 断开后 REST 仍可恢复页面状态。
6. 账号登录流程可产生 QR，挑战可重发/过期/模拟解决。
7. 普通成员不能调用管理员动作，workspace 数据不能串租户。

自动化 smoke 还必须覆盖：注册后的再次登录、refresh token 轮换、空挑战确认值被拒绝、签名素材直链只能使用一次、未登录账号不能创建发布任务，以及 `EXECUTOR_MODE=mock` 和 `EXECUTOR_MODE=web` 两种本机执行模式。

### 人工验收（用户执行）

- 用户在目标平台完成一次真实扫码登录。
- 用户选一个真实账号、上传真实素材、发布一个测试任务。
- 用户确认目标平台内容、任务结果和失败重试。

## 7. 参考代码许可和借鉴边界

- `references/social-auto-upload`：MIT，HEAD `1c66b7d`；借鉴 uploader 抽象、统一校验、QR 登录和平台 CLI 参数，不直接复制其当前 Web 层（README 已说明 Web 非主线）。
- `references/social-auto-upload-web-ui`：MIT，HEAD `85e783c`；借鉴 Flask 蓝图拆分、Registry、SSE 登录、串行任务队列、素材中心和批量发布参数。
- `references/MediaPublishPlatform`：MIT，HEAD `0813236`；借鉴统一 BaseFileUploader、批量账号轮换、定时参数和发布记录页面，但不复制其 SQLite/明文 Cookie/全局 CORS。
- 任何复制的 MIT 代码必须保留版权/许可证说明；新增代码优先用当前 Go/React 技术栈重写，参考仓库作为 `references/` 只读材料。