# EveryPublish 交付文档（技术栈定版 · 页面构成 · 日计划）

> 2026-08-20 · 开发顺序：网站端(含API) → 客户端(Windows) → 联调交付（含两个用户确认检查点）。基础仓库已拉取：apps/web（Tencent/tdesign-react-starter，MIT）。技术栈定版见 docs/tech-stack.md（MySQL + 前后端 Go 统一）。

## 1. 技术栈定版

| 层 | 选型 | 依据 |
|---|---|---|
| 网页端 | React 18 + TDesign React（Tencent starter，MIT） | 已拉取预览：Vite + TS + Router6 + Redux Toolkit + axios；自带后台页面与 mock，无需装饰 |
| 网页端后端（服务器） | **Go**（gin + coder/websocket + asynq + GORM） | 见 Rust/Go 对比；与 agent-core 同语言共享协议模块；页面层仍为 React+TDesign |
| 客户端 UI | **WinUI 3（C#/.NET 8）原生** | 系统原生控件，无需自写 UI；QR 用 QRCoder 本地渲染 token |
| 客户端核心 | **Go**（WSS 客户端 + go-rod CDP 自动化 + 凭据保险库） | 单二进制、无运行时、可二期抽 Windows 服务/跑 VPS |
| 数据库/队列 | **MySQL 8.x（GORM）+ Redis（asynq）** | 任务队列/排期靠 Redis；MySQL 存业务数据 |
| 素材存储 | 一期服务器本地盘（签名直链）；二期 OSS | StorageDriver 抽象预留 |

### 1.1 Rust 还是 Go：结论选 Go

| 维度 | Go | Rust |
|---|---|---|
| 本项目规模 | 性能绰绰有余（WS 网关 goroutine-per-conn，千级连接轻松） | 性能过剩，无收益 |
| 开发与 AI 协作 | AI 生成质量高、迭代快、编译秒级 | borrow checker 调试成本高、编译慢 |
| 单二进制部署 | 静态编译、零依赖（Windows 端尤其省心） | 更小，但构建链复杂 |
| 浏览器自动化 | go-rod（CDP）成熟可用 | 生态弱 |
| Windows 常驻/服务 | kardianos/service 简单 | 复杂度高 |
| 生态（队列/WS/DB） | asynq / coder-websocket / GORM(MySQL) 齐全 | 可选少 |

**性能保障**：①WSS 网关 goroutine-per-conn，单机万级并发无压力；②GORM（MySQL 连接池）+ Redis 承载队列；③大文件绝不走 WSS（签名直链），网关只传 <1KB 消息；④服务无状态可水平扩展；⑤验收硬指标：任务下发 <300ms（tools/diag-connection.mjs 实测基线）。

## 2. 样式方案

- **网页端**：TDesign starter 默认主题（企业后台风格，深浅色可切换），全部页面用 TDesign 组件，不写自定义样式；示例页清理后按菜单骨架填充。
- **客户端**：WinUI 3 Fluent 原生风格（与 Windows 11 一致），托盘用 H.NotifyIcon.WinUI（或 Win32 interop），扫码/挑战用对话框页。

## 3. 网页端页面构成

### 3.1 用户端（客户工作台）

| 菜单 | 页面 | 关键功能 | 角色 |
|---|---|---|---|
| 工作台 | 仪表盘 | 今日发布统计、待处理挑战数、Agent 在线状态、最近任务 | 全部 |
| 发布管理 | 任务列表 / 新建发布 / 排期日历 / 任务详情 | 状态筛选、批量重试/取消；选素材→平台账号→标题话题→定时/立即→提交审核；月/周视图；事件时间线+回执截图+失败原因 | 运营/审核/管理员 |
| 素材库 | 素材列表 / 上传 / 预览 | 拖拽上传(multipart+进度)、分组标签、sha256、删除 | 运营/审核 |
| 账号管理 | 账号台账 / 绑定向导 / 挑战弹窗 | 平台/绑定状态/健康度/代理/最后活跃；发起扫码→QR 弹窗；重新扫码/解绑 | 管理员 |
| 审核中心 | 待审列表 | 分平台预览、通过/驳回+批注（可配置跳过） | 审核/管理员 |
| 通知与挑战 | 挑战中心 / 通知列表 | QR 从 token 本地渲染、验证码输入、APP确认指引、超时挂起/一键重发 | 相关角色 |
| 成员与权限 | 成员列表 / 邀请 | 邀请链接、角色分配 | 管理员 |
| 设置 | 工作区资料 / 安全 / 通知渠道 / Agent 设备 | 2FA 开关(默认关)、企微/钉钉/邮件、设备列表与吊销 | 管理员 |
| 审计日志 | 日志列表 | 谁在何时做了什么、筛选 | 管理员 |

