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,473 @@
package com.nanri.aiimage.common.excel;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.io.BufferedOutputStream;
import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.util.ArrayList;
import java.util.Enumeration;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
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;
/**
* Excel 365 "Place in Cell" 图片写入器。
* <p>
* 该格式不是传统 drawing 浮动图片,而是 richData 单元格值:点击图片区域选中的是单元格,
* 图片无法像浮动对象一样拖到任意位置,也不需要开启工作表保护。
*/
public final class ExcelCellImageWriter {
private static final Logger log = LoggerFactory.getLogger(ExcelCellImageWriter.class);
private static final String CONTENT_TYPES_PART = "[Content_Types].xml";
private static final String WORKBOOK_RELS_PART = "xl/_rels/workbook.xml.rels";
private static final String SHEET1_PART = "xl/worksheets/sheet1.xml";
private static final String RICH_VALUE_RELS_PART = "xl/richData/_rels/richValueRel.xml.rels";
private static final String RD_RICH_VALUE_PART = "xl/richData/rdrichvalue.xml";
private static final String RD_RICH_VALUE_STRUCTURE_PART = "xl/richData/rdrichvaluestructure.xml";
private static final String RD_RICH_VALUE_TYPES_PART = "xl/richData/rdRichValueTypes.xml";
private static final String RICH_VALUE_REL_PART = "xl/richData/richValueRel.xml";
private static final String METADATA_PART = "xl/metadata.xml";
private static final Pattern SHEET_CELL_PATTERN = Pattern.compile(
"<c\\b(?=[^>]*\\br=\"([A-Z]+[1-9][0-9]*)\")[^>]*(?:/>|>.*?</c>)",
Pattern.DOTALL);
private static final String REL_TYPE_IMAGE =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
private static final String REL_TYPE_RICH_VALUE_STRUCTURE =
"http://schemas.microsoft.com/office/2017/06/relationships/rdRichValueStructure";
private static final String REL_TYPE_RICH_VALUE =
"http://schemas.microsoft.com/office/2017/06/relationships/rdRichValue";
private static final String REL_TYPE_RICH_VALUE_REL =
"http://schemas.microsoft.com/office/2022/10/relationships/richValueRel";
private static final String REL_TYPE_SHEET_METADATA =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/sheetMetadata";
private static final String REL_TYPE_RICH_VALUE_TYPES =
"http://schemas.microsoft.com/office/2017/06/relationships/rdRichValueTypes";
private ExcelCellImageWriter() {
}
public static Session createSession() {
return new Session();
}
public static void patchXlsxFile(File xlsx, Session session) throws IOException {
if (xlsx == null || !xlsx.exists() || session == null || session.isEmpty()) {
return;
}
Path xlsxPath = xlsx.toPath().toAbsolutePath();
Path parent = xlsxPath.getParent();
if (parent == null) {
throw new IOException("[excel-cell-image] xlsx has no parent directory: " + xlsxPath);
}
Path tmp = Files.createTempFile(parent, "excel-cell-image-", ".xlsx");
boolean success = false;
Set<String> replacementNames = replacementEntryNames(session);
int patchedCells = -1;
try {
try (ZipFile zfIn = new ZipFile(xlsxPath.toFile());
// 与 WpsCellImageWriter 同一处修法:每个 entry 的头/数据/中央目录项都是独立 syscall,
// 万级图片时写放大占大头(实测 media loop 3.0s + close 4.1s)
ZipOutputStream zout = new ZipOutputStream(new BufferedOutputStream(
Files.newOutputStream(tmp), 64 * 1024))) {
Enumeration<? extends ZipEntry> entries = zfIn.entries();
while (entries.hasMoreElements()) {
ZipEntry entry = entries.nextElement();
String name = entry.getName();
if (replacementNames.contains(name)) {
continue;
}
if (entry.isDirectory()) {
writeDirectoryEntry(zout, name);
continue;
}
byte[] bytes;
try (InputStream in = zfIn.getInputStream(entry)) {
bytes = readAll(in);
}
if (CONTENT_TYPES_PART.equals(name)) {
bytes = patchContentTypes(bytes);
} else if (WORKBOOK_RELS_PART.equals(name)) {
bytes = patchWorkbookRels(bytes);
} else if (SHEET1_PART.equals(name)) {
PatchSheetResult sheetResult = patchSheet(bytes, session);
bytes = sheetResult.bytes();
patchedCells = sheetResult.patchedCount();
if (sheetResult.patchedCount() != session.size()) {
log.warn("[excel-cell-image] patched cells mismatch file={} images={} patchedCells={}",
xlsx.getName(), session.size(), sheetResult.patchedCount());
}
}
writeEntry(zout, name, bytes);
}
writeEntry(zout, RICH_VALUE_RELS_PART, buildRichValueRels(session).getBytes(StandardCharsets.UTF_8));
writeEntry(zout, RD_RICH_VALUE_PART, buildRdRichValue(session).getBytes(StandardCharsets.UTF_8));
writeEntry(zout, RD_RICH_VALUE_STRUCTURE_PART, buildRdRichValueStructure().getBytes(StandardCharsets.UTF_8));
writeEntry(zout, RD_RICH_VALUE_TYPES_PART, buildRdRichValueTypes().getBytes(StandardCharsets.UTF_8));
writeEntry(zout, RICH_VALUE_REL_PART, buildRichValueRel(session).getBytes(StandardCharsets.UTF_8));
writeEntry(zout, METADATA_PART, buildMetadata(session).getBytes(StandardCharsets.UTF_8));
int idx = 1;
for (RegisteredCellImage image : session.images) {
if (image.bytes != null) {
writeEntry(zout, mediaPart(idx), image.bytes);
} else {
writeEntry(zout, mediaPart(idx), image.path);
}
idx++;
}
}
try {
Files.move(tmp, xlsxPath, StandardCopyOption.REPLACE_EXISTING);
} catch (IOException moveEx) {
try {
Thread.sleep(200L);
} catch (InterruptedException ignored) {
Thread.currentThread().interrupt();
}
Files.move(tmp, xlsxPath, StandardCopyOption.REPLACE_EXISTING);
log.warn("[excel-cell-image] patch xlsx move retried after error file={} cause={}",
xlsx.getName(), moveEx.toString());
}
success = true;
log.info("[excel-cell-image] patch xlsx finished file={} images={} patchedCells={}",
xlsx.getName(), session.size(), patchedCells);
} catch (IOException ioe) {
log.error("[excel-cell-image] patch xlsx failed file={} images={} err={}",
xlsx.getName(), session.size(), ioe.toString(), ioe);
throw ioe;
} finally {
if (!success) {
try {
Files.deleteIfExists(tmp);
} catch (IOException ignored) {
// 临时文件清理失败不影响主流程
}
}
}
}
private static Set<String> replacementEntryNames(Session session) {
Set<String> names = new HashSet<>();
names.add(RICH_VALUE_RELS_PART);
names.add(RD_RICH_VALUE_PART);
names.add(RD_RICH_VALUE_STRUCTURE_PART);
names.add(RD_RICH_VALUE_TYPES_PART);
names.add(RICH_VALUE_REL_PART);
names.add(METADATA_PART);
for (int i = 1; i <= session.images.size(); i++) {
names.add(mediaPart(i));
}
return names;
}
private static PatchSheetResult patchSheet(byte[] original, Session session) {
String content = new String(original, StandardCharsets.UTF_8);
Map<String, Integer> metadataIndexByCell = new HashMap<>(session.images.size());
for (int idx = 0; idx < session.images.size(); idx++) {
metadataIndexByCell.put(session.images.get(idx).cellRef, idx + 1);
}
Set<String> missingCells = new HashSet<>(metadataIndexByCell.keySet());
Matcher matcher = SHEET_CELL_PATTERN.matcher(content);
StringBuilder patched = new StringBuilder(content.length());
int patchedCount = 0;
while (matcher.find()) {
String cellRef = matcher.group(1);
Integer metadataIndex = metadataIndexByCell.get(cellRef);
if (metadataIndex == null) {
matcher.appendReplacement(patched, Matcher.quoteReplacement(matcher.group()));
continue;
}
// [MS-XLSX] §2.2.10: cell @vm is a 1-based valueMetadata index.
String replacement = "<c r=\"" + cellRef + "\" t=\"e\" vm=\"" + metadataIndex
+ "\"><v>#VALUE!</v></c>";
matcher.appendReplacement(patched, Matcher.quoteReplacement(replacement));
missingCells.remove(cellRef);
patchedCount++;
}
matcher.appendTail(patched);
for (String cellRef : missingCells) {
log.warn("[excel-cell-image] cell {} not found in sheet xml, skip image", cellRef);
}
return new PatchSheetResult(patched.toString().getBytes(StandardCharsets.UTF_8), patchedCount);
}
private static byte[] patchContentTypes(byte[] original) {
String content = new String(original, StandardCharsets.UTF_8);
StringBuilder injection = new StringBuilder();
if (!content.contains("Extension=\"jpeg\"")) {
injection.append("<Default Extension=\"jpeg\" ContentType=\"image/jpeg\"/>");
}
appendOverrideIfMissing(content, injection, "/xl/metadata.xml",
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheetMetadata+xml");
appendOverrideIfMissing(content, injection, "/xl/richData/richValueRel.xml",
"application/vnd.ms-excel.richvaluerel+xml");
appendOverrideIfMissing(content, injection, "/xl/richData/rdrichvalue.xml",
"application/vnd.ms-excel.rdrichvalue+xml");
appendOverrideIfMissing(content, injection, "/xl/richData/rdrichvaluestructure.xml",
"application/vnd.ms-excel.rdrichvaluestructure+xml");
appendOverrideIfMissing(content, injection, "/xl/richData/rdRichValueTypes.xml",
"application/vnd.ms-excel.rdrichvaluetypes+xml");
if (injection.isEmpty()) {
return original;
}
int closeIdx = content.lastIndexOf("</Types>");
if (closeIdx < 0) {
log.warn("[excel-cell-image] [Content_Types].xml missing </Types>, skip patch");
return original;
}
return (content.substring(0, closeIdx) + injection + content.substring(closeIdx))
.getBytes(StandardCharsets.UTF_8);
}
private static void appendOverrideIfMissing(String content, StringBuilder injection, String partName, String contentType) {
if (!content.contains("PartName=\"" + partName + "\"")) {
injection.append("<Override PartName=\"").append(partName)
.append("\" ContentType=\"").append(contentType).append("\"/>");
}
}
private static byte[] patchWorkbookRels(byte[] original) {
String content = new String(original, StandardCharsets.UTF_8);
int maxId = findMaxRId(content);
StringBuilder injection = new StringBuilder();
maxId = appendRelationshipIfMissing(content, injection, maxId, REL_TYPE_RICH_VALUE_STRUCTURE,
"richData/rdrichvaluestructure.xml");
maxId = appendRelationshipIfMissing(content, injection, maxId, REL_TYPE_RICH_VALUE,
"richData/rdrichvalue.xml");
maxId = appendRelationshipIfMissing(content, injection, maxId, REL_TYPE_RICH_VALUE_REL,
"richData/richValueRel.xml");
maxId = appendRelationshipIfMissing(content, injection, maxId, REL_TYPE_SHEET_METADATA,
"metadata.xml");
appendRelationshipIfMissing(content, injection, maxId, REL_TYPE_RICH_VALUE_TYPES,
"richData/rdRichValueTypes.xml");
if (injection.isEmpty()) {
return original;
}
int closeIdx = content.lastIndexOf("</Relationships>");
if (closeIdx < 0) {
log.warn("[excel-cell-image] xl/_rels/workbook.xml.rels missing </Relationships>, skip patch");
return original;
}
return (content.substring(0, closeIdx) + injection + content.substring(closeIdx))
.getBytes(StandardCharsets.UTF_8);
}
private static int appendRelationshipIfMissing(String content,
StringBuilder injection,
int maxId,
String type,
String target) {
if (content.contains("Target=\"" + target + "\"")) {
return maxId;
}
int next = maxId + 1;
injection.append("<Relationship Id=\"rId").append(next)
.append("\" Type=\"").append(type)
.append("\" Target=\"").append(target).append("\"/>");
return next;
}
private static String buildRichValueRels(Session session) {
StringBuilder sb = new StringBuilder();
sb.append("<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>");
sb.append("<Relationships xmlns=\"http://schemas.openxmlformats.org/package/2006/relationships\">");
for (int i = 1; i <= session.images.size(); i++) {
sb.append("<Relationship Id=\"rId").append(i)
.append("\" Type=\"").append(REL_TYPE_IMAGE)
.append("\" Target=\"../media/excelcellimage").append(i).append(".jpeg\"/>");
}
sb.append("</Relationships>");
return sb.toString();
}
private static String buildRdRichValue(Session session) {
StringBuilder sb = new StringBuilder();
sb.append("<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>");
sb.append("<rvData xmlns=\"http://schemas.microsoft.com/office/spreadsheetml/2017/richdata\" count=\"")
.append(session.images.size()).append("\">");
for (int i = 0; i < session.images.size(); i++) {
sb.append("<rv s=\"0\"><v>").append(i).append("</v><v>5</v></rv>");
}
sb.append("</rvData>");
return sb.toString();
}
private static String buildRdRichValueStructure() {
return "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>"
+ "<rvStructures xmlns=\"http://schemas.microsoft.com/office/spreadsheetml/2017/richdata\" count=\"1\">"
+ "<s t=\"_localImage\"><k n=\"_rvRel:LocalImageIdentifier\" t=\"i\"/><k n=\"CalcOrigin\" t=\"i\"/></s>"
+ "</rvStructures>";
}
private static String buildRdRichValueTypes() {
return "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>"
+ "<rvTypesInfo xmlns=\"http://schemas.microsoft.com/office/spreadsheetml/2017/richdata2\""
+ " xmlns:mc=\"http://schemas.openxmlformats.org/markup-compatibility/2006\" mc:Ignorable=\"x\""
+ " xmlns:x=\"http://schemas.openxmlformats.org/spreadsheetml/2006/main\">"
+ "<global><keyFlags>"
+ "<key name=\"_Self\"><flag name=\"ExcludeFromFile\" value=\"1\"/><flag name=\"ExcludeFromCalcComparison\" value=\"1\"/></key>"
+ "<key name=\"_DisplayString\"><flag name=\"ExcludeFromCalcComparison\" value=\"1\"/></key>"
+ "<key name=\"_Flags\"><flag name=\"ExcludeFromCalcComparison\" value=\"1\"/></key>"
+ "<key name=\"_Format\"><flag name=\"ExcludeFromCalcComparison\" value=\"1\"/></key>"
+ "<key name=\"_SubLabel\"><flag name=\"ExcludeFromCalcComparison\" value=\"1\"/></key>"
+ "<key name=\"_Attribution\"><flag name=\"ExcludeFromCalcComparison\" value=\"1\"/></key>"
+ "<key name=\"_Icon\"><flag name=\"ExcludeFromCalcComparison\" value=\"1\"/></key>"
+ "<key name=\"_Display\"><flag name=\"ExcludeFromCalcComparison\" value=\"1\"/></key>"
+ "<key name=\"_CanonicalPropertyNames\"><flag name=\"ExcludeFromCalcComparison\" value=\"1\"/></key>"
+ "<key name=\"_ClassificationId\"><flag name=\"ExcludeFromCalcComparison\" value=\"1\"/></key>"
+ "</keyFlags></global></rvTypesInfo>";
}
private static String buildRichValueRel(Session session) {
StringBuilder sb = new StringBuilder();
sb.append("<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>");
sb.append("<richValueRels xmlns=\"http://schemas.microsoft.com/office/spreadsheetml/2022/richvaluerel\"")
.append(" xmlns:r=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships\">");
for (int i = 1; i <= session.images.size(); i++) {
sb.append("<rel r:id=\"rId").append(i).append("\"/>");
}
sb.append("</richValueRels>");
return sb.toString();
}
private static String buildMetadata(Session session) {
StringBuilder sb = new StringBuilder();
int count = session.images.size();
sb.append("<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>");
sb.append("<metadata xmlns=\"http://schemas.openxmlformats.org/spreadsheetml/2006/main\"")
.append(" xmlns:xlrd=\"http://schemas.microsoft.com/office/spreadsheetml/2017/richdata\">")
.append("<metadataTypes count=\"1\">")
.append("<metadataType name=\"XLRICHVALUE\" minSupportedVersion=\"120000\" copy=\"1\" pasteAll=\"1\"")
.append(" pasteValues=\"1\" merge=\"1\" splitFirst=\"1\" rowColShift=\"1\" clearFormats=\"1\"")
.append(" clearComments=\"1\" assign=\"1\" coerce=\"1\"/>")
.append("</metadataTypes>")
.append("<futureMetadata name=\"XLRICHVALUE\" count=\"").append(count).append("\">");
for (int i = 0; i < count; i++) {
sb.append("<bk><extLst><ext uri=\"{3e2802c4-a4d2-4d8b-9148-e3be6c30e623}\">")
.append("<xlrd:rvb i=\"").append(i).append("\"/>")
.append("</ext></extLst></bk>");
}
sb.append("</futureMetadata><valueMetadata count=\"").append(count).append("\">");
for (int i = 0; i < count; i++) {
sb.append("<bk><rc t=\"1\" v=\"").append(i).append("\"/></bk>");
}
sb.append("</valueMetadata></metadata>");
return sb.toString();
}
private static int findMaxRId(String content) {
int maxId = 0;
Matcher matcher = Pattern.compile("Id=\"rId(\\d+)\"").matcher(content);
while (matcher.find()) {
try {
maxId = Math.max(maxId, Integer.parseInt(matcher.group(1)));
} catch (NumberFormatException ignored) {
// 非数字 rId 不影响新增关系
}
}
return maxId;
}
private static String mediaPart(int idx) {
return "xl/media/excelcellimage" + idx + ".jpeg";
}
private static byte[] readAll(InputStream in) throws IOException {
ByteArrayOutputStream baos = new ByteArrayOutputStream();
byte[] buf = new byte[8192];
int n;
while ((n = in.read(buf)) > 0) {
baos.write(buf, 0, n);
}
return baos.toByteArray();
}
private static void writeEntry(ZipOutputStream zout, String name, byte[] bytes) throws IOException {
ZipEntry entry = new ZipEntry(name);
zout.putNextEntry(entry);
zout.write(bytes);
zout.closeEntry();
}
private static void writeEntry(ZipOutputStream zout, String name, Path path) throws IOException {
ZipEntry entry = new ZipEntry(name);
zout.putNextEntry(entry);
try (InputStream in = Files.newInputStream(path)) {
in.transferTo(zout);
} finally {
zout.closeEntry();
}
}
private static void writeDirectoryEntry(ZipOutputStream zout, String name) throws IOException {
ZipEntry entry = new ZipEntry(name);
zout.putNextEntry(entry);
zout.closeEntry();
}
public static final class Session {
private final List<RegisteredCellImage> images = new ArrayList<>();
public synchronized void registerImage(int rowIdx, int colIdx, byte[] jpegBytes) {
if (jpegBytes == null || jpegBytes.length == 0) {
return;
}
images.add(new RegisteredCellImage(cellRef(rowIdx, colIdx), jpegBytes, null));
}
public synchronized void registerImage(int rowIdx, int colIdx, Path jpegPath) {
if (jpegPath == null || !Files.isRegularFile(jpegPath)) {
return;
}
images.add(new RegisteredCellImage(cellRef(rowIdx, colIdx), null,
jpegPath.toAbsolutePath().normalize()));
}
public synchronized boolean isEmpty() {
return images.isEmpty();
}
public synchronized int size() {
return images.size();
}
private static String cellRef(int rowIdx, int colIdx) {
return columnName(colIdx) + (rowIdx + 1);
}
private static String columnName(int colIdx) {
int value = colIdx + 1;
StringBuilder sb = new StringBuilder();
while (value > 0) {
int rem = (value - 1) % 26;
sb.append((char) ('A' + rem));
value = (value - 1) / 26;
}
return sb.reverse().toString();
}
}
private record RegisteredCellImage(String cellRef, byte[] bytes, Path path) {
}
private record PatchSheetResult(byte[] bytes, int patchedCount) {
}
}
@@ -1,4 +1,4 @@
package com.nanri.aiimage.common.util;
package com.nanri.aiimage.common.excel;
import com.alibaba.excel.EasyExcel;
import com.alibaba.excel.context.AnalysisContext;
@@ -1,4 +1,4 @@
package com.nanri.aiimage.common.util;
package com.nanri.aiimage.common.excel;
import org.apache.poi.ss.usermodel.CellStyle;
import org.apache.poi.ss.usermodel.Font;
@@ -0,0 +1,479 @@
package com.nanri.aiimage.common.excel;
import lombok.extern.slf4j.Slf4j;
import java.io.BufferedOutputStream;
import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Enumeration;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.UUID;
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;
/**
* WPS DISPIMG "图片嵌入单元格" 协议写入器。
* <p>
* Excel 1997-2007 OOXML 没有 "图片嵌入单元格" 概念,POI 5.2.5 也不支持写入 Excel 365 的 IMAGE() 函数。
* 本类基于 WPS 在 OOXML 上的扩展协议(cellimages.xml),让生成的 xlsx 在 WPS、钉钉表格、
* 飞书表格中表现为 "图片真嵌入到单元格内":解除工作表保护后图片仍跟着单元格走,
* 拷贝粘贴行/排序时图片随单元格移动,无法被鼠标拖出。
* <p>
* 用法:
* <pre>
* WpsCellImageWriter.Session session = WpsCellImageWriter.createSession();
* // 写每个 cell:
* String id = session.registerImage(jpegBytes, width, height);
* cell.setCellFormula(WpsCellImageWriter.dispImgFormula(id));
* // workbook.write(file) 之后调用:
* WpsCellImageWriter.patchXlsxFile(xlsx, session);
* </pre>
* <p>
* 协议参考:WPS Office 表格扩展 cellimages.xml。2026-09-09 修复三处与 WPS 原生产物不一致的协议细节
* (此前 WPS 打开 DISPIMG 显示 #REF,根因见各常量注释):
* 1. [Content_Types].xml 的 Content-Type 应为 vnd.wps-officedocument.cellimage+xml;
* 2. workbook.xml.rels 的关系类型应为 wps.cn/officeDocument/2020/cellImage;
* 3. 公式单元格需为 &lt;f t="shared" ref="X"&gt; + &lt;v&gt;=DISPIMG(...)&lt;/v&gt; 形态,POI 输出的裸 &lt;f&gt; 不满足;
* 另 spPr 补 a:xfrm / a:noFill / a:ln w=9525(原图尺寸按 9525 EMU/px 换算)。
*/
@Slf4j
public final class WpsCellImageWriter {
public static final String CELLIMAGES_PART = "xl/cellimages.xml";
public static final String CELLIMAGES_RELS_PART = "xl/_rels/cellimages.xml.rels";
public static final String CONTENT_TYPES_PART = "[Content_Types].xml";
public static final String WORKBOOK_RELS_PART = "xl/_rels/workbook.xml.rels";
public static final String SHEET1_PART = "xl/worksheets/sheet1.xml";
public static final String CELLIMAGES_CONTENT_TYPE =
"application/vnd.wps-officedocument.cellimage+xml";
public static final String CELLIMAGES_REL_TYPE =
"http://www.wps.cn/officeDocument/2020/cellImage";
public static final String IMAGE_REL_TYPE =
"http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
/** 1 像素 = 9525 EMU(Excel 内部单位),用于 cellimages.xml 中 a:ext 的原图尺寸。 */
static final int EMU_PER_PIXEL = 9525;
/**
* 公式单元格规范化正则:匹配 POI 写出的裸公式格(f 无 t="shared"),
* 替换为 WPS 原生形态(f t="shared" ref= + v=公式字符串)。
* POI 输出公式中的双引号为 XML 实体 &quot;,此处两种形态都兼容。
* 负向前瞻保证已规范化的单元格不被二次改写(重复 patch 幂等)。
*/
private static final Pattern DISPIMG_CELL_PATTERN = Pattern.compile(
"<c r=\"([A-Z]+[1-9][0-9]*)\"([^>]*)>\\s*<f(?![^>]*t=\"shared\")[^>]*>"
+ "_xlfn\\.DISPIMG\\((?:&quot;|\")([^&\"<>]+)(?:&quot;|\"),1\\)</f>(?:<v>[^<]*</v>)?</c>",
Pattern.DOTALL);
private static final Pattern CELL_STYLE_PATTERN = Pattern.compile("s=\"(\\d+)\"");
private WpsCellImageWriter() {
}
public static Session createSession() {
return new Session();
}
/**
* 构造 DISPIMG 公式。
* <p>
* 第二个参数固定 1:图片自动缩放到单元格大小(与 IMAGE_ROW_HEIGHT_POINTS / IMAGE_COL_WIDTH_CHARS 配合,
* 既不会拉伸变形也能填充单元格)。
*/
public static String dispImgFormula(String id) {
if (id == null || id.isBlank()) {
return null;
}
return "_xlfn.DISPIMG(\"" + id + "\",1)";
}
/**
* 在已写出的 xlsx 文件上 patch DISPIMG 协议所需的 4 个 part:
* - 新建 xl/cellimages.xml
* - 新建 xl/_rels/cellimages.xml.rels
* - 新建 xl/media/cellimage{N}.jpeg
* - 修改 [Content_Types].xml(加 Override)
* - 修改 xl/_rels/workbook.xml.rels(加 Relationship)
* - 修改 xl/worksheets/sheet1.xml(把 POI 写出的裸 DISPIMG 公式格规范化为 WPS 原生形态,
* 保证 WPS 识别;POI 的 setCellFormula 输出缺 f t="shared"/ref 与 v=公式字符串,WPS 会判 #REF)
* <p>
* 通过临时文件 + REPLACE_EXISTING move 实现:失败时 xlsx 文件保持原样不被破坏。
* 历史使用 ATOMIC_MOVE+REPLACE_EXISTING,但 Java NIO 规范说 ATOMIC_MOVE 下其它选项被忽略,
* Windows 实现遇到目标已存在会抛 AccessDeniedException / FileAlreadyExistsException,
* 故改为常规 REPLACE_EXISTING(Windows 内部走 MoveFileEx,行为已非常接近原子)。
*/
public static void patchXlsxFile(File xlsx, Session session) throws IOException {
if (xlsx == null || !xlsx.exists() || session == null || session.isEmpty()) {
return;
}
Path xlsxPath = xlsx.toPath().toAbsolutePath();
Path parent = xlsxPath.getParent();
if (parent == null) {
throw new IOException("[wps-dispimg] xlsx has no parent directory: " + xlsxPath);
}
Path tmp = Files.createTempFile(parent, "wps-dispimg-", ".xlsx");
boolean success = false;
int patchedCells = -1;
try {
// 使用 ZipFile(基于中央目录读)替代 ZipInputStream(顺序流读)。
// 原因:POI SXSSFWorkbook 写出的 xlsx,部分 entry 的 LFH(Local File Header)会用 data descriptor
// 把 size 字段置 0,把真实 CRC/size 放到 entry 末尾。ZipInputStream 在 STORED 模式下按 LFH 的 size=0
// 校验,会抛 "ZipException: invalid entry size (expected 0 but got N bytes)"。ZipFile 直接读中央目录
// 拿到真实 size,绕开该问题。
try (ZipFile zfIn = new ZipFile(xlsxPath.toFile());
// 64KB 缓冲:一次导出常有 8k 级图片,未缓冲时每个 entry 的头/数据/中央目录项都是独立
// syscall(实测 10k entry 时 media loop 3.0s + close 4.1s,其中绝大部分是写放大不是压缩)
ZipOutputStream zout = new ZipOutputStream(new BufferedOutputStream(
Files.newOutputStream(tmp), 64 * 1024))) {
Enumeration<? extends ZipEntry> entries = zfIn.entries();
while (entries.hasMoreElements()) {
ZipEntry entry = entries.nextElement();
String name = entry.getName();
if (entry.isDirectory()) {
writeDirectoryEntry(zout, name);
continue;
}
// DISPIMG 专属 part 由尾部统一重建(重复 patch 时原样保留,保证幂等)
if (CELLIMAGES_PART.equals(name) || CELLIMAGES_RELS_PART.equals(name)
|| name.startsWith("xl/media/cellimage")) {
continue;
}
byte[] bytes;
try (InputStream in = zfIn.getInputStream(entry)) {
bytes = readAll(in);
}
if (CONTENT_TYPES_PART.equals(name)) {
bytes = patchContentTypes(bytes);
} else if (WORKBOOK_RELS_PART.equals(name)) {
bytes = patchWorkbookRels(bytes);
} else if (SHEET1_PART.equals(name)) {
PatchSheetResult sheetResult = patchSheet(bytes, session);
bytes = sheetResult.bytes();
patchedCells = sheetResult.patchedCount();
}
writeEntry(zout, name, bytes);
}
writeEntry(zout, CELLIMAGES_PART,
buildCellImagesXml(session).getBytes(StandardCharsets.UTF_8));
writeEntry(zout, CELLIMAGES_RELS_PART,
buildCellImagesRelsXml(session).getBytes(StandardCharsets.UTF_8));
int idx = 1;
for (RegisteredImage img : session.images) {
writeEntry(zout, "xl/media/cellimage" + idx + ".jpeg", img.bytes());
idx++;
}
}
try {
Files.move(tmp, xlsxPath, StandardCopyOption.REPLACE_EXISTING);
} catch (IOException moveEx) {
// Windows 上偶发 AccessDenied(如反病毒/索引服务短暂占用源文件),retry 一次。
try {
Thread.sleep(200L);
} catch (InterruptedException ignored) {
Thread.currentThread().interrupt();
}
Files.move(tmp, xlsxPath, StandardCopyOption.REPLACE_EXISTING);
log.warn("[wps-dispimg] patch xlsx move retried after error file={} cause={}",
xlsx.getName(), moveEx.toString());
}
success = true;
log.info("[wps-dispimg] patch xlsx finished file={} images={} patchedCells={}",
xlsx.getName(), session.size(), patchedCells);
} catch (IOException ioe) {
log.error("[wps-dispimg] patch xlsx failed file={} images={} err={}",
xlsx.getName(), session.size(), ioe.toString(), ioe);
throw ioe;
} finally {
if (!success) {
try {
Files.deleteIfExists(tmp);
} catch (IOException ignored) {
// 临时文件清理失败不影响主流程
}
}
}
}
private static byte[] readAll(InputStream in) throws IOException {
ByteArrayOutputStream baos = new ByteArrayOutputStream();
byte[] buf = new byte[8192];
int n;
while ((n = in.read(buf)) > 0) {
baos.write(buf, 0, n);
}
return baos.toByteArray();
}
private static void writeEntry(ZipOutputStream zout, String name, byte[] bytes) throws IOException {
ZipEntry entry = new ZipEntry(name);
zout.putNextEntry(entry);
zout.write(bytes);
zout.closeEntry();
}
private static void writeDirectoryEntry(ZipOutputStream zout, String name) throws IOException {
ZipEntry entry = new ZipEntry(name);
zout.putNextEntry(entry);
zout.closeEntry();
}
/**
* 规范化 sheet 中 POI 写出的 DISPIMG 公式单元格:
* &lt;c r="M2" s="9" t="str"&gt;&lt;f&gt;_xlfn.DISPIMG("ID_x",1)&lt;/f&gt;…&lt;/c&gt;
* → &lt;c r="M2" s="9" t="str"&gt;&lt;f t="shared" ref="M2"&gt;_xlfn.DISPIMG("ID_x",1)&lt;/f&gt;&lt;v&gt;=DISPIMG("ID_x",1)&lt;/v&gt;&lt;/c&gt;
* 保留原单元格样式 s。
*/
private static PatchSheetResult patchSheet(byte[] original, Session session) {
String content = new String(original, StandardCharsets.UTF_8);
Matcher matcher = DISPIMG_CELL_PATTERN.matcher(content);
StringBuilder patched = new StringBuilder(content.length());
int patchedCount = 0;
while (matcher.find()) {
String cellRef = matcher.group(1);
String imageId = matcher.group(3);
String style = "";
Matcher styleMatcher = CELL_STYLE_PATTERN.matcher(matcher.group(2));
if (styleMatcher.find()) {
style = " s=\"" + styleMatcher.group(1) + "\"";
}
String replacement = "<c r=\"" + cellRef + "\"" + style + " t=\"str\">"
+ "<f t=\"shared\" ref=\"" + cellRef + "\">_xlfn.DISPIMG(\"" + imageId + "\",1)</f>"
+ "<v>=DISPIMG(\"" + imageId + "\",1)</v></c>";
matcher.appendReplacement(patched, Matcher.quoteReplacement(replacement));
patchedCount++;
}
matcher.appendTail(patched);
if (patchedCount != session.size()) {
// 重复 patch(公式格已规范化,patchedCount=0)属预期,降级为 debug
if (patchedCount == 0) {
log.debug("[wps-dispimg] dispimg cells already normalized file={} images={}",
session.size());
} else {
log.warn("[wps-dispimg] patched dispimg cells mismatch file={} images={} patchedCells={}",
session.size(), patchedCount);
}
}
return new PatchSheetResult(patched.toString().getBytes(StandardCharsets.UTF_8), patchedCount);
}
static byte[] patchContentTypes(byte[] original) {
String content = new String(original, StandardCharsets.UTF_8);
// 已经存在则跳过(幂等:避免重复 patch)
if (content.contains("PartName=\"/" + CELLIMAGES_PART + "\"")) {
return original;
}
String injection = "<Override PartName=\"/" + CELLIMAGES_PART
+ "\" ContentType=\"" + CELLIMAGES_CONTENT_TYPE + "\"/>";
int closeIdx = content.lastIndexOf("</Types>");
if (closeIdx < 0) {
log.warn("[wps-dispimg] [Content_Types].xml missing </Types>, skip patch");
return original;
}
String patched = content.substring(0, closeIdx) + injection + content.substring(closeIdx);
return patched.getBytes(StandardCharsets.UTF_8);
}
static byte[] patchWorkbookRels(byte[] original) {
String content = new String(original, StandardCharsets.UTF_8);
if (content.contains("Target=\"cellimages.xml\"")) {
return original;
}
// 扫描已有最大 rId
int maxId = 0;
Matcher m = Pattern.compile("Id=\"rId(\\d+)\"").matcher(content);
while (m.find()) {
try {
maxId = Math.max(maxId, Integer.parseInt(m.group(1)));
} catch (NumberFormatException ignored) {
// 非数字 rId 无影响
}
}
String newId = "rId" + (maxId + 1);
String injection = "<Relationship Id=\"" + newId
+ "\" Type=\"" + CELLIMAGES_REL_TYPE
+ "\" Target=\"cellimages.xml\"/>";
int closeIdx = content.lastIndexOf("</Relationships>");
if (closeIdx < 0) {
log.warn("[wps-dispimg] xl/_rels/workbook.xml.rels missing </Relationships>, skip patch");
return original;
}
String patched = content.substring(0, closeIdx) + injection + content.substring(closeIdx);
return patched.getBytes(StandardCharsets.UTF_8);
}
static String buildCellImagesXml(Session session) {
StringBuilder sb = new StringBuilder();
sb.append("<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>");
sb.append("<etc:cellImages")
.append(" xmlns:etc=\"http://www.wps.cn/officeDocument/2017/etCustomData\"")
.append(" xmlns:xdr=\"http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing\"")
.append(" xmlns:a=\"http://schemas.openxmlformats.org/drawingml/2006/main\"")
.append(" xmlns:r=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships\">");
int idx = 1;
for (RegisteredImage img : session.images) {
// cNvPr id 从 2 起步、descr 为空字符串、spPr 含 a:xfrm(原图尺寸 EMU)/a:noFill/a:ln w=9525——
// 与 WPS 实测样本完全对齐(2026-09-09 补齐后 WPS 12.1 实测显示正常,此前缺 xfrm 等导致 #REF)。
int cNvPrId = idx + 1;
sb.append("<etc:cellImage>")
.append("<xdr:pic>")
.append("<xdr:nvPicPr>")
.append("<xdr:cNvPr id=\"").append(cNvPrId)
.append("\" name=\"").append(img.id)
.append("\" descr=\"\"/>")
.append("<xdr:cNvPicPr><a:picLocks noChangeAspect=\"1\"/></xdr:cNvPicPr>")
.append("</xdr:nvPicPr>")
.append("<xdr:blipFill>")
.append("<a:blip xmlns:r=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships\"")
.append(" r:embed=\"rId").append(idx).append("\"/>")
.append("<a:stretch><a:fillRect/></a:stretch>")
.append("</xdr:blipFill>")
.append("<xdr:spPr>")
.append("<a:xfrm>")
.append("<a:off x=\"0\" y=\"0\"/>")
.append("<a:ext cx=\"").append(Math.max(1L, (long) img.width * EMU_PER_PIXEL))
.append("\" cy=\"").append(Math.max(1L, (long) img.height * EMU_PER_PIXEL))
.append("\"/>")
.append("</a:xfrm>")
.append("<a:prstGeom prst=\"rect\"><a:avLst/></a:prstGeom>")
.append("<a:noFill/>")
.append("<a:ln w=\"9525\"><a:noFill/></a:ln>")
.append("</xdr:spPr>")
.append("</xdr:pic>")
.append("</etc:cellImage>");
idx++;
}
sb.append("</etc:cellImages>");
return sb.toString();
}
static String buildCellImagesRelsXml(Session session) {
StringBuilder sb = new StringBuilder();
sb.append("<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>");
sb.append("<Relationships xmlns=\"http://schemas.openxmlformats.org/package/2006/relationships\">");
int idx = 1;
for (RegisteredImage ignored : session.images) {
sb.append("<Relationship Id=\"rId").append(idx)
.append("\" Type=\"").append(IMAGE_REL_TYPE)
.append("\" Target=\"media/cellimage").append(idx)
.append(".jpeg\"/>");
idx++;
}
sb.append("</Relationships>");
return sb.toString();
}
/**
* 同一 task 内的图片注册会话。线程安全(synchronized)。
*/
public static final class Session {
final List<RegisteredImage> images = new ArrayList<>();
// 字节级去重:相同图片只写一次 cellimage{N}.jpeg,节省 xlsx 体积。
private final Map<String, String> bytesHashToId = new LinkedHashMap<>();
// 磁盘路径去重:同一任务内相同源文件(预取 spool 同一份)只写一次 media,避免内存/体积膨胀。
private final Map<String, String> pathHashToId = new LinkedHashMap<>();
public synchronized String registerImage(byte[] jpegBytes, int width, int height) {
if (jpegBytes == null || jpegBytes.length == 0) {
return null;
}
String hash = md5Hex(jpegBytes);
String existingId = bytesHashToId.get(hash);
if (existingId != null) {
return existingId;
}
String id = newImageId();
images.add(new RegisteredImage(id, jpegBytes, width, height));
bytesHashToId.put(hash, id);
return id;
}
/** 按磁盘路径注册(预取 spool 已落盘,避免整份字节驻留内存);按绝对路径去重,重复路径复用同一 media。 */
public synchronized String registerImageByPath(Path path, int width, int height) {
if (path == null) {
return null;
}
String normalized = path.toAbsolutePath().normalize().toString();
String existingId = pathHashToId.get(normalized);
if (existingId != null) {
return existingId;
}
String id = newImageId();
images.add(new RegisteredImage(id, path, width, height));
pathHashToId.put(normalized, id);
return id;
}
public synchronized boolean isEmpty() {
return images.isEmpty();
}
public synchronized int size() {
return images.size();
}
private static String newImageId() {
// ID_xxx 格式(32 hex chars = MD5 风格)模拟 WPS 默认风格,避免特殊字符让公式解析出错。
return "ID_" + UUID.randomUUID().toString().replace("-", "").toUpperCase();
}
private static String md5Hex(byte[] bytes) {
try {
MessageDigest md = MessageDigest.getInstance("MD5");
byte[] digest = md.digest(bytes);
StringBuilder sb = new StringBuilder(digest.length * 2);
for (byte b : digest) {
sb.append(String.format("%02x", b));
}
return sb.toString();
} catch (NoSuchAlgorithmException ex) {
// MD5 缺失只在极端 JVM 下出现,退化用 hashCode 即可保证 session 内"内存唯一性"
return "len" + bytes.length + ":h" + Arrays.hashCode(bytes);
}
}
}
static final class RegisteredImage {
final String id;
final byte[] bytes;
final Path sourcePath;
final int width;
final int height;
RegisteredImage(String id, byte[] bytes, int width, int height) {
this.id = id;
this.bytes = bytes;
this.sourcePath = null;
this.width = width;
this.height = height;
}
RegisteredImage(String id, Path sourcePath, int width, int height) {
this.id = id;
this.bytes = null;
this.sourcePath = sourcePath;
this.width = width;
this.height = height;
}
byte[] bytes() throws IOException {
return sourcePath != null ? Files.readAllBytes(sourcePath) : bytes;
}
}
private record PatchSheetResult(byte[] bytes, int patchedCount) {
}
}
@@ -3,7 +3,7 @@ package com.nanri.aiimage.common.exception;
import com.nanri.aiimage.common.api.ApiResponse;
import com.nanri.aiimage.common.security.DeviceSessionPolicy;
import com.nanri.aiimage.common.service.TaskOwnerForwardService;
import com.nanri.aiimage.common.util.UserMessages;
import com.nanri.aiimage.common.text.UserMessages;
import com.nanri.aiimage.config.TaskOperationLockConfig;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.validation.ConstraintViolationException;
@@ -1,6 +1,6 @@
package com.nanri.aiimage.common.service;
import com.nanri.aiimage.common.util.UserMessages;
import com.nanri.aiimage.common.text.UserMessages;
import com.nanri.aiimage.common.exception.BusinessException;
import com.nanri.aiimage.common.exception.TaskOwnerMismatchException;
import com.nanri.aiimage.config.InstanceRoutingProperties;
@@ -1,4 +1,4 @@
package com.nanri.aiimage.common.util;
package com.nanri.aiimage.common.support;
import java.util.Collections;
import java.util.LinkedHashMap;
@@ -1,4 +1,4 @@
package com.nanri.aiimage.common.util;
package com.nanri.aiimage.common.support;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.http.HttpHeaders;
@@ -1,4 +1,4 @@
package com.nanri.aiimage.common.util;
package com.nanri.aiimage.common.support;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.LinkedBlockingQueue;
@@ -1,4 +1,4 @@
package com.nanri.aiimage.common.util;
package com.nanri.aiimage.common.task;
import java.util.ArrayList;
import java.util.List;
@@ -1,4 +1,4 @@
package com.nanri.aiimage.common.util;
package com.nanri.aiimage.common.task;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
@@ -1,4 +1,4 @@
package com.nanri.aiimage.common.util;
package com.nanri.aiimage.common.task;
import io.micrometer.core.instrument.Gauge;
import io.micrometer.core.instrument.MeterRegistry;
@@ -1,4 +1,4 @@
package com.nanri.aiimage.common.util;
package com.nanri.aiimage.common.task;
import lombok.extern.slf4j.Slf4j;
@@ -1,4 +1,4 @@
package com.nanri.aiimage.common.util;
package com.nanri.aiimage.common.task;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
@@ -1,4 +1,4 @@
package com.nanri.aiimage.common.util;
package com.nanri.aiimage.common.text;
import java.util.regex.Pattern;
@@ -1,4 +1,4 @@
package com.nanri.aiimage.common.util;
package com.nanri.aiimage.common.text;
import java.net.URI;
@@ -1,4 +1,4 @@
package com.nanri.aiimage.common.util;
package com.nanri.aiimage.common.text;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;