"""B09 근거 사전이 **여러 장에서 같이 쓰는 조각** (PLAN 8-36 ④).

왜 따로 두나
    사전이 두 파일로 갈리면서(값을 낳는 장 / 바깥에서 오거나 모으는 장) 두 쪽이 같은
    이름표 열과 같은 「비고」 설명을 쓴다. 한쪽에 두고 다른 쪽이 가져가면 **고리가 생겨**
    (`Provenance` → `Provenance_Sources` → `Provenance`) 불러들이지 못한다.
    그래서 두 쪽이 함께 바라보는 자리를 따로 뒀다.

⚠ 여기에는 **여러 장이 실제로 같이 쓰는 것만** 둔다. 한 장만 쓰는 문장을 여기로 올리면
    사전을 읽을 때 그 장에서 눈이 떠나 버린다.
"""

from __future__ import annotations

from common_util.common_util_provenance import (
    TIER_STANDARD,
    TIER_UNCLASSIFIED,
    ColumnProvenance,
)

#: 이름표 열(코드·명칭·규격·단위)이 공통으로 쓰는 문장.
CATALOG_SOURCE = "단가판·품셈 표의 이름을 그대로 옮긴 자리 — 여기서 짓지 않음"

#: 「비고」가 왜 미분류인지 — 표마다 같은 말을 쓴다.
NOTE_RULE = (
    "이 칸은 등급을 붙일 열이 아니라 **다른 열의 사유를 담는 그릇**이다. "
    "안에 든 조각마다 닿는 열이 다르므로(갈래 근거는 규격, 반영률은 수량, "
    "막힘 사유는 단가) 호버는 조각을 그 열의 칸에만 띄운다"
)


def _label(key: str, label: str, extra: str = "") -> ColumnProvenance:
    """이름표 열 — 값을 낳은 것이 아니라 옮겨 적은 자리."""
    return ColumnProvenance(
        key=key,
        label=label,
        tier=TIER_STANDARD,
        formula="옮겨 적은 값 (여기서 계산하지 않음)",
        source=CATALOG_SOURCE + (f" · {extra}" if extra else ""),
    )


def _note_column(code: str) -> ColumnProvenance:
    """「비고」 열 — 여덟 어디에도 안 맞아 `unclassified` 로 둔다(PLAN 8-36 ㉮)."""
    return ColumnProvenance(
        key="note",
        label="비고",
        tier=TIER_UNCLASSIFIED,
        formula="줄에 달린 사유 조각을 차례로 이어 붙인 글",
        source="조각마다 원천이 다름 — 조각별 원천은 그 조각이 닿는 열의 카드에 뜸",
        rule=NOTE_RULE,
        code=code,
    )