Contract Review Pro

"""Package marker for contract-review scripts."""

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
合同智能分析模块

自动提取合同文本,识别合同类型和关键条款位置,
为批注提供智能搜索关键词或行号定位。
"""

import subprocess
import re
from pathlib import Path
from typing import Dict, List, Optional, Tuple
from defusedxml import minidom


class ContractAnalyzer:
    """合同智能分析器"""

    def __init__(self, contract_path: str):
        """
        初始化分析器

        Args:
            contract_path: 合同文件路径
        """
        self.contract_path = Path(contract_path)
        self.full_text = ""
        self.paragraphs = []
        self.contract_type = "unknown"
        self.key_clauses = {}

    def extract_text(self) -> str:
        """
        使用pandoc提取合同纯文本

        Returns:
            str: 合同的纯文本内容
        """
        try:
            result = subprocess.run(
                ["pandoc", "-f", "docx", "-t", "plain", str(self.contract_path)],
                capture_output=True,
                text=True,
                check=True,
                timeout=30
            )
            self.full_text = result.stdout
            return self.full_text
        except subprocess.CalledProcessError as e:
            print(f"⚠️  pandoc提取失败: {e}")
            return ""
        except subprocess.TimeoutExpired:
            print(f"⚠️  pandoc提取超时")
            return ""
        except FileNotFoundError:
            print(f"⚠️  未找到pandoc命令,请先安装: sudo apt-get install pandoc")
            return ""

    def extract_paragraphs_with_line_numbers(self) -> List[Tuple[int, str]]:
        """
        提取段落文本及对应的行号

        Returns:
            List[Tuple[int, str]]: [(行号, 段落文本), ...]列表
        """
        if not self.full_text:
            self.extract_text()

        lines = self.full_text.split('\n')
        self.paragraphs = []

        for i, line in enumerate(lines, 1):
            stripped = line.strip()
            if stripped:  # 跳过空行
                self.paragraphs.append((i, stripped))

        return self.paragraphs

    def identify_contract_type(self) -> str:
        """
        识别合同类型

        Returns:
            str: 合同类型 (training/purchase/service/cooperation/unknown)
        """
        if not self.full_text:
            self.extract_text()

        text_lower = self.full_text.lower()

        # 关键词匹配规则
        type_keywords = {
            "training": ["培训", "训练", "课程", "讲师", "学员"],
            "purchase": ["采购", "购销", "买方", "卖方", "订购", "货物"],
            "service": ["服务", "提供", "服务费", "维护", "技术支持"],
            "cooperation": ["合作", "推广", "联合", "协议", "框架"],
        }

        # 统计每种类型的关键词出现次数
        type_scores = {}
        for contract_type, keywords in type_keywords.items():
            score = sum(1 for keyword in keywords if keyword in text_lower)
            if score > 0:
                type_scores[contract_type] = score

        # 返回得分最高的类型
        if type_scores:
            self.contract_type = max(type_scores, key=type_scores.get)
        else:
            self.contract_type = "unknown"

        return self.contract_type

    def find_clause_location(self, search_keywords: List[str]) -> Optional[int]:
        """
        查找包含指定关键词的条款所在行号

        Args:
            search_keywords: 搜索关键词列表

        Returns:
            Optional[int]: 找到的行号,未找到返回None
        """
        if not self.paragraphs:
            self.extract_paragraphs_with_line_numbers()

        # 遍历所有段落,查找包含任一关键词的段落
        for line_num, paragraph in self.paragraphs:
            for keyword in search_keywords:
                if keyword in paragraph:
                    return line_num

        return None

    def analyze_common_fields(self) -> Dict[str, List[str]]:
        """
        分析合同中的常见字段,返回多个可能的搜索关键词

        支持中英文标点符号变体

        Returns:
            Dict[str, List[str]]: 字段名到关键词列表的映射
        """
        if not self.full_text:
            self.extract_text()

        # 定义常见字段,支持中英文标点符号变体
        common_fields = {
            "合同编号": [
                "合同编号:", "协议编号:", "合同号:", "协议号:", "编号:",
                "合同编号：", "协议编号：", "合同号：", "协议号：", "编号：",  # 中文冒号
            ],
            "合同金额": [
                "合同总金额", "协议总金额", "合同价款", "协议价款", "费用总额", "总金额",
                "¥", "人民币", "元",  # 金额符号
            ],
            "签署日期": [
                "签署日期", "签订日期", "签约日期", "签署时间", "生效日期",
                "签署日期：", "签订日期：",  # 中文冒号
            ],
            "甲方": [
                "甲方:", "甲方（", "需方:", "买方:", "委托方:",
                "甲方：", "甲方（", "需方：",  # 中文冒号
            ],
            "乙方": [
                "乙方:", "乙方（", "供方:", "卖方:", "服务方:",
                "乙方：", "乙方（", "供方：",  # 中文冒号
            ],
            "违约责任": [
                "违约责任", "违约金", "赔偿责任", "赔偿条款",
                "违约责任：", "违约金：",  # 中文冒号
            ],
            "争议解决": [
                "争议解决", "纠纷解决", "管辖", "诉讼", "仲裁",
                "争议解决：",  # 中文冒号
            ],
            "保密条款": [
                "保密", "商业秘密", "保密义务", "保密条款",
                "保密：",  # 中文冒号
            ],
        }

        # 检查每个字段在合同中的实际表述
        found_fields = {}
        for field_name, keywords in common_fields.items():
            found_keywords = []
            for keyword in keywords:
                if keyword in self.full_text:
                    found_keywords.append(keyword)
            if found_keywords:
                found_fields[field_name] = found_keywords

        return found_fields

    def generate_smart_search_keywords(self) -> Dict[str, List[str]]:
        """
        生成智能搜索关键词

        基于合同内容分析,为常见审核点提供最合适的搜索关键词。

        Returns:
            Dict[str, List[str]]: 审核点到关键词列表的映射
        """
        # 先分析常见字段
        common_fields = self.analyze_common_fields()

        # 生成智能搜索关键词映射
        smart_keywords = {
            "合同编号为空": common_fields.get("合同编号", ["合同编号:", "协议编号:"]),
            "金额表述不一致": common_fields.get("合同金额", ["合同总金额", "总金额", "¥"]),
            "签署日期": common_fields.get("签署日期", ["签署日期", "签订日期"]),
            "甲方信息": common_fields.get("甲方", ["甲方:"]),
            "乙方信息": common_fields.get("乙方", ["乙方:"]),
            "违约责任条款": common_fields.get("违约责任", ["违约责任", "违约金"]),
            "争议解决条款": common_fields.get("争议解决", ["争议解决", "协商"]),
            "保密条款": common_fields.get("保密条款", ["保密", "商业秘密"]),
        }

        return smart_keywords

    def get_contract_summary(self) -> Dict:
        """
        获取合同摘要信息

        Returns:
            Dict: 包含合同类型、关键词字段等信息的字典
        """
        if not self.full_text:
            self.extract_text()

        if not self.paragraphs:
            self.extract_paragraphs_with_line_numbers()

        if self.contract_type == "unknown":
            self.identify_contract_type()

        smart_keywords = self.generate_smart_search_keywords()

        return {
            "contract_type": self.contract_type,
            "total_paragraphs": len(self.paragraphs),
            "text_length": len(self.full_text),
            "smart_keywords": smart_keywords,
            "found_fields": len(smart_keywords)
        }


def demo():
    """演示合同分析功能"""
    # 示例用法
    analyzer = ContractAnalyzer("合同.docx")

    # 1. 提取文本
    text = analyzer.extract_text()
    print(f"提取文本长度: {len(text)}")

    # 2. 识别合同类型
    contract_type = analyzer.identify_contract_type()
    print(f"合同类型: {contract_type}")

    # 3. 分析常见字段
    common_fields = analyzer.analyze_common_fields()
    print(f"发现字段: {list(common_fields.keys())}")

    # 4. 生成智能搜索关键词
    smart_keywords = analyzer.generate_smart_search_keywords()
    print("智能搜索关键词:")
    for field, keywords in smart_keywords.items():
        print(f"  {field}: {keywords}")

    # 5. 获取合同摘要
    summary = analyzer.get_contract_summary()
    print(f"\n合同摘要: {summary}")


if __name__ == "__main__":
    demo()

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Minimal DOCX comment editor for contract review.
"""

