Files
crawler-plugin/backend-java/docs/plans/02-plan-task-polling-audit.md
T
huangzd1997 49c3fc1491 docs(仓库): 规划文档改为入库,落盘品牌库/去重库每公司一套二期方案
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」,
代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红),
跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
2026-10-04 13:51:16 +08:00

16 KiB
Raw Blame History

02-plan — 任务轮询审计补强

对应 docs/specs/02-task-polling-audit.md。技术栈:TypeScript + Vitest(frontend-vue/)。 核心决策:不重写,只补强;getTaskPollBackoffMs 保持签名向后兼容。

任务 29:退避配置项(MaxMs/Factor)

所属模块:02 轮询 依赖:无 预估:8-15 分钟

功能点要求

task-progress-config.ts 新增 getTaskPollBackoffMaxMs()(默认 10000)与 getTaskPollBackoffFactor()(默认 2);默认值可通过 window 配置/测试注入覆盖。

测试用例(≥8)

  1. test_backoff_max_default — 默认 10000
  2. test_backoff_factor_default — 默认 2
  3. test_backoff_max_override — 可覆盖
  4. test_backoff_max_positive — 非正钳制
  5. test_backoff_factor_min_one — factor <1 钳制为 1
  6. test_backoff_config_isolated — 配置隔离(不串到其他用例)
  7. test_backoff_max_freeze — 默认值快照
  8. test_backoff_factor_freeze — factor 快照

TDD 流程

  1. 写测试 → npx vitest run src/shared/__tests__/task-progress-config.test.ts RED
  2. 实现 → GREEN
  3. vue-tsc --noEmit 通过

任务 30:getTaskPollBackoffMs 递增序列

所属模块:02 轮询 依赖:29 预估:8-15 分钟

功能点要求

getTaskPollBackoffMs(attempt):500 * factor^attempt 递增;attempt=0 返回 500(与现状一致);上限 maxMs;现签名向后兼容(attempt 省略视为 0)。

测试用例(≥8)

  1. test_backoff_attempt0_500 — attempt0=500
  2. test_backoff_attempt1_1000 — attempt1=1000
  3. test_backoff_attempt2_2000 — attempt2=2000
  4. test_backoff_sequence_monotonic — 序列递增
  5. test_backoff_capped_at_max — 封顶 10000
  6. test_backoff_no_attempt_default — 省略参数=500
  7. test_backoff_negative_attempt_zero — 负 attempt 当 0
  8. test_backoff_custom_factor — 自定义 factor 生效

TDD 流程 / 验证方法

同上。

任务 31:连续失败计数

所属模块:02 轮询 依赖:30 预估:8-15 分钟

功能点要求

轮询循环维护失败计数:refreshOnce 成功(收到响应)归零;连续失败递增;提供测试可观测出口(onError 带 attempt)。

测试用例(≥8)

  1. test_failure_count_increments — 连续失败递增
  2. test_success_resets_count — 成功后归零
  3. test_any_response_resets — 4xx 也算收到响应归零
  4. test_on_error_receives_attempt — onError 带 attempt
  5. test_initial_count_zero — 初始 0
  6. test_interleaved_fail_success — 失败成功交错计数正确
  7. test_count_bounded — 计数有界(不溢出)
  8. test_dispose_clears_count — dispose 后不再上报

TDD 流程 / 验证方法

同上。

任务 32:退避封顶

所属模块:02 轮询 依赖:30,31 预估:8-15 分钟

功能点要求

失败计数继续增长但退避间隔停在 maxMs;达到封顶后不再增长(间隔恒等于 maxMs)。

测试用例(≥8)

  1. test_backoff_cap_reached — 达到封顶
  2. test_backoff_stays_capped — 之后保持 maxMs
  3. test_cap_with_low_max — 低 maxMs 提前封顶
  4. test_cap_with_high_factor — 高 factor 快速封顶
  5. test_cap_resets_after_success — 成功后重新从 500 起
  6. test_cap_attempt_boundary — 恰好等于封顶那一档
  7. test_cap_integration_loop — 集成:循环内退避生效
  8. test_cap_config_negative — 非法 maxMs 钳制

TDD 流程 / 验证方法

同上。

任务 33:网络错误走退避且不触发终态

所属模块:02 轮询 依赖:31 预估:8-15 分钟

功能点要求

