feat: Articulation Check + OCF 분해 + 영업외 분해 추가

Phase 1-3 + Phase 2 재무제표 직접 읽기:

3. calcArticulationCheck (crossStatement.py)
   BS-CF 정합성: PPE/현금/자본 변동 검증. 오차가 크면 연결범위/환율 변동.

4. calcOcfDecomposition (cashflow.py)
   영업CF = 순이익 + 감가상각 + 운전자본변동 + 기타.
   삼성전자: NI 19.6조 + 감가상각 21.5조 + 운전자본 -8.4조 = OCF 28.8조

5. calcNonOperatingBreakdown (earningsQuality.py)
   영업외 = 순금융 + 지분법 + 기타. 삼성전자 2024: 금융수익 6조 ≈ 영업이익 6.5조

Author: eddmpython

src/dartlab/analysis/financial/cashflow.py

@@ -248,3 +248,92 @@ def calcCashFlowFlags(company, *, basePeriod: str | None = None) -> list[str]:
             flags.append(f"영업CF 마진 {margin:.1f}% — 매출 대비 현금 유출")
 
     return flags
+
+
+# ── 영업CF 내부 분해 (BS 변동 기반) ──
+
+
+def calcOcfDecomposition(company, *, basePeriod: str | None = None) -> dict | None:
+    """영업CF를 구성요소로 분해 — 현금흐름의 원천을 파악.
+
+    대부분 기업이 CF에 개별 조정항목을 안 쓰므로 BS 변동으로 간접 추정.
+
+    OCF ≈ 순이익 + 비현금비용(감가상각 추정) + 운전자본 변동
+    운전자본 변동 = -(delta_AR) - (delta_Inv) + (delta_AP)
+
+    반환::
+
+        {
+            "history": [
+                {"period": str, "ni": float, "ocf": float,
+                 "depEstimate": float, "wcEffect": float,
+                 "arChange": float, "invChange": float, "apChange": float,
+                 "residual": float},
+                ...
+            ],
+        }
+    """
+    isResult = company.select("IS", ["당기순이익"])
+    cfResult = company.select("CF", ["영업활동현금흐름"])
+    bsResult = company.select(
+        "BS",
+        ["매출채권및기타채권", "재고자산", "매입채무", "유형자산"],
+    )
+
+    isParsed = _toDict(isResult)
+    cfParsed = _toDict(cfResult)
+    bsParsed = _toDict(bsResult)
+    if isParsed is None or cfParsed is None or bsParsed is None:
+        return None
+
+    isData, _ = isParsed
+    cfData, cfPeriods = cfParsed
+    bsData, _ = bsParsed
+
+    niRow = isData.get("당기순이익", {})
+    ocfRow = cfData.get("영업활동현금흐름", {})
+    arRow = bsData.get("매출채권및기타채권", {})
+    invRow = bsData.get("재고자산", {})
+    apRow = bsData.get("매입채무", {})
+    ppeRow = bsData.get("유형자산", {})
+
+    from dartlab.analysis.financial._helpers import annualColsFromPeriods
+
+    yCols = annualColsFromPeriods(cfPeriods, basePeriod, 9)
+    if len(yCols) < 2:
+        return None
+
+    history = []
+    for i in range(len(yCols) - 1):
+        col = yCols[i]
+        prevCol = yCols[i + 1]
+
+        ni = _get(niRow, col)
+        ocf = _get(ocfRow, col)
+        ppe = _get(ppeRow, col)
+
+        # 감가상각 추정 (유형자산/10)
+        depEst = ppe / 10 if ppe > 0 else 0
+
+        # 운전자본 변동 (BS delta)
+        arChange = _get(arRow, col) - _get(arRow, prevCol)  # 증가=현금유출
+        invChange = _get(invRow, col) - _get(invRow, prevCol)
+        apChange = _get(apRow, col) - _get(apRow, prevCol)  # 증가=현금유입
+        wcEffect = -arChange - invChange + apChange
+
+        # 잔차 (설명 안 되는 부분: 영업외, 세금, 기타 조정)
+        residual = ocf - ni - depEst - wcEffect
+
+        history.append({
+            "period": col,
+            "ni": ni,
+            "ocf": ocf,
+            "depEstimate": round(depEst),
+            "wcEffect": round(wcEffect),
+            "arChange": round(arChange),
+            "invChange": round(invChange),
+            "apChange": round(apChange),
+            "residual": round(residual),
+        })
+
+    return {"history": history} if history else None

