feat(export): Word 文档样式和表格渲染优化

全面的段落格式支持：新增对行距、段前间距、段后间距等段落属性的完整支持
段落样式优先级应用：实现段落级样式的正确继承和覆盖机制
基于优先级的字体和字号应用：改进 run 级别的样式应用，确保字体名称和字号按正确优先级生效
健壮的 XML 元素管理：优化粗体、斜体、下划线格式的 XML 元素处理，确保格式正确应用
中文字符渲染支持：显式添加 eastAsia 字体属性，确保中文字符使用正确的字体显示
标题和段落块渲染优化：改进标题和段落块的样式应用逻辑，确保所有样式属性正确生效
空段落样式保留：修复空段落的样式保留问题，确保在 Word 中维持默认格式
对齐方式支持：为表格单元格添加水平对齐（左对齐、居中、右对齐）和垂直对齐（顶部、居中、底部）支持
单元格样式完整性：确保单元格内文本样式与对齐方式正确配合
全面的错误处理：为所有样式应用添加错误处理机制，防止单个样式错误影响整体导出
降级回退机制：当特定样式应用失败时，自动回退到默认样式，确保文档导出成功
SQLite 设计文档完善：更新 content-sqlite-design.md 文档，添加合并单元格的提取与导出的详细说明
设计模式和最佳实践：补充数据结构设计、XML 处理、样式优先级等最佳实践指南

app/services/export_service.py

@@ -9,6 +9,7 @@ from pathlib import Path
 from typing import Optional
 
 from docx import Document
+from docx.enum.table import WD_TABLE_ALIGNMENT, WD_CELL_VERTICAL_ALIGNMENT
 from docx.enum.text import WD_ALIGN_PARAGRAPH
 from docx.oxml import OxmlElement
 from docx.oxml.ns import qn
@@ -116,12 +117,7 @@ def _resolve_style_id(style_map: dict, *keys: str) -> Optional[str]:
 
 
 def _apply_paragraph_style(para, style: dict):
-    """应用段落级样式（对齐方式）
-    
-    Args:
-        para: python-docx 段落对象
-        style: 样式字典
-    """
+    """应用段落级样式（对齐方式、行距、缩进等）"""
     # 对齐方式
     align = style.get('align')
     if align == 'center':
@@ -132,22 +128,115 @@ def _apply_paragraph_style(para, style: dict):
         para.alignment = WD_ALIGN_PARAGRAPH.JUSTIFY
     elif align == 'left':
         para.alignment = WD_ALIGN_PARAGRAPH.LEFT
+    
+    # 段落格式（行距、缩进等）- 如果需要的话
+    pf = para.paragraph_format
+    
+    # 行距
+    if style.get('line_spacing'):
+        try:
+            pf.line_spacing = style['line_spacing']
+        except Exception:
+            pass
+    
+    # 段前间距
+    if style.get('space_before'):
+        try:
+            pf.space_before = Pt(style['space_before'])
+        except Exception:
+            pass
+    
+    # 段后间距
+    if style.get('space_after'):
+        try:
+            pf.space_after = Pt(style['space_after'])
+        except Exception:
+            pass
 
 
 def _apply_run_style(run, style: dict):
-    """应用 run 级样式（字符级格式）
+    """应用 run 级样式（字符级格式）- 增强版"""
+    # 字体名称（支持中文字体 eastAsia）- 优先处理字体
+    if style.get('font_name'):
+        font_name = style['font_name']
+        run.font.name = font_name
+        
+        # 对于中文字体，需要设置 eastAsia 属性（关键！）
+        try:
+            r = run._element
+            rPr = r.get_or_add_rPr()
+            rFonts = rPr.get_or_add_rFonts()
+            # 设置所有字体属性，确保中文字体正确应用
+            rFonts.set(qn('w:ascii'), font_name)
+            rFonts.set(qn('w:hAnsi'), font_name)
+            rFonts.set(qn('w:eastAsia'), font_name)
+            rFonts.set(qn('w:cs'), font_name)  # 复杂文字
+        except Exception:
+            pass
+    
+    # 字号（优先处理）
+    if style.get('font_size'):
+        try:
+            size_pt = float(style['font_size'])
+            run.font.size = Pt(size_pt)
+            
+            # 确保字号正确应用到 XML
+            r = run._element
+            rPr = r.get_or_add_rPr()
+            
+            # 移除旧的字号元素
+            for sz in rPr.findall(qn('w:sz')):
+                rPr.remove(sz)
+            for szCs in rPr.findall(qn('w:szCs')):
+                rPr.remove(szCs)
+            
+            # 添加新的字号元素（Word 使用半磅单位）
+            sz = OxmlElement('w:sz')
+            sz.set(qn('w:val'), str(int(size_pt * 2)))
+            rPr.append(sz)
+            
+            szCs = OxmlElement('w:szCs')
+            szCs.set(qn('w:val'), str(int(size_pt * 2)))
+            rPr.append(szCs)
+        except Exception:
+            pass
     
-    Args:
-        run: python-docx run 对象
-        style: 样式字典
-    """
     # 粗体
     if style.get('bold'):
         run.bold = True
+        # 确保粗体正确应用
+        try:
+            r = run._element
+            rPr = r.get_or_add_rPr()
+            # 移除旧的粗体元素
+            for b in rPr.findall(qn('w:b')):
+                rPr.remove(b)
+            for bCs in rPr.findall(qn('w:bCs')):
+                rPr.remove(bCs)
+            # 添加新的粗体元素
+            b = OxmlElement('w:b')
+            rPr.append(b)
+            bCs = OxmlElement('w:bCs')
+            rPr.append(bCs)
+        except Exception:
+            pass
     
     # 斜体
     if style.get('italic'):
         run.italic = True
+        try:
+            r = run._element
+            rPr = r.get_or_add_rPr()
+            for i in rPr.findall(qn('w:i')):
+                rPr.remove(i)
+            for iCs in rPr.findall(qn('w:iCs')):
+                rPr.remove(iCs)
+            i = OxmlElement('w:i')
+            rPr.append(i)
+            iCs = OxmlElement('w:iCs')
+            rPr.append(iCs)
+        except Exception:
+            pass
     
     # 下划线
     if style.get('underline'):
@@ -170,24 +259,6 @@ def _apply_run_style(run, style: dict):
                 )
         except (ValueError, AttributeError):
             pass
-    
-    # 字体名称（支持中文字体 eastAsia）
-    if style.get('font_name'):
-        font_name = style['font_name']
-        run.font.name = font_name
-        
-        # 对于中文字体，需要设置 eastAsia 属性
-        try:
-            r = run._element
-            rPr = r.get_or_add_rPr()
-            rFonts = rPr.get_or_add_rFonts()
-            rFonts.set(qn('w:eastAsia'), font_name)
-        except Exception:
-            pass
-    
-    # 字号
-    if style.get('font_size'):
-        run.font.size = Pt(style['font_size'])
 
 
 # ------------------------------------------------------------------ #
