두 보고서가 같은 지표에 대해 서로 다른 숫자를 보여주는 이유를 설명합니다. — Claude Skill

""" 지표 정합성 검증 도우미

같은 기간에 대해 두 출처의 지표 값을 비교하고 계산 경로가 어디에서 갈라지는지 식별합니다.

사용법: python reconcile_metrics.py --source-a source_a.csv --source-b source_b.csv
--metric revenue --date 2025-01-01 python reconcile_metrics.py --values 125000 118500 --metric revenue --tolerance 0.02 """

import argparse import csv import io import sys

def compare_values(value_a: float, value_b: float, tolerance: float = 0.001) -> dict: """ 두 지표 값을 비교하고 정합성 검증 통계를 반환합니다.

인수:
    value_a: 출처 A의 값
    value_b: 출처 B의 값
    tolerance: 격차를 수용하는 비율 허용 범위(기본 0.1%)

반환:
    absolute_diff, pct_diff, within_tolerance, status를 포함한 dict
"""
absolute_diff = value_a - value_b
pct_diff = absolute_diff / value_a if value_a != 0 else float("inf")
within_tolerance = abs(pct_diff) <= tolerance

return {
    "value_a": value_a,
    "value_b": value_b,
    "absolute_diff": absolute_diff,
    "pct_diff": pct_diff,
    "within_tolerance": within_tolerance,
    "status": "ACCEPTED" if within_tolerance else "INVESTIGATE",
}

def load_metric_from_csv(filepath: str, metric_col: str, date_col: str = None, date: str = None) -> float: """ CSV 파일에서 단일 지표 값을 불러옵니다.

date가 제공되면 해당 날짜와 일치하는 모든 행의 metric_col을 합산합니다.
"""
total = 0.0
matched = 0

with open(filepath, newline="", encoding="utf-8") as f:
    reader = csv.DictReader(f)
    for row in reader:
        if date_col and date and row.get(date_col) != date:
            continue
        total += float(row[metric_col])
        matched += 1

if matched == 0:
    raise ValueError(f"{filepath}에서 행을 찾을 수 없습니다" + (f"(날짜: {date})" if date else ""))

return total

def reconciliation_report(result: dict, source_a_label: str, source_b_label: str) -> str: """사람이 읽을 수 있는 정합성 검증 요약을 생성합니다.""" display_status = "수용" if result["within_tolerance"] else "조사 필요" lines = [ "=" * 60, "지표 정합성 검증 보고서", "=" * 60, f" {source_a_label}: {result['value_a']:,.2f}", f" {source_b_label}: {result['value_b']:,.2f}", f" 절대 차이: {result['absolute_diff']:+,.2f}", f" 비율 차이: {result['pct_diff']:+.4%}", "", " 상태: " + display_status, ]

if result["within_tolerance"]:
    lines.append("  격차가 허용 범위 안에 있습니다. 추가 조치는 필요 없습니다.")
else:
    lines += [
        "",
        "  다음 단계:",
        "  1. 각 출처의 쿼리/파이프라인 정의를 나란히 비교합니다.",
        "  2. 필터 조건, 조인 유형, null 처리, 날짜 절단을 확인합니다.",
        "  3. 첫 분기점을 찾기 위해 행 단위 데이터를 가져옵니다.",
        "  4. assets/reconciliation_report_template.md에 근본 원인을 문서화합니다.",
    ]

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

def main(): parser = argparse.ArgumentParser(description="두 출처 간 지표 정합성을 검증합니다.") parser.add_argument("--source-a", help="출처 A CSV 경로") parser.add_argument("--source-b", help="출처 B CSV 경로") parser.add_argument("--values", nargs=2, type=float, metavar=("A", "B"), help="직접 값 지정: --values 125000 118500") parser.add_argument("--metric", required=False, default="value", help="지표 열 이름") parser.add_argument("--date-col", default=None, help="필터링할 날짜 열 이름") parser.add_argument("--date", default=None, help="필터링할 날짜(예: 2025-01-01)") parser.add_argument("--tolerance", type=float, default=0.001, help="수용할 격차 비율(기본 0.001 = 0.1%%)") parser.add_argument("--label-a", default="출처 A") parser.add_argument("--label-b", default="출처 B") args = parser.parse_args()

