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

287 lines
10 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.
# 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 不变要求逐项核对;三模块各一个独立提交。