49c3fc1491
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
400 lines
16 KiB
Markdown
400 lines
16 KiB
Markdown
# 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` 通过。
|