Merge pull request #433 from easygap/feat/weekly-report

feat: 주간 요약 리포트 — 판단 주기 다이제스트 + 귀속 주간 푸시

Author: easygap

core/weekly_report.py

@@ -0,0 +1,94 @@
+"""주간 요약 리포트 — 판단 주기(주 1회)에 맞춘 다이제스트.
+
+한 달 운영 리뷰(docs/PAPER_MONTH1_REVIEW_AND_PLAN.md P1-7)의 배경: 일일 숫자는
+노이즈가 커서 매일 판단하기엔 부적합하다. 주간 요약은 (1) 주간·누적 성과, (2) 성과
+귀속(실행 격차/구성 격차 — CLI에만 있던 P1-4 분석을 오너에게 주간 푸시), (3) 일정
+대비 진행률·커버리지, (4) 주간 운영 이벤트(결측·스킵·오류)를 한 장으로 모은다.
+
+build_weekly_summary는 순수 함수다 — 입력(평가결과·주간 NAV 변화·이벤트 카운트)을
+받아 Discord embed 필드 목록과 텍스트 폴백을 만든다. 데이터 수집은 호출부(main.py
+run_weekly_report)가 담당한다.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_weekly_summary(
+    *,
+    basket_name: str,
+    eval_result: dict[str, Any],
+    week_nav_change_pct: float | None = None,
+    missing_days: int = 0,
+    cycle_errors: int = 0,
+) -> dict[str, Any]:
+    """주간 다이제스트를 만든다(순수 함수).
+
+    missing_days: 이번 주(최근 영업일) 스냅샷이 빠진 '고유 일수' — SNAPSHOT_GAP 이벤트
+      원시 카운트가 아니다(P0-1이 미복구 결측을 매 사이클 재경보하므로 이벤트 수는
+      하루 결측을 여러 건으로 부풀린다 → 고유 일수로 집계해야 정확).
+    cycle_errors: 이번 주 CYCLE_ERROR 발생 건수.
+
+    반환: {"title": str, "fields": [{"name","value","inline"}...], "text": str}
+      - fields: notifier.send_embed용
+      - text: 임베드 실패 시 폴백 텍스트
+    """
+    m = (eval_result or {}).get("metrics") or {}
+    verdict = (eval_result or {}).get("verdict", "?")
+    icon = {"WAIT": "⏳", "PASS_CANDIDATE": "✅", "FAIL_REVIEW": "❌"}.get(verdict, "❓")
+
+    fields: list[dict[str, Any]] = []
+
+    # 1) 성과 — 주간 변화 + 누적
+    nav = m.get("nav_return_pct")
+    perf = []
+    if week_nav_change_pct is not None:
+        perf.append(f"주간 {week_nav_change_pct:+.2f}%")
+    if nav is not None:
+        perf.append(f"누적 {nav:+.2f}%")
+    if perf:
+        fields.append({"name": "💰 성과", "value": " · ".join(perf), "inline": False})
+
+    # 2) vs KS11 + 귀속 분해(실행/구성)
+    bench = m.get("benchmark_return_pct")
+    exe = m.get("execution_gap_pct")
+    comp = m.get("composition_gap_pct")
+    if bench is not None and nav is not None:
+        line = f"NAV {nav:+.2f}% vs KS11 {bench:+.2f}% (격차 {nav - bench:+.2f}%p)"
+        fields.append({"name": "📊 vs KS11", "value": line, "inline": False})
+    if exe is not None or comp is not None:
+        parts = []
+        if exe is not None:
+            parts.append(f"실행 {exe:+.2f}%p")
+        if comp is not None:
+            parts.append(f"구성 {comp:+.2f}%p")
+        fields.append({
+            "name": "🔎 귀속 분해",
+            "value": " · ".join(parts) + " (실행=통제가능 / 구성=설계수용)",
+            "inline": False,
+        })
+
+    # 3) 일정 대비 — 진행률·커버리지
+    progress_days = eval_result.get("progress_days") if eval_result else None
+    min_days = eval_result.get("min_trading_days") if eval_result else None
+    coverage = eval_result.get("snapshot_coverage") if eval_result else None
+    if progress_days is not None and min_days:
+        cov = f" · 커버리지 {coverage:.0%}" if coverage is not None else ""
+        fields.append({
+            "name": "📅 진행률",
+            "value": f"{progress_days}/{min_days}일 ({progress_days / min_days:.0%}){cov}",
+            "inline": False,
+        })
+
+    # 4) 주간 운영 이벤트 — 결측은 '고유 일수'(이벤트 재경보로 부풀지 않게), 오류는 건수.
+    md = int(missing_days or 0)
+    ce = int(cycle_errors or 0)
+    ev_line = f"결측 {md}일 · 사이클 오류 {ce}건"
+    if md == 0 and ce == 0:
+        ev_line += " (무사고)"
+    fields.append({"name": "🛠 주간 이벤트", "value": ev_line, "inline": False})
+
+    title = f"{icon} 주간 요약 — {basket_name} ({verdict})"
+    text_lines = [title] + [f"{f['name']}: {f['value']}" for f in fields]
+    return {"title": title, "fields": fields, "text": "\n".join(text_lines)}

docs/PAPER_MONTH1_REVIEW_AND_PLAN.md

@@ -181,7 +181,13 @@ P0-1(하트비트·재시도)을 먼저 머지하고 재시작하는 순서를 
 >   (일일 사이클 부담 없음, `--no-attribution`로 생략 가능). 실CLI 스모크 확인.
 >   적대적 리뷰 반영: NAV(마지막 스냅샷 시점)와 벤치마크·설계 조회 종료일을 일치시켜
 >   하루치 시장 변동이 실행 격차로 오귀속되지 않게 창을 정합.
-> - ⬜ P1-6/7 (스냅샷 시점 정합·주간 리포트), P2~P3 — 대기
+> - ✅ **P1-7 주간 요약 리포트** — `core/weekly_report.py`에 순수 `build_weekly_summary`,
+>   `main.py`에 `--mode weekly_report`. 주간 성과 + 귀속 분해(실행/구성 격차 — CLI 전용이던
+>   P1-4를 오너에게 주간 푸시) + 진행률/커버리지 + 주간 이벤트를 Discord 한 장으로. 금요일
+>   크론에 추가해 쓴다. 적대적 리뷰 반영: 결측은 SNAPSHOT_GAP 이벤트 원시 카운트 대신
+>   '고유 일수'로 집계(재경보 부풀림 방지), 주간 변화 기준 스냅샷을 ~1주 밴드로 제한
+>   (공백 시 다주간 수익 오표기 방지). 실데이터 스모크 확인.
+> - ⬜ P1-6 (스냅샷 시점 정합), P2~P3 — 대기
 >   - P1-6은 트랙레코드 재시작(오너 자본 결정) 시점에 함께 다루는 게 안전(운영 중 스냅샷
 >     시점 변경은 시계열 일관성 훼손) — 재시작 전까지 보류.
 

main.py

@@ -1724,6 +1724,102 @@ def _design_fraction(cfg: dict) -> float:
     return {"OK": 0, "ATTENTION": 1, "BLOCKED": 2}.get(health["verdict"], 1)
 
 
+def run_weekly_report() -> int:
+    """주간 요약 리포트 — 판단 주기(주 1회) 다이제스트를 Discord로 발송.
+
+    일일 숫자는 노이즈가 커서 매일 판단하기엔 부적합하다(P1-7). 주간 성과·귀속 분해
+    (실행/구성 격차)·진행률·주간 이벤트를 한 장으로 모아 오너가 주 1회 이것만 봐도
+    운영 판단이 되게 한다. 금요일 스케줄 작업에 추가해 쓴다. 반환: 0 정상.
+    """
+    from datetime import datetime, timedelta
+    from zoneinfo import ZoneInfo
+    from core.notifier import Notifier
+    from core.basket_evaluation import collect_basket_paper_evaluation
+    from core.weekly_report import build_weekly_summary
+    from core.cycle_observability import detect_snapshot_gaps_for_account
+    from core.basket_rebalancer import BasketRebalancer, rebalance_live_strategy_id
+    from database.models import get_session, PortfolioSnapshot, OperationEvent, init_database
+
+    init_database()
+    config = Config.get()
+    notifier = Notifier(config)
+    now_kst = datetime.now(ZoneInfo("Asia/Seoul")).replace(tzinfo=None)
+
+    def _d(v):
+        return v.date() if hasattr(v, "date") and callable(getattr(v, "date")) else v
+
+    names = BasketRebalancer.get_enabled_baskets()
+    if not names:
+        logger.warning("enabled 바스켓 없음 — 주간 리포트 생략")
+        return 0
+
+    for name in names:
+        try:
+            eval_result, basket_name = collect_basket_paper_evaluation(
+                basket_name=name, include_attribution=True,
+            )
+            key = rebalance_live_strategy_id(name)
+            session = get_session()
+            try:
+                snaps = (
+                    session.query(PortfolioSnapshot)
+                    .filter(PortfolioSnapshot.account_key == key)
+                    .order_by(PortfolioSnapshot.date.asc())
+                    .all()
+                )
+                since = now_kst - timedelta(days=7)
+                cycle_errors = (
+                    session.query(OperationEvent)
+                    .filter(OperationEvent.strategy == key)
+                    .filter(OperationEvent.event_type == "CYCLE_ERROR")
+                    .filter(OperationEvent.created_at >= since)
+                    .count()
+                )
+            finally:
+                session.close()
+
+            # 주간 NAV 변화: 마지막 스냅샷 vs '약 1주 전' 스냅샷.
+            # 기준 스냅샷이 7일 전 근방(±3일 밴드) 안에 있을 때만 '주간'으로 표기한다 —
+            # 스냅샷 공백으로 기준이 2~4주 전이면 다주간 수익을 주간으로 오표기하게 되므로
+            # 그 경우 주간 항을 생략한다(누적은 유지). (적대적 리뷰 low)
+            week_change = None
+            if len(snaps) >= 2:
+                last_val = float(snaps[-1].total_value)
+                last_date = _d(snaps[-1].date)
+                band = [
+                    s for s in snaps
+                    if last_date - timedelta(days=10) <= _d(s.date) <= last_date - timedelta(days=4)
+                ]
+                if band:
+                    ref_val = float(band[-1].total_value)
+                    if ref_val > 0:
+                        week_change = (last_val / ref_val - 1) * 100
+
+            # 결측은 '고유 일수'로 집계(SNAPSHOT_GAP 이벤트는 미복구 결측을 매 사이클
+            # 재경보해 부풀려짐 → 최근 7일 실제 빠진 영업일 수를 직접 센다).
+            try:
+                missing_days = len(detect_snapshot_gaps_for_account(
+                    config, key, now_kst, lookback_calendar_days=7,
+                ))
+            except Exception:
+                missing_days = 0
+
+            summary = build_weekly_summary(
+                basket_name=basket_name, eval_result=eval_result,
+                week_nav_change_pct=week_change,
+                missing_days=missing_days, cycle_errors=cycle_errors,
+            )
+            logger.info("\n{}", summary["text"])
+            try:
+                notifier.send_embed(summary["title"], "", fields=summary["fields"])
+            except Exception as e:
+                logger.debug("주간 리포트 발송 실패(무시): {}", e)
+        except Exception as exc:
+            logger.warning("바스켓 '{}' 주간 리포트 생성 실패: {}", name, exc)
+
+    return 0
+
+
 def _build_cli_guide(args) -> str:
     """인자 없이 실행하거나 --mode guide 일 때 보여줄 사용 가이드.
 