@@ -406,7 +477,7 @@ def _inject_numbering_via_zip(docx_bytes: bytes, style_data: dict) -> bytes:
 
 
 def _render_heading_block(doc: Document, block: dict, style_map: dict):
-    """渲染标题块（支持编号格式和自定义样式）"""
+    """渲染标题块（支持编号格式和自定义样式）- 增强版"""
     level = block['level']
     content = block['content']
     style_name = block.get('word_style', f'Heading {level}')
@@ -435,7 +506,9 @@ def _render_heading_block(doc: Document, block: dict, style_map: dict):
     else:
         # 纯文本：应用 block 级样式到 run
         run = para.add_run(str(content))
-        _apply_run_style(run, block_style)
+        # 标题也需要应用自定义样式（如果有的话）
+        if block_style:
+            _apply_run_style(run, block_style)
     
     # 尝试应用编号格式（如果样式中包含编号定义）
     try:
@@ -463,7 +536,7 @@ def _render_heading_block(doc: Document, block: dict, style_map: dict):
 
 
 def _render_paragraph_block(doc: Document, block: dict, style_map: dict):
-    """渲染段落块（支持富文本和自定义样式）"""
+    """渲染段落块（支持富文本和自定义样式）- 增强版"""
     content = block['content']
     style_name = block.get('word_style', 'Normal')
     block_style = block.get('style', {})
@@ -487,22 +560,62 @@ def _render_paragraph_block(doc: Document, block: dict, style_map: dict):
     if isinstance(content, list):
         # 富文本：应用 run 级样式
         _render_rich_text(para, content, block_style)
+    elif content:
+        # 有内容的纯文本
+        run = para.add_run(str(content))
+        _apply_run_style(run, block_style)
     else:
-        # 纯文本或空内容
-        # 即使是空内容，如果有 block 级样式（字体、字号等），也需要添加空 run 来保存样式
-        # 这样当用户在 Word 中输入文本时，会自动应用这些样式
-        run = para.add_run(str(content) if content else '')
+        # 空内容 - 关键修复：确保空段落也能保留样式
+        # 创建空 run 并应用样式，这样用户在 Word 中输入文本时会自动应用这些样式
+        run = para.add_run('')
         _apply_run_style(run, block_style)
+        
+        # 对于空段落，还需要确保段落格式正确
+        # 特别是字体和字号，即使 run 是空的也要设置
+        if block_style.get('font_name') or block_style.get('font_size'):
+            # 再添加一个空格符 run 来"激活"样式（Word 的特殊处理）
+            # 然后立即删除，但样式会保留
+            try:
+                # 方法：在段落属性中设置默认 run 属性
+                pPr = para._element.get_or_add_pPr()
+                rPr = pPr.find(qn('w:rPr'))
+                if rPr is None:
+                    rPr = OxmlElement('w:rPr')
+                    pPr.insert(0, rPr)
+                
+                # 设置字体
+                if block_style.get('font_name'):
+                    font_name = block_style['font_name']
+                    rFonts = rPr.find(qn('w:rFonts'))
+                    if rFonts is None:
+                        rFonts = OxmlElement('w:rFonts')
+                        rPr.append(rFonts)
+                    rFonts.set(qn('w:ascii'), font_name)
+                    rFonts.set(qn('w:hAnsi'), font_name)
+                    rFonts.set(qn('w:eastAsia'), font_name)
+                    rFonts.set(qn('w:cs'), font_name)
+                
+                # 设置字号
+                if block_style.get('font_size'):
+                    size_pt = float(block_style['font_size'])
+                    # 移除旧的字号
+                    for sz in rPr.findall(qn('w:sz')):
+                        rPr.remove(sz)
+                    for szCs in rPr.findall(qn('w:szCs')):
+                        rPr.remove(szCs)
+                    # 添加新的字号
+                    sz = OxmlElement('w:sz')
+                    sz.set(qn('w:val'), str(int(size_pt * 2)))
+                    rPr.append(sz)
+                    szCs = OxmlElement('w:szCs')
+                    szCs.set(qn('w:val'), str(int(size_pt * 2)))
+                    rPr.append(szCs)
+            except Exception:
+                pass
 
 
 def _render_rich_text(para, segments: list, block_style: dict = None):
-    """渲染富文本格式
-    
-    Args:
-        para: python-docx 段落对象
-        segments: 富文本片段列表，每个片段包含 text 和 style
-        block_style: Block 级样式，作为默认样式（可选）
-    """
+    """渲染富文本格式 - 增强版"""
     for seg in segments:
         text = seg.get('text', '')
         seg_style = seg.get('style', {})
@@ -516,7 +629,15 @@ def _render_rich_text(para, segments: list, block_style: dict = None):
         merged_style.update(seg_style)
         
         # 应用合并后的样式
-        _apply_run_style(run, merged_style)
+        if merged_style:
+            _apply_run_style(run, merged_style)
+        
+        # 处理 word_style（如果片段有独立的 word_style）
+        word_style = seg.get('word_style')
+        if word_style:
+            # 注意：run 不能直接应用样式，只能应用字符样式
+            # 这里我们只应用格式属性
+            pass
 
 
 def _render_table_block(doc: Document, block: dict, style_map: dict):
@@ -561,6 +682,16 @@ def _render_table_block(doc: Document, block: dict, style_map: dict):
     except KeyError:
         table.style = 'Table Grid'
     
+    # 设置表格对齐方式（默认居中）
+    block_style = block.get('style', {})
+    table_align = block_style.get('table_align', 'center')  # 默认居中
+    if table_align == 'center':
+        table.alignment = WD_TABLE_ALIGNMENT.CENTER
+    elif table_align == 'left':
+        table.alignment = WD_TABLE_ALIGNMENT.LEFT
+    elif table_align == 'right':
+        table.alignment = WD_TABLE_ALIGNMENT.RIGHT
+    
     # 设置列宽
     if col_widths:
         for col_idx, width in enumerate(col_widths):
@@ -569,6 +700,7 @@ def _render_table_block(doc: Document, block: dict, style_map: dict):
     
     # 填充内容并处理合并单元格
     merge_map = {}  # {(row, col): (end_row, end_col)} 记录合并区域
+    occupied = {}  # {(row, col): True} 记录哪些位置已被占用（被合并的单元格）
     
     for r_idx, row_data in enumerate(rows):
         # 设置行高
@@ -577,36 +709,58 @@ def _render_table_block(doc: Document, block: dict, style_map: dict):
             table.rows[r_idx].height = Pt(row_height)
         
         cells_data = row_data.get('cells', [])
-        col_offset = 0  # 当前列偏移（考虑 colspan）
         
+        # 构建一个映射：col_index -> cell_data
+        cells_by_col = {}
         for cell_data in cells_data:
