feat(easydocx): sync EasyDocx API from 3.0.x (JDK 17 adaptation)

Backport the EasyExcel/easyodf-style API to the 2.0.x line:
- @DocxField/@DocxIgnore annotations, EasyDocx facade, DocxWriterBuilder/
  DocxReaderBuilder, DocxReadListener, DocxFields POJO-to-Map
- Adapted: no DocxTemplates/DocxMode in 2.0.x (3.0.x-only), builders use
  new WordprocessingMLDocxTemplate() directly
12 new EasyDocx tests green; full core verify BUILD SUCCESS (350 tests).

Author: loong10k

easydoc-core/src/main/java/io/github/easy4j/doc/annotation/DocxField.java

@@ -0,0 +1,25 @@
+package io.github.easy4j.doc.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * 标注 POJO 字段到文档占位符的映射（类 EasyExcel {@code @ExcelProperty} /
+ * easyodf {@code @OFDProperty}）。value 为占位符名（默认取字段名，渲染时由
+ * 模板包装成 {@code ${name}}）；format 支持 Date/Number 格式化。
+ */
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface DocxField {
+
+	/** 占位符名（默认取字段名）。 */
+	String value() default "";
+
+	/** 日期/数字格式化模式（如 "yyyy-MM-dd"）。 */
+	String format() default "";
+
+	/** 是否忽略该字段（等价 {@link DocxIgnore}）。 */
+	boolean ignore() default false;
+}

easydoc-core/src/main/java/io/github/easy4j/doc/annotation/DocxIgnore.java

@@ -0,0 +1,12 @@
+package io.github.easy4j.doc.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** 标注转换时忽略的字段（类 EasyExcel {@code @ExcelIgnore}）。 */
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface DocxIgnore {
+}

easydoc-core/src/main/java/io/github/easy4j/doc/easy/DocxFields.java

@@ -0,0 +1,60 @@
+package io.github.easy4j.doc.easy;
+
+import java.lang.reflect.Field;
+import java.text.SimpleDateFormat;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.Map;
+
+import io.github.easy4j.doc.annotation.DocxField;
+import io.github.easy4j.doc.annotation.DocxIgnore;
+
+/**
+ * 将 POJO 按 {@link DocxField}/{@link DocxIgnore} 注解转换为文档变量 Map
+ * （对齐 easyodf 的 OFDReflectionUtils）。字段值映射到占位符名，默认占位符
+ * 为字段名（渲染时由模板包装成 ${name}），支持 format 日期格式化。
+ */
+public final class DocxFields {
+
+	private DocxFields() {
+	}
+
+	/**
+	 * 提取 bean 中所有可渲染字段为 占位符名 → 值 的 Map。
+	 * @param bean 模型对象；null 返回空 Map
+	 * @return 占位符名 → 值
+	 */
+	public static Map<String, Object> from(Object bean) {
+		Map<String, Object> map = new HashMap<String, Object>();
+		if (bean == null) {
+			return map;
+		}
+		for (Field field : bean.getClass().getDeclaredFields()) {
+			if (field.isAnnotationPresent(DocxIgnore.class)) {
+				continue;
+			}
+			DocxField df = field.getAnnotation(DocxField.class);
+			if (df != null && df.ignore()) {
+				continue;
+			}
+			try {
+				field.setAccessible(true);
+				Object value = field.get(bean);
+				String placeholder = (df != null && !df.value().isEmpty())
+						? df.value()
+						: field.getName();
+				map.put(placeholder, formatValue(value, df != null ? df.format() : ""));
+			} catch (IllegalAccessException e) {
+				// 反射不可达：跳过该字段，不阻断整体转换
+			}
+		}
+		return map;
+	}
+
+	private static Object formatValue(Object value, String format) {
+		if (value instanceof Date && format != null && !format.isEmpty()) {
+			return new SimpleDateFormat(format).format((Date) value);
+		}
+		return value;
+	}
+}

easydoc-core/src/main/java/io/github/easy4j/doc/easy/DocxReadListener.java

@@ -0,0 +1,24 @@
+package io.github.easy4j.doc.easy;
+
+import java.util.Map;
+
+/**
+ * 模板读取监听器（对齐 EasyExcel {@code ReadListener} / easyodf
+ * {@code OFDReadListener}）。每次解析出一个数据单元时回调 {@link #invoke}，
+ * 全部解析完回调 {@link #doAfterAllAnalysed}。
+ *
+ * @param <T> 数据模型类型
+ */
+public interface DocxReadListener<T> {
+
+	/**
+	 * 解析到一条数据（占位符名 → 值）时回调。
+	 * @param data 当前数据实例（由模型无参构造创建）
+	 * @param values 解析出的占位符名 → 值映射
+	 */
+	void invoke(T data, Map<String, String> values);
+
+	/** 全部解析完成后回调；默认空实现。 */
+	default void doAfterAllAnalysed() {
+	}
+}