网络错误(fetch 拒绝/超时)不触发 onTerminal、不修改 taskStatuses、进入退避;恢复后继续轮询。

测试用例(≥8)

  1. test_network_error_no_terminal — 不触发 onTerminal
  2. test_network_error_no_status_change — 状态不变
  3. test_network_error_backoff_scheduled — 进入退避
  4. test_network_error_on_error_called — onError 调用
  5. test_network_recovery — 恢复后轮询继续
  6. test_network_error_repeated — 多次失败仍退避
  7. test_network_error_keeps_task — 任务不丢失
  8. test_network_error_then_success — 失败后成功收到响应

TDD 流程 / 验证方法

vitest fake timers + mock fetch 拒绝。

任务 34:HTTP 4xx/5xx 分类

所属模块:02 轮询 依赖:31 预估:8-15 分钟

功能点要求

4xx/5xx 记 onError 并退避;5xx 且无法解析明细时不误判 FAILED;不触发终态。

测试用例(≥8)

  1. test_4xx_on_error — 4xx 记 onError
  2. test_5xx_on_error — 5xx 记 onError
  3. test_5xx_no_terminal_failed — 不误判 FAILED
  4. test_5xx_backoff — 5xx 退避
  5. test_5xx_unknown_status_untouched — 未知状态不动
  6. test_4xx_recovery — 4xx 后恢复
  7. test_status_500_partial_items — 部分 items 仍处理
  8. test_5xx_no_status_wipe — 不清空已有状态

TDD 流程 / 验证方法

同上。

任务 35:未知状态不判终态固化

所属模块:02 轮询 依赖:无 预估:8-15 分钟

功能点要求

PENDING/SYNCING/空串/undefined 状态:isTerminal=false,不触发终态回调,轮询继续。

测试用例(≥8)

  1. test_pending_not_terminal — PENDING false
  2. test_syncing_not_terminal — SYNCING false
  3. test_empty_status_not_terminal — 空串 false
  4. test_undefined_status_not_terminal — undefined false
  5. test_unknown_status_continues_polling — 轮询继续
  6. test_mixed_terminal_unknown — 同批终态+未知分开处理
  7. test_custom_is_terminal — 自定义判定生效
  8. test_lowercase_unknown — 小写未知值也不误判

TDD 流程 / 验证方法

扩展 polling-state-machine.test.ts。

任务 36:终态任务仅一次 onTerminal

所属模块:02 轮询 依赖:无 预估:8-15 分钟

功能点要求

coordinator.markTerminal 语义:终态任务只触发一次 onTerminal;重复收到同任务终态不再回调;从轮询集合移除。

测试用例(≥8)

  1. test_terminal_called_once — 只一次
  2. test_terminal_removed_from_poll — 移除
  3. test_terminal_repeat_response — 重复响应不回调
  4. test_terminal_after_readd — 重新 add 后可再触发
  5. test_terminal_multiple_tasks — 多任务各自一次
  6. test_terminal_coordinator_order — markTerminal 先于 remove
  7. test_terminal_storage_cleared — localStorage 清空
  8. test_terminal_dispose_no_call — dispose 后不回调

TDD 流程 / 验证方法

同上。

任务 37:onTerminal 抛错语义测试

所属模块:02 轮询 依赖:无 预估:8-15 分钟

功能点要求

onTerminal 抛错:任务已从轮询集合移除(语义固化);错误不中断其他终态回调;页面可自行重新 add() 恢复。

测试用例(≥8)

  1. test_terminal_error_does_not_break_loop — 不中断循环
  2. test_terminal_error_task_removed — 任务已移除
  3. test_terminal_error_re_add_works — 重新 add 生效
  4. test_terminal_error_other_tasks — 其他终态仍回调
  5. test_terminal_error_swallowed — 错误被捕获不抛到外层
  6. test_terminal_error_then_success — 后一轮正常
  7. test_terminal_error_not_retried — 不自动重试回调
  8. test_terminal_error_status_kept — 状态保留

TDD 流程 / 验证方法

同上。

任务 38:同轮多任务终态分别回调

所属模块:02 轮询 依赖:无 预估:8-15 分钟

功能点要求

同一轮响应中多个任务同时终态:每个任务各触发一次 onTerminal(带各自 detail/status);顺序按响应顺序。

