docs: 项目文档、设计图、工具、协议模块、部署说明

2026-08-20 20:38:21 +08:00
commit bf25d8beac
46 changed files with 2965 additions and 0 deletions
@@ -0,0 +1,153 @@
+# 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 兜底 |