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

13 KiB
Raw Blame History

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)

  1. test_history_batch_loads — 批量加载装配
  2. test_history_single_row — 单条
  3. test_history_multiple_tasks — 多任务
  4. test_history_no_jobs — 无 Job 兼容
  5. test_history_order_unchanged — 排序不变
  6. test_history_pagination — 分页不变
  7. test_history_missing_related — 关联缺失兜底
  8. test_history_sql_count — IN 查询次数(≤N,断言 mapper 调用次数)

TDD 流程

  1. 写测试(mock mapper 断言查询次数与装配)→ RED
  2. 改造 history 实现 → GREEN
  3. 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)

  1. test_result_job_batch — 批量取 Job
  2. test_result_job_single — 单条
  3. test_result_job_empty — 空结果
  4. test_result_job_map_keyed — 按 resultId Map
  5. test_result_job_missing — 缺 Job 兜底
  6. test_result_job_query_count — 查询次数断言
  7. test_result_job_null_guard — null 安全
  8. test_result_job_consistency — 与现状一致

任务 108:dashboard 聚合查询

所属模块:06 批量加载 依赖:无 预估:8-15 分钟

功能点要求

dashboard 统计改批量聚合(COUNT/GROUP BY 一次出);状态分类计数与逐条统计结果一致;输出结构不变。

测试用例(≥8)

  1. test_dashboard_counts — 各状态计数
  2. test_dashboard_empty — 空用户 0 计数
  3. test_dashboard_aggregate_sql — 聚合 SQL 调用
  4. test_dashboard_recent_tasks — 最近任务列表
  5. test_dashboard_consistency — 与逐条一致
  6. test_dashboard_mixed_status — 混合状态
  7. test_dashboard_user_filter — 用户过滤
  8. 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)

  1. test_light_returns_light_fields — 只返回轻量字段
  2. test_light_missing_task — missingTaskIds
  3. test_light_empty_ids — 空 ids 空结果
  4. test_light_dedup_ids — 去重
  5. test_light_old_endpoint_untouched — 旧端点仍工作
  6. test_light_status_mapping — 状态映射正确
  7. test_light_file_fields — file 字段附带
  8. test_light_unknown_id — 未知 id 缺失列表

TDD 流程

  1. 测试(MockMvc 打新端点)→ RED(404)
  2. 实现 controller + service → GREEN
  3. mvn test -Dtest=SimilarAsinControllerTest 通过

任务 110:progress/light 字段白名单

所属模块:06 批量加载 依赖:109 预估:8-15 分钟

功能点要求

响应仅含白名单字段(taskId/status/statusCode/fileStatus/fileReady/updatedAt);不含 items 明细/payload/result 内容;序列化断言。

测试用例(≥8)

  1. test_whitelist_no_items — 无明细数组
  2. test_whitelist_no_payload — 无 payload 字段
  3. test_whitelist_exact_keys — 键集合精确匹配
  4. test_whitelist_file_phase — file 字段在白名单
  5. test_whitelist_extra_rejected — 多余键测试失败
  6. test_whitelist_null_values_ok — null 值允许
  7. test_whitelist_response_size_small — 响应体小(<1KB)
  8. test_whitelist_documented — 白名单文档一致

任务 111:progress/light 空/超长 taskIds

所属模块:06 批量加载 依赖:109 预估:8-15 分钟

功能点要求

空数组→空 items;null→空;>200 个截断或返回错误(定义行为);非正数过滤。

测试用例(≥8)

  1. test_light_empty_array — 空数组
  2. test_light_null_body — null body 处理
  3. test_light_negative_filter — 负数过滤
  4. test_light_zero_filter — 0 过滤
  5. test_light_over_200 — 超长截断/错误
  6. test_light_duplicates — 重复去重
  7. test_light_single — 单 id
  8. test_light_max_exact — 恰好上限

任务 112:progress/light 终态任务返回

所属模块:06 批量加载 依赖:109 预估:8-15 分钟

功能点要求

SUCCESS/FAILED 任务在 light 接口返回终态状态 + file 阶段;前端可凭此停止轮询并展示。

测试用例(≥8)

  1. test_light_success_task — SUCCESS 返回
  2. test_light_failed_task — FAILED 返回
  3. test_light_pending — PENDING
  4. test_light_running — RUNNING
  5. test_light_success_file_status — 附带 fileStatus
  6. test_light_failed_file_error — 失败附带 fileError
  7. test_light_terminal_complete — 终态字段完整
  8. 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)

  1. test_light_all_modules_exist — 12 个 light 端点存在
  2. test_light_common_shape — 响应结构一致
  3. test_light_module_specific_status — 各模块状态映射
  4. test_light_publish_files — publish 文件级字段
  5. test_light_old_endpoints_all_kept — 旧端点全保留
  6. test_light_whitelist_all — 白名单一致
  7. test_light_missing_all — 缺失任务处理
  8. test_light_contract_frozen — 契约快照

任务 114:批量加载等价快照测试

所属模块:06 批量加载 依赖:105-108 预估:8-15 分钟

功能点要求

改造前后同数据:历史页、结果页、dashboard 输出字段完全一致(快照对比)。

测试用例(≥8)

  1. test_history_snapshot_equiv — 历史快照一致
  2. test_dashboard_snapshot_equiv — dashboard 一致
  3. test_result_snapshot_equiv — 结果一致
  4. test_pagination_equiv — 分页一致
  5. test_snapshot_reproducible — 可重复
  6. test_snapshot_diff_fails — 篡改即失败
  7. test_snapshot_covers_all — 覆盖三页
  8. test_snapshot_regression_guard — 全量回归门禁