if args.values:
    value_a, value_b = args.values
elif args.source_a and args.source_b:
    value_a = load_metric_from_csv(args.source_a, args.metric, args.date_col, args.date)
    value_b = load_metric_from_csv(args.source_b, args.metric, args.date_col, args.date)
else:
    parser.error("--values 또는 --source-a와 --source-b를 모두 제공하세요")

result = compare_values(value_a, value_b, args.tolerance)
print(reconciliation_report(result, args.label_a, args.label_b))

sys.exit(0 if result["within_tolerance"] else 1)

if name == "main": # 데모: 5.5% 격차가 있는 두 값은 조사 필요 상태를 발생시켜야 합니다. demo_a = 125_000.0 demo_b = 118_120.0 result = compare_values(demo_a, demo_b, tolerance=0.001) print(reconciliation_report(result, "대시보드(출처 A)", "재무 보고서(출처 B)")) print() print("데모 종료 상태:", "수용" if result["within_tolerance"] else "조사 필요")

지표 정합성 검증 패턴

지표가 서로 달라지는 이유

1. 필터 차이

가장 흔한 원인입니다. 같은 테이블에서 가져오는 두 쿼리라도 WHERE 절이 다르면 다른 숫자가 나옵니다. 확인할 것: 상태 필터, 날짜 절단(>= vs BETWEEN), NULL 처리, 삭제된 레코드 제외 여부.

2. 조인 유형 불일치

LEFT JOIN과 INNER JOIN은 조용히 행을 추가하거나 제거합니다. 고객 테이블에 LEFT JOIN된 매출 수치는 일치하는 고객이 없는 주문도 계산하지만, INNER JOIN은 해당 주문을 제거합니다.

3. 집계 단위 불일치

한 쿼리는 주문 수준에서 집계하고, 다른 쿼리는 주문 라인 수준에서 집계합니다. 한 출처의 중복 행이 합계를 부풀립니다.

4. 시간대 처리

UTC와 현지 시간의 차이 때문에 시스템에 따라 행이 서로 다른 기간에 들어갑니다. 글로벌 대시보드에서 흔합니다.

5. 정의 드리프트

비즈니스 정의가 바뀌었지만(예: "활성 사용자"가 이제 한 세션이 아니라 두 세션을 요구함) 모든 파이프라인이 동시에 업데이트되지 않았습니다.

6. 새로고침 지연

한 출처는 어제의 스냅샷을 반영하고, 다른 출처는 거의 실시간입니다. 하루 중 정합성 검증 중에 비교하면 가짜 격차가 생깁니다.

---

정합성 조사 순서

1. 숫자 확인 — 캐시된 대시보드가 아니라 권위 있는 출처에서 두 값을 가져옵니다.
2. 집계 단위 확인 — 각 출처에서 한 행이 무엇을 의미하는지 확인합니다.
3. 기간 정렬 — 둘 다 같은 시작/종료 경계와 시간대를 사용하는지 확인합니다.
4. 필터 비교 — 모든 WHERE 조건을 나란히 나열합니다.
5. 조인 비교 — 모든 JOIN과 그 유형을 추적합니다.
6. 샘플 수준 확인 — A에는 있지만 B에는 없는 행 20개와 그 반대를 가져옵니다.
7. 근본 원인 문서화 — assets/reconciliation_report_template.md에 기록합니다.

---

지표 유형별 허용 범위 임곗값

---

해결 후 문서화 체크리스트

• 근본 원인 식별(한 문장)
• 어떤 출처를 단일 진실 공급원으로 지정하는지
• 파이프라인 수정이 필요한지, 아니면 정의 명확화가 필요한지
• 차이가 관찰되고 해결된 날짜
• 하위 소비자에게 재계산이 필요한지

지표 정합성 검증 보고서

지표: [지표명] 기간: [날짜 또는 날짜 범위] 분석가: [이름] 날짜: [YYYY-MM-DD]

---

비교한 값

절대 차이: [출처 A - 출처 B] 비율 차이: [(A - B) / A x 100]% 허용 범위 내: 예 / 아니요(허용 범위: [임곗값])

---

근본 원인

상태: 확인됨 / 조사 중 / 문제 없음