+            col_idx = cell_data.get('col_index', None)
+            if col_idx is not None:
+                cells_by_col[col_idx] = cell_data
+        
+        # 遍历所有列
+        for col_idx in range(num_cols):
+            # 检查这个位置是否被占用（被上方的合并单元格占用）
+            if occupied.get((r_idx, col_idx), False):
+                continue  # 跳过被占用的位置
+            
+            # 检查是否有数据要填充到这个位置
+            if col_idx not in cells_by_col:
+                continue  # 这个位置没有数据
+            
+            cell_data = cells_by_col[col_idx]
+            
             # 跳过被合并的单元格（rowspan=0 表示这个单元格被上面的单元格合并了）
             rowspan = cell_data.get('rowspan', 1)
             if rowspan == 0:
-                col_offset += 1
                 continue
             
             colspan = cell_data.get('colspan', 1)
             
             # 确保不越界
-            if col_offset >= num_cols:
-                break
+            if col_idx >= num_cols:
+                continue
             
             # 获取起始单元格
-            start_cell = table.rows[r_idx].cells[col_offset]
+            start_cell = table.rows[r_idx].cells[col_idx]
             
             # 处理合并单元格
             if colspan > 1 or rowspan > 1:
                 # 计算结束位置
-                end_col = min(col_offset + colspan - 1, num_cols - 1)
+                end_col = min(col_idx + colspan - 1, num_cols - 1)
                 end_row = min(r_idx + rowspan - 1, num_rows - 1)
                 
                 # 合并单元格
-                if end_col > col_offset or end_row > r_idx:
+                if end_col > col_idx or end_row > r_idx:
                     try:
                         end_cell = table.rows[end_row].cells[end_col]
                         start_cell.merge(end_cell)
-                        merge_map[(r_idx, col_offset)] = (end_row, end_col)
+                        merge_map[(r_idx, col_idx)] = (end_row, end_col)
+                        
+                        # 标记被合并的单元格位置为已占用
+                        for merge_r in range(r_idx, end_row + 1):
+                            for merge_c in range(col_idx, end_col + 1):
+                                if merge_r != r_idx or merge_c != col_idx:  # 不标记起始单元格
+                                    occupied[(merge_r, merge_c)] = True
                     except Exception:
                         pass  # 合并失败，继续
             
@@ -621,11 +775,45 @@ def _render_table_block(doc: Document, block: dict, style_map: dict):
             # 填充单元格内容
             cell_text = cell_data.get('text', '')
             cell_style = cell_data.get('style', {})
+            cell_word_style = cell_data.get('word_style')  # 获取单元格的 word_style
+            
+            # 设置单元格垂直对齐（默认居中）
+            valign = cell_style.get('valign', 'center')  # 默认垂直居中
+            if valign == 'center' or valign == 'middle':
+                start_cell.vertical_alignment = WD_CELL_VERTICAL_ALIGNMENT.CENTER
+            elif valign == 'top':
+                start_cell.vertical_alignment = WD_CELL_VERTICAL_ALIGNMENT.TOP
+            elif valign == 'bottom':
+                start_cell.vertical_alignment = WD_CELL_VERTICAL_ALIGNMENT.BOTTOM
             
             # 清空默认段落
             start_cell.text = ''
             para = start_cell.paragraphs[0]
             
+            # 应用单元格的 Word 样式（如果有）
+            if cell_word_style:
+                # 尝试从 style_map 解析样式ID
+                style_id = _resolve_style_id(style_map, cell_word_style)
+                
+                if style_id:
+                    # 通过 style_id 应用样式
+                    try:
+                        para.style = doc.styles[style_id]
+                    except KeyError:
+                        # 如果 style_id 不存在，尝试直接使用名称
+                        try:
+                            para.style = cell_word_style
+                        except KeyError:
+                            # 都失败了，使用 Normal
+                            para.style = 'Normal'
+                else:
+                    # 没有找到 style_id，尝试直接使用名称
+                    try:
+                        para.style = cell_word_style
+                    except KeyError:
+                        # 失败了，使用 Normal
+                        para.style = 'Normal'
+            
             # 应用单元格段落级样式（对齐）
             _apply_paragraph_style(para, cell_style)
             
@@ -638,9 +826,6 @@ def _render_table_block(doc: Document, block: dict, style_map: dict):
                 run = para.add_run(str(cell_text))
                 # 应用单元格 run 级样式
                 _apply_run_style(run, cell_style)
-            
-            # 更新列偏移
-            col_offset += colspan
 
 
 def _render_image_block(doc: Document, block: dict):

app/services/word_parser.py

@@ -18,14 +18,7 @@ _current_theme_fonts = {}
 
 
 def _load_theme_fonts(docx_path: Path) -> dict:
-    """从 Word 文档中加载主题字体定义
-    
-    Args:
-        docx_path: Word 文档路径
-        
-    Returns:
-        主题字体映射字典，例如: {'minorEastAsia': '宋体', 'majorEastAsia': '黑体'}
-    """
+    """从 Word 文档中加载主题字体定义"""
     # 检查缓存
     cache_key = str(docx_path)
     if cache_key in _theme_fonts_cache:
@@ -83,14 +76,7 @@ def _load_theme_fonts(docx_path: Path) -> dict:
 
 
 def _get_eastasia_font_from_element(element):
-    """从 XML 元素中提取 eastAsia 字体（用于中文字体）
-    
-    Args:
-        element: rPr XML 元素
-        
-    Returns:
-        eastAsia 字体名称或 None
-    """
+    """从 XML 元素中提取 eastAsia 字体（用于中文字体）"""
     if element is None:
         return None
     rFonts = element.find(qn('w:rFonts'))
@@ -102,19 +88,7 @@ def _get_eastasia_font_from_element(element):
 
 
 def _get_font_name(run, theme_fonts: dict = None):
-    """获取 run 的字体名（优先 eastAsia，其次 ascii，支持主题字体）
-    
-    特殊处理：如果 run 只定义了 ascii 字体（如 Times New Roman），
-    但没有定义 eastAsia，则忽略 run 的字体，返回 None 让其从样式继承中文字体。
-    这样可以正确处理混合语言的字体继承。
-    
-    Args:
-        run: python-docx Run 对象
-        theme_fonts: 主题字体映射字典（可选，默认使用全局的 _current_theme_fonts）
-        
-    Returns:
-        字体名称或 None
-    """
+    """获取 run 的字体名（优先 eastAsia，其次 ascii，支持主题字体；特殊处理混合语言字体继承）"""
     if theme_fonts is None:
         theme_fonts = _current_theme_fonts
     
@@ -153,16 +127,7 @@ def _get_font_name(run, theme_fonts: dict = None):
 
 
 def _get_paragraph_style_font(para):
-    """从段落样式中提取字体（当 run 级别没有字体设置时使用）
-    
-    优先提取 eastAsia（中文字体），如果没有则查找基础样式的 eastAsia
-    
-    Args:
-        para: python-docx 段落对象
-        
-    Returns:
-        字体名称或 None
-    """
+    """从段落样式中提取字体（当 run 级别没有字体设置时使用，优先 eastAsia）"""
     try:
         style = para.style
         if hasattr(style, 'element'):
