`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
10 KiB
05-plan — 巨型 Service 纯函数抽取
对应
docs/specs/05-service-pure-function-extraction.md。目标:SimilarAsinTaskService(7228 行)、AppearancePatentTaskService(3195)、ShopDataCrawlTaskService(3013)。 纪律:只抽纯函数;门面签名不收缩;每模块独立提交;同一提交只做类拆分。
任务 83:SimilarAsinExcelParser 行解析器
所属模块:05 拆分 依赖:无 预估:8-15 分钟
功能点要求
新类 modules/similarasin/service/support/SimilarAsinExcelParser:POI 读 Excel 行 → 中间行对象(原始单元格值);输入 InputStream/文件 → 输出 List<中间行>;不改动现有解析语义(同一文件输出与现状逐字节一致)。
测试用例(≥8)
- test_parse_normal_rows — 正常多行解析
- test_parse_single_row — 单行
- test_parse_columns_mapping — 列序映射
- test_parse_empty_sheet — 空表返回空
- test_parse_empty_rows_skipped — 空行跳过
- test_parse_null_input_throws — 空输入抛 IllegalArgumentException
- test_parse_unsupported_format — 非 Excel 文件抛对应异常
- test_parse_no_mutation — 输入流不被篡改(可重复读)
TDD 流程
- 写测试(用夹具 xlsx 放 test resources)→ RED
- 实现解析器(从 Service 中搬移现有解析逻辑)→ GREEN
mvn test -Dtest=SimilarAsinExcelParserTest通过
任务 84:行解析边界测试
所属模块:05 拆分 依赖:83 预估:8-15 分钟
功能点要求
边界输入:超长字段(>32767)、畸形 ASIN(特殊字符)、BOM、混合编码、行数上限(>65535 xlsx)、数值/文本混合单元格。
测试用例(≥8)
- test_parse_long_field — 超长字段不截断/按现状
- test_parse_malformed_asin — 畸形 ASIN 原样透传
- test_parse_bom — BOM 头处理
- test_parse_mixed_encoding — 混合编码单元格
- test_parse_numeric_cell — 数值单元格转文本
- test_parse_date_cell — 日期单元格
- test_parse_formula_cell — 公式单元格取缓存值
- test_parse_large_sheet — 大表(5000 行)性能上界
任务 85:字段归一化器
所属模块:05 拆分 依赖:无 预估:8-15 分钟
功能点要求
SimilarAsinRowNormalizer:trim/大小写/ASIN 格式统一(保留现状规则,不改变输出);纯函数无状态。
测试用例(≥8)
- test_trim_whitespace — 首尾空白
- test_lowercase_asin — 小写转大写
- test_mixed_case_asin — 混合大小写统一
- test_internal_whitespace_kept — 内部空格保留(现状)
- test_null_safe — null 安全
- test_empty_string — 空串
- test_special_chars_untouched — 特殊字符不动
- test_normalize_identity_after — 幂等(二次归一不变)
任务 86:分组转换器
所属模块:05 拆分 依赖:83,85 预估:8-15 分钟
功能点要求
SimilarAsinGroupingConverter:归一化行 → 分组 → DTO(TaskItem/FileItem);分组规则与现状一致(同组/子行 2_2、2_3 处理);纯函数。
测试用例(≥8)
- test_group_normal — 正常分组
- test_group_sub_rows — 子行归组
- test_group_single_item — 单元素组
- test_group_empty_input — 空输入空输出
- test_group_dto_fields — DTO 字段映射
- test_group_dedup — 组内去重
- test_group_order — 分组顺序保持
- test_group_missing_key — 缺分组键兜底
任务 87:纯校验器
所属模块:05 拆分 依赖:85 预估:8-15 分钟
功能点要求
SimilarAsinRowValidator:必填检查、ASIN 格式校验、重复检测;返回错误清单(不抛异常,由调用方决定);规则与现状一致。
测试用例(≥8)
- test_validate_required_present — 必填齐全通过
- test_validate_required_missing — 缺必填报错
- test_validate_asin_format — ASIN 格式
- test_validate_duplicates — 重复标记
- test_validate_blank_row — 空白行
- test_validate_no_error_happy — 无误通过
- test_validate_error_detail — 错误含行列信息
- test_validate_null_input — 空输入错误清单
任务 88:Sheet 构造器
所属模块:05 拆分 依赖:无 预估:8-15 分钟
功能点要求
SimilarAsinSheetBuilder:结果 Workbook/Sheet 构造辅助(表头、列顺序、样式);输入数据 → 输出 workbook;不落库、无 IO 依赖。
测试用例(≥8)
- test_sheet_header_row — 表头正确
- test_sheet_column_order — 列顺序固定
- test_sheet_data_rows — 数据行写入
- test_sheet_empty_data — 空数据仍出表头
- test_sheet_style_applied — 样式应用
- test_sheet_zip_output — 可输出 xlsx 文件流
- test_sheet_large_rows — 大行数(5000)性能
- test_sheet_no_state_leak — 多次调用独立
任务 89:SimilarAsinService.parse 门面改委托
所属模块:05 拆分 依赖:83-88 预估:8-15 分钟
功能点要求
parse 方法内部改为:parser.parse → normalizer.normalize → validator → converter → 落库(落库逻辑保留原处);方法签名、参数、返回类型一字不变;删除搬走的代码。
测试用例(≥8)
- test_parse_signature_unchanged — 签名编译兼容
- test_parse_delegates_parser — 调用解析器
- test_parse_delegates_normalizer
- test_parse_delegates_validator
- test_parse_delegates_converter
- test_parse_persistence_kept — 落库逻辑仍在
- test_parse_result_same — 与改造前结果一致
- test_parse_exception_same — 异常行为一致
任务 90:抽取前后快照对比测试
所属模块:05 拆分 依赖:89 预估:8-15 分钟
功能点要求
夹具 Excel → 解析结果快照(golden 文件);抽取前后同一夹具输出完全一致;快照变更即失败(防止行为漂移)。
测试用例(≥8)
- test_snapshot_parse_output — 解析输出快照一致
- test_snapshot_groups — 分组快照
- test_snapshot_dtos — DTO 快照
- test_snapshot_error_cases — 错误案例快照
- test_snapshot_reproducible — 可重复(跑两次一致)
- test_snapshot_golden_committed — golden 文件存在
- test_snapshot_diff_detected — 篡改 golden 即失败
- test_snapshot_regression_all_parse — 全 parse 路径回归
任务 91:SimilarAsin 历史查询组装抽取
所属模块:05 拆分 依赖:无 预估:8-15 分钟
功能点要求
历史列表 VO 拼装(history + toHistoryItem 辅助)抽到独立组件 SimilarAsinHistoryAssembler;只读不落库;输出与现状一致。
测试用例(≥8)
- test_assembler_history_items — 历史项组装
- test_assembler_no_result — 无结果空列表
- test_assembler_file_state — file 状态附带
- test_assembler_order — 排序保持
- test_assembler_null_task — 缺 task 兜底
- test_assembler_download_url — URL 构造
- test_assembler_immutable_input — 输入不被改
- test_assembler_consistency — 与现状输出一致
任务 92:SimilarAsin 全量回归
所属模块:05 拆分 依赖:89-91 预估:8-15 分钟
功能点要求
similarasin 模块相关测试全绿;mvn test 无回归;API 行为与改造前一致。
测试用例(≥8)
1-8. 回归清单:新组件测试全绿、既有 similarasin 测试全绿、controller 签名编译、DTO 字段快照、Python 回调相关测试、单测全量、package 通过、git diff 无越界
TDD 流程 / 验证方法
mvn test + mvn clean package -DskipTests。
任务 93:AppearancePatent 行解析/归一化抽取
所属模块:05 拆分 依赖:83,85 预估:8-15 分钟
同 83/85 模式,针对 AppearancePatentTaskService 的解析与归一化逻辑(注意其 Excel 结构与 similarasin 不同)。
测试用例(≥8)
1-8:正常解析、单行、空表、空行、归一化规则、边界(超长/畸形)、输入安全、快照一致。
任务 94:AppearancePatent Sheet 构造抽取
所属模块:05 拆分 依赖:88 预估:8-15 分钟
同 88 模式(列顺序以 appearancepatent 现状为准)。
测试用例(≥8)
1-8:表头、列序、数据行、空数据、样式、输出流、大行数、无状态泄漏。
任务 95:AppearancePatent 门面改委托
所属模块:05 拆分 依赖:93,94 预估:8-15 分钟
同 89 模式;注意 appearancepatent 的 submitResult 双事务路径不动。
测试用例(≥8)
1-8:签名不变、委托各组件、落库保留、结果一致、异常一致、双事务路径不变、owner 检查不变、全回归。
任务 96:AppearancePatent 快照对比测试
所属模块:05 拆分 依赖:95 预估:8-15 分钟
同 90 模式(夹具为 appearancepatent 实际 Excel 结构)。
测试用例(≥8)
同 90。
任务 97:AppearancePatent 历史查询组装抽取
所属模块:05 拆分 依赖:无 预估:8-15 分钟
同 91 模式。
测试用例(≥8)
同 91。
任务 98:AppearancePatent 全量回归
所属模块:05 拆分 依赖:95-97 预估:8-15 分钟
同 92 模式。
测试用例(≥8)
同 92(appearancepatent 相关)。
任务 99:ShopDataCrawl 行解析抽取
所属模块:05 拆分 依赖:83,85 预估:8-15 分钟
同 93 模式(shopdatacrawl 结构)。
测试用例(≥8)
同 93。
任务 100:ShopDataCrawl Sheet 构造抽取
所属模块:05 拆分 依赖:88 预估:8-15 分钟
同 94 模式。
测试用例(≥8)
同 94。
任务 101:ShopDataCrawl 门面改委托
所属模块:05 拆分 依赖:99,100 预估:8-15 分钟
同 95 模式。
测试用例(≥8)
同 95。
任务 102:ShopDataCrawl 快照对比测试
所属模块:05 拆分 依赖:101 预估:8-15 分钟
同 96 模式。
测试用例(≥8)
同 96。
任务 103:ShopDataCrawl 历史查询组装抽取
所属模块:05 拆分 依赖:无 预估:8-15 分钟
同 97 模式。
测试用例(≥8)
同 97。
任务 104:ShopDataCrawl 全量回归
所属模块:05 拆分 依赖:101-103 预估:8-15 分钟
同 98 模式。
测试用例(≥8)
同 98。
收尾验证(本模块)
mvn test 全量 + mvn clean package -DskipTests;05 spec §4 不变要求逐项核对;三模块各一个独立提交。