src/dartlab/analysis/financial/crossStatement.py

@@ -330,3 +330,109 @@ def calcCrossStatementFlags(company, *, basePeriod: str | None = None) -> list[s
             flags.append(f"종합 이상점수 {h0['score']:.0f} — 재무제표 신뢰성 주의")
 
     return flags
+
+
+# ── BS-CF Articulation Check ──
+
+
+def calcArticulationCheck(company, *, basePeriod: str | None = None) -> dict | None:
+    """BS-CF 정합성 검증 — 재무제표 3표가 수학적으로 연결되는지.
+
+    3가지 정합성:
+    1. PPE 정합: delta_PPE ≈ CAPEX - 감가상각 - 처분
+    2. 현금 정합: delta_Cash ≈ OCF + ICF + FCF
+    3. 자본 정합: delta_Equity ≈ NI - 배당 + OCI + 신주발행
+
+    오차가 크면 연결범위 변동, 환율 효과, 재분류 가능성.
+
+    반환::
+
+        {
+            "history": [
+                {"period": str, "ppeError": float, "cashError": float,
+                 "equityError": float, "maxErrorPct": float},
+                ...
+            ],
+        }
+
+    학술근거: Articulation of Financial Statements (FASB/IASB).
+    """
+    bsResult = company.select(
+        "BS",
+        ["유형자산", "현금및현금성자산", "자본총계"],
+    )
+    cfResult = company.select(
+        "CF",
+        ["영업활동현금흐름", "투자활동현금흐름", "재무활동현금흐름",
+         "유형자산의취득", "유형자산의처분"],
+    )
+    isResult = company.select("IS", ["당기순이익"])
+
+    bsParsed = _toDict(bsResult)
+    cfParsed = _toDict(cfResult)
+    isParsed = _toDict(isResult)
+    if bsParsed is None or cfParsed is None or isParsed is None:
+        return None
+
+    bsData, bsPeriods = bsParsed
+    cfData, _ = cfParsed
+    isData, _ = isParsed
+
+    ppeRow = bsData.get("유형자산", {})
+    cashRow = bsData.get("현금및현금성자산", {})
+    eqRow = bsData.get("자본총계", {})
+    ocfRow = cfData.get("영업활동현금흐름", {})
+    icfRow = cfData.get("투자활동현금흐름", {})
+    fcfRow = cfData.get("재무활동현금흐름", {})
+    capexRow = cfData.get("유형자산의취득", {})
+    dispRow = cfData.get("유형자산의처분", {})
+    niRow = isData.get("당기순이익", {})
+
+    yCols = _annualColsFromPeriods(bsPeriods, basePeriod, _MAX_YEARS + 1)
+    if len(yCols) < 2:
+        return None
+
+    history = []
+    for i in range(len(yCols) - 1):
+        col = yCols[i]
+        prevCol = yCols[i + 1]
+
+        # 1. PPE 정합
+        ppeCur = _get(ppeRow, col)
+        ppePrev = _get(ppeRow, prevCol)
+        capex = abs(_get(capexRow, col))
+        disp = abs(_get(dispRow, col))
+        # 감가상각은 추정 (유형자산/10)
+        depEst = ppePrev / 10 if ppePrev > 0 else 0
+        ppeExpected = ppePrev + capex - depEst - disp
+        ppeActual = ppeCur
+        ppeError = abs(ppeActual - ppeExpected) / ppePrev * 100 if ppePrev > 0 else None
+
+        # 2. 현금 정합
+        cashCur = _get(cashRow, col)
+        cashPrev = _get(cashRow, prevCol)
+        ocf = _get(ocfRow, col)
+        icf = _get(icfRow, col)
+        fcf = _get(fcfRow, col)
+        cashExpected = cashPrev + ocf + icf + fcf
+        cashError = abs(cashCur - cashExpected) / abs(cashPrev) * 100 if cashPrev != 0 else None
+
+        # 3. 자본 정합
+        eqCur = _get(eqRow, col)
+        eqPrev = _get(eqRow, prevCol)
+        ni = _get(niRow, col)
+        eqExpected = eqPrev + ni  # 배당/OCI 미포함이므로 대략적
+        eqError = abs(eqCur - eqExpected) / abs(eqPrev) * 100 if eqPrev != 0 else None
+
+        errors = [e for e in [ppeError, cashError, eqError] if e is not None]
+        maxErr = max(errors) if errors else None
+
+        history.append({
+            "period": col,
+            "ppeError": round(ppeError, 1) if ppeError is not None else None,
+            "cashError": round(cashError, 1) if cashError is not None else None,
+            "equityError": round(eqError, 1) if eqError is not None else None,
+            "maxErrorPct": round(maxErr, 1) if maxErr is not None else None,
+        })
+
+    return {"history": history} if history else None

src/dartlab/analysis/financial/earningsQuality.py

@@ -460,3 +460,77 @@ def calcRichardsonAccrual(company, *, basePeriod: str | None = None) -> dict | N
         })
 
     return {"history": history} if history else None