@@ -201,14 +166,7 @@ def _get_paragraph_style_font(para):
 
 
 def _get_paragraph_style_font_recursive(style):
-    """递归查找样式的 eastAsia 字体（用于基础样式查找）
-    
-    Args:
-        style: python-docx Style 对象
-        
-    Returns:
-        eastAsia 字体名称或 None
-    """
+    """递归查找样式的 eastAsia 字体（用于基础样式查找）"""
     try:
         if hasattr(style, 'element'):
             rPr = style.element.find(qn('w:rPr'))
@@ -229,14 +187,7 @@ def _get_paragraph_style_font_recursive(style):
 
 
 def _get_style_formatting(style):
-    """从样式中提取格式属性（加粗、斜体、下划线等）
-    
-    Args:
-        style: python-docx Style 对象
-        
-    Returns:
-        格式属性字典 {'bold': True/False, 'italic': True/False, ...}
-    """
+    """从样式中提取格式属性（加粗、斜体、下划线等）"""
     formatting = {}
     
     if not style or not hasattr(style, 'element'):
@@ -274,14 +225,7 @@ def _get_style_formatting(style):
 
 
 def parse_word_to_blocks(docx_path: Path) -> list[dict]:
-    """将 Word 文档解析为 Block 列表
-    
-    Args:
-        docx_path: Word 文档路径
-        
-    Returns:
-        Block 列表，每个 Block 包含 id, block_order, type, level, index, content 等字段
-    """
+    """将 Word 文档解析为 Block 列表"""
     global _current_theme_fonts
     
     doc = DocxDocument(str(docx_path))
@@ -513,15 +457,7 @@ def parse_word_to_blocks(docx_path: Path) -> list[dict]:
 
 
 def _identify_heading_level(para, style_name: str) -> Optional[int]:
-    """识别段落的标题级别
-    
-    Args:
-        para: python-docx 段落对象
-        style_name: 样式名称
-        
-    Returns:
-        标题级别（1-6）或 None（不是标题）
-    """
+    """识别段落的标题级别（1-6 或 None）"""
     # 方法1：检查样式名称（内置样式）
     if style_name.startswith('Heading'):
         try:
@@ -559,14 +495,7 @@ def _identify_heading_level(para, style_name: str) -> Optional[int]:
 
 
 def _extract_paragraph_format(para) -> dict:
-    """提取段落级样式（Block 级别的 style）
-    
-    Args:
-        para: python-docx 段落对象
-        
-    Returns:
-        段落样式字典（只包含设计文档 5.3 中可支持的属性）
-    """
+    """提取段落级样式（Block 级别的 style）"""
     style = {}
     
     # 对齐方式
@@ -656,16 +585,7 @@ def _extract_paragraph_format(para) -> dict:
 
 
 def _extract_rich_text(para) -> str | list:
-    """提取段落的富文本内容
-    
-    Args:
-        para: python-docx 段落对象
-        
-    Returns:
-        纯文本字符串 或 富文本片段列表
-        - 纯文本：所有 runs 样式相同，返回字符串
-        - 富文本：runs 样式不同，返回数组，每个元素包含完整样式
-    """
+    """提取段落的富文本内容（纯文本字符串或富文本片段列表）"""
     text = para.text.strip()
     if not text:
         return ""
@@ -760,14 +680,7 @@ def _extract_rich_text(para) -> str | list:
 
 
 def _extract_table(table) -> dict:
-    """提取表格内容
-    
-    Args:
-        table: python-docx 表格对象
-        
-    Returns:
-        表格数据字典，包含合并单元格和尺寸信息
-    """
+    """提取表格内容（包含合并单元格和尺寸信息）- 完整修复版"""
     rows_data = []
     
     # 提取表格列宽（从 tblGrid）
@@ -781,200 +694,312 @@ def _extract_table(table) -> dict:
                 # twips 转 pt (1 pt = 20 twips)
                 col_widths.append(int(width) / 20)
     
-    # 用于跟踪行合并（vMerge）
-    # col_index -> {start_row, rowspan_count}
-    vmerge_tracking = {}
+    # 第一遍：从 XML 直接读取，建立列索引到行合并信息的映射
+    # col_index -> [{start_row, end_row}, ...]  # 可能有多个合并区间
+    vmerge_map = {}
     
-    for row_idx, row in enumerate(table.rows):
-        cells_data = []
-        
-        # 提取行高
-        row_height = None
-        if row.height:
-            row_height = row.height.pt
+    trs = tbl_elem.findall(qn('w:tr'))
+    for row_idx, tr in enumerate(trs):
+        tcs = tr.findall(qn('w:tc'))
+        col_offset = 0
         
-        col_offset = 0  # 当前列偏移（考虑 colspan）
-        seen_cells = set()  # 用于去重（基于对象 ID）
-        
-        for cell_idx, cell in enumerate(row.cells):
-            # 去重：跳过重复的单元格对象（合并单元格会返回同一个对象）
-            cell_id = id(cell)
-            if cell_id in seen_cells:
-                continue
-            seen_cells.add(cell_id)
-            # 提取单元格文本
-            cell_text = []
-            for para in cell.paragraphs:
-                para_text = _extract_rich_text(para)
-                if para_text:
-                    cell_text.append(para_text if isinstance(para_text, str) else para_text)
-            
-            # 检测单元格样式（从第一个段落的第一个 run）
-            cell_style = {}
-            cell_word_style = None  # 单元格的 word_style
-            
-            if cell.paragraphs:
-                first_para = cell.paragraphs[0]
-                
-                # 提取 word_style（段落样式）
-                if first_para.style:
-                    cell_word_style = first_para.style.name
-                    
-                    # 从样式中提取格式（加粗、斜体等）
-                    style_formatting = _get_style_formatting(first_para.style)
-                    # 将样式中定义的格式作为基础
-                    cell_style.update(style_formatting)
-                
-                if first_para.runs:
-                    first_run = first_para.runs[0]
-                    
-                    # 加粗（run 明确设置会覆盖样式）
-                    if first_run.bold is True:
-                        cell_style['bold'] = True
-                    elif first_run.bold is False:
-                        # 明确设置为不加粗，移除样式的加粗
-                        cell_style.pop('bold', None)
-                    # 如果 run.bold 为 None，保持样式中的设置
-                    
-                    # 斜体（run 明确设置会覆盖样式）
-                    if first_run.italic is True:
-                        cell_style['italic'] = True
-                    elif first_run.italic is False:
-                        cell_style.pop('italic', None)
-                    
-                    # 下划线（run 明确设置会覆盖样式）
-                    if first_run.underline:
-                        cell_style['underline'] = True
-                    
-                    # 字体
-                    font_name = _get_font_name(first_run)
-                    if font_name:
-                        cell_style['font_name'] = font_name
-                    
-                    # 字号
-                    if first_run.font.size:
-                        cell_style['font_size'] = first_run.font.size.pt
-                    
-                    # 颜色
-                    if first_run.font.color and first_run.font.color.rgb:
-                        cell_style['color'] = str(first_run.font.color.rgb)
-                
-                # 对齐方式
-                if first_para.alignment is not None:
-                    align_map = {0: 'left', 1: 'center', 2: 'right', 3: 'justify'}
-                    cell_style['align'] = align_map.get(first_para.alignment, 'left')
-            
-            # 合并多个段落的文本
-            if len(cell_text) == 1:
-                text_content = cell_text[0]
-            elif len(cell_text) > 1:
-                # 多个段落，用换行符连接
-                text_content = ' '.join(str(t) for t in cell_text)
-            else:
-                text_content = ""
-            
-            # 提取合并信息
-            tc_elem = cell._tc
-            tcPr = tc_elem.find(qn('w:tcPr'))
+        for tc in tcs:
+            tcPr = tc.find(qn('w:tcPr'))
             
             colspan = 1
