## [ERR-20260427-007] 长耗时同步同步等 HTTP → 前端"网络错误"

**日期**: 2026-04-27
**类别**: 架构 / API 设计
**严重度**: 高（功能形同不可用）

### 问题描述
ADP Linker 拉 100+ 名员工 + 158 个 PTO 拉取（即使加了 800ms 节流）总耗时 100+ 秒。POST /trigger 同步等结果，前端 toast 报：
```
慢请求告警: /api/v1/adp-sync/linker/trigger 耗时 102034ms (阈值: 2000ms)
Failed to load PTO list: Network connection failed
```
HTTP 客户端默认超时（axios 默认 0=无限制，但 Next 反代/Nginx/浏览器都有 ~60s 上限）必然撞墙。

### 修复：fire-and-forget + 前端轮询
后端：scheduler 加 `triggerLinkerAsync` / `triggerPtoSyncAsync`：
```ts
triggerLinkerAsync(triggeredBy?: string) {
  if (this.runningTasks.has(TASK_CODE)) return { accepted: false, reason: 'already-running' };
  setImmediate(() => this.executeTask(...));  // 后台跑
  return { accepted: true };  // 立即返回
}
```
Controller 立即返回 `{ accepted: true, status: 'RUNNING' }`，HTTP < 100ms。

前端：触发后 toast "已开始执行..."，每 3s 轮询 GET /status，看 `lastExecution.status !== 'RUNNING'` 时 toast 完成结果，最多等 5 分钟。

### 启示
- **超过 5-10 秒的"业务操作"都不应该同步等 HTTP**。否则浏览器/Nginx/反代/云服务任何一层超时都会把用户体验打碎
- 项目里已有 AutomationExecution 表跟踪状态，**复用现有"任务记录 + 轮询"模式**比新加 SSE/WebSocket 简单（不需要前端引入 EventSource）
- `setImmediate` 在 Node.js 里足够"后台化"任务：本进程内执行不依赖外部队列。**仅适合幂等任务**（重启会丢失，但本场景下次 cron 会兜底）；高保障场景应该入队列（Bull/Temporal）
- 「锁」用 `runningTasks: Set<string>` 防同一任务并发触发，简单有效；分布式部署时需要换成 DB 锁

---