원인 범주: 필터 차이 / 조인 유형 / 집계 단위 불일치 / 정의 드리프트 / 새로고침 지연 / 기타

설명: [한 문단: 쿼리나 파이프라인의 어떤 구체적 차이가 격차를 설명하는가]

---

근거

원인을 식별하기 위해 수행한 단계:

1. [1단계 — 예: WHERE 절 비교]
2. [2단계 — 예: JOIN 유형 확인]
3. [3단계 — 예: 행 단위 샘플 추출]

핵심 발견: [차이를 설명하는 특정 쿼리 줄 또는 파이프라인 동작]

---

해결

지정된 단일 진실 공급원: [출처 A / 출처 B / 없음 — 정렬 필요]

필요한 조치:

• 파이프라인 수정 필요(담당자: [이름], 기한: [날짜])
• 쿼리 수정 필요(담당자: [이름], 기한: [날짜])
• 정의 명확화 필요(담당자: [이름], 기한: [날짜])
• 하위 소비자 재계산 필요(목록: [])
• 조치 없음 — 격차가 허용 범위 내

---

예방 조치

[앞으로 이를 더 일찍 어떻게 잡을 것인가? 예: 자동 정합성 검증, CI 테스트, 데이터 품질 경보]

---

템플릿: reconciliation_report_template.md

---

name: metric-reconciliation description: 같은 지표가 둘 이상의 출처에서 서로 다른 값을 보일 때 차이를 추적하고 해결합니다. 보고 전, 파이프라인 변경 후, 이해관계자가 숫자에 의문을 제기할 때 사용합니다.

지표 정합성 검증

사용 시점

• 두 대시보드나 보고서가 같은 KPI에 대해 다른 값을 보여줄 때
• 데이터 파이프라인 업데이트 후 지표가 예상치 못하게 바뀌었을 때
• 이해관계자가 숫자에 의문을 제기하고 권위 있는 설명이 필요할 때
• 기존 보고 출처를 병합하거나 지원 중단할 준비를 할 때
• 분석가를 새 데이터 모델에 온보딩하고 이전 모델과 대조 검증할 때

프로세스

1. 지표와 범위 정의 — 정확한 정의(분자, 분모, 필터, 시간대)와 조사 기간을 확인합니다. 정의 불일치는 차이의 가장 흔한 원인입니다.
2. 두 출처에서 값 가져오기 — 같은 기간에 대해 각 출처의 지표 값을 추출합니다. 절대값, 행 수, 사용된 쿼리나 계산 경로를 기록합니다.
3. 격차 계산 — 절대 차이와 비율 차이를 계산합니다. 격차가 합의된 허용 범위(예: ±0.1%) 안이면 수용으로 문서화하고 종료합니다. 허용 범위 지침은 references/reconciliation_patterns.md를 참조합니다.
4. 계산 경로 추적 — 각 출처의 쿼리나 파이프라인을 단계별로 따라갑니다. 흔한 분기점: 다른 조인 유형, 필터 순서, null 처리, 날짜 절단, 중복 제거 로직.
5. 근본 원인 식별 — references/metric_discrepancy_guide.md를 사용해 원인을 분류합니다(정의 불일치, 데이터 최신성, 집계 단위, 계산 버그). 코드 조각이나 쿼리 발췌와 함께 분기점을 문서화합니다.
6. 해결과 문서화 — 계산을 고치거나 표준 출처를 수용한 뒤 assets/reconciliation_report_template.md를 완성해 이해관계자에게 공유합니다.

스킬에 필요한 입력

• 지표명과 비즈니스 정의(분자, 분모, 알려진 변형)
• 두 출처에 대한 접근(쿼리, 대시보드 SQL, 원시 데이터)
• 차이를 보이는 기간
• 필요한 경우 행 단위 비교를 가능하게 할 행 수 또는 레코드 수준 데이터
• 파이프라인, 스키마, 비즈니스 규칙의 최근 변경 사항

출력

• assets/reconciliation_report_template.md — 출처 A와 출처 B, 격차, 근본 원인, 해결 상태를 보여주는 완성 보고서
• 버그가 발견된 경우 수정된 쿼리 또는 파이프라인 변경
• 격차가 허용 가능한 경우 문서화된 허용 범위 합의