docs(仓库): 规划文档改为入库,落盘品牌库/去重库每公司一套二期方案
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
This commit is contained in:
@@ -0,0 +1,325 @@
|
||||
# 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`。
|
||||
Reference in New Issue
Block a user