refactor(phase-4): 解散万能 util——similarasin/util 与 common/util 按域归位

similarasin/util 7 支:
- 域内件(SimilarAsinImageEmbedder/PuzzleImageMerger/SimilarAsinLogSupport/
  BoundedImageCache)并入既有 service/support 先例;
- 通用 Excel 件(ExcelCellImageWriter/WpsCellImageWriter)归 common/excel;
- 仅测试用的 SimilarAsinPerfFixture 移出生产源到 src/test。

common/util 13 支解散为四个关注点包:excel(读/写/单元格图片)、
text(BrandLabel/SecretMasking/UserMessages)、task(行过滤/分组传播/判死文案/
删除台账/锁跳过留痕)、support(LRU/下载头/线程池)。老 util 目录不再存在。

纯粹的包搬迁与 import 重写(diff 219 增 / 217 删),零行为改动:
搬迁前后由 SimilarAsinCreateTaskSnapshotTest 的建单入口 golden 对撞相等;
新增 MovedComponentScanTest 钉住三枚 @Component 仍被根包扫描发现、老包零残留。
This commit is contained in:
2026-10-23 00:59:53 +08:00
parent 8f6913fb4a
commit dbe35dfcb5
162 changed files with 282 additions and 217 deletions
@@ -0,0 +1,166 @@
package com.nanri.aiimage.common.excel;
import org.junit.jupiter.api.Test;
import java.time.Duration;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.zip.ZipEntry;
import java.util.zip.ZipFile;
import java.util.zip.ZipOutputStream;
import static org.junit.jupiter.api.Assertions.assertArrayEquals;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTimeoutPreemptively;
import static org.junit.jupiter.api.Assertions.assertTrue;
class ExcelCellImageWriterTest {
@Test
void patchedCellImageValueMetadataUsesOneBasedVmIndexes() throws Exception {
Path dir = Files.createTempDirectory("excel-cell-image-test-");
Path xlsx = dir.resolve("result.xlsx");
writeMinimalWorkbook(xlsx);
ExcelCellImageWriter.Session session = ExcelCellImageWriter.createSession();
session.registerImage(1, 9, new byte[]{1, 2, 3});
session.registerImage(1, 10, new byte[]{4, 5, 6});
ExcelCellImageWriter.patchXlsxFile(xlsx.toFile(), session);
try (ZipFile zip = new ZipFile(xlsx.toFile())) {
String sheet = read(zip, "xl/worksheets/sheet1.xml");
// cell @vm 是 [MS-XLSX] 规范里的 1-based 索引(0 表示"无 metadata")。
assertTrue(sheet.contains("<c r=\"J2\" t=\"e\" vm=\"1\"><v>#VALUE!</v></c>"));
assertTrue(sheet.contains("<c r=\"K2\" t=\"e\" vm=\"2\"><v>#VALUE!</v></c>"));
// futureMetadata 内部块仍然是 0-based。
String metadata = read(zip, "xl/metadata.xml");
assertTrue(metadata.contains("<xlrd:rvb i=\"0\"/>"));
assertTrue(metadata.contains("<xlrd:rvb i=\"1\"/>"));
assertEquals(2, maxVm(sheet));
}
}
@Test
void streamsRegisteredImagePathIntoWorkbookMedia() throws Exception {
Path dir = Files.createTempDirectory("excel-cell-image-path-test-");
Path xlsx = dir.resolve("result.xlsx");
Path image = dir.resolve("thumb.jpeg");
byte[] imageBytes = new byte[]{7, 8, 9, 10};
writeMinimalWorkbook(xlsx);
Files.write(image, imageBytes);
ExcelCellImageWriter.Session session = ExcelCellImageWriter.createSession();
session.registerImage(1, 9, image);
ExcelCellImageWriter.patchXlsxFile(xlsx.toFile(), session);
try (ZipFile zip = new ZipFile(xlsx.toFile())) {
assertArrayEquals(imageBytes,
zip.getInputStream(zip.getEntry("xl/media/excelcellimage1.jpeg")).readAllBytes());
}
}
@Test
void patchesTenThousandImageCellsWithinLinearTimeBudget() {
assertTimeoutPreemptively(Duration.ofSeconds(10), () -> {
Path dir = Files.createTempDirectory("excel-cell-image-linear-test-");
Path xlsx = dir.resolve("result.xlsx");
writeWorkbookWithImageCells(xlsx, 10_000);
ExcelCellImageWriter.Session session = ExcelCellImageWriter.createSession();
for (int row = 1; row <= 10_000; row++) {
session.registerImage(row, 9, new byte[]{1});
}
ExcelCellImageWriter.patchXlsxFile(xlsx.toFile(), session);
try (ZipFile zip = new ZipFile(xlsx.toFile())) {
String sheet = read(zip, "xl/worksheets/sheet1.xml");
assertEquals(10_000, maxVm(sheet));
assertTrue(sheet.contains("<c r=\"J10001\" t=\"e\" vm=\"10000\"><v>#VALUE!</v></c>"));
}
});
}
private static int maxVm(String sheet) {
Matcher matcher = Pattern.compile("vm=\"(\\d+)\"").matcher(sheet);
int max = -1;
while (matcher.find()) {
max = Math.max(max, Integer.parseInt(matcher.group(1)));
}
return max;
}
private static String read(ZipFile zip, String name) throws Exception {
return new String(zip.getInputStream(zip.getEntry(name)).readAllBytes(), StandardCharsets.UTF_8);
}
private static void writeMinimalWorkbook(Path xlsx) throws Exception {
try (ZipOutputStream out = new ZipOutputStream(Files.newOutputStream(xlsx))) {
write(out, "[Content_Types].xml", """
<?xml version="1.0" encoding="UTF-8"?>
<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
<Default Extension="xml" ContentType="application/xml"/>
<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>
<Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>
</Types>
""");
write(out, "_rels/.rels", """
<?xml version="1.0" encoding="UTF-8"?>
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>
</Relationships>
""");
write(out, "xl/workbook.xml", """
<?xml version="1.0" encoding="UTF-8"?>
<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"
xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
<sheets><sheet name="Sheet1" r:id="rId1" sheetId="1"/></sheets>
</workbook>
""");
write(out, "xl/_rels/workbook.xml.rels", """
<?xml version="1.0" encoding="UTF-8"?>
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>
</Relationships>
""");
write(out, "xl/worksheets/sheet1.xml", """
<?xml version="1.0" encoding="UTF-8"?>
<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">
<sheetData>
<row r="2">
<c r="J2" t="inlineStr"><is><t>main</t></is></c>
<c r="K2" t="inlineStr"><is><t>puzzle</t></is></c>
</row>
</sheetData>
</worksheet>
""");
}
}
private static void writeWorkbookWithImageCells(Path xlsx, int imageCount) throws Exception {
try (ZipOutputStream out = new ZipOutputStream(Files.newOutputStream(xlsx))) {
write(out, "[Content_Types].xml", "<Types></Types>");
write(out, "xl/_rels/workbook.xml.rels", "<Relationships></Relationships>");
StringBuilder sheet = new StringBuilder("<worksheet><sheetData>");
for (int row = 2; row <= imageCount + 1; row++) {
sheet.append("<row r=\"").append(row).append("\"><c r=\"J").append(row)
.append("\" t=\"inlineStr\"><is><t>image</t></is></c></row>");
}
sheet.append("</sheetData></worksheet>");
write(out, "xl/worksheets/sheet1.xml", sheet.toString());
}
}
private static void write(ZipOutputStream out, String name, String content) throws Exception {
out.putNextEntry(new ZipEntry(name));
out.write(content.getBytes(StandardCharsets.UTF_8));
out.closeEntry();
}
}
@@ -0,0 +1,185 @@
package com.nanri.aiimage.common.excel;
import com.alibaba.excel.EasyExcel;
import com.nanri.aiimage.common.exception.BusinessException;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.Map;
import java.util.zip.ZipEntry;
import java.util.zip.ZipOutputStream;
import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertSame;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* ExcelStreamReader 的异常出口契约(现网缺陷:带单元格图片的 xlsx 解析失败时
* POI 的 ExcelAnalysisException 原样冒到 GlobalExceptionHandler,用户拿到 HTTP 500 且看不到真因)。
*/
class ExcelStreamReaderParseFailureTest {
@TempDir
Path tempDir;
/** 生产现场形状:xlsx 包里有一个未声明 content type 的 media 部件。 */
@Test
void parseFailureOnMalformedPackageSurfacesAsIoExceptionWithReason() throws Exception {
Path bad = tempDir.resolve("cellimage-no-content-type.xlsx");
Files.write(bad, packageWithUndeclaredMediaPart());
IOException thrown = assertThrows(IOException.class,
() -> ExcelStreamReader.readFirstSheet(bad.toFile(), noopHandler()));
String reason = rawParseFailureMessageOf(bad);
assertTrue(thrown.getMessage().contains(reason),
"消息里要能看到底层真因 [" + reason + "],实际=" + thrown.getMessage());
}
/** 反向钉:读全部 sheet 的入口同样收口(另有 6 个调用点走这条)。 */
@Test
void parseFailureOnReadAllSheetsAlsoSurfacesAsIoException() throws Exception {
Path bad = tempDir.resolve("cellimage-no-content-type-all.xlsx");
Files.write(bad, packageWithUndeclaredMediaPart());
assertThrows(IOException.class, () -> ExcelStreamReader.readAllSheets(bad.toFile(), noopHandler()));
}
/** 反向钉:调用方在 onRow 里抛的业务异常不能被改写成 IOException,否则 400 语义会塌成"文件坏了"。 */
@Test
void handlerBusinessExceptionIsNotRewrittenIntoIoException() throws Exception {
Path good = writeWorkbook();
BusinessException thrown = assertThrows(BusinessException.class, () -> ExcelStreamReader
.readFirstSheet(good.toFile(), rowHandlerThatThrows(
new BusinessException("品牌列缺失,请检查表头"))));
assertEquals("品牌列缺失,请检查表头", thrown.getMessage());
}
/** 调用方抛的运行时异常原样透传,不借"解析失败"这条路被包成 IOException。 */
@Test
void handlerRuntimeExceptionPropagatesUnchanged() throws Exception {
Path good = writeWorkbook();
IllegalStateException failure = new IllegalStateException("行处理失败");
IllegalStateException thrown = assertThrows(IllegalStateException.class,
() -> ExcelStreamReader.readFirstSheet(good.toFile(), rowHandlerThatThrows(failure)));
assertSame(failure, thrown);
}
/** 调用方抛的受检异常走 IOException 契约,且不把内部包装类漏给调用方。 */
@Test
void handlerCheckedExceptionSurfacesAsIoExceptionWithReason() throws Exception {
Path good = writeWorkbook();
IOException thrown = assertThrows(IOException.class, () -> ExcelStreamReader.readFirstSheet(
good.toFile(), rowHandlerThatThrows(new Exception("行数据超出上限 5000"))));
assertTrue(thrown.getMessage().contains("行数据超出上限 5000"),
"消息里要能看到调用方抛出的真因,实际=" + thrown.getMessage());
}
/** 好文件照旧能读完(保证收口没有把正常路径一起改掉)。 */
@Test
void validWorkbookStillReadsRows() throws Exception {
Path good = writeWorkbook();
StringBuilder seen = new StringBuilder();
assertDoesNotThrow(() -> ExcelStreamReader.readFirstSheet(
good.toFile(), (sheetName, sheetNo, rowIndex, headerMap, rowMap) ->
seen.append(rowMap.get(0))));
assertEquals("Nike", seen.toString());
}
private Path writeWorkbook() {
Path file = tempDir.resolve("ok.xlsx");
List<List<String>> head = List.of(List.of("品牌"), List.of("ASIN"));
List<List<String>> data = List.of(List.of("Nike", "B01ABC"));
EasyExcel.write(file.toFile()).head(head).sheet("Sheet1").doWrite(data);
return file;
}
private ExcelStreamReader.SheetRowHandler noopHandler() {
return new ExcelStreamReader.SheetRowHandler() {
@Override
public void onRow(String sheetName, Integer sheetNo, int rowIndex,
Map<Integer, String> headerMap, Map<Integer, String> rowMap) {
}
};
}
private ExcelStreamReader.SheetRowHandler rowHandlerThatThrows(Exception failure) {
return new ExcelStreamReader.SheetRowHandler() {
@Override
public void onRow(String sheetName, Integer sheetNo, int rowIndex,
Map<Integer, String> headerMap, Map<Integer, String> rowMap) throws Exception {
throw failure;
}
};
}
/** 直接喂同一个坏包,取 POI 自己报出来的真因文本,用来断言它没被收口吞掉。 */
private String rawParseFailureMessageOf(Path badFile) throws IOException {
String message = null;
try (var input = Files.newInputStream(badFile)) {
EasyExcel.read(input).sheet(0).headRowNumber(1).doRead();
throw new AssertionError("构造的坏包必须让 EasyExcel 抛异常,否则这条用例证明不了收口");
} catch (RuntimeException ex) {
Throwable deepest = ex;
while (deepest.getCause() != null) {
deepest = deepest.getCause();
}
message = deepest.getMessage();
}
assertTrue(message != null && message.length() > 20,
"底层真因文本应当有信息量,实际=" + message);
return message;
}
private byte[] packageWithUndeclaredMediaPart() throws IOException {
ByteArrayOutputStream bytes = new ByteArrayOutputStream();
try (ZipOutputStream zip = new ZipOutputStream(bytes, StandardCharsets.UTF_8)) {
put(zip, "[Content_Types].xml", """
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
<Default Extension="xml" ContentType="application/xml"/>
<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>
</Types>""");
put(zip, "_rels/.rels", """
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>
</Relationships>""");
put(zip, "xl/workbook.xml", """
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
<sheets><sheet name="Sheet1" sheetId="1" r:id="rId1"/></sheets>
</workbook>""");
put(zip, "xl/_rels/workbook.xml.rels", """
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/cellImages" Target="cellimages.xml"/>
</Relationships>""");
put(zip, "xl/cellimages.xml", """
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cellImages xmlns="http://www.wps.cn/officeDocument/2020/cellImage"/>""");
zip.putNextEntry(new ZipEntry("xl/media/cellimage1.jpeg"));
zip.write(new byte[]{(byte) 0xFF, (byte) 0xD8, (byte) 0xFF, (byte) 0xD9});
zip.closeEntry();
}
return bytes.toByteArray();
}
private void put(ZipOutputStream zip, String name, String content) throws IOException {
zip.putNextEntry(new ZipEntry(name));
zip.write(content.getBytes(StandardCharsets.UTF_8));
zip.closeEntry();
}
}
@@ -0,0 +1,142 @@
package com.nanri.aiimage.common.excel;
import org.apache.poi.ss.usermodel.CellStyle;
import org.apache.poi.ss.usermodel.Font;
import org.apache.poi.ss.usermodel.Row;
import org.apache.poi.ss.usermodel.Sheet;
import org.apache.poi.xssf.streaming.SXSSFWorkbook;
import org.junit.jupiter.api.Test;
import javax.imageio.ImageIO;
import java.awt.Color;
import java.awt.Graphics2D;
import java.awt.image.BufferedImage;
import java.io.ByteArrayOutputStream;
import java.io.File;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.util.zip.ZipFile;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* WPS DISPIMG 协议回归测试:真实写入流水线(SXSSF 写公式格 → patch)产出的 part 必须与
* WPS 12.1 实测通过的原生形态一致。2026-09-09 曾因三处协议细节与 WPS 原生产物不一致
* (Content-Type / workbook 关系类型 / 公式格形态)导致 WPS 打开显示 #REF,本测试锁死这些契约。
*/
class WpsCellImageWriterProtocolTest {
private static byte[] jpeg(int size) throws Exception {
BufferedImage image = new BufferedImage(size, size, BufferedImage.TYPE_INT_RGB);
Graphics2D g = image.createGraphics();
g.setColor(Color.WHITE);
g.fillRect(0, 0, size, size);
g.dispose();
ByteArrayOutputStream baos = new ByteArrayOutputStream();
assertTrue(ImageIO.write(image, "jpg", baos), "JPEG writer should be available");
return baos.toByteArray();
}
@Test
void patchedWorkbookMatchesWpsNativeShape() throws Exception {
File xlsx = File.createTempFile("wps-dispimg-protocol-", ".xlsx");
xlsx.deleteOnExit();
try {
WpsCellImageWriter.Session session = WpsCellImageWriter.createSession();
byte[] jpeg = jpeg(300);
String imageId = session.registerImage(jpeg, 300, 300);
assertNotNull(imageId, "图片注册应返回 ID");
assertTrue(imageId.matches("ID_[0-9A-F]{32}"), "图片 ID 应为 WPS 风格 ID_+32hex, got=" + imageId);
try (SXSSFWorkbook workbook = new SXSSFWorkbook(200)) {
Sheet sheet = workbook.createSheet("相似asin检测");
CellStyle headerStyle = workbook.createCellStyle();
Font font = workbook.createFont();
font.setBold(true);
headerStyle.setFont(font);
sheet.setColumnWidth(12, 80 * 256);
Row header = sheet.createRow(0);
header.createCell(0).setCellValue("id");
sheet.createRow(1).createCell(0).setCellValue("827665");
Row row = sheet.createRow(1);
row.setHeightInPoints(409f);
row.createCell(12).setCellFormula(WpsCellImageWriter.dispImgFormula(imageId));
try (var fos = Files.newOutputStream(xlsx.toPath())) {
workbook.write(fos);
}
workbook.dispose();
}
WpsCellImageWriter.patchXlsxFile(xlsx, session);
try (ZipFile zf = new ZipFile(xlsx)) {
String sheetXml = readEntry(zf, "xl/worksheets/sheet1.xml");
assertTrue(sheetXml.contains("<f t=\"shared\" ref=\"M2\">_xlfn.DISPIMG(\"" + imageId + "\",1)</f>"),
"公式格应为 WPS 原生形态(f t=shared/ref+公式字符串 v), got=" + snippet(sheetXml, "M2"));
assertTrue(sheetXml.contains("<v>=DISPIMG(\"" + imageId + "\",1)</v>"),
"公式格 <v> 应为 =DISPIMG(...) 形态");
String ct = readEntry(zf, "[Content_Types].xml");
assertTrue(ct.contains("application/vnd.wps-officedocument.cellimage+xml"),
"cellimages Content-Type 应为 vnd.wps-officedocument.cellimage+xml");
String rels = readEntry(zf, "xl/_rels/workbook.xml.rels");
assertTrue(rels.contains("http://www.wps.cn/officeDocument/2020/cellImage"),
"cellimages 关系类型应为 wps.cn/officeDocument/2020/cellImage");
String cellImages = readEntry(zf, "xl/cellimages.xml");
assertTrue(cellImages.contains("r:embed=\"rId1\""), "cellimages.xml 应引用 rId1");
assertTrue(cellImages.contains("<a:xfrm>"), "spPr 应含 a:xfrm");
assertTrue(cellImages.contains("cx=\"2857500\""), "a:ext 应按 300px×9525EMU 换算");
assertTrue(cellImages.contains("name=\"" + imageId + "\""), "cNvPr name 应为图片 ID");
String cellImagesRels = readEntry(zf, "xl/_rels/cellimages.xml.rels");
assertTrue(cellImagesRels.contains("Target=\"media/cellimage1.jpeg\""), "rels 应指向 media/cellimage1.jpeg");
}
} finally {
Files.deleteIfExists(xlsx.toPath());
}
}
@Test
void repatchIsIdempotent() throws Exception {
File xlsx = File.createTempFile("wps-dispimg-idempotent-", ".xlsx");
xlsx.deleteOnExit();
try {
WpsCellImageWriter.Session session = WpsCellImageWriter.createSession();
String imageId = session.registerImage(jpeg(64), 64, 64);
try (SXSSFWorkbook workbook = new SXSSFWorkbook(200)) {
Sheet sheet = workbook.createSheet("s");
Row row = sheet.createRow(1);
row.setHeightInPoints(409f);
row.createCell(12).setCellFormula(WpsCellImageWriter.dispImgFormula(imageId));
try (var fos = Files.newOutputStream(xlsx.toPath())) {
workbook.write(fos);
}
workbook.dispose();
}
WpsCellImageWriter.patchXlsxFile(xlsx, session);
WpsCellImageWriter.patchXlsxFile(xlsx, session);
try (ZipFile zf = new ZipFile(xlsx)) {
String sheetXml = readEntry(zf, "xl/worksheets/sheet1.xml");
assertTrue(sheetXml.contains("<f t=\"shared\" ref=\"M2\">_xlfn.DISPIMG(\"" + imageId + "\",1)</f>"),
"重复 patch 不应破坏公式格");
assertTrue(!sheetXml.contains("<f>_xlfn.DISPIMG"),
"不应残留未规范化的裸公式格");
}
} finally {
Files.deleteIfExists(xlsx.toPath());
}
}
private static String readEntry(ZipFile zf, String name) throws Exception {
try (var in = zf.getInputStream(zf.getEntry(name))) {
return new String(in.readAllBytes(), StandardCharsets.UTF_8);
}
}
private static String snippet(String xml, String cellRef) {
int idx = xml.indexOf("r=\"" + cellRef + "\"");
return idx < 0 ? "<not found>" : xml.substring(Math.max(0, idx), Math.min(xml.length(), idx + 160));
}
}