from __future__ import annotations

import html
from datetime import datetime, timezone
from pathlib import Path
from typing import Dict, List, Optional

from .utilities import XMLEditor

COMMENTS_CONTENT_TYPE = (
    "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml"
)
COMMENTS_REL_TYPE = (
    "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments"
)


class Document:
    """Edit an unpacked .docx directory to insert comments."""

    def __init__(self, unpacked_path: str | Path, author: str = "Contract Review Assistant", initials: str = "CR"):
        self.unpacked_path = Path(unpacked_path)
        if not self.unpacked_path.exists():
            raise FileNotFoundError(f"Unpacked path not found: {self.unpacked_path}")

        self.word_path = self.unpacked_path / "word"
        self.document_path = self.word_path / "document.xml"
        self.comments_path = self.word_path / "comments.xml"
        self.rels_path = self.word_path / "_rels" / "document.xml.rels"
        self.content_types_path = self.unpacked_path / "[Content_Types].xml"

        self.author = author
        self.initials = initials
        self._editors: Dict[str, XMLEditor] = {}

        self._ensure_comments_part()
        self.next_comment_id = self._get_next_comment_id()

    def __getitem__(self, xml_path: str) -> XMLEditor:
        if xml_path not in self._editors:
            target = self.unpacked_path / xml_path
            self._editors[xml_path] = XMLEditor(target)
        return self._editors[xml_path]

    def save(self, validate: bool = False) -> None:
        _ = validate
        for editor in self._editors.values():
            editor.save()

    def get_paragraph_text(self, paragraph) -> str:
        text_parts = []
        for run in paragraph.getElementsByTagName("w:r"):
            for text_node in run.getElementsByTagName("w:t"):
                if text_node.firstChild:
                    text_parts.append(text_node.firstChild.nodeValue)
        return "".join(text_parts)

    def find_paragraph_by_text(self, search_text, allow_fallback: bool = True):
        editor = self["word/document.xml"]
        paragraphs = editor.dom.getElementsByTagName("w:p")
        search_keywords = [search_text] if isinstance(search_text, str) else search_text

        for keyword in search_keywords:
            for para in paragraphs:
                if keyword in self.get_paragraph_text(para):
                    return para

        if not allow_fallback:
            raise ValueError(f"Paragraph not found for: {search_text}")

        for para in paragraphs[:20]:
            if self.get_paragraph_text(para).strip():
                return para
        return paragraphs[0] if paragraphs else None

    def add_comment(self, start, end, text: str, risk_level: str = "中风险") -> int:
        _ = end
        para = self._get_paragraph_node(start)
        if para is None:
            raise ValueError("Comment target paragraph not found")

        comment_id = self.next_comment_id
        self.next_comment_id += 1

        reviewer = self._get_reviewer_by_risk_level(risk_level)
        author = reviewer["author"]
        initials = reviewer["initials"]
        timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

        self._insert_comment_range(para, comment_id)
        self._append_comment_reference(para, comment_id)
        self._append_comment_entry(comment_id, author, initials, timestamp, text)

        return comment_id

    def verify_comments(self) -> dict:
        result = {"total": 0, "found": 0, "missing": 0, "comment_list": []}
        if not self.comments_path.exists():
            return result

        comments_editor = self["word/comments.xml"]
        comment_nodes = _find_by_local_name(comments_editor.dom, "comment")
        result["total"] = len(comment_nodes)

        document_editor = self["word/document.xml"]
        range_nodes = _find_by_local_name(document_editor.dom, "commentRangeStart")
        result["found"] = len(range_nodes)
        result["missing"] = max(result["total"] - result["found"], 0)

        for node in comment_nodes:
            comment_id = node.getAttribute("w:id") or node.getAttribute("id")
            author = node.getAttribute("w:author") or node.getAttribute("author")
            preview = _extract_first_text(node)
            result["comment_list"].append({
                "id": comment_id,
                "author": author,
                "preview": preview,
            })

        return result

    def _ensure_comments_part(self) -> None:
        self._ensure_comments_xml()
        self._ensure_comments_relationship()
        self._ensure_comments_content_type()

    def _ensure_comments_xml(self) -> None:
        if self.comments_path.exists():
            return
        xml = (
            "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>"
            "<w:comments xmlns:w=\"http://schemas.openxmlformats.org/wordprocessingml/2006/main\"/>"
        )
        self.comments_path.write_text(xml, encoding="utf-8")

    def _ensure_comments_relationship(self) -> None:
        if not self.rels_path.exists():
            raise FileNotFoundError(f"Missing rels file: {self.rels_path}")

        rels_editor = self["word/_rels/document.xml.rels"]
        root = rels_editor.dom.documentElement

        for rel in _find_by_local_name(rels_editor.dom, "Relationship"):
            if rel.getAttribute("Type") == COMMENTS_REL_TYPE:
                return

        next_id = _next_relationship_id(rels_editor.dom)
        rel = rels_editor.dom.createElement("Relationship")
        rel.setAttribute("Id", next_id)
        rel.setAttribute("Type", COMMENTS_REL_TYPE)
        rel.setAttribute("Target", "comments.xml")
        root.appendChild(rel)

    def _ensure_comments_content_type(self) -> None:
        if not self.content_types_path.exists():
            raise FileNotFoundError(f"Missing content types file: {self.content_types_path}")

        types_editor = self["[Content_Types].xml"]
        root = types_editor.dom.documentElement
        for override in _find_by_local_name(types_editor.dom, "Override"):
            if override.getAttribute("PartName") == "/word/comments.xml":
                return

        override = types_editor.dom.createElement("Override")
        override.setAttribute("PartName", "/word/comments.xml")
        override.setAttribute("ContentType", COMMENTS_CONTENT_TYPE)
        root.appendChild(override)

    def _get_next_comment_id(self) -> int:
        if not self.comments_path.exists():
            return 0
        comments_editor = self["word/comments.xml"]
        max_id = -1
        for node in _find_by_local_name(comments_editor.dom, "comment"):
            raw = node.getAttribute("w:id") or node.getAttribute("id")
            if raw:
                try:
                    max_id = max(max_id, int(raw))
                except ValueError:
                    continue
        return max_id + 1

    def _insert_comment_range(self, paragraph, comment_id: int) -> None:
        doc = self["word/document.xml"].dom
        start_elem = doc.createElement("w:commentRangeStart")
        start_elem.setAttribute("w:id", str(comment_id))

        first_elem = _first_element_child(paragraph)
        if first_elem is not None:
            paragraph.insertBefore(start_elem, first_elem)
        else:
            paragraph.appendChild(start_elem)

    def _append_comment_reference(self, paragraph, comment_id: int) -> None:
        doc = self["word/document.xml"].dom
        end_elem = doc.createElement("w:commentRangeEnd")
        end_elem.setAttribute("w:id", str(comment_id))
        paragraph.appendChild(end_elem)

        run = doc.createElement("w:r")
        ref = doc.createElement("w:commentReference")
        ref.setAttribute("w:id", str(comment_id))
        run.appendChild(ref)
        paragraph.appendChild(run)

    def _append_comment_entry(self, comment_id: int, author: str, initials: str, timestamp: str, text: str) -> None:
        comments_editor = self["word/comments.xml"]
        root = comments_editor.dom.documentElement

        comment = comments_editor.dom.createElement("w:comment")
        comment.setAttribute("w:id", str(comment_id))
        comment.setAttribute("w:author", author)
        comment.setAttribute("w:initials", initials)
        comment.setAttribute("w:date", timestamp)

        lines = text.splitlines() or [""]
        for line in lines:
            para = comments_editor.dom.createElement("w:p")
            run = comments_editor.dom.createElement("w:r")
            text_elem = comments_editor.dom.createElement("w:t")
            if _needs_space_preserve(line):
                text_elem.setAttribute("xml:space", "preserve")
            text_elem.appendChild(comments_editor.dom.createTextNode(html.escape(line)))
            run.appendChild(text_elem)
            para.appendChild(run)
            comment.appendChild(para)

        root.appendChild(comment)

    def _get_reviewer_by_risk_level(self, risk_level: str) -> dict:
        risk_reviewers = {
            "高风险": {"author": "高风险", "initials": "高风险"},
            "中风险": {"author": "中风险", "initials": "中风险"},
            "低风险": {"author": "低风险", "initials": "低风险"},
        }
        english_reviewers = {
            "high": {"author": "High Risk", "initials": "H"},
            "medium": {"author": "Medium Risk", "initials": "M"},
            "low": {"author": "Low Risk", "initials": "L"},
        }

        if not risk_level:
            return risk_reviewers["中风险"]
        if risk_level in risk_reviewers:
            return risk_reviewers[risk_level]

        normalized = risk_level.strip().lower().replace("-", " ")
        normalized = " ".join(normalized.split()).replace(" risk", "")
        if normalized in english_reviewers:
            return english_reviewers[normalized]
        return risk_reviewers["中风险"]

    def _get_paragraph_node(self, node):
        current = node
        while current is not None:
            if getattr(current, "tagName", None) == "w:p":
                return current
            current = current.parentNode
        return None


