auto: 일일 백업 2026-07-30 02:00

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

agents/stock/workspace/scripts/kiwoom_client.py

@@ -39,6 +39,7 @@ ENDPOINT_RKINFO = '/api/dostk/rkinfo'    # 순위정보 — ka10023 거래량급
 TR_DEPOSIT = 'kt00001'       # 예수금상세현황요청
 TR_ACNT_EVAL = 'kt00004'     # 계좌평가현황요청 (acnt_nm·brch_nm 포함)
 TR_TRUST_TRADE = 'kt00015'   # 위탁종합거래내역요청 (tp='1' 입출금 — 당일 추가입금/인출 추출용)
+TR_ACNT_RETURN = 'kt00016'   # 일별계좌수익률상세현황요청 (기간내총입금·총출금 — 투자원금 산출용)
 TR_POSITIONS = 'kt00018'     # 계좌평가잔고내역요청 (종목별 상세, 수수료·세금 포함)
 TR_TRADE_DIARY = 'ka10170'   # 당일매매일지요청 (round-trip·풀매도 포함, 잔고에 없는 거래도 잡힘)
 TR_ORDER_EXEC = 'kt00007'    # 계좌별주문체결내역상세 (주문번호·시각·체결가·체결수량 단위, REST/영웅문 출처 구분)
@@ -431,25 +432,39 @@ def get_trade_journal_all(base_dt: str | None = None, labels: list[str] | None =
     return {a['label']: get_trade_journal(a['label'], base_dt) for a in accs}
 
 
-def get_cash_flow(account_label: str, base_dt: str | None = None) -> list[dict]:
-    """당일 입출금 내역 (kt00015 tp='1').
+def get_cash_flow(account_label: str, base_dt: str | None = None,
+                  strt_dt: str | None = None, end_dt: str | None = None) -> list[dict]:
+    """입출금 내역 (kt00015 tp='1').
 
     base_dt: YYYYMMDD (None이면 KST 오늘). 시작/종료 동일 → 그날치만.
+    strt_dt/end_dt: 둘 다 주면 기간 조회 (base_dt 무시).
+      ⚠️ **조회기간 1년 제한** — 넘기면 `[2000](501058:조회기간은 1년 이내로만 가능합니다.)`.
+      다년치는 연도별로 쪼개 호출한다 (investment_principal.py 참조).
     tp='1'(입출금)·gds_tp='0'(전체)로 매매·환전 등은 제외. KRW만 필터.
 
+    ⚠️ tp='1' 입금에는 **배당금·예탁금이용료(이자)·수익분배금·공모주환불금·단주매각대금**이
+    섞여 들어온다. 이건 '내가 넣은 돈'이 아니므로 투자원금 합산에 그대로 쓰면 과대계상된다.
+    kt00016의 기간내총입금/총출금은 이걸 이미 제외한 순수 외부 이체액이다 (전 계좌·연도 실증).
+    적요 기준 분류는 `investment_principal.is_principal_flow`.
+
     반환 행:
+      - date:    'YYYYMMDD' (trde_dt)
       - time:    'HH:MM:SS' (proc_tm 앞 8자리)
       - io_tp:   'IN' | 'OUT'
       - amount:  거래금액 (원, 양수)
       - signed:  +amount (입금) / -amount (출금) — 합산으로 net cash flow 산출
-      - rmrk:    적요명 (예: '타사대체입금', '은행이체출금')
+      - rmrk:    적요명 (예: '이체입금(지급결제)', '배당금입금', '이체출금')
       - balance: 거래 후 예수금잔고 (entra_remn)
     """
-    if base_dt is None:
-        base_dt = datetime.now(KST).strftime('%Y%m%d')
+    if strt_dt and end_dt:
+        fr, to = strt_dt, end_dt
+    else:
+        if base_dt is None:
+            base_dt = datetime.now(KST).strftime('%Y%m%d')
+        fr = to = base_dt
     body = {
-        'strt_dt': base_dt,
-        'end_dt': base_dt,
+        'strt_dt': fr,
+        'end_dt': to,
         'tp': '1',
         'stk_cd': '',
         'crnc_cd': '',
@@ -478,6 +493,7 @@ def get_cash_flow(account_label: str, base_dt: str | None = None) -> list[dict]:
             continue
         proc_tm = (it.get('proc_tm') or '').strip()
         out.append({
+            'date': (it.get('trde_dt') or '').strip(),
             'time': proc_tm[:8],
             'io_tp': io_tp,
             'amount': amount,
@@ -497,6 +513,38 @@ def get_cash_flow_all(base_dt: str | None = None, labels: list[str] | None = Non
     return {a['label']: get_cash_flow(a['label'], base_dt) for a in accs}
 
 
+def get_period_return(account_label: str, fr_dt: str, to_dt: str) -> dict:
+    """기간 계좌수익률 상세 (kt00016) — 기간내 총입금·총출금 포함.
+
+    ⚠️ **조회기간 1년 제한** — 넘기면 `[2000](505221:조회기간은 1년이내로만 가능합니다.)`.
+    전체기간 투자원금은 연도별 창으로 쪼개 누적해야 한다 (investment_principal.py 참조).
+
+    ⚠️ 응답의 `invt_bsamt`는 "투자원금**평잔**"(기간 평균잔고)이라 누적 투자원금이 아니다 —
+    이름이 비슷해 오용하기 쉬우니 반환하지 않는다. 누적 원금은 cash_in − cash_out.
+
+    계좌 개설 전 기간은 에러 없이 전 필드 0으로 응답한다.
+    항등식 `net_fr + cash_in − cash_out + eval_pl == net_to` 가 성립 (자체 검증용).
+
+    반환:
+      - cash_in/cash_out:  기간내 총입금/총출금 (원)
+      - qty_in/qty_out:    기간내 총입고/총출고 (주식 대체 — 0이 아니면 현금 기준 원금이 과소계상)
+      - net_fr/net_to:     순자산액계 기초/기말
+      - eval_pl:           평가손익
+    """
+    resp = _call(account_label, TR_ACNT_RETURN, {'fr_dt': fr_dt, 'to_dt': to_dt})
+    return {
+        'label': account_label,
+        'cash_in': _to_int(resp.get('termin_tot_trns')),   # 기간내총입금
+        'cash_out': _to_int(resp.get('termin_tot_pymn')),  # 기간내총출금
+        'qty_in': _to_int(resp.get('termin_tot_inq')),     # 기간내총입고
+        'qty_out': _to_int(resp.get('termin_tot_outq')),   # 기간내총출고
+        'net_fr': _to_int(resp.get('tot_amt_fr')),         # 순자산액계_초
+        'net_to': _to_int(resp.get('tot_amt_to')),         # 순자산액계_말
+        'eval_pl': _to_int(resp.get('evltv_prft')),        # 평가손익
+        'raw': resp,
+    }
+
+
 def get_order_executions(account_label: str, base_dt: str | None = None) -> list[dict]:
     """계좌별 주문체결내역 (kt00007) — 주문번호·시각 단위 행 리스트.