### 3.2 平台端（admin 角色，同部署加一个角色即可）

| 菜单 | 页面 | 功能 |
|---|---|---|
| 租户管理 | 客户列表/详情 | 状态、配额（简单）、停用 |
| Agent 总览 | 设备列表 | 在线/版本/强制吊销/远程指令 |
| 渠道状态（后置） | 适配器列表 | 平台模块状态、灰度 |
| 风控台账（后置） | 事件列表 | 风控/冷却记录 |

## 4. 调用方式设计

```mermaid
flowchart LR
    subgraph WEB["网页端 React+TDesign"]
        U["用户端页面 / 平台端admin"]
    end
    subgraph SRV["Go 服务器"]
        API["REST /api/*"]
        WS["WSS 网关"]
    end
    subgraph CLIENT["Windows 客户端"]
        UI["WinUI 3 壳 C#"] -->|"localhost HTTP+随机token"| CORE["agent-core Go"]
    end
    U -->|"REST(axios) + 实时WS(JWT)"| API
    U -->|"实时状态推送"| WS
    CORE -->|"WSS Ed25519设备签名"| WS
    CORE -->|"素材直链下载(签名token)"| API
    CORE -->|"CDP 驱动系统Chrome/Edge"| CH["浏览器"]
```

- ① 网页端 → 服务器：REST（axios，JWT 15min + refresh 轮换）+ 原生 WebSocket（实时状态推送）。
- ② 客户端 WinUI 壳 → agent-core：localhost HTTP/WS + 随机 token（仅回环，配对时写入本地配置）。
- ③ agent-core → 服务器：WSS + Ed25519 设备签名（配对码注册公钥）。
- ④ 素材：multipart 上传 + 签名直链下载（大文件不走 WSS）。

## 5. 后台常驻方案（Windows）

- **开机自启**：安装时写注册表 HKCU Run。
- **最小化到托盘**：H.NotifyIcon.WinUI / Win32 Shell_NotifyIcon。
- **进程模型**：WinUI 主进程（UI）spawn agent-core 子进程（随机端口+token）；主进程做 watchdog——心跳检测、崩溃自拉起、3 次失败弹窗提示。
- **断线自愈**：core 内 WSS 指数退避重连（1s/5s/15s/60s）。
- **二期**：core 抽离为 Windows 服务（kardianos/service），支持无 UI 部署与客户 VPS 形态。

## 6. 开发日计划（1 人 + AI，顺序开发，D1-D13 + 2 天缓冲）

### 阶段一 网站端（D1-D7）

| 日 | 任务 | 验收标准 |
|---|---|---|
| D1 | 预览与工程化：starter 跑通 → 依赖升级评估(Vite2→5/TS4.8→5) → 清理示例页与 mock → 按页面清单搭菜单/路由空壳；Go 后端初始化(health/配置/DB/Redis) | dev 无报错、菜单空壳可点、/health 200、DB 连上 |
| D2 | 认证与工作区 API：Argon2 登录/refresh 轮换/登出(2FA 代码留位默认关)、成员/邀请/角色、审计埋点 | 单测过；前端登录页真实登录 |
| D3 | 业务 API：账号台账(bind→challenge)、素材(multipart+签名直链+sha256)、任务 CRUD+状态机+排期、审核动作、通知 | 单测+接口文档；curl 全接口可跑 |
| D4 | WSS 网关(hello 验签/心跳/断线、task.push/ack/result、challenge 双向) + 假执行器脚本 + 前端实时推送 | localhost 假执行器闭环：任务→下发→执行→回传→页面变绿，<300ms |
| D5 | 页面①：登录、仪表盘、成员、设置 | 页面与真实 API 联通 |
| D6 | 页面②：素材库、账号台账+绑定挑战弹窗、任务列表+新建+排期日历 | 全流程可点通（与假执行器） |
| D7 | 页面③：审核中心、挑战中心(QR 本地渲染+验证码)、通知、审计 + admin(租户列表/Agent 总览) | 角色权限正确、admin 入口可用 |

