feat: introduce HeaderMergeStrategy for flexible header merging and fix issue #666

Author: liugddx

fesod/src/main/java/org/apache/fesod/excel/enums/HeaderMergeStrategy.java

@@ -43,7 +43,6 @@ public enum HeaderMergeStrategy {
 
     /**
      * Only vertical merge (same cells in the same column).
-     * Note: This strategy does not check context consistency (unlike AUTO strategy).
      */
     VERTICAL_ONLY,
 
@@ -54,7 +53,6 @@ public enum HeaderMergeStrategy {
 
     /**
      * Auto merge (default behavior for backward compatibility).
-     * Includes context consistency validation to prevent incorrect merges.
      */
     AUTO
 }

fesod/src/main/java/org/apache/fesod/excel/write/property/ExcelWriteHeadProperty.java

@@ -181,7 +181,7 @@ public List<CellRange> headCellRangeList(HeaderMergeStrategy mergeStrategy) {
                             }
                         }
 
-                        // For AUTO strategy, also check context consistency (above cells)
+                        // For AUTO strategy, also check context consistency
                         if (canMerge && mergeStrategy == HeaderMergeStrategy.AUTO) {
                             canMerge = canMergeVertically(headList, j, k, i, lastCol, headName);
                         }

fesod/src/test/java/org/apache/fesod/excel/head/HeaderMergeStrategyTest.java

