`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
16 KiB
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)
- test_backoff_max_default — 默认 10000
- test_backoff_factor_default — 默认 2
- test_backoff_max_override — 可覆盖
- test_backoff_max_positive — 非正钳制
- test_backoff_factor_min_one — factor <1 钳制为 1
- test_backoff_config_isolated — 配置隔离(不串到其他用例)
- test_backoff_max_freeze — 默认值快照
- test_backoff_factor_freeze — factor 快照
TDD 流程
- 写测试 →
npx vitest run src/shared/__tests__/task-progress-config.test.tsRED - 实现 → GREEN
vue-tsc --noEmit通过
任务 30:getTaskPollBackoffMs 递增序列
所属模块:02 轮询 依赖:29 预估:8-15 分钟
功能点要求
getTaskPollBackoffMs(attempt):500 * factor^attempt 递增;attempt=0 返回 500(与现状一致);上限 maxMs;现签名向后兼容(attempt 省略视为 0)。
测试用例(≥8)
- test_backoff_attempt0_500 — attempt0=500
- test_backoff_attempt1_1000 — attempt1=1000
- test_backoff_attempt2_2000 — attempt2=2000
- test_backoff_sequence_monotonic — 序列递增
- test_backoff_capped_at_max — 封顶 10000
- test_backoff_no_attempt_default — 省略参数=500
- test_backoff_negative_attempt_zero — 负 attempt 当 0
- test_backoff_custom_factor — 自定义 factor 生效
TDD 流程 / 验证方法
同上。
任务 31:连续失败计数
所属模块:02 轮询 依赖:30 预估:8-15 分钟
功能点要求
轮询循环维护失败计数:refreshOnce 成功(收到响应)归零;连续失败递增;提供测试可观测出口(onError 带 attempt)。
测试用例(≥8)
- test_failure_count_increments — 连续失败递增
- test_success_resets_count — 成功后归零
- test_any_response_resets — 4xx 也算收到响应归零
- test_on_error_receives_attempt — onError 带 attempt
- test_initial_count_zero — 初始 0
- test_interleaved_fail_success — 失败成功交错计数正确
- test_count_bounded — 计数有界(不溢出)
- test_dispose_clears_count — dispose 后不再上报
TDD 流程 / 验证方法
同上。
任务 32:退避封顶
所属模块:02 轮询 依赖:30,31 预估:8-15 分钟
功能点要求
失败计数继续增长但退避间隔停在 maxMs;达到封顶后不再增长(间隔恒等于 maxMs)。
测试用例(≥8)
- test_backoff_cap_reached — 达到封顶
- test_backoff_stays_capped — 之后保持 maxMs
- test_cap_with_low_max — 低 maxMs 提前封顶
- test_cap_with_high_factor — 高 factor 快速封顶
- test_cap_resets_after_success — 成功后重新从 500 起
- test_cap_attempt_boundary — 恰好等于封顶那一档
- test_cap_integration_loop — 集成:循环内退避生效
- test_cap_config_negative — 非法 maxMs 钳制
TDD 流程 / 验证方法
同上。
任务 33:网络错误走退避且不触发终态
所属模块:02 轮询 依赖:31 预估:8-15 分钟
功能点要求
网络错误(fetch 拒绝/超时)不触发 onTerminal、不修改 taskStatuses、进入退避;恢复后继续轮询。
测试用例(≥8)
- test_network_error_no_terminal — 不触发 onTerminal
- test_network_error_no_status_change — 状态不变
- test_network_error_backoff_scheduled — 进入退避
- test_network_error_on_error_called — onError 调用
- test_network_recovery — 恢复后轮询继续
- test_network_error_repeated — 多次失败仍退避
- test_network_error_keeps_task — 任务不丢失
- 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)
- test_4xx_on_error — 4xx 记 onError
- test_5xx_on_error — 5xx 记 onError
- test_5xx_no_terminal_failed — 不误判 FAILED
- test_5xx_backoff — 5xx 退避
- test_5xx_unknown_status_untouched — 未知状态不动
- test_4xx_recovery — 4xx 后恢复
- test_status_500_partial_items — 部分 items 仍处理
- test_5xx_no_status_wipe — 不清空已有状态
TDD 流程 / 验证方法
同上。
任务 35:未知状态不判终态固化
所属模块:02 轮询 依赖:无 预估:8-15 分钟
功能点要求
PENDING/SYNCING/空串/undefined 状态:isTerminal=false,不触发终态回调,轮询继续。
测试用例(≥8)
- test_pending_not_terminal — PENDING false
- test_syncing_not_terminal — SYNCING false
- test_empty_status_not_terminal — 空串 false
- test_undefined_status_not_terminal — undefined false
- test_unknown_status_continues_polling — 轮询继续
- test_mixed_terminal_unknown — 同批终态+未知分开处理
- test_custom_is_terminal — 自定义判定生效
- test_lowercase_unknown — 小写未知值也不误判
TDD 流程 / 验证方法
扩展 polling-state-machine.test.ts。
任务 36:终态任务仅一次 onTerminal
所属模块:02 轮询 依赖:无 预估:8-15 分钟
功能点要求
coordinator.markTerminal 语义:终态任务只触发一次 onTerminal;重复收到同任务终态不再回调;从轮询集合移除。
测试用例(≥8)
- test_terminal_called_once — 只一次
- test_terminal_removed_from_poll — 移除
- test_terminal_repeat_response — 重复响应不回调
- test_terminal_after_readd — 重新 add 后可再触发
- test_terminal_multiple_tasks — 多任务各自一次
- test_terminal_coordinator_order — markTerminal 先于 remove
- test_terminal_storage_cleared — localStorage 清空
- test_terminal_dispose_no_call — dispose 后不回调
TDD 流程 / 验证方法
同上。
任务 37:onTerminal 抛错语义测试
所属模块:02 轮询 依赖:无 预估:8-15 分钟
功能点要求
onTerminal 抛错:任务已从轮询集合移除(语义固化);错误不中断其他终态回调;页面可自行重新 add() 恢复。
测试用例(≥8)
- test_terminal_error_does_not_break_loop — 不中断循环
- test_terminal_error_task_removed — 任务已移除
- test_terminal_error_re_add_works — 重新 add 生效
- test_terminal_error_other_tasks — 其他终态仍回调
- test_terminal_error_swallowed — 错误被捕获不抛到外层
- test_terminal_error_then_success — 后一轮正常
- test_terminal_error_not_retried — 不自动重试回调
- test_terminal_error_status_kept — 状态保留
TDD 流程 / 验证方法
同上。
任务 38:同轮多任务终态分别回调
所属模块:02 轮询 依赖:无 预估:8-15 分钟
功能点要求
同一轮响应中多个任务同时终态:每个任务各触发一次 onTerminal(带各自 detail/status);顺序按响应顺序。
测试用例(≥8)
- test_multi_terminal_each_called — 各自回调
- test_multi_terminal_correct_detail — 各自 detail
- test_multi_terminal_correct_status — 各自 status
- test_multi_terminal_order — 按响应顺序
- test_multi_terminal_one_fails_other_runs — 一个抛错另一个仍回调
- test_multi_terminal_all_removed — 全部移除
- test_multi_terminal_await_sequence — 依次 await
- test_multi_terminal_async_on_terminal — 异步回调等待
TDD 流程 / 验证方法
同上。
任务 39:in-flight 合并测试补强
所属模块:02 轮询 依赖:无 预估:8-15 分钟
功能点要求
in-flight 期间不叠加 timer;等待上一次完成再按退避重试;同一时间只有一个请求。
测试用例(≥8)
- test_in_flight_no_second_request — 不并发
- test_in_flight_queues_after — 完成后继续
- test_in_flight_backoff_wait — 等待按退避
- test_in_flight_timer_single — 仅一个 timer
- test_in_flight_add_during — 期间 add 不重复
- test_in_flight_error_releases — 失败后释放
- test_in_flight_immediate_repeat — ensure(true) 不叠加
- test_in_flight_long_request — 长请求期间无叠加
TDD 流程 / 验证方法
同上。
任务 40:页面隐藏降频与可见恢复
所属模块:02 轮询 依赖:无 预估:8-15 分钟
功能点要求
visibilityState=hidden 时 30s 间隔;切回 visible 立即刷新(开关可配置、延迟可配置);降频不改任务集合。
测试用例(≥8)
- test_hidden_30s_interval — 隐藏 30s
- test_visible_5s_interval — 可见 5s
- test_foreground_refresh_triggered — 恢复立即刷新
- test_foreground_refresh_disabled — 开关关闭不刷新
- test_foreground_refresh_delayed — 延迟生效
- test_hidden_polling_continues — 隐藏仍轮询
- test_visibility_event_bound_unbound — 事件绑定/解绑
- test_hidden_no_immediate_refresh — 隐藏不触发即时刷新
TDD 流程 / 验证方法
mock document.visibilityState + dispatchEvent。
任务 41:storage 恢复与清理
所属模块:02 轮询 依赖:无 预估:8-15 分钟
功能点要求
恢复时过滤非正数/非数字;空列表清除 key;终态清理后同步 storage;写失败不影响功能。
测试用例(≥8)
- test_storage_restore_valid_ids — 恢复合法 id
- test_storage_restore_filters_invalid — 过滤非法
- test_storage_restore_empty_clears — 空列表清 key
- test_storage_terminal_removes — 终态后 key 更新
- test_storage_write_failure_ignored — 写失败不抛
- test_storage_bad_json — 坏 JSON 返回空
- test_storage_restore_starts_polling — 恢复即开始轮询
- test_storage_no_key_noop — 无 key 无操作
TDD 流程 / 验证方法
mock localStorage。
任务 42:退避恢复测试
所属模块:02 轮询 依赖:31,32 预估:8-15 分钟
功能点要求
失败→退避序列→成功→恢复 500ms 正常间隔;连续失败计数归零后重新从 500 起。
测试用例(≥8)
- test_recovery_after_failure — 失败后成功恢复
- test_backoff_reset_after_success — 计数归零
- test_interval_returns_to_base — 回到正常间隔
- test_recovery_cycle_repeat — 多次失败成功循环
- test_recovery_partial_items — 部分成功算成功
- test_recovery_with_foreground — 前台刷新下恢复
- test_recovery_after_many_failures — 长失败后恢复
- test_recovery_timing_assert — 时间断言(fake timers)
TDD 流程 / 验证方法
fake timers 时间断言。
任务 43:progressCache TTL 惰性清理边界
所属模块:02 轮询 依赖:无 预估:8-15 分钟
功能点要求
缓存条目超 TTL 在读取时清理;条目数上限(溢出淘汰最旧);空缓存 get 返回 undefined。
测试用例(≥8)
- test_cache_get_hit — 命中返回
- test_cache_get_expired_cleared — 过期清理
- test_cache_max_entries_evict — 超上限淘汰
- test_cache_empty_get_undefined — 空缓存
- test_cache_set_overwrites — 同 key 覆盖
- test_cache_ttl_zero — TTL=0 立即过期
- test_cache_lazy_cleanup — 惰性清理不主动扫
- 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)
- test_light_fetch_used — 切换后调轻量
- test_light_detail_shape_parsed — 轻量结构解析
- test_light_fallback_to_old — 默认旧端点
- test_light_missing_optional — 轻量缺字段容错
- test_light_terminal_detection — 终态判定
- test_light_progress_cache — 缓存写入
- test_light_on_update_called — onUpdate 收到
- test_light_snapshot_compat — 与旧响应兼容
TDD 流程 / 验证方法
同上。
任务 45:轮询与历史刷新分离
所属模块:02 轮询 依赖:无 预估:8-15 分钟
功能点要求
进度轮询不触发历史接口;历史刷新独立触发(onTerminal 或页面主动);同一轮中不混发 history 请求。
测试用例(≥8)
- test_polling_no_history_request — 轮询不发 history
- test_terminal_triggers_history — 终态触发历史刷新
- test_history_separate_call — 独立调用
- test_no_burst_history — 同轮不多发
- test_history_ttl_cache — 历史 TTL 生效
- test_history_force_refresh — force 参数跳过缓存
- test_polling_history_parallel — 可并行不阻塞
- test_polling_continues_after_history — 历史后轮询继续
TDD 流程 / 验证方法
同上。
任务 46:双页面同 key 行为记录
所属模块:02 轮询 依赖:无 预估:8-15 分钟
功能点要求
只读断言现状:两页面同 storageKey 时各自独立轮询集合,互不等待(记录已知边界,不改实现)。
测试用例(≥8)
- test_two_loops_same_key_independent — 独立
- test_shared_key_no_crash — 不崩溃
- test_shared_key_last_write — 写互相覆盖(现状)
- test_shared_key_restore_both — 各自恢复
- test_shared_key_no_live_sync — 无实时同步(现状)
- test_shared_key_dispose_one — 一方卸载另一方不受影响
- test_documented_boundary — 行为与文档一致
- test_shared_key_separate_storage — 不同 key 完全隔离
TDD 流程 / 验证方法
同上。
任务 47:轮询 baseline 统计补强
所属模块:02 轮询 依赖:无 预估:8-15 分钟
功能点要求
baseline 记录:请求量、响应体大小、缓存内存占用、轮询失败次数;每轮 refreshOnce 后回传 baseline 实例。
测试用例(≥8)
- test_baseline_request_count — 请求计数
- test_baseline_response_size — 响应大小
- test_baseline_cache_usage — 缓存占用
- test_baseline_failure_count — 失败次数
- test_baseline_callback_after_round — 每轮回调
- test_baseline_round_accuracy — 轮次准确
- test_baseline_reset — 重置
- 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 通过。