# EveryPublish 逻辑图全集（最小闭环版）

> 2026-08-20 · 汇总自 docs/multi-platform-publish-plan.md 与 docs/system-design.md，MVP 范围已标注。

## 图索引

| # | 图 | 回答的问题 | 来源 | PNG |
|---|---|---|---|---|
| 1 | 总体架构（双通道） | 系统由哪些部分组成、如何协作 | plan §3 | [PNG](../diagrams/png/01-总体架构.png) |
| 2 | 控制面/数据面分离 | 为什么我方服务器不会被封 | plan §3.1 | [PNG](../diagrams/png/02-控制面-数据面分离.png) |
| 3 | MVP 部署拓扑（内网联调） | 一期怎么跑起来（Mac+Windows） | 新增 | [PNG](../diagrams/png/03-MVP-部署拓扑.png) |
| 4 | IP 路由逻辑 | 账号与 IP 如何绑定 | plan §8 | [PNG](../diagrams/png/04-IP-路由逻辑.png) |
| 5 | 重试与降级状态机 | 失败/挑战/风控如何流转 | plan §21.2 | [PNG](../diagrams/png/05-重试与降级状态机.png) |
| 6 | 全链路时序（含异常分支） | 用户→端→平台→用户完整路径 | plan §21.1 | [PNG](../diagrams/png/06-全链路时序.png) |
| 7 | 二次验证挑战兜底流程 | 扫码/验证码/APP确认怎么处理 | plan §21.3 | [PNG](../diagrams/png/07-二次验证挑战兜底流程.png) |
| 8 | 登录链路优化时序 | 登录为何能从 10s 级压到 2s 级 | plan §22 | [PNG](../diagrams/png/08-登录链路优化时序.png) |
| 9 | Agent 配对时序 | 客户端如何安全接入 | system-design §8.2 | [PNG](../diagrams/png/09-Agent-配对时序.png) |
| 10 | 素材传输链路 | 文件怎么上传/下发/回传 | system-design §12 | [PNG](../diagrams/png/10-素材传输链路.png) |
| 11 | 开发排期甘特 | 何时完成最小闭环 | 新增 | [PNG](../diagrams/png/11-开发排期甘特.png) |

## 图1 总体架构（双通道）

**MVP 范围**：一期只做通道B（Agent 自动化）+ 国内四平台（抖音/快手/小红书/B站）；通道A（官方API）与视频号为二期。

```mermaid
flowchart TB
    subgraph WEB["① 控制端 Web 多租户SaaS"]
        U["运营 / 审核 / 管理员"]
        W["任务编排 · 素材库 · 账号台账 · 审计"]
        U --- W
    end
    subgraph CORE["② 调度中心 服务器"]
        Q["任务队列 Redis(asynq) · 状态机 · 排期器"]
        API["通道A 官方API执行器 OAuth"]
        AGW["通道B Agent网关 WSS注册/心跳/路由"]
    end
    subgraph AGENT["③ 执行端 Agent 客户侧安装"]
        WS["WSS长连接 主动出网回连"]
        VAULT["凭据保险库 cookie本地加密"]
        ROUTER["代理路由器 一账号一IP"]
        PA["浏览器执行器 go-rod CDP 独立档案"]
        QR["扫码登录面板"]
    end
    WEB -->|"任务下发"| Q
    Q -->|"通道A 官方API"| API
    Q -->|"通道B 自动化"| AGW
    AGW --> WS --> ROUTER --> PA
    VAULT --- PA
    QR --- VAULT
    API --> INT["国际 X/IG/YouTube/TikTok"]
    PA --> DOM["国内 抖音/快手/小红书/视频号/B站"]
    PA --> INT
```

## 图2 控制面/数据面分离

我方服务器只流转任务元数据（<1KB），绝不触达平台；全部平台流量从客户 Agent 发出。

```mermaid
flowchart TB
    subgraph CP["控制面 我方服务器 无平台流量"]
        WEB["控制台/API"] --- Q["队列/排期/状态机"]
        Q --- GW["Agent网关 WSS"]
    end
    subgraph DP["数据面 客户Agent 全部平台流量"]
        WS["WSS客户端"] --- EX["任务执行器"]
        EX --- V["凭据保险库"]
        EX --- PR["代理路由"]
    end
    CP -->|"任务元数据 WSS <1KB"| DP
    DP -->|"结果/挑战 WSS"| CP
    DP -->|"上传/发布 平台流量"| P["目标平台"]
    CP -.->|"绝不触达"| P
```

## 图3 MVP 部署拓扑（内网联调）

Mac 跑网页端+服务器，Windows 装客户端，同局域网联调。注意服务器绑定 0.0.0.0、客户端用局域网 IP、防火墙放行、关 AP 隔离。

