feat: 파일 업로드 기능 개선 및 Parent Chunk 생성 활성화

- 파일 업로드 시 Parent Chunk 자동 생성 기능 활성화
- 파일 업로드 진행 상황 단계별 표시 기능 추가
- fetch 요청에 credentials: 'include' 추가 (세션 인증)
- 인증 오류 및 리다이렉트 감지 기능 추가
- 요청 타임아웃 5분 설정
- 서버 로그 강화 (타임스탬프, 헤더 등)
- 프로젝트 리팩토링: core, models, prompts, utils 모듈 분리
- .cursorrules 추가 및 코드 구조 개선
- vector_db 바이너리 파일 gitignore 추가

.gitignore

@@ -35,4 +35,7 @@ Thumbs.db
 uploads/*
 !uploads/.gitkeep
 
+# Vector DB
+vector_db/
+
 

app/.cursorrules

@@ -0,0 +1,69 @@
+# Role & Perspective
+You are an expert Python AI Engineer specializing in NLP and LLM integration.
+You are building an "SOY NV AI" that helps users generate plots, characters, and story chapters.
+Your goals are:
+1. Write clean, modular, and asynchronous Python code.
+2. Manage LLM context and tokens efficiently.
+3. Maintain structured data for story elements (Characters, World-building).
+
+# General Guidelines
+- **Python Version**: Use **Python 3.10+** syntax features (e.g., structural pattern matching `match/case`).
+- **Style**: Follow **PEP 8** style guidelines strictly.
+- **Prefer Explicit**: Code should be explicit. Avoid "magic" implicit behaviors.
+- **Modularity**: Break down complex logic into small, pure helper functions.
+- **Language**: All code logic in English, but **Docstrings and Comments must be in Korean**.
+
+# Type Hinting & Safety
+- **Strict Type Hints**: Mandatory for all function arguments, return values, and class attributes.
+- **No `Any`**: Avoid using `Any` unless absolutely necessary.
+- **Data Validation**: Use `pydantic` models for all complex data structures.
+
+# Error Handling
+- Use specific exceptions (e.g., `ValueError`, `KeyError`) instead of bare `except:`.
+- Implement robust error logging using the `logging` module (not `print`).
+- Handle API failures gracefully (e.g., use `tenacity` for retries).
+
+# Libraries & Paths
+- **Path Handling**: ALWAYS use `pathlib` instead of `os.path`.
+- **Environment**: Use `pydantic-settings` or `python-dotenv` to manage secrets. NEVER hardcode API keys.
+
+# Testing (Cost Saving)
+- **Framework**: Use `pytest`.
+- **Mocking**: NEVER call real LLM APIs in unit tests. Use `unittest.mock` or `pytest-mock` to mock responses and save costs.
+- **Fixtures**: Use fixtures for setup/teardown.
+
+# AI & LLM Specific Guidelines
+- **Structured Output**: Always use **Pydantic models** to define schemas for LLM responses.
+- **Prompt Management**: Keep prompt templates separate in `src/prompts/`. Do not embed long strings in code.
+- **Async**: Use `asyncio` for all LLM API calls to prevent blocking the event loop.
+
+# Project Structure (Src Layout)
+Reference this structure. Do not modify existing RAG implementations unless requested.
+
+.
+├── src/
+│   └── novel_assistant/       # Main Package
+│       ├── __init__.py
+│       ├── main.py            # Entry point
+│       ├── core/              # Config, Logger
+│       │   └── config.py
+│       ├── models/            # Pydantic Schemas
+│       │   ├── character.py
+│       │   └── story.py
+│       ├── prompts/           # System prompts & Jinja2 templates
+│       │   ├── templates/
+│       │   └── manager.py
+│       ├── services/          # Business logic
+│       │   ├── generation.py  # Text generation logic
+│       │   └── memory.py      # Context management (Interfaces with existing RAG)
+│       └── utils/             # Helpers
+├── tests/                     # Mirror of src structure
+├── data/                      # Local storage
+├── .env                       # API Keys
+└── pyproject.toml
+
+# Implementation Process (Chain of Thought)
+1. **Define Model**: Start by defining the Pydantic model for the data.
+2. **Draft Prompt**: Check/Create the prompt template.
+3. **Implement**: Write the async service function.
+4. **Mock Test**: Write a test case mocking the API call.

app/__init__.py

@@ -1,122 +1,180 @@
+"""
+Flask 애플리케이션 초기화
+"""
+
 from flask import Flask
 from flask_login import LoginManager
-from app.database import db, User
-import os
 import sqlite3
 from pathlib import Path
+from typing import Optional
+
+from app.database import db, User
+from app.core.config import Config, get_config
+from app.core.logger import get_logger
+
+logger = get_logger(__name__)
 
 login_manager = LoginManager()
 login_manager.login_view = 'main.login'
 login_manager.login_message = '로그인이 필요합니다.'
 login_manager.login_message_category = 'info'
 
+
 @login_manager.user_loader
-def load_user(user_id):
-    return User.query.get(int(user_id))
+def load_user(user_id: str) -> Optional[User]:
+    """
+    사용자 로드 함수 (Flask-Login용)
+    
+    Args:
+        user_id: 사용자 ID (문자열)
+    
+    Returns:
+        User 객체 또는 None
+    """
+    try:
+        return User.query.get(int(user_id))
+    except (ValueError, TypeError):
+        return None
+
 
-def create_app():
-    # 템플릿 폴더 경로 명시적 설정
-    template_folder = os.path.join(os.path.dirname(os.path.abspath(__file__)), '..', 'templates')
+def create_app() -> Flask:
+    """
+    Flask 애플리케이션 팩토리 함수
+    
+    Returns:
+        설정된 Flask 애플리케이션 인스턴스
+    """
+    config = get_config()
+    
+    # 필수 디렉토리 생성
+    config.ensure_directories()
+    
+    # 템플릿 폴더 경로 설정
+    template_folder = str(config.TEMPLATES_FOLDER)
+    
     app = Flask(__name__, template_folder=template_folder)
-    app.config['SECRET_KEY'] = os.getenv('SECRET_KEY', 'dev-secret-key-change-in-production')
-    app.config['SQLALCHEMY_DATABASE_URI'] = os.getenv('DATABASE_URL', 'sqlite:///finance_analysis.db')
-    app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
-    app.config['MAX_CONTENT_LENGTH'] = 100 * 1024 * 1024  # 100MB 파일 크기 제한
     
+    # Flask 설정 적용
+    app.config['SECRET_KEY'] = config.SECRET_KEY
+    app.config['SQLALCHEMY_DATABASE_URI'] = config.SQLALCHEMY_DATABASE_URI
+    app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = config.SQLALCHEMY_TRACK_MODIFICATIONS
+    app.config['MAX_CONTENT_LENGTH'] = config.MAX_CONTENT_LENGTH
+    
+    # 확장 초기화
     db.init_app(app)
     login_manager.init_app(app)
     
+    # Blueprint 등록
     from app.routes import main_bp
     app.register_blueprint(main_bp)
     
+    # 데이터베이스 초기화 및 마이그레이션
     with app.app_context():
         db.create_all()
-        # 데이터베이스 마이그레이션 (nickname 컬럼 추가)
         migrate_database(app)
-        # 초기 관리자 계정 생성
         create_admin_user()
     
+    logger.info("Flask 애플리케이션이 초기화되었습니다.")
+    
     return app
 
-def migrate_database(app):
-    """데이터베이스 마이그레이션"""
+
+def migrate_database(app: Flask) -> None:
+    """
+    데이터베이스 마이그레이션 실행
+    
+    Args:
+        app: Flask 애플리케이션 인스턴스
+    """
     try:
-        # 데이터베이스 URI에서 경로 추출
         db_uri = app.config['SQLALCHEMY_DATABASE_URI']
-        if db_uri.startswith('sqlite:///'):
-            db_path = db_uri.replace('sqlite:///', '')
-            # 상대 경로인 경우 instance 폴더 기준으로 처리
-            if not os.path.isabs(db_path):
-                db_path = os.path.join(app.instance_path, db_path)
-            
-            if not os.path.exists(db_path):
-                print(f"[마이그레이션] 데이터베이스 파일이 없습니다: {db_path}")
-                return
+        
+        if not db_uri.startswith('sqlite:///'):
+            logger.warning(f"SQLite가 아닌 데이터베이스는 자동 마이그레이션이 지원되지 않습니다: {db_uri}")
+            return
+        
+        db_path_str = db_uri.replace('sqlite:///', '')
+        db_path = Path(db_path_str)
+        
+        # 상대 경로인 경우 instance 폴더 기준으로 처리
+        if not db_path.is_absolute():
+            db_path = Path(app.instance_path) / db_path
+        
+        if not db_path.exists():
+            logger.info(f"데이터베이스 파일이 없습니다 (새로 생성됨): {db_path}")
+            return
+        
+        logger.info(f"데이터베이스 마이그레이션 시작: {db_path}")
+        
+        conn = sqlite3.connect(str(db_path))
+        cursor = conn.cursor()
+        
+        # user 테이블에 nickname 컬럼이 있는지 확인
+        cursor.execute("PRAGMA table_info(user)")
+        user_columns = [column[1] for column in cursor.fetchall()]
+        
+        if 'nickname' not in user_columns:
+            logger.info("user 테이블에 nickname 컬럼 추가 중...")
+            cursor.execute("ALTER TABLE user ADD COLUMN nickname VARCHAR(80)")
+            conn.commit()
+            logger.info("user.nickname 컬럼 추가 완료")
+        
+        # uploaded_file 테이블이 존재하는지 확인
+        cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='uploaded_file'")
+        if cursor.fetchone():
+            cursor.execute("PRAGMA table_info(uploaded_file)")
+            uploaded_file_columns = [column[1] for column in cursor.fetchall()]
             
-            conn = sqlite3.connect(db_path)
-            cursor = conn.cursor()
-            
-            # user 테이블에 nickname 컬럼이 있는지 확인
-            cursor.execute("PRAGMA table_info(user)")
-            user_columns = [column[1] for column in cursor.fetchall()]
-            
-            if 'nickname' not in user_columns:
-                print("[마이그레이션] user 테이블에 nickname 컬럼 추가 중...")
-                cursor.execute("ALTER TABLE user ADD COLUMN nickname VARCHAR(80)")
+            if 'uploaded_by' not in uploaded_file_columns:
+                logger.info("uploaded_file 테이블에 uploaded_by 컬럼 추가 중...")
+                cursor.execute("ALTER TABLE uploaded_file ADD COLUMN uploaded_by INTEGER")
                 conn.commit()
-                print("[마이그레이션] user.nickname 컬럼 추가 완료")
-            
-            # uploaded_file 테이블이 존재하는지 확인
-            cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='uploaded_file'")
-            if cursor.fetchone():
-                # uploaded_file 테이블에 uploaded_by 컬럼이 있는지 확인
-                cursor.execute("PRAGMA table_info(uploaded_file)")
-                uploaded_file_columns = [column[1] for column in cursor.fetchall()]
-                
-                if 'uploaded_by' not in uploaded_file_columns:
-                    print("[마이그레이션] uploaded_file 테이블에 uploaded_by 컬럼 추가 중...")
-                    cursor.execute("ALTER TABLE uploaded_file ADD COLUMN uploaded_by INTEGER")
-                    conn.commit()
-                    print("[마이그레이션] uploaded_file.uploaded_by 컬럼 추가 완료")
-                
-                # uploaded_file 테이블에 parent_file_id 컬럼이 있는지 확인
-                if 'parent_file_id' not in uploaded_file_columns:
-                    print("[마이그레이션] uploaded_file 테이블에 parent_file_id 컬럼 추가 중...")
-                    cursor.execute("ALTER TABLE uploaded_file ADD COLUMN parent_file_id INTEGER")
-                    conn.commit()
-                    print("[마이그레이션] uploaded_file.parent_file_id 컬럼 추가 완료")
+                logger.info("uploaded_file.uploaded_by 컬럼 추가 완료")
             
-            # document_chunk 테이블이 존재하는지 확인
-            cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='document_chunk'")
-            if cursor.fetchone():
-                # document_chunk 테이블에 chunk_metadata 컬럼이 있는지 확인
-                cursor.execute("PRAGMA table_info(document_chunk)")
-                document_chunk_columns = [column[1] for column in cursor.fetchall()]
-                
-                if 'chunk_metadata' not in document_chunk_columns:
-                    print("[마이그레이션] document_chunk 테이블에 chunk_metadata 컬럼 추가 중...")
-                    cursor.execute("ALTER TABLE document_chunk ADD COLUMN chunk_metadata TEXT")
-                    conn.commit()
-                    print("[마이그레이션] document_chunk.chunk_metadata 컬럼 추가 완료")
+            if 'parent_file_id' not in uploaded_file_columns:
+                logger.info("uploaded_file 테이블에 parent_file_id 컬럼 추가 중...")
+                cursor.execute("ALTER TABLE uploaded_file ADD COLUMN parent_file_id INTEGER")
+                conn.commit()
+                logger.info("uploaded_file.parent_file_id 컬럼 추가 완료")
+        
+        # document_chunk 테이블이 존재하는지 확인
+        cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='document_chunk'")
+        if cursor.fetchone():
+            cursor.execute("PRAGMA table_info(document_chunk)")
+            document_chunk_columns = [column[1] for column in cursor.fetchall()]
             
-            conn.close()
-            print("[마이그레이션] 데이터베이스 마이그레이션 완료")
+            if 'chunk_metadata' not in document_chunk_columns:
+                logger.info("document_chunk 테이블에 chunk_metadata 컬럼 추가 중...")
+                cursor.execute("ALTER TABLE document_chunk ADD COLUMN chunk_metadata TEXT")
+                conn.commit()
+                logger.info("document_chunk.chunk_metadata 컬럼 추가 완료")
+        
+        conn.close()
+        logger.info("데이터베이스 마이그레이션 완료")
+        
+    except sqlite3.Error as e:
+        logger.error(f"데이터베이스 마이그레이션 중 SQLite 오류 발생: {e}", exc_info=True)
     except Exception as e:
-        print(f"[마이그레이션] 오류 발생: {e}")
-        import traceback
-        traceback.print_exc()
+        logger.error(f"데이터베이스 마이그레이션 중 오류 발생: {e}", exc_info=True)
 
-def create_admin_user():
-    """초기 관리자 계정 생성"""
+
+def create_admin_user() -> None:
+    """
+    초기 관리자 계정 생성
+    """
     admin_username = 'soymedia'
     admin_password = 's0ymedi@1@34'
     
-    admin = User.query.filter_by(username=admin_username).first()
-    if not admin:
-        admin = User(username=admin_username, is_admin=True, is_active=True)
-        admin.set_password(admin_password)
-        db.session.add(admin)
-        db.session.commit()
-        print(f'관리자 계정이 생성되었습니다: {admin_username}')
-
-
+    try:
+        admin = User.query.filter_by(username=admin_username).first()
+        if not admin:
+            admin = User(username=admin_username, is_admin=True, is_active=True)
+            admin.set_password(admin_password)
+            db.session.add(admin)
+            db.session.commit()
+            logger.info(f'관리자 계정이 생성되었습니다: {admin_username}')
+        else:
+            logger.debug(f'관리자 계정이 이미 존재합니다: {admin_username}')
+    except Exception as e:
+        logger.error(f'관리자 계정 생성 중 오류 발생: {e}', exc_info=True)
+        db.session.rollback()

app/core/__init__.py

@@ -0,0 +1,9 @@
+"""
+Core 모듈: 설정 및 로거
+"""
+
+from app.core.config import get_config
+from app.core.logger import get_logger
+
+__all__ = ['get_config', 'get_logger']
+

app/core/config.py

@@ -0,0 +1,61 @@
+"""
+설정 관리 모듈
+환경 변수 및 애플리케이션 설정을 관리합니다.
+"""
+
+import os
+from pathlib import Path
+from typing import Optional
+from dotenv import load_dotenv
+
+# .env 파일 로드
+load_dotenv()
+
+# 프로젝트 루트 디렉토리
+PROJECT_ROOT = Path(__file__).parent.parent.parent
+
+class Config:
+    """애플리케이션 설정 클래스"""
+    
+    # Flask 설정
+    SECRET_KEY: str = os.getenv('SECRET_KEY', 'dev-secret-key-change-in-production')
+    SQLALCHEMY_DATABASE_URI: str = os.getenv(
+        'DATABASE_URL', 
+        f'sqlite:///{PROJECT_ROOT / "instance" / "finance_analysis.db"}'
+    )
+    SQLALCHEMY_TRACK_MODIFICATIONS: bool = False
+    MAX_CONTENT_LENGTH: int = 100 * 1024 * 1024  # 100MB
+    
+    # Ollama 설정
+    OLLAMA_BASE_URL: str = os.getenv('OLLAMA_BASE_URL', 'http://localhost:11434')
+    
+    # 경로 설정
+    UPLOAD_FOLDER: Path = PROJECT_ROOT / 'uploads'
+    VECTOR_DB_PATH: Path = PROJECT_ROOT / 'vector_db'
+    KNOWLEDGE_GRAPH_PATH: Path = PROJECT_ROOT / 'knowledge_graphs'
+    TEMPLATES_FOLDER: Path = PROJECT_ROOT / 'templates'
+    INSTANCE_FOLDER: Path = PROJECT_ROOT / 'instance'
+    
+    # 파일 확장자 설정
+    ALLOWED_EXTENSIONS: set[str] = {'txt', 'md', 'pdf', 'docx', 'epub'}
+    
+    # 임베딩 모델 설정
+    EMBEDDING_MODEL_NAME: str = os.getenv('EMBEDDING_MODEL_NAME', 'sentence-transformers/all-MiniLM-L6-v2')
+    RERANKER_MODEL_NAME: str = os.getenv('RERANKER_MODEL_NAME', 'BAAI/bge-reranker-base')
+    
+    # Gemini API 설정
+    GEMINI_API_KEY: Optional[str] = os.getenv('GEMINI_API_KEY', None)
+    
+    @classmethod
+    def ensure_directories(cls) -> None:
+        """필수 디렉토리 생성"""
+        cls.UPLOAD_FOLDER.mkdir(parents=True, exist_ok=True)
+        cls.VECTOR_DB_PATH.mkdir(parents=True, exist_ok=True)
+        cls.KNOWLEDGE_GRAPH_PATH.mkdir(parents=True, exist_ok=True)
+        cls.INSTANCE_FOLDER.mkdir(parents=True, exist_ok=True)
+
+
+def get_config() -> Config:
+    """설정 인스턴스 반환"""
+    return Config
+

app/core/logger.py

@@ -0,0 +1,65 @@
+"""
+로깅 설정 모듈
+"""
+
+import logging
+import sys
+from pathlib import Path
+from typing import Optional
+
+# 로그 디렉토리
+LOG_DIR = Path(__file__).parent.parent.parent / 'logs'
+LOG_DIR.mkdir(exist_ok=True)
+
+# 로그 포맷
+LOG_FORMAT = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+DATE_FORMAT = '%Y-%m-%d %H:%M:%S'
+
+
+def get_logger(name: str, level: int = logging.INFO) -> logging.Logger:
+    """
+    로거 인스턴스 생성 및 반환
+    
+    Args:
+        name: 로거 이름 (일반적으로 __name__ 사용)
+        level: 로그 레벨 (기본값: INFO)
+    
+    Returns:
+        설정된 로거 인스턴스
+    """
+    logger = logging.getLogger(name)
+    
+    # 이미 핸들러가 설정되어 있으면 기존 로거 반환
+    if logger.handlers:
+        return logger
+    
+    logger.setLevel(level)
+    
+    # 콘솔 핸들러
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(level)
+    console_formatter = logging.Formatter(LOG_FORMAT, datefmt=DATE_FORMAT)
+    console_handler.setFormatter(console_formatter)
+    logger.addHandler(console_handler)
+    
+    # 파일 핸들러 (애플리케이션 로그)
+    file_handler = logging.FileHandler(
+        LOG_DIR / 'app.log',
+        encoding='utf-8'
+    )
+    file_handler.setLevel(logging.DEBUG)
+    file_formatter = logging.Formatter(LOG_FORMAT, datefmt=DATE_FORMAT)
+    file_handler.setFormatter(file_formatter)
+    logger.addHandler(file_handler)
+    
+    # 에러 전용 파일 핸들러
+    error_handler = logging.FileHandler(
+        LOG_DIR / 'error.log',
+        encoding='utf-8'
+    )
+    error_handler.setLevel(logging.ERROR)
+    error_handler.setFormatter(file_formatter)
+    logger.addHandler(error_handler)
+    
+    return logger
+

app/models/__init__.py

@@ -0,0 +1,23 @@
+"""
+Pydantic 모델 정의
+데이터 검증 및 직렬화를 위한 모델들을 정의합니다.
+"""
+
+from app.models.chunk import (
+    ChunkMetadata,
+    ChunkCreate,
+    ChunkResponse,
+)
+from app.models.file import (
+    FileUpload,
+    FileResponse,
+)
+
+__all__ = [
+    'ChunkMetadata',
+    'ChunkCreate',
+    'ChunkResponse',
+    'FileUpload',
+    'FileResponse',
+]
+

app/models/chunk.py

@@ -0,0 +1,50 @@
+"""
+청크 관련 Pydantic 모델
+"""
+
+from typing import Optional, List
+from pydantic import BaseModel, Field
+
+
+class ChunkMetadata(BaseModel):
+    """청크 메타데이터 모델"""
+    
+    pov: Optional[str] = Field(None, description="화자/시점")
+    characters: Optional[List[str]] = Field(default_factory=list, description="등장인물 목록")
+    time_background: Optional[str] = Field(None, description="시간적 배경")
+    chapter: Optional[int] = Field(None, description="챕터 번호")
+    
+    class Config:
+        """Pydantic 설정"""
+        json_schema_extra = {
+            "example": {
+                "pov": "1인칭 주인공",
+                "characters": ["홍길동", "김철수"],
+                "time_background": "현재 시점",
+                "chapter": 1
+            }
+        }
+
+
+class ChunkCreate(BaseModel):
+    """청크 생성 요청 모델"""
+    
+    file_id: int = Field(..., description="파일 ID")
+    chunk_index: int = Field(..., description="청크 인덱스")
+    content: str = Field(..., min_length=1, description="청크 내용")
+    metadata: Optional[ChunkMetadata] = Field(None, description="청크 메타데이터")
+
+
+class ChunkResponse(BaseModel):
+    """청크 응답 모델"""
+    
+    id: int
+    file_id: int
+    chunk_index: int
+    content: str
+    metadata: Optional[ChunkMetadata] = None
+    
+    class Config:
+        """Pydantic 설정"""
+        from_attributes = True
+

app/models/file.py

@@ -0,0 +1,39 @@
+"""
+파일 관련 Pydantic 모델
+"""
+
+from typing import Optional
+from pydantic import BaseModel, Field
+from datetime import datetime
+
+
+class FileUpload(BaseModel):
+    """파일 업로드 요청 모델"""
+    
+    filename: str = Field(..., description="파일명")
+    file_size: int = Field(..., ge=0, description="파일 크기")
+    model_name: Optional[str] = Field(None, description="연결된 모델 이름")
+    parent_file_id: Optional[int] = Field(None, description="부모 파일 ID")
+
+
+class FileResponse(BaseModel):
+    """파일 응답 모델"""
+    
+    id: int
+    filename: str
+    original_filename: str
+    file_size: int
+    model_name: Optional[str] = None
+    uploaded_at: datetime
+    uploaded_by: Optional[int] = None
+    parent_file_id: Optional[int] = None
+    chunk_count: int = 0
+    child_count: int = 0
+    
+    class Config:
+        """Pydantic 설정"""
+        from_attributes = True
+        json_encoders = {
+            datetime: lambda v: v.isoformat()
+        }
+

app/prompts/__init__.py

@@ -0,0 +1,13 @@
+"""
+프롬프트 관리 모듈
+LLM 프롬프트 템플릿을 관리합니다.
+"""
+
+from app.prompts.metadata import get_metadata_extraction_prompt
+from app.prompts.parent_chunk import get_parent_chunk_analysis_prompt
+
+__all__ = [
+    'get_metadata_extraction_prompt',
+    'get_parent_chunk_analysis_prompt',
+]
+

app/prompts/metadata.py

@@ -0,0 +1,39 @@
+"""
+메타데이터 추출 프롬프트
+"""
+
+from typing import Optional
+
+
+def get_metadata_extraction_prompt(
+    chunk_content: str,
+    max_length: int = 2000
+) -> str:
+    """
+    청크 메타데이터 추출을 위한 프롬프트 생성
+    
+    Args:
+        chunk_content: 분석할 청크 내용
+        max_length: 프롬프트에 포함할 최대 텍스트 길이
+    
+    Returns:
+        프롬프트 문자열
+    """
+    content_preview = chunk_content[:max_length]
+    
+    prompt = f"""다음 웹소설 텍스트를 분석하여 아래 정보를 JSON 형식으로만 응답하세요:
+
+텍스트:
+{content_preview}
+
+다음 형식으로만 응답하세요 (JSON 형식):
+{{
+    "pov": "화자/시점을 설명하세요 (예: 1인칭 주인공, 3인칭 전지적 작가 등)",
+    "characters": ["등장인물1", "등장인물2"],
+    "time_background": "시간적 배경 설명 (예: 과거 회상, 현재 시점, 미래 등)"
+}}
+
+응답은 오직 JSON 형식만 사용하고, 다른 설명은 포함하지 마세요."""
+    
+    return prompt
+

app/prompts/parent_chunk.py

@@ -0,0 +1,52 @@
+"""
+Parent Chunk 분석 프롬프트
+"""
+
+from typing import Optional
+
+
+def get_parent_chunk_analysis_prompt(
+    content: str,
+    max_length: int = 8000
+) -> str:
+    """
+    Parent Chunk 분석을 위한 프롬프트 생성
+    
+    Args:
+        content: 분석할 전체 텍스트
+        max_length: 프롬프트에 포함할 최대 텍스트 길이
+    
+    Returns:
+        프롬프트 문자열
+    """
+    content_preview = content[:max_length]
+    is_truncated = len(content) > max_length
+    
+    truncation_note = "\n(참고: 텍스트가 길어 일부만 사용되었습니다.)" if is_truncated else ""
+    
+    prompt = f"""다음 웹소설 텍스트를 분석하여 세계관, 캐릭터, 스토리, 에피소드, 기타 정보를 추출하세요.
+
+텍스트:
+{content_preview}{truncation_note}
+
+다음 형식으로 응답하세요:
+
+## 세계관
+[세계관에 대한 상세 설명]
+
+## 캐릭터
+[주요 캐릭터들의 특징과 배경]
+
+## 스토리
+[주요 스토리 라인과 전개]
+
+## 에피소드
+[주요 에피소드와 사건들]
+
+## 기타
+[기타 중요한 정보]
+
+각 섹션은 상세하고 구조화된 형태로 작성해주세요."""
+    
+    return prompt
+

app/routes.py

@@ -366,7 +366,8 @@ def create_chunks_for_file(file_id, content, extract_metadata=True):
     try:
         print(f"[청크 생성] 파일 ID {file_id}에 대한 청크 생성 시작")
         print(f"[청크 생성] 원본 텍스트 길이: {len(content)}자")
-        print(f"[청크 생성] 메타데이터 추출: {'예' if extract_metadata else '아니오'}")
+        print(f"[청크 생성] 메타데이터 추출: 비활성화됨 (주석 처리)")
+        # print(f"[청크 생성] 메타데이터 추출: {'예' if extract_metadata else '아니오'}")  # 주석 처리됨
         
         # 파일 정보 가져오기 (모델명 등)
         uploaded_file = UploadedFile.query.get(file_id)
@@ -397,40 +398,41 @@ def create_chunks_for_file(file_id, content, extract_metadata=True):
         # 각 청크를 데이터베이스와 벡터 DB에 저장
         saved_count = 0
         vector_saved_count = 0
-        metadata_extracted_count = 0
+        # metadata_extracted_count = 0  # 메타데이터 추출 비활성화로 주석 처리
         
-        if extract_metadata:
-            print(f"[청크 생성] 메타데이터 추출 시작 (AI 사용: {model_name is not None})...")
-        else:
-            print(f"[청크 생성] 메타데이터 추출 건너뜀 (사용자 선택)")
+        # 메타데이터 추출 기능 주석 처리됨
+        # if extract_metadata:
+        #     print(f"[청크 생성] 메타데이터 추출 시작 (AI 사용: {model_name is not None})...")
+        # else:
+        #     print(f"[청크 생성] 메타데이터 추출 건너뜀 (사용자 선택)")
         
         for idx, chunk_content in enumerate(chunks):
             try:
-                # 메타데이터 추출 (옵션이 활성화된 경우에만)
+                # 메타데이터 추출 (옵션이 활성화된 경우에만) - 주석 처리됨
                 metadata = None
                 metadata_json = None
                 
-                if extract_metadata:
-                    metadata = extract_chunk_metadata(
-                        chunk_content=chunk_content,
-                        full_content=content,
-                        chunk_index=idx,
-                        file_id=file_id,
-                        model_name=model_name
-                    )
-                    
-                    # 메타데이터를 JSON 문자열로 변환
-                    metadata_json = json.dumps(metadata, ensure_ascii=False) if metadata else None
-                    
-                    if metadata and (metadata.get("chapter") or metadata.get("pov") or metadata.get("characters") or metadata.get("time_background")):
-                        metadata_extracted_count += 1
+                # if extract_metadata:
+                #     metadata = extract_chunk_metadata(
+                #         chunk_content=chunk_content,
+                #         full_content=content,
+                #         chunk_index=idx,
+                #         file_id=file_id,
+                #         model_name=model_name
+                #     )
+                #     
+                #     # 메타데이터를 JSON 문자열로 변환
+                #     metadata_json = json.dumps(metadata, ensure_ascii=False) if metadata else None
+                #     
+                #     if metadata and (metadata.get("chapter") or metadata.get("pov") or metadata.get("characters") or metadata.get("time_background")):
+                #         metadata_extracted_count += 1
                 
-                # DB에 청크 저장 (메타데이터 포함)
+                # DB에 청크 저장 (메타데이터 없이)
                 chunk = DocumentChunk(
                     file_id=file_id,
                     chunk_index=idx,
                     content=chunk_content,
-                    chunk_metadata=metadata_json
+                    chunk_metadata=None  # 메타데이터 추출 비활성화
                 )
                 db.session.add(chunk)
                 db.session.flush()  # ID 생성
@@ -448,7 +450,7 @@ def create_chunks_for_file(file_id, content, extract_metadata=True):
                 
                 # 진행 상황 출력 (10개마다)
                 if (idx + 1) % 10 == 0:
-                    print(f"[청크 생성] 진행 중: {idx + 1}/{len(chunks)}개 청크 저장 중... (DB: {saved_count}, 벡터 DB: {vector_saved_count}, 메타데이터: {metadata_extracted_count})")
+                    print(f"[청크 생성] 진행 중: {idx + 1}/{len(chunks)}개 청크 저장 중... (DB: {saved_count}, 벡터 DB: {vector_saved_count})")
             except Exception as e:
                 print(f"[청크 생성] 경고: 청크 {idx} 저장 중 오류: {str(e)}")
                 import traceback
@@ -456,7 +458,7 @@ def create_chunks_for_file(file_id, content, extract_metadata=True):
                 continue
         
         db.session.commit()
-        print(f"[청크 생성] 완료: {saved_count}개 청크가 데이터베이스에 저장되었습니다. (벡터 DB: {vector_saved_count}개, 메타데���터 추출: {metadata_extracted_count}개)")
+        print(f"[청크 생성] 완료: {saved_count}개 청크가 데이터베이스에 저장되었습니다. (벡터 DB: {vector_saved_count}개)")
         
         # 저장 확인
         verified_count = DocumentChunk.query.filter_by(file_id=file_id).count()
@@ -1717,18 +1719,24 @@ def upload_file():
     
     # 모든 출력을 즉시 플러시하여 로그가 바로 보이도록
     def log_print(*args, **kwargs):
-        print(*args, **kwargs)
+        from datetime import datetime
+        timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S.%f')[:-3]
+        print(f"[{timestamp}]", *args, **kwargs)
         sys.stdout.flush()
     
     try:
         log_print(f"\n{'='*60}")
         log_print(f"=== 파일 업로드 요청 시작 ===")
+        log_print(f"요청 URL: {request.url}")
         log_print(f"요청 메서드: {request.method}")
         log_print(f"Content-Type: {request.content_type}")
         log_print(f"Content-Length: {request.content_length}")
+        log_print(f"Remote Address: {request.remote_addr}")
+        log_print(f"Headers: {dict(request.headers)}")
         log_print(f"Form 데이터 키: {list(request.form.keys())}")
         log_print(f"Files 키: {list(request.files.keys())}")
-        log_print(f"사용자: {current_user.username if current_user else 'None'}")
+        log_print(f"사용자: {current_user.username if current_user and current_user.is_authenticated else 'None'}")
+        log_print(f"사용자 인증 상태: {current_user.is_authenticated if current_user else False}")
         log_print(f"{'='*60}\n")
         
         # 업로드 폴더 확인 및 생성
@@ -1755,7 +1763,8 @@ def upload_file():
         log_print(f"[2/8] 파일 수신: {file.filename if file else 'None'}")
         log_print(f"[2/8] 모델명: {model_name if model_name else 'None (비어있음)'}")
         log_print(f"[2/8] 이어서 업로드: {parent_file_id if parent_file_id else '아니오'}")
-        log_print(f"[2/8] 메타데이터 추출: {'예' if extract_metadata else '아니오'}")
+        log_print(f"[2/8] 메타데이터 추출: 비활성화됨 (주석 처리)")
+        # log_print(f"[2/8] 메타데이터 추출: {'예' if extract_metadata else '아니오'}")  # 주석 처리됨
         
         if file.filename == '':
             error_msg = '파일명이 없습니다.'
@@ -1917,7 +1926,8 @@ def upload_file():
                         log_print(f"[7/8] CP949 인코딩으로 파일 읽기 성공: {len(content)}자")
                     
                     # 청크 생성 및 저장
-                    log_print(f"[7/8] 청크 생성 함수 호출 중... (메타데이터 추출: {'예' if extract_metadata else '아니오'})")
+                    log_print(f"[7/8] 청크 생성 함수 호출 중... (메타데이터 추출: 비활성화됨)")
+                    # log_print(f"[7/8] 청크 생성 함수 호출 중... (메타데이터 추출: {'예' if extract_metadata else '아니오'})")  # 주석 처리됨
                     chunk_count = create_chunks_for_file(uploaded_file.id, content, extract_metadata=extract_metadata)
                     
                     if chunk_count > 0:
@@ -1928,14 +1938,21 @@ def upload_file():
                         print(f"경고: 파일 {original_filename}에 대한 청크가 생성되지 않았습니다.")
                     
                     # Parent Chunk 생성 (AI 분석)
-                    log_print(f"[7/9] Parent Chunk 생성 시작 (AI 분석)...")
-                    parent_chunk = create_parent_chunk_with_ai(uploaded_file.id, content, model_name)
-                    if parent_chunk:
-                        log_print(f"[7/9] ✅ Parent Chunk 생성 완료: {original_filename}")
-                        print(f"Parent Chunk가 생성되었습니다: {original_filename}")
-                    else:
-                        log_print(f"[7/9] ⚠️ 경고: Parent Chunk 생성 실패: {original_filename}")
-                        print(f"경고: Parent Chunk 생성에 실패했습니다: {original_filename}")
+                    try:
+                        log_print(f"[8/8] Parent Chunk 생성 시작 (AI 분석)...")
+                        parent_chunk = create_parent_chunk_with_ai(uploaded_file.id, content, model_name)
+                        if parent_chunk:
+                            log_print(f"[8/8] ✅ Parent Chunk 생성 완료: {original_filename}")
+                            print(f"Parent Chunk가 생성되었습니다: {original_filename}")
+                        else:
+                            log_print(f"[8/8] ⚠️ 경고: Parent Chunk 생성 실패: {original_filename}")
+                            print(f"경고: Parent Chunk 생성에 실패했습니다: {original_filename}")
+                    except Exception as parent_chunk_error:
+                        # Parent Chunk 생성 실패해도 업로드는 계속 진행
+                        log_print(f"[8/8] ⚠️ 경고: Parent Chunk 생성 중 예외 발생: {str(parent_chunk_error)}")
+                        print(f"경고: Parent Chunk 생성 중 오류가 발생했습니다: {original_filename}")
+                        import traceback
+                        traceback.print_exc()
                     
                 except Exception as e:
                     error_msg = f"청크 생성 중 오류: {str(e)}"
@@ -1943,6 +1960,8 @@ def upload_file():
                     print(error_msg)
                     import traceback
                     traceback.print_exc()
+                    # 청크 생성 실패해도 파일 업로드는 계속 진행 (경고만 표시)
+                    log_print(f"[7/8] ⚠️ 경고: 청크 생성 실패했지만 파일 업로드는 계속 진행합니다.")
             
             # 최종 청크 개수 확인 및 저장
             chunk_count = 0
@@ -1963,13 +1982,23 @@ def upload_file():
             log_print(f"{'='*60}")
             log_print(f"=== 파일 업로드 성공 ===")
             log_print(f"{'='*60}\n")
+            
+            log_print(f"[8/8] 업로드 완료 - 파일: {original_filename}, 모델: {model_name}, 크기: {saved_file_size} bytes")
+            
+            return jsonify({
+                'message': f'파일이 성공적으로 업로드되었습니다. (모델: {model_name})',
+                'file': uploaded_file.to_dict(),
+                'model_name': model_name,
+                'chunk_count': chunk_count
+            }), 200
+            
         except Exception as e:
             db.session.rollback()
             error_msg = f'데이터베이스 저장 중 오류가 발생했습니다: {str(e)}'
             log_print(f"[ERROR] 데이터베이스 저장 오류: {error_msg}")
             traceback.print_exc()
             # 데이터베이스 저장 실패 시 파일도 삭제
-            if os.path.exists(file_path):
+            if 'file_path' in locals() and os.path.exists(file_path):
                 try:
                     os.remove(file_path)
                     log_print(f"오류로 인한 파일 삭제: {file_path}")
@@ -1977,15 +2006,6 @@ def upload_file():
                     log_print(f"파일 삭제 실패: {str(del_e)}")
             return jsonify({'error': error_msg, 'step': 'database_save'}), 500
         
-        log_print(f"[8/8] 업로드 완료 - 파일: {original_filename}, 모델: {model_name}, 크기: {saved_file_size} bytes")
-        
-        return jsonify({
-            'message': f'파일이 성공적으로 업로드되었습니다. (모델: {model_name})',
-            'file': uploaded_file.to_dict(),
-            'model_name': model_name,
-            'chunk_count': chunk_count if 'chunk_count' in locals() else 0
-        }), 200
-        
     except Exception as e:
         db.session.rollback()
         error_msg = str(e)

app/utils/__init__.py

@@ -0,0 +1,25 @@
+"""
+유틸리티 모듈
+공통 유틸리티 함수들을 제공합니다.
+"""
+
+from app.utils.file_utils import (
+    allowed_file,
+    ensure_upload_folder,
+    get_file_extension,
+)
+from app.utils.text_utils import (
+    split_text_into_chunks,
+    extract_chapter_number,
+    clean_text,
+)
+
+__all__ = [
+    'allowed_file',
+    'ensure_upload_folder',
+    'get_file_extension',
+    'split_text_into_chunks',
+    'extract_chapter_number',
+    'clean_text',
+]
+

app/utils/file_utils.py

@@ -0,0 +1,79 @@
+"""
+파일 관련 유틸리티 함수
+"""
+
+from pathlib import Path
+from typing import Optional
+from werkzeug.utils import secure_filename
+
+from app.core.config import Config
+from app.core.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def allowed_file(filename: str) -> bool:
+    """
+    파일 확장자가 허용된 확장자인지 확인
+    
+    Args:
+        filename: 파일명
+    
+    Returns:
+        허용된 확장자면 True, 아니면 False
+    """
+    if '.' not in filename:
+        return False
+    extension = filename.rsplit('.', 1)[1].lower()
+    return extension in Config.ALLOWED_EXTENSIONS
+
+
+def get_file_extension(filename: str) -> Optional[str]:
+    """
+    파일 확장자 추출
+    
+    Args:
+        filename: 파일명
+    
+    Returns:
+        확장자 (점 제외), 없으면 None
+    """
+    if '.' not in filename:
+        return None
+    return filename.rsplit('.', 1)[1].lower()
+
+
+def ensure_upload_folder() -> Path:
+    """
+    업로드 폴더가 존재하는지 확인하고 없으면 생성
+    
+    Returns:
+        업로드 폴더 경로
+    
+    Raises:
+        OSError: 폴더 생성 또는 쓰기 권한 오류
+    """
+    upload_folder = Config.UPLOAD_FOLDER
+    
+    try:
+        # 폴더 생성
+        upload_folder.mkdir(parents=True, exist_ok=True)
+        logger.debug(f"업로드 폴더 확인 완료: {upload_folder}")
+        
+        # 쓰기 권한 테스트
+        test_file = upload_folder / '.write_test'
+        try:
+            test_file.write_text('test')
+            test_file.unlink()
+            logger.debug(f"업로드 폴더 쓰기 권한 확인 완료: {upload_folder}")
+        except PermissionError as e:
+            raise OSError(f'업로드 폴더에 쓰기 권한이 없습니다: {upload_folder}') from e
+        except Exception as e:
+            raise OSError(f'업로드 폴더 쓰기 테스트 실패: {upload_folder}') from e
+        
+        return upload_folder
+        
+    except Exception as e:
+        logger.error(f"업로드 폴더 생성 오류: {e}", exc_info=True)
+        raise
+

app/utils/text_utils.py

@@ -0,0 +1,195 @@
+"""
+텍스트 처리 유틸리티 함수
+"""
+
+import re
+from typing import List, Optional
+
+from app.core.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def clean_text(text: str) -> str:
+    """
+    텍스트 정리 (공백 정규화 등)
+    
+    Args:
+        text: 정리할 텍스트
+    
+    Returns:
+        정리된 텍스트
+    """
+    if not text:
+        return ''
+    
+    # 연속된 공백 제거
+    text = re.sub(r'\s+', ' ', text)
+    # 앞뒤 공백 제거
+    text = text.strip()
+    
+    return text
+
+
+def split_text_into_chunks(
+    text: str,
+    min_chunk_size: int = 200,
+    max_chunk_size: int = 1000,
+    overlap: int = 150
+) -> List[str]:
+    """
+    의미 기반 텍스트 청킹 (문장과 문단 경계를 고려하여 분할)
+    
+    Args:
+        text: 분할할 텍스트
+        min_chunk_size: 최소 청크 크기
+        max_chunk_size: 최대 청크 크기
+        overlap: 오버랩 크기
+    
+    Returns:
+        분할된 청크 리스트
+    """
+    if not text or len(text.strip()) == 0:
+        return []
+    
+    # 1단계: 문단 단위로 분할 (빈 줄 기준)
+    paragraphs = re.split(r'\n\s*\n', text.strip())
+    paragraphs = [p.strip() for p in paragraphs if p.strip()]
+    
+    if not paragraphs:
+        return []
+    
+    # 2단계: 각 문단을 문장 단위로 분할
+    sentence_pattern = r'([.!?]+)(?=\s+|$)'
+    
+    all_sentences: List[str] = []
+    for para in paragraphs:
+        parts = re.split(sentence_pattern, para)
+        combined_sentences: List[str] = []
+        current_sentence = ""
+        
+        for part in parts:
+            if not part.strip():
+                continue
+            if re.match(r'^[.!?]+$', part):
+                # 구두점인 경우 현재 문장에 추가하고 문장 완성
+                current_sentence += part
+                if current_sentence.strip():
+                    combined_sentences.append(current_sentence.strip())
+                current_sentence = ""
+            else:
+                # 텍스트인 경우 현재 문장에 추가
+                current_sentence += part
+        
+        # 마지막 문장 처리
+        if current_sentence.strip():
+            combined_sentences.append(current_sentence.strip())
+        
+        # 문장이 하나도 없는 경우
+        if not combined_sentences and para.strip():
+            combined_sentences.append(para.strip())
+        
+        all_sentences.extend(combined_sentences)
+    
+    if not all_sentences:
+        return [text] if text.strip() else []
+    
+    # 3단계: 문장들을 모아서 의미 있는 청크 생성
+    chunks: List[str] = []
+    current_chunk: List[str] = []
+    current_size = 0
+    
+    for sentence in all_sentences:
+        sentence_size = len(sentence)
+        
+        # 현재 청크에 문장 추가 시 최대 크기를 초과하는 경우
+        if current_size + sentence_size > max_chunk_size and current_chunk:
+            # 현재 청크 저장
+            chunk_text = '\n'.join(current_chunk)
+            if len(chunk_text.strip()) >= min_chunk_size:
+                chunks.append(chunk_text)
+            else:
+                # 최소 크기 미만이면 다음 청크와 병합
+                if chunks:
+                    chunks[-1] = chunks[-1] + '\n' + chunk_text
+                else:
+                    chunks.append(chunk_text)
+            
+            # 오버랩을 위한 문장 유지
+            overlap_sentences: List[str] = []
+            overlap_size = 0
+            for s in reversed(current_chunk):
+                if overlap_size + len(s) <= overlap:
+                    overlap_sentences.insert(0, s)
+                    overlap_size += len(s) + 1
+                else:
+                    break
+            
+            current_chunk = overlap_sentences + [sentence]
+            current_size = overlap_size + sentence_size
+        else:
+            # 현재 청크에 문장 추가
+            current_chunk.append(sentence)
+            current_size += sentence_size + 1
+    
+    # 마지막 청크 추가
+    if current_chunk:
+        chunk_text = '\n'.join(current_chunk)
+        if chunks and len(chunk_text.strip()) < min_chunk_size:
+            chunks[-1] = chunks[-1] + '\n' + chunk_text
+        else:
+            chunks.append(chunk_text)
+    
+    # 빈 청크 제거 및 최소 크기 미만 청크 처리
+    final_chunks: List[str] = []
+    for chunk in chunks:
+        chunk = chunk.strip()
+        if chunk and len(chunk) >= min_chunk_size:
+            final_chunks.append(chunk)
+        elif chunk:
+            if final_chunks:
+                final_chunks[-1] = final_chunks[-1] + '\n' + chunk
+            else:
+                final_chunks.append(chunk)
+    
+    return final_chunks if final_chunks else [text] if text.strip() else []
+
+
+def extract_chapter_number(text: str) -> Optional[int]:
+    """
+    텍스트에서 챕터 번호 추출
+    
+    Args:
+        text: 챕터 번호를 추출할 텍스트
+    
+    Returns:
+        챕터 번호, 없으면 None
+    """
+    # 다양한 챕터 패턴 매칭
+    patterns = [
+        r'제\s*(\d+)\s*장',  # 제1장, 제 1 장
+        r'제\s*(\d+)\s*화',  # 제1화
+        r'Chapter\s*(\d+)',  # Chapter 1
+        r'CHAPTER\s*(\d+)',  # CHAPTER 1
+        r'Ch\.\s*(\d+)',     # Ch. 1
+        r'(\d+)\s*장',       # 1장
+        r'(\d+)\s*화',       # 1화
+        r'chap\.\s*(\d+)',   # chap. 1
+        r'ch\s*(\d+)',       # ch 1
+        r'(\d+)\s*章',       # 1章
+    ]
+    
+    # 텍스트의 처음 500자만 검사
+    search_text = text[:500]
+    
+    for pattern in patterns:
+        match = re.search(pattern, search_text, re.IGNORECASE)
+        if match:
+            try:
+                chapter_num = int(match.group(1))
+                return chapter_num
+            except (ValueError, AttributeError):
+                continue
+    
+    return None
+

requirements.txt

@@ -8,5 +8,7 @@ chromadb==0.4.22
 sentence-transformers==2.3.1
 numpy==1.24.3
 google-generativeai==0.3.2
+pydantic==2.5.0
+pydantic-settings==2.1.0
 
 

templates/admin_webnovels.html

@@ -472,6 +472,7 @@
             </div>
 
             <!-- 메타데이터 추가 옵션 -->
+             <!-- 
             <div style="margin-bottom: 16px; padding: 12px; background: #f8f9fa; border-radius: 6px; border: 1px solid #dadce0;">
                 <label style="display: flex; align-items: center; cursor: pointer; font-size: 14px;">
                     <input type="checkbox" id="extractMetadataCheckbox" checked style="margin-right: 8px; width: 18px; height: 18px; cursor: pointer;">
@@ -482,7 +483,7 @@
                     <span style="color: #c5221f;">⚠️ 메타데이터 추출은 AI를 사용하므로 시간이 오래 걸릴 수 있습니다.</span>
                 </div>
             </div>
-
+            -->
             <!-- 파일 업로드 -->
             <div class="file-upload-input-wrapper" id="fileUploadWrapper">
                 <input type="file" id="fileInput" accept=".txt,.md,.pdf,.docx,.epub" multiple>
@@ -582,6 +583,15 @@
         const fileUploadStatus = document.getElementById('fileUploadStatus');
         const fileModelSelect = document.getElementById('fileModelSelect');
         const filesTableBody = document.getElementById('filesTableBody');
+        
+        // 디버깅: 요소 존재 확인
+        console.log('[초기화] 파일 업로드 요소 확인:', {
+            fileInput: !!fileInput,
+            fileUploadWrapper: !!fileUploadWrapper,
+            fileUploadStatus: !!fileUploadStatus,
+            fileModelSelect: !!fileModelSelect,
+            filesTableBody: !!filesTableBody
+        });
 
         // 모델 목록 로드 (관리자용: 모든 모델 표시)
         async function loadModelsForFiles() {
@@ -728,24 +738,57 @@
 
         // 파일 업로드 처리
         async function handleFileUpload(files) {
-            if (!files || files.length === 0) return;
+            console.log('[handleFileUpload] 함수 호출됨', { filesCount: files ? files.length : 0 });
+            
+            if (!files || files.length === 0) {
+                console.warn('[handleFileUpload] 파일이 없습니다');
+                return;
+            }
 
-            const modelName = fileModelSelect.value;
-            if (!modelName) {
-                showAlert('먼저 AI 모델을 선택해주세요.', 'error');
+            let modelName;
+            try {
+                modelName = fileModelSelect.value;
+                console.log('[handleFileUpload] 모델명:', modelName);
+                
+                if (!modelName) {
+                    console.error('[handleFileUpload] 모델이 선택되지 않음');
+                    showAlert('먼저 AI 모델을 선택해주세요.', 'error');
+                    return;
+                }
+            } catch (error) {
+                console.error('[handleFileUpload] 초기 검증 오류:', error);
+                showAlert(`오류: ${error.message}`, 'error');
                 return;
             }
 
-            // 업로드 중 UI 비활성화
-            fileUploadWrapper.classList.add('disabled');
-            fileModelSelect.disabled = true;
-            fileInput.disabled = true;
+            try {
+                // 업로드 중 UI 비활성화
+                console.log('[handleFileUpload] UI 비활성화 시작');
+                if (!fileUploadWrapper || !fileModelSelect || !fileInput) {
+                    throw new Error('필수 UI 요소를 찾을 수 없습니다');
+                }
+                
+                fileUploadWrapper.classList.add('disabled');
+                fileModelSelect.disabled = true;
+                fileInput.disabled = true;
 
-            // 진행 상태 초기화
-            const progressContainer = document.getElementById('fileUploadProgress');
-            const progressItems = document.getElementById('progressItems');
-            progressContainer.classList.add('active');
-            progressItems.innerHTML = '';
+                // 진행 상태 초기화
+                const progressContainer = document.getElementById('fileUploadProgress');
+                const progressItems = document.getElementById('progressItems');
+                
+                if (!progressContainer || !progressItems) {
+                    console.error('[handleFileUpload] 진행 상태 컨테이너를 찾을 수 없습니다');
+                    throw new Error('진행 상태 컨테이너를 찾을 수 없습니다');
+                }
+                
+                progressContainer.classList.add('active');
+                progressItems.innerHTML = '';
+                console.log('[handleFileUpload] UI 비활성화 완료');
+            } catch (uiError) {
+                console.error('[handleFileUpload] UI 설정 오류:', uiError);
+                showAlert(`UI 설정 오류: ${uiError.message}`, 'error');
+                return;
+            }
 
             // 각 파일에 대한 진행 항목 생성
             const progressMap = new Map();
@@ -756,48 +799,131 @@
                 item.innerHTML = `
                     <span class="progress-item-name">${escapeHtml(file.name)}</span>
                     <span class="progress-item-status uploading" id="progress-status-${index}">
-                        <span class="spinner"></span>업로드 중...
+                        <span class="spinner"></span>대기 중...
                     </span>
                 `;
                 progressItems.appendChild(item);
-                progressMap.set(index, { file, item, status: 'uploading' });
+                progressMap.set(index, { file, item, status: 'waiting', step: 0 });
             });
 
-            fileUploadStatus.textContent = `총 ${files.length}개 파일 업로드 중...`;
-            fileUploadStatus.className = 'file-upload-status progress';
+            // 업로드 단계 정의
+            const uploadSteps = [
+                { name: '업로드 폴더 확인', step: 1 },
+                { name: '파일 수신', step: 2 },
+                { name: '파일 검증', step: 3 },
+                { name: '파일 저장', step: 4 },
+                { name: '데이터베이스 저장', step: 5 },
+                { name: '청크 생성', step: 6 },
+                { name: '완료', step: 7 }
+            ];
+
+            function updateProgressStatus(fileIndex, stepIndex, stepName) {
+                const statusElement = document.getElementById(`progress-status-${fileIndex}`);
+                if (statusElement) {
+                    const step = uploadSteps[stepIndex] || { name: stepName || '처리 중', step: stepIndex + 1 };
+                    statusElement.innerHTML = `<span class="spinner"></span>${step.name} (${step.step}/7)`;
+                }
+            }
+
+            function updateOverallStatus(currentFile, totalFiles, stepIndex) {
+                const step = uploadSteps[stepIndex] || { name: '처리 중', step: stepIndex + 1 };
+                fileUploadStatus.textContent = `[${currentFile}/${totalFiles}] ${step.name} 중... (${step.step}/7)`;
+            }
+
+            if (fileUploadStatus) {
+                fileUploadStatus.textContent = `[0/${files.length}] 업로드 준비 중...`;
+                fileUploadStatus.className = 'file-upload-status progress';
+            }
 
             let successCount = 0;
             let failCount = 0;
             const errors = [];
 
+            console.log(`[handleFileUpload] 업로드 루프 시작 준비, 파일 개수: ${files.length}`);
+            
             // 파일을 순차적으로 업로드
-            for (let i = 0; i < files.length; i++) {
-                const file = files[i];
-                const formData = new FormData();
-                formData.append('file', file);
-                formData.append('model_name', modelName);
-                // 메타데이터 추출 옵션 추가
-                const extractMetadata = document.getElementById('extractMetadataCheckbox').checked;
-                formData.append('extract_metadata', extractMetadata ? 'true' : 'false');
-                
-                // 이어서 업로드인 경우 parent_file_id 추가
-                if (continueUploadFileId) {
-                    formData.append('parent_file_id', continueUploadFileId);
-                }
+            try {
+                console.log(`[handleFileUpload] for 루프 시작 전, files.length: ${files.length}`);
+                for (let i = 0; i < files.length; i++) {
+                    console.log(`[handleFileUpload] for 루프 ${i}번째 반복 시작`);
+                    const file = files[i];
+                    console.log(`[업로드 루프 시작] 파일 ${i + 1}/${files.length}: ${file.name}`);
+                    
+                    const formData = new FormData();
+                    formData.append('file', file);
+                    formData.append('model_name', modelName);
+                    
+                    // 메타데이터 추출 옵션 추가 (체크박스가 주석 처리되어 있으므로 기본값 false 사용)
+                    try {
+                        const extractMetadataCheckbox = document.getElementById('extractMetadataCheckbox');
+                        const extractMetadata = extractMetadataCheckbox ? extractMetadataCheckbox.checked : false;
+                        formData.append('extract_metadata', extractMetadata ? 'true' : 'false');
+                        console.log(`[메타데이터 설정] extract_metadata: ${extractMetadata}`);
+                    } catch (metadataError) {
+                        console.warn(`[메타데이터 설정 오류] 기본값 false 사용:`, metadataError);
+                        formData.append('extract_metadata', 'false');
+                    }
+                    
+                    // 이어서 업로드인 경우 parent_file_id 추가
+                    if (continueUploadFileId) {
+                        formData.append('parent_file_id', continueUploadFileId);
+                    }
 
-                const statusElement = document.getElementById(`progress-status-${i}`);
-                const itemElement = document.getElementById(`progress-item-${i}`);
+                    const statusElement = document.getElementById(`progress-status-${i}`);
+                    const itemElement = document.getElementById(`progress-item-${i}`);
 
-                try {
-                    console.log(`[업로드 시작] 파일: ${file.name}, 크기: ${file.size} bytes, 모델: ${modelName}`);
+                    try {
+                        console.log(`[업로드 시작] 파일: ${file.name}, 크기: ${file.size} bytes, 모델: ${modelName}`);
+                        
+                        // 단계 1: 업로드 폴더 확인
+                        console.log(`[단계 1] 업로드 폴더 확인 시작`);
+                        updateProgressStatus(i, 0, '업로드 폴더 확인');
+                        updateOverallStatus(i + 1, files.length, 0);
+                        
+                        console.log(`[단계 1] fetch 호출 시작: /api/upload`);
+                        console.log(`[단계 1] FormData 항목:`, Array.from(formData.entries()).map(([k, v]) => [k, v instanceof File ? v.name : v]));
+                        
+                        // 타임아웃이 있는 fetch 래퍼
+                        const fetchWithTimeout = (url, options, timeout = 300000) => { // 5분 타임아웃
+                            return Promise.race([
+                                fetch(url, options),
+                                new Promise((_, reject) =>
+                                    setTimeout(() => reject(new Error(`요청 타임아웃: ${timeout/1000}초 내에 응답이 없습니다.`)), timeout)
+                                )
+                            ]);
+                        };
+                        
+                        const response = await fetchWithTimeout('/api/upload', {
+                            method: 'POST',
+                            body: formData,
+                            credentials: 'include'  // 쿠키 포함 (세션 인증)
+                        }, 300000); // 5분 타임아웃
+                        
+                        console.log(`[단계 1] fetch 응답 수신: ${response.status} ${response.statusText}`);
+                        
+                        // 인증 오류 체크
+                        if (response.status === 401 || response.status === 403) {
+                            const errorText = await response.text();
+                            console.error(`[인증 오류] ${response.status}: ${errorText}`);
+                            throw new Error(`인증 오류: 서버에서 로그인이 필요하다고 응답했습니다. (${response.status})`);
+                        }
+                        
+                        // 리다이렉트 체크
+                        if (response.redirected) {
+                            console.warn(`[리다이렉트] 요청이 리다이렉트되었습니다: ${response.url}`);
+                            throw new Error('서버에서 리다이렉트가 발생했습니다. 로그인 상태를 확인해주세요.');
+                        }
                     
-                    const response = await fetch('/api/upload', {
-                        method: 'POST',
-                        body: formData
-                    });
+                    // 단계 2: 파일 수신
+                    updateProgressStatus(i, 1, '파일 수신');
+                    updateOverallStatus(i + 1, files.length, 1);
 
                     console.log(`[응답 수신] 상태: ${response.status} ${response.statusText}, Content-Type: ${response.headers.get('Content-Type')}`);
 
+                    // 단계 3: 파일 검증
+                    updateProgressStatus(i, 2, '파일 검증');
+                    updateOverallStatus(i + 1, files.length, 2);
+
                     let data;
                     let responseText = '';
                     try {
@@ -810,10 +936,27 @@
                         throw new Error(`서버 응답 오류 (${response.status}): ${responseText.substring(0, 200)}`);
                     }
 
+                    // 단계 4: 파일 저장
+                    updateProgressStatus(i, 3, '파일 저장');
+                    updateOverallStatus(i + 1, files.length, 3);
+
                     if (response.ok) {
+                        // 단계 5: 데이터베이스 저장
+                        updateProgressStatus(i, 4, '데이터베이스 저장');
+                        updateOverallStatus(i + 1, files.length, 4);
+                        
+                        // 단계 6: 청크 생성
+                        updateProgressStatus(i, 5, '청크 생성');
+                        updateOverallStatus(i + 1, files.length, 5);
+                        
                         successCount++;
                         const modelName = data.model_name || '알 수 없음';
                         const chunkCount = data.chunk_count || 0;
+                        
+                        // 단계 7: 완료
+                        updateProgressStatus(i, 6, '완료');
+                        updateOverallStatus(i + 1, files.length, 6);
+                        
                         statusElement.className = 'progress-item-status success';
                         statusElement.innerHTML = '✓ 완료';
                         statusElement.title = `모델: ${modelName}${chunkCount > 0 ? `, 청크: ${chunkCount}개` : ''}`;
@@ -838,38 +981,68 @@
                 } catch (error) {
                     failCount++;
                     const errorMsg = error.message || '네트워크 오류';
-                    statusElement.className = 'progress-item-status error';
-                    statusElement.innerHTML = '✗ 실패';
-                    statusElement.title = errorMsg; // 툴팁으로 상세 에러 표시
-                    statusElement.style.cursor = 'help'; // 툴팁 표시를 위한 커서 변경
+                    if (statusElement) {
+                        statusElement.className = 'progress-item-status error';
+                        statusElement.innerHTML = '✗ 실패';
+                        statusElement.title = errorMsg; // 툴팁으로 상세 에러 표시
+                        statusElement.style.cursor = 'help'; // 툴팁 표시를 위한 커서 변경
+                    }
                     errors.push(`${file.name}: ${errorMsg}`);
                     console.error(`[업로드 예외] 파일: ${file.name}`, error);
+                    console.error(`[업로드 예외 스택]`, error.stack);
+                    
+                    // 네트워크 오류나 타임아웃인 경우 사용자에게 명확한 메시지 표시
+                    if (error.name === 'TypeError' && error.message.includes('fetch')) {
+                        console.error(`[네트워크 오류] 서버와의 연결이 끊어졌습니다.`);
+                        if (fileUploadStatus) {
+                            fileUploadStatus.textContent = `[${i + 1}/${files.length}] 네트워크 오류: 서버 연결 실패`;
+                            fileUploadStatus.className = 'file-upload-status error';
+                        }
+                    }
                     console.error(`[스택 트레이스]`, error.stack);
                 }
 
-                // 진행 상태 업데이트
-                fileUploadStatus.textContent = `업로드 중... (${i + 1}/${files.length})`;
+                    // 진행 상태 업데이트 (다음 파일로 넘어가기 전)
+                    if (i < files.length - 1) {
+                        fileUploadStatus.textContent = `[${i + 1}/${files.length}] 완료, 다음 파일 처리 중...`;
+                    } else {
+                        fileUploadStatus.textContent = `[${i + 1}/${files.length}] 모든 파일 처리 완료`;
+                    }
+                }
+            } catch (uploadLoopError) {
+                console.error('[업로드 루프 오류]', uploadLoopError);
+                fileUploadStatus.textContent = `업로드 처리 중 오류 발생: ${uploadLoopError.message}`;
+                fileUploadStatus.className = 'file-upload-status error';
+                showAlert(`업로드 처리 중 오류가 발생했습니다: ${uploadLoopError.message}`, 'error');
             }
 
             // 업로드 완료 처리
-            fileUploadStatus.className = 'file-upload-status';
-            if (successCount > 0) {
-                fileUploadStatus.textContent = `${successCount}개 파일 업로드 완료${failCount > 0 ? ` (${failCount}개 실패)` : ''}`;
-                fileUploadStatus.className = 'file-upload-status success';
-                showAlert(`${successCount}개 파일이 성공적으로 업로드되었습니다.${failCount > 0 ? ` (${failCount}개 실패)` : ''}`, 'success');
-                loadFiles();
-            } else {
-                fileUploadStatus.textContent = '모든 파일 업로드 실패';
-                fileUploadStatus.className = 'file-upload-status error';
-                const errorDetails = errors.length > 0 ? '\n' + errors.slice(0, 3).join('\n') + (errors.length > 3 ? `\n... 외 ${errors.length - 3}개 오류` : '') : '';
-                showAlert(`파일 업로드에 실패했습니다.${errorDetails}`, 'error');
-            }
+            try {
+                if (fileUploadStatus) {
+                    fileUploadStatus.className = 'file-upload-status';
+                    if (successCount > 0) {
+                        fileUploadStatus.textContent = `${successCount}개 파일 업로드 완료${failCount > 0 ? ` (${failCount}개 실패)` : ''}`;
+                        fileUploadStatus.className = 'file-upload-status success';
+                        showAlert(`${successCount}개 파일이 성공적으로 업로드되었습니다.${failCount > 0 ? ` (${failCount}개 실패)` : ''}`, 'success');
+                        loadFiles();
+                    } else {
+                        fileUploadStatus.textContent = '모든 파일 업로드 실패';
+                        fileUploadStatus.className = 'file-upload-status error';
+                        const errorDetails = errors.length > 0 ? '\n' + errors.slice(0, 3).join('\n') + (errors.length > 3 ? `\n... 외 ${errors.length - 3}개 오류` : '') : '';
+                        showAlert(`파일 업로드에 실패했습니다.${errorDetails}`, 'error');
+                    }
+                }
 
-            // UI 활성화
-            fileUploadWrapper.classList.remove('disabled');
-            fileModelSelect.disabled = false;
-            fileInput.disabled = false;
-            fileInput.value = '';
+                // UI 활성화
+                if (fileUploadWrapper) fileUploadWrapper.classList.remove('disabled');
+                if (fileModelSelect) fileModelSelect.disabled = false;
+                if (fileInput) {
+                    fileInput.disabled = false;
+                    fileInput.value = '';
+                }
+            } catch (finalError) {
+                console.error('[handleFileUpload] 완료 처리 오류:', finalError);
+            }
 
             // 3초 후 진행 상태 숨기기
             setTimeout(() => {
@@ -922,33 +1095,51 @@
         }
 
         // 파일 입력 이벤트
-        fileInput.addEventListener('change', function(e) {
-            if (e.target.files.length > 0) {
-                handleFileUpload(Array.from(e.target.files));
-            }
-            // 이어서 업로드 모드 초기화
-            continueUploadFileId = null;
-        });
+        if (fileInput) {
+            fileInput.addEventListener('change', function(e) {
+                console.log('[파일 입력 이벤트] 파일 선택됨', { filesCount: e.target.files.length });
+                if (e.target.files.length > 0) {
+                    console.log('[파일 입력 이벤트] handleFileUpload 호출');
+                    handleFileUpload(Array.from(e.target.files)).catch(error => {
+                        console.error('[파일 입력 이벤트] handleFileUpload 오류:', error);
+                        showAlert(`업로드 오류: ${error.message}`, 'error');
+                    });
+                }
+                // 이어서 업로드 모드 초기화
+                continueUploadFileId = null;
+            });
+        } else {
+            console.error('[초기화 오류] fileInput 요소를 찾을 수 없습니다');
+        }
 
         // 드래그 앤 드롭
-        fileUploadWrapper.addEventListener('dragover', (e) => {
-            e.preventDefault();
-            fileUploadWrapper.classList.add('dragover');
-        });
+        if (fileUploadWrapper) {
+            fileUploadWrapper.addEventListener('dragover', (e) => {
+                e.preventDefault();
+                fileUploadWrapper.classList.add('dragover');
+            });
 
-        fileUploadWrapper.addEventListener('dragleave', () => {
-            fileUploadWrapper.classList.remove('dragover');
-        });
+            fileUploadWrapper.addEventListener('dragleave', () => {
+                fileUploadWrapper.classList.remove('dragover');
+            });
 
-        fileUploadWrapper.addEventListener('drop', (e) => {
-            e.preventDefault();
-            fileUploadWrapper.classList.remove('dragover');
-            
-            const files = Array.from(e.dataTransfer.files);
-            if (files.length > 0) {
-                handleFileUpload(files);
-            }
-        });
+            fileUploadWrapper.addEventListener('drop', (e) => {
+                e.preventDefault();
+                fileUploadWrapper.classList.remove('dragover');
+                
+                const files = Array.from(e.dataTransfer.files);
+                console.log('[드래그 앤 드롭] 파일 드롭됨', { filesCount: files.length });
+                if (files.length > 0) {
+                    console.log('[드래그 앤 드롭] handleFileUpload 호출');
+                    handleFileUpload(files).catch(error => {
+                        console.error('[드래그 앤 드롭] handleFileUpload 오류:', error);
+                        showAlert(`업로드 오류: ${error.message}`, 'error');
+                    });
+                }
+            });
+        } else {
+            console.error('[초기화 오류] fileUploadWrapper 요소를 찾을 수 없습니다');
+        }
 
         // Parent Chunk 확인
         async function viewParentChunk(fileId, fileName) {