@@ -1862,6 +1958,7 @@ def main():
             "rebalance",
             "health",
             "deploy_check",
+            "weekly_report",
             "guide",
         ],
         help="실행 모드. backtest_momentum_top: 모멘텀 상위 동일비중 멀티종목. portfolio_backtest: 멀티종목 포트폴리오 백테스트. paper: 워치리스트 1회. schedule: 모의 스케줄 무한 루프(상시 서버). rebalance: 바스켓 리밸런싱. health: 운영 통합 헬스 점검(전 전략 runtime + blockers). deploy_check: 바스켓 배포 점검(계획·비용·활성화 절차).",
@@ -2054,6 +2151,8 @@ def main():
             raise SystemExit(run_health_check())
         elif args.mode == "deploy_check":
             raise SystemExit(run_deploy_check(args))
+        elif args.mode == "weekly_report":
+            raise SystemExit(run_weekly_report())
         else:
             logger.error("알 수 없는 모드: {}", args.mode)
     except KeyboardInterrupt:

tests/test_weekly_report.py

@@ -0,0 +1,93 @@
+"""build_weekly_summary — 주간 요약 다이제스트 포맷터 단위 테스트(순수 함수)."""
+
+from core.weekly_report import build_weekly_summary
+
+
+def _eval(**over):
+    base = {
+        "verdict": "WAIT",
+        "progress_days": 22,
+        "min_trading_days": 60,
+        "snapshot_coverage": 0.95,
+        "metrics": {
+            "nav_return_pct": -5.47,
+            "benchmark_return_pct": 0.71,
+            "execution_gap_pct": -2.04,
+            "composition_gap_pct": -5.51,
+            "total_gap_pct": -6.18,
+        },
+    }
+    base.update(over)
+    return base
+
+
+def _fields(out):
+    return {f["name"]: f["value"] for f in out["fields"]}
+
+
+class TestBuildWeeklySummary:
+    def test_title_has_verdict_and_basket(self):
+        out = build_weekly_summary(basket_name="kr_diversified_hold", eval_result=_eval())
+        assert "kr_diversified_hold" in out["title"]
+        assert "WAIT" in out["title"]
+
+    def test_performance_week_and_cumulative(self):
+        out = build_weekly_summary(
+            basket_name="b", eval_result=_eval(), week_nav_change_pct=-1.2,
+        )
+        perf = _fields(out)["💰 성과"]
+        assert "주간 -1.20%" in perf
+        assert "누적 -5.47%" in perf
+
+    def test_attribution_fields_present(self):
+        f = _fields(build_weekly_summary(basket_name="b", eval_result=_eval()))
+        assert "NAV -5.47% vs KS11 +0.71%" in f["📊 vs KS11"]
+        assert "실행 -2.04%p" in f["🔎 귀속 분해"]
+        assert "구성 -5.51%p" in f["🔎 귀속 분해"]
+
+    def test_progress_field(self):
+        f = _fields(build_weekly_summary(basket_name="b", eval_result=_eval()))
+        assert "22/60일" in f["📅 진행률"]
+        assert "커버리지 95%" in f["📅 진행률"]
+
+    def test_event_counts_and_no_incident(self):
+        f = _fields(build_weekly_summary(
+            basket_name="b", eval_result=_eval(), missing_days=0, cycle_errors=0,
+        ))
+        assert "무사고" in f["🛠 주간 이벤트"]
+
+    def test_event_counts_with_incidents(self):
+        f = _fields(build_weekly_summary(
+            basket_name="b", eval_result=_eval(), missing_days=1, cycle_errors=2,
+        ))
+        ev = f["🛠 주간 이벤트"]
+        assert "결측 1일" in ev and "사이클 오류 2건" in ev
+        assert "무사고" not in ev
+
+    def test_missing_days_counts_distinct_not_events(self):
+        # 하루 결측이 여러 SNAPSHOT_GAP 이벤트로 재경보돼도 '1일'로만 집계돼야 한다
+        # (호출부가 고유 일수를 넘기는 계약을 포맷터 수준에서 못박음).
+        f = _fields(build_weekly_summary(
+            basket_name="b", eval_result=_eval(), missing_days=1, cycle_errors=0,
+        ))
+        assert "결측 1일" in f["🛠 주간 이벤트"]
+
+    def test_missing_week_change_omits_week_term(self):
+        f = _fields(build_weekly_summary(basket_name="b", eval_result=_eval()))
+        assert "주간" not in f["💰 성과"]
+        assert "누적 -5.47%" in f["💰 성과"]
+
+    def test_text_fallback_contains_fields(self):
+        out = build_weekly_summary(basket_name="b", eval_result=_eval())
+        for f in out["fields"]:
+            assert f["value"] in out["text"]
+
+    def test_missing_attribution_still_builds(self):
+        out = build_weekly_summary(
+            basket_name="b",
+            eval_result={"verdict": "WAIT", "progress_days": 5, "min_trading_days": 60,
+                         "snapshot_coverage": 1.0, "metrics": {"nav_return_pct": None}},
+        )
+        names = [f["name"] for f in out["fields"]]
+        assert "🔎 귀속 분해" not in names  # 귀속 데이터 없으면 생략
+        assert "🛠 주간 이벤트" in names    # 이벤트 필드는 항상