From 14f5bef1c42d7257891afb083486af5de280cff0 Mon Sep 17 00:00:00 2001 From: yakenator Date: Tue, 24 Feb 2026 04:47:10 +0900 Subject: [PATCH] docs: add detailed README.md with project documentation Co-Authored-By: Claude Opus 4.6 --- README.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 136 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index e215bc4..1d3d966 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,150 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). +# stock-frontend -## Getting Started +한국 주식 분석 플랫폼의 **웹 대시보드**. Next.js 기반으로 APISIX 게이트웨이를 통해 모든 백엔드 서비스의 데이터를 시각화합니다. -First, run the development server: +## 기능 -```bash -npm run dev -# or -yarn dev -# or -pnpm dev -# or -bun dev +- **대시보드**: 서비스 상태, 스크리닝 결과 요약, Stream 통계 실시간 표시 +- **종목 목록**: 검색, KOSPI/KOSDAQ 필터, 시가총액 기준 정렬, 등락률 표시 +- **종목 상세**: 가격 정보, 밸류에이션 지표(PER/PBR/ROE), AI 분석, 공시 목록 +- **스크리닝**: 전략별 스크리닝 실행 트리거 + 결과 테이블 표시 +- **파이프라인 모니터링**: 6개 서비스 상태, Redis Stream 큐 길이, 데이터 흐름도 + +## 페이지 구성 + +| 경로 | 페이지 | 설명 | +|------|--------|------| +| `/` | 대시보드 | 전체 현황, 서비스 상태, 최근 스크리닝 결과 | +| `/stock` | 종목 목록 | 검색, 필터, 종목 카드 그리드 | +| `/stock/[code]` | 종목 상세 | 가격, 밸류에이션, AI 분석, 공시 | +| `/screening` | 스크리닝 | 실행 트리거, 결과 테이블 | +| `/pipeline` | 파이프라인 | 서비스 상태, Stream 모니터링 | + +## 기술 스택 + +| 기술 | 버전 | 용도 | +|------|------|------| +| Next.js | 16.1 | React 프레임워크 (App Router) | +| React | 19.2 | UI 라이브러리 | +| TypeScript | 5.x | 타입 안전성 | +| Tailwind CSS | 4.x | 유틸리티 CSS | +| Lucide React | 0.575 | 아이콘 | +| Recharts | 3.7 | 차트 (향후 사용) | + +## API 클라이언트 + +모든 API 호출은 `src/lib/api.ts`의 타입 안전한 클라이언트를 통해 APISIX 게이트웨이(`/api/v1/...`)로 전달됩니다. + +```typescript +import { fetchStocks, fetchStock, fetchScreeningLatest } from "@/lib/api"; + +// 종목 검색 +const { total, stocks } = await fetchStocks({ search: "삼성", market: "KOSPI" }); + +// 종목 상세 +const detail = await fetchStock("005930"); + +// 스크리닝 결과 +const screening = await fetchScreeningLatest(10); ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +### API 클라이언트 함수 목록 -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. +| 함수 | 게이트웨이 경로 | 설명 | +|------|---------------|------| +| `fetchAllHealth()` | `GET /{svc}/health` | 전체 서비스 헬스체크 | +| `fetchAllStreams()` | `GET /{svc}/streams` | 전체 Stream 정보 | +| `fetchStocks()` | `GET /kis/stocks` | 종목 목록 | +| `fetchStock(code)` | `GET /kis/stocks/{code}` | 종목 상세 | +| `fetchScreeningLatest()` | `GET /screening/results/latest` | 스크리닝 결과 | +| `fetchCatalystResults(code)` | `GET /catalyst/results/{code}` | 공시/카탈리스트 | +| `fetchAnalysisResults(code)` | `GET /analysis/results/{code}` | AI 분석 결과 | +| `triggerScreening()` | `POST /screening/screen` | 스크리닝 실행 | +| `triggerDartFinancials()` | `POST /dart/collect/financials` | DART 수집 | +| `triggerKisCollect()` | `POST /kis/collect/stocks` | KIS 수집 | +| `triggerNewsCrawl()` | `POST /news/collect/news` | 뉴스 수집 | -This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. +## 프로젝트 구조 -## Learn More +``` +stock-frontend/ +├── package.json +├── next.config.ts +├── Dockerfile # 멀티 스테이지 빌드 +├── .dockerignore +├── src/ +│ ├── app/ +│ │ ├── layout.tsx # 루트 레이아웃 (Sidebar 포함) +│ │ ├── page.tsx # 대시보드 +│ │ ├── globals.css # Tailwind 글로벌 스타일 +│ │ ├── pipeline/ +│ │ │ └── page.tsx # 파이프라인 모니터링 +│ │ ├── screening/ +│ │ │ └── page.tsx # 스크리닝 +│ │ └── stock/ +│ │ ├── page.tsx # 종목 목록 +│ │ └── [code]/ +│ │ └── page.tsx # 종목 상세 +│ ├── components/ +│ │ ├── sidebar.tsx # 사이드바 네비게이션 +│ │ └── stat-card.tsx # 통계 카드 컴포넌트 +│ └── lib/ +│ ├── api.ts # 게이트웨이 API 클라이언트 +│ └── types.ts # 공통 타입 정의 +└── public/ +``` -To learn more about Next.js, take a look at the following resources: +## 빠른 시작 -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. +### 로컬 개발 -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! +```bash +npm install +npm run dev +``` -## Deploy on Vercel +`http://localhost:3000`에서 접근 가능. 기본적으로 게이트웨이 `http://localhost:9080/api/v1`에 연결합니다. -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. +### Docker -Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details. +```bash +# stock-gateway의 docker-compose 사용 (권장) +cd ../stock-gateway && docker compose up stock-frontend + +# 단독 빌드 +docker build --build-arg NEXT_PUBLIC_API_URL=http://localhost:9080/api/v1 -t stock-frontend . +docker run -p 3000:3000 stock-frontend +``` + +## 환경변수 + +| 변수 | 설명 | 기본값 | +|------|------|--------| +| `NEXT_PUBLIC_API_URL` | APISIX 게이트웨이 URL | `http://localhost:9080/api/v1` | + +> `NEXT_PUBLIC_*` 변수는 **빌드 타임**에 번들에 포함됩니다. Docker에서는 `ARG`로 빌드 시 주입합니다. + +## Docker 빌드 구조 + +```dockerfile +# Stage 1: 의존성 설치 +FROM node:20-alpine AS deps +RUN npm ci + +# Stage 2: 빌드 (API URL 주입) +FROM node:20-alpine AS builder +ARG NEXT_PUBLIC_API_URL=http://localhost:9080/api/v1 +ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL +RUN npm run build + +# Stage 3: 프로덕션 실행 +FROM node:20-alpine AS runner +COPY --from=builder .next/standalone ./ +CMD ["node", "server.js"] +``` + +## 의존성 + +- Node.js >= 20 +- Next.js 16.1 (App Router, standalone output) +- React 19, TypeScript 5, Tailwind CSS 4