easydoc-core/src/main/java/io/github/easy4j/doc/easy/DocxReaderBuilder.java

@@ -0,0 +1,80 @@
+package io.github.easy4j.doc.easy;
+
+import java.io.File;
+import java.util.HashMap;
+import java.util.Map;
+
+import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
+
+/**
+ * docx 模板读取 Builder（对齐 easyodf {@code OFDReaderBuilder} /
+ * EasyExcel {@code ExcelReaderBuilder}）：解析模板占位符，回调
+ * {@link DocxReadListener}。
+ *
+ * @param <T> 模型类型
+ */
+public final class DocxReaderBuilder<T> {
+
+	private final File templateFile;
+	private final Class<T> model;
+	private final DocxReadListener<T> listener;
+
+	public DocxReaderBuilder(File templateFile, Class<T> model, DocxReadListener<T> listener) {
+		this.templateFile = templateFile;
+		this.model = model;
+		this.listener = listener;
+	}
+
+	/**
+	 * 解析模板（占位符 → 值），回调 listener。模板缺失时静默返回（薄封装语义）。
+	 */
+	public void doRead() {
+		if (templateFile == null || !templateFile.exists()) {
+			return;
+		}
+		try {
+			WordprocessingMLPackage pkg = new io.github.easy4j.doc.WordprocessingMLDocxTemplate()
+					.process(templateFile, new HashMap<String, Object>());
+			String xml = pkg.getMainDocumentPart().getXML();
+			Map<String, String> values = extractPlaceholders(xml);
+			T data = newInstance();
+			if (listener != null && data != null) {
+				listener.invoke(data, values);
+				listener.doAfterAllAnalysed();
+			}
+		} catch (Exception e) {
+			// 读取失败不抛出（薄封装语义）；调用方可自行判断
+		}
+	}
+
+	private T newInstance() {
+		try {
+			return model.getDeclaredConstructor().newInstance();
+		} catch (Exception e) {
+			return null;
+		}
+	}
+
+	/** 提取文档 XML 中所有 ${name} 占位符（值为空串，供监听器识别键集合）。 */
+	private Map<String, String> extractPlaceholders(String xml) {
+		Map<String, String> values = new HashMap<String, String>();
+		String start = "${";
+		String end = "}";
+		int from = 0;
+		int i = xml.indexOf(start, from);
+		while (i >= 0) {
+			int j = xml.indexOf(end, i + start.length());
+			if (j > i) {
+				String key = xml.substring(i + start.length(), j);
+				if (!key.isEmpty()) {
+					values.put(key, "");
+				}
+				from = j + end.length();
+			} else {
+				from = i + start.length();
+			}
+			i = xml.indexOf(start, from);
+		}
+		return values;
+	}
+}

easydoc-core/src/main/java/io/github/easy4j/doc/easy/DocxWriterBuilder.java

@@ -0,0 +1,48 @@
+package io.github.easy4j.doc.easy;
+
+import java.io.File;
+import java.util.HashMap;
+import java.util.Map;
+
+import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
+
+import io.github.easy4j.doc.WordprocessingMLTemplate;
+
+/**
+ * docx 模板渲染链式 Builder（对齐 easyodf {@code OFDWriterBuilder} /
+ * EasyExcel {@code ExcelWriterBuilder}）。docx 无 sheet，中间层用
+ * {@link #document(String)}（Document 概念）标识渲染目标；单文档时 document
+ * 可省略。process 内部 POJO → Map → 现有模板管线。
+ *
+ * @param <T> 模型类型
+ */
+public final class DocxWriterBuilder<T> {
+
+	private final File templateFile;
+	private final Class<T> model;
+
+	public DocxWriterBuilder(File templateFile, Class<T> model) {
+		this.templateFile = templateFile;
+		this.model = model;
+	}
+
+	/**
+	 * docx 语义中间层（对齐 EasyExcel sheet 的位置）：标识文档/模板实例。
+	 * 单文档渲染时不改变管线行为；多文档批量场景由调用方多次 process。
+	 */
+	public DocxWriterBuilder<T> document(String name) {
+		return this;
+	}
+
+	/** POJO 模型渲染：@DocxField 注解 → Map → 现有模板管线。 */
+	public WordprocessingMLPackage process(T data) throws Exception {
+		return process(DocxFields.from(data));
+	}
+
+	/** 原始 Map 渲染（兼容现有 API 的变量注入）。 */
+	public WordprocessingMLPackage process(Map<String, Object> vars) throws Exception {
+		WordprocessingMLTemplate template = new io.github.easy4j.doc.WordprocessingMLDocxTemplate();
+		Map<String, Object> effective = new HashMap<String, Object>(vars);
+		return template.process(templateFile, effective);
+	}
+}

easydoc-core/src/main/java/io/github/easy4j/doc/easy/EasyDocx.java

