auto-trade/common-docs/improvement/plans/dev-plan-2026-02-26-market-indices-display.md

[계획 문서 경로]

• common-docs/improvement/plans/dev-plan-2026-02-26-market-indices-display.md

[요구사항 요약]

• 메인 레이아웃의 헤더에 KOSPI 및 KOSDAQ 지수를 표시한다.
• 지수에는 현재가, 전일 대비 등락, 등락률이 포함되어야 한다.
• 데이터는 30초마다 자동으로 새로고침되어야 한다.

[가정]

• 사용자는 로그인 상태이며 KIS API 키가 설정되어 있다고 가정한다.
• lib/kis/dashboard.ts의 getDomesticDashboardIndices 함수가 정상 동작한다고 가정한다.

[영향 범위]

• 수정:
  • features/layout/components/header.tsx: MarketIndices 컴포넌트를 추가하고 레이아웃을 조정.
• 추가:
  • app/api/kis/indices/route.ts: KIS 지수 데이터를 조회하는 새로운 API 라우트.
  • features/layout/stores/market-indices-store.ts: 지수 데이터 상태 관리를 위한 Zustand 스토어.
  • features/layout/hooks/use-market-indices.ts: 지수 데이터를 가져오는 커스텀 훅.
  • features/layout/components/market-indices.tsx: 지수 정보를 표시하는 UI 컴포넌트.
• 삭제:
  • 없음

[구현 단계]

• 1. KIS 지수 API 라우트 생성 (app/api/kis/indices/route.ts): getDomesticDashboardIndices 함수를 사용하여 KOSPI, KOSDAQ 지수 정보를 반환하는 GET 엔드포인트를 구현.
• 2. 상태 관리 스토어 생성 (features/layout/stores/market-indices-store.ts): 지수 데이터, 로딩 상태, 에러 상태를 관리하기 위한 Zustand 스토어를 생성.
• 3. 커스텀 훅 생성 (features/layout/hooks/use-market-indices.ts): 위에서 만든 API 라우트를 호출하고, 스토어의 상태를 업데이트하는 useMarketIndices 훅을 구현.
• 4. UI 컴포넌트 생성 (features/layout/components/market-indices.tsx): useMarketIndices 훅을 사용하여 지수 정보를 받아와 화면에 표시하는 컴포넌트를 생성. 30초마다 데이터를 폴링하는 로직을 포함.
• 5. 헤더에 컴포넌트 추가 (features/layout/components/header.tsx): 생성된 MarketIndices 컴포넌트를 헤더 중앙에 추가하고, 로그인 및 blendWithBackground 상태에 따라 노출 여부를 제어.

[사용할 MCP/Skills]

• MCP: 없음
• Skills: dev-plan-writer, dev-mcp-implementation, dev-refactor-polish, dev-test-gate, dev-plan-completion-checker

[참조 문서(common-docs)]

• common-docs/api-reference/kis_api_reference.md

[주석/문서 반영 계획]

• 각 파일 상단에 파일의 목적과 역할을 설명하는 JSDoc 주석을 추가.
• 주요 함수에 파라미터와 반환 값, 역할을 설명하는 주석을 추가.

[리스크/회귀 포인트]

• KIS API 호출 실패 시 에러 처리가 적절히 이루어지지 않으면 UI가 깨지거나 오류 메시지가 표시되지 않을 수 있다.
• 자동 새로고침 로직이 메모리 누수를 일으키지 않도록 useEffect의 cleanup 함수를 정확히 구현해야 한다.

[검증 계획]

• 1. API 라우트 검증: 브라우저나 API 테스트 도구로 /api/kis/indices를 직접 호출하여 정상적인 JSON 응답(지수 데이터, fetchedAt)이 오는지 확인.
• 2. UI 초기 로딩 검증: 페이지 로드 시 MarketIndices 컴포넌트 영역에 스켈레톤 UI가 먼저 표시되는지 확인.
• 3. UI 데이터 표시 검증: 데이터 로딩 완료 후 KOSPI, KOSDAQ 지수 정보(현재가, 등락, 등락률)가 헤더에 정상적으로 표시되는지 확인. 등락에 따라 색상(빨강/파랑)이 올바르게 적용되는지 확인.
• 4. UI 자동 새로고침 검증: 약 30초가 지난 후 fetchedAt 시간이 갱신되며 데이터가 새로고침되는지 네트워크 탭과 화면 표시를 통해 확인.
• 5. 로그아웃/비로그인 상태 검증: 로그아웃하거나 비로그인 상태로 접속했을 때, 지수 컴포넌트가 헤더에 표시되지 않는지 확인.
• 6. 홈 랜딩 페이지 검증: blendWithBackground prop이 true로 설정된 홈 랜딩 페이지에서 지수 컴포넌트가 표시되지 않는지 확인.

[진행 로그]

• 2026-02-26: 계획 문서 작성 및 기능 구현 완료.