# 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`。