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

400 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` 通过。