任务 115:高频查询 EXPLAIN 索引审计

所属模块:06 批量加载 依赖:无 预估:8-15 分钟

功能点要求

对高频查询(history/progress/dashboard)逐条 EXPLAIN;产出索引迁移清单(表/列/类型/收益/风险);不做 DDL。

测试用例(≥8)

  1. test_explain_history_plan — history 执行计划记录
  2. test_explain_progress_plan — progress 计划
  3. test_explain_dashboard_plan — dashboard 计划
  4. test_full_scan_detected — 全表扫描标记
  5. test_index_candidates_listed — 候选索引清单
  6. test_plan_documented — 审计文档产出
  7. test_plan_repeatable — 可重复执行
  8. test_no_ddl_this_task — 本任务无 DDL

任务 116:索引迁移 V{N+1}

所属模块:06 批量加载 依赖:115 预估:8-15 分钟

功能点要求

按审计清单追加 db/V{N+1}__*.sql(只追加不改历史);包含验证 SQL;标注锁表风险与窗口。

测试用例(≥8)

  1. test_migration_file_exists — 迁移文件存在
  2. test_migration_version_sequential — 版本号续接
  3. test_migration_validated — 验证 SQL 通过(副本库)
  4. test_migration_index_created — 索引生效
  5. test_explain_improved — 执行计划改善
  6. test_migration_no_alter_legacy — 不改历史迁移
  7. test_migration_rollback_doc — 回滚步骤记录
  8. test_migration_backward_safe — 旧数据兼容

任务 117:progress/light user_id 权限过滤

所属模块:06 批量加载 依赖:109 预估:8-15 分钟

功能点要求

user_id 传入时仅返回该用户任务;未传时按 taskId 反查;越权任务进 missingTaskIds(不泄露)。

测试用例(≥8)

  1. test_light_user_filter — 用户过滤
  2. test_light_no_user_reverse — 无 user 反查
  3. test_light_other_user_hidden — 他人任务隐藏
  4. test_light_missing_on_unauthorized — 越权进 missing
  5. test_light_user_null — 全空 userId
  6. test_light_admin_scope — 管理范围(按现状)
  7. test_light_user_consistent — 与旧端点一致
  8. test_light_no_leak — 响应不含他人数据

任务 118:前端 getModuleProgressLight 适配

所属模块:06 批量加载 依赖:109,44 预估:8-15 分钟

功能点要求

java-modules.ts 新增 getModuleProgressLight(module, taskIds) 调 light 端点;返回结构归一为现有 progress 类型;页面可渐进切换。

测试用例(≥8)

  1. test_light_url_module — 模块路径正确
  2. test_light_payload — taskIds body
  3. test_light_response_shape — 归一结构
  4. test_light_fallback_flag — 可开关
  5. test_light_missing_ids — missingTaskIds 映射
  6. test_light_timeout — 10s 超时
  7. test_light_type_compat — 与旧类型兼容
  8. test_light_snapshot — 快照

任务 119:前端 dashboard/history/progress 分离调用测试

所属模块:06 批量加载 依赖:无 预估:8-15 分钟

功能点要求

前端页面:dashboard 只调统计、history 只调摘要、progress 只调轻量;首次打开不加载全部明细;断言请求路径分离。

测试用例(≥8)

  1. test_page_dashboard_only_stats — 只调统计
  2. test_page_history_only_summary — 只调摘要
  3. test_page_progress_only_light — 只调进度
  4. test_page_no_full_detail_on_load — 首开不拉明细
  5. test_page_items_on_open — 打开明细才请求
  6. test_page_result_on_demand — 结果按需
  7. test_page_request_count_bounded — 请求数有界
  8. test_page_snapshot — 请求快照

任务 120:大页数据性能回归

所属模块:06 批量加载 依赖:105-108 预估:8-15 分钟

功能点要求

500 任务级数据:history/dashboard/progress 响应时间上界(基准线);不劣于改造前。

测试用例(≥8)

  1. test_perf_history_500 — 历史耗时
  2. test_perf_dashboard_500 — dashboard 耗时
  3. test_perf_progress_200 — 200 任务进度
  4. test_perf_light_200 — light 更快
  5. test_perf_query_count — 查询次数上界
  6. test_perf_no_regression — 与基线对比
  7. test_perf_memory_bounded — 内存有界
  8. test_perf_report — 结果记录

任务 121:N+1 扫描审计

所属模块:06 批量加载 依赖:无 预估:8-15 分钟

功能点要求

对 modules 下 Service 扫描逐条 selectById/selectOne 循环模式;产出 N+1 清单(位置/对象/影响);不做修改。

测试用例(≥8)

  1. test_scan_select_in_loop — 识别循环内单查
  2. test_scan_output_listed — 清单产出
  3. test_scan_priority — 按影响排序
  4. test_scan_module_coverage — 覆盖主要模块
  5. test_scan_false_positive_checked — 排除误报(已批量)
  6. test_scan_repeatable — 可重复
  7. test_scan_documented — 文档产出
  8. test_scan_no_edit — 本任务不改代码

任务 122:N+1 批量化修复

所属模块:06 批量加载 依赖:121 预估:8-15 分钟

功能点要求

按清单修复高影响 N+1(IN 查询 + Map 装配);行为不变;快照对比验证。

测试用例(≥8)

  1. test_fix_in_query — 改 IN 查询
  2. test_fix_map_assembly — Map 装配
  3. test_fix_behavior_same — 行为一致
  4. test_fix_single_row — 单行兼容
  5. test_fix_empty — 空兼容
  6. test_fix_query_count_reduced — 查询次数下降
  7. test_fix_snapshot — 输出快照
  8. 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。