+
+
+# ── 영업외손익 분해 ──
+
+
+def calcNonOperatingBreakdown(company, *, basePeriod: str | None = None) -> dict | None:
+    """영업외손익 항목별 분해 — 영업이익과 세전이익 사이의 갭.
+
+    금융이익/비용, 지분법손익, 기타수익/비용을 개별 추적.
+    영업외가 영업이익의 30% 이상이면 영업만으로 기업 판단 불가.
+
+    반환::
+
+        {
+            "history": [
+                {"period": str, "opIncome": float, "finIncome": float,
+                 "finCost": float, "netFinance": float, "associateIncome": float,
+                 "otherIncome": float, "otherExpense": float,
+                 "nonOpTotal": float, "nonOpRatio": float},
+                ...
+            ],
+        }
+    """
+    isResult = company.select(
+        "IS",
+        ["영업이익", "금융이익", "금융비용", "지분법관련손익",
+         "기타수익", "기타비용", "법인세차감전순이익"],
+    )
+
+    isParsed = _toDict(isResult)
+    if isParsed is None:
+        return None
+
+    isData, isPeriods = isParsed
+    opRow = isData.get("영업이익", {})
+    finIncRow = isData.get("금융이익", {})
+    finCostRow = isData.get("금융비용", {})
+    assocRow = isData.get("지분법관련손익", {})
+    otherIncRow = isData.get("기타수익", {})
+    otherExpRow = isData.get("기타비용", {})
+    ptRow = isData.get("법인세차감전순이익", {})
+
+    yCols = _annualColsFromPeriods(isPeriods, _MAX_YEARS, basePeriod=basePeriod)
+    if not yCols:
+        return None
+
+    history = []
+    for col in yCols:
+        op = _get(opRow, col)
+        finInc = _get(finIncRow, col)
+        finCost = _get(finCostRow, col)
+        assoc = _get(assocRow, col)
+        otherInc = _get(otherIncRow, col)
+        otherExp = _get(otherExpRow, col)
+        pt = _get(ptRow, col)
+
+        netFinance = finInc - finCost
+        nonOpTotal = pt - op if op != 0 else None
+        nonOpRatio = round(abs(nonOpTotal) / abs(op) * 100, 1) if op != 0 and nonOpTotal is not None else None
+
+        history.append({
+            "period": col,
+            "opIncome": op,
+            "finIncome": finInc,
+            "finCost": finCost,
+            "netFinance": netFinance,
+            "associateIncome": assoc,
+            "otherIncome": otherInc,
+            "otherExpense": otherExp,
+            "nonOpTotal": nonOpTotal,
+            "nonOpRatio": nonOpRatio,
+        })
+
+    return {"history": history} if history else None