AI주식 Spec
화면 경로 /mainPages/stockMarketDashboard · 작성일 2026-10-12 · 수정일 2026-10-24
AI주식 화면의 기능·데이터·권한을 정리한 원본 문서입니다. 도움말(stockMarketDashboard-help.html)의 상세 링크가 이 문서의 각 항목으로 연결됩니다.
A1. 업무 흐름
사용자는 시황에서 관심종목을 정하고, 필요하면 AI 리포트로 요약을 받고, 조건 알림을 걸고, 모의투자로 매매를 연습합니다. 시세 갱신·조건 감시·AI 모의매매는 서버 안 주기 작업이 합니다.
- 사용자① 시황 · 관심종목시황 탭
- 사용자② AI 리포트 · 브리핑AI 리포트 탭
- 사용자③ 시그널 등록시그널 알림 탭
- 시스템④ 조건 감시 · 푸시시그널 크론
- 사용자⑤ 모의 매매모의투자 탭
사용 지점 · 사용 주체 · 목적
| 단계 | 사용 지점 | 사용 주체 | 목적 |
|---|
| ① 시황 | 장 시작 전후, 관심종목 확인 | 로그인 사용자 | 시장 흐름 파악 |
| ② AI 리포트 | 종목을 깊게 보고 싶을 때 | 로그인 사용자 | 지표·포인트·리스크 요약 |
| ③ 시그널 | 특정 가격·등락률을 기다릴 때 | 로그인 사용자 | 조건 도달 알림 |
| ⑤ 모의투자 | 매매를 연습할 때 | 로그인 사용자 | 가상 자금 매매, AI 계좌와 비교 |
진입 경로
| 진입 | 동작 |
|---|
| 메뉴 · 홈 카드 | ?tab= 값에 맞는 탭으로 열림 (없으면 시황) |
A2. 화면 Meta data
| 항목 | 내용 |
|---|
| 화면명 | AI주식 |
| 화면 경로 | /mainPages/stockMarketDashboard?tab=market · report · signal · paper |
| 화면 목적 | 시황 확인, AI 요약, 조건 알림, 모의투자를 한 곳에서 한다 |
| 화면 유형 | 조회+등록 |
| 프로그램 | components/core/client/contents/stockMarketDashboardContent.js, components/core/client/market/MarketDashboard.js · StockReportTab.js · StockSignalTab.js · StockPaperTab.js |
| API 모듈 | pages/api/biz/stockMarket.js (stockMarket.*), /api/market/dashboard |
| 주요 테이블 | TB_STK_CACHE, TB_STK_AI_REPORT, TB_STK_SIGNAL_SUB, TB_STK_SIGNAL_LOG, TB_STK_PAPER_ACCOUNT · ORDER · POSITION · TRADE, TB_STK_AI_PAPER_RUN |
| 도움말 파일 | public/help/stockMarketDashboard-help.html, stockMarketDashboard-spec.html |
A3. 화면 구성 상세
| 영역 | 영역명 | 사용자가 하는 일 | 화면 동작 | backend 동작 |
|---|
| ① | 탭 | 시황·AI 리포트·시그널 알림·모의투자 전환 | 주소의 tab 과 동기화, 전환이 뒤로가기 이력에 남음 | 없음 |
| ② | 시황 | 종목 검색·관심종목, 히트맵·상승/하락·거래량·섹터·뉴스, 차트 기간 선택 | 캐시 데이터면 "캐시 데이터" 표시 | stockMarket.dashboard, symbolSearch |
| ③ | AI 리포트 | 종목 리포트 생성, 관심종목 브리핑, 지난 리포트 보기 | 생성 중 "분석 중…" | stockMarket.reportGenerate, reportList |
| ④ | 시그널 알림 | 조건 추가, 켜기·끄기, 삭제, 최근 발생 확인 | 푸시가 꺼져 있으면 안내 | stockMarket.signalSubscribe · signalToggle · signalDelete · signalList |
| ⑤ | 모의투자 | 매수·매도 주문, 예약 주문 취소, 계좌 초기화, AI 계좌·순위 보기 | 장이 닫혀 있으면 예약 주문으로 표시 | stockMarket.paperState · paperTrade · paperCancelOrder · paperReset · paperLeaderboard · aiPaperState · aiPaperTopPick |
A4. 조회 조건
| 조건 | 입력 유형 | 기본값 | 설명 |
|---|
| 탭 | 탭 (열거형) | 시황 | market · report · signal · paper |
| 종목 검색 | 문자 | 없음 | 종목명 또는 심볼 (예: 삼성전자, AAPL) |
| 차트 기간 | 버튼 (열거형) | - | 1일 · 1주 · 1달 · 3달 · 1년 · 5년 |
시그널 조건 값
| 조건 | 뜻 |
|---|
| 가격 ≥ | 가격이 기준값 이상이 되면 |
| 가격 ≤ | 가격이 기준값 이하가 되면 |
| 상승률 % ≥ | 상승률이 기준값 이상이면 |
| 하락률 % ≥ | 하락률이 기준값 이상이면 |
A5. 표시 항목 정의
데이터 출처: 시세 공급자(Yahoo Finance 우선, 실패 시 Twelve Data), 서버 수집 뉴스, AI 분석 결과.
| 항목 | 의미 | 표시 위치 |
|---|
| 평균 등락률 · 상승/하락 · 총 거래량 | 관심 범위 전체의 요약 | ② |
| 시장 히트맵 · 상승률 TOP · 하락률 TOP · 거래량 TOP · 섹터 성과 | 시장 흐름 | ② |
| 자동 선별 종목 · 점수 | 선별 규칙이 고른 종목과 점수 | ② |
| 최종 갱신 · 데이터 | 마지막 갱신 시각과 공급자 | ② |
| 주요 지표 · 핵심 포인트 · 유의할 리스크 · 참고 맥락 | AI 리포트 내용 | ③ |
| 보유 · 예약 주문 · 거래내역 · 수익률 | 모의 계좌 상태 | ⑤ |
A6. 버튼 동작
| 버튼 (영역) | 누를 수 있을 때 | 결과 | backend 처리 |
|---|
| 새로고침 (②) | 항상 | 시황 다시 조회 | stockMarket.dashboard |
| 리포트 생성 (③) | 종목 선택 + 크레딧 3 이상 | 리포트 표시, 지난 리포트에 추가 | reportGenerate: 3크레딧 차감 |
| 브리핑 받기 (③) | 관심종목 1개 이상 + 크레딧 5 이상 | 관심종목 전체 브리핑 | reportGenerate: 5크레딧 차감 |
| 알림 추가 (④) | 종목·조건·기준값 입력 | 목록에 활성으로 추가 | signalSubscribe |
| 활성 · 중지 / 삭제 (④) | 등록된 알림 | 감시 켜기·끄기, 지우기 | signalToggle, signalDelete |
| 매수 · 매도 (⑤) | 수량 입력, 현금·보유 충분 | 장중이면 체결, 장외면 예약 | paperTrade |
| 주문 취소 (⑤) | 예약 주문 | 예약 취소 (이미 처리된 주문은 불가) | paperCancelOrder |
| 계좌 초기화 (⑤) | 항상 | 확인 후 시작 잔고로 되돌림, 보유·예약·내역 삭제 | paperReset |
A7. 권한과 비용
| 역할 | 시황 | AI 리포트 | 시그널 | 모의투자 |
|---|
| 로그인 사용자 | O | O (크레딧 차감) | O | O (본인 계좌) |
| 로그인 전 | X | X | X | X |
리포트 3크레딧·브리핑 5크레딧이 기본이며 서버 환경변수 STOCK_REPORT_CREDIT_COST · STOCK_BRIEF_CREDIT_COST 로 바꿉니다. 화면에 보이는 크레딧은 서버가 내려준 값입니다. 모든 결과는 정보 제공용이며 투자 자문이 아닙니다.
A8. 상태 변화
모의 주문
주문장외
이 화면예약장 열림 · 시세 확인
서버체결
| 현재 상태 | 이벤트 | 다음 상태 | 조건 |
|---|
| 주문 | 매수 · 매도 | 체결 | 그 시장 정규장 + 시세 확인 |
| 주문 | 매수 · 매도 | 예약 | 장이 닫혀 있음 |
| 예약 | 장 열림 | 체결 | 현금·보유 충분 |
| 예약 | 주문 취소 | 취소 | 아직 처리 전 |
시그널
| 현재 상태 | 이벤트 | 다음 상태 |
|---|
| 활성 | 중지 | 중지 |
| 중지 | 활성 | 활성 |
| 활성 | 조건 도달 (서버) | 활성 + 최근 발생에 기록, 푸시 발송 |
A9. 데이터 연계
| 처리 | 바뀌는 데이터 | 함께 일어나는 일 | 되돌리기 |
|---|
| 시황 조회 | TB_STK_CACHE (30분 캐시) | 만료된 캐시는 바로 보여 주고 뒤에서 갱신 | - |
| 리포트 · 브리핑 생성 | TB_STK_AI_REPORT, 크레딧 원장 | 크레딧 차감 | 불가 |
| 시그널 등록 | TB_STK_SIGNAL_SUB | 서버 시그널 크론이 감시, 도달 시 TB_STK_SIGNAL_LOG 기록과 푸시 | 삭제 |
| 모의 매매 | TB_STK_PAPER_ORDER · POSITION · TRADE · ACCOUNT | 시작 잔고 1억 원(STOCK_PAPER_START_CASH) | 계좌 초기화 |
| AI 모의매매 | AI 계좌(TB_STK_AI_PAPER_RUN 등) | 서버 크론이 30분마다 점검, 시장별 하루 매매 한도 내에서 매매 | - |
주기 작업(시그널 감시·AI 모의매매·뉴스 수집)은 GitHub Actions 가 아니라 Brunner 서버 안 스케줄러가 돌립니다.
개정 이력
| 버전 | 수정일 | 수정 내용 |
|---|
| 1.0 | 2026-10-12 | 최초 작성 |
| 1.1 | 2026-10-24 | Spec 표준 형식으로 재작성(탭별 구성·버튼·크레딧·상태·연계 상세화) |