# 2026-05-28 推送页面 5 项迭代功能

## 变更摘要
1. F1: 推送进度实时追踪 — WebSocket 逐台推送进度更新
2. F2: 服务器分组选择 — 分类/平台筛选 + 选中当前筛选
3. F4: 推送历史增强 — 可展开详情面板（耗时/错误/diff）
4. F7: 文件管理器操作 — 解压文件删除/重命名
5. F8: 推送后校验 — md5sum 对比本地源与远程目标

## 动机
推送页面已完成 ZIP 上传 + rsync 推送基础功能，但存在 5 个体验缺陷：批量推送无实时反馈、2000+ 服务器无法分组选择、历史记录无详情、文件管理器只读、推送后无法校验文件一致性。

## 涉及文件

### 后端
- `server/api/websocket.py` — 新增 `broadcast_sync_progress()` 函数
  - 参数: batch_id, server_id, server_name, status, completed, failed, total, error_message, duration_seconds
  - 通过 `_dispatch_ws_message()` 发布到 Redis Pub/Sub + 本地 WebSocket
- `server/application/services/sync_engine_v2.py` — 推送引擎改造
  - `sync_files()`: 新增 `batch_id` (uuid) 用于 WS 消息过滤
  - `_sync_one()`: 计数器更新后调用 `broadcast_sync_progress()`
  - `_sync_one()`: 捕获 `diff_summary = result["stdout"][:2000]`
  - `_log_to_dict()`: 新增 files_transferred, files_skipped, bytes_transferred, diff_summary
  - 返回 dict 新增 `batch_id`
- `server/api/servers.py` — 服务器列表 + 历史增强
  - `list_servers()`: 新增 `platform_id`, `node_id` Query 参数
  - 新增 `GET /api/servers/categories` 端点（分类+平台列表）
  - `_sync_log_to_dict()`: 新增 files_skipped, bytes_transferred, diff_summary
- `server/infrastructure/database/server_repo.py` — `get_paginated()` 增加 `platform_id`, `node_id` 参数
- `server/api/schemas.py` — 新增 `LocalFileOperation`, `SyncVerify` 模型
- `server/api/sync_v2.py` — 新增端点
  - `POST /api/sync/local-file-ops`: 删除/重命名上传临时目录中的文件
  - `POST /api/sync/verify`: md5sum 对比本地源与远程目标

### 前端
- `web/app/push.html` — 全面改造
  - F1: WebSocket 连接 `connectPushWS()` + `updateProgressFromWS()` 逐台更新
  - F2: 分类/平台筛选下拉框 + `filterServers()` + "选中当前筛选" 按钮
  - F4: 历史记录可点击展开详情（源/目标路径、耗时、错误、diff_summary）
  - F7: 文件管理器 hover 显示操作按钮 + `deleteLocalFile()`/`renameLocalFile()`
  - F8: "推送后校验" 复选框 + `doVerify()` + 校验结果面板

## 安全影响
- F1 (WS): WS 消息需 JWT 认证 + batch_id 过滤防混淆
- F7 (文件操作): `os.path.realpath()` + `startswith("/tmp/nexus_upload_")` 双重校验，新路径也必须在上传目录内
- F8 (校验): SSH 命令中文件名通过 `shlex.quote()` 防注入
- 所有新端点需 JWT 认证 + 审计日志

## 需要迁移/重启
- 是：后端 Python 需重启（supervisorctl restart nexus）
- 否：无数据库 schema 迁移

## 验证方式
1. F1: 推送 3+ 台服务器 → 观察 WS 逐台更新状态（不等全部完成）
2. F2: 分类筛选 → 选中筛选 → 服务器列表正确过滤
3. F4: 点击历史记录 → 展开详情 → 显示耗时/错误/diff
4. F7: 上传 ZIP → 文件管理器 → 删除/重命名文件 → 刷新确认
5. F8: 勾选校验 → 推送 → 校验结果正确显示匹配/缺失

## 进度条
☑实现 ☑WSL验证 ☐审计8步 ☐部署 ☐健康检查 ☐浏览器验证 ☐changelog