> **检查点①（暂停）**：D7 完成后暂停目标 → 执行网页端手动测试（§7 第 1-5 项 + 全页面冒烟）→ 输出测试报告 → 等待用户确认通过后再进入阶段二。

### 阶段二 客户端（D8-D11）

| 日 | 任务 | 验收标准 |
|---|---|---|
| D8 | agent-core(Go)：WSS 客户端(重连/幂等)、凭据保险库(加密)、执行器框架、代理配置、挑战处理 + 假平台执行器 | core 单测过；与服务器假执行闭环 |
| D9 | WinUI 3 壳：托盘、配对引导、扫码/挑战窗口、状态页；localhost 调 core；开机自启+watchdog；打包脚本 | Windows 实机：安装→配对→假任务→回传 |
| D10 | 真实平台：B站（投稿协议，无浏览器）先行 | B站真实发布成功 |
| D11 | 抖音/快手/小红书（go-rod CDP：系统 Chrome、独立档案、指纹、代理绑定；参考 social-auto-upload） | 三平台真实发布+截图回执（可先交付可跑子集） |

> **检查点②（暂停）**：D11 完成后暂停目标 → 打包并交付用户测试（附测试清单）→ 等待用户确认测试通过后再进入阶段三联调。

### 阶段三 联调与交付（D12-D13）

| 日 | 任务 | 验收标准 |
|---|---|---|
| D12 | 内网联调+异常注入：断线重连/重复任务/登录过期挑战/失败退避；延迟基线 | 验收清单全过 |
| D13 | 打包（安装器+自动更新）、内部试用、修复、部署手册 | 新机安装走通、交付物齐 |
| D14-15 | 缓冲（主要给平台逆向） | — |

## 7. 最终验收清单

1. 登录/刷新/登出/角色权限正常（2FA 默认关）。
2. 任务全生命周期：草稿→审核→排期→队列→执行→成功/失败→重试。
3. 任务下发 <300ms；断线重连 <10s 恢复；同任务不重复执行（幂等）。
4. 挑战全流程：扫码/验证码/APP确认/超时挂起/一键重发。
5. 素材：上传、签名直链下载、sha256 校验。
6. 四平台真实发布成功 + 回执截图入库。
7. Windows 新机：安装→配对→绑定账号→真实发布。
8. 凭据不出本机；审计日志完整。
9. 安装包 + 自动更新可用。

## 8. 交付物清单

- 代码：web/（网页端）、server/（Go 服务器）、client/（WinUI+agent-core）。
- 文档：docs/prd.md（需求）、docs/tech-stack.md（技术栈）、docs/system-design.md（设计）、docs/logic-diagrams.md（逻辑图）、docs/page-wireframes.md（页面线框图）、docs/frontend-guide.md（前端指南）、本交付文档（排期）、部署手册、验收报告。
- 工具：tools/diag-connection.mjs 联调诊断。

## 9. 风险与应对

| 风险 | 应对 |
|---|---|
| starter 依赖过旧（Vite2/TS4.8） | D1 升级评估，必要则升 Vite5+TS5，锁定 LTS Node |
| 平台逆向不可预测 | D14-15 缓冲；B站先行；卡住降级为可跑子集 |
| WinUI 托盘无官方控件 | H.NotifyIcon.WinUI 或 Win32 interop（D9 前验证） |
| 系统 Chrome 版本兼容 | go-rod 用 CDP，绑定系统 Edge 兜底 |