```mermaid
flowchart LR
    subgraph M["Mac 开发机 内网测试环境"]
        WEB["网页端 dev"] --> S["服务器 API + WSS网关"]
    end
    subgraph W["Windows 客户机"]
        APP["客户端App Agent<br/>WinUI壳+Go执行核心"]
    end
    W -->|"WSS ws://局域网IP:端口"| S
    S --> DB[("MySQL + Redis")]
    S --> FS[("素材 服务器本地盘")]
    APP -->|"直链下载素材 带签名token"| FS
```

## 图4 IP 路由逻辑

一账号一固定 IP，国内账号=国内住宅 IP，国外账号=国外住宅 IP，浏览器 Context 级注入。

```mermaid
flowchart LR
    ACC["账号台账"] --> REG{"账号归属地?"}
    REG -->|国内平台| POOL1["国内住宅IP池<br/>芝麻/快代理/922S5等"]
    REG -->|国外平台| POOL2["海外住宅IP池<br/>BrightData/IPRoyal等"]
    POOL1 --> BIND["一账号绑定一IP<br/>长期固定不轮换"]
    POOL2 --> BIND
    BIND --> CTX["浏览器Context级注入<br/>非全局TUN 防串账号"]
    CTX --> EXEC["执行发布"]
```

## 图5 重试与降级状态机

失败按原因分流：网络→指数退避重试；登录态→挑战（人工扫码）；风控→账号冷却+人工队列。

```mermaid
stateDiagram-v2
    [*] --> 队列中
    队列中 --> 执行中: Agent认领
    执行中 --> 已发布: 平台回执成功
    执行中 --> 网络重试: 网络/超时错误
    网络重试 --> 执行中: 退避1m/5m/15m/1h
    网络重试 --> 失败终态: 超上限N次
    执行中 --> 挑战中: 需扫码/验证码
    挑战中 --> 执行中: 用户完成挑战
    挑战中 --> 挂起: 挑战超时
    挂起 --> 执行中: 用户稍后处理
    执行中 --> 账号冷却: 风控拦截
    账号冷却 --> 执行中: 冷却结束+人工确认
    账号冷却 --> 失败终态: 人工放弃
    失败终态 --> 队列中: 人工一键重发
    已发布 --> [*]
    失败终态 --> [*]
```

## 图6 全链路时序（含异常分支）

```mermaid
sequenceDiagram
    participant OP as 运营
    participant S as 服务器
    participant A as Agent
    participant PL as 平台
    participant IT as 账号负责人
    Note over A,S: 单条WSS长连接复用(实测RTT 0.07ms)
    OP->>S: 提交任务(素材/平台/排期)
    S->>S: 校验→审核→入队→排期触发
    S->>A: task.push(taskId,加密载荷)
    A-->>S: ack(taskId) 幂等确认
    A->>A: 选账号→注入代理→协议级登录态校验(不启浏览器)
    alt 登录态正常
        A->>PL: 冷启动浏览器→上传素材→提交发布
        PL-->>A: 发布回执+截图
        A->>S: task.result(success)
        S-->>OP: 实时状态+链接
    else 平台触发二次验证
        PL-->>A: 挑战(扫码/短信/APP确认/滑块)
        A->>S: challenge.push(类型,凭证)
        S-->>IT: 控制台+企微提醒
        IT->>S: 扫码或输入验证码
        S->>A: challenge.resolve(结果)
        A->>PL: 继续发布流程
    else 网络类失败
        A->>A: 指数退避 1m/5m/15m/1h
        A->>PL: 自动重试上传
    else 登录态失效
        A->>S: challenge.push(qr)
        S-->>IT: 推送扫码提醒
        IT->>S: 扫码成功
        S->>A: challenge.resolve
        A->>PL: 恢复执行
    else 风控拦截
        A->>S: task.result(fail,原因)
        S->>S: 账号冷却+人工队列
        S-->>OP: 告警通知
    end
```

## 图7 二次验证挑战兜底流程

验证码类挑战人工兜底为主、Agent 硬解为辅；超时挂起→人工队列→一键重发。

```mermaid
flowchart TB
    TR["平台触发二次验证"] --> DET{"Agent检测挑战类型"}
    DET -->|二维码登录| QR["取码→推控制台+企微<br/>码过期自动刷新"]
    DET -->|APP确认| CF["推送手机确认提醒<br/>Agent轮询登录态"]
    DET -->|短信/邮箱| SMS["控制台弹输入框<br/>用户输入→回传回填"]
    DET -->|滑块/点选| CAP["默认截图推人工<br/>低风控平台本地尝试"]
    QR --> OK{"完成?"}
    CF --> OK
    SMS --> OK
    CAP --> OK
    OK -->|是| CONT["Agent继续发布流程"]
    OK -->|否/超时| PEND["任务挂起→人工队列<br/>一键重发/放弃"]
    PEND --> CONT
```