-            rowspan = 1
-            is_vmerge_continue = False
+            has_vmerge_restart = False
+            has_vmerge_continue = False
+            is_empty = False
             
             if tcPr is not None:
-                # 列合并 (gridSpan)
+                # 列合并
                 grid_span = tcPr.find(qn('w:gridSpan'))
                 if grid_span is not None:
                     colspan = int(grid_span.get(qn('w:val')))
                 
-                # 行合并 (vMerge)
+                # 行合并
                 v_merge = tcPr.find(qn('w:vMerge'))
                 if v_merge is not None:
                     v_merge_val = v_merge.get(qn('w:val'))
                     if v_merge_val == 'restart':
-                        # 行合并起始
-                        vmerge_tracking[col_offset] = {
-                            'start_row': row_idx,
-                            'count': 1
-                        }
-                    elif v_merge_val is None:
-                        # 行合并继续（被合并的单元格）
-                        is_vmerge_continue = True
-                        if col_offset in vmerge_tracking:
-                            vmerge_tracking[col_offset]['count'] += 1
-            
-            # 计算实际的 rowspan
-            if col_offset in vmerge_tracking:
-                if vmerge_tracking[col_offset]['start_row'] == row_idx:
-                    # 这是起始行，后续会更新 rowspan
-                    rowspan = vmerge_tracking[col_offset]['count']
-                elif is_vmerge_continue:
-                    # 这是被合并的单元格，标记为 0（表示被合并）
-                    rowspan = 0
-            
-            # 提取单元格宽度
-            cell_width = None
+                        has_vmerge_restart = True
+                    else:
+                        # 'continue' 或 None/空字符串都表示继续合并
+                        has_vmerge_continue = True
+            
+            # 检查是否为空单元格（用于判断行合并）
+            paras = tc.findall(qn('w:p'))
+            text_parts = []
+            for p in paras:
+                runs = p.findall(qn('w:r'))
+                for r in runs:
+                    ts = r.findall(qn('w:t'))
+                    for t in ts:
+                        if t.text and t.text.strip():
+                            text_parts.append(t.text)
+            is_empty = len(text_parts) == 0
+            
+            # 处理行合并逻辑 - 记录所有合并区间
+            if col_offset not in vmerge_map:
+                vmerge_map[col_offset] = []
+            
+            merges = vmerge_map[col_offset]
+            
+            if has_vmerge_restart:
+                # 开始新的行合并
+                merges.append({
+                    'start_row': row_idx,
+                    'end_row': row_idx  # 初始结束行等于开始行，后续会扩展
+                })
+            elif has_vmerge_continue:
+                # 明确标记为 continue - 扩展最后一个合并
+                if merges:
+                    merges[-1]['end_row'] = row_idx
+            # 注意：移除了 "is_empty" 的判断，因为空单元格不一定意味着合并
+            
+            col_offset += colspan
+    
+    # 第二遍：完全从 XML 提取单元格数据
+    for row_idx, tr in enumerate(trs):
+        cells_data = []
+        
+        # 提取行高（从 python-docx，因为 XML 提取行高比较复杂）
+        row_height = None
+        if row_idx < len(table.rows):
+            row = table.rows[row_idx]
+            if row.height:
+                row_height = row.height.pt
+        
+        # 遍历 XML 的 tc 元素
+        tcs = tr.findall(qn('w:tc'))
+        col_offset = 0
+        
+        for tc in tcs:
+            # 首先提取 colspan 和 vMerge 信息
+            tcPr = tc.find(qn('w:tcPr'))
+            
+            # 提取 colspan
+            colspan = 1
             if tcPr is not None:
-                tcW = tcPr.find(qn('w:tcW'))
-                if tcW is not None:
-                    width_val = tcW.get(qn('w:w'))
-                    width_type = tcW.get(qn('w:type'))
-                    if width_val and width_type != 'pct':
-                        # twips 转 pt
-                        cell_width = int(width_val) / 20
-            
-            # 如果没有明确宽度，使用列宽
-            if cell_width is None and col_offset < len(col_widths):
-                if colspan == 1:
-                    cell_width = col_widths[col_offset]
-                else:
-                    # 多列合并，计算总宽度
-                    cell_width = sum(col_widths[col_offset:col_offset + colspan])
-            
-            # 构建单元格数据（方案 D：包含 word_style）
-            cell_data = {
-                'text': text_content,
-                'rowspan': rowspan,
-                'colspan': colspan,
-                'style': cell_style
-            }
+                grid_span = tcPr.find(qn('w:gridSpan'))
+                if grid_span is not None:
+                    colspan = int(grid_span.get(qn('w:val')))
+            
+            # 检查 vMerge - 如果是 continue，跳过这个单元格
+            is_vmerge_continue = False
+            if tcPr is not None:
+                v_merge = tcPr.find(qn('w:vMerge'))
+                if v_merge is not None:
+                    v_merge_val = v_merge.get(qn('w:val'))
+                    # 'continue' 或 None/空字符串都表示继续合并
+                    if v_merge_val != 'restart':
+                        is_vmerge_continue = True
+            
+            if is_vmerge_continue:
+                # 这是被合并的单元格，跳过
+                col_offset += colspan
+                continue
+            
+            # 不需要跳过被占用的列，因为 XML 中已经包含了占位符
+            # （上面的 is_vmerge_continue 检查已经处理了）
             
-            # 添加 word_style
-            if cell_word_style:
-                cell_data['word_style'] = cell_word_style
+            # 检查是否为空单元格
+            is_empty = True
+            paras = tc.findall(qn('w:p'))
+            text_parts = []
+            for p in paras:
+                runs = p.findall(qn('w:r'))
+                for r in runs:
+                    ts = r.findall(qn('w:t'))
+                    for t in ts:
+                        if t.text and t.text.strip():
+                            is_empty = False
+                            text_parts.append(t.text)
             
-            # 添加尺寸信息
-            if cell_width is not None:
-                cell_data['width'] = round(cell_width, 2)
+            # 判断是否应该提取此单元格
+            should_extract = True
+            rowspan = 1
+            
+            # 查找该列该行所在的合并区间
+            if col_offset in vmerge_map:
+                merges = vmerge_map[col_offset]
+                for merge in merges:
+                    if merge['start_row'] == row_idx:
+                        # 这是合并的起始行
+                        rowspan = merge['end_row'] - merge['start_row'] + 1
+                        break
+                    elif row_idx > merge['start_row'] and row_idx <= merge['end_row']:
+                        # 这是被合并的行
+                        should_extract = False  # 跳过被合并的单元格
+                        break
             
