Class DocumentComposer

ReportEngine/core/stitcher.py:15–130

将章节拼接成Document IR的简单装订器。 作用： - 按order排序章节，补充默认chapterId； - 防止anchor重复，生成全局唯一锚点； - 注入 IR 版本与生成时间戳。

class DocumentComposer:
    """
    将章节拼接成Document IR的简单装订器。

    作用：
        - 按order排序章节，补充默认chapterId；
        - 防止anchor重复，生成全局唯一锚点；
        - 注入 IR 版本与生成时间戳。
    """

    def __init__(self):
        """初始化装订器并记录已使用的锚点，避免重复"""
        self._seen_anchors: Set[str] = set()

    def build_document(
        self,
        report_id: str,
        metadata: Dict[str, object],
        chapters: List[Dict[str, object]],
    ) -> Dict[str, object]:
        """
        把所有章节按order排序并注入唯一锚点，形成整本IR。

        同时合并 metadata/themeTokens/assets，供渲染器直接消费。

        参数:
            report_id: 本次报告ID。
            metadata: 全局元信息（标题、主题、toc等）。
            chapters: 章节payload列表。

        返回:
            dict: 满足渲染器需求的Document IR。
        """
        # 构建从chapterId到toc anchor的映射
        toc_anchor_map = self._build_toc_anchor_map(metadata)

        ordered = sorted(chapters, key=lambda c: c.get("order", 0))
        for idx, chapter in enumerate(ordered, start=1):
            chapter.setdefault("chapterId", f"S{idx}")

            # 优先级：1. 目录配置的anchor 2. 章节自带的anchor 3. 默认anchor
            chapter_id = chapter.get("chapterId")
            anchor = (
                toc_anchor_map.get(chapter_id) or
                chapter.get("anchor") or
                f"section-{idx}"
            )
            chapter["anchor"] = self._ensure_unique_anchor(anchor)
            chapter.setdefault("order", idx * 10)
            if chapter.get("errorPlaceholder"):
                self._ensure_heading_block(chapter)

        document = {
            "version": IR_VERSION,
            "reportId": report_id,
            "metadata": {
                **metadata,
                "generatedAt": metadata.get("generatedAt")