def _needs_space_preserve(text: str) -> bool:
    if text.startswith(" ") or text.endswith(" "):
        return True
    if "  " in text:
        return True
    return False


def _first_element_child(node):
    child = node.firstChild
    while child is not None:
        if child.nodeType == child.ELEMENT_NODE:
            return child
        child = child.nextSibling
    return None


def _find_by_local_name(dom, local: str) -> List:
    matches = []
    for node in dom.getElementsByTagName("*"):
        if node.tagName.split(":")[-1] == local:
            matches.append(node)
    return matches


def _extract_first_text(node) -> str:
    for text_node in node.getElementsByTagName("w:t"):
        if text_node.firstChild:
            return text_node.firstChild.nodeValue
    return ""


def _next_relationship_id(dom) -> str:
    max_id = 0
    for rel in _find_by_local_name(dom, "Relationship"):
        rid = rel.getAttribute("Id")
        if rid.startswith("rId"):
            try:
                max_id = max(max_id, int(rid[3:]))
            except ValueError:
                continue
    return f"rId{max_id + 1}"

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
错误处理和用户反馈工具
Error Handling and User Feedback Utilities

提供统一的错误处理、日志记录和用户反馈功能。
"""

import sys
import traceback
from typing import List, Dict, Optional
from datetime import datetime
from pathlib import Path


# ==================== 自定义异常类 ====================

class ReviewError(Exception):
    """合同审核基础异常类"""
    pass


class CommentNotFoundError(ReviewError):
    """批注目标未找到错误"""
    pass


class DocumentValidationError(ReviewError):
    """文档验证失败错误"""
    pass


class PythonVersionError(ReviewError):
    """Python 版本不兼容错误"""
    pass


class UnpackError(ReviewError):
    """文档解包失败错误"""
    pass


class PackError(ReviewError):
    """文档打包失败错误"""
    pass


# ==================== 版本检查 ====================

def check_python_version(min_version: tuple = (3, 9),
                        recommended_version: tuple = (3, 10)) -> None:
    """
    检查 Python 版本是否满足要求

    Args:
        min_version: 最低版本要求 (默认 3.9)
        recommended_version: 推荐版本 (默认 3.10)

    Raises:
        PythonVersionError: 如果版本低于最低要求

    Example:
        >>> check_python_version()  # 默认要求 3.9+
        >>> check_python_version((3, 10))  # 要求 3.10+
    """
    current = (sys.version_info.major, sys.version_info.minor)

    if current < min_version:
        raise PythonVersionError(
            f"Python {'.'.join(map(str, min_version))}+ required, "
            f"current: {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
        )

    if current < recommended_version:
        import warnings
        warnings.warn(
            f"Python {'.'.join(map(str, recommended_version))}+ recommended for best compatibility. "
            f"Current: {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
            UserWarning
        )


# ==================== 错误格式化 ====================

def format_error_summary(errors: List[Dict]) -> str:
    """
    格式化错误摘要为可读文本

    Args:
        errors: 错误列表,每个错误包含 type, location, message, suggestion 等字段

    Returns:
        str: 格式化的错误摘要文本

    Example:
        >>> errors = [
        ...     {"type": "文本一致性", "location": "第10行", "message": "金额不一致"},
        ...     {"type": "合同标的", "location": "第20行", "message": "数量不明确"}
        ... ]
        >>> print(format_error_summary(errors))
    """
    if not errors:
        return "✓ 无错误"

    lines = []
    lines.append(f"✗ 发现 {len(errors)} 个错误:\n")

    for i, error in enumerate(errors, 1):
        lines.append(f"\n{i}. {error.get('type', 'Unknown Error')}")
        lines.append(f"   位置: {error.get('location', 'N/A')}")
        lines.append(f"   原因: {error.get('message', 'N/A')}")

        if 'suggestion' in error:
            lines.append(f"   建议: {error['suggestion']}")

        if 'risk_level' in error:
            lines.append(f"   风险等级: {error['risk_level']}")

    return '\n'.join(lines)


# ==================== 批注批处理日志记录器 ====================

class CommentBatchLogger:
    """
    批注批处理日志记录器

    记录批注添加过程中的成功、失败和警告,
    并生成详细的执行报告。

    Attributes:
        successful: 成功添加的批注列表
        failed: 失败的批注列表
        warnings: 警告列表
        start_time: 开始时间

    Example:
        >>> logger = CommentBatchLogger()
        >>> try:
        ...     logger.log_success(1, "合同总价")
        ... except Exception as e:
        ...     logger.log_failure("合同总价", e)
        >>> print(logger.generate_summary())
    """

    def __init__(self):
        """初始化日志记录器"""
        self.successful = []
        self.failed = []
        self.warnings = []
        self.start_time = datetime.now()

    def log_success(self, comment_id: int, search_text: str, preview: str = ""):
        """
        记录成功添加的批注

        Args:
            comment_id: 批注ID
            search_text: 搜索文本
            preview: 批注内容预览(可选)
        """
        self.successful.append({
            'id': comment_id,
            'search': search_text,
            'preview': preview,
            'timestamp': datetime.now()
        })

    def log_failure(self, search_text: str, error: Exception):
        """
        记录失败的批注

        Args:
            search_text: 搜索文本
            error: 异常对象
        """
        self.failed.append({
            'search': search_text,
            'error': str(error),
            'error_type': type(error).__name__,
            'traceback': traceback.format_exc(),
            'timestamp': datetime.now()
        })

    def log_warning(self, message: str, details: str = ""):
        """
        记录警告

        Args:
            message: 警告消息
            details: 详细信息(可选)
        """
        self.warnings.append({
            'message': message,
            'details': details,
            'timestamp': datetime.now()
        })

    def generate_summary(self) -> str:
        """
        生成执行摘要

        Returns:
            str: 格式化的摘要文本
        """
        duration = (datetime.now() - self.start_time).total_seconds()

        lines = []
        lines.append("=" * 60)
        lines.append("批注添加摘要")
        lines.append("=" * 60)
        lines.append(f"\n执行时间: {duration:.2f} 秒")
        lines.append(f"成功: {len(self.successful)} 个")
        lines.append(f"失败: {len(self.failed)} 个")
        lines.append(f"警告: {len(self.warnings)} 个")

        if self.failed:
            lines.append("\n失败详情:")
            lines.append("-" * 60)
            for i, fail in enumerate(self.failed, 1):
                lines.append(f"\n{i}. 搜索文本: {fail['search'][:50]}")
                lines.append(f"   错误类型: {fail['error_type']}")
                lines.append(f"   错误: {fail['error'][:100]}")

        if self.warnings:
            lines.append("\n警告:")
            lines.append("-" * 60)
            for i, warning in enumerate(self.warnings, 1):
                lines.append(f"{i}. {warning['message']}")
                if warning['details']:
                    lines.append(f"   详情: {warning['details'][:80]}")

        lines.append("\n" + "=" * 60)
        return '\n'.join(lines)

    def save_to_file(self, filepath: str):
        """
        保存详细日志到文件

        Args:
            filepath: 日志文件路径
        """
        with open(filepath, 'w', encoding='utf-8') as f:
            # 写入摘要
            f.write(self.generate_summary())
            f.write("\n\n详细错误追踪:\n")
            f.write("=" * 60 + "\n\n")

            # 写入每个失败的详细信息
            for i, fail in enumerate(self.failed, 1):
                f.write(f"错误 #{i}:\n")
                f.write(f"搜索文本: {fail['search']}\n")
                f.write(f"时间: {fail['timestamp'].strftime('%Y-%m-%d %H:%M:%S')}\n")
                f.write(f"错误类型: {fail['error_type']}\n")
                f.write(f"错误信息:\n{fail['traceback']}\n")
                f.write("\n" + "-" * 60 + "\n\n")

            # 写入警告详情
            if self.warnings:
                f.write("\n警告详情:\n")
                f.write("=" * 60 + "\n\n")
                for i, warning in enumerate(self.warnings, 1):
                    f.write(f"警告 #{i}:\n")
                    f.write(f"时间: {warning['timestamp'].strftime('%Y-%m-%d %H:%M:%S')}\n")
                    f.write(f"消息: {warning['message']}\n")
                    if warning['details']:
                        f.write(f"详情: {warning['details']}\n")
                    f.write("\n")

    def get_statistics(self) -> Dict:
        """
        获取统计信息

        Returns:
            dict: 包含 total, successful, failed, warnings 等统计
        """
        total = len(self.successful) + len(self.failed)
        success_rate = (len(self.successful) / total * 100) if total > 0 else 0

        return {
            'total': total,
            'successful': len(self.successful),
            'failed': len(self.failed),
            'warnings': len(self.warnings),
            'success_rate': success_rate,
            'duration_seconds': (datetime.now() - self.start_time).total_seconds()
        }


# ==================== 审核报告生成器 ====================

class ReviewReportGenerator:
    """
    审核报告生成器

    生成结构化的审核报告,包括:
    - 基本信息
    - 统计数据
    - 详细问题列表
    - 验证结果
    - 总体评价

    Example:
        >>> generator = ReviewReportGenerator()
        >>> generator.add_basic_info(contract="合同.docx", reviewer="张三")
        >>> generator.add_issue(type="文本一致性", level="高风险", ...)
        >>> generator.save("report.txt")
    """

    def __init__(self):
        """初始化报告生成器"""
        self.basic_info = {}
        self.issues = {
            'high': [],
            'medium': [],
            'low': []
        }
        self.statistics = {}
        self.verification = {}

    def add_basic_info(self, contract: str, reviewer: str, date: str = None):
        """
        添加基本信息

        Args:
            contract: 合同文档路径
            reviewer: 审核人
            date: 审核日期(默认为当前时间)
        """
        self.basic_info = {
            'contract': contract,
            'reviewer': reviewer,
            'date': date or datetime.now().strftime('%Y-%m-%d %H:%M:%S')
        }

    def add_issue(self, issue_type: str, level: str, location: str,
                  reason: str, suggestion: str, original_text: str = ""):
        """
        添加审核问题

        Args:
            issue_type: 问题类型
            level: 风险等级 (高风险/中风险/低风险)
            location: 所在位置
            reason: 风险原因
            suggestion: 修订建议
            original_text: 原文内容(可选)
        """
        issue = {
            'type': issue_type,
            'location': location,
            'reason': reason,
            'suggestion': suggestion,
            'original_text': original_text
        }

        # 根据风险等级分类
        level_key = level.replace('风险', '').replace(' ', '').lower()
        if '高' in level or level_key == 'high':
            self.issues['high'].append(issue)
        elif '中' in level or level_key == 'medium':
            self.issues['medium'].append(issue)
        else:
            self.issues['low'].append(issue)

    def add_statistics(self, total_comments: int, successful: int, failed: int):
        """
        添加统计数据

        Args:
            total_comments: 总批注数
            successful: 成功添加数
            failed: 失败数
        """
        self.statistics = {
            'total': total_comments,
            'successful': successful,
            'failed': failed,
            'success_rate': (successful / total_comments * 100) if total_comments > 0 else 0
        }

    def add_verification(self, total: int, found: int, missing: int):
        """
        添加验证结果

        Args:
            total: 批注总数
            found: 找到的引用数
            missing: 缺失的引用数
        """
        self.verification = {
            'total': total,
            'found': found,
            'missing': missing
        }

    def generate(self) -> str:
        """
        生成报告文本

        Returns:
            str: 完整的报告文本
        """
        lines = []

        # 标题
        lines.append("=" * 60)
        lines.append("合同审核报告")
        lines.append("=" * 60)
        lines.append("")

        # 基本信息
        lines.append("一、基本信息")
        lines.append("-" * 60)
        lines.append(f"合同文档: {self.basic_info.get('contract', 'N/A')}")
        lines.append(f"审核人: {self.basic_info.get('reviewer', 'N/A')}")
        lines.append(f"审核日期: {self.basic_info.get('date', 'N/A')}")
        lines.append("")

        # 统计数据
        if self.statistics:
            lines.append("二、统计数据")
            lines.append("-" * 60)
            lines.append(f"总批注数: {self.statistics['total']}")
            lines.append(f"成功添加: {self.statistics['successful']}")
            lines.append(f"添加失败: {self.statistics['failed']}")
            lines.append(f"成功率: {self.statistics['success_rate']:.1f}%")
            lines.append("")

        # 验证结果
        if self.verification:
            lines.append("三、验证结果")
            lines.append("-" * 60)
            lines.append(f"批注总数: {self.verification['total']}")
            lines.append(f"文档引用: {self.verification['found']}")
            lines.append(f"缺失引用: {self.verification['missing']}")
            lines.append("")

        # 问题列表(按风险等级分组)
        all_issues = []
        if self.issues['high']:
            all_issues.extend([(i, '🔴 高风险') for i in self.issues['high']])
        if self.issues['medium']:
            all_issues.extend([(i, '🟡 中风险') for i in self.issues['medium']])
        if self.issues['low']:
            all_issues.extend([(i, '🔵 低风险') for i in self.issues['low']])

        if all_issues:
            lines.append("四、审核问题列表")
            lines.append("-" * 60)
            lines.append("")

            for idx, (issue, risk_label) in enumerate(all_issues, 1):
                lines.append(f"{idx}. 【问题类型】{issue['type']}")
                lines.append(f"   【风险等级】{risk_label}")
                lines.append(f"   【所在位置】{issue['location']}")
                lines.append(f"   【风险原因】{issue['reason']}")
                lines.append(f"   【修订建议】{issue['suggestion']}")
                if issue.get('original_text'):
                    lines.append(f"   【原文内容】{issue['original_text'][:80]}...")
                lines.append("")

        # 总体评价
        lines.append("=" * 60)
        lines.append("总体评价")
        lines.append("=" * 60)
        high_count = len(self.issues['high'])
        medium_count = len(self.issues['medium'])
        low_count = len(self.issues['low'])

        if high_count > 0:
            lines.append(f"\n发现 {high_count} 个高风险问题,建议优先修改。")
        if medium_count > 0:
            lines.append(f"发现 {medium_count} 个中风险问题,建议仔细评估。")
        if low_count > 0:
            lines.append(f"发现 {low_count} 个低风险问题,可在有时间时优化。")

        if high_count == 0 and medium_count == 0:
            lines.append("\n✓ 合同质量良好,仅发现少量低风险问题。")

        lines.append("")
        lines.append("=" * 60)

        return '\n'.join(lines)

    def save(self, filepath: str):
        """
        保存报告到文件

        Args:
            filepath: 报告文件路径
        """
        report_text = self.generate()
        with open(filepath, 'w', encoding='utf-8') as f:
            f.write(report_text)


# ==================== 使用示例 ====================

if __name__ == "__main__":
    print("错误处理和用户反馈工具")
    print("=" * 60)
    print()
    print("功能模块:")
    print("1. 自定义异常类: ReviewError, CommentNotFoundError 等")
    print("2. 版本检查: check_python_version()")
    print("3. 错误格式化: format_error_summary()")
    print("4. 批注日志: CommentBatchLogger")
    print("5. 报告生成: ReviewReportGenerator")
    print()
    print("使用示例:")
    print()
    print("from scripts.error_handling import CommentBatchLogger")
    print()
    print("logger = CommentBatchLogger()")
    print("logger.log_success(1, '合同总价', '金额不一致')")
    print("logger.log_failure('培训时间', Exception('未找到'))")
    print("print(logger.generate_summary())")
    print("logger.save_to_file('review_log.txt')")

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Render Mermaid flowcharts to image files via mermaid-cli (mmdc).
"""

