# 실사용 시작 가이드

## 0. 핵심 원칙

이 시스템은 주문을 대신 실행하지 않는다. 역할은 시장, 계좌, 기회비용, 피로도를 한 번에 정리해 사용자가 더 빨리 판단하게 돕는 것이다.

실제 주문 전 최종 기준은 항상 나무증권 앱의 현재가, 주문가능현금, 환율, 거래 가능 여부다.

## 1. 매일 쓰는 흐름

### 장 시작 전

1. 대시보드를 연다: `account_growth_command_center.html`
2. 계좌 스크린샷을 Codex 채팅에 업로드하거나 계좌 스냅샷을 최신화한다.
3. 장전 리포트에서 오늘 모드를 본다.
4. 매수 후보가 있어도 목표가, 손절, 시간제한, 수량이 없으면 보류한다.

### 스크린샷으로 빠르게 공유

계좌 숫자를 직접 입력하기 부담스러우면 스크린샷을 올린다.

```text
SCREENSHOT_ACCOUNT_ANALYSIS
time:
broker: 나무증권
screenshots_attached: yes
stress: 낮음/보통/높음
urgent_question:
```

권장 촬영 화면은 `screenshot_account_analysis_flow.md`를 따른다.

스크린샷 분석이 끝나면 Codex가 `account,ticker,qty,avg_price,current_price,value_krw,pnl_krw` 형식의 포지션 CSV를 만들어준다. 이 CSV를 대시보드의 `보유종목 실시간 요약` 입력칸에 붙이고 `붙여넣기 반영`을 누르면 본계좌/부계좌 보유종목과 비중이 자동 갱신된다.

### 장중

빠른 판단이 필요하면 아래처럼 채팅에 붙여넣는다.

```text
STATUS_CHECK
time: 2026-06-06 23:40 KST
main_total:
main_cash:
sub_total:
sub_cash:
watch: RDW/MU/SOXL/SOXS/AMD
stress: 낮음/보통/높음
question: 지금 매수/대기/축소 중 무엇이 우선?
```

### 매수/매도 직후

```text
TRADE_UPDATE
time: 2026-06-06 00:45 KST
account: main/sub
action: BUY/SELL/TRIM/ADD
ticker:
qty:
price:
reason:
cash_source:
thesis:
invalid:
notes:
```

### 장 마감 후

```text
ACCOUNT_SNAPSHOT
time: 2026-06-06 07:00 KST
main_total:
main_cash:
sub_total:
sub_cash:
day_pnl:
realized_ytd:
notes:
```

### 애프터마켓 급변

```text
AFTER_MARKET_EMERGENCY
time:
ticker:
after_hours_move:
news_seen:
position_size:
question:
```

## 2. 입력 우선순위

시간이 없으면 이것만 보낸다.

1. 본계좌 총액/현금
2. 부계좌 총액/현금
3. 오늘 체결한 종목, 수량, 가격
4. 보유 상위 4-5개 종목의 평가액 또는 비중
5. SOXL/SOXS용 1,000만원 현금 확보 가능 여부

정확한 CSV 관리는 시간이 있을 때 한다.

- `portfolio_positions_template.csv`: 보유종목, 평단, 비중, thesis
- `trade_updates_template.csv`: 체결 내역
- `account_snapshot_template.csv`: 계좌 총액/현금
- `tax_lots_template.csv`: 세금용 매수 단가/실현손익

## 3. 카카오톡 알림 구조

사용 방식은 카카오 디벨로퍼스의 카카오톡 메시지 API 중 `나에게 기본 템플릿으로 메시지 발송`이다.

특징:

- 내 카카오톡 `나와의 채팅방`으로만 발송된다.
- 친구나 가족에게 보내는 기능이 아니다.
- 현재 스크립트는 텍스트 요약과 링크 버튼만 보낸다.
- 자동화는 `KAKAO_SHORT_SUMMARY`가 생성되면 환경변수 확인 후 발송을 시도한다.

## 4. 비용/쿼터 판단

개인 계좌용 하루 몇 회 요약 발송은 비용 걱정 없이 운용 가능한 수준이다.

공식 쿼터 문서 기준:

- 전체 API 월 무료 쿼터가 있다.
- 카카오톡 메시지는 무료 일일 쿼터가 문서화되어 있다.
- 유료 추가 쿼터 가격표는 카카오톡 공유 쪽이 명시되어 있으며, 현재 개인용 `나에게 보내기` 하루 2-6회 수준은 쿼터에 한참 못 미친다.

보수적 운영 규칙:

- 기본 자동 발송은 하루 2-4회로 제한한다.
- 긴급 알림까지 포함해도 하루 20회 이내를 목표로 한다.
- 카카오 정책은 바뀔 수 있으므로, 카카오 디벨로퍼스 앱의 `통계 > 쿼터`를 가끔 확인한다.

