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

10 KiB
Raw Blame History

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)

  1. test_parse_normal_rows — 正常多行解析
  2. test_parse_single_row — 单行
  3. test_parse_columns_mapping — 列序映射
  4. test_parse_empty_sheet — 空表返回空
  5. test_parse_empty_rows_skipped — 空行跳过
  6. test_parse_null_input_throws — 空输入抛 IllegalArgumentException
  7. test_parse_unsupported_format — 非 Excel 文件抛对应异常
  8. test_parse_no_mutation — 输入流不被篡改(可重复读)

TDD 流程

  1. 写测试(用夹具 xlsx 放 test resources)→ RED
  2. 实现解析器(从 Service 中搬移现有解析逻辑)→ GREEN
  3. mvn test -Dtest=SimilarAsinExcelParserTest 通过

任务 84:行解析边界测试

所属模块:05 拆分 依赖:83 预估:8-15 分钟

功能点要求

边界输入:超长字段(>32767)、畸形 ASIN(特殊字符)、BOM、混合编码、行数上限(>65535 xlsx)、数值/文本混合单元格。

测试用例(≥8)

  1. test_parse_long_field — 超长字段不截断/按现状
  2. test_parse_malformed_asin — 畸形 ASIN 原样透传
  3. test_parse_bom — BOM 头处理
  4. test_parse_mixed_encoding — 混合编码单元格
  5. test_parse_numeric_cell — 数值单元格转文本
  6. test_parse_date_cell — 日期单元格
  7. test_parse_formula_cell — 公式单元格取缓存值
  8. test_parse_large_sheet — 大表(5000 行)性能上界

任务 85:字段归一化器

所属模块:05 拆分 依赖:无 预估:8-15 分钟

功能点要求

SimilarAsinRowNormalizer:trim/大小写/ASIN 格式统一(保留现状规则,不改变输出);纯函数无状态。

测试用例(≥8)

  1. test_trim_whitespace — 首尾空白
  2. test_lowercase_asin — 小写转大写
  3. test_mixed_case_asin — 混合大小写统一
  4. test_internal_whitespace_kept — 内部空格保留(现状)
  5. test_null_safe — null 安全
  6. test_empty_string — 空串
  7. test_special_chars_untouched — 特殊字符不动
  8. test_normalize_identity_after — 幂等(二次归一不变)

任务 86:分组转换器

所属模块:05 拆分 依赖:83,85 预估:8-15 分钟

功能点要求

SimilarAsinGroupingConverter:归一化行 → 分组 → DTO(TaskItem/FileItem);分组规则与现状一致(同组/子行 2_2、2_3 处理);纯函数。

测试用例(≥8)

  1. test_group_normal — 正常分组
  2. test_group_sub_rows — 子行归组
  3. test_group_single_item — 单元素组
  4. test_group_empty_input — 空输入空输出
  5. test_group_dto_fields — DTO 字段映射
  6. test_group_dedup — 组内去重
  7. test_group_order — 分组顺序保持
  8. test_group_missing_key — 缺分组键兜底

任务 87:纯校验器

所属模块:05 拆分 依赖:85 预估:8-15 分钟

功能点要求

SimilarAsinRowValidator:必填检查、ASIN 格式校验、重复检测;返回错误清单(不抛异常,由调用方决定);规则与现状一致。

测试用例(≥8)

  1. test_validate_required_present — 必填齐全通过
  2. test_validate_required_missing — 缺必填报错
  3. test_validate_asin_format — ASIN 格式
  4. test_validate_duplicates — 重复标记
  5. test_validate_blank_row — 空白行
  6. test_validate_no_error_happy — 无误通过
  7. test_validate_error_detail — 错误含行列信息
  8. test_validate_null_input — 空输入错误清单

任务 88:Sheet 构造器

所属模块:05 拆分 依赖:无 预估:8-15 分钟

功能点要求

SimilarAsinSheetBuilder:结果 Workbook/Sheet 构造辅助(表头、列顺序、样式);输入数据 → 输出 workbook;不落库、无 IO 依赖。

测试用例(≥8)

  1. test_sheet_header_row — 表头正确
  2. test_sheet_column_order — 列顺序固定
  3. test_sheet_data_rows — 数据行写入
  4. test_sheet_empty_data — 空数据仍出表头
  5. test_sheet_style_applied — 样式应用
  6. test_sheet_zip_output — 可输出 xlsx 文件流
  7. test_sheet_large_rows — 大行数(5000)性能
  8. test_sheet_no_state_leak — 多次调用独立

任务 89:SimilarAsinService.parse 门面改委托

所属模块:05 拆分 依赖:83-88 预估:8-15 分钟

功能点要求

parse 方法内部改为:parser.parse → normalizer.normalize → validator → converter → 落库(落库逻辑保留原处);方法签名、参数、返回类型一字不变;删除搬走的代码。

测试用例(≥8)

  1. test_parse_signature_unchanged — 签名编译兼容
  2. test_parse_delegates_parser — 调用解析器
  3. test_parse_delegates_normalizer
  4. test_parse_delegates_validator
  5. test_parse_delegates_converter
  6. test_parse_persistence_kept — 落库逻辑仍在
  7. test_parse_result_same — 与改造前结果一致
  8. test_parse_exception_same — 异常行为一致

任务 90:抽取前后快照对比测试

所属模块:05 拆分 依赖:89 预估:8-15 分钟

功能点要求

夹具 Excel → 解析结果快照(golden 文件);抽取前后同一夹具输出完全一致;快照变更即失败(防止行为漂移)。

测试用例(≥8)

  1. test_snapshot_parse_output — 解析输出快照一致
  2. test_snapshot_groups — 分组快照
  3. test_snapshot_dtos — DTO 快照
  4. test_snapshot_error_cases — 错误案例快照
  5. test_snapshot_reproducible — 可重复(跑两次一致)
  6. test_snapshot_golden_committed — golden 文件存在
  7. test_snapshot_diff_detected — 篡改 golden 即失败
  8. test_snapshot_regression_all_parse — 全 parse 路径回归

任务 91:SimilarAsin 历史查询组装抽取

所属模块:05 拆分 依赖:无 预估:8-15 分钟

功能点要求

历史列表 VO 拼装(history + toHistoryItem 辅助)抽到独立组件 SimilarAsinHistoryAssembler;只读不落库;输出与现状一致。

测试用例(≥8)

  1. test_assembler_history_items — 历史项组装
  2. test_assembler_no_result — 无结果空列表
  3. test_assembler_file_state — file 状态附带
  4. test_assembler_order — 排序保持
  5. test_assembler_null_task — 缺 task 兜底
  6. test_assembler_download_url — URL 构造
  7. test_assembler_immutable_input — 输入不被改
  8. 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 不变要求逐项核对;三模块各一个独立提交。