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

## 背景与目标

推送页面已完成 Round 1（5项）+ Round 2（5项）+ Round 3（6项）共 16 项功能。实际使用中发现以下 5 项体验/功能缺口：

1. **2000+ 服务器无法快速定位** — 下拉列表滚动查找低效，缺少搜索过滤
2. **推送前无法预览内容差异** — 只知道哪些文件会传输，不知道具体改了什么
3. **推送失败无法快速诊断** — 失败后不知道是 SSH 不通、磁盘满、还是权限问题
4. **源路径仅支持 ZIP 上传** — 服务器已有文件需先下载再上传，重复劳动
5. **批量失败需逐台点重试** — 推送 50 台失败 20 台，需点 20 次重试按钮

## 方案对比

### H2 服务器搜索过滤

| 方案 | 优点 | 缺点 |
|------|------|------|
| A: `<select>` 上方加搜索框 + 实时过滤 | 简单直观，不改变交互模式 | 无 |
| B: 替换为自定义下拉组件（带搜索） | 更灵活 | 改动大，多选交互复杂 |

**选定方案 A** — 在现有 `<select>` 上方加 `<input>` 搜索框，按名称/域名实时过滤选项

### H3 推送对比 Diff 视图

| 方案 | 优点 | 缺点 |
|------|------|------|
| A: 预览文件列表中，每行加"查看diff"按钮 | 按需加载，精确 | 需后端端点读远程文件 |
| B: 批量拉取所有文件diff | 一次性展示全貌 | 大量文件时性能差 |
| C: 推送完成后对比 | 有实际结果 | 不是"推送前"预览 |

**选定方案 A** — 预览文件列表中加"查看diff"按钮，点击后请求后端读本地+远程文件内容，前端渲染逐行 diff（新增绿/删除红/修改黄）

### H4 推送排错面板

| 方案 | 优点 | 缺点 |
|------|------|------|
| A: 失败行加"🔍 诊断"按钮，弹面板显示检查结果 | 上下文内操作，体验流畅 | 需后端端点 |
| B: 失败后自动诊断 | 全自动 | 每次失败都跑诊断，浪费资源 |

**选定方案 A** — 失败行加"🔍 诊断"按钮，后端端点依次检查 SSH 连通 → 磁盘空间 → 目标路径权限，返回结构化结果

### H5 源路径直接输入

| 方案 | 优点 | 缺点 |
|------|------|------|
| A: ZIP 上传区域旁加"或输入服务器本地路径"输入框 | 不破坏现有流程 | 无 |
| B: 两种模式切换（上传/路径） | 界面清晰 | 增加交互步骤 |

**选定方案 A** — 上传区域下方加一行"或输入源路径"输入框 + "验证路径"按钮，验证后替代上传路径

### H6 批量重试

| 方案 | 优点 | 缺点 |
|------|------|------|
| A: 进度条区域加"重试所有失败"按钮 | 一键操作 | 无 |
| B: 勾选式批量重试 | 灵活选择 | 交互复杂 |

**选定方案 A** — 推送完成后，如果存在失败行，在进度条区域显示"重试全部失败（N台）"按钮

## 选定方案及理由

全部选方案 A（最简方案）：
- H2/H5/H6 均为纯前端或轻量前端改动
- H3/H4 需后端新端点，但复用现有 SSH 执行能力
- 改动范围最小，风险最低

## 接口/数据模型

### H3: 新增 API 端点
- `POST /api/sync/file-diff` — `{server_id, source_path, relative_path, target_path?}` → `{diff_lines: [{type, content}], file_name, local_exists, remote_exists}`
- 新增 Schema: `FileSyncDiff`

### H4: 新增 API 端点
- `POST /api/sync/diagnose` — `{server_id, target_path?}` → `{ssh_ok, disk_info, path_exists, path_writable, errors[]}`
- 新增 Schema: `SyncDiagnose`

### H5: 新增 API 端点
- `POST /api/sync/validate-source-path` — `{path}` → `{valid, is_dir, file_count, size_bytes, error?}`
- 新增 Schema: `ValidateSourcePath`

## 安全与性能约束

- H3: 仅允许对比 `/tmp/nexus_upload_*` 目录下的文件（realpath 校验）；远程文件通过 SSH cat 读取，限制 100KB
- H4: 诊断命令通过 `shlex.quote()` 防注入；SSH 操作复用连接池
- H5: realpath 校验 + 不允许 `/etc` `/root` `/home` 等敏感路径前缀；仅允许已存在目录
- H3/H4/H5 均需 JWT 认证 + 审计日志
- H2/H6 纯前端，无安全影响

## 验收标准

1. H2: 输入搜索文字 → 服务器下拉列表实时过滤匹配项
2. H3: 预览文件列表 → 点击"diff" → 弹出逐行对比视图
3. H4: 推送失败 → 点击"🔍 诊断" → 弹出面板显示 SSH/磁盘/权限检查结果
4. H5: 输入服务器本地路径 → 点验证 → 成功后可直接推送
5. H6: 推送完成后有失败 → 显示"重试全部失败"按钮 → 点击后所有失败服务器重试
