fix

app/app_routes.py

@@ -1,5 +1,5 @@
 """
-RAG 검색 챗봇 웹 애플리케이션 - API 라우트 정의
+RAG 검색 챗봇 웹 애플리케이션 - API 라우트 정의 (수정 제안 포함)
 """
 
 import os
@@ -7,6 +7,7 @@ import json
 import logging
 import tempfile
 import requests
+import time # 앱 시작 시간 기록 위해 추가
 from flask import request, jsonify, render_template, send_from_directory, session, redirect, url_for
 from datetime import datetime
 from werkzeug.utils import secure_filename
@@ -14,10 +15,13 @@ from werkzeug.utils import secure_filename
 # 로거 가져오기
 logger = logging.getLogger(__name__)
 
-def register_routes(app, login_required, llm_interface, retriever, stt_client, DocumentProcessor, base_retriever, app_ready, ADMIN_USERNAME, ADMIN_PASSWORD, DEVICE_SERVER_URL):
+# 앱 시작 시간 기록 (모듈 로드 시점)
+APP_START_TIME = time.time()
+
+def register_routes(app, login_required, llm_interface, retriever, stt_client, DocumentProcessor, base_retriever, app_ready_flag, ADMIN_USERNAME, ADMIN_PASSWORD, DEVICE_SERVER_URL):
     """Flask 애플리케이션에 기본 라우트 등록"""
-    
-    # 헬퍼 함수
+
+    # 헬퍼 함수 (변경 없음)
     def allowed_audio_file(filename):
         """파일이 허용된 오디오 확장자를 가지는지 확인"""
         ALLOWED_AUDIO_EXTENSIONS = {'mp3', 'wav', 'ogg', 'm4a'}