from __future__ import annotations

import shutil
import subprocess
import json
import os
import tempfile
import re
from pathlib import Path
from typing import Optional, Tuple


def normalize_mermaid_code(code: str) -> str:
    """
    Normalize Mermaid code by stripping code fences and ensuring a trailing newline.
    """
    cleaned = code.strip()
    if cleaned.startswith("```"):
        lines = cleaned.splitlines()
        if len(lines) >= 2 and lines[-1].strip().startswith("```"):
            cleaned = "\n".join(lines[1:-1]).strip()
    if not cleaned.endswith("\n"):
        cleaned += "\n"
    return cleaned


def write_mermaid_file(code: str, output_dir: Path, filename: str) -> Path:
    """
    Write Mermaid code to a .mmd file in output_dir.
    """
    output_dir = Path(output_dir)
    output_dir.mkdir(parents=True, exist_ok=True)
    mmd_path = output_dir / filename
    mmd_path.write_text(code, encoding="utf-8")
    return mmd_path


def render_mermaid_file(
    mmd_path: Path,
    image_path: Path,
    theme: str = "default",
    background_color: str = "white",
    mmdc_path: Optional[str] = None,
    scale: float = 2,
    width: Optional[int] = None,
    height: Optional[int] = None,
    puppeteer_config_path: Optional[str] = None,
) -> None:
    """
    Render a Mermaid .mmd file to an image using mermaid-cli (mmdc).
    """
    mmdc_path = mmdc_path or shutil.which("mmdc")
    if not mmdc_path:
        raise FileNotFoundError(
            "mmdc not found in PATH. Install @mermaid-js/mermaid-cli to render Mermaid."
        )

    def build_cmd(input_path: Path, config_path: Optional[Path]) -> list[str]:
        cmd = [mmdc_path, "-i", str(input_path), "-o", str(image_path)]
        if theme:
            cmd += ["-t", theme]
        if background_color:
            cmd += ["-b", background_color]
        if scale and scale != 1:
            cmd += ["-s", str(scale)]
        if width:
            cmd += ["-w", str(width)]
        if height:
            cmd += ["-H", str(height)]
        if config_path:
            cmd += ["-p", str(config_path)]
        return cmd

    config_path = Path(puppeteer_config_path) if puppeteer_config_path else None
    created_config = False
    temp_user_data_dir: Optional[Path] = None
    last_error: Optional[subprocess.CalledProcessError] = None

    try:
        try:
            subprocess.run(build_cmd(mmd_path, config_path), check=True)
            return
        except subprocess.CalledProcessError as exc:
            last_error = exc

        if config_path is None:
            chrome_path = os.environ.get("PUPPETEER_EXECUTABLE_PATH") or _find_chrome_executable()
            if not chrome_path:
                raise last_error
            config_path, temp_user_data_dir = _write_puppeteer_config(chrome_path)
            created_config = True

        try:
            subprocess.run(build_cmd(mmd_path, config_path), check=True)
            return
        except subprocess.CalledProcessError as exc:
            last_error = exc

        try:
            original = mmd_path.read_text(encoding="utf-8")
        except Exception:
            raise last_error

        sanitized = _sanitize_mermaid_code_for_render(original)
        if sanitized == original:
            raise last_error

        sanitized_path = _write_temp_mmd(sanitized, mmd_path)
        try:
            subprocess.run(build_cmd(sanitized_path, config_path), check=True)
            return
        except subprocess.CalledProcessError as exc:
            last_error = exc
            raise last_error
        finally:
            try:
                sanitized_path.unlink(missing_ok=True)
            except Exception:
                pass
    finally:
        if created_config:
            try:
                config_path.unlink(missing_ok=True)
            except Exception:
                pass
            if temp_user_data_dir:
                shutil.rmtree(temp_user_data_dir, ignore_errors=True)