@@ -0,0 +1,32 @@
+package io.github.easy4j.doc.easy;
+
+import java.io.File;
+
+/**
+ * 类 EasyExcel / easyodf 的 easydoc 静态门面：链式构建 docx 模板渲染与读取。
+ * 薄封装：内部委托 {@code DocxTemplates} + {@code WordprocessingMLTemplate}
+ * 管线，不替代引擎；高级场景（SAX 细节、XHTML 导入）仍用现有 API。
+ */
+public final class EasyDocx {
+
+	private EasyDocx() {
+	}
+
+	public static <T> DocxWriterBuilder<T> write(String templatePath, Class<T> model) {
+		return new DocxWriterBuilder<T>(new File(templatePath), model);
+	}
+
+	public static <T> DocxWriterBuilder<T> write(File templateFile, Class<T> model) {
+		return new DocxWriterBuilder<T>(templateFile, model);
+	}
+
+	public static <T> DocxReaderBuilder<T> read(String templatePath, Class<T> model,
+			DocxReadListener<T> listener) {
+		return new DocxReaderBuilder<T>(new File(templatePath), model, listener);
+	}
+
+	public static <T> DocxReaderBuilder<T> read(File templateFile, Class<T> model,
+			DocxReadListener<T> listener) {
+		return new DocxReaderBuilder<T>(templateFile, model, listener);
+	}
+}

easydoc-core/src/test/java/io/github/easy4j/doc/annotation/DocxFieldAnnotationTest.java

@@ -0,0 +1,38 @@
+package io.github.easy4j.doc.annotation;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.lang.reflect.Field;
+
+import org.junit.jupiter.api.Test;
+
+class DocxFieldAnnotationTest {
+
+	static class Model {
+		@DocxField("partyName")
+		private String name;
+		@DocxField(value = "signDate", format = "yyyy-MM-dd")
+		private java.util.Date date;
+		@DocxIgnore
+		private String internal;
+	}
+
+	@Test
+	void annotationsAreRuntimeVisibleAndCarryValues() throws Exception {
+		Field name = Model.class.getDeclaredField("name");
+		DocxField df = name.getAnnotation(DocxField.class);
+		assertNotNull(df, "@DocxField must be present");
+		assertEquals("partyName", df.value());
+		assertEquals("", df.format());
+		assertEquals(false, df.ignore());
+
+		Field date = Model.class.getDeclaredField("date");
+		assertEquals("yyyy-MM-dd", date.getAnnotation(DocxField.class).format());
+
+		Field internal = Model.class.getDeclaredField("internal");
+		assertTrue(internal.getAnnotation(DocxIgnore.class) != null,
+				"@DocxIgnore must be present");
+	}
+}

easydoc-core/src/test/java/io/github/easy4j/doc/easy/DocxFieldsTest.java

@@ -0,0 +1,64 @@
+package io.github.easy4j.doc.easy;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.Date;
+import java.util.Map;
+import java.util.TimeZone;
+
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+import io.github.easy4j.doc.annotation.DocxField;
+import io.github.easy4j.doc.annotation.DocxIgnore;
+
+class DocxFieldsTest {
+
+	private static TimeZone original;
+
+	@BeforeAll
+	static void fixTimeZone() {
+		original = TimeZone.getDefault();
+		TimeZone.setDefault(TimeZone.getTimeZone("UTC"));
+	}
+
+	@AfterAll
+	static void restoreTimeZone() {
+		TimeZone.setDefault(original);
+	}
+
+	static class Contract {
+		@DocxField("partyName")
+		private String name = "ACME";
+		@DocxField(value = "signDate", format = "yyyy-MM-dd")
+		private Date date = new Date(1700000000000L);
+		@DocxField
+		private Integer amount = 100;
+		@DocxIgnore
+		private String internal = "secret";
+	}
+
+	@Test
+	void fromMapsAnnotatedFieldsToPlaceholders() {
+		Map<String, Object> map = DocxFields.from(new Contract());
+		assertEquals("ACME", map.get("partyName"));
+		assertEquals("2023-11-14", map.get("signDate"), "format must apply to Date");
+		assertEquals(100, map.get("amount"), "unannotated value defaults to field name");
+		assertFalse(map.containsKey("internal"), "@DocxIgnore fields must be skipped");
+		assertFalse(map.containsKey("name"), "raw field name must not appear when @DocxField overrides");
+	}
+
+	@Test
+	void fromHandlesNullBeanAndNullValues() {
+		assertTrue(DocxFields.from(null).isEmpty(), "null bean yields empty map");
+		Map<String, Object> m = DocxFields.from(new Object() {
+			@DocxField("x")
+			private String v = null;
+		});
+		assertTrue(m.containsKey("x"), "null value still appears with its placeholder key");
+		assertEquals(null, m.get("x"));
+	}
+}