@@ -28,6 +32,7 @@ def register_routes(app, login_required, llm_interface, retriever, stt_client, D
         ALLOWED_DOC_EXTENSIONS = {'txt', 'md', 'pdf', 'docx', 'csv'}
         return '.' in filename and filename.rsplit('.', 1)[1].lower() in ALLOWED_DOC_EXTENSIONS
 
+    # --- 로그인/로그아웃 라우트 (큰 문제 없음, 로깅 강화) ---
     @app.route('/login', methods=['GET', 'POST'])
     def login():
         error = None
@@ -40,41 +45,37 @@ def register_routes(app, login_required, llm_interface, retriever, stt_client, D
             username = request.form.get('username', '')
             password = request.form.get('password', '')
             logger.info(f"입력된 사용자명: {username}")
-            logger.info(f"비밀번호 입력 여부: {len(password) > 0}")
+            # logger.info(f"비밀번호 입력 여부: {len(password) > 0}") # 실제 비밀번호 로깅은 보안상 좋지 않음
 
-            # 환경 변수 또는 기본값과 비교
             valid_username = ADMIN_USERNAME
             valid_password = ADMIN_PASSWORD
             logger.info(f"검증용 사용자명: {valid_username}")
-            logger.info(f"검증용 비밀번호 존재 여부: {valid_password is not None and len(valid_password) > 0}")
+            # logger.info(f"검증용 비밀번호 존재 여부: {valid_password is not None and len(valid_password) > 0}")
 
             if username == valid_username and password == valid_password:
                 logger.info(f"로그인 성공: {username}")
-                # 세션 설정 전 현재 세션 상태 로깅
-                logger.debug(f"세션 설정 전: {session}")
+                # logger.debug(f"세션 설정 전: {session}") # 디버그 레벨로 변경
 
-                # 세션에 로그인 정보 저장
                 session.permanent = True
                 session['logged_in'] = True
                 session['username'] = username
-                session.modified = True
+                # session.modified = True # Flask는 세션 변경 시 자동으로 modified 플래그를 설정하므로 명시적 호출 불필요
 
-                logger.info(f"세션 설정 후: {session}")
-                logger.info("세션 설정 완료, 리디렉션 시도")
+                logger.info(f"세션 설정 완료: {session}")
 
-                # 로그인 성공 후 리디렉션
                 redirect_to = next_url or url_for('index')
                 logger.info(f"리디렉션 대상: {redirect_to}")
                 response = redirect(redirect_to)
+                # 세션 쿠키가 제대로 설정되도록 응답 반환 전 확인 (디버깅용)
+                logger.debug(f"로그인 응답 헤더 (Set-Cookie 확인): {response.headers.getlist('Set-Cookie')}")
                 return response
             else:
                 logger.warning("로그인 실패: 아이디 또는 비밀번호 불일치")
-                if username != valid_username: logger.warning("사용자명 불일치")
-                if password != valid_password: logger.warning("비밀번호 불일치")
+                # 실패 원인 상세 로깅은 보안 위험 소지가 있으므로 주의
                 error = '아이디 또는 비밀번호가 올바르지 않습니다.'
-        else:
+        else: # GET 요청
             logger.info("로그인 페이지 GET 요청")
-            if 'logged_in' in session:
+            if session.get('logged_in'): # .get() 사용이 더 안전
                 logger.info("이미 로그인된 사용자, 메인 페이지로 리디렉션")
                 return redirect(url_for('index'))
 
@@ -85,40 +86,49 @@ def register_routes(app, login_required, llm_interface, retriever, stt_client, D
     @app.route('/logout')
     def logout():
         """로그아웃 처리"""
-        if 'logged_in' in session:
-            username = session.get('username', 'unknown')
-            logger.info(f"사용자 {username} 로그아웃 처리 시작")
-            session.pop('logged_in', None)
-            session.pop('username', None)
-            session.modified = True
-            logger.info(f"세션 정보 삭제 완료. 현재 세션: {session}")
+        username = session.get('username', 'unknown') # 먼저 사용자 이름 가져오기
+        if session.pop('logged_in', None): # pop으로 제거 시도 및 성공 여부 확인
+             session.pop('username', None)
+             # session.modified = True # pop 사용 시 자동 처리됨
+             logger.info(f"사용자 {username} 로그아웃 처리 완료. 현재 세션: {session}")
         else:
-            logger.warning("로그인되지 않은 상태에서 로그아웃 시도")
+             logger.warning("로그인되지 않은 상태에서 로그아웃 시도")
 
         logger.info("로그인 페이지로 리디렉션")
         response = redirect(url_for('login'))
+        # 로그아웃 시 쿠키 삭제 확인 (디버깅용)
+        logger.debug(f"로그아웃 응답 헤더 (Set-Cookie 확인): {response.headers.getlist('Set-Cookie')}")
         return response
 
-
+    # --- 메인 페이지 및 상태 확인 ---
     @app.route('/')
     @login_required
     def index():
         """메인 페이지"""
-        nonlocal app_ready
-        
-        # 앱 준비 상태 확인 - 30초 이상 지났으면 강제로 ready 상태로 변경
-        current_time = datetime.now()
-        start_time = datetime.fromtimestamp(os.path.getmtime(__file__))
-        time_diff = (current_time - start_time).total_seconds()
-        
-        if not app_ready and time_diff > 30:
-            logger.warning(f"앱이 30초 이상 초기화 중 상태입니다. 강제로 ready 상태로 변경합니다.")
-            app_ready = True
-        
-        if not app_ready:
-            logger.info("앱이 아직 준비되지 않아 로딩 페이지 표시")
-            return render_template('loading.html'), 503  # 서비스 준비 안됨 상태 코드
-        
+        # app_ready_flag는 register_routes 호출 시점의 값으로 고정됨.
+        # 실시간 상태를 반영하려면 app.py의 전역 변수를 직접 참조하거나 다른 방법 필요.
+        # 여기서는 전달받은 플래그를 사용한다고 가정.
+
+        # !! 중요: app_ready_flag는 register_routes 시점의 값입니다.
+        # 실시간 상태를 보려면 app.py의 app_ready 변수를 직접 참조해야 합니다.
+        # 예: from app import app_ready (순환 참조 문제 없을 경우)
+        # 여기서는 일단 전달된 값 사용
+        is_ready = app_ready_flag.is_set() if isinstance(app_ready_flag, threading.Event) else app_ready_flag # Event 객체 또는 bool 가정
+
+        # 앱 시작 후 경과 시간 계산 (파일 수정 시간 대신 실제 시작 시간 사용)
+        time_elapsed = time.time() - APP_START_TIME
+
+        # 30초 강제 Ready 로직 제거 또는 수정 권장
+        # if not is_ready and time_elapsed > 30:
+        #     logger.warning(f"앱이 {time_elapsed:.1f}초 이상 초기화 중 상태입니다. (강제 Ready 로직 비활성화됨)")
+            # app_ready = True # 전역 변수를 직접 수정해야 함
+
+        if not is_ready:
+            logger.info(f"앱이 아직 준비되지 않아 로딩 페이지 표시 (경과 시간: {time_elapsed:.1f}초)")
+            # 503 대신 로딩 페이지를 정상적으로 보여주는 것이 사용자 경험에 더 좋을 수 있음
+            return render_template('loading.html') # 503 대신 200 OK와 로딩 페이지
+            # return render_template('loading.html'), 503 # 기존 로직
+
         logger.info("메인 페이지 요청")
         return render_template('index.html')
 
@@ -127,22 +137,31 @@ def register_routes(app, login_required, llm_interface, retriever, stt_client, D
     @login_required
     def app_status():
         """앱 초기화 상태 확인 API"""
-        logger.info(f"앱 상태 확인 요청: {'Ready' if app_ready else 'Not Ready'}")
-        return jsonify({"ready": app_ready})
-
+        is_ready = app_ready_flag.is_set() if isinstance(app_ready_flag, threading.Event) else app_ready_flag
+        logger.info(f"앱 상태 확인 요청: {'Ready' if is_ready else 'Not Ready'}")
+        return jsonify({"ready": is_ready})
 
+    # --- LLM API (큰 문제 없어 보임, 방어 코드 추가) ---
     @app.route('/api/llm', methods=['GET', 'POST'])
     @login_required
     def llm_api():
         """사용 가능한 LLM 목록 및 선택 API"""
-        if not app_ready:
-            return jsonify({"error": "앱이 아직 초기화 중입니다. 잠시 후 다시 시도해주세요."}), 503
+        is_ready = app_ready_flag.is_set() if isinstance(app_ready_flag, threading.Event) else app_ready_flag
+        if not is_ready:
+             # LLM API는 초기화 중이어도 목록 조회는 가능하게 할 수 있음 (선택적)
+             # return jsonify({"error": "앱이 아직 초기화 중입니다. 잠시 후 다시 시도해주세요."}), 503
+             pass # 일단 진행 허용
 
         if request.method == 'GET':
             logger.info("LLM 목록 요청")
             try:
-                current_details = llm_interface.get_current_llm_details() if hasattr(llm_interface, 'get_current_llm_details') else {"id": "unknown", "name": "Unknown"}
-                supported_llms_dict = llm_interface.SUPPORTED_LLMS if hasattr(llm_interface, 'SUPPORTED_LLMS') else {}
+                # llm_interface 객체 존재 및 속성 확인 강화
+                if llm_interface is None or not hasattr(llm_interface, 'get_current_llm_details') or not hasattr(llm_interface, 'SUPPORTED_LLMS'):
+                     logger.error("LLM 인터페이스가 준비되지 않았거나 필요한 속성이 없습니다.")
+                     return jsonify({"error": "LLM 인터페이스 오류"}), 500
+
+                current_details = llm_interface.get_current_llm_details()
+                supported_llms_dict = llm_interface.SUPPORTED_LLMS
                 supported_list = [{
                     "name": name, "id": id, "current": id == current_details.get("id")
                 } for name, id in supported_llms_dict.items()]
@@ -152,7 +171,7 @@ def register_routes(app, login_required, llm_interface, retriever, stt_client, D
                     "current_llm": current_details
                 })
             except Exception as e:
-                logger.error(f"LLM 정보 조회 오류: {e}")
+                logger.error(f"LLM 정보 조회 오류: {e}", exc_info=True) # exc_info 추가
                 return jsonify({"error": "LLM 정보 조회 중 오류 발생"}), 500
 
         elif request.method == 'POST':
@@ -164,8 +183,10 @@ def register_routes(app, login_required, llm_interface, retriever, stt_client, D
             logger.info(f"LLM 변경 요청: {llm_id}")
 
             try:
-                if not hasattr(llm_interface, 'set_llm') or not hasattr(llm_interface, 'llm_clients'):
-                    raise NotImplementedError("LLM 인터페이스에 필요한 메소드/속성 없음")
+                # llm_interface 객체 존재 및 속성 확인 강화
+                if llm_interface is None or not hasattr(llm_interface, 'set_llm') or not hasattr(llm_interface, 'llm_clients') or not hasattr(llm_interface, 'get_current_llm_details'):
+                     logger.error("LLM 인터페이스가 준비되지 않았거나 필요한 속성/메소드가 없습니다.")
+                     return jsonify({"error": "LLM 인터페이스 오류"}), 500
 
                 if llm_id not in llm_interface.llm_clients:
                     return jsonify({"error": f"지원되지 않는 LLM ID: {llm_id}"}), 400
@@ -186,18 +207,20 @@ def register_routes(app, login_required, llm_interface, retriever, stt_client, D
                 logger.error(f"LLM 변경 처리 중 오류: {e}", exc_info=True)
                 return jsonify({"error": f"LLM 변경 중 오류 발생: {str(e)}"}), 500
 
-
+    # --- Chat API (retriever None 체크 수정) ---
     @app.route('/api/chat', methods=['POST'])
     @login_required
     def chat():
         """텍스트 기반 채봇 API"""
-        # 수정된 부분: app_ready 체크 제거하고 retriever가 None일 때 오류 대신 메시지 반환
-        if retriever is None:
-            logger.warning("채팅 API 요청시 retriever가 None임")
+        # retriever 객체가 None인지, 그리고 search 메소드가 있는지 확인
+        if retriever is None or not hasattr(retriever, 'search'):
+            logger.warning("채팅 API 요청 시 retriever가 준비되지 않았거나 search 메소드가 없습니다.")
+            # 503 대신 사용자 친화적인 메시지 반환
             return jsonify({
-                "answer": "죄송합니다. 검색기가 아직 초기화 중입니다. 잠시 후 다시 시도해주세요.",
-                "sources": []
-            })
+                "answer": "죄송합니다. 검색 엔진이 아직 준비되지 않았습니다. 잠시 후 다시 시도해주세요.",
+                "sources": [],
+                "error": "Retriever not ready" # 클라이언트에서 구분할 수 있도록 추가
+            }), 200 # 또는 503
 
         try:
             data = request.get_json()
@@ -208,22 +231,24 @@ def register_routes(app, login_required, llm_interface, retriever, stt_client, D
             logger.info(f"텍스트 쿼리 수신: {query[:100]}...")
 
             # RAG 검색 수행
-            if not hasattr(retriever, 'search'):
-                raise NotImplementedError("Retriever에 search 메소드가 없습니다.")
-            search_results = retriever.search(query, top_k=5, first_stage_k=6)
+            search_results = retriever.search(query, top_k=5, first_stage_k=6) # first_stage_k��� base_retriever에 전달될 수 있음
 
             # 컨텍스트 준비
-            if not hasattr(DocumentProcessor, 'prepare_rag_context'):
-                raise NotImplementedError("DocumentProcessor에 prepare_rag_context 메소드가 없습니다.")
-            context = DocumentProcessor.prepare_rag_context(search_results, field="text")
+            if DocumentProcessor is None or not hasattr(DocumentProcessor, 'prepare_rag_context'):
+                 logger.error("DocumentProcessor가 준비되지 않았거나 prepare_rag_context 메소드가 없습니다.")
+                 return jsonify({"error": "문서 처리기 오류"}), 500
+            context = DocumentProcessor.prepare_rag_context(search_results, field="text") # 'text' 필드가 있다고 가정
 
             if not context:
-                logger.warning("검색 결과가 없어 컨텍스트를 생성하지 못함.")
+                logger.warning(f"쿼리 '{query[:50]}...'에 대한 검색 결과 없음.")
+                # 컨텍스트 없이 LLM 호출 시도 또는 기본 응답 반환 결정 필요
+                # 여기서는 LLM 호출 로직에서 처리하도록 함
 
             # LLM에 질의
-            llm_id = data.get('llm_id', None)
-            if not hasattr(llm_interface, 'rag_generate'):
-                raise NotImplementedError("LLMInterface에 rag_generate 메소드가 없습니다.")
+            llm_id = data.get('llm_id', None) # 요청에서 llm_id 가져오기
+            if llm_interface is None or not hasattr(llm_interface, 'rag_generate'):
+                 logger.error("LLM 인터페이스가 준비되지 않았거나 rag_generate 메소드가 없습니다.")
+                 return jsonify({"error": "LLM 인터페이스 오류"}), 500
 
             if not context:
                 answer = "죄송합니다. 관련 정보를 찾을 수 없습니다."
@@ -232,7 +257,7 @@ def register_routes(app, login_required, llm_interface, retriever, stt_client, D
                 answer = llm_interface.rag_generate(query, context, llm_id=llm_id)
                 logger.info(f"LLM 응답 생성 완료 (길이: {len(answer)})")
 
-            # 소스 정보 추출 (CSV ID 추출 로직 포함)
+            # 소스 정보 추출 (기존 로직 유지, 방어 코드 강화)
             sources = []
             if search_results:
                 for result in search_results:
@@ -240,14 +265,21 @@ def register_routes(app, login_required, llm_interface, retriever, stt_client, D
                         logger.warning(f"예상치 못한 검색 결과 형식: {type(result)}")
                         continue
 
-                    if "source" in result:
-                        source_info = {
-                            "source": result.get("source", "Unknown"),
-                            "score": result.get("rerank_score", result.get("score", 0))
-                        }
+                    source_info = {}
+                    source_key = result.get("source") # Langchain Document 호환성 위해 metadata도 확인
+                    if not source_key and "metadata" in result and isinstance(result["metadata"], dict):
+                        source_key = result["metadata"].get("source")
+
+                    if source_key:
+                        source_info["source"] = source_key
+                        source_info["score"] = result.get("rerank_score", result.get("score", 0))
 
-                        # CSV 파일 특정 처리
-                        if "text" in result and result.get("filetype") == "csv":
+                        # CSV ID 추출 로직
+                        filetype = result.get("filetype")
+                        if not filetype and "metadata" in result and isinstance(result["metadata"], dict):
+                            filetype = result["metadata"].get("filetype")
+
+                        if "text" in result and filetype == "csv":
                             try:
                                 text_lines = result["text"].strip().split('\n')
                                 if text_lines:
@@ -255,9 +287,9 @@ def register_routes(app, login_required, llm_interface, retriever, stt_client, D
                                     if ',' in first_line:
                                         first_column = first_line.split(',')[0].strip()
                                         source_info["id"] = first_column
-                                        logger.debug(f"CSV 소스 ID 추출: {first_column} from {source_info['source']}")
+                                        # logger.debug(f"CSV 소스 ID 추출: {first_column} from {source_info['source']}")
                             except Exception as e:
-                                logger.warning(f"CSV 소스 ID 추출 실패 ({result.get('source')}): {e}")
+                                logger.warning(f"CSV 소스 ID 추출 실패 ({source_info.get('source')}): {e}")
 
                         sources.append(source_info)
 
@@ -273,33 +305,27 @@ def register_routes(app, login_required, llm_interface, retriever, stt_client, D
             logger.error(f"채팅 처리 중 오류 발생: {e}", exc_info=True)
             return jsonify({"error": f"처리 중 오류가 발생했습니다: {str(e)}"}), 500
 
-
+    # --- Voice Chat API (retriever, stt_client None 체크 강화) ---
     @app.route('/api/voice', methods=['POST'])
     @login_required
     def voice_chat():
         """음성 챗 API 엔드포인트"""
-        if not app_ready:
-            logger.warning("앱 초기화가 완료되지 않았지만 음성 API 요청 처리 시도")
-            # 여기서 바로 리턴하지 않고 계속 진행
-            # 사전 검사: retriever와 stt_client가 제대로 초기화되었는지 확인
-
-        if retriever is None:
-            logger.error("retriever가 아직 초기화되지 않았습니다")
-            return jsonify({
-                "transcription": "(음성을 텍스트로 변환했지만 검색 엔진이 아직 준비되지 않았습니다)",
-                "answer": "죄송합니다. 검색 엔진이 아직 초기화 중입니다. 잠시 후 다시 시도해주세요.",
-                "sources": []
-            })
-        # 또는 필수 컴포넌트가 없을 때만 특별 응답 반환
-        if stt_client is None:
-            return jsonify({
-                "transcription": "(음성 인식 기능이 준비 중입니다)",
-                "answer": "죄송합니다. 현재 음성 인식 서비스가 초기화 중입니다. 잠시 후 다시 시도해주세요.",
-                "sources": []
-            })
+        # 필수 컴포넌트 확인
+        if retriever is None or not hasattr(retriever, 'search'):
+            logger.error("음성 API 요청 시 retriever가 준비되지 않음")
+            return jsonify({"error": "검색 엔진 준비 안됨"}), 503
+        if stt_client is None or not hasattr(stt_client, 'transcribe_audio'):
+            logger.error("음성 API 요청 시 STT 클라이언트가 준비되지 않음")
+            return jsonify({"error": "음성 인식 서비스 준비 안됨"}), 503
+        if llm_interface is None or not hasattr(llm_interface, 'rag_generate'):
+             logger.error("음성 API 요청 시 LLM 인터페이스가 준비되지 않음")
+             return jsonify({"error": "LLM 인터페이스 오류"}), 500
+        if DocumentProcessor is None or not hasattr(DocumentProcessor, 'prepare_rag_context'):
+             logger.error("음성 API 요청 시 DocumentProcessor가 준비되지 않음")
+             return jsonify({"error": "문서 처리기 오류"}), 500
 
         logger.info("음성 챗 요청 수신")
-        
+
         if 'audio' not in request.files:
             logger.error("오디오 파일이 제공되지 않음")
             return jsonify({"error": "오디오 파일이 제공되지 않았습니다."}), 400
@@ -308,57 +334,40 @@ def register_routes(app, login_required, llm_interface, retriever, stt_client, D
         logger.info(f"수신된 오디오 파일: {audio_file.filename} ({audio_file.content_type})")
 
         try:
-            # 오디오 파일 처리
-            # 임시 파일 사용 고려 (메모리 부담 줄이기 위해)
-            with tempfile.NamedTemporaryFile(delete=True) as temp_audio:
+            # 오디오 파일 임시 저장 및 처리
+            with tempfile.NamedTemporaryFile(delete=True, suffix=os.path.splitext(audio_file.filename)[1]) as temp_audio:
                 audio_file.save(temp_audio.name)
                 logger.info(f"오디오 파일을 임시 저장: {temp_audio.name}")
-                # VitoSTT.transcribe_audio 가 파일 경로 또는 바이트를 받을 수 있도록 구현되어야 함
-                # 여기서는 파일 경로를 사용한다고 가정
-                if not hasattr(stt_client, 'transcribe_audio'):
-                    raise NotImplementedError("STT 클라이언트에 transcribe_audio 메소드가 없습니다.")
-
-                # 파일 경로로 전달 시
-                # stt_result = stt_client.transcribe_audio(temp_audio.name, language="ko")
-                # 바이트로 전달 시
+
+                # STT 수행 (바이트 또는 경로 전달)
+                # 예: 바이트 전달
                 with open(temp_audio.name, 'rb') as f_bytes:
                     audio_bytes = f_bytes.read()
-                stt_result = stt_client.transcribe_audio(audio_bytes, language="ko")
-
+                stt_result = stt_client.transcribe_audio(audio_bytes, language="ko") # VitoSTT가 바이트를 받는다고 가정
 
             if not isinstance(stt_result, dict) or not stt_result.get("success"):
                 error_msg = stt_result.get("error", "알 수 없는 STT 오류") if isinstance(stt_result, dict) else "STT 결과 형식 오류"
                 logger.error(f"음성인식 실패: {error_msg}")
-                return jsonify({
-                    "error": "음성인식 실패",
-                    "details": error_msg
-                }), 500
+                return jsonify({"error": "음성인식 실패", "details": error_msg}), 500
 
             transcription = stt_result.get("text", "")
             if not transcription:
                 logger.warning("음성인식 결과가 비어있습니다.")
-                return jsonify({"error": "음성에서 텍스트를 인식하지 못했습니다.", "transcription": ""}), 400
+                # 빈 텍스트라도 응답 구조는 유지
+                return jsonify({
+                    "transcription": "",
+                    "answer": "음성에서 텍스트를 인식하지 못했습니다.",
+                    "sources": [],
+                    "llm": llm_interface.get_current_llm_details() if hasattr(llm_interface, 'get_current_llm_details') else {}
+                }), 200 # 400 대신 200 OK와 메시지
 
             logger.info(f"음성인식 성공: {transcription[:50]}...")
-            if retriever is None:
-                logger.error("STT 성공 후 검색 시도 중 retriever가 None임")
-                return jsonify({
-                    "transcription": transcription,
-                    "answer": "음성을 인식했지만, 현재 검색 시스템이 준비되지 않았습니다. 잠시 후 다시 시도해주세요.",
-                    "sources": []
-                })
-            # --- 이후 로직은 /api/chat과 거의 동일 ---
-            # RAG 검색 수행
+
+            # --- 이후 로직은 /api/chat과 동일 ---
             search_results = retriever.search(transcription, top_k=5, first_stage_k=6)
             context = DocumentProcessor.prepare_rag_context(search_results, field="text")
 
-            if not context:
-                logger.warning("음성 쿼리에 대한 검색 결과 없음.")
-                # answer = "죄송합니다. 관련 정보를 찾을 수 없습니다." (아래 LLM 호출 로직에서 처리)
-                pass
-
-            # LLM 호출
-            llm_id = request.form.get('llm_id', None) # 음성 요청은 form 데이터로 LLM ID 받을 수 있음
+            llm_id = request.form.get('llm_id', None) # form 데이터에서 llm_id 가져오기
             if not context:
                 answer = "죄송합니다. 관련 정보를 찾을 수 없습니다."
                 logger.info("컨텍스트 없이 기본 응답 생성")
@@ -366,201 +375,243 @@ def register_routes(app, login_required, llm_interface, retriever, stt_client, D
                 answer = llm_interface.rag_generate(transcription, context, llm_id=llm_id)
                 logger.info(f"LLM 응답 생성 완료 (길이: {len(answer)})")
 
-
-            # 소스 정보 추출
-            enhanced_sources = []
+            # 소스 정보 추출 (chat API와 동일 로직 사용)
+            sources = []
             if search_results:
-                for doc in search_results:
-                    if not isinstance(doc, dict): continue # A
-                    if "source" in doc:
-                        source_info = {
-                            "source": doc.get("source", "Unknown"),
-                            "score": doc.get("rerank_score", doc.get("score", 0))
-                        }
-                        if "text" in doc and doc.get("filetype") == "csv":
-                            try:
-                                text_lines = doc["text"].strip().split('\n')
-                                if text_lines:
-                                    first_line = text_lines[0].strip()
-                                    if ',' in first_line:
-                                        first_column = first_line.split(',')[0].strip()
-                                        source_info["id"] = first_column
-                            except Exception as e:
-                                logger.warning(f"[음성챗] CSV 소스 ID 추출 실패 ({doc.get('source')}): {e}")
-                        enhanced_sources.append(source_info)
+                 for result in search_results:
+                     if not isinstance(result, dict): continue
+                     source_info = {}
+                     source_key = result.get("source")
+                     if not source_key and "metadata" in result and isinstance(result["metadata"], dict):
+                         source_key = result["metadata"].get("source")
+                     if source_key:
+                         source_info["source"] = source_key
+                         source_info["score"] = result.get("rerank_score", result.get("score", 0))
+                         filetype = result.get("filetype")
+                         if not filetype and "metadata" in result and isinstance(result["metadata"], dict):
+                             filetype = result["metadata"].get("filetype")
+                         if "text" in result and filetype == "csv":
+                             try:
+                                 text_lines = result["text"].strip().split('\n')
+                                 if text_lines:
+                                     first_line = text_lines[0].strip()
+                                     if ',' in first_line:
+                                         first_column = first_line.split(',')[0].strip()
+                                         source_info["id"] = first_column
+                             except Exception as e:
+                                 logger.warning(f"[음성챗] CSV 소스 ID 추출 실패 ({source_info.get('source')}): {e}")
+                         sources.append(source_info)
 
             # 최종 응답
             response_data = {
                 "transcription": transcription,
                 "answer": answer,
-                "sources": enhanced_sources,
+                "sources": sources,
                 "llm": llm_interface.get_current_llm_details() if hasattr(llm_interface, 'get_current_llm_details') else {}
             }
             return jsonify(response_data)
 
         except Exception as e:
             logger.error(f"음성 챗 처리 중 오류 발생: {e}", exc_info=True)
-            return jsonify({
-                "error": "음성 처리 중 내부 오류 발생",
-                "details": str(e)
-            }), 500
-
+            return jsonify({"error": "음성 처리 중 내부 오류 발생", "details": str(e)}), 500
 
+    # --- Document Upload API (base_retriever None 체크 강화) ---
     @app.route('/api/upload', methods=['POST'])
     @login_required
     def upload_document():
         """지식베이스 문서 업로드 API"""
-        if not app_ready or base_retriever is None:
-            return jsonify({"error": "앱/기본 검색기가 아직 초기화 중입니다."}), 503
+        # base_retriever 객체 및 필수 메소드 확인
+        if base_retriever is None or not hasattr(base_retriever, 'add_documents') or not hasattr(base_retriever, 'save'):
+            logger.error("문서 업로드 API 요청 시 base_retriever가 준비되지 않았거나 필수 메소드가 없습니다.")
+            return jsonify({"error": "기본 검색기가 준비되지 않았습니다."}), 503
 
         if 'document' not in request.files:
             return jsonify({"error": "문서 파일이 제공되지 않았습니다."}), 400
 
         doc_file = request.files['document']
-        if doc_file.filename == '':
+        if not doc_file or not doc_file.filename: # 파일 존재 및 파일명 확인
             return jsonify({"error": "선택된 파일이 없습니다."}), 400
 
         if not allowed_doc_file(doc_file.filename):
-            logger.error(f"허용되지 않는 파일 형식: {doc_file.filename}")
+            ALLOWED_DOC_EXTENSIONS = {'txt', 'md', 'pdf', 'docx', 'csv'} # 여기서 다시 정의 필요
+            logger.warning(f"허용되지 않는 파일 형식: {doc_file.filename}")
             return jsonify({"error": f"허용되지 않는 파일 형식입니다. 허용: {', '.join(ALLOWED_DOC_EXTENSIONS)}"}), 400
 
         try:
             filename = secure_filename(doc_file.filename)
-            filepath = os.path.join(app.config['DATA_FOLDER'], filename)
+            # DATA_FOLDER가 app.config에 설정되어 있다고 가정
+            data_folder = app.config.get('DATA_FOLDER', os.path.join(os.path.dirname(__file__), '..', 'data')) # 기본값 설정
+            os.makedirs(data_folder, exist_ok=True) # 폴더 없으면 생성
+            filepath = os.path.join(data_folder, filename)
+
             doc_file.save(filepath)
             logger.info(f"문서 저장 완료: {filepath}")
 
-            # 문서 처리 (인코딩 처리 포함)
-            try:
-                with open(filepath, 'r', encoding='utf-8') as f:
-                    content = f.read()
-            except UnicodeDecodeError:
-                logger.info(f"UTF-8 디코딩 실패, CP949로 시도: {filename}")
-                try:
-                    with open(filepath, 'r', encoding='cp949') as f:
-                        content = f.read()
-                except Exception as e_cp949:
-                    logger.error(f"CP949 디코딩 실패 ({filename}): {e_cp949}")
-                    return jsonify({"error": "파일 인코딩을 읽을 수 없습니다 (UTF-8, CP949 시도 실패)."}), 400
-            except Exception as e_read:
-                logger.error(f"파일 읽기 오류 ({filename}): {e_read}")
-                return jsonify({"error": f"파일 읽기 중 오류 발생: {str(e_read)}"}), 500
-
-
-            # 메타데이터 및 문서 분할/처리
-            metadata = {
-                "source": filename, "filename": filename,
-                "filetype": filename.rsplit('.', 1)[1].lower(),
-                "filepath": filepath
-            }
-            file_ext = metadata["filetype"]
+            # 문서 처리 (DocumentProcessor 객체 및 메소드 확인)
+            if DocumentProcessor is None or not hasattr(DocumentProcessor, 'csv_to_documents') or not hasattr(DocumentProcessor, 'text_to_documents'):
+                 logger.error("DocumentProcessor가 준비되지 않았거나 필요한 메소드가 없습니다.")
+                 # 이미 저장된 파일 삭제 고려
+                 try: os.remove(filepath)
+                 except OSError: pass
+                 return jsonify({"error": "문서 처리기 오류"}), 500
+
+            content = None
+            file_ext = filename.rsplit('.', 1)[1].lower()
+            metadata = {"source": filename, "filename": filename, "filetype": file_ext, "filepath": filepath}
             docs = []
 
-            if not hasattr(DocumentProcessor, 'csv_to_documents') or not hasattr(DocumentProcessor, 'text_to_documents'):
-                raise NotImplementedError("DocumentProcessor에 필요한 메소드 없음")
-
-            if file_ext == 'csv':
-                logger.info(f"CSV 파일 처리 시작: {filename}")
-                docs = DocumentProcessor.csv_to_documents(content, metadata) # 행 단위 처리 가정
-            else: # 기타 텍스트 기반 문서
-                logger.info(f"일반 텍스트 문서 처리 시작: {filename}")
-                # PDF, DOCX 등은 별도 라이브러리(pypdf, python-docx) 필요
-                if file_ext in ['pdf', 'docx']:
-                    logger.warning(f".{file_ext} 파일 처리는 현재 구현되지 않았습니다. 텍스트 추출 로직 추가 필요.")
-                    # 여기에 pdf/docx 텍스트 추출 로직 추가
-                    # 예: content = extract_text_from_pdf(filepath)
-                    # content = extract_text_from_docx(filepath)
-                    # 임시로 비워둠
-                    content = ""
-
-                if content: # 텍스트 내용이 있을 때만 처리
+            # 텍스트 기반 파일 읽기 (인코딩 처리 포함)
+            if file_ext in ['txt', 'md', 'csv']:
+                try:
+                    with open(filepath, 'r', encoding='utf-8') as f:
+                        content = f.read()
+                except UnicodeDecodeError:
+                    logger.info(f"UTF-8 디코딩 실패, CP949로 시도: {filename}")
+                    try:
+                        with open(filepath, 'r', encoding='cp949') as f:
+                            content = f.read()
+                    except Exception as e_cp949:
+                        logger.error(f"CP949 디코딩 실패 ({filename}): {e_cp949}")
+                        return jsonify({"error": "파일 인코딩을 읽을 수 없습니다 (UTF-8, CP949 시도 실패)."}), 400
+                except Exception as e_read:
+                    logger.error(f"파일 읽기 오류 ({filename}): {e_read}")
+                    return jsonify({"error": f"파일 읽기 중 오류 발생: {str(e_read)}"}), 500
+            # PDF/DOCX 처리 로직 (별도 라이브러리 필요)
+            elif file_ext == 'pdf':
+                 logger.warning("PDF 처리는 구현되지 않았습니다.")
+                 # content = extract_text_from_pdf(filepath) # 예시
+            elif file_ext == 'docx':
+                 logger.warning("DOCX 처리는 구현되지 않았습니다.")
+                 # content = extract_text_from_docx(filepath) # 예시
+
+            # 문서 분할/처리
+            if content is not None: # 내용이 성공적으로 읽혔을 때만
+                if file_ext == 'csv':
+                    logger.info(f"CSV 파일 처리 시작: {filename}")
+                    docs = DocumentProcessor.csv_to_documents(content, metadata)
+                elif file_ext in ['txt', 'md']: # 기타 텍스트
+                    logger.info(f"텍스트 문서 처리 시작: {filename}")
                     docs = DocumentProcessor.text_to_documents(
                         content, metadata=metadata,
-                        chunk_size=512, chunk_overlap=50
+                        chunk_size=512, chunk_overlap=50 # 설정값 사용
                     )
+                # PDF/DOCX에서 추출된 content 처리 로직 추가 가능
 
-            # 검색기에 문서 추가 및 인덱스 저장
+            # 검색기에 추가 및 저장
             if docs:
-                if not hasattr(base_retriever, 'add_documents') or not hasattr(base_retriever, 'save'):
-                    raise NotImplementedError("기본 검색기에 add_documents 또는 save 메소드 없음")
-
                 logger.info(f"{len(docs)}개 문서 청크를 검색기에 추가합니다...")
                 base_retriever.add_documents(docs)
 
-                # 인덱스 저장 (업로드마다 저장 - 비효율적일 수 있음)
                 logger.info(f"검색기 상태를 저장합니다...")
-                index_path = app.config['INDEX_PATH']
+                index_path = app.config.get('INDEX_PATH', os.path.join(data_folder, 'index')) # 기본값 설정
+                os.makedirs(os.path.dirname(index_path), exist_ok=True) # 인덱스 폴더 없으면 생성
                 try:
                     base_retriever.save(index_path)
                     logger.info("인덱스 저장 완료")
-                    # 재순위화 검색기도 업데이트 필요 시 로직 추가
-                    # 예: retriever.update_base_retriever(base_retriever)
+                    # TODO: 재순위화 검색기(retriever) 업데이트 로직 필요 시 추가
                     return jsonify({
                         "success": True,
                         "message": f"파일 '{filename}' 업로드 및 처리 완료 ({len(docs)}개 청크 추가)."
                     })
                 except Exception as e_save:
-                    logger.error(f"인덱스 저장 중 오류 발생: {e_save}")
+                    logger.error(f"인덱스 저장 중 오류 발생: {e_save}", exc_info=True)
+                    # 저장 실패 시 추가된 문서 롤백 고려?
                     return jsonify({"error": f"인덱스 저장 중 오류: {str(e_save)}"}), 500
             else:
                 logger.warning(f"파일 '{filename}'에서 처리할 내용이 없거나 지원되지 않는 형식입니다.")
-                # 파일은 저장되었으므로 성공으로 간주할지 결정 필요
+                # 파일은 저장되었으므로 warning 반환
                 return jsonify({
-                    "warning": True,
-                    "message": f"파일 '{filename}'이 저장되었지만 처리할 내용이 없습니다."
+                    "warning": True, # 'success' 대신 'warning' 사용
+                    "message": f"파일 '{filename}'이 저장되었지만 처리할 내용이 없거나 지원되지 않는 형식입니다."
                 })
 
         except Exception as e:
             logger.error(f"파일 업로드 또는 처리 중 오류 발생: {e}", exc_info=True)
+            # 오류 발생 시 저장된 파일 삭제 고려
+            if 'filepath' in locals() and os.path.exists(filepath):
+                try: os.remove(filepath)
+                except OSError: pass
             return jsonify({"error": f"파일 업로드 중 오류: {str(e)}"}), 500
 
-
+    # --- Document List API (오류 원인 분석 필요) ---
     @app.route('/api/documents', methods=['GET'])
     @login_required
     def list_documents():
         """지식베이스 문서 목록 API"""
-        # app_ready 검사 제거 - 문서 목록 불러오기는 항상 허용
+        # !! 중요: 이 API가 503을 반환하는 원인을 찾아야 함 !!
+        # 현재 코드 상으로는 base_retriever가 None일 때 503이 아닌 빈 목록을 반환함.
+        # 503 오류는 이 함수 실행 *전* 단계(예: 다른 데코레이터, 미들웨어, Flask 내부 오류)
+        # 또는 base_retriever 접근 시 발생하는 예외 처리 과정에서 나올 가능성 있음.
+
+        logger.info("문서 목록 API 요청 시작") # 로그 추가
+
+        # base_retriever 상태 상세 로깅
         if base_retriever is None:
-            logger.warning("문서 API 요청시 base_retriever가 None임")
+            logger.warning("문서 API 요청 시 base_retriever가 None입니다.")
+            # 503 대신 빈 목록 반환 (의도된 동작)
             return jsonify({"documents": [], "total_documents": 0, "total_chunks": 0})
+        elif not hasattr(base_retriever, 'documents'):
+             logger.warning("문서 API 요청 시 base_retriever에 'documents' 속성이 없습니다.")
+             return jsonify({"documents": [], "total_documents": 0, "total_chunks": 0})
+
+        logger.info(f"base_retriever 객체 타입: {type(base_retriever)}")
+        logger.info(f"base_retriever.documents 존재 여부: {hasattr(base_retriever, 'documents')}")
+        if hasattr(base_retriever, 'documents'):
+             logger.info(f"base_retriever.documents 타입: {type(base_retriever.documents)}")
+             logger.info(f"base_retriever.documents 길이: {len(base_retriever.documents) if isinstance(base_retriever.documents, list) else 'N/A'}")
+
 
         try:
             sources = {}
             total_chunks = 0
-            # base_retriever.documents 와 같은 속성이 실제 클래스에 있다고 가정
-            if hasattr(base_retriever, 'documents') and base_retriever.documents:
-                logger.info(f"총 {len(base_retriever.documents)}개 문서 청크에서 소스 목록 생성 중...")
-                for doc in base_retriever.documents:
-                    # 문서 청크가 딕셔너리 형태라고 가정
-                    if not isinstance(doc, dict): continue
-
-                    source = doc.get("source", "unknown") # 메타데이터에서 source 가져오기
-                    if source == "unknown" and "metadata" in doc and isinstance(doc["metadata"], dict):
-                        source = doc["metadata"].get("source", "unknown") # Langchain Document 구조 고려
-
-                    if source != "unknown":
-                        if source in sources:
-                            sources[source]["chunks"] += 1
-                        else:
-                            # 메타데이터에서 추가 정보 가져오기
-                            filename = doc.get("filename", source)
-                            filetype = doc.get("filetype", "unknown")
-                            if "metadata" in doc and isinstance(doc["metadata"], dict):
-                                filename = doc["metadata"].get("filename", filename)
-                                filetype = doc["metadata"].get("filetype", filetype)
-
-                            sources[source] = {
-                                "filename": filename,
-                                "chunks": 1,
-                                "filetype": filetype
-                            }
+            doc_list = base_retriever.documents # 속성이 있다고 가정하고 접근
+
+            if not isinstance(doc_list, list):
+                 logger.error(f"base_retriever.documents가 리스트가 아님: {type(doc_list)}")
+                 # 이 경우 500 오류를 반환하거나 빈 목록 반환
+                 return jsonify({"error": "내부 데이터 구조 오류"}), 500
+
+            logger.info(f"총 {len(doc_list)}개 문서 청크에서 소스 목록 생성 중...")
+            for i, doc in enumerate(doc_list):
+                # 각 문서 청크 처리 로깅 추가
+                # logger.debug(f"처리 중인 청크 {i}: {doc}") # 너무 상세하면 주석 처리
+
+                if not isinstance(doc, dict):
+                     logger.warning(f"청크 {i}가 딕셔너리 타입이 아님: {type(doc)}")
+                     continue # 다음 청크로 넘어감
+
+                # 소스 정보 추출 (기존 로직 개선)
+                source = "unknown"
+                metadata = doc.get("metadata") # metadata 먼저 확인 (Langchain Document 구조)
+                if isinstance(metadata, dict):
+                    source = metadata.get("source", "unknown")
+                if source == "unknown": # metadata에 없으면 doc 자체에서 찾기
+                    source = doc.get("source", "unknown")
+
+                if source != "unknown":
+                    if source in sources:
+                        sources[source]["chunks"] += 1
+                    else:
+                        # 메타데이터 우선 사용
+                        filename = metadata.get("filename", source) if isinstance(metadata, dict) else source
+                        filetype = metadata.get("filetype", "unknown") if isinstance(metadata, dict) else "unknown"
+                        # 메타데이터 없으면 doc 자체에서 찾기
+                        if filename == source and "filename" in doc: filename = doc["filename"]
+                        if filetype == "unknown" and "filetype" in doc: filetype = doc["filetype"]
+
+                        sources[source] = {
+                            "filename": filename,
+                            "chunks": 1,
+                            "filetype": filetype
+                        }
                     total_chunks += 1
-            else:
-                logger.info("검색기에 문서가 없거나 documents 속성을 찾을 수 없습니다.")
+                else:
+                     logger.warning(f"청크 {i}에서 소스 정보를 찾을 수 없음: {doc}")
+
 
-            # 목록 형식 변환 및 정렬
+            # 목록 형식 변환 및 정렬 (변경 없음)
             documents = [{"source": src, **info} for src, info in sources.items()]
-            documents.sort(key=lambda x: x["chunks"], reverse=True)
+            documents.sort(key=lambda x: x.get("filename", ""), reverse=False) # 파일명 기준 정렬
 
             logger.info(f"문서 목록 조회 완료: {len(documents)}개 소스 파일, {total_chunks}개 청크")
             return jsonify({
@@ -570,5 +621,51 @@ def register_routes(app, login_required, llm_interface, retriever, stt_client, D
             })
 
         except Exception as e:
-            logger.error(f"문서 목록 조회 중 오류 발생: {e}", exc_info=True)
-            return jsonify({"error": f"문서 목록 조회 중 오류: {str(e)}"}), 500
+            # !! 중요: 여기서 발생하는 예외가 503으로 이어질 수 있는지 확인 !!
+            logger.error(f"문서 목록 조회 중 심각한 오류 발생: {e}", exc_info=True)
+            # 일반적인 내부 오류는 500 반환
+            return jsonify({"error": f"문서 목록 조회 중 오류: {str(e)}"}), 500
+
+```
+
+**주요 문제점 및 수정 제안:**
+
+1.  **`/api/documents` 503 오류의 미스터리:**
+    * 제공된 `list_documents` 함수 코드 자체에는 `app_ready` 상태나 `base_retriever`가 `None`인 상태를 확인하여 503 오류를 반환하는 로직이 **없습니다.** 로그에서 503이 발생했다면, 원인은 다음 중 하나일 가능성이 높습니다:
+        * **실제 실행 중인 코드 불일치:** 현재 서버에서 실행 중인 코드가 제공해주신 코드와 다를 수 있습니다. (예: 이전 버전에 `if not app_ready: return ..., 503` 코드가 남아있음)
+        * **`base_retriever` 접근 오류:** `base_retriever.documents` 속성에 접근하는 과정에서 예기치 않은 오류가 발생하고, Flask의 전역 오류 핸들러나 특정 미들웨어가 이를 503으로 처리할 수 있습니다. (일반적으로는 500 Internal Server Error가 반환됩니다.)
+        * **외부 요인:** 웹 서버(Nginx 등) 설정이나 로드 밸런서 등 Flask 애플리케이션 앞단의 다른 시스템에서 503 오류를 반환할 수도 있습니다.
+    * **수정 제안:**
+        * `list_documents` 함수 시작 부분과 `try...except` 블록 내부에 **더 상세한 로그**를 추가하여 함수 실행 흐름과 `base_retriever` 객체 상태를 명확히 파악합니다. (위 코드에 로깅 추가됨)
+        * 실행 중인 코드가 최신 버전인지 다시 확인합니다.
+        * `base_retriever` 객체 자체 (`VectorRetriever` 클래스)의 `documents` 속성 구현을 확인합니다.
+
+2.  **`app_ready` 상태 관리 및 사용:**
+    * `register_routes` 함수는 앱 시작 시 한 번만 호출되므로, 인자로 전달된 `app_ready` 값은 **호출 시점의 스냅샷**입니다. 백그라운드 스레드가 나중에 `app.py`의 전역 `app_ready` 값을 변경해도 `register_routes` 내부의 지역 변수 `app_ready` (코드에서는 `app_ready_flag`로 명칭 변경 제안)는 업데이트되지 않습니다.
+    * `index` 함수 내에서 `nonlocal app_ready` 사용은 잘못되었습니다. `app_ready`는 전역 변수이므로 `global app_ready`를 사용하거나, 더 좋은 방법은 Flask의 `app.before_request` 데코레이터나 `g` 객체를 사용하여 요청 컨텍스트 내에서 상태를 확인하는 것입니다. 혹은 `threading.Event` 객체를 사용하여 스레드 간 상태를 안전하게 공유할 수 있습니다.
+    * `index` 함수의 30초 강제 Ready 로직은 `os.path.getmtime(__file__)`을 사용하는데, 이는 파일 수정 시간을 기준으로 하므로 앱의 실제 시작 시간과 달라 부정확합니다.
+    * **수정 제안:**
+        * `app.py`에서 `app_ready`를 `threading.Event` 객체로 관리하고, 이를 `register_routes`에 전달합니다. 각 라우트 핸들러에서는 `app_ready_event.is_set()`으로 상태를 확인합니다. (위 코드에 반영됨)
+        * 앱 시작 시간을 모듈 로드 시점에 `time.time()`으로 기록하고, `index` 함수에서 이를 사용하여 경과 시간을 계산합니다. (위 코드에 반영됨)
+        * 30초 강제 Ready 로직은 주석 처리하거나 제거하는 것을 권장합니다. 초기화가 오래 걸리는 근본 원인을 해결하는 것이 좋습니다.
+
+3.  **객체 및 속성 존재 여부 확인 (방어 코드):**
+    * `llm_interface`, `retriever`, `stt_client`, `DocumentProcessor`, `base_retriever` 등의 객체가 None이거나 필요한 메소드/속성(`search`, `transcribe_audio`, `add_documents`, `documents` 등)이 없을 경우 `AttributeError`나 `TypeError`가 발생할 수 있습니다.
+    * **수정 제안:** 각 API 핸들러 시작 부분이나 객체 사용 직전에 해당 객체와 필요한 속성/메소드가 존재하는지 확인하는 방어 코드를 추가합니다. (위 코드에 일부 반영됨)
+
+4.  **오류 로깅:**
+    * `except Exception as e:` 블록에서 `logger.error(f"...", exc_info=True)`를 사용하여 스택 트레이스 전체를 로깅하면 디버깅에 더 유용합니다.
+    * **수정 제안:** 주요 `except` 블록에 `exc_info=True`를 추가합니다. (위 코드에 반영됨)
+
+5.  **`/api/documents` 로직 개선:**
+    * `base_retriever.documents`가 Langchain의 `Document` 객체 리스트일 경우, `source` 등의 정보는 `doc.metadata['source']` 와 같이 접근해야 할 수 있습니다. 현재 코드는 딕셔너리와 Langchain `Document` 구조를 혼용하여 처리하려고 시도하고 있습니다. `base_retriever.documents`의 실제 데이터 구조를 명확히 하고 그에 맞게 코드를 수정해야 합니다.
+    * 문서 목록 정렬 기준을 파일명(`filename`)으로 변경하는 것이 더 직관적일 수 있습니다.
+    * **수정 제안:** `base_retriever.documents`의 구조를 확인하고 `source`, `filename`, `filetype` 추출 로직을 명확히 합니다. 정렬 기준을 `filename`으로 변경했습니다. (위 코드 참조)
+
+**요약 및 다음 단계:**
+
+* `/api/documents`의 503 오류는 현재 코드만으로는 설명하기 어렵습니다. **실행 환경의 코드 버전 확인** 및 **상세 로깅 추가**를 통해 원인을 추적해야 합니다.
+* `app_ready` 상태 관리 방식을 `threading.Event` 등으로 개선하고, `index` 함수의 시간 계산 로직을 수정하는 것이 좋습니다.
+* 코드 전반에 걸쳐 객체 및 속성 존재 여부를 확인하는 방어 코드를 추가하고, 오류 로깅을 강화합니다.
+
+**가장 먼저 브라우저 개발자 도구의 'Network' 탭에서 `/api/documents` 요청의 응답(Response) 본문에 혹시 더 자세한 오류 메시지가 있는지 확인해 보세요