대시보드 실시간 기능 추가

features/dashboard/components/StockDetailPreview.tsx

@@ -1,4 +1,14 @@
-import { BarChartBig, MousePointerClick } from "lucide-react";
+/**
+ * @file StockDetailPreview.tsx
+ * @description 대시보드 우측 영역의 선택 종목 상세 정보 및 실시간 시세 반영 컴포넌트
+ * @remarks
+ * - [레이어] Components / UI
+ * - [사용자 행동] 종목 리스트에서 항목 선택 -> 상세 정보 조회 -> 실시간 시세 변동 확인
+ * - [데이터 흐름] DashboardContainer(realtimeSelectedHolding) -> StockDetailPreview -> Metric(UI)
+ * - [연관 파일] DashboardContainer.tsx, dashboard.types.ts, use-price-flash.ts
+ * @author jihoon87.lee
+ */
+import { BarChartBig, ExternalLink, MousePointerClick } from "lucide-react";
 import {
   Card,
   CardContent,
@@ -6,6 +16,8 @@ import {
   CardHeader,
   CardTitle,
 } from "@/components/ui/card";
+import { useRouter } from "next/navigation";
+import { usePriceFlash } from "@/features/dashboard/hooks/use-price-flash";
 import type { DashboardHoldingItem } from "@/features/dashboard/types/dashboard.types";
 import {
   formatCurrency,
@@ -15,18 +27,30 @@ import {
 import { cn } from "@/lib/utils";
 
 interface StockDetailPreviewProps {
+  /** 선택된 종목 정보 (없으면 null) */
   holding: DashboardHoldingItem | null;
+  /** 현재 총 자산 (비중 계산용) */
   totalAmount: number;
 }
 
 /**
- * @description 선택 종목 상세 요약 카드입니다.
- * @see features/dashboard/components/DashboardContainer.tsx HoldingsList 선택 결과를 전달받아 렌더링합니다.
+ * [컴포넌트] 선택 종목 상세 요약 카드
+ * 대시보드에서 선택된 특정 종목의 매입가, 현재가, 수익률 등 상세 지표를 실시간으로 보여줍니다.
+ *
+ * @param props StockDetailPreviewProps
+ * @see DashboardContainer.tsx - HoldingsList 선택 결과를 실시간 데이터로 전달받아 렌더링
  */
 export function StockDetailPreview({
   holding,
   totalAmount,
 }: StockDetailPreviewProps) {
+  const router = useRouter();
+  // [State/Hook] 실시간 가격 변동 애니메이션 상태 관리
+  // @remarks 종목이 선택되지 않았을 때를 대비해 safe value(0)를 전달하며, 종목 변경 시 효과를 초기화하도록 symbol 전달
+  const currentPrice = holding?.currentPrice ?? 0;
+  const priceFlash = usePriceFlash(currentPrice, holding?.symbol);
+
+  // [Step 1] 종목이 선택되지 않은 경우 초기 안내 화면 렌더링
   if (!holding) {
     return (
       <Card>
@@ -48,29 +72,67 @@ export function StockDetailPreview({
     );
   }
 
+  // [Step 2] 수익/손실 여부에 따른 UI 톤(색상) 결정
   const profitToneClass = getChangeToneClass(holding.profitLoss);
+
+  // [Step 3] 총 자산 대비 비중 계산
   const allocationRate =
-    totalAmount > 0 ? Math.min((holding.evaluationAmount / totalAmount) * 100, 100) : 0;
+    totalAmount > 0
+      ? Math.min((holding.evaluationAmount / totalAmount) * 100, 100)
+      : 0;
 
   return (
     <Card>
+      {/* ========== 카드 헤더: 종목명 및 기본 정보 ========== */}
       <CardHeader className="pb-3">
-        {/* ========== TITLE ========== */}
         <CardTitle className="flex items-center gap-2 text-base">
           <BarChartBig className="h-4 w-4 text-brand-600 dark:text-brand-400" />
           선택 종목 정보
         </CardTitle>
-        <CardDescription>
-          {holding.name} ({holding.symbol}) · {holding.market}
+        <CardDescription className="flex items-center gap-1.5 flex-wrap">
+          <button
+            type="button"
+            onClick={() =>
+              router.push(
+                `/trade?symbol=${holding.symbol}&name=${encodeURIComponent(holding.name)}`,
+              )
+            }
+            className={cn(
+              "group flex items-center gap-1.5 rounded-md border border-brand-200 bg-brand-50 px-2 py-0.5",
+              "text-sm font-bold text-brand-700 transition-all cursor-pointer",
+              "hover:border-brand-400 hover:bg-brand-100 hover:shadow-sm",
+              "dark:border-brand-800/60 dark:bg-brand-900/40 dark:text-brand-400 dark:hover:border-brand-600 dark:hover:bg-brand-900/60",
+            )}
+            title={`${holding.name} 종목 상세 거래로 이동`}
+          >
+            <span className="truncate">{holding.name}</span>
+            <span className="text-[10px] font-medium opacity-70">
+              ({holding.symbol})
+            </span>
+            <ExternalLink className="h-3 w-3 transition-transform group-hover:translate-x-0.5 group-hover:-translate-y-0.5" />
+          </button>
+          <span className="text-xs text-muted-foreground">
+            · {holding.market}
+          </span>
         </CardDescription>
       </CardHeader>
 
       <CardContent className="space-y-4">
-        {/* ========== PRIMARY METRICS ========== */}
+        {/* ========== 실시간 주요 지표 영역 (Grid) ========== */}
         <div className="grid grid-cols-2 gap-2 text-sm">
-          <Metric label="보유 수량" value={`${holding.quantity.toLocaleString("ko-KR")}주`} />
-          <Metric label="매입 평균가" value={`${formatCurrency(holding.averagePrice)}원`} />
-          <Metric label="현재가" value={`${formatCurrency(holding.currentPrice)}원`} />
+          <Metric
+            label="보유 수량"
+            value={`${holding.quantity.toLocaleString("ko-KR")}주`}
+          />
+          <Metric
+            label="매입 평균가"
+            value={`${formatCurrency(holding.averagePrice)}원`}
+          />
+          <Metric
+            label="현재가"
+            value={`${formatCurrency(holding.currentPrice)}원`}
+            flash={priceFlash}
+          />
           <Metric
             label="수익률"
             value={formatPercent(holding.profitRate)}
@@ -87,7 +149,7 @@ export function StockDetailPreview({
           />
         </div>
 
-        {/* ========== ALLOCATION BAR ========== */}
+        {/* ========== 자산 비중 그래프 영역 ========== */}
         <div className="rounded-xl border border-border/70 bg-background/70 p-3">
           <div className="flex items-center justify-between text-xs text-muted-foreground">
             <span>총 자산 대비 비중</span>
@@ -101,7 +163,7 @@ export function StockDetailPreview({
           </div>
         </div>
 
-        {/* ========== QUICK ORDER PLACEHOLDER ========== */}
+        {/* ========== 추가 기능 예고 영역 (Placeholder) ========== */}
         <div className="rounded-xl border border-dashed border-border/80 bg-muted/30 p-3">
           <p className="flex items-center gap-1.5 text-sm font-medium text-foreground/80">
             <MousePointerClick className="h-4 w-4 text-brand-500" />
@@ -117,23 +179,48 @@ export function StockDetailPreview({
 }
 
 interface MetricProps {
+  /** 지표 레이블 */
   label: string;
+  /** 표시될 값 */
   value: string;
+  /** 값 텍스트 추가 스타일 */
   valueClassName?: string;
+  /** 가격 변동 애니메이션 상태 */
+  flash?: { type: "up" | "down"; val: number; id: number } | null;
 }
 
 /**
- * @description 상세 카드에서 공통으로 사용하는 지표 행입니다.
- * @param label 지표명
- * @param value 지표값
- * @param valueClassName 값 텍스트 색상 클래스
- * @see features/dashboard/components/StockDetailPreview.tsx 종목 상세 지표 표시
+ * [컴포넌트] 상세 카드용 개별 지표 아이템
+ * 레이블과 값을 박스 형태로 렌더링하며, 필요한 경우 시세 변동 Flash 애니메이션을 처리합니다.
+ *
+ * @param props MetricProps
+ * @see StockDetailPreview.tsx - 내부 그리드 영역에서 여러 개 호출
  */
-function Metric({ label, value, valueClassName }: MetricProps) {
+function Metric({ label, value, valueClassName, flash }: MetricProps) {
   return (
-    <div className="rounded-xl border border-border/70 bg-background/70 p-3">
+    <div className="relative overflow-hidden rounded-xl border border-border/70 bg-background/70 p-3 transition-colors">
+      {/* 시세 변동 시 나타나는 일시적인 수치 표시 (Flash) */}
+      {flash && (
+        <span
+          key={flash.id}
+          className={cn(
+            "pointer-events-none absolute right-2 top-2 text-xs font-bold animate-in fade-in slide-in-from-bottom-1 fill-mode-forwards duration-300",
+            flash.type === "up" ? "text-red-500" : "text-blue-500",
+          )}
+        >
+          {flash.type === "up" ? "+" : ""}
+          {flash.val.toLocaleString()}
+        </span>
+      )}
+
+      {/* 지표 레이블 및 본체 값 */}
       <p className="text-xs text-muted-foreground">{label}</p>
-      <p className={cn("mt-1 text-sm font-semibold text-foreground", valueClassName)}>
+      <p
+        className={cn(
+          "mt-1 text-sm font-semibold text-foreground transition-colors",
+          valueClassName,
+        )}
+      >
         {value}
       </p>
     </div>