`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
13 KiB
06-plan — 只读查询与批量加载优化
对应
docs/specs/06-read-query-batch-loading.md。行为不变型优化 + 新增 progress/light 轻量接口。 技术栈:Java 21 + MyBatis-Plus + Flyway。
任务 105:similarasin 历史列表 IN 查询批量加载
所属模块:06 批量加载 依赖:无 预估:8-15 分钟
功能点要求
history 方法:任务+结果+Job 关联数据由逐条查询改为 IN 批量查询 + 按 ID Map 装配;分页结果、排序、过滤不变;输出与现状一致。
测试用例(≥8)
- test_history_batch_loads — 批量加载装配
- test_history_single_row — 单条
- test_history_multiple_tasks — 多任务
- test_history_no_jobs — 无 Job 兼容
- test_history_order_unchanged — 排序不变
- test_history_pagination — 分页不变
- test_history_missing_related — 关联缺失兜底
- test_history_sql_count — IN 查询次数(≤N,断言 mapper 调用次数)
TDD 流程
- 写测试(mock mapper 断言查询次数与装配)→ RED
- 改造 history 实现 → GREEN
mvn test -Dtest=SimilarAsinTaskServiceTest通过
任务 106:appearancepatent 历史列表批量加载
所属模块:06 批量加载 依赖:105 预估:8-15 分钟
同 105 模式。
测试用例(≥8)
同 105(appearancepatent)。
任务 107:结果列表关联 Job 批量加载
所属模块:06 批量加载 依赖:无 预估:8-15 分钟
功能点要求
结果列表/详情页关联 TaskFileJob 状态:findAssembleJobsByResultIds 覆盖审计;逐条查 result→job 的路径改 IN;输出不变。
测试用例(≥8)
- test_result_job_batch — 批量取 Job
- test_result_job_single — 单条
- test_result_job_empty — 空结果
- test_result_job_map_keyed — 按 resultId Map
- test_result_job_missing — 缺 Job 兜底
- test_result_job_query_count — 查询次数断言
- test_result_job_null_guard — null 安全
- test_result_job_consistency — 与现状一致
任务 108:dashboard 聚合查询
所属模块:06 批量加载 依赖:无 预估:8-15 分钟
功能点要求
dashboard 统计改批量聚合(COUNT/GROUP BY 一次出);状态分类计数与逐条统计结果一致;输出结构不变。
测试用例(≥8)
- test_dashboard_counts — 各状态计数
- test_dashboard_empty — 空用户 0 计数
- test_dashboard_aggregate_sql — 聚合 SQL 调用
- test_dashboard_recent_tasks — 最近任务列表
- test_dashboard_consistency — 与逐条一致
- test_dashboard_mixed_status — 混合状态
- test_dashboard_user_filter — 用户过滤
- test_dashboard_big_data — 大数据量聚合
任务 109:progress/light 轻量接口(similarasin 首个)
所属模块:06 批量加载 依赖:无 预估:8-15 分钟
功能点要求
新端点 POST /api/similar-asin/tasks/progress/light:body {taskIds};resp items[{taskId,status,statusCode?,fileStatus,fileReady,updatedAt}];旧 progress/batch 保留不动;走轻量查询(不查明细/result 行)。
测试用例(≥8)
- test_light_returns_light_fields — 只返回轻量字段
- test_light_missing_task — missingTaskIds
- test_light_empty_ids — 空 ids 空结果
- test_light_dedup_ids — 去重
- test_light_old_endpoint_untouched — 旧端点仍工作
- test_light_status_mapping — 状态映射正确
- test_light_file_fields — file 字段附带
- test_light_unknown_id — 未知 id 缺失列表
TDD 流程
- 测试(MockMvc 打新端点)→ RED(404)
- 实现 controller + service → GREEN
mvn test -Dtest=SimilarAsinControllerTest通过
任务 110:progress/light 字段白名单
所属模块:06 批量加载 依赖:109 预估:8-15 分钟
功能点要求
响应仅含白名单字段(taskId/status/statusCode/fileStatus/fileReady/updatedAt);不含 items 明细/payload/result 内容;序列化断言。
测试用例(≥8)
- test_whitelist_no_items — 无明细数组
- test_whitelist_no_payload — 无 payload 字段
- test_whitelist_exact_keys — 键集合精确匹配
- test_whitelist_file_phase — file 字段在白名单
- test_whitelist_extra_rejected — 多余键测试失败
- test_whitelist_null_values_ok — null 值允许
- test_whitelist_response_size_small — 响应体小(<1KB)
- test_whitelist_documented — 白名单文档一致
任务 111:progress/light 空/超长 taskIds
所属模块:06 批量加载 依赖:109 预估:8-15 分钟
功能点要求
空数组→空 items;null→空;>200 个截断或返回错误(定义行为);非正数过滤。
测试用例(≥8)
- test_light_empty_array — 空数组
- test_light_null_body — null body 处理
- test_light_negative_filter — 负数过滤
- test_light_zero_filter — 0 过滤
- test_light_over_200 — 超长截断/错误
- test_light_duplicates — 重复去重
- test_light_single — 单 id
- test_light_max_exact — 恰好上限
任务 112:progress/light 终态任务返回
所属模块:06 批量加载 依赖:109 预估:8-15 分钟
功能点要求
SUCCESS/FAILED 任务在 light 接口返回终态状态 + file 阶段;前端可凭此停止轮询并展示。
测试用例(≥8)
- test_light_success_task — SUCCESS 返回
- test_light_failed_task — FAILED 返回
- test_light_pending — PENDING
- test_light_running — RUNNING
- test_light_success_file_status — 附带 fileStatus
- test_light_failed_file_error — 失败附带 fileError
- test_light_terminal_complete — 终态字段完整
- test_light_status_frozen — 状态值语义不变
任务 113:其余模块 progress/light 接入
所属模块:06 批量加载 依赖:109-112 预估:8-15 分钟
功能点要求
同构端点接入:appearancepatent/publish/queryasin/shopdatacrawl/withdraw/patroldelete/shopmatch/productrisk/pricetrack/deletebrand/collectdata(11 个);路径模式统一;字段白名单一致。
测试用例(≥8)
- test_light_all_modules_exist — 12 个 light 端点存在
- test_light_common_shape — 响应结构一致
- test_light_module_specific_status — 各模块状态映射
- test_light_publish_files — publish 文件级字段
- test_light_old_endpoints_all_kept — 旧端点全保留
- test_light_whitelist_all — 白名单一致
- test_light_missing_all — 缺失任务处理
- test_light_contract_frozen — 契约快照
任务 114:批量加载等价快照测试
所属模块:06 批量加载 依赖:105-108 预估:8-15 分钟
功能点要求
改造前后同数据:历史页、结果页、dashboard 输出字段完全一致(快照对比)。
测试用例(≥8)
- test_history_snapshot_equiv — 历史快照一致
- test_dashboard_snapshot_equiv — dashboard 一致
- test_result_snapshot_equiv — 结果一致
- test_pagination_equiv — 分页一致
- test_snapshot_reproducible — 可重复
- test_snapshot_diff_fails — 篡改即失败
- test_snapshot_covers_all — 覆盖三页
- test_snapshot_regression_guard — 全量回归门禁
任务 115:高频查询 EXPLAIN 索引审计
所属模块:06 批量加载 依赖:无 预估:8-15 分钟
功能点要求
对高频查询(history/progress/dashboard)逐条 EXPLAIN;产出索引迁移清单(表/列/类型/收益/风险);不做 DDL。
测试用例(≥8)
- test_explain_history_plan — history 执行计划记录
- test_explain_progress_plan — progress 计划
- test_explain_dashboard_plan — dashboard 计划
- test_full_scan_detected — 全表扫描标记
- test_index_candidates_listed — 候选索引清单
- test_plan_documented — 审计文档产出
- test_plan_repeatable — 可重复执行
- test_no_ddl_this_task — 本任务无 DDL
任务 116:索引迁移 V{N+1}
所属模块:06 批量加载 依赖:115 预估:8-15 分钟
功能点要求
按审计清单追加 db/V{N+1}__*.sql(只追加不改历史);包含验证 SQL;标注锁表风险与窗口。
测试用例(≥8)
- test_migration_file_exists — 迁移文件存在
- test_migration_version_sequential — 版本号续接
- test_migration_validated — 验证 SQL 通过(副本库)
- test_migration_index_created — 索引生效
- test_explain_improved — 执行计划改善
- test_migration_no_alter_legacy — 不改历史迁移
- test_migration_rollback_doc — 回滚步骤记录
- test_migration_backward_safe — 旧数据兼容
任务 117:progress/light user_id 权限过滤
所属模块:06 批量加载 依赖:109 预估:8-15 分钟
功能点要求
user_id 传入时仅返回该用户任务;未传时按 taskId 反查;越权任务进 missingTaskIds(不泄露)。
测试用例(≥8)
- test_light_user_filter — 用户过滤
- test_light_no_user_reverse — 无 user 反查
- test_light_other_user_hidden — 他人任务隐藏
- test_light_missing_on_unauthorized — 越权进 missing
- test_light_user_null — 全空 userId
- test_light_admin_scope — 管理范围(按现状)
- test_light_user_consistent — 与旧端点一致
- test_light_no_leak — 响应不含他人数据
任务 118:前端 getModuleProgressLight 适配
所属模块:06 批量加载 依赖:109,44 预估:8-15 分钟
功能点要求
java-modules.ts 新增 getModuleProgressLight(module, taskIds) 调 light 端点;返回结构归一为现有 progress 类型;页面可渐进切换。
测试用例(≥8)
- test_light_url_module — 模块路径正确
- test_light_payload — taskIds body
- test_light_response_shape — 归一结构
- test_light_fallback_flag — 可开关
- test_light_missing_ids — missingTaskIds 映射
- test_light_timeout — 10s 超时
- test_light_type_compat — 与旧类型兼容
- test_light_snapshot — 快照
任务 119:前端 dashboard/history/progress 分离调用测试
所属模块:06 批量加载 依赖:无 预估:8-15 分钟
功能点要求
前端页面:dashboard 只调统计、history 只调摘要、progress 只调轻量;首次打开不加载全部明细;断言请求路径分离。
测试用例(≥8)
- test_page_dashboard_only_stats — 只调统计
- test_page_history_only_summary — 只调摘要
- test_page_progress_only_light — 只调进度
- test_page_no_full_detail_on_load — 首开不拉明细
- test_page_items_on_open — 打开明细才请求
- test_page_result_on_demand — 结果按需
- test_page_request_count_bounded — 请求数有界
- test_page_snapshot — 请求快照
任务 120:大页数据性能回归
所属模块:06 批量加载 依赖:105-108 预估:8-15 分钟
功能点要求
500 任务级数据:history/dashboard/progress 响应时间上界(基准线);不劣于改造前。
测试用例(≥8)
- test_perf_history_500 — 历史耗时
- test_perf_dashboard_500 — dashboard 耗时
- test_perf_progress_200 — 200 任务进度
- test_perf_light_200 — light 更快
- test_perf_query_count — 查询次数上界
- test_perf_no_regression — 与基线对比
- test_perf_memory_bounded — 内存有界
- test_perf_report — 结果记录
任务 121:N+1 扫描审计
所属模块:06 批量加载 依赖:无 预估:8-15 分钟
功能点要求
对 modules 下 Service 扫描逐条 selectById/selectOne 循环模式;产出 N+1 清单(位置/对象/影响);不做修改。
测试用例(≥8)
- test_scan_select_in_loop — 识别循环内单查
- test_scan_output_listed — 清单产出
- test_scan_priority — 按影响排序
- test_scan_module_coverage — 覆盖主要模块
- test_scan_false_positive_checked — 排除误报(已批量)
- test_scan_repeatable — 可重复
- test_scan_documented — 文档产出
- test_scan_no_edit — 本任务不改代码
任务 122:N+1 批量化修复
所属模块:06 批量加载 依赖:121 预估:8-15 分钟
功能点要求
按清单修复高影响 N+1(IN 查询 + Map 装配);行为不变;快照对比验证。
测试用例(≥8)
- test_fix_in_query — 改 IN 查询
- test_fix_map_assembly — Map 装配
- test_fix_behavior_same — 行为一致
- test_fix_single_row — 单行兼容
- test_fix_empty — 空兼容
- test_fix_query_count_reduced — 查询次数下降
- test_fix_snapshot — 输出快照
- test_fix_no_side_effect — 无副作用
任务 123:06 全量回归
所属模块:06 批量加载 依赖:105-122 预估:8-15 分钟
功能点要求
06 全部任务产出物 + 既有测试全绿;light 契约快照冻结;无行为回退。
测试用例(≥8)
1-8:全部新测试绿、既有回归绿、light 契约快照、旧端点可用、索引迁移就绪、前端适配编译、性能基线、git diff 范围
验证方法
mvn test 全量 + cd frontend-vue && npm run build + npx vitest run。