90 lines
3.5 KiB
Markdown
90 lines
3.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
이 파일은 Claude Code(claude.ai/code)가 이 저장소에서 작업할 때 참고하는 가이드입니다.
|
|
|
|
## 명령어
|
|
|
|
```bash
|
|
# 애플리케이션 실행
|
|
go run main.go
|
|
|
|
# 바이너리 빌드
|
|
go build -o stockSearch .
|
|
|
|
# 전체 테스트 실행
|
|
go test ./...
|
|
|
|
# 단일 테스트 실행
|
|
go test -run TestFunctionName ./...
|
|
|
|
# 린트 실행 (golangci-lint 설치 필요)
|
|
golangci-lint run
|
|
```
|
|
|
|
## 작업 방침
|
|
|
|
- 필요한 명령어(빌드, 테스트 등)는 사용자에게 묻지 않고 직접 실행한다.
|
|
- /Users/hayato5246/GolandProjects/stockSearch/kiwoom_api_doc.txt 이 문서는 키움증권 REST API 문서입니다.
|
|
- Bash Commmand 실행 시 묻지 말고 직접 실행하고 테스트 까지 처리해서 확인한다.
|
|
- 코드 수정시 사용자에게 묻지 말고 직접 수정한다.
|
|
|
|
## 언어 설정
|
|
|
|
- 코드 주석은 **한글**로만 작성한다.
|
|
- 사용자에 대한 답변은 가능한 모든 부분을 **한글**로 작성한다.
|
|
|
|
## 프로젝트 정보
|
|
|
|
- **모듈명**: `stocksearch`
|
|
- **Go 버전**: 1.22 이상
|
|
- 키움증권 REST API 기반 주식 시세 웹서비스 (api.kiwoom.com)
|
|
|
|
## 아키텍처
|
|
|
|
```
|
|
main.go → 라우터 설정, WebSocket Hub 고루틴 시작, HTTP 서버 실행
|
|
config/ 환경변수 (.env) 로딩
|
|
models/ 순수 데이터 구조체 (비즈니스 로직 없음)
|
|
services/ 키움 API 클라이언트, 토큰 관리, 캐시, 비즈니스 로직
|
|
handlers/ HTTP 핸들러 (HTML 렌더링 / JSON API / WebSocket)
|
|
websocket/ Hub 패턴 실시간 시세 (1초 Ticker + gorilla/websocket)
|
|
middleware/ 로깅, 패닉 복구
|
|
templates/ Go html/template SSR (layout/base.html 상속)
|
|
static/ Tailwind CSS, Lightweight Charts, WebSocket 클라이언트 JS
|
|
```
|
|
|
|
**레이어 의존성**: `handlers → services → models`, `websocket → services`
|
|
|
|
**템플릿 구조**: 각 페이지별 독립 템플릿 세트 파싱 (content 블록 충돌 방지)
|
|
- `NewPageHandler()`에서 base.html + 각 페이지 html을 별도 ParseFiles로 파싱
|
|
- `render()`에서 `ExecuteTemplate(w, "base.html", data)` 호출
|
|
|
|
## 주요 설계 사항
|
|
|
|
- **토큰 관리**: `services/token_service.go` — 서버 시작 시 토큰 발급, 만료 1시간 전 자동 갱신
|
|
- 응답 필드: `token` (access token), `expires_dt` (YYYYMMDDHHmmss)
|
|
- **캐시**: `services/cache_service.go` — sync.Map 기반 TTL 캐시 (현재가 1초, 차트 5분, 등락률 1분)
|
|
- **WebSocket Hub**: `websocket/hub.go` — 1초 Ticker로 구독 종목 시세 조회 → 클라이언트에 브로드캐스트
|
|
- **Rate Limit**: KiwoomClient에 `golang.org/x/time/rate` 적용 (초당 18건)
|
|
- **관심종목**: 클라이언트 localStorage 저장, WebSocket 실시간 구독
|
|
|
|
## 키움증권 REST API
|
|
|
|
- **기본 URL**: `https://api.kiwoom.com`
|
|
- **공통 요청**: POST, JSON body, 헤더에 `api-id`, `authorization: Bearer {token}`, `cont-yn`, `next-key`
|
|
- **토큰 발급**: `POST /oauth2/token` (appkey + secretkey)
|
|
- **현재가** `ka10001`: `POST /api/dostk/stkinfo` → `cur_prc`, `pred_pre`, `flu_rt`, `trde_qty`, `open_pric`, `high_pric`, `low_pric`, `stk_nm`
|
|
- **체결정보** `ka10003`: `POST /api/dostk/stkinfo` → `cntr_infr[0].cntr_str` (체결강도)
|
|
- **일봉** `ka10005`: `POST /api/dostk/mrkcond` → `stk_ddwkmm[]` (date, open_pric, high_pric, low_pric, close_pric, trde_qty)
|
|
- **등락률순위** `ka10027`: `POST /api/dostk/rkinfo` → `pred_pre_flu_rt_upper[]`
|
|
|
|
## 환경 설정
|
|
|
|
`.env` 파일 (`.gitignore`에 등록됨):
|
|
```
|
|
KIWOOM_APP_KEY=...
|
|
KIWOOM_APP_SECRET=...
|
|
KIWOOM_BASE_URL=https://api.kiwoom.com
|
|
SERVER_PORT=8080
|
|
```
|