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

326 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`。