docs/project_plan.md

# Gradio RAG 챗봇 & LocalPCAgent 제어 웹앱 통합 프로젝트 계획

## 1. 프로젝트 개요

본 프로젝트는 기존에 구현된 RAG 챗봇 애플리케이션과 LocalPCAgent 제어 기능을 가진 웹 애플리케이션을 하나의 통합된 웹 애플리케이션으로 결합하는 작업입니다. 사용자가 단일 웹 인터페이스 내에서 RAG 챗봇과 상호작용하면서 동시에 원격 PC의 프로그램을 실행하거나 상태를 확인하는 등의 제어 기능을 사용할 수 있게 됩니다.

## 2. 프로젝트 현재 상태

### 완료된 작업
- [x] 백엔드 API 확인 및 준비 (app_device_routes.py)
- [x] HTML/CSS UI 요소 추가 (템플릿 수정, CSS 추가)
- [x] JavaScript 코어 유틸리티 모듈 생성 (app-core.js)
- [x] 장치 제어 UI 모듈 생성 (app-device.js)
- [x] 메인 JavaScript 코드 업데이트 (app.js)

### 구성 요소
- **Flask 백엔드**
  - app_revised.py: 메인 Flask 애플리케이션
  - app_routes.py: RAG 챗봇 관련 API 라우트
  - app_device_routes.py: 장치 제어 관련 API 라우트
  - init_retriever.py: RAG 검색기 초기화 관련 코드
  
- **웹 프론트엔드**
  - index.html: 메인 UI 템플릿 (채팅, 문서 관리, 장치 제어 탭 포함)
  - app-core.js: 공통 유틸리티 JavaScript 모듈
  - app-device.js: 장치 제어 관련 JavaScript 모듈
  - app.js: 메인 JavaScript 코드
  - device-style.css: 장치 제어 UI 관련 스타일

## 3. 기능 설명

### RAG 챗봇 기능
- 텍스트 기반 질의응답
- 음성 인식을 통한 질의응답
- 문서 업로드 및 관리
- 다양한 LLM 모델 선택 가능 (OpenAI, DeepSeek 등)

### LocalPCAgent 제어 기능
- 원격 PC 상태 확인
- 실행 가능한 프로그램 목록 조회
- 원격으로 프로그램 실행

## 4. 기술 스택

### 백엔드
- Flask: 웹 서버 및 API 제공
- OpenAI/DeepSeek: LLM 모델 통신
- VITO STT: 음성-텍스트 변환
- 임베딩/검색: RAG 기능 구현

### 프론트엔드
- HTML/CSS/JavaScript: 기본 웹 인터페이스
- Fetch API: 백엔드 통신
- MediaRecorder API: 오디오 녹음

## 5. 통합 아키텍처

### 통합 방식
이 프로젝트는 "Flask 백엔드 + HTML/JavaScript 프론트엔드" 구조로 되어 있습니다. RAG 챗봇과 장치 제어 기능은 다음과 같이 통합되었습니다:

1. **백엔드 통합**
   - app_revised.py에서 RAG 챗봇 라우트(app_routes.py)와 장치 제어 라우트(app_device_routes.py)를 모두 등록
   - 장치 제어는 백엔드에서 LocalPCAgent와 통신 (프록시 패턴)

2. **프론트엔드 통합**
   - 탭 기반 UI로 기능 분리 (채팅, 문서 관리, 장치 제어)
   - 모듈화된 JavaScript 파일로 각 기능 구현
   - 공통 유틸리티 함수는 app-core.js에 통합

### 데이터 흐름
- 사용자 -(요청)-> 웹 UI -(API 호출)-> Flask 백엔드 -(프록시 요청)-> LocalPCAgent/LLM
- LocalPCAgent/LLM -(응답)-> Flask 백엔드 -(JSON 응답)-> 웹 UI -(표시)-> 사용자

## 6. 보안 고려사항

- 모든 API에 `@login_required` 데코레이터 적용하여 인증된 사용자만 접근 가능
- 브라우저에서 직접 LocalPCAgent URL에 접근하지 않고 항상 Flask 백엔드를 통해 접근
- DEVICE_SERVER_URL은 서버 환경변수로만 관리 (클라이언트 코드에 노출 안 함)

## 7. 테스트 방법

### 로컬 테스트
1. LocalPCAgent 서버 실행 및 ngrok URL 확인
2. 환경 변수 설정: `DEVICE_SERVER_URL=<ngrok-url>`
3. Flask 앱 실행: `python app.py`
4. 웹 브라우저에서 `http://localhost:7860` 접속
5. 로그인 후 '장치 제어' 탭 테스트

### 디버깅
- 브라우저 개발자 도구 콘솔: JavaScript 로그 및 오류 확인
- Flask 서버 로그: API 요청 및 응답 확인
- LocalPCAgent 서버 로그: 실제 실행 결과 확인

## 8. 향후 개선 사항

- 장치 제어 로그 저장 및 이력 조회 기능
- 실행 결과 스크린샷 자동 캡처 및 표시
- 실행 프로그램 스케줄링 (예약 실행)
- 더 상세한 오류 처리 및 복구 메커니즘
- 장치 관리 기능과 챗봇의 연동 (채팅으로 장치 제어 명령 내리기)