def render_mermaid_code(
    code: str,
    output_dir: Path,
    mmd_filename: str,
    image_filename: str,
    theme: str = "default",
    background_color: str = "white",
    scale: float = 2,
    width: Optional[int] = None,
    height: Optional[int] = None,
    puppeteer_config_path: Optional[str] = None,
) -> Tuple[Path, Path]:
    """
    Write Mermaid code to .mmd and render to image.
    """
    normalized = normalize_mermaid_code(code)
    mmd_path = write_mermaid_file(normalized, output_dir, mmd_filename)
    image_path = Path(output_dir) / image_filename
    render_mermaid_file(
        mmd_path,
        image_path,
        theme=theme,
        background_color=background_color,
        scale=scale,
        width=width,
        height=height,
        puppeteer_config_path=puppeteer_config_path,
    )
    return mmd_path, image_path


def _find_chrome_executable() -> Optional[str]:
    """
    Best-effort Chrome/Chromium detection for Puppeteer fallback.
    """
    candidates = [
        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
        "/Applications/Chromium.app/Contents/MacOS/Chromium",
    ]
    for candidate in candidates:
        if Path(candidate).exists():
            return candidate
    return None


def _write_puppeteer_config(executable_path: str) -> tuple[Path, Path]:
    """
    Write a temporary Puppeteer config with safer sandbox args.
    """
    user_data_dir = Path(tempfile.mkdtemp(prefix="puppeteer-user-data-"))
    payload = {
        "executablePath": executable_path,
        "args": [
            "--no-sandbox",
            "--disable-setuid-sandbox",
            "--disable-dev-shm-usage",
            "--disable-crashpad",
            "--no-first-run",
            "--no-default-browser-check",
            f"--user-data-dir={user_data_dir}",
        ],
    }
    handle, path = tempfile.mkstemp(prefix="puppeteer-", suffix=".json")
    os.close(handle)
    config_path = Path(path)
    config_path.write_text(json.dumps(payload), encoding="utf-8")
    return config_path, user_data_dir


