docs/project_plan.md

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

1. 프로젝트 개요

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

2. 프로젝트 현재 상태

완료된 작업

• 백엔드 API 확인 및 준비 (app_device_routes.py)
• HTML/CSS UI 요소 추가 (템플릿 수정, CSS 추가)
• JavaScript 코어 유틸리티 모듈 생성 (app-core.js)
• 장치 제어 UI 모듈 생성 (app-device.js)
• 메인 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. 향후 개선 사항

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