## 5. 카카오 디벨로퍼스 설정

### 1단계: 앱 생성

1. Kakao Developers 접속
2. 내 애플리케이션 생성
3. 앱 키에서 `REST API 키` 확인

### 2단계: 플랫폼/Redirect URI

카카오 로그인 설정에서 Redirect URI를 등록한다.

처음 테스트용 추천:

```text
http://localhost:8080/oauth
```

### 3단계: 카카오 로그인 활성화

1. 카카오 로그인 활성화
2. 동의항목에서 `카카오톡 메시지 전송(talk_message)` 설정
3. 필요하면 앱을 개발자 본인 계정으로 테스트 가능하게 둔다.

### 4단계: 인증 URL 만들기

```bash
python3 /Users/jangbogeun/Documents/Codex/2026-06-06/2/outputs/kakao_oauth_helper.py auth-url \
  --rest-api-key "REST_API_KEY" \
  --redirect-uri "http://localhost:8080/oauth"
```

출력된 URL을 브라우저에 붙여넣고 카카오 로그인을 진행한다.

브라우저가 `http://localhost:8080/oauth?code=...` 같은 주소로 이동하면, 주소창의 `code=` 뒤 값을 복사한다.

### 5단계: Refresh Token 받기

```bash
python3 /Users/jangbogeun/Documents/Codex/2026-06-06/2/outputs/kakao_oauth_helper.py exchange-code \
  --rest-api-key "REST_API_KEY" \
  --redirect-uri "http://localhost:8080/oauth" \
  --code "복사한_CODE"
```

출력 JSON에서 `refresh_token`을 저장한다. 토큰은 비밀번호처럼 취급하고 문서에 붙여넣지 않는다.

## 6. 자격증명 저장

권장 방식은 macOS Keychain 저장이다. 토큰을 문서나 CSV에 남기지 않는다.

```bash
python3 /Users/jangbogeun/Documents/Codex/2026-06-06/2/outputs/kakao_keychain_setup.py set
```

프롬프트가 나오면 아래 값을 입력한다.

- `KAKAO_REST_API_KEY`
- `KAKAO_REFRESH_TOKEN`
- `KAKAO_CLIENT_SECRET`: 앱에서 클라이언트 시크릿을 켰을 때만
- `KAKAO_LINK_URL`: 생략 가능

저장 여부 확인:

```bash
python3 /Users/jangbogeun/Documents/Codex/2026-06-06/2/outputs/kakao_keychain_setup.py status
```

터미널에서 임시로만 테스트할 때는 환경변수도 가능하다.

```bash
export KAKAO_REST_API_KEY="REST_API_KEY"
export KAKAO_REFRESH_TOKEN="REFRESH_TOKEN"
export KAKAO_LINK_URL="https://finance.yahoo.com"
```

클라이언트 시크릿을 켠 앱이면 추가:

```bash
export KAKAO_CLIENT_SECRET="CLIENT_SECRET"
```

## 7. 발송 테스트

먼저 dry-run:

```bash
python3 /Users/jangbogeun/Documents/Codex/2026-06-06/2/outputs/send_kakao_memo.py \
  --title "US Equity 테스트" \
  --message "테스트: 카카오 나에게 보내기 연결 확인" \
  --dry-run
```

실제 발송:

```bash
python3 /Users/jangbogeun/Documents/Codex/2026-06-06/2/outputs/send_kakao_memo.py \
  --title "US Equity 테스트" \
  --message "테스트: 카카오 나에게 보내기 연결 확인"
```

성공 시 `{}` 또는 성공 JSON이 출력되고 카카오톡 나와의 채팅방에 메시지가 온다.

## 8. 자주 막히는 지점

- `talk_message` 동의항목이 없으면 메시지를 보낼 수 없다.
- Redirect URI가 앱 설정과 명령어에서 정확히 같아야 한다.
- `code`는 1회용이다. 실패하면 인증 URL부터 다시 진행한다.
- refresh token은 만료/회전될 수 있다. 발송 실패가 반복되면 새로 발급한다.
- `send_kakao_memo.py`는 환경변수를 먼저 보고, 없으면 macOS Keychain의 `codex-us-equity-kakao` 항목을 찾는다.
- 자동화 런타임이 환경변수를 받지 못해도 Keychain 접근이 허용되면 자동 발송이 가능하다.

## 9. 권장 알림 레벨

기본:

- 장전 요약
- 장후 계좌 요약
- 실시간 타이밍 요약

긴급:

- 보유종목 장외 급락/악재
- SOXL/SOXS 1,000만원 현금 준비 경보
- 시장 모드가 공격에서 방어로 급변
- 보유 4-5개 제한 초과로 정리 필요

카카오 메시지는 짧게, 대시보드는 자세히 본다.