56 lines
4.2 KiB
Markdown
56 lines
4.2 KiB
Markdown
|
[계획 문서 경로]
|
||
|
|
- 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 컴포넌트.
|
||
|
|
- 삭제:
|
||
|
|
- 없음
|
||
|
|
|
||
|
|
[구현 단계]
|
||
|
|
- [x] 1. KIS 지수 API 라우트 생성 (`app/api/kis/indices/route.ts`): `getDomesticDashboardIndices` 함수를 사용하여 KOSPI, KOSDAQ 지수 정보를 반환하는 GET 엔드포인트를 구현.
|
||
|
|
- [x] 2. 상태 관리 스토어 생성 (`features/layout/stores/market-indices-store.ts`): 지수 데이터, 로딩 상태, 에러 상태를 관리하기 위한 Zustand 스토어를 생성.
|
||
|
|
- [x] 3. 커스텀 훅 생성 (`features/layout/hooks/use-market-indices.ts`): 위에서 만든 API 라우트를 호출하고, 스토어의 상태를 업데이트하는 `useMarketIndices` 훅을 구현.
|
||
|
|
- [x] 4. UI 컴포넌트 생성 (`features/layout/components/market-indices.tsx`): `useMarketIndices` 훅을 사용하여 지수 정보를 받아와 화면에 표시하는 컴포넌트를 생성. 30초마다 데이터를 폴링하는 로직을 포함.
|
||
|
|
- [x] 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: 계획 문서 작성 및 기능 구현 완료.
|