-            cells_data.append(cell_data)
+            if should_extract:
+                # 从 XML 提取文本（支持富文本）
+                cell_text_segments = []
+                for p in paras:
+                    para_segments = []
+                    runs = p.findall(qn('w:r'))
+                    
+                    for r in runs:
+                        # 提取文本
+                        run_text = []
+                        for t in r.findall(qn('w:t')):
+                            if t.text:
+                                run_text.append(t.text)
+                        
+                        if run_text:
+                            # 提取 run 级样式
+                            run_style = {}
+                            rPr = r.find(qn('w:rPr'))
+                            if rPr is not None:
+                                # 加粗
+                                if rPr.find(qn('w:b')) is not None:
+                                    run_style['bold'] = True
+                                
+                                # 斜体
+                                if rPr.find(qn('w:i')) is not None:
+                                    run_style['italic'] = True
+                                
+                                # 下划线
+                                if rPr.find(qn('w:u')) is not None:
+                                    run_style['underline'] = True
+                                
+                                # 字号
+                                sz = rPr.find(qn('w:sz'))
+                                if sz is not None:
+                                    size_val = sz.get(qn('w:val'))
+                                    if size_val:
+                                        run_style['font_size'] = int(size_val) / 2  # 半磅转磅
+                                
+                                # 颜色
+                                color = rPr.find(qn('w:color'))
+                                if color is not None:
+                                    color_val = color.get(qn('w:val'))
+                                    if color_val and color_val != 'auto':
+                                        run_style['color'] = color_val
+                            
+                            para_segments.append({
+                                'text': ''.join(run_text),
+                                'style': run_style
+                            })
+                    
+                    if para_segments:
+                        cell_text_segments.extend(para_segments)
+                
+                # 合并文本
+                if len(cell_text_segments) == 0:
+                    text_content = ""
+                elif len(cell_text_segments) == 1 and not cell_text_segments[0]['style']:
+                    # 纯文本
+                    text_content = cell_text_segments[0]['text']
+                else:
+                    # 富文本或多个片段 - 简化处理：合并为纯文本
+                    text_content = ''.join(seg['text'] for seg in cell_text_segments)
+                
+                # 提取单元格样式（从第一个段落的第一个 run）
+                cell_style = {}
+                cell_word_style = None
+                
+                if paras:
+                    first_p = paras[0]
+                    pPr = first_p.find(qn('w:pPr'))
+                    
+                    if pPr is not None:
+                        # 段落样式名称
+                        pStyle = pPr.find(qn('w:pStyle'))
+                        if pStyle is not None:
+                            cell_word_style = pStyle.get(qn('w:val'))
+                        
+                        # 对齐方式
+                        jc = pPr.find(qn('w:jc'))
+                        if jc is not None:
+                            align_val = jc.get(qn('w:val'))
+                            align_map = {'left': 'left', 'center': 'center', 'right': 'right', 'both': 'justify'}
+                            cell_style['align'] = align_map.get(align_val, 'left')
+                    
+                    # 从第一个 run 提取样式
+                    runs = first_p.findall(qn('w:r'))
+                    if runs:
+                        first_r = runs[0]
+                        rPr = first_r.find(qn('w:rPr'))
+                        if rPr is not None:
+                            # 加粗
+                            if rPr.find(qn('w:b')) is not None:
+                                cell_style['bold'] = True
+                            
+                            # 斜体
+                            if rPr.find(qn('w:i')) is not None:
+                                cell_style['italic'] = True
+                            
+                            # 下划线
+                            if rPr.find(qn('w:u')) is not None:
+                                cell_style['underline'] = True
+                            
+                            # 字号
+                            sz = rPr.find(qn('w:sz'))
+                            if sz is not None:
+                                size_val = sz.get(qn('w:val'))
+                                if size_val:
+                                    cell_style['font_size'] = int(size_val) / 2
+                            
+                            # 颜色
+                            color = rPr.find(qn('w:color'))
+                            if color is not None:
+                                color_val = color.get(qn('w:val'))
+                                if color_val and color_val != 'auto':
+                                    cell_style['color'] = color_val
+                            
+                            # 字体（复杂，需要处理主题字体）
+                            rFonts = rPr.find(qn('w:rFonts'))
+                            if rFonts is not None:
+                                font_name = (rFonts.get(qn('w:eastAsia')) or 
+                                           rFonts.get(qn('w:ascii')) or 
+                                           rFonts.get(qn('w:hAnsi')))
+                                if font_name:
+                                    cell_style['font_name'] = font_name
+                
+                # 提取单元格宽度
+                cell_width = None
+                if tcPr is not None:
+                    tcW = tcPr.find(qn('w:tcW'))
+                    if tcW is not None:
+                        width_val = tcW.get(qn('w:w'))
+                        width_type = tcW.get(qn('w:type'))
+                        if width_val and width_type != 'pct':
+                            cell_width = int(width_val) / 20
+                
+                if cell_width is None and col_offset < len(col_widths):
+                    if colspan == 1:
+                        cell_width = col_widths[col_offset]
+                    else:
+                        cell_width = sum(col_widths[col_offset:col_offset + colspan])
+                
+                # 构建单元格数据
+                cell_data = {
+                    'text': text_content,
+                    'rowspan': rowspan,
+                    'colspan': colspan,
+                    'col_index': col_offset,  # 记录该单元格的绝对列位置
+                    'style': cell_style
+                }
+                
+                if cell_word_style:
+                    cell_data['word_style'] = cell_word_style
+                
+                if cell_width is not None:
+                    cell_data['width'] = round(cell_width, 2)
+                
+                cells_data.append(cell_data)
             
-            # 更新列偏移
             col_offset += colspan
         
         # 构建行数据
-        row_data = {
-            'cells': cells_data
-        }
-        
-        # 添加行高
+        row_data = {'cells': cells_data}
         if row_height is not None:
             row_data['height'] = round(row_height, 2)
         
         rows_data.append(row_data)
     