## 图8 登录链路优化时序

API 取码免浏览器、只传 token 不传截图、短轮询检测、扫码与检测并行。

```mermaid
sequenceDiagram
    participant U as 用户(手机)
    participant C as 控制台/企微
    participant S as 服务器
    participant A as Agent
    participant P as 平台
    Note over A,P: 首选API直取(无浏览器, B站已验证)
    A->>P: HTTP取码 0.1-0.5s 得token+图片URL
    A->>S: challenge.push(token) 实测<50ms
    S->>C: WS推码 并行推企微/托盘
    C->>C: 本地重渲染二维码(非截图)
    par 用户扫码 3-10s
        U->>U: 手机扫码确认
    and Agent短轮询检测
        loop 300-500ms
            A->>P: 轮询扫码状态(或网络钩子)
        end
    end
    A->>P: API换取cookie 0.2-0.5s
    A->>A: 存入凭据保险库
    A->>S: challenge.resolve(已登录)
    S-->>C: 状态变绿
```

## 图9 Agent 配对时序

```mermaid
sequenceDiagram
    participant U as 用户
    participant W as 网页端
    participant S as 服务器
    participant A as App(Agent)
    U->>W: 登录(密码+TOTP 2FA可选)
    W->>S: POST /api/auth/login
    S-->>W: JWT(15min) + refresh cookie
    U->>W: 工作区→设备→添加设备
    W->>S: POST /api/agents/pairing
    S-->>W: 配对码(6位,5分钟有效)
    U->>A: 输入配对码
    A->>A: 生成Ed25519密钥对+deviceId
    A->>S: WSS auth(deviceId,配对码,公钥,签名)
    S->>S: 验证→注册公钥→签发agentToken(可吊销)
    S-->>A: 绑定成功
    A->>A: 私钥入本地保险库(DPAPI/SQLCipher)
```

## 图10 素材传输链路（一期本地盘 / 二期OSS）

大文件绝不走 WSS；一期存服务器本地盘、直链带签名 token；二期切 OSS 预签名（StorageDriver 抽象保证零改动）。

```mermaid
flowchart TB
    OP["运营(网页端)"] -->|"① multipart直传(一期服务器本地盘)"| FS["素材存储 一期本地盘/二期OSS"]
    OP -->|"② 元数据 API(sha256)"| S["服务器"]
    S -->|"③ WSS task.push + 短时效下载URL"| A["Agent"]
    A -->|"④ 直链下载(带签名token)"| FS
    A -->|"⑤ 上传发布"| P["目标平台"]
    P -->|"⑥ 回执+截图"| A
    A -->|"⑦ WSS task.result(URL+状态)"| S
    S -->|"⑧ WSS 实时状态推送"| OP
```

## 图11 开发排期甘特（2 人，至最小闭环）

> 2026-08-20 更新：AI 加速版日级排期见 docs/dev-schedule.md，以新文档为准。

```mermaid
gantt
    title EveryPublish 最小闭环排期(2人)
    dateFormat YYYY-MM-DD
    axisFormat %m-%d
    section 奠基
    协议包+工程骨架 :M0, 2026-08-24, 7d
    section 网页端
    服务器最小闭环 :M1, 2026-08-31, 14d
    网页端全部功能 :M2, 2026-08-31, 28d
    section 客户端Windows
    Agent框架+WinUI壳 :M3, 2026-08-31, 21d
    真实平台接入4平台 :M4, 2026-09-21, 21d
    section 联调与收尾
    内网联调+异常加固 :M5, 2026-10-12, 14d
    打包+内部试用 :M6, 2026-10-26, 7d
    section 二期
    视频号+官方API通道 :M7, after M6, 21d
```

## 最小闭环验收清单

| 里程碑 | 验收标准 | 周次 |
|---|---|---|
| M0 协议+骨架 | 协议包单测通过，两端共享类型 | W1 |
| M1 服务器最小闭环 | 假执行器：任务→下发→执行→回传→显示全通 | W2-3 |
| M2 网页端全部功能 | 账号/素材/任务/排期/审核/挑战/审计/通知全页面可用 | W2-6 |
| M3 Windows 客户端框架 | 安装→配对→接假任务→回传结果 | W2-4 |
| M4 真实平台接入 | 抖音/快手/小红书/B站真实发布成功+截图回执 | W5-7 |
| M5 内网联调+加固 | 断线/重试/挑战/延迟<300ms 验收全过 | W8-9 |
| M6 打包+试用 | Windows 安装包+自动更新+内部试用 | W10 |

**人力**：2 人（网页/服务端 1 + 客户端 1）10 周闭环；单人 16-18 周。闭环后持续成本：平台适配每周 0.5-1 天。