auto-trade/common-docs/improvement/plans/dev-plan-2026-03-04-dashboard-market-hub-and-orderbook-rate.md

[계획 문서 경로]

• common-docs/improvement/plans/dev-plan-2026-03-04-dashboard-market-hub-and-orderbook-rate.md

[요구사항 요약]

• 호가창 각 호가 행에 기준가 대비 퍼센트(등락률)를 추가 표시한다.
• /dashboard 안에서 내 종목/내 재산/주문내역 같은 개인 자산 정보를 별도 메뉴(탭)로 분리한다.
• /dashboard 메인 화면에는 급등주식, 인기종목, 주요 뉴스와 추가 시장 정보 카드를 배치한다.

[가정]

• "메뉴를 하나 새로"는 /dashboard 내부 탭 메뉴(시장 탭/내 자산 탭) 추가로 해석한다.
• 기존 KIS 인증/세션 헤더 체계는 유지하고, 신규 데이터도 동일 헤더로 조회한다.
• 인기종목은 거래량 기준 상위(필요 시 거래대금 기준 포함)로 제공한다.

[영향 범위]

• 수정:
  • features/trade/components/orderbook/orderbook-utils.ts
  • features/trade/components/orderbook/orderbook-sections.tsx
  • features/dashboard/types/dashboard.types.ts
  • features/dashboard/apis/dashboard.api.ts
  • features/dashboard/hooks/use-dashboard-data.ts
  • features/dashboard/components/DashboardContainer.tsx
  • lib/kis/dashboard.ts
• 추가:
  • app/api/kis/domestic/market-hub/route.ts
  • features/dashboard/components/MarketHubSection.tsx
• 삭제:
  • features/dashboard/hooks/use-market-movers-alert.ts

[구현 단계]

• 1. 호가창 퍼센트 표시 로직 추가: 기준가 대비 등락률 계산 유틸을 만들고 호가 행 UI에 퍼센트를 노출한다. (features/trade/components/orderbook/orderbook-utils.ts, features/trade/components/orderbook/orderbook-sections.tsx)
• 2. 대시보드 시장 허브 API 추가: 급등주식/거래량 상위/뉴스(및 보조 지표)를 KIS에서 조회해 단일 응답으로 반환한다. (lib/kis/dashboard.ts, app/api/kis/domestic/market-hub/route.ts)
• 3. 대시보드 데이터 훅 확장: 기존 balance/indices/activity에 market-hub 데이터를 병렬 조회하고 에러 상태를 분리 관리한다. (features/dashboard/hooks/use-dashboard-data.ts, features/dashboard/apis/dashboard.api.ts, features/dashboard/types/dashboard.types.ts)
• 4. /dashboard 메뉴 분리: "시장" 탭과 "내 자산" 탭을 만들고 개인 자산 컴포넌트를 "내 자산" 탭으로 이동한다. (features/dashboard/components/DashboardContainer.tsx)
• 5. 시장 탭 구성: 급등주식, 인기종목, 주요 뉴스, 추가 정보(시장 폭/업다운 카운트)를 카드로 구성한다. (features/dashboard/components/MarketHubSection.tsx)

[사용할 MCP/Skills]

• MCP: next-devtools(런타임 점검), web search(요구사항의 검색 반영)
• Skills: dev-auto-pipeline, dev-plan-writer, dev-mcp-implementation, dev-refactor-polish, dev-test-gate, dev-plan-completion-checker, nextjs-app-router-patterns, vercel-react-best-practices

[참조 문서(common-docs)]

• common-docs/api-reference/openapi_all.xlsx
• common-docs/api-reference/kis_api_reference.md
• common-docs/api-reference/kis-error-code-reference.md
• common-docs/features/trade-stock-sync.md
• common-docs/ui/GLOBAL_ALERT_SYSTEM.md

[주석/문서 반영 계획]

• 함수 주석: [목적]/[사용처]/[데이터 흐름] 중심으로 유지한다.
• 상태 주석: market-hub 로딩/오류 상태가 화면에 미치는 영향 한 줄 주석을 추가한다.
• 복잡 로직: 시장 허브 응답 정규화는 1,2,3 단계 주석으로 분해한다.

[리스크/회귀 포인트]

• KIS 순위/뉴스 API는 파라미터 조합에 따라 빈 응답이 나올 수 있어 폴백 파라미터가 필요하다.
• 신규 시장 API 실패 시에도 기존 내 자산 탭은 정상 동작해야 한다.
• 호가 퍼센트 표시가 모바일에서 줄바꿈/폭 깨짐을 유발할 수 있어 반응형 폭 점검이 필요하다.

[검증 계획]

• 1. lint: 타입/린트 오류 없이 통과하는지 확인. (npm run lint 통과)
• 2. build: Next.js 프로덕션 빌드가 통과하는지 확인. (npm run build 통과)
• 3. 런타임: /dashboard 진입 후 시장 탭/내 자산 탭 전환이 정상 동작하는지 확인. (Playwright MCP에서 탭 전환 및 화면 반영 확인)
• 4. 런타임: 시장 탭에서 급등/인기/뉴스 카드가 실패 시에도 개별 에러 안내로 안전하게 렌더링되는지 확인. (Playwright MCP route abort로 /api/kis/domestic/market-hub 실패 주입 후 Failed to fetch + 빈 카드 안전 렌더링 확인)
• 5. 런타임: /trade 호가창에서 각 가격 행에 퍼센트가 표시되는지 확인. (Playwright MCP로 /dashboard 종목 클릭 이동 후 일반호가 행 ±x.xx% 표기 확인)

[진행 로그]

• 2026-03-04: 계획 문서 작성.
• 2026-03-04: 구현 1~5 완료, npm run lint/npm run build 통과.
• 2026-03-04: 브라우저 스모크 실행 시 /dashboard, /trade, /settings가 비로그인 상태에서 /login으로 리다이렉트되는 동작 확인.
• 2026-03-04: 급등주 미노출 대응(등락률 API 파라미터 폴백 + 거래량 기반 폴백) 적용.
• 2026-03-04: 급락주 데이터 및 급등/급락 주기 알림(60초 갱신 + 3분 쿨다운 모달) 추가.
• 2026-03-04: 요청 반영으로 급등/급락 전역 모달 알림 훅 제거.
• 2026-03-04: KIS 문서/코드 기준 급등·급락 웹소켓 수신 가능성 검토 완료(순위는 REST, WS는 종목 체결/호가 중심).
• 2026-03-04: Playwright MCP로 /dashboard 시장/내 자산 탭 전환 정상 동작 재검증 완료.
• 2026-03-04: Playwright MCP route abort 주입으로 시장 허브 API 실패 시 에러 안내/빈 상태 카드 안전 렌더링 확인.
• 2026-03-04: Playwright MCP로 급등/급락/인기/거래대금 카드 종목 클릭 시 /trade 이동 및 선택 종목 반영 확인.
• 2026-03-04: Playwright MCP로 /trade 일반호가 각 가격 행의 퍼센트(등락률) 표기 확인.

[계획 대비 완료체크]

• 완료: 구현 15, 검증 15
• 부분 완료: 없음
• 미완료: 없음
• 최종 판정: 배포 가능