def _sanitize_mermaid_code_for_render(code: str) -> str:
    if "%" not in code and "％" not in code:
        return code
    replacement = "百分比" if _contains_cjk(code) else "percent"
    sanitized = code.replace("％", replacement).replace("%", replacement)
    sanitized = re.sub(r"(?<=\\d),(?=\\d)", "", sanitized)
    sanitized = sanitized.replace("(", " ").replace(")", " ")
    sanitized = re.sub(r"\\s{2,}", " ", sanitized)
    return sanitized


def _contains_cjk(text: str) -> bool:
    for char in text:
        if "\u4e00" <= char <= "\u9fff":
            return True
    return False


def _write_temp_mmd(code: str, source_path: Path) -> Path:
    handle, path = tempfile.mkstemp(
        prefix=f"{source_path.stem}-sanitized-",
        suffix=source_path.suffix,
    )
    os.close(handle)
    temp_path = Path(path)
    temp_path.write_text(code, encoding="utf-8")
    return temp_path

"""OOXML helpers for packing, unpacking, and lightweight validation."""

from .pack import pack_document
from .unpack import unpack_document

__all__ = ["pack_document", "unpack_document"]

#!/usr/bin/env python3
"""
Pack an unpacked Office directory into a .docx, .pptx, or .xlsx file.
"""