@@ -46,7 +46,6 @@ public class HeaderMergeStrategyTest {
     private static File fileVerticalOnly;
     private static File fileFullRectangle;
     private static File fileAuto;
-    private static File fileIssue666;
 
     @BeforeAll
     public static void init() {
@@ -55,53 +54,6 @@ public static void init() {
         fileVerticalOnly = TestFileUtil.createNewFile("headerMergeStrategyVerticalOnly.xlsx");
         fileFullRectangle = TestFileUtil.createNewFile("headerMergeStrategyFullRectangle.xlsx");
         fileAuto = TestFileUtil.createNewFile("headerMergeStrategyAuto.xlsx");
-        fileIssue666 = TestFileUtil.createNewFile("headerMergeStrategyIssue666.xlsx");
-    }
-
-    /**
-     * Test issue #666 scenario: dynamic head with same cell name but different context
-     * Expected: C2 and D2 should not be merged
-     */
-    @Test
-    public void testIssue666() {
-        List<List<String>> multiHeader = new ArrayList<>();
-        multiHeader.add(new ArrayList<>(Arrays.asList("head10")));
-        multiHeader.add(new ArrayList<>(Arrays.asList("head20", "head21")));
-        multiHeader.add(new ArrayList<>(Arrays.asList("head30", "head31")));
-        multiHeader.add(new ArrayList<>(Arrays.asList("head40", "head31")));
-        multiHeader.add(new ArrayList<>(Arrays.asList("head40", "head41")));
-
-        // Test with FULL_RECTANGLE strategy - should not merge C2 and D2
-        FastExcel.write(fileIssue666)
-                .head(multiHeader)
-                .headerMergeStrategy(HeaderMergeStrategy.FULL_RECTANGLE)
-                .sheet()
-                .doWrite(createTestData());
-
-        // Verify that C2 and D2 are not merged
-        try (org.apache.poi.ss.usermodel.Workbook workbook =
-                org.apache.poi.ss.usermodel.WorkbookFactory.create(fileIssue666)) {
-            Sheet sheet = workbook.getSheetAt(0);
-            int mergedRegionCount = sheet.getNumMergedRegions();
-
-            // Check all merged regions
-            boolean c2AndD2Merged = false;
-            for (int i = 0; i < mergedRegionCount; i++) {
-                CellRangeAddress region = sheet.getMergedRegion(i);
-                // C2 is row 1, col 2; D2 is row 1, col 3
-                // If they are merged, there should be a region covering both
-                if (region.getFirstRow() == 1 && region.getLastRow() == 1
-                        && region.getFirstColumn() == 2 && region.getLastColumn() == 3) {
-                    c2AndD2Merged = true;
-                    break;
-                }
-            }
-
-            // Assert that C2 and D2 are NOT merged
-            Assertions.assertFalse(c2AndD2Merged, "C2 and D2 should not be merged in issue #666 scenario");
-        } catch (Exception e) {
-            throw new RuntimeException("Failed to verify merged regions", e);
-        }
     }
 
     @Test
@@ -213,7 +165,7 @@ public void testAutoStrategy() {
                 .sheet()
                 .doWrite(createTestData());
 
-        // AUTO strategy should work similar to the old behavior but with context validation
+        // AUTO strategy should work similar to the old behavior
         try (org.apache.poi.ss.usermodel.Workbook workbook =
                 org.apache.poi.ss.usermodel.WorkbookFactory.create(fileAuto)) {
             Sheet sheet = workbook.getSheetAt(0);

website/docs/help/parameter.md

@@ -181,7 +181,7 @@ The `headerMergeStrategy` parameter provides fine-grained control over how heade
 - **HORIZONTAL_ONLY**: Only merges cells horizontally (same row).
 - **VERTICAL_ONLY**: Only merges cells vertically (same column).
 - **FULL_RECTANGLE**: Only merges complete rectangular regions where all cells have the same name.
-- **AUTO**: Automatic merging (default behavior for backward compatibility), with improved context validation to prevent incorrect merges.
+- **AUTO**: Automatic merging (default behavior for backward compatibility).
 
 **Example**:
 ```java

website/docs/write/head.md

@@ -90,7 +90,7 @@ By default, FastExcel automatically merges header cells with the same name. Howe
 - **HORIZONTAL_ONLY**: Only merges cells horizontally (same row).
 - **VERTICAL_ONLY**: Only merges cells vertically (same column).
 - **FULL_RECTANGLE**: Only merges complete rectangular regions where all cells have the same name.
-- **AUTO**: Automatic merging (default), with improved context validation.
+- **AUTO**: Automatic merging (default).
 
 ### Code Example
 
@@ -114,22 +114,6 @@ public void dynamicHeadWriteWithStrategy() {
 
 ### Common Use Cases
 
-**Prevent incorrect merges**: When you have cells with the same name but different contexts (e.g., different parent headers), use `FULL_RECTANGLE` or `HORIZONTAL_ONLY`:
-
-```java
-List<List<String>> multiHeader = new ArrayList<>();
-multiHeader.add(new ArrayList<>(Arrays.asList("head10")));
-multiHeader.add(new ArrayList<>(Arrays.asList("head20", "head21")));
-multiHeader.add(new ArrayList<>(Arrays.asList("head30", "head31")));
-multiHeader.add(new ArrayList<>(Arrays.asList("head40", "head31"))); // Same name "head31" but different context
-
-FastExcel.write(fileName)
-    .head(multiHeader)
-    .headerMergeStrategy(HeaderMergeStrategy.FULL_RECTANGLE) // Prevents incorrect vertical merge
-    .sheet()
-    .doWrite(data());
-```
-
 **Disable merging**: Use `NONE` to completely disable automatic merging:
 
 ```java

website/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/parameter.md

@@ -181,7 +181,7 @@ WriteWorkbook  --|>  WriteBasicParameter
 - **HORIZONTAL_ONLY**: 仅水平合并（同一行内的相同单元格）。
 - **VERTICAL_ONLY**: 仅垂直合并（同一列内的相同单元格）。
 - **FULL_RECTANGLE**: 仅合并完整的矩形区域（所有单元格名称相同）。
-- **AUTO**: 自动合并（默认行为，向后兼容），增强了上下文验证以防止错误的合并。
+- **AUTO**: 自动合并（默认行为，向后兼容）。
 
 **示例**:
 ```java

website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/head.md

@@ -90,7 +90,7 @@ public void dynamicHeadWrite() {
 - **HORIZONTAL_ONLY**: 仅水平合并（同一行内的相同单元格）。
 - **VERTICAL_ONLY**: 仅垂直合并（同一列内的相同单元格）。
 - **FULL_RECTANGLE**: 仅合并完整的矩形区域（所有单元格名称相同）。
-- **AUTO**: 自动合并（默认），增强了上下文验证。
+- **AUTO**: 自动合并（默认）。
 
 ### 代码示例
 
@@ -114,22 +114,6 @@ public void dynamicHeadWriteWithStrategy() {
 
 ### 常见使用场景
 
-**防止错误合并**: 当您有名称相同但上下文不同的单元格（例如，不同的父级表头）时，使用 `FULL_RECTANGLE` 或 `HORIZONTAL_ONLY`：
-
-```java
-List<List<String>> multiHeader = new ArrayList<>();
-multiHeader.add(new ArrayList<>(Arrays.asList("head10")));
-multiHeader.add(new ArrayList<>(Arrays.asList("head20", "head21")));
-multiHeader.add(new ArrayList<>(Arrays.asList("head30", "head31")));
-multiHeader.add(new ArrayList<>(Arrays.asList("head40", "head31"))); // 相同的名称 "head31" 但上下文不同
-
-FastExcel.write(fileName)
-    .head(multiHeader)
-    .headerMergeStrategy(HeaderMergeStrategy.FULL_RECTANGLE) // 防止错误的垂直合并
-    .sheet()
-    .doWrite(data());
-```
-
 **禁用合并**: 使用 `NONE` 完全禁用自动合并：
 
 ```java