170 lines
6.4 KiB
Markdown
170 lines
6.4 KiB
Markdown
# 엔큐톡 프론트엔드 (React + Vite)
|
||
|
||
엔큐톡(ncuetalk)은 다양한 AI 엔진(챗봇·PDF QA·Text-to-SQL 등)을 한 화면에서 사용할 수 있게 해 주는 통합 프론트엔드입니다. 기존 jQuery SPA 구조를 **React 18 / Vite 7** 기반으로 전면 개편하였습니다.
|
||
|
||
## 폴더 구조
|
||
|
||
```
|
||
ncuetalk_frontend/
|
||
├── index.html # Vite 진입점 (root div 및 module script)
|
||
├── style.css # 전역 스타일 – 기존 CSS 그대로 유지
|
||
├── package.json # 의존성 & 스크립트
|
||
├── vite.config.js # Vite 설정
|
||
├── src/ # React 소스 코드
|
||
│ ├── main.jsx # React DOM 마운트
|
||
│ ├── App.jsx # 라우팅·레이아웃 컨테이너
|
||
│ ├── context/
|
||
│ │ └── ToolContext.jsx # 도구 상태 전역 관리(Context API)
|
||
│ ├── components/
|
||
│ │ └── Sidebar.jsx # 좌측 메뉴 바
|
||
│ ├── pages/ # 상단 메뉴별 화면
|
||
│ │ ├── ChatPage.jsx # 채팅 화면(일반/iframe/dev_chatbot)
|
||
│ │ ├── ToolsPage.jsx # 도구 목록/필터/즐겨찾기
|
||
│ │ ├── LecturePage.jsx # 강의 모음(정적)
|
||
│ │ └── CommunityPage.jsx# 커뮤니티(정적)
|
||
│ └── tools/ # 개별 도구 전용 컴포넌트·헬퍼
|
||
│ └── dev_chatbot/
|
||
│ ├── constants.js # 백엔드 API base URL 등
|
||
│ ├── AIService.js # /chat 호출 래퍼
|
||
│ ├── OCRService.js # Tesseract.js 기반 OCR
|
||
│ ├── ChatHandler.js # 파일/OCR 처리 후 AIService 호출
|
||
│ └── ChatInput.jsx # dev_chatbot 전용 채팅 UI
|
||
└── frontend/ # (구)폴더 – iframe 전용 도구의 README만 보관
|
||
├── lims_text2sql/
|
||
└── research_qa/
|
||
```
|
||
|
||
### 주요 흐름
|
||
1. **ToolsPage** 가 `/tools` API를 조회해 카드 목록을 표시
|
||
2. 카드 클릭 → 선택 도구가 `ToolContext` 에 저장되며 `ChatPage` 로 이동
|
||
3. ChatPage
|
||
* dev_chatbot → `DevChatInput` 렌더링 (OCR + 멀티파트 업로드 지원)
|
||
* research_qa / lims_text2sql → 외부 URL을 iframe 으로 임베드
|
||
* 그 외 → 일반 채팅 UI (textarea + API `/chat` 호출)
|
||
|
||
## 환경 변수 설정
|
||
|
||
프로젝트 루트 또는 쉘 설정(`~/.zshrc`)에 다음 값을 지정하세요.
|
||
|
||
```bash
|
||
# OpenAI Key (필수) – 브라우저에서 직접 호출할 때 사용
|
||
OPENAI_API_KEY="sk-..."
|
||
```
|
||
|
||
Vite 설정에서 `envPrefix` 를 `OPENAI_` 로 포함했으므로 `VITE_` 접두어 없이도 노출됩니다.
|
||
|
||
## 실행
|
||
```bash
|
||
nvm install 20
|
||
nvm use 20
|
||
node -v # 20.x 확인
|
||
npm install
|
||
npm run dev # 개발 서버 (http://localhost:5173)
|
||
```
|
||
|
||
## 주요 기능
|
||
1. React 18 + Vite 7 SPA 구조
|
||
2. ChatGPT 도구
|
||
- 모델 선택: GPT-4o(기본), GPT-4.1-mini, o4-mini
|
||
- 긴 한국어 답변 + 이모지 + Markdown 렌더링
|
||
- 입력 후 "생각중… (경과초)" 로딩 표시
|
||
3. 개발챗봇 도구
|
||
- PDF 파일 사이드바(업로드·삭제)
|
||
- 이미지 OCR(Tesseract.js) 지원
|
||
4. 강의·커뮤니티 페이지 정적 콘텐츠 표시
|
||
|
||
## 의존성 주요 목록
|
||
| 라이브러리 | 용도 |
|
||
|------------|------|
|
||
| React 18 | UI |
|
||
| Vite 7 | 번들러 |
|
||
| marked 5 | Markdown → HTML 변환 |
|
||
| tesseract.js| 이미지 OCR |
|
||
|
||
## 빌드 & 미리보기
|
||
```bash
|
||
nvm use 20
|
||
npm ci # (처음/의존성 변경 시 권장) 이미 설치돼 있으면 npm install도 OK
|
||
npm run build
|
||
```
|
||
|
||
## 재빌드
|
||
```bash
|
||
npm run build
|
||
npm run preview # http://localhost:4173
|
||
```
|
||
|
||
|
||
## 프로덕션 배포 (Apache)
|
||
이 프로젝트는 기본적으로 API 호출을 `API_BASE_URL` 기준으로 수행합니다.
|
||
|
||
- `VITE_API_BASE_URL`를 지정하면 해당 주소로 호출합니다.
|
||
- 미지정 시:
|
||
- 개발( `npm run dev` )에서는 `http://localhost:8010`
|
||
- 프로덕션 빌드에서는 **same-origin**(현재 접속한 도메인)으로 호출합니다.
|
||
|
||
즉, Apache로 프론트를 HTTPS로 서비스하는 경우에는 아래처럼 **리버스 프록시**로 백엔드(예: `http://127.0.0.1:8010`)를 연결하는 방식을 권장합니다.
|
||
|
||
### Apache 모듈 활성화
|
||
```bash
|
||
sudo a2enmod proxy proxy_http rewrite
|
||
sudo systemctl reload apache2
|
||
```
|
||
|
||
### VirtualHost 예시 (프론트 정적 + API 프록시)
|
||
```apache
|
||
<VirtualHost *:443>
|
||
ServerName your-domain.com
|
||
|
||
DocumentRoot /var/www/ncuetalk_frontend
|
||
|
||
<Directory /var/www/ncuetalk_frontend>
|
||
AllowOverride All
|
||
Require all granted
|
||
</Directory>
|
||
|
||
# SPA 라우팅
|
||
RewriteEngine On
|
||
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f [OR]
|
||
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -d
|
||
RewriteRule ^ - [L]
|
||
RewriteRule ^ /index.html [L]
|
||
|
||
# Backend reverse proxy (HTTP backend on :8010)
|
||
ProxyPreserveHost On
|
||
ProxyPass /auth http://127.0.0.1:8010/auth
|
||
ProxyPassReverse /auth http://127.0.0.1:8010/auth
|
||
|
||
ProxyPass /community http://127.0.0.1:8010/community
|
||
ProxyPassReverse /community http://127.0.0.1:8010/community
|
||
|
||
ProxyPass /chat http://127.0.0.1:8010/chat
|
||
ProxyPassReverse /chat http://127.0.0.1:8010/chat
|
||
|
||
ProxyPass /tools http://127.0.0.1:8010/tools
|
||
ProxyPassReverse /tools http://127.0.0.1:8010/tools
|
||
</VirtualHost>
|
||
```
|
||
|
||
### 404로 무한 요청이 날 때(중요 체크)
|
||
브라우저 콘솔에 아래처럼 뜨면:
|
||
|
||
- `GET https://talk.ncue.net/community/ai_news ... 404`
|
||
|
||
대부분은 **Apache가 `/community`를 백엔드로 프록시하지 않고**, 프론트 정적 파일에서 해당 경로를 찾으려다 404를 내는 상황입니다.
|
||
|
||
- Apache 설정에 `ProxyPass /community ...`가 **:443 가상호스트에 실제로 적용**되었는지 확인
|
||
- `a2enmod proxy proxy_http` 적용 후 `systemctl reload apache2`
|
||
- SPA rewrite(.htaccess)와 함께 쓴다면, **프록시가 rewrite보다 먼저 적용**되도록 VirtualHost에 ProxyPass를 두는 것을 권장
|
||
|
||
백엔드 엔드포인트가 더 있다면 동일 패턴으로 `ProxyPass`를 추가하거나, `/api` prefix로 백엔드를 묶어 프론트 코드에서 `VITE_API_BASE_URL=/api`로 통일하는 것도 가능합니다.
|
||
|
||
## 빌드 산출물 구조
|
||
프로덕션 빌드시 `dist/` 폴더가 생성되며, 정적 파일을 Nginx·S3 등에 바로 서빙할 수 있습니다.
|
||
|
||
## 기여 & 문의
|
||
Pull Request 환영합니다. 버그·제안은 Issue로 등록해 주세요.
|
||
|
||
---
|
||
© 2025 Daewoong AI Lab – All rights reserved.
|