docs: add detailed README.md with project documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-24 04:47:10 +09:00
parent dab7d0921d
commit 14f5bef1c4
1 changed files with 136 additions and 22 deletions
--- 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