docs(user-manual): add product user manual aligned to live code

Cover onboarding, workspace, article creation, brand library, media publishing, knowledge base, image library, GEO tracking, desktop client, KOL marketplace, AI points, and FAQ — sourced from actual views and i18n rather than the v1 PRD. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-06 00:20:47 +08:00
parent 65e9b7e293
commit ab62d666b4
13 changed files with 1391 additions and 0 deletions
@@ -0,0 +1,146 @@
+# 桌面客户端
+
+桌面客户端（Electron 应用）是省心推执行**真实操作**的地方：媒体账号绑定、AI 平台授权、文章发布、AI 数据采集都在这里运行。Web 端只是查询和配置入口。
+
+## 1. 安装与登录
+
+1. 从运营或管理员处获取桌面客户端安装包（macOS / Windows）
+2. 安装后启动，首屏是登录页：与 Web 端使用**完全相同**的账号登录
+3. 登录成功后侧边栏出现 4 个导航项：
+
+| 入口 | 用途 |
+| --- | --- |
+| **控制台** | 运行总览、活动流、健康度 |
+| **发布管理** | 待发布队列、历史发送结果、重试 |
+| **媒体账号** | 13 个发布平台的授权与多账号管理 |
+| **AI 平台** | 6 个 AI 对话平台的绑定与授权 |
+
+侧边栏底部展示当前登录的操作员、邮箱、设备名（client）。设置入口为右下角图标，会另开独立设置窗口。
+
+## 2. 控制台（首页）
+
+路径 `/`。汇总展示：
+
+- **总体健康度**：服务连接、心跳、单点事件流、调度节点、任务消费端
+- **本地账号同步**事件：每次同步成功/失败都会记录
+- **任务流事件**：任务领取、执行成功、执行失败、租约续期失败、令牌过期等
+- **未完成问题**列表：任务执行失败、账号需要人工验证、触发风控等异常会聚合到这里
+
+> 控制台事件是英文事件名+本地化文案双显示。如果看到全英文事件名，说明翻译表里还没收录这条事件，可保留截图反馈。
+
+## 3. 媒体账号
+
+路径 `/media-platforms`。
+
+### 顶部概览
+
+- **已授权数**、**待处理数**、**风险观察数**、**在线客户端数** 四个总览数
+
+### 平台卡片
+
+按 13 个发布平台并排陈列，每张卡片显示：
+
+- 平台 Logo、名称、缩写、品牌色
+- 当前已绑定账号数
+- 最近一个账号的状态、UID、昵称、最后校验时间
+
+### 平台筛选
+
+- **平台**：全部 / 单平台
+- **状态**：全部 / 已授权 / 待处理 / 风险观察 / 授权过期
+- **搜索框**：按账号昵称或 UID
+
+### 操作
+
+- **去绑定 / 重新绑定**：在受控浏览器里打开平台登录页，登录成功后客户端识别 cookie + UID，回写到 SaaS
+- **打开平台**：直接在受控浏览器里打开该平台后台
+- **重新检测**（探测）：单账号触发一次状态校验
+- **重新授权**：账号过期时使用，等价于"重新登录"
+- **解绑**：断开 SaaS 与该账号的关联（本地 cookie 仍保留）
+
+### 状态徽标
+
+| 状态 | 含义 |
+| --- | --- |
+| **已授权** | 正常，可发布 |
+| **授权过期** | Cookie/Session 失效，需重新授权 |
+| **触发风控** | 平台返回风控挑战，需要人工在受控浏览器完成验证 |
+| **需人工验证** | 与风控类似，多为短信、扫码二次验证 |
+| **已停用** | 服务端 revoke |
+| **等待校验 / 校验中** | 探测任务排队或执行中 |
+| **最近校验失败** | 网络问题，重试即可 |
+
+## 4. AI 平台
+
+路径 `/ai-platforms`。
+
+### 当前支持的 AI 平台（6 个）
+
+- **豆包**（doubao）
+- **文心一言**（wenxin）
+- **通义千问**（qwen）
+- **DeepSeek**（deepseek）
+- **Kimi**（kimi）
+- **混元 / 元宝**（yuanbao）
+
+每个平台**只允许绑定一个账号**（与发布媒体不同），但绑定后即可用于全部品牌的 AI 数据采样。
+
+### 卡片字段
+
+- 平台名称 + 简介
+- 绑定状态徽标：**未绑定 / 授权正常 / 授权过期 / 需人工验证 / 触发风控 / 已停用 / 待校验**
+- 已绑定账号的 UID、最后校验时间
+- 操作按钮：**去绑定 / 重新授权 / 打开平台 / 解绑**
+
+### 顶部总览
+
+- **已配置平台数**、**已绑定数**、**当前在线数**、**在线客户端数**
+
+> AI 平台不能发布文章，只用于数据采集。绑定流程与媒体账号一致：受控浏览器登录 → 客户端识别 cookie → 回写服务端。
+
+## 5. 发布管理
+
+路径 `/publish-management`。集中查看发布任务队列与历史。
+
+### 列表字段
+
+- 文章标题、目标平台、目标账号
+- 任务状态：**等待发布** / **正在发送** / **发布成功** / **发布失败** / **结果未知**
+- 已发送链接、错误信息、合规拦截记录
+- 重试次数、租约到期时间、创建/更新时间
+
+### 操作
+
+- **再次发送**：失败任务可重试；会创建新任务记录
+- **打开链接**：成功任务的外链
+- **复制错误信息**：把脱敏后的错误详情复制出来报障
+
+### 自动刷新
+
+发布管理列表会按固定间隔（PAGE 内部计时）自动刷新，无需手动操作。
+
+## 6. 设置（独立窗口）
+
+点击侧边栏底部 **设置** 图标会弹出独立窗口，分四块：
+
+- **通用**：开机自启 / 保持后台运行
+- **登录设置**：服务端 API 地址（默认指向生产环境，未修改不要动）
+- **诊断**：导出 runtime 快照（包含子系统状态、客户端列表、版本号）用于报障
+- **关于 GEO**：版本号、客户端 ID
+
+> 修改服务端地址后需要重启客户端生效。仅在切换内部测试环境时需要修改。
+
+## 7. 客户端常见状态
+
+- **客户端不在线**：Web 端发布弹窗会标灰、立即采集会被拦截。打开桌面客户端，控制台会显示连接状态
+- **令牌过期**：控制台事件流会出现「客户端令牌已过期」，重新登录即可
+- **心跳失败 / 单点事件流退避**：网络抖动；通常自动恢复，不超过 30 秒应该回到正常
+- **任务领取失败 / 兜底拉取失败**：消息队列异常时会自动走数据库兜底；如果持续失败请联系平台
+
+## 8. 多设备同账号
+
+同一个账号可以在多台设备上登录桌面客户端。在线客户端数会显示在控制台和侧边栏。多台同时在线时：
+
+- 发布任务会被某一台领取并执行（避免重复）
+- AI 数据采集任务也按设备分流
+- 媒体账号绑定相互独立：A 机器绑定的知乎账号，不会自动出现在 B 机器