first commit

CLAUDE.md

@@ -0,0 +1,89 @@
+# 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
+```