# Changelog — BUG Batch 4：推送进度 WS / 浏览缓存 / 心跳 flush（2026-06-04）

## 摘要

修复推送页 WebSocket 进度永远收不到、远程文件操作后目录 ETag 304 陈旧、以及心跳 flush 每服务器单独事务的三处问题。

## 动机

- `POST /sync/files` 阻塞到推送结束，原前端在 POST 返回后才连 `/ws/sync`，所有 `sync_progress` 已发完。
- `file-ops` / 剪贴板变更远程目录后未失效服务端 browse ETag 缓存。
- `heartbeat_flush` 对每台服务器 `commit()` 一次，且对已删除服务器的空 UPDATE 仍计入成功。

## 变更

| 文件 | 说明 |
|------|------|
| `server/api/schemas.py` | `SyncFiles.batch_id`（12 位 hex，可选） |
| `server/application/services/sync_engine_v2.py` | 接受客户端 `batch_id` |
| `server/api/sync_v2.py` | 透传 `batch_id`；file-ops/clipboard 后 `invalidate_browse_cache` |
| `server/background/heartbeat_flush.py` | 单 session 批量提交；`rowcount` 统计 |
| `frontend/src/composables/push/usePushProgress.ts` | 先连 WS 再 POST；HTTP `results` 兜底 |
| `tests/test_sync_batch_id.py` | batch_id 校验单测 |
| `docs/reports/audit-bug-line-walk-2026-06-04-batch4.md` | BUG Batch 4 报告 |

## 迁移 / 重启

- 需重启 `nexus`；前端需重新 `vite build` 后部署 `web/app/`。
- 无 DB 迁移。

## 验证

```bash
ruff check server/api/sync_v2.py server/background/heartbeat_flush.py server/api/schemas.py
pytest tests/test_sync_batch_id.py tests/ -q
cd frontend && npm run type-check
```

## 关联

- Batch 3：`docs/changelog/2026-06-04-bug-batch3-retry-sync-stats.md`