测试用例(≥8)

  1. test_multi_terminal_each_called — 各自回调
  2. test_multi_terminal_correct_detail — 各自 detail
  3. test_multi_terminal_correct_status — 各自 status
  4. test_multi_terminal_order — 按响应顺序
  5. test_multi_terminal_one_fails_other_runs — 一个抛错另一个仍回调
  6. test_multi_terminal_all_removed — 全部移除
  7. test_multi_terminal_await_sequence — 依次 await
  8. test_multi_terminal_async_on_terminal — 异步回调等待

TDD 流程 / 验证方法

同上。

任务 39:in-flight 合并测试补强

所属模块:02 轮询 依赖:无 预估:8-15 分钟

功能点要求

in-flight 期间不叠加 timer;等待上一次完成再按退避重试;同一时间只有一个请求。

测试用例(≥8)

  1. test_in_flight_no_second_request — 不并发
  2. test_in_flight_queues_after — 完成后继续
  3. test_in_flight_backoff_wait — 等待按退避
  4. test_in_flight_timer_single — 仅一个 timer
  5. test_in_flight_add_during — 期间 add 不重复
  6. test_in_flight_error_releases — 失败后释放
  7. test_in_flight_immediate_repeat — ensure(true) 不叠加
  8. test_in_flight_long_request — 长请求期间无叠加

TDD 流程 / 验证方法

同上。

任务 40:页面隐藏降频与可见恢复

所属模块:02 轮询 依赖:无 预估:8-15 分钟

功能点要求

visibilityState=hidden 时 30s 间隔;切回 visible 立即刷新(开关可配置、延迟可配置);降频不改任务集合。

测试用例(≥8)

  1. test_hidden_30s_interval — 隐藏 30s
  2. test_visible_5s_interval — 可见 5s
  3. test_foreground_refresh_triggered — 恢复立即刷新
  4. test_foreground_refresh_disabled — 开关关闭不刷新
  5. test_foreground_refresh_delayed — 延迟生效
  6. test_hidden_polling_continues — 隐藏仍轮询
  7. test_visibility_event_bound_unbound — 事件绑定/解绑
  8. test_hidden_no_immediate_refresh — 隐藏不触发即时刷新

TDD 流程 / 验证方法

mock document.visibilityState + dispatchEvent。

任务 41:storage 恢复与清理

所属模块:02 轮询 依赖:无 预估:8-15 分钟

功能点要求

恢复时过滤非正数/非数字;空列表清除 key;终态清理后同步 storage;写失败不影响功能。

测试用例(≥8)

  1. test_storage_restore_valid_ids — 恢复合法 id
  2. test_storage_restore_filters_invalid — 过滤非法
  3. test_storage_restore_empty_clears — 空列表清 key
  4. test_storage_terminal_removes — 终态后 key 更新
  5. test_storage_write_failure_ignored — 写失败不抛
  6. test_storage_bad_json — 坏 JSON 返回空
  7. test_storage_restore_starts_polling — 恢复即开始轮询
  8. test_storage_no_key_noop — 无 key 无操作

TDD 流程 / 验证方法

mock localStorage。

任务 42:退避恢复测试

所属模块:02 轮询 依赖:31,32 预估:8-15 分钟

功能点要求

失败→退避序列→成功→恢复 500ms 正常间隔;连续失败计数归零后重新从 500 起。

测试用例(≥8)

  1. test_recovery_after_failure — 失败后成功恢复
  2. test_backoff_reset_after_success — 计数归零
  3. test_interval_returns_to_base — 回到正常间隔
  4. test_recovery_cycle_repeat — 多次失败成功循环
  5. test_recovery_partial_items — 部分成功算成功
  6. test_recovery_with_foreground — 前台刷新下恢复
  7. test_recovery_after_many_failures — 长失败后恢复
  8. test_recovery_timing_assert — 时间断言(fake timers)

TDD 流程 / 验证方法

fake timers 时间断言。

任务 43:progressCache TTL 惰性清理边界

所属模块:02 轮询 依赖:无 预估:8-15 分钟

功能点要求

缓存条目超 TTL 在读取时清理;条目数上限(溢出淘汰最旧);空缓存 get 返回 undefined。

