"""Shared helpers for recognizing document codes in text.

公文文号识别工具模块。
使用正则表达式从文本中提取符合"机构名〔年份〕第N号"格式的
政府公文文号（如"国发〔2024〕15号"），用于文档引用关系的
自动发现和知识图谱中的文档间关联构建。
"""

from __future__ import annotations

import re
from collections.abc import Iterator

DOC_CODE_RE = re.compile(
    r"[\u4e00-\u9fffA-Za-z]{2,20}"
    r"\s*[〔\[【(（]"
    r"\s*\d{4}\s*"
    r"[〕\]】)）]"
    r"\s*第?\s*\d+\s*号"
)


def iter_doc_codes(text: str) -> Iterator[str]:
    """Yield unique document codes from text in encounter order."""
    seen: set[str] = set()
    for match in DOC_CODE_RE.finditer(text or ""):
        doc_code = match.group(0).strip()
        if doc_code and doc_code not in seen:
            seen.add(doc_code)
            yield doc_code


def extract_first_doc_code(text: str) -> str | None:
    """Return the first recognized document code from text."""
    return next(iter_doc_codes(text), None)