주식앱 갤러리

UC-01. 대시보드 진입 — 관심종목·시그널

앱 첫 화면입니다. 상단 탭 6개(관심종목·시그널 / 종목 리스트 / 추천 / 목표가 알림 / 내 포트폴리오 / 계좌·주문) + AI 챗봇 링크로 구성됩니다.

• 관심종목 카드마다 종합 시그널과 4팩터(감성·추세·수급·재무) 점수를 표시합니다.
• 카드는 현재가·5일 변동률·관련 뉴스(호재/악재/중립 라벨)·뉴스 요약을 함께 보여줍니다.
• API: GET /api/v1/watchlist, GET /api/v1/signals/{symbol}

UC-02. 종목 검색 → 시그널 조회

종목명 또는 코드로 검색해 뉴스·추세 종합 시그널을 분석하는 흐름입니다.

• 검색어를 입력하면 자동완성 후보를 내려줍니다. 검색은 findTop20BySymbolContainingIgnoreCase... 라 최대 20건이며, 삼성전자 처럼 이름이 거의 일치하면 1건만 나옵니다.
• API: GET /api/v1/stocks/search?q=

조회를 누르면 해당 종목의 시그널 카드를 렌더링합니다.

UC-03. 관심종목 카드 단일 새로고침

카드별 새로고침 버튼으로 해당 종목 하나만 최신 시그널을 다시 계산합니다. 전체 재조회 없이 필요한 종목만 갱신해 LLM 호출을 줄이는 동작입니다.

• API: GET /api/v1/signals/{symbol}?refresh=true

UC-04. 관심종목 상세 — 가격 예측 + 시그널

/watchlist/{symbol} 상세 화면입니다. 예측 차트와 시그널 카드를 함께 보여줍니다.

• 실제 종가(실선)와 예측(점선), 변동성 밴드(최근 20일 ±1.5σ)를 한 차트에 그립니다.
• 예측 판단 근거를 문장으로 제공합니다 — 4팩터 종합 점수와 밴드 산출 방식을 함께 설명합니다.
• 관련 뉴스는 호재/악재 라벨과 요약으로 정리합니다.
• API: GET /api/v1/signals/{symbol}, GET /api/v1/predictions/{symbol}

UC-05. 전체 종목 리스트 조회

등록된 194개 종목을 실시간 가격과 함께 조회합니다. 페이지당 20개, 총 10페이지입니다.

• 5초마다 가격을 갱신하며(PRICE_POLL_INTERVAL_MS = 5000), 갱신 중에는 ● 실시간 배지를 표시합니다.
• 섹터 열은 내렸습니다 — 토스가 업종을 주지 않아 194종목 전부 결측이었습니다(STK14-15). 소스 확보 후 복원 예정(STK14-18).
• API: GET /api/v1/stocks?page=&size=, GET /api/v1/stocks/prices

다음으로 페이지를 이동합니다.

UC-06. 오늘의 추천 종목

4팩터 시그널을 기반으로 추천 종목을 산출하는 화면입니다.

• TTL 캐시가 신선하면 즉시 표시됩니다(캡쳐 시 5초 내 표시). 캐시가 만료된 첫 조회는 여러 종목을 LLM으로 분석하므로 수십 초가 걸리고, 그동안 “여러 종목 분석 중 (수십 초 소요될 수 있어요)“를 안내합니다.
• 결과는 순위별 카드로 나옵니다. 카드마다 진입가·진입 전략·현재가·5일 변동·감성/추세 점수와 이 진입가로 알림 등록 버튼을 제공합니다.
• 카드 하단에 단기·중기·장기 예측 차트를 탭으로 전환해 볼 수 있습니다.
• API: GET /api/v1/recommendations/enhanced?limit=

UC-07. 목표가 알림

목표가 도달 시 알림을 받는 기능입니다. 활성 알림과 발송 이력을 10초 주기로 갱신합니다.

• 발송 이력은 종목코드·방향·목표가·도달가·메모·발송일시를 보여줍니다 (실 이력 5건).
• API: GET /api/v1/alerts, GET /api/v1/alerts/history

알림 추가 폼에 종목코드·목표가·방향(이상/이하)·메모를 입력합니다. 캡쳐는 입력까지만이며 등록은 실행하지 않았습니다.

• API: POST /api/v1/alerts

UC-08. 내 포트폴리오

수동 입력한 보유 종목의 현재가·손익과 기간별 예측을 확인하는 화면입니다.

• 보유 종목이 없을 때의 빈 상태입니다.
• API: GET /api/v1/portfolio

종목 추가 모달에서 종목명으로 검색해 종목코드를 채우고, 평균단가·수량을 입력합니다. 저장은 실행하지 않았습니다.

• API: GET /api/v1/stocks/search?q=, POST /api/v1/portfolio

UC-09. 계좌·주문 (토스 증권 연동)

토스 증권 계좌를 조회하고 주문을 넣는 화면입니다. 토스는 시장가 주문만 지원하므로 가격 입력 없이 현재 시세로 즉시 체결을 요청합니다.

• 계좌번호는 1500****437 로 마스킹해 한 번만 표시합니다(STK14-05).
• 계좌가 1건이면 자동 선택되고, 예수금 대신 매수가능금액을 보여줍니다 — 계좌 목록 API 는 잔고를 주지 않습니다.
• API: GET /api/v1/accounts

주문 폼에 종목코드·방향(매수/매도)·수량을 입력합니다. 실제 주문이 나가므로 주문하기는 누르지 않았습니다.

• API: POST /api/v1/orders

UC-10. AI 챗봇

종목 시그널을 근거로 묻고 답하는 화면입니다. 조회·분석 전용이며, 관심종목 추가·알림 등록은 대시보드 탭에서 처리합니다 (FE-01로 화면 문구를 실제 기능에 맞게 정정했습니다).

• 경로: /chat → Next.js API 라우트(/api/chat) → BFF POST /api/chat/message
• 호출에 CHAT_API_TOKEN 인증이 필요합니다.

질문을 보내면 시그널 데이터를 근거로 4팩터 표와 종합 판단을 답합니다.

• 답변 근거는 ml이 계산한 시그널을 프롬프트에 사실로 주입한 값입니다 — 결측 팩터는 “없음”으로 표기하고 추측하지 않습니다.
• 분석 요청이 밀려 슬롯을 못 잡으면 무한 대기 대신 “지금 분석 요청이 밀려 있습니다. 잠시 후 다시 물어봐 주세요.”를 즉시 안내합니다.