测试用例(≥8)

  1. test_cache_get_hit — 命中返回
  2. test_cache_get_expired_cleared — 过期清理
  3. test_cache_max_entries_evict — 超上限淘汰
  4. test_cache_empty_get_undefined — 空缓存
  5. test_cache_set_overwrites — 同 key 覆盖
  6. test_cache_ttl_zero — TTL=0 立即过期
  7. test_cache_lazy_cleanup — 惰性清理不主动扫
  8. test_cache_after_polling_cycle — 轮询周期内缓存可用

TDD 流程 / 验证方法

扩展 progress-response-cache.test.ts。

任务 44:轻量端点切换能力

所属模块:02 轮询 依赖:26 预估:8-15 分钟

功能点要求

useTaskProgressLoop 的 fetchProgress 可切到轻量端点(只返回 taskId/status/fileStatus 的 items);返回结构兼容(extractTaskId/extractStatus 从轻量字段取);默认仍走原端点。

测试用例(≥8)

  1. test_light_fetch_used — 切换后调轻量
  2. test_light_detail_shape_parsed — 轻量结构解析
  3. test_light_fallback_to_old — 默认旧端点
  4. test_light_missing_optional — 轻量缺字段容错
  5. test_light_terminal_detection — 终态判定
  6. test_light_progress_cache — 缓存写入
  7. test_light_on_update_called — onUpdate 收到
  8. test_light_snapshot_compat — 与旧响应兼容

TDD 流程 / 验证方法

同上。

任务 45:轮询与历史刷新分离

所属模块:02 轮询 依赖:无 预估:8-15 分钟

功能点要求

进度轮询不触发历史接口;历史刷新独立触发(onTerminal 或页面主动);同一轮中不混发 history 请求。

测试用例(≥8)

  1. test_polling_no_history_request — 轮询不发 history
  2. test_terminal_triggers_history — 终态触发历史刷新
  3. test_history_separate_call — 独立调用
  4. test_no_burst_history — 同轮不多发
  5. test_history_ttl_cache — 历史 TTL 生效
  6. test_history_force_refresh — force 参数跳过缓存
  7. test_polling_history_parallel — 可并行不阻塞
  8. test_polling_continues_after_history — 历史后轮询继续

TDD 流程 / 验证方法

同上。

任务 46:双页面同 key 行为记录

所属模块:02 轮询 依赖:无 预估:8-15 分钟

功能点要求

只读断言现状:两页面同 storageKey 时各自独立轮询集合,互不等待(记录已知边界,不改实现)。

测试用例(≥8)

  1. test_two_loops_same_key_independent — 独立
  2. test_shared_key_no_crash — 不崩溃
  3. test_shared_key_last_write — 写互相覆盖(现状)
  4. test_shared_key_restore_both — 各自恢复
  5. test_shared_key_no_live_sync — 无实时同步(现状)
  6. test_shared_key_dispose_one — 一方卸载另一方不受影响
  7. test_documented_boundary — 行为与文档一致
  8. test_shared_key_separate_storage — 不同 key 完全隔离

TDD 流程 / 验证方法

同上。

任务 47:轮询 baseline 统计补强

所属模块:02 轮询 依赖:无 预估:8-15 分钟

功能点要求

baseline 记录:请求量、响应体大小、缓存内存占用、轮询失败次数;每轮 refreshOnce 后回传 baseline 实例。

测试用例(≥8)

  1. test_baseline_request_count — 请求计数
  2. test_baseline_response_size — 响应大小
  3. test_baseline_cache_usage — 缓存占用
  4. test_baseline_failure_count — 失败次数
  5. test_baseline_callback_after_round — 每轮回调
  6. test_baseline_round_accuracy — 轮次准确
  7. test_baseline_reset — 重置
  8. test_baseline_optional_off — 不传 onBaseline 不创建

TDD 流程 / 验证方法

扩展 task-polling-baseline.test.ts。

任务 48:轮询全量回归

所属模块:02 轮询 依赖:29-47 预估:8-15 分钟

功能点要求

20 个既有轮询相关测试 + 本轮新增全部通过;npm run build(vue-tsc)通过;无行为回退。

测试用例(≥8)

1-8. 回归清单:既有 20 文件全绿、新 19 文件全绿、build 通过、无类型错误、无未用导出、页面入口编译、快照一致、git diff 仅限 shared 目录

TDD 流程 / 验证方法

npx vitest run 全绿 + npm run build 通过。