---
name: stock-agent
description: 주식 포트폴리오 리포트를 담당하는 에이전트. 키움 REST API(조회 전용)로 4계좌(본인 일반·ISA + 가희 일반·ISA) 보유종목·예수금·손익을 실시간 조회해 owner 그룹별 블록 형태로 이메일 리포트 발송. 평일 20:10 launchd 자동 실행.
---

# stock-agent

주식 포트폴리오 일일 리포트를 담당합니다. 2026-04-24부터 **키움 REST API 기반**으로 전환 — `portfolio.json` 및 네이버 시세 의존 제거, iMessage 체결 파싱(`portfolio-update.py`)도 폐기되었습니다.

## 데이터 소스

- `kt00018` 계좌평가잔고내역: 종목별 수량·평단·현재가·평가액·손익·수익률·당일매매수량 (ground truth)
- `kt00001` 예수금상세현황: 예수금·주문가능금액·대용금
- 4계좌(본인 **일반**·**ISA** + **가희_일반**·**가희_ISA**) 각각 별도 AppKey로 조회 — 토큰이 계좌에 바인딩되어 자동 분기
- owner 그룹은 라벨 prefix로 결정: `_` 없는 라벨은 본인, `가희_` prefix는 가희

## Commands

```bash
python3 scripts/stock_portfolio_report.py run                # owner 블록 뷰 출력 (기본)
python3 scripts/stock_portfolio_report.py run --by-account   # owner 블록 안에서 계좌별 분리 뷰
python3 scripts/stock_portfolio_report.py send               # owner 블록 뷰 이메일 발송 (텔레그램 요약 없음)
python3 scripts/stock_portfolio_report.py send --by-account  # 분리 뷰 이메일 발송 (텔레그램 요약 없음)
```

- 기본 표시는 owner 그룹별 블록(본인 / 가희) — 그룹 내에서만 같은 종목 가중평단 머지. 본인↔가희 자금은 절대 합산하지 않음
- `--by-account`: owner 블록 안에서 추가로 계좌별(4계좌) 섹션까지 분리
- 당일 매매 있는 종목은 `★ 오늘 매매 발생` 표시 (tdy_buyq/tdy_sellq 기반)
- 일일 리포트는 이메일만 발송합니다. 텔레그램 요약 발송은 2026-05-14 관리자님 요청으로 비활성화했습니다.
- **전날대비**는 owner별 **순자산(평가금액 + 예수금)** 기준으로 계산. 평가금액만으로는 매도 시 평가→예수금 이동분이 손실처럼 표시되어 부정확

## Workflow

1. `kiwoom_client.get_positions_all()` → 4계좌 보유종목 수집
2. owner 그룹별로 분리 → 그룹 내 같은 종목 가중평단 머지 (`--by-account`면 계좌까지 유지)
3. 예수금/주문가능/대용금 계좌별 표시 (owner 블록 안)
4. `state/portfolio_daily_snapshot.json`에 v4 스키마(`{owner: {holdings: {stock: {...}}, deposit: int, trade_journal: [...], realized_pl_total: int, realized_fees_total: int}}`)로 오늘 날짜 스냅샷 저장. legacy v1(flat)·v2(owner→stock)는 자동 승격하되 `deposit=None` 처리되어 해당 일자에 대한 순자산 비교는 불가. v3 스냅샷은 매매일지 키가 없을 뿐 그대로 호환
5. `send` 모드면 gog gmail로 관리자님 메일만 발송 (레이 봇 텔레그램 요약 없음)

## Files

- Script: `scripts/stock_portfolio_report.py` (심볼릭 링크: `skills/stock-agent/scripts/stock_portfolio_report.py`)
- Snapshot: `state/portfolio_daily_snapshot.json` (일자별 v4 스냅샷 — `{owner: {holdings: {stock: {qty,avg_price,price,eval_value,profit}}, deposit: int, trade_journal: [{code,name,accounts,buy_qty,buy_avg,buy_amt,sell_qty,sell_avg,sell_amt,realized_pl,fees_tax,realized_profit_rate}], realized_pl_total: int, realized_fees_total: int}}`. 전날대비 순자산 비교 + 월별 실현손익/회전율/수수료 통계용. legacy v1/v2/v3 자동 호환)
- Portfolio memo: `memory/portfolio.json` (v2 스키마 — 참고용. 실제 리포트 숫자는 REST 실시간 조회)
- 의존 스킬: `kiwoom-rest` (클라이언트 및 TR 매핑)

## 매매 절대 원칙

이 스킬은 조회·리포트만 수행합니다. 매수·매도 트리거로 이어지는 어떤 자동화도 포함하지 않으며, 매매 제안이 필요한 경우 텔레그램 알림까지가 한계입니다 (kiwoom-rest 스킬 참고).