import argparse
import sys
import zipfile
from pathlib import Path

import defusedxml.ElementTree as ET


DOC_REQUIRED = {
    ".docx": ["[Content_Types].xml", "word/document.xml", "word/_rels/document.xml.rels"],
    ".pptx": ["[Content_Types].xml", "ppt/presentation.xml"],
    ".xlsx": ["[Content_Types].xml", "xl/workbook.xml"],
}


def pack_document(input_dir: str, output_file: str, validate: bool = False) -> bool:
    """
    Pack a directory into an Office file (.docx/.pptx/.xlsx).

    Args:
        input_dir: Path to unpacked Office document directory
        output_file: Path to output Office file
        validate: If True, run lightweight structural checks

    Returns:
        bool: True if successful, False if validation failed
    """
    input_path = Path(input_dir)
    output_path = Path(output_file)

    if not input_path.is_dir():
        raise ValueError(f"{input_dir} is not a directory")
    if output_path.suffix.lower() not in DOC_REQUIRED:
        raise ValueError(f"{output_file} must be a .docx, .pptx, or .xlsx file")

    output_path.parent.mkdir(parents=True, exist_ok=True)

    with zipfile.ZipFile(output_path, "w", zipfile.ZIP_DEFLATED) as archive:
        for item in sorted(input_path.rglob("*")):
            if item.is_file():
                archive.write(item, item.relative_to(input_path))

    if validate:
        if not validate_document(output_path):
            output_path.unlink(missing_ok=True)
            return False

    return True


def validate_document(doc_path: Path) -> bool:
    """Lightweight validation: required files exist and XML parses."""
    suffix = doc_path.suffix.lower()
    required = DOC_REQUIRED.get(suffix, [])

    try:
        with zipfile.ZipFile(doc_path, "r") as archive:
            names = set(archive.namelist())
            missing = [name for name in required if name not in names]
            if missing:
                print(f"Validation error: missing files: {missing}", file=sys.stderr)
                return False

            for name in required:
                if name.endswith((".xml", ".rels")):
                    with archive.open(name) as handle:
                        try:
                            ET.parse(handle)
                        except ET.ParseError as exc:
                            print(f"Validation error: invalid XML in {name}: {exc}", file=sys.stderr)
                            return False
    except zipfile.BadZipFile as exc:
        print(f"Validation error: invalid zip file: {exc}", file=sys.stderr)
        return False

    return True


def main() -> None:
    parser = argparse.ArgumentParser(description="Pack a directory into an Office file")
    parser.add_argument("input_directory", help="Unpacked Office document directory")
    parser.add_argument("output_file", help="Output Office file (.docx/.pptx/.xlsx)")
    parser.add_argument("--force", action="store_true", help="Skip validation")
    args = parser.parse_args()

    success = pack_document(
        args.input_directory,
        args.output_file,
        validate=not args.force,
    )

    if args.force:
        print("Warning: Skipped validation, file may be corrupt", file=sys.stderr)
    elif not success:
        print("Contents would produce an invalid file.", file=sys.stderr)
        print("Use --force to skip validation and pack anyway.", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Unpack Office files (.docx, .pptx, .xlsx) into a directory."""

import random
import sys
import zipfile
from pathlib import Path


def unpack_document(input_file: str, output_dir: str) -> None:
    """
    Unpack an Office file into a directory.

    Args:
        input_file: Path to the Office file (.docx, .pptx, .xlsx)
        output_dir: Directory to extract contents to
    """
    input_path = Path(input_file)
    output_path = Path(output_dir)

    if not input_path.is_file():
        raise FileNotFoundError(f"Input file not found: {input_file}")

    output_path.mkdir(parents=True, exist_ok=True)

    with zipfile.ZipFile(input_path, "r") as archive:
        archive.extractall(output_path)

    if input_path.suffix.lower() == ".docx":
        suggested_rsid = "".join(random.choices("0123456789ABCDEF", k=8))
        print(f"Suggested RSID for edit session: {suggested_rsid}")


if __name__ == "__main__":
    if len(sys.argv) != 3:
        raise SystemExit("Usage: python unpack.py <office_file> <output_dir>")
    unpack_document(sys.argv[1], sys.argv[2])

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""Run lightweight validation on unpacked Office documents."""

from __future__ import annotations

import argparse
from pathlib import Path
import sys

from validation import DOCXSchemaValidator, PPTXSchemaValidator, RedliningValidator


def _validators_for(ext: str):
    if ext == ".docx":
        return [DOCXSchemaValidator, RedliningValidator]
    if ext == ".pptx":
        return [PPTXSchemaValidator]
    return None


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description="Validate unpacked Office XML")
    parser.add_argument("unpacked_dir", help="Unpacked directory path")
    parser.add_argument("--original", required=True, help="Original file (.docx/.pptx/.xlsx)")
    parser.add_argument("-v", "--verbose", action="store_true", help="Verbose output")
    args = parser.parse_args(argv)

    unpacked_dir = Path(args.unpacked_dir)
    original_file = Path(args.original)

    if not unpacked_dir.is_dir():
        print(f"Error: {unpacked_dir} is not a directory")
        return 1
    if not original_file.is_file():
        print(f"Error: {original_file} is not a file")
        return 1

    validators = _validators_for(original_file.suffix.lower())
    if not validators:
        print(f"Error: validation not supported for {original_file.suffix}")
        return 1

    success = True
    for validator_cls in validators:
        validator = validator_cls(unpacked_dir, original_file, verbose=args.verbose)
        if not validator.validate():
            success = False

    if success:
        print("Validation completed successfully.")
    return 0 if success else 1


if __name__ == "__main__":
    sys.exit(main())

