# BUG 专项逐行走读 — Batch 4（2026-06-04）

**标准**: `docs/project/line-walk-audit-standard.md` · 八类仅列 **BUG**

## 范围（5 文件，全文 Read）

| 文件 | N | Read |
|------|---|------|
| `server/api/sync_v2.py` | file-ops / browse / files | 125–280, 73–90 |
| `server/api/files.py` | 78 | GET browse + ETag |
| `server/background/heartbeat_flush.py` | 97 | 1–97 |
| `frontend/src/composables/push/usePushProgress.ts` | 289 | 全流程 |
| `server/api/schemas.py` | SyncFiles | batch_id |

---

## Step 3 规则扫描（BUG 相关）

| 文件 | 命中 |
|------|------|
| sync_v2.py | file-ops 后 ETag、batch_id |
| files.py | 304 缓存与变更一致性 |
| heartbeat_flush.py | 每 key 一 session、孤儿 key |
| usePushProgress.ts | WS 与 POST 时序 |
| schemas.py | batch_id 校验 |

---

## Closure 表（BUG）

| 文件 | 行号 | 判定 | 严重度 | 理由 |
|------|------|------|--------|------|
| usePushProgress.ts | 184-194 | **FINDING** | P1 | POST 阻塞至推送结束才连 WS，进度事件全部丢失 |
| sync_v2.py | 125-182 | **FINDING** | P2 | 远程 file-ops 后未 `invalidate_browse_cache`，304 陈旧目录 |
| heartbeat_flush.py | 57-89 | **FINDING** | P2 | 每服务器独立 session/commit；已删服务器仍计 flushed |
| files.py | 39-77 | SAFE | — | 只读 browse；失效由 mutation 侧负责 |
| sync_v2.py | 73-90 | SAFE | — | 同步 API 本身无 ETag |

---

## FINDING 列表

### BUG-06-04-08 · P1 · usePushProgress.ts

**现象**：`/sync/files` 在服务端同步执行完毕才返回，客户端却在返回后才连接 `/ws/sync`，实时 `sync_progress` 全部错过；界面长期 pending 直至 300s 超时。

**修复**：客户端预生成 `batch_id` → 等待 WS `onopen` → POST 携带 `batch_id`；响应 `results` 作兜底合并。

### BUG-06-04-09 · P2 · sync_v2 file-ops

**现象**：删除/重命名/mkdir/剪贴板后 GET browse 仍可能 304。

**修复**：`invalidate_browse_cache(server_id, parent_dir)`。

### BUG-06-04-10 · P2 · heartbeat_flush.py

**现象**：2000 台时 2000 次 commit；已删服务器 UPDATE 0 行仍计入 flushed。

**修复**：单 session 批量 UPDATE + `rowcount` 统计。

---

## Step 7 统计

```
usePushProgress.ts        1 FINDING（已修）
sync_v2.py                1 FINDING（已修）
heartbeat_flush.py        1 FINDING（已修）
files.py                    0
```

## Step 8 DoD

- [x] 5 文件覆盖
- [x] Closure 全表
- [x] 3 项已修 + pytest

## 验证

```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 --tb=no
cd frontend && npm run type-check
```

Changelog: `docs/changelog/2026-06-04-bug-batch4-push-etag-heartbeat.md`

## 下一批（BUG）

- `server/api/sync_v2.py` 上传/远程写文件路径
- `server/background/self_monitor.py`
- Agent 心跳与 Redis TTL 一致性抽测