"""DOCX 合并：把多份 docx 按顺序合并成一个（模板间分页 + 页脚隔离）。"""
from __future__ import annotations

from pathlib import Path

from docx import Document
from docx.enum.section import WD_SECTION
from docxcompose.composer import Composer

from app.core.logger import get_logger
from app.core.response import AppError

logger = get_logger(__name__)


def merge_docx(docx_paths: list[Path], output_path: str | Path) -> Path:
    """把多份 docx 按顺序合并成一个 docx（保留图片/样式/关系）。

    每个非首个文档前加「下一页」分节符，并解除页眉/页脚继承，避免前一模板的页脚泄漏。
    """
    if not docx_paths:
        raise AppError("无 docx 可合并")

    output_path = Path(output_path)
    output_path.parent.mkdir(parents=True, exist_ok=True)
    logger.info("合并 %d 个 docx -> %s", len(docx_paths), output_path)

    master = Document(str(docx_paths[0]))
    composer = Composer(master)
    for p in docx_paths[1:]:
        section = composer.doc.add_section(WD_SECTION.NEW_PAGE)
        section.footer.is_linked_to_previous = False
        section.header.is_linked_to_previous = False
        composer.append(Document(str(p)))
    composer.save(str(output_path))
    return output_path