-    # 第二遍：更新 rowspan 值
-    for col_idx, info in vmerge_tracking.items():
-        start_row = info['start_row']
-        count = info['count']
-        # 找到起始行的单元格并更新 rowspan
-        if start_row < len(rows_data):
-            for cell in rows_data[start_row]['cells']:
-                # 简化：假设 col_idx 对应 cells 索引（实际可能需要考虑 colspan）
-                if 'rowspan' in cell and cell['rowspan'] > 0:
-                    cell['rowspan'] = count
-                    break
-    
     return {
         'rows': rows_data,
         'col_widths': [round(w, 2) for w in col_widths] if col_widths else None

docs/content-sqlite-design.md

@@ -893,7 +893,324 @@ ORDER BY block_order;
 ```
 
 
-#### 4.3.7 表格样式示例
+#### 4.3.7 合并单元格的提取与导出
+
+##### Word XML 中的合并单元格标记
+
+Word 文档使用 XML 标记表示合并单元格：
+
+**垂直合并（rowspan）标记：**
+```xml
+<!-- 合并起始单元格 -->
+<w:tc>
+    <w:tcPr>
+        <w:vMerge w:val="restart"/>  <!-- 标记合并开始 -->
+    </w:tcPr>
+    <w:p><w:r><w:t>井控风险级别划分</w:t></w:r></w:p>
+</w:tc>
+
+<!-- 被合并的单元格（在后续行中）-->
+<w:tc>
+    <w:tcPr>
+        <w:vMerge/>  <!-- 或 <w:vMerge w:val="continue"/> -->
+    </w:tcPr>
+    <w:p></w:p>  <!-- 内容通常为空 -->
+</w:tc>
+```
+
+**水平合并（colspan）标记：**
+```xml
+<w:tc>
+    <w:tcPr>
+        <w:gridSpan w:val="3"/>  <!-- 横跨3列 -->
+    </w:tcPr>
+    <w:p><w:r><w:t>标题</w:t></w:r></w:p>
+</w:tc>
+<!-- 注意：被横跨的列在 XML 中不存在 -->
+```
+
+**vMerge 属性值说明：**
+
+| vMerge 值 | 含义 | Python 解析结果 |
+|-----------|------|-----------------|
+| `w:val="restart"` | 垂直合并的起始单元格 | `v_merge_val = 'restart'` (字符串) |
+| `w:val="continue"` | 垂直合并的继续单元格（新格式） | `v_merge_val = 'continue'` (字符串) |
+| 无 val 属性（`<w:vMerge/>`）| 垂直合并的继续单元格（旧格式） | `v_merge_val = None` |
+
+**关键注意事项：**
+- ⚠️ `v_merge_val` 可能是字符串 `'continue'`，而不是 `None`
+- ⚠️ 被垂直合并的单元格在 XML 中**仍然存在**（只是标记为 vMerge），必须在提取时跳过
+- ⚠️ 被水平合并的列在 XML 中**不存在**，不需要特殊处理
+
+##### 提取阶段：两遍扫描算法
+
+提取表格时采用**两遍扫描**策略，确保正确识别合并单元格：
+
+**第一遍：构建 vmerge_map**
+
+扫描所有单元格的 XML 元素，记录每列的所有垂直合并区间：
+
+```python
+# vmerge_map 数据结构
+vmerge_map = {
+    0: [  # 列0的合并区间列表
+        {'start_row': 1, 'end_row': 12},   # 行1-12 合并
+        {'start_row': 15, 'end_row': 15}   # 行15 单独
+    ],
+    1: [  # 列1的合并区间列表
+        {'start_row': 1, 'end_row': 8},    # 行1-8 合并
+        {'start_row': 9, 'end_row': 11},   # 行9-11 合并
+        {'start_row': 12, 'end_row': 12}   # 行12 单独
+    ]
+}
+```
+
+**检测逻辑：**
+```python
+if has_vmerge_restart:
+    # 开始新的行合并区间
+    merges.append({
+        'start_row': row_idx,
+        'end_row': row_idx
+    })
+elif has_vmerge_continue:
+    # 扩展当前合并区间（只有明确标记为 continue 才扩展）
+    if merges:
+        merges[-1]['end_row'] = row_idx
+# ⚠️ 不使用 is_empty 判断，避免将空单元格误认为合并
+```
+
+**第二遍：提取单元格数据**
+
+从 XML 直接提取单元格，根据 vmerge_map 判断是否跳过：
+
+```python
+for row_idx, tr in enumerate(trs):
+    for tc in tr.findall(qn('w:tc')):
+        # 1. 检查 vMerge 标记
+        v_merge_val = tc.find('.//w:vMerge').get(qn('w:val'))
+        
+        # 2. 跳过被合并的单元格
+        if v_merge_val != 'restart':  # 'continue' 或 None
+            col_offset += colspan
+            continue  # 不提取被合并的单元格
+        
+        # 3. 计算 rowspan
+        rowspan = 1
+        if col_offset in vmerge_map:
+            for merge in vmerge_map[col_offset]:
+                if merge['start_row'] == row_idx:
+                    rowspan = merge['end_row'] - merge['start_row'] + 1
+                    break
+        
+        # 4. 提取单元格数据（从 XML）
+        cell_data = {
+            'text': extract_text_from_xml(tc),
+            'rowspan': rowspan,
+            'colspan': colspan,
+            'col_index': col_offset,  # ← 记录绝对列位置
+            'style': extract_style_from_xml(tc)
+        }
+        
+        cells_data.append(cell_data)
+        col_offset += colspan
+```
+
+**关键字段：`col_index`**
+- `col_index` 记录单元格在表格中的绝对列位置（0-based）
+- 对于导出阶段至关重要，确保单元格被放置到正确的列
+
+##### 导出阶段：列索引映射
+
+导出时使用 `col_index` 字段确保单元格被放置到正确的列位置：
+
+**导出逻辑：**
+```python
+# 1. 构建列索引映射
+cells_by_col = {}
+for cell_data in cells_data:
+    col_idx = cell_data.get('col_index')
+    if col_idx is not None:
+        cells_by_col[col_idx] = cell_data
+
+# 2. 遍历所有列（而非只遍历 cells_data）
+occupied = {}  # 记录被合并单元格占用的位置
+for col_idx in range(num_cols):
+    # 3. 检查位置是否被占用
+    if occupied.get((r_idx, col_idx), False):
+        continue  # 跳过被占用的位置
+    
+    # 4. 检查是否有数据填充
+    if col_idx not in cells_by_col:
+        continue  # 这个位置没有数据
+    
+    cell_data = cells_by_col[col_idx]
+    
+    # 5. 使用绝对列位置访问单元格
+    start_cell = table.rows[r_idx].cells[col_idx]
+    
+    # 6. 处理合并
+    if colspan > 1 or rowspan > 1:
+        end_row = r_idx + rowspan - 1
+        end_col = col_idx + colspan - 1
+        end_cell = table.rows[end_row].cells[end_col]
+        start_cell.merge(end_cell)
+        
+        # 7. 标记被合并的位置为已占用
+        for merge_r in range(r_idx, end_row + 1):
+            for merge_c in range(col_idx, end_col + 1):
+                if merge_r != r_idx or merge_c != col_idx:
+                    occupied[(merge_r, merge_c)] = True
+```
+
+**关键改进：**
+- ✓ 使用 `cells_by_col` 映射，避免按顺序迭代
+- ✓ 遍历所有列（0 到 num_cols-1），而非只遍历提取的单元格
+- ✓ 使用 `occupied` 字典跟踪被合并占用的位置
+- ✓ 使用 `col_index` 而非 `col_offset`，确保位置正确
+
+##### 合并单元格数据示例
+
+**表格效果：**
+```
+┌──────────────┬─────────┬──────────┬──────┬──────┐
+│井控风险级别  │  一级   │ 预测地层 │      │      │
+│划分          │         │ 压力     │      │      │
+│(12行合并)    │(8行合并)│≥105MPa  │      │      │
+├──────────────┼─────────┼──────────┼──────┼──────┤
+│              │         │ 预测硫化 │      │      │
+│              │         │ 氢含量   │      │      │
+│              ├─────────┼──────────┼──────┼──────┤
+│              │  二级   │ ...      │      │      │
+│              │(3行合并)│          │      │      │
+└──────────────┴─────────┴──────────┴──────┴──────┘
+```
+
+**提取结果（JSON 数据）：**
+
+```json
+{
+  "rows": [
+    {
+      "cells": [
+        {
+          "col_index": 0,
+          "rowspan": 12,
+          "colspan": 1,
+          "text": "井控风险级别划分",
+          "style": {}
+        },
+        {
+          "col_index": 1,
+          "rowspan": 8,
+          "colspan": 1,
+          "text": "一级",
+          "style": {}
+        },
+        {
+          "col_index": 2,
+          "rowspan": 1,
+          "colspan": 3,
+          "text": "预测地层压力≥105MPa",
+          "style": {}
+        },
+        {
+          "col_index": 5,
+          "rowspan": 1,
+          "colspan": 1,
+          "text": " ",
+          "style": {}
+        },
+        {
+          "col_index": 6,
+          "rowspan": 1,
+          "colspan": 1,
+          "text": " ",
+          "style": {}
+        }
+      ]
+    },
+    {
+      "cells": [
+        // 注意：列0和列1被上一行占用，不在此行定义
+        {
+          "col_index": 2,
+          "rowspan": 1,
+          "colspan": 3,
+          "text": "预测硫化氢含量...",
+          "style": {}
+        },
+        {
+          "col_index": 5,
+          "rowspan": 1,
+          "colspan": 1,
+          "text": " ",
+          "style": {}
+        },
+        {
+          "col_index": 6,
+          "rowspan": 1,
+          "colspan": 1,
+          "text": " ",
+          "style": {}
+        }
+      ]
+    },
+    {
+      "cells": [
+        // 列0仍被第1行占用，列1在第9行才重新开始
+        {
+          "col_index": 1,
+          "rowspan": 3,
+          "colspan": 1,
+          "text": "二级",
+          "style": {}
+        },
+        // ...
+      ]
+    }
+  ]
+}
+```
+
+**关键特征：**
+- ✓ 被合并的单元格**不出现**在数据中
+- ✓ 每个单元格都有 `col_index` 字段记录绝对列位置
+- ✓ `rowspan` 表示垂直跨越的行数（从 vmerge_map 计算）
+- ✓ `colspan` 表示水平跨越的列数（从 gridSpan 提取）
+
+##### 技术要点总结
+
+**提取阶段关键点：**
+1. ⚠️ **不要依赖 python-docx 的 `row.cells`**：对于合并单元格，它会在多行返回同一个对象
+2. ✓ **完全从 XML 提取**：直接解析 `<w:tc>` 元素
+3. ✓ **两遍扫描**：第一遍构建 vmerge_map，第二遍提取数据
+4. ✓ **跳过 vMerge=continue**：只提取合并起始单元格（restart）
+5. ✓ **记录 col_index**：为每个单元格记录绝对列位置
+
+**导出阶段关键点：**
+1. ✓ **使用 col_index 映射**：不按顺序迭代 cells_data
+2. ✓ **遍历所有列**：从 0 到 num_cols-1，而非只遍历单元格数据
+3. ✓ **跟踪 occupied 位置**：记录哪些位置被合并单元格占用
+4. ✓ **使用绝对列索引**：`table.rows[r_idx].cells[col_idx]`
+5. ✓ **标记合并占用**：合并后标记所有涉及的位置为已占用
+
+**常见错误与修复：**
+
+| 错误 | 现象 | 原因 | 修复 |
+|------|------|------|------|
+| **错误合并** | 空单元格被合并 | 使用 `is_empty` 判断扩展合并 | 只在明确标记 `vMerge=continue` 时扩展 |
+| **重复单元格** | 被合并的单元格也被提取 | 没有跳过 `vMerge=continue` 单元格 | 检测并跳过 |
+| **位置错误** | 单元格在错误的列 | 按顺序迭代而非使用 col_index | 使用 `cells_by_col` 映射 + 遍历所有列 |
+| **应该合并的不合并** | rowspan 应该 >1 但为 1 | 第一遍扫描的判断逻辑不一致 | 统一使用 `v_merge_val != 'restart'` |
+
+##### 相关文档
+
+- `TABLE_MERGE_FIX_SUMMARY.md` - 提取阶段修复详细说明
+- `TABLE_EXPORT_FIX_SUMMARY.md` - 导出阶段修复详细说明
+- `MERGE_CELL_COMPLETE_FIX.md` - 完整修复总结
+
+#### 4.3.8 表格样式示例
 
 **示例 1：基础表格（无合并）**
 ```json
@@ -944,6 +1261,7 @@ ORDER BY block_order;
           "text": "标题", 
           "rowspan": 1, 
           "colspan": 3,       // ← 横跨3列
+          "col_index": 0,
           "style": {
             "bold": true,
             "align": "center",
@@ -957,20 +1275,21 @@ ORDER BY block_order;
         {
           "text": "项目A", 
           "rowspan": 2,       // ← 纵跨2行
-          "colspan": 1, 
+          "colspan": 1,
+          "col_index": 0,
           "style": {
             "valign": "middle"
           }
         },
-        {"text": "子项1", "rowspan": 1, "colspan": 1, "style": {}},
-        {"text": "100", "rowspan": 1, "colspan": 1, "style": {}}
+        {"text": "子项1", "rowspan": 1, "colspan": 1, "col_index": 1, "style": {}},
+        {"text": "100", "rowspan": 1, "colspan": 1, "col_index": 2, "style": {}}
       ]
     },
     {
       "cells": [
         // 注意：第1个单元格被上一行的"项目A"占据，所以这行只有2个单元格
-        {"text": "子项2", "rowspan": 1, "colspan": 1, "style": {}},
-        {"text": "200", "rowspan": 1, "colspan": 1, "style": {}}
+        {"text": "子项2", "rowspan": 1, "colspan": 1, "col_index": 1, "style": {}},
+        {"text": "200", "rowspan": 1, "colspan": 1, "col_index": 2, "style": {}}
       ]
     }
   ]
@@ -980,6 +1299,7 @@ ORDER BY block_order;
 **关键点：**
 - `colspan`: 横向合并，值为合并的列数
 - `rowspan`: 纵向合并，值为合并的行数
+- `col_index`: 单元格在表格中的绝对列位置（0-based）
 - 被合并占据的单元格**不需要**在数据中定义
 - 例如：第3行只定义2个单元格，因为第1个位置被"项目A"占据