"""Validator exports for lightweight OOXML checks."""

from .docx import DOCXSchemaValidator as DocxValidator
from .pptx import PPTXSchemaValidator as PptxValidator
from .redlining import RedliningValidator as RedlineValidator

DOCXSchemaValidator = DocxValidator
PPTXSchemaValidator = PptxValidator
RedliningValidator = RedlineValidator

__all__ = [
    "DOCXSchemaValidator",
    "PPTXSchemaValidator",
    "RedliningValidator",
]

"""Lightweight validation helpers for Office XML documents."""

from __future__ import annotations

from pathlib import Path
from typing import Iterable

import defusedxml.ElementTree as ET


class BaseValidator:
    """Basic structural checks for unpacked Office documents."""

    required_files: Iterable[str] = ()

    def __init__(self, unpacked_dir: Path, original_file: Path, verbose: bool = False):
        self.unpacked_dir = Path(unpacked_dir)
        self.original_file = Path(original_file)
        self.verbose = verbose

    def validate(self) -> bool:
        if not self._check_required_files(self.required_files):
            return False
        return self._parse_xml_files(self.required_files)

    def _check_required_files(self, rel_paths: Iterable[str]) -> bool:
        missing = [p for p in rel_paths if not (self.unpacked_dir / p).exists()]
        if missing:
            if self.verbose:
                print(f"Missing required files: {missing}")
            return False
        return True

    def _parse_xml_files(self, rel_paths: Iterable[str]) -> bool:
        for rel_path in rel_paths:
            if not rel_path.endswith((".xml", ".rels")):
                continue
            file_path = self.unpacked_dir / rel_path
            try:
                ET.parse(file_path)
            except ET.ParseError as exc:
                if self.verbose:
                    print(f"Invalid XML in {rel_path}: {exc}")
                return False
        return True

"""Lightweight DOCX validation (structure + XML well-formedness)."""

from __future__ import annotations

from .base import BaseValidator


class DOCXSchemaValidator(BaseValidator):
    required_files = (
        "[Content_Types].xml",
        "word/document.xml",
        "word/_rels/document.xml.rels",
    )

"""Lightweight PPTX validation (structure + XML well-formedness)."""

from __future__ import annotations

from .base import BaseValidator


class PPTXSchemaValidator(BaseValidator):
    required_files = (
        "[Content_Types].xml",
        "ppt/presentation.xml",
    )

"""Minimal redlining validator placeholder."""

from __future__ import annotations

from .base import BaseValidator


class RedliningValidator(BaseValidator):
    required_files = (
        "word/document.xml",
    )

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Render comprehensive review opinion text to a styled DOCX document.
"""

from __future__ import annotations

import re
from pathlib import Path
from typing import List

from docx import Document
from docx.enum.text import WD_PARAGRAPH_ALIGNMENT, WD_LINE_SPACING
from docx.oxml import OxmlElement
from docx.oxml.ns import qn
from docx.shared import Pt


DEFAULT_LINE_SPACING = 1.3
NUMBERED_ITEM_PATTERN = re.compile(r"(?:^|[\s：:；;])(\d+[\.、](?!\d))")


def render_opinion_docx(
    opinion_text: str,
    output_path: Path,
    font_name: str = "仿宋",
    base_font_size: int = 12,
    line_spacing: float = DEFAULT_LINE_SPACING,
    add_title: bool = True,
    title_text: str = "综合审核意见",
) -> Path:
    """
    Render opinion text into a DOCX file.
    """
    output_path = Path(output_path)
    output_path.parent.mkdir(parents=True, exist_ok=True)

    doc = Document()
    _set_document_font(doc, font_name, base_font_size, line_spacing)

    if add_title:
        _add_title(doc, title_text, font_name)

    paragraphs = _split_paragraphs(opinion_text)
    for para_text in paragraphs:
        for segment in _split_numbered_items(para_text):
            _add_paragraph(doc, segment, font_name, line_spacing)

    doc.save(output_path)
    return output_path


def _split_paragraphs(text: str) -> List[str]:
    raw = text.strip()
    if not raw:
        return []
    parts = [p.strip() for p in raw.split("\n\n") if p.strip()]
    if parts:
        return parts
    return [line.strip() for line in raw.splitlines() if line.strip()]


def _split_numbered_items(text: str) -> List[str]:
    cleaned = text.strip()
    if not cleaned:
        return []
    matches = list(NUMBERED_ITEM_PATTERN.finditer(cleaned))
    if not matches:
        return [cleaned]

    starts = [match.start(1) for match in matches]
    parts: List[str] = []
    lead = cleaned[:starts[0]].strip()
    if lead:
        parts.append(lead)
    for index, start in enumerate(starts):
        end = starts[index + 1] if index + 1 < len(starts) else len(cleaned)
        item = cleaned[start:end].strip()
        item = item.rstrip("；; ")
        if item:
            parts.append(item)
    return parts


def _set_document_font(doc: Document, font_name: str, base_font_size: int, line_spacing: float) -> None:
    for style_name in ("Normal", "Heading 1"):
        if style_name not in doc.styles:
            continue
        style = doc.styles[style_name]
        style.font.name = font_name
        style.font.size = Pt(base_font_size)
        _set_style_east_asia_font(style, font_name)
        style.paragraph_format.line_spacing_rule = WD_LINE_SPACING.MULTIPLE
        style.paragraph_format.line_spacing = line_spacing


def _set_style_east_asia_font(style, font_name: str) -> None:
    rpr = style.element.get_or_add_rPr()
    rfonts = rpr.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)


def _set_run_font(run, font_name: str, size: int | None = None, bold: bool | None = None) -> None:
    run.font.name = font_name
    if size is not None:
        run.font.size = Pt(size)
    if bold is not None:
        run.bold = bold

    rpr = run._element.get_or_add_rPr()
    rfonts = rpr.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)


def _add_title(doc: Document, text: str, font_name: str) -> None:
    para = doc.add_paragraph()
    run = para.add_run(text)
    _set_run_font(run, font_name, size=16, bold=True)
    para.paragraph_format.space_after = Pt(6)
    para.alignment = WD_PARAGRAPH_ALIGNMENT.LEFT


def _add_paragraph(doc: Document, text: str, font_name: str, line_spacing: float) -> None:
    para = doc.add_paragraph()
    run = para.add_run(text)
    _set_run_font(run, font_name)
    para.paragraph_format.space_after = Pt(4)
    para.paragraph_format.line_spacing_rule = WD_LINE_SPACING.MULTIPLE
    para.paragraph_format.line_spacing = line_spacing