Nexus/docs/design/specs/2026-05-29-push-round2-design.md

2026-05-29 推送页面迭代 Round 2 — 设计文档

背景与目标

推送页面 Round 1 已完成 5 项功能（WS 实时进度、分组选择、历史增强、文件操作、推送校验）。用户在实际使用中发现 5 项体验/功能缺陷：

1. 推送失败需手动切页重试 — 失败后需跳到"重试队列"页面，操作割裂
2. 无法识别服务器在线状态 — 选中离线服务器推送必然超时失败，浪费等待时间
3. 推送完成无即时通知 — 批量推送耗时长，用户离开页面后无法得知结果
4. 文件管理器无法预览内容 — 不确定推送的是否是正确文件，需下载验证
5. 同步模式含义不明确 — "增量/全量/校验和"对非运维用户不直观

方案对比

F1 失败自动重试

方案	优点	缺点
A: 行内重试按钮	不离开页面，体验流畅	需要从推送结果中获取 retry_job_id
B: 自动重试无需按钮	全自动	可能对临时性错误造成无意义重试
C: 弹窗显示失败列表+批量重试	可选择重试哪些	交互重

选定方案 A — 推送失败的行内"🔄 重试"按钮，利用现有 PushRetryJob + /api/retries/ 体系

F2 在线状态标识

方案	优点	缺点
A: 选项文字前加🟢/🔴	直观，零交互成本	无
B: hover 显示状态详情	信息更多	需额外交互

选定方案 A — 最简方案，API 已返回 is_online 字段

F3 Telegram 通知

方案	优点	缺点
A: 推送完成后发一条汇总通知	信息集中，不扰	延迟感知差
B: 逐台通知	实时	消息太多
C: 完成时汇总 + 部分失败时额外通知	覆盖全面	两条消息

选定方案 A — 推送完成后发一条汇总 Telegram 消息，含成功/失败数、失败服务器名、耗时

F4 文件内容预览

方案	优点	缺点
A: 点击文件名弹模态框预览	体验流畅	需新增后端端点
B: 新 tab 打开	简单	跳离上下文

选定方案 A — 新增 /api/sync/local-file-preview 端点，前端模态框预览

F5 同步模式说明

方案	优点	缺点
A: radio 下方固定说明文字	简单直观	占空间
B: hover tooltip	不占空间	可能被忽略
C: 模式旁❓图标hover显示	平衡	交互多一步

选定方案 A — radio 组下方增加动态说明文字，切换模式时更新

选定方案及理由

所有 5 项均选方案 A（最简方案），理由：

• 利用现有基础设施（重试体系、Telegram 模块、Redis heartbeat）
• 改动范围最小，风险最低
• 用户需求明确，无需复杂设计

接口/数据模型

F1: 新增 WS 字段

• broadcast_sync_progress() 增加可选参数 retry_job_id: int = None
• WS 消息 {type: "sync_progress", ..., retry_job_id: 123} (失败时有值)

F3: 新增 Telegram 函数

• send_telegram_sync_complete(completed, failed, total, source_path, operator, failed_servers, duration_seconds)

F4: 新增 API 端点

• POST /api/sync/local-file-preview — {path: str} → {name, size, content_base64, truncated, encoding_hint}
• 新增 Schema: LocalFilePreview

安全与性能约束

• F1: 重试按钮调已有 /api/retries/{id}/retry，已有 JWT 认证 + 审计
• F3: Telegram 消息经 sanitize_external_message() 脱敏
• F4: 文件预览限制：仅 /tmp/nexus_upload_* 目录 + 最多 4KB + realpath 校验
• F4: 预览端点需 JWT 认证 + 审计日志

验收标准

1. F5: 切换同步模式 → 下方说明文字正确更新
2. F2: 服务器列表在线🟢/离线🔴标识正确
3. F1: 推送失败 → 行内出现重试按钮 → 点击可重试
4. F3: 推送完成 → Telegram 收到通知含详情
5. F4: 点击文件名 → 弹出预览框