synapse-sdk 2025.9.1__py3-none-any.whl → 2025.9.4__py3-none-any.whl

synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/plugins/upload-plugins.md

@@ -1,240 +1,802 @@
+---
+id: upload-plugins
+title: 업로드 플러그인
+sidebar_position: 3
+---
+
 # 업로드 플러그인
 
-업로드 플러그인은 다양한 데이터 소스에서 Synapse 데이터셋으로 파일을 업로드하기 위한 강력하고 유연한 시스템입니다. 로컬 파일, Excel 스프레드시트, 이미지 컬렉션을 위한 포괄적인 업로드 기능을 제공합니다.
+업로드 플러그인은 포괄적인 메타데이터 지원, 보안 검증 및 체계적인 데이터 단위 생성을 통해 파일을 Synapse 플랫폼으로 처리하기 위한 파일 업로드 및 데이터 수집 작업을 제공합니다.
 
 ## 개요
 
-업로드 플러그인은 메타데이터 추출, 보안 검증, 진행률 추적을 포함하여 파일 업로드 과정의 모든 측면을 처리합니다. 대용량 파일 배치와 복잡한 디렉터리 구조를 효율적으로 관리하도록 설계되었습니다.
+**사용 가능한 액션:**
+
+- `upload` - 선택적 Excel 메타데이터 처리를 통한 파일 및 디렉토리 스토리지 업로드
+
+**사용 사례:**
+
+- 메타데이터 주석을 포함한 대량 파일 업로드
+- Excel 기반 메타데이터 매핑 및 검증
+- 재귀적 디렉토리 처리
+- 타입 기반 파일 구성
+- 배치 데이터 단위 생성
+- 크기 및 내용 검증을 통한 안전한 파일 처리
+
+**지원되는 업로드 소스:**
+
+- 로컬 파일 시스템 경로 (파일 및 디렉토리)
+- 재귀적 디렉토리 스캔
+- 향상된 파일 주석을 위한 Excel 메타데이터 파일
+- 자동 구성을 통한 혼합 파일 타입
 
-### 주요 기능
+## 업로드 액션 아키텍처
+
+업로드 시스템은 검증된 디자인 패턴을 기반으로 구축된 현대적이고 확장 가능한 아키텍처를 사용합니다. 리팩토링된 구현은 이전의 모놀리식 접근 방식을 관심사의 명확한 분리가 있는 모듈식 전략 기반 시스템으로 변환합니다.
+
+### 디자인 패턴
 
-- **다중 파일 형식 지원**: Excel, 이미지, 텍스트 파일 등
-- **메타데이터 추출**: Excel 파일에서 자동 메타데이터 수집
-- **보안 검증**: 파일 액세스 제어 및 권한 검사
-- **진행률 추적**: 실시간 업로드 진행률 모니터링
-- **배치 처리**: 여러 파일의 효율적인 배치 업로드
-- **분산 실행**: Ray를 사용한 확장 가능한 처리
+아키텍처는 여러 핵심 디자인 패턴을 활용합니다:
 
-## 아키텍처
+- **전략 패턴**: 검증, 파일 발견, 메타데이터 처리, 업로드 작업 및 데이터 단위 생성을 위한 플러그형 동작
+- **파사드 패턴**: UploadOrchestrator는 복잡한 워크플로우를 조정하기 위한 단순화된 인터페이스를 제공
+- **팩토리 패턴**: StrategyFactory는 런타임 매개변수를 기반으로 적절한 전략 구현을 생성
+- **컨텍스트 패턴**: UploadContext는 워크플로우 구성 요소 간의 공유 상태 및 통신을 유지
 
-업로드 플러그인은 각각 특정한 책임을 가진 여러 모듈로 구성되어 있습니다:
+### 컴포넌트 아키텍처
 
 ```mermaid
-graph TD
-    A[UploadAction] --> B[UploadRun]
-    A --> C[UploadParams]
-    B --> D[LogCode]
-    B --> E[UploadStatus]
-    A --> F[ExcelSecurityConfig]
-    A --> G[ExcelMetadataUtils]
-
-    style A fill:#e1f5fe80,stroke:#01579b,stroke-width:2px
-    style B fill:#f3e5f580,stroke:#4a148c,stroke-width:2px
-    style C fill:#e8f5e880,stroke:#1b5e20,stroke-width:2px
-    style D fill:#fff3e080,stroke:#e65100,stroke-width:2px
-    style E fill:#fff3e080,stroke:#e65100,stroke-width:2px
-    style F fill:#fce4ec80,stroke:#880e4f,stroke-width:2px
-    style G fill:#fce4ec80,stroke:#880e4f,stroke-width:2px
-```
-
-### 디렉터리 구조
-
-```
-synapse_sdk/
-├── plugins/
-│   └── categories/
-│       └── upload/
-│           └── actions/
-│               └── upload/
-│                   ├── __init__.py          # 공개 API 내보내기
-│                   ├── action.py            # 주요 UploadAction 클래스
-│                   ├── run.py              # UploadRun 클래스 및 실행 로직
-│                   ├── models.py           # 매개변수 모델 및 검증
-│                   ├── enums.py            # 열거형 및 상수
-│                   ├── exceptions.py       # 사용자 정의 예외
-│                   └── utils.py            # 유틸리티 클래스 및 헬퍼
+classDiagram
+    %% Light/Dark mode compatible colors
+    classDef coreClass fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000000
+    classDef strategyClass fill:#e8f5e8,stroke:#388e3c,stroke-width:2px,color:#000000
+    classDef stepClass fill:#fff9c4,stroke:#f57c00,stroke-width:2px,color:#000000
+    classDef contextClass fill:#ffebee,stroke:#d32f2f,stroke-width:2px,color:#000000
+
+    class UploadAction {
+        +name: str = "upload"
+        +category: PluginCategory.UPLOAD
+        +method: RunMethod.JOB
+        +run_class: UploadRun
+        +params_model: UploadParams
+        +strategy_factory: StrategyFactory
+        +step_registry: StepRegistry
+
+        +start() dict
+        +get_workflow_summary() dict
+        +_configure_workflow() None
+        +_configure_strategies() dict
+    }
+
+    class UploadOrchestrator {
+        +context: UploadContext
+        +step_registry: StepRegistry
+        +strategies: dict
+        +executed_steps: list
+        +current_step_index: int
+        +rollback_executed: bool
+
+        +execute() dict
+        +get_workflow_summary() dict
+        +get_executed_steps() list
+        +is_rollback_executed() bool
+        +_execute_step(step) StepResult
+        +_handle_step_failure(step, error) None
+        +_rollback_executed_steps() None
+    }
+
+    class UploadContext {
+        +params: dict
+        +run: UploadRun
+        +client: Any
+        +storage: Any
+        +pathlib_cwd: Path
+        +metadata: dict
+        +file_specifications: dict
+        +organized_files: list
+        +uploaded_files: list
+        +data_units: list
+        +metrics: dict
+        +errors: list
+        +strategies: dict
+        +rollback_data: dict
+
+        +update(result: StepResult) None
+        +get_result() dict
+        +has_errors() bool
+        +update_metrics(category, metrics) None
+    }
+
+    class StepRegistry {
+        +_steps: list
+        +register(step: BaseStep) None
+        +get_steps() list
+        +get_total_progress_weight() float
+        +clear() None
+    }
+
+    class StrategyFactory {
+        +create_validation_strategy(params, context) BaseValidationStrategy
+        +create_file_discovery_strategy(params, context) BaseFileDiscoveryStrategy
+        +create_metadata_strategy(params, context) BaseMetadataStrategy
+        +create_upload_strategy(params, context) BaseUploadStrategy
+        +create_data_unit_strategy(params, context) BaseDataUnitStrategy
+        +get_available_strategies() dict
+    }
+
+    class BaseStep {
+        <<abstract>>
+        +name: str
+        +progress_weight: float
+        +execute(context: UploadContext) StepResult
+        +can_skip(context: UploadContext) bool
+        +rollback(context: UploadContext) None
+        +create_success_result(data) StepResult
+        +create_error_result(error) StepResult
+        +create_skip_result() StepResult
+    }
+
+    class StepResult {
+        +success: bool
+        +data: dict
+        +error: str
+        +rollback_data: dict
+        +skipped: bool
+        +original_exception: Exception
+        +timestamp: datetime
+    }
+
+    %% Strategy Base Classes
+    class BaseValidationStrategy {
+        <<abstract>>
+        +validate_files(files, context) bool
+        +validate_security(file_path) bool
+    }
+
+    class BaseFileDiscoveryStrategy {
+        <<abstract>>
+        +discover_files(path, context) list
+        +organize_files(files, specs, context) list
+    }
+
+    class BaseMetadataStrategy {
+        <<abstract>>
+        +process_metadata(context) dict
+        +extract_metadata(file_path) dict
+    }
+
+    class BaseUploadStrategy {
+        <<abstract>>
+        +upload_files(files, context) list
+        +upload_batch(batch, context) list
+    }
+
+    class BaseDataUnitStrategy {
+        <<abstract>>
+        +generate_data_units(files, context) list
+        +create_data_unit_batch(batch, context) list
+    }
+
+    %% Workflow Steps
+    class InitializeStep {
+        +name = "initialize"
+        +progress_weight = 0.05
+    }
+
+    class ProcessMetadataStep {
+        +name = "process_metadata"
+        +progress_weight = 0.05
+    }
+
+    class AnalyzeCollectionStep {
+        +name = "analyze_collection"
+        +progress_weight = 0.05
+    }
+
+    class OrganizeFilesStep {
+        +name = "organize_files"
+        +progress_weight = 0.10
+    }
+
+    class ValidateFilesStep {
+        +name = "validate_files"
+        +progress_weight = 0.05
+    }
+
+    class UploadFilesStep {
+        +name = "upload_files"
+        +progress_weight = 0.30
+    }
+
+    class GenerateDataUnitsStep {
+        +name = "generate_data_units"
+        +progress_weight = 0.35
+    }
+
+    class CleanupStep {
+        +name = "cleanup"
+        +progress_weight = 0.05
+    }
+
+    %% Relationships
+    UploadAction --> UploadOrchestrator : creates and executes
+    UploadAction --> StrategyFactory : configures strategies
+    UploadAction --> StepRegistry : manages workflow steps
+    UploadOrchestrator --> UploadContext : coordinates state
+    UploadOrchestrator --> StepRegistry : executes steps from
+    UploadOrchestrator --> BaseStep : executes
+    BaseStep --> StepResult : returns
+    UploadContext --> StepResult : updates with
+    StrategyFactory --> BaseValidationStrategy : creates
+    StrategyFactory --> BaseFileDiscoveryStrategy : creates
+    StrategyFactory --> BaseMetadataStrategy : creates
+    StrategyFactory --> BaseUploadStrategy : creates
+    StrategyFactory --> BaseDataUnitStrategy : creates
+    StepRegistry --> BaseStep : contains
+
+    %% Step inheritance
+    InitializeStep --|> BaseStep : extends
+    ProcessMetadataStep --|> BaseStep : extends
+    AnalyzeCollectionStep --|> BaseStep : extends
+    OrganizeFilesStep --|> BaseStep : extends
+    ValidateFilesStep --|> BaseStep : extends
+    UploadFilesStep --|> BaseStep : extends
+    GenerateDataUnitsStep --|> BaseStep : extends
+    CleanupStep --|> BaseStep : extends
+
+    %% Note: Class styling defined above - Mermaid will apply based on classDef definitions
 ```
 
-## 업로드 액션 아키텍처
+### 단계 기반 워크플로우 실행
+
+리팩토링된 아키텍처는 UploadOrchestrator에 의해 조정되는 단계 기반 워크플로우를 사용합니다. 각 단계는 정의된 책임과 진행률 가중치를 가집니다.
 
-### 업로드 처리 흐름
+#### 워크플로우 단계 개요
 
-업로드 플러그인은 다음과 같은 단계별 처리 흐름을 따릅니다:
+| 단계 | 이름                | 가중치 | 책임                               |
+| ---- | ------------------- | ------ | ---------------------------------- |
+| 1    | Initialize          | 5%     | 스토리지, pathlib, 기본 검증 설정  |
+| 2    | Process Metadata    | 5%     | 제공된 Excel 메타데이터 처리       |
+| 3    | Analyze Collection  | 5%     | 데이터 컬렉션 사양 검색 및 검증    |
+| 4    | Organize Files      | 10%    | 타입별 파일 발견 및 구성           |
+| 5    | Validate Files      | 5%     | 보안 및 내용 검증                  |
+| 6    | Upload Files        | 30%    | 스토리지에 파일 업로드             |
+| 7    | Generate Data Units | 35%    | 업로드된 파일에서 데이터 단위 생성 |
+| 8    | Cleanup             | 5%     | 임시 리소스 정리                   |
+
+#### 실행 플로우
 
 ```mermaid
 flowchart TD
-    A[파라미터 검증] --> B[스토리지/컬렉션 존재 확인]
-    B --> C[파일 발견 및 필터링]
-    C --> D{Excel 파일 포함?}
-    D -->|예| E[Excel 보안 검증]
-    D -->|아니오| F[일반 파일 처리]
-    E --> G[Excel 메타데이터 추출]
-    G --> H[데이터 단위 생성]
-    F --> H
-    H --> I[배치 업로드 실행]
-    I --> J[진행률 추적]
-    J --> K[결과 반환]
-
-    style A fill:#e3f2fd80,stroke:#1976d2,stroke-width:2px
-    style B fill:#f3e5f580,stroke:#7b1fa2,stroke-width:2px
-    style C fill:#e8f5e880,stroke:#388e3c,stroke-width:2px
-    style D fill:#fff3e080,stroke:#f57c00,stroke-width:2px
-    style E fill:#ffebee80,stroke:#d32f2f,stroke-width:2px
-    style F fill:#e8f5e880,stroke:#388e3c,stroke-width:2px
-    style G fill:#f3e5f580,stroke:#7b1fa2,stroke-width:2px
-    style H fill:#e3f2fd80,stroke:#1976d2,stroke-width:2px
-    style I fill:#fff3e080,stroke:#f57c00,stroke-width:2px
-    style J fill:#e8f5e880,stroke:#388e3c,stroke-width:2px
-    style K fill:#ffebee80,stroke:#d32f2f,stroke-width:2px
-```
-
-이 처리 흐름은 견고성과 보안을 보장하면서 다양한 파일 유형에 대해 최적화된 성능을 제공합니다.
-
-## 빠른 시작
-
-### 기본 사용법
-
-```python
-from synapse_sdk.plugins.categories.upload.actions import upload
-
-# 업로드 매개변수 정의
-params = upload.UploadParams(
-    source_path="/path/to/files",
-    storage_id="your_storage_id",
-    collection_id="your_collection_id",
-    project_id="your_project_id"
-)
+    %% Start
+    A["🚀 업로드 액션 시작"] --> B["📋 UploadContext 생성"]
+    B --> C["⚙️ 전략 구성"]
+    C --> D["📝 워크플로우 단계 등록"]
+    D --> E["🎯 UploadOrchestrator 생성"]
+
+    %% Strategy Injection
+    E --> F["💉 컨텍스트에 전략 주입"]
+    F --> G["📊 진행률 추적 초기화"]
+
+    %% Step Execution Loop
+    G --> H["🔄 단계 실행 루프 시작"]
+    H --> I["📍 다음 단계 가져오기"]
+    I --> J{"🤔 단계를 건너뛸 수 있는가?"}
+    J -->|Yes| K["⏭️ 단계 건너뛰기"]
+    J -->|No| L["▶️ 단계 실행"]
+
+    %% Step Execution
+    L --> M{"✅ 단계 성공?"}
+    M -->|Yes| N["📈 진행률 업데이트"]
+    M -->|No| O["❌ 단계 실패 처리"]
+
+    %% Success Path
+    N --> P["💾 단계 결과 저장"]
+    P --> Q["📝 실행된 단계에 추가"]
+    Q --> R{"🏁 더 많은 단계?"}
+    R -->|Yes| I
+    R -->|No| S["🎉 워크플로우 완료"]
+
+    %% Skip Path
+    K --> T["📊 진행률 업데이트 (건너뛰기)"]
+    T --> R
+
+    %% Error Handling
+    O --> U["🔙 롤백 프로세스 시작"]
+    U --> V["⏪ 실행된 단계 롤백"]
+    V --> W["📝 롤백 결과 로그"]
+    W --> X["💥 예외 전파"]
+
+    %% Final Results
+    S --> Y["📊 최종 메트릭 수집"]
+    Y --> Z["📋 결과 요약 생성"]
+    Z --> AA["🔄 UploadAction으로 반환"]
+
+    %% Apply styles - Light/Dark mode compatible
+    classDef startNode fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000000
+    classDef processNode fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000000
+    classDef decisionNode fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#000000
+    classDef successNode fill:#e8f5e8,stroke:#388e3c,stroke-width:2px,color:#000000
+    classDef errorNode fill:#ffebee,stroke:#d32f2f,stroke-width:2px,color:#000000
+    classDef stepNode fill:#f0f4c3,stroke:#689f38,stroke-width:1px,color:#000000
+
+    class A,B,E startNode
+    class C,D,F,G,H,I,L,N,P,Q,T,Y,Z,AA processNode
+    class J,M,R decisionNode
+    class K,S successNode
+    class O,U,V,W,X errorNode
+```
 
-# 업로드 액션 실행
-action = upload.UploadAction(params=params)
-result = action.run()
+#### 단계 실행 세부사항
 
-print(f"업로드 상태: {result.status}")
+```mermaid
+flowchart TD
+    %% Individual Step Details
+    A["🚀 워크플로우 단계 개요"]
+
+    A --> B1["1. 🏗️ 초기화 단계<br/>가중치: 5%<br/>• 스토리지 연결 설정<br/>• pathlib 액세스 검증<br/>• 컨텍스트 상태 초기화"]
+    A --> B2["2. 📋 메타데이터 처리 단계<br/>가중치: 5%<br/>• Excel 메타데이터 파싱<br/>• 보안 제약 검증<br/>• 파일명 매핑 생성"]
+    A --> B3["3. 🔍 컬렉션 분석 단계<br/>가중치: 5%<br/>• 파일 사양 검색<br/>• 컬렉션 접근 검증<br/>• 구성 규칙 설정"]
+    A --> B4["4. 🗂️ 파일 구성 단계<br/>가중치: 10%<br/>• 파일 발견 (재귀/평면)<br/>• 파일 타입별 그룹화<br/>• 구성된 구조 생성"]
+    A --> B5["5. ✅ 파일 검증 단계<br/>가중치: 5%<br/>• 보안 검증<br/>• 크기 및 내용 검사<br/>• 검증 전략 적용"]
+    A --> B6["6. ⬆️ 파일 업로드 단계<br/>가중치: 30%<br/>• 배치 파일 업로드<br/>• 진행률 추적<br/>• 실패한 업로드 재시도"]
+    A --> B7["7. 🏗️ 데이터 단위 생성 단계<br/>가중치: 35%<br/>• 데이터 단위 생성<br/>• 배치 처리<br/>• 파일을 단위에 연결"]
+    A --> B8["8. 🧹 정리 단계<br/>가중치: 5%<br/>• 임시 파일 정리<br/>• 리소스 해제<br/>• 최종 검증"]
+
+    %% Step Details
+    B1 --> C1["책임사항:<br/>• 클라이언트에서 스토리지 가져오기<br/>• pathlib 작업 디렉터리 초기화<br/>• 기본 업로드 전제조건 검증"]
+    B2 --> C2["책임사항:<br/>• Excel 메타데이터 파일 로드 및 파싱<br/>• 보안 검증 적용<br/>• 파일명-메타데이터 매핑 생성"]
+    B3 --> C3["책임사항:<br/>• 데이터 컬렉션 사양 가져오기<br/>• 파일 타입 요구사항 검증<br/>• 구성 규칙 설정"]
+    B4 --> C4["책임사항:<br/>• 파일 발견 전략 사용<br/>• 파일 필터링 및 분류<br/>• 구성된 파일 구조 생성"]
+    B5 --> C5["책임사항:<br/>• 검증 전략 사용<br/>• 파일 보안 및 내용 검사<br/>• 비즈니스 검증 규칙 적용"]
+    B6 --> C6["책임사항:<br/>• 업로드 전략 사용<br/>• 구성 가능한 배치로 파일 처리<br/>• 진행률 추적 및 실패 처리"]
+    B7 --> C7["책임사항:<br/>• 데이터 단위 전략 사용<br/>• 업로드된 파일에서 데이터 단위 생성<br/>• 파일을 적절한 단위에 연결"]
+    B8 --> C8["책임사항:<br/>• 임시 파일 및 리소스 정리<br/>• 최종 시스템 검증 수행<br/>• 깨끗한 종료 보장"]
+
+    %% Apply styles - Light/Dark mode compatible
+    classDef overviewNode fill:#e3f2fd,stroke:#1976d2,stroke-width:3px,color:#000000
+    classDef stepNode fill:#fff9c4,stroke:#f57c00,stroke-width:2px,color:#000000
+    classDef detailNode fill:#f0f4c3,stroke:#689f38,stroke-width:1px,color:#000000
+
+    class A overviewNode
+    class B1,B2,B3,B4,B5,B6,B7,B8 stepNode
+    class C1,C2,C3,C4,C5,C6,C7,C8 detailNode
 ```
 
-### Excel 파일 업로드
+#### 전략 통합 지점
 
-```python
-from synapse_sdk.plugins.categories.upload.actions import upload
+전략은 워크플로우의 특정 지점에서 주입됩니다:
 
-# Excel 파일에 대한 매개변수
-params = upload.UploadParams(
-    source_path="/path/to/excel/files",
-    storage_id="storage123",
-    collection_id="collection456",
-    project_id="project789",
-    excel_security_config={
-        "check_macros": True,
-        "check_external_links": True,
-        "max_file_size": 50  # MB
-    }
-)
+- **검증 전략**: ValidateFilesStep에서 사용
+- **파일 발견 전략**: OrganizeFilesStep에서 사용
+- **메타데이터 전략**: ProcessMetadataStep에서 사용
+- **업로드 전략**: UploadFilesStep에서 사용
+- **데이터 단위 전략**: GenerateDataUnitsStep에서 사용
+
+#### 오류 처리 및 롤백
 
-action = upload.UploadAction(params=params)
-result = action.run()
+오케스트레이터는 자동 롤백 기능을 제공합니다:
+
+1. **예외 캡처**: 디버깅을 위해 원본 예외 보존
+2. **롤백 실행**: 성공적으로 실행된 모든 단계에서 역순으로 rollback() 호출
+3. **우아한 저하**: 개별 단계 롤백이 실패해도 롤백 계속 진행
+4. **상태 보존**: 실패 후 분석을 위한 실행 상태 유지
+
+## 개발 가이드
+
+이 섹션은 사용자 정의 전략과 워크플로우 단계로 업로드 액션을 확장하기 위한 포괄적인 가이드를 제공합니다.
+
+### 사용자 정의 전략 생성
+
+전략은 업로드 프로세스의 다양한 측면에 대한 특정 동작을 구현합니다. 각 전략 타입은 잘 정의된 인터페이스를 가지고 있습니다.
+
+#### 사용자 정의 검증 전략
+
+```python
+from synapse_sdk.plugins.categories.upload.actions.upload.strategies.validation.base import BaseValidationStrategy
+from synapse_sdk.plugins.categories.upload.actions.upload.context import UploadContext
+
+class CustomValidationStrategy(BaseValidationStrategy):
+    """고급 보안 검사를 포함한 사용자 정의 검증 전략."""
+
+    def validate_files(self, files: List[Path], context: UploadContext) -> bool:
+        """사용자 정의 비즈니스 규칙을 사용하여 파일 검증."""
+        for file_path in files:
+            # 사용자 정의 검증 로직
+            if not self._validate_custom_rules(file_path):
+                return False
+
+            # 보안 검증 호출
+            if not self.validate_security(file_path):
+                return False
+        return True
+
+    def validate_security(self, file_path: Path) -> bool:
+        """사용자 정의 보안 검증."""
+        # 사용자 정의 보안 검사 구현
+        if file_path.suffix in ['.exe', '.bat', '.sh']:
+            return False
+
+        # 파일 크기 검사
+        if file_path.stat().st_size > 100 * 1024 * 1024:  # 100MB
+            return False
+
+        return True
+
+    def _validate_custom_rules(self, file_path: Path) -> bool:
+        """도메인별 검증 규칙 구현."""
+        # 사용자 정의 비즈니스 로직
+        return True
 ```
 
-### 진행률 모니터링
+#### 사용자 정의 파일 발견 전략
 
 ```python
-import asyncio
-from synapse_sdk.plugins.categories.upload.actions import upload
+from synapse_sdk.plugins.categories.upload.actions.upload.strategies.file_discovery.base import BaseFileDiscoveryStrategy
+from pathlib import Path
+from typing import List, Dict, Any
+
+class CustomFileDiscoveryStrategy(BaseFileDiscoveryStrategy):
+    """고급 필터링을 포함한 사용자 정의 파일 발견."""
+
+    def discover_files(self, path: Path, context: UploadContext) -> List[Path]:
+        """사용자 정의 필터링 규칙으로 파일 발견."""
+        files = []
+
+        if context.get_param('is_recursive', False):
+            files = list(path.rglob('*'))
+        else:
+            files = list(path.iterdir())
+
+        # 사용자 정의 필터링 적용
+        return self._apply_custom_filters(files, context)
+
+    def organize_files(self, files: List[Path], specs: Dict[str, Any], context: UploadContext) -> List[Dict[str, Any]]:
+        """사용자 정의 분류를 사용하여 파일 구성."""
+        organized = []
+
+        for file_path in files:
+            if file_path.is_file():
+                category = self._determine_category(file_path)
+                organized.append({
+                    'file_path': file_path,
+                    'category': category,
+                    'metadata': self._extract_file_metadata(file_path)
+                })
+
+        return organized
+
+    def _apply_custom_filters(self, files: List[Path], context: UploadContext) -> List[Path]:
+        """도메인별 파일 필터 적용."""
+        filtered = []
+        for file_path in files:
+            if self._should_include_file(file_path):
+                filtered.append(file_path)
+        return filtered
+
+    def _determine_category(self, file_path: Path) -> str:
+        """사용자 정의 로직을 사용하여 파일 카테고리 결정."""
+        # 사용자 정의 분류 로직
+        ext = file_path.suffix.lower()
+        if ext in ['.jpg', '.png', '.gif']:
+            return 'images'
+        elif ext in ['.pdf', '.doc', '.docx']:
+            return 'documents'
+        else:
+            return 'other'
+```
 
-async def upload_with_progress():
-    params = upload.UploadParams(
-        source_path="/path/to/large/dataset",
-        storage_id="storage123",
-        collection_id="collection456",
-        project_id="project789"
-    )
+#### 사용자 정의 업로드 전략
+
+```python
+from synapse_sdk.plugins.categories.upload.actions.upload.strategies.upload.base import BaseUploadStrategy
+from typing import List, Dict, Any
+
+class CustomUploadStrategy(BaseUploadStrategy):
+    """고급 재시도 로직을 포함한 사용자 정의 업로드 전략."""
+
+    def upload_files(self, files: List[Dict[str, Any]], context: UploadContext) -> List[Dict[str, Any]]:
+        """사용자 정의 배치 및 재시도 로직으로 파일 업로드."""
+        uploaded_files = []
+        batch_size = context.get_param('upload_batch_size', 10)
+
+        # 사용자 정의 배치로 처리
+        for i in range(0, len(files), batch_size):
+            batch = files[i:i + batch_size]
+            batch_results = self.upload_batch(batch, context)
+            uploaded_files.extend(batch_results)
+
+        return uploaded_files
+
+    def upload_batch(self, batch: List[Dict[str, Any]], context: UploadContext) -> List[Dict[str, Any]]:
+        """재시도 로직으로 파일 배치 업로드."""
+        results = []
+
+        for file_info in batch:
+            max_retries = 3
+            for attempt in range(max_retries):
+                try:
+                    result = self._upload_single_file(file_info, context)
+                    results.append(result)
+                    break
+                except Exception as e:
+                    if attempt == max_retries - 1:
+                        # 최종 시도 실패
+                        context.add_error(f"Failed to upload {file_info['file_path']}: {e}")
+                    else:
+                        # 재시도 전 대기
+                        time.sleep(2 ** attempt)
+
+        return results
+
+    def _upload_single_file(self, file_info: Dict[str, Any], context: UploadContext) -> Dict[str, Any]:
+        """사용자 정의 로직으로 단일 파일 업로드."""
+        # 사용자 정의 업로드 구현
+        file_path = file_info['file_path']
+
+        # 컨텍스트에서 스토리지 사용
+        storage = context.storage
+
+        # 여기에 사용자 정의 업로드 로직
+        uploaded_file = {
+            'file_path': str(file_path),
+            'storage_path': f"uploads/{file_path.name}",
+            'size': file_path.stat().st_size,
+            'checksum': self._calculate_checksum(file_path)
+        }
+
+        return uploaded_file
+```
 
-    action = upload.UploadAction(params=params)
+### 사용자 정의 워크플로우 단계 생성
 
-    # 진행률 콜백으로 업로드 실행
-    result = await action.run_async(
-        progress_callback=lambda progress: print(f"진행률: {progress}%")
-    )
+사용자 정의 워크플로우 단계는 기본 단계 클래스를 확장하고 필수 인터페이스를 구현합니다.
 
-    return result
+#### 사용자 정의 처리 단계
 
-# 비동기 업로드 실행
-result = asyncio.run(upload_with_progress())
+```python
+from synapse_sdk.plugins.categories.upload.actions.upload.steps.base import BaseStep
+from synapse_sdk.plugins.categories.upload.actions.upload.context import UploadContext, StepResult
+from pathlib import Path
+
+class CustomProcessingStep(BaseStep):
+    """특수 파일 처리를 위한 사용자 정의 처리 단계."""
+
+    @property
+    def name(self) -> str:
+        return 'custom_processing'
+
+    @property
+    def progress_weight(self) -> float:
+        return 0.15  # 전체 워크플로우의 15%
+
+    def execute(self, context: UploadContext) -> StepResult:
+        """사용자 정의 처리 로직 실행."""
+        try:
+            # 사용자 정의 처리 로직
+            processed_files = self._process_files(context)
+
+            # 결과로 컨텍스트 업데이트
+            return self.create_success_result({
+                'processed_files': processed_files,
+                'processing_stats': self._get_processing_stats()
+            })
+
+        except Exception as e:
+            return self.create_error_result(f'Custom processing failed: {str(e)}')
+
+    def can_skip(self, context: UploadContext) -> bool:
+        """단계를 건너뛸 수 있는지 결정."""
+        # 처리할 파일이 없으면 건너뛰기
+        return len(context.organized_files) == 0
+
+    def rollback(self, context: UploadContext) -> None:
+        """사용자 정의 처리 작업 롤백."""
+        # 처리 중에 생성된 리소스 정리
+        self._cleanup_processing_resources(context)
+
+    def _process_files(self, context: UploadContext) -> List[Dict]:
+        """사용자 정의 파일 처리 구현."""
+        processed = []
+
+        for file_info in context.organized_files:
+            # 사용자 정의 처리 로직
+            result = self._process_single_file(file_info)
+            processed.append(result)
+
+        return processed
+
+    def _process_single_file(self, file_info: Dict) -> Dict:
+        """단일 파일 처리."""
+        # 사용자 정의 처리 구현
+        return {
+            'original': file_info,
+            'processed': True,
+            'timestamp': datetime.now()
+        }
 ```
 
-## API 참조
+### 전략 팩토리 확장
+
+사용자 정의 전략을 사용 가능하게 하려면 StrategyFactory를 확장하세요:
+
+```python
+from synapse_sdk.plugins.categories.upload.actions.upload.factory import StrategyFactory
+
+class CustomStrategyFactory(StrategyFactory):
+    """사용자 정의 전략을 포함한 확장 팩토리."""
+
+    def create_validation_strategy(self, params: Dict, context=None):
+        """사용자 정의 옵션으로 검증 전략 생성."""
+        validation_type = params.get('custom_validation_type', 'default')
 
-### UploadAction
+        if validation_type == 'strict':
+            return CustomValidationStrategy()
+        else:
+            return super().create_validation_strategy(params, context)
 
-업로드 작업을 관리하는 주요 클래스입니다.
+    def create_file_discovery_strategy(self, params: Dict, context=None):
+        """사용자 정의 옵션으로 파일 발견 전략 생성."""
+        discovery_mode = params.get('discovery_mode', 'default')
+
+        if discovery_mode == 'advanced':
+            return CustomFileDiscoveryStrategy()
+        else:
+            return super().create_file_discovery_strategy(params, context)
+```
+
+### 사용자 정의 업로드 액션
+
+포괄적인 커스터마이제이션을 위해서는 UploadAction 자체를 확장하세요:
 
 ```python
-class UploadAction:
-    def __init__(self, params: UploadParams, run: Optional[UploadRun] = None):
-        """
-        업로드 액션을 초기화합니다.
+from synapse_sdk.plugins.categories.upload.actions.upload.action import UploadAction
+from synapse_sdk.plugins.categories.decorators import register_action
+
+@register_action
+class CustomUploadAction(UploadAction):
+    """확장 워크플로우를 포함한 사용자 정의 업로드 액션."""
+
+    name = 'custom_upload'
 
-        Args:
-            params: 업로드 매개변수
-            run: 선택적 실행 인스턴스
-        """
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # 사용자 정의 전략 팩토리 사용
+        self.strategy_factory = CustomStrategyFactory()
+
+    def _configure_workflow(self) -> None:
+        """추가 단계로 사용자 정의 워크플로우 구성."""
+        # 표준 단계 등록
+        super()._configure_workflow()
+
+        # 사용자 정의 처리 단계 추가
+        self.step_registry.register(CustomProcessingStep())
+
+    def _configure_strategies(self, context=None) -> Dict[str, Any]:
+        """사용자 정의 매개변수로 전략 구성."""
+        strategies = super()._configure_strategies(context)
+
+        # 사용자 정의 전략 추가
+        strategies['custom_processing'] = self._create_custom_processing_strategy()
+
+        return strategies
+
+    def _create_custom_processing_strategy(self):
+        """사용자 정의 처리 전략 생성."""
+        return CustomProcessingStrategy(self.params)
 ```
 
-#### 메서드
+### 사용자 정의 컴포넌트 테스트
 
-- `run() -> UploadResult`: 동기적으로 업로드를 실행합니다
-- `run_async() -> UploadResult`: 비동기적으로 업로드를 실행합니다
-- `validate_params() -> bool`: 업로드 매개변수를 검증합니다
-- `discover_files() -> List[str]`: 업로드할 파일을 발견합니다
-- `process_excel_metadata() -> Dict`: Excel 파일에서 메타데이터를 추출합니다
+#### 사용자 정의 전략 테스트
 
-### UploadParams
+```python
+import pytest
+from unittest.mock import Mock
+from pathlib import Path
+
+class TestCustomValidationStrategy:
+
+    def setup_method(self):
+        self.strategy = CustomValidationStrategy()
+        self.context = Mock()
+
+    def test_validate_files_success(self):
+        """성공적인 파일 검증 테스트."""
+        files = [Path('/test/file1.txt'), Path('/test/file2.jpg')]
+        result = self.strategy.validate_files(files, self.context)
+        assert result is True
+
+    def test_validate_files_security_failure(self):
+        """보안상 이유로 검증 실패 테스트."""
+        files = [Path('/test/malware.exe')]
+        result = self.strategy.validate_files(files, self.context)
+        assert result is False
+
+    def test_validate_large_file_failure(self):
+        """큰 파일에 대한 검증 실패 테스트."""
+        # 큰 크기를 반환하도록 파일 stat 모킹
+        large_file = Mock(spec=Path)
+        large_file.suffix = '.txt'
+        large_file.stat.return_value.st_size = 200 * 1024 * 1024  # 200MB
+
+        result = self.strategy.validate_security(large_file)
+        assert result is False
+```
 
-업로드 구성을 위한 매개변수 모델입니다.
+#### 사용자 정의 단계 테스트
 
 ```python
-class UploadParams(BaseModel):
-    source_path: str
-    storage_id: str
-    collection_id: str
-    project_id: str
-    excel_security_config: Optional[ExcelSecurityConfig] = None
-    batch_size: int = 100
-    max_workers: int = 4
-    include_patterns: Optional[List[str]] = None
-    exclude_patterns: Optional[List[str]] = None
+class TestCustomProcessingStep:
+
+    def setup_method(self):
+        self.step = CustomProcessingStep()
+        self.context = Mock()
+        self.context.organized_files = [
+            {'file_path': '/test/file1.txt'},
+            {'file_path': '/test/file2.jpg'}
+        ]
+
+    def test_execute_success(self):
+        """성공적인 단계 실행 테스트."""
+        result = self.step.execute(self.context)
+
+        assert result.success is True
+        assert 'processed_files' in result.data
+        assert len(result.data['processed_files']) == 2
+
+    def test_can_skip_with_no_files(self):
+        """단계 건너뛰기 로직 테스트."""
+        self.context.organized_files = []
+        assert self.step.can_skip(self.context) is True
+
+    def test_rollback_cleanup(self):
+        """롤백 정리 테스트."""
+        # 이것은 예외를 발생시키지 않아야 함
+        self.step.rollback(self.context)
 ```
 
-#### 필드
+## 업로드 매개변수
+
+업로드 액션은 포괄적인 매개변수 검증을 위해 `UploadParams`를 사용합니다:
+
+### 필수 매개변수
+
+| 매개변수          | 타입  | 설명                    | 검증                   |
+| ----------------- | ----- | ----------------------- | ---------------------- |
+| `name`            | `str` | 읽기 쉬운 업로드 이름   | 빈 값이 아니어야 함    |
+| `path`            | `str` | 소스 파일/디렉토리 경로 | 유효한 경로여야 함     |
+| `storage`         | `int` | 대상 스토리지 ID        | API를 통해 존재해야 함 |
+| `data_collection` | `int` | 데이터 컬렉션 ID        | API를 통해 존재해야 함 |
 
-- **source_path**: 업로드할 파일의 소스 경로
-- **storage_id**: 대상 스토리지 식별자
-- **collection_id**: 대상 컬렉션 식별자
-- **project_id**: 대상 프로젝트 식별자
-- **excel_security_config**: Excel 보안 설정 (선택사항)
-- **batch_size**: 배치 처리 크기 (기본값: 100)
-- **max_workers**: 최대 작업자 수 (기본값: 4)
-- **include_patterns**: 포함할 파일 패턴 (선택사항)
-- **exclude_patterns**: 제외할 파일 패턴 (선택사항)
+### 선택적 매개변수
+
+| 매개변수                        | 타입          | 기본값  | 설명                        |
+| ------------------------------- | ------------- | ------- | --------------------------- |
+| `description`                   | `str \| None` | `None`  | 업로드 설명                 |
+| `project`                       | `int \| None` | `None`  | 프로젝트 ID (제공시 검증됨) |
+| `excel_metadata_path`           | `str \| None` | `None`  | Excel 메타데이터 파일 경로  |
+| `is_recursive`                  | `bool`        | `False` | 디렉토리를 재귀적으로 스캔  |
+| `max_file_size_mb`              | `int`         | `50`    | 최대 파일 크기 (MB)         |
+| `creating_data_unit_batch_size` | `int`         | `100`   | 데이터 단위 배치 크기       |
+| `use_async_upload`              | `bool`        | `True`  | 비동기 처리 사용            |
 
 ### 매개변수 검증
 
-UploadParams는 Pydantic 모델을 사용하여 포괄적인 검증을 제공합니다:
+시스템은 실시간 검증을 수행합니다:
 
 ```python
-# 필수 매개변수 검증
-params = upload.UploadParams(
-    source_path="/valid/directory",  # 존재하는 디렉터리여야 함
-    storage_id="storage_123",        # 비어있지 않은 문자열
-    collection_id="collection_456",  # 비어있지 않은 문자열
-    project_id="project_789"         # 비어있지 않은 문자열
-)
-
-# 스토리지 및 컬렉션 존재 검증
-try:
-    action = upload.UploadAction(params=params)
-    result = action.run()
-except ValidationError as e:
-    print(f"매개변수 검증 실패: {e}")
+# 스토리지 검증
+@field_validator('storage', mode='before')
+@classmethod
+def check_storage_exists(cls, value: str, info) -> str:
+    action = info.context['action']
+    client = action.client
+    try:
+        client.get_storage(value)
+    except ClientError:
+        raise PydanticCustomError('client_error', 'Storage not found')
+    return value
 ```
 
 **검증 규칙:**
@@ -296,25 +858,13 @@ Excel 파일 보안 설정:
 
 ```python
 class ExcelSecurityConfig:
-    check_macros: bool = True
-    check_external_links: bool = True
-    max_file_size: int = 50  # MB
-    allowed_extensions: List[str] = [".xlsx", ".xls"]
-```
-
-#### ExcelMetadataUtils
-
-Excel 메타데이터 추출을 위한 유틸리티:
-
-```python
-class ExcelMetadataUtils:
-    @staticmethod
-    def extract_metadata(file_path: str) -> Dict:
-        """Excel 파일에서 메타데이터를 추출합니다."""
+    max_file_size_mb: int = 10      # 파일 크기 제한 (MB)
+    max_rows: int = 100000          # 행 수 제한
+    max_columns: int = 50           # 열 수 제한
 
-    @staticmethod
-    def get_sheet_info(file_path: str) -> List[Dict]:
-        """Excel 시트 정보를 가져옵니다."""
+    @classmethod
+    def from_action_config(cls, action_config) -> 'ExcelSecurityConfig':
+        """config.yaml에서 설정을 로드합니다."""
 ```
 
 #### PathAwareJSONEncoder
@@ -343,555 +893,1185 @@ class PathAwareJSONEncoder:
 
 ## Excel 메타데이터 처리
 
+업로드 플러그인은 포괄적인 파일명 매칭, 유연한 헤더 지원 및 최적화된 성능을 통한 고급 Excel 메타데이터 처리를 제공합니다:
+
 ### Excel 파일 형식
 
-업로드 플러그인은 다음 Excel 형식을 지원합니다:
+Excel 파일은 유연한 헤더 형식과 포괄적인 파일명 매칭을 지원합니다:
+
+#### 지원되는 헤더 형식
+
+대소문자를 구분하지 않는 매칭으로 두 헤더 형식 모두 지원됩니다:
+
+**옵션 1: "filename" 헤더**
+| filename | category | description | custom_field |
+| ---------- | -------- | ------------------ | ------------ |
+| image1.jpg | nature | Mountain landscape | high_res |
+| image2.png | urban | City skyline | processed |
+
+**옵션 2: "file_name" 헤더**  
+| file_name | category | description | custom_field |
+| ---------- | -------- | ------------------ | ------------ |
+| image1.jpg | nature | Mountain landscape | high_res |
+| image2.png | urban | City skyline | processed |
 
-- **XLSX**: Office Open XML 형식 (권장)
-- **XLS**: 레거시 Excel 형식 (제한적 지원)
+#### 파일명 매칭 전략
+
+시스템은 파일과 메타데이터를 연결하기 위해 포괄적인 5단계 우선순위 매칭 알고리즘을 사용합니다:
+
+1. **정확한 stem 매칭** (최우선): `image1`이 `image1.jpg`와 매칭
+2. **정확한 파일명 매칭**: `image1.jpg`가 `image1.jpg`와 매칭
+3. **메타데이터 키 stem 매칭**: `path/image1.ext` stem이 `image1`과 매칭
+4. **부분 경로 매칭**: `/uploads/image1.jpg`에 `image1` 포함
+5. **전체 경로 매칭**: 복잡한 구조에 대한 완전한 경로 매칭
+
+이 강력한 매칭은 파일 구성이나 명명 규칙에 관계없이 메타데이터가 올바르게 연결되도록 보장합니다.
 
 ### 보안 검증
 
-Excel 파일에 대해 포괄적인 보안 검사를 수행합니다:
+Excel 파일은 포괄적인 보안 검증을 받습니다:
 
 ```python
-# 보안 구성 예제
-security_config = {
-    "check_macros": True,           # 매크로 탐지
-    "check_external_links": True,   # 외부 링크 탐지
-    "max_file_size": 50,           # 최대 파일 크기 (MB)
-    "max_memory_usage": 100,       # 최대 메모리 사용량 (MB)
-    "max_rows": 1000000,           # 최대 행 수
-    "max_columns": 16384,          # 최대 열 수
-}
+class ExcelSecurityConfig:
+    max_file_size_mb: int = 10      # 파일 크기 제한 (MB)
+    max_rows: int = 100000          # 행 수 제한
+    max_columns: int = 50           # 열 수 제한
 ```
 
-### 환경 구성
+#### 고급 보안 기능
 
-환경 변수를 통해 Excel 처리 설정을 재정의할 수 있습니다:
+- **파일 형식 검증**: Excel 파일 시그니처 확인 (.xlsx의 경우 PK, .xls의 경우 복합 문서)
+- **메모리 추정**: 대용량 스프레드시트로 인한 메모리 고갈 방지
+- **내용 정화**: 지나치게 긴 값의 자동 잘라내기
+- **오류 복원력**: 손상되거나 접근할 수 없는 파일의 우아한 처리
 
-```bash
-# 메모리 제한 설정
-export EXCEL_MAX_MEMORY_MB=200
+### config.yaml을 통한 구성
 
-# 파일 크기 제한 설정
-export EXCEL_MAX_FILE_SIZE_MB=100
+보안 제한 및 처리 옵션을 구성할 수 있습니다:
 
-# 행/열 제한 설정
-export EXCEL_MAX_ROWS=500000
-export EXCEL_MAX_COLUMNS=1000
+```yaml
+actions:
+  upload:
+    excel_config:
+      max_file_size_mb: 10 # Excel 파일 최대 크기 (MB)
+      max_rows: 100000 # 허용되는 최대 행 수
+      max_columns: 50 # 허용되는 최대 열 수
 ```
 
-### 메타데이터 처리 흐름
+### 성능 최적화
+
+Excel 메타데이터 처리에는 여러 성능 향상 기능이 포함되어 있습니다:
 
-```mermaid
-flowchart TD
-    A[Excel 파일 발견] --> B[보안 검증]
-    B --> C{검증 통과?}
-    C -->|실패| D[보안 오류 발생]
-    C -->|통과| E[시트 정보 추출]
-    E --> F[행/열 수 확인]
-    F --> G[메타데이터 수집]
-    G --> H[JSON 직렬화]
-    H --> I[데이터 단위 생성]
-
-    style A fill:#e3f2fd80,stroke:#1976d2,stroke-width:2px
-    style B fill:#ffebee80,stroke:#d32f2f,stroke-width:2px
-    style C fill:#fff3e080,stroke:#f57c00,stroke-width:2px
-    style D fill:#ffcdd280,stroke:#d32f2f,stroke-width:2px
-    style E fill:#e8f5e880,stroke:#388e3c,stroke-width:2px
-    style F fill:#f3e5f580,stroke:#7b1fa2,stroke-width:2px
-    style G fill:#e3f2fd80,stroke:#1976d2,stroke-width:2px
-    style H fill:#fff3e080,stroke:#f57c00,stroke-width:2px
-    style I fill:#e8f5e880,stroke:#388e3c,stroke-width:2px
-```
+#### 메타데이터 인덱싱
 
-## 파일 구성
+- **O(1) 해시 검색**: 정확한 stem 및 파일명 매칭용
+- **사전 구축된 인덱스**: 일반적인 매칭 패턴용
+- **대체 알고리즘**: 복잡한 경로 매칭 시나리오용
+
+#### 효율적인 처리
 
-### 타입 탐지
+- **최적화된 행 처리**: 빈 행을 조기에 건너뛰기
+- **메모리 인식 작업**: 배치로 파일 처리
+- **스마트 파일 발견**: 반복되는 변환을 피하기 위한 경로 문자열 캐시
 
-업로드 플러그인은 파일 확장자와 MIME 타입을 기반으로 파일 유형을 자동 탐지합니다:
+### 메타데이터 처리 플로우
+
+1. **보안 검증**: 파일 크기, 형식 및 내용 제한
+2. **헤더 검증**: 대소문자를 구분하지 않는 매칭으로 "filename" 및 "file_name" 모두 지원
+3. **인덱스 구축**: 성능을 위한 O(1) 검색 구조 생성
+4. **내용 처리**: 최적화를 통한 행별 메타데이터 추출
+5. **데이터 정화**: 자동 잘라내기 및 검증
+6. **패턴 매칭**: 5단계 파일명 연결 알고리즘
+7. **매핑 생성**: 최적화된 파일명에서 메타데이터로의 매핑
+
+### Excel 메타데이터 매개변수
+
+사용자 정의 Excel 메타데이터 파일 경로를 지정할 수 있습니다:
 
 ```python
-# 지원되는 파일 유형
-SUPPORTED_EXTENSIONS = {
-    '.xlsx': 'Excel 워크북',
-    '.xls': 'Excel 레거시',
-    '.csv': 'CSV 파일',
-    '.txt': '텍스트 파일',
-    '.json': 'JSON 데이터',
-    '.jpg': 'JPEG 이미지',
-    '.png': 'PNG 이미지',
-    '.pdf': 'PDF 문서'
+params = {
+    "name": "Excel 메타데이터 업로드",
+    "path": "/data/files",
+    "storage": 1,
+    "data_collection": 5,
+    "excel_metadata_path": "/data/custom_metadata.xlsx"  # 사용자 정의 Excel 파일
 }
 ```
 
-### 디렉터리 구조
+#### 경로 해결
+
+- **절대 경로**: 존재하고 접근 가능한 경우 직접 사용
+- **상대 경로**: 업로드 경로에 상대적으로 해결
+- **기본 발견**: 경로가 지정되지 않은 경우 자동으로 `meta.xlsx` 또는 `meta.xls` 검색
+- **스토리지 통합**: 적절한 경로 해결을 위해 스토리지 구성 사용
+
+### 오류 처리
+
+포괄적인 오류 처리로 강력한 작업을 보장합니다:
+
+```python
+# Excel 처리 오류는 우아하게 처리됩니다
+try:
+    metadata = process_excel_metadata(excel_path)
+except ExcelSecurityError as e:
+    # 보안 위반 - 파일이 너무 크거나 행이 너무 많음 등
+    log_security_violation(e)
+except ExcelParsingError as e:
+    # 파싱 실패 - 손상된 파일, 잘못된 형식 등
+    log_parsing_error(e)
+```
+
+#### 오류 복구
+
+- **우아한 성능 저하**: Excel이 실패하면 빈 메타데이터로 처리 계속
+- **상세 로깅**: 다양한 실패 유형에 대한 특정 오류 코드
+- **경로 검증**: 매개변수 처리 중 포괄적인 검증
+- **대체 동작**: 메타데이터를 처리할 수 없을 때 스마트 기본값
+
+## 파일 구성
+
+업로드 시스템은 파일을 타입에 따라 자동으로 구성합니다:
+
+### 타입 감지
+
+파일은 다음을 기반으로 분류됩니다:
 
-복잡한 디렉터리 구조를 효율적으로 처리합니다:
+- 파일 확장자 패턴
+- MIME 타입 감지
+- 내용 분석
+- 사용자 정의 타입 규칙
+
+### 디렉토리 구조
 
 ```
-source_directory/
-├── excel_files/
-│   ├── data1.xlsx
-│   └── data2.xlsx
+upload_output/
 ├── images/
-│   ├── photo1.jpg
-│   └── photo2.png
-└── documents/
-    ├── report.pdf
-    └── notes.txt
+│   ├── image1.jpg
+│   └── image2.png
+├── documents/
+│   ├── report.pdf
+│   └── data.xlsx
+└── videos/
+    └── presentation.mp4
 ```
 
 ### 배치 처리
 
-파일들을 효율적인 배치로 그룹화합니다:
+파일은 구성 가능한 배치로 처리됩니다:
 
-- **유형별 그룹화**: 동일한 처리 로직을 사용하는 파일들을 함께 처리
-- **크기 기반 분할**: 메모리 사용량을 제어하기 위해 큰 파일들을 별도로 처리
-- **병렬 처리**: 독립적인 배치들을 동시에 처리
+```python
+# 배치 크기 구성
+params = {
+    "creating_data_unit_batch_size": 100,
+    "use_async_upload": True
+}
+```
 
 ## 진행률 추적 및 메트릭
 
 ### 진행률 카테고리
 
-업로드 과정에서 다음 진행률 카테고리를 추적합니다:
+업로드 액션은 세 가지 주요 단계에서 진행률을 추적합니다:
 
-```python
-# 진행률 카테고리
-PROGRESS_CATEGORIES = {
-    'file_discovery': '파일 발견',
-    'validation': '검증',
-    'excel_processing': 'Excel 처리',
-    'metadata_extraction': '메타데이터 추출',
-    'upload_preparation': '업로드 준비',
-    'data_upload': '데이터 업로드',
-    'finalization': '완료 처리'
-}
-```
+| 카테고리              | 비율 | 설명                     |
+| --------------------- | ---- | ------------------------ |
+| `analyze_collection`  | 2%   | 매개변수 검증 및 설정    |
+| `upload_data_files`   | 38%  | 파일 업로드 처리         |
+| `generate_data_units` | 60%  | 데이터 단위 생성 및 완료 |
 
 ### 메트릭 수집
 
-상세한 성능 메트릭을 수집하여 분석에 활용할 수 있습니다:
+모니터링을 위해 실시간 메트릭이 수집됩니다:
 
 ```python
-# 수집되는 메트릭
-metrics = {
-    "processing_time": {
-        "file_discovery": 2.5,        # 초
-        "excel_processing": 15.2,
-        "upload": 45.8
+metrics_categories = {
+    'data_files': {
+        'stand_by': 0,    # 처리 대기 중인 파일
+        'failed': 0,      # 업로드 실패한 파일
+        'success': 0,     # 성공적으로 업로드된 파일
     },
-    "file_statistics": {
-        "total_files": 150,
-        "excel_files": 25,
-        "image_files": 100,
-        "other_files": 25
+    'data_units': {
+        'stand_by': 0,    # 생성 대기 중인 단위
+        'failed': 0,      # 생성 실패한 단위
+        'success': 0,     # 성공적으로 생성된 단위
     },
-    "data_volume": {
-        "total_size_mb": 2048,
-        "excel_data_mb": 512,
-        "media_data_mb": 1536
-    }
 }
 ```
 
 ## 타입 안전 로깅
 
+업로드 시스템은 일관성을 위해 열거형 기반 로깅을 사용합니다:
+
 ### 로그 코드
 
-모든 로깅 작업에 타입 안전 코드를 사용합니다:
+```python
+class LogCode(str, Enum):
+    VALIDATION_FAILED = 'VALIDATION_FAILED'
+    NO_FILES_FOUND = 'NO_FILES_FOUND'
+    EXCEL_SECURITY_VIOLATION = 'EXCEL_SECURITY_VIOLATION'
+    EXCEL_PARSING_ERROR = 'EXCEL_PARSING_ERROR'
+    FILES_DISCOVERED = 'FILES_DISCOVERED'
+    UPLOADING_DATA_FILES = 'UPLOADING_DATA_FILES'
+    GENERATING_DATA_UNITS = 'GENERATING_DATA_UNITS'
+    IMPORT_COMPLETED = 'IMPORT_COMPLETED'
+```
+
+### 로깅 사용법
 
 ```python
-# 검증 관련 로그 코드
-VALIDATION_FAILED = "UPLOAD_001"
-STORAGE_VALIDATION_FAILED = "UPLOAD_002"
-COLLECTION_VALIDATION_FAILED = "UPLOAD_003"
+# 기본 로깅
+run.log_message_with_code(LogCode.FILES_DISCOVERED, file_count)
+
+# 사용자 정의 레벨로
+run.log_message_with_code(
+    LogCode.EXCEL_SECURITY_VIOLATION,
+    filename,
+    level=Context.DANGER
+)
+
+# 업로드 특정 이벤트
+run.log_upload_event(LogCode.UPLOADING_DATA_FILES, batch_size)
+```
+
+## 마이그레이션 가이드
+
+### 레거시에서 리팩토링된 아키텍처로
+
+업로드 액션은 **100% 하위 호환성**을 유지하면서 현대적인 디자인 패턴을 사용하여 리팩토링되었습니다. 기존 코드는 변경 없이 계속 작동합니다.
+
+#### 주요 변경 사항
+
+**이전 (레거시 모놀리식):**
+
+- 모든 로직을 포함한 단일 900+ 줄 액션 클래스
+- 검증, 파일 발견 등에 대한 하드코딩된 동작
+- 확장성이나 커스터마이제이션 옵션 없음
+- 전반에 걸친 수동 오류 처리
 
-# 파일 처리 관련 로그 코드
-NO_FILES_FOUND = "UPLOAD_004"
-FILES_DISCOVERED = "UPLOAD_005"
-FILE_FILTERED = "UPLOAD_006"
+**이후 (전략/파사드 패턴):**
 
-# Excel 처리 관련 로그 코드
-EXCEL_SECURITY_VIOLATION = "UPLOAD_010"
-EXCEL_PARSING_ERROR = "UPLOAD_011"
-EXCEL_METADATA_EXTRACTED = "UPLOAD_012"
+- 8개 워크플로우 단계로 명확한 관심사 분리
+- 다양한 동작을 위한 플러그형 전략
+- 사용자 정의 구현을 위한 확장 가능한 아키텍처
+- 자동 롤백 및 포괄적인 오류 처리
 
-# 진행률 관련 로그 코드
-UPLOADING_DATA_FILES = "UPLOAD_020"
-GENERATING_DATA_UNITS = "UPLOAD_021"
-UPLOAD_PROGRESS = "UPLOAD_022"
+#### 하위 호환성
+
+```python
+# 이 레거시 사용법은 동일하게 작동합니다
+from synapse_sdk.plugins.categories.upload.actions.upload.action import UploadAction
+
+params = {
+    "name": "My Upload",
+    "path": "/data/files",
+    "storage": 1,
+    "data_collection": 5  # 'collection'에서 'data_collection'으로 변경
+}
+
+action = UploadAction(params=params, plugin_config=config)
+result = action.start()  # 이전과 동일하게 작동
 ```
 
-### 로깅 사용법
+#### 향상된 기능
 
-구조화된 로깅으로 일관된 메시지 형식을 보장합니다:
+리팩토링된 아키텍처는 새로운 기능을 제공합니다:
 
 ```python
-# 로그 메시지 예제
-run.log_message_with_code(
-    LogCode.FILES_DISCOVERED,
-    file_count=25,
-    directory=source_path
-)
-# 출력: [UPLOAD_005] INFO: 25개 파일 발견: /path/to/files
+# 자세한 워크플로우 정보 가져오기
+action = UploadAction(params=params, plugin_config=config)
+workflow_info = action.get_workflow_summary()
+print(f"Configured with {workflow_info['step_count']} steps")
+print(f"Available strategies: {workflow_info['available_strategies']}")
+
+# 실행하고 자세한 결과 가져오기
+result = action.start()
+print(f"Success: {result['success']}")
+print(f"Uploaded files: {result['uploaded_files_count']}")
+print(f"Generated data units: {result['generated_data_units_count']}")
+print(f"Errors: {result['errors']}")
+print(f"Metrics: {result['metrics']}")
 ```
 
-## 고급 사용법
+#### 매개변수 변경
+
+하나의 매개변수 이름만 변경되었습니다:
+
+| 레거시             | 리팩토링          | 상태          |
+| ------------------ | ----------------- | ------------- |
+| `collection`       | `data_collection` | **필수 변경** |
+| 기타 모든 매개변수 | 변경 없음         | 완전 호환     |
+
+#### 마이그레이션의 이점
+
+- **더 나은 오류 처리**: 실패 시 자동 롤백
+- **진행률 추적**: 워크플로우 단계 전반의 자세한 진행률 메트릭
+- **확장성**: 사용자 정의 전략 및 단계 추가
+- **테스트**: 모킹 친화적인 아키텍처로 더 나은 테스트 가능성
+- **유지보수성**: 명확한 관심사 분리
+- **성능**: 더 효율적인 리소스 관리
+
+## 사용 예제
 
-### 사용자 정의 파일 필터링
+### 기본 파일 업로드 (리팩토링된 아키텍처)
 
 ```python
-from synapse_sdk.plugins.categories.upload.actions import upload
+from synapse_sdk.plugins.categories.upload.actions.upload.action import UploadAction
+
+# 새 아키텍처로 기본 업로드 구성
+params = {
+    "name": "Dataset Upload",
+    "description": "Training dataset for ML model",
+    "path": "/data/training_images",
+    "storage": 1,
+    "data_collection": 5,  # 참고: 'collection' 대신 'data_collection'
+    "is_recursive": True,
+    "max_file_size_mb": 100
+}
 
-params = upload.UploadParams(
-    source_path="/path/to/mixed/files",
-    storage_id="storage123",
-    collection_id="collection456",
-    project_id="project789",
-    include_patterns=["*.xlsx", "*.jpg", "*.png"],
-    exclude_patterns=["*temp*", "*backup*"]
+action = UploadAction(
+    params=params,
+    plugin_config=plugin_config
 )
 
-action = upload.UploadAction(params=params)
-result = action.run()
+# 자동 단계 기반 워크플로우 및 롤백으로 실행
+result = action.start()
+
+# 향상된 결과 정보
+print(f"Upload successful: {result['success']}")
+print(f"Uploaded {result['uploaded_files_count']} files")
+print(f"Generated {result['generated_data_units_count']} data units")
+print(f"Workflow errors: {result['errors']}")
+
+# 자세한 메트릭에 액세스
+workflow_metrics = result['metrics'].get('workflow', {})
+print(f"Total steps executed: {workflow_metrics.get('current_step', 0)}")
+print(f"Progress completed: {workflow_metrics.get('progress_percentage', 0)}%")
 ```
 
-### 배치 크기 최적화
+### 진행률 추적이 포함된 Excel 메타데이터 업로드
 
 ```python
-# 대용량 파일에 대한 더 작은 배치 크기
-params = upload.UploadParams(
-    source_path="/path/to/large/files",
-    storage_id="storage123",
-    collection_id="collection456",
-    project_id="project789",
-    batch_size=50,  # 메모리 사용량 감소
-    max_workers=2   # 리소스 사용량 감소
+# Excel 메타데이터 및 진행률 모니터링으로 업로드
+params = {
+    "name": "Annotated Dataset Upload",
+    "path": "/data/images",
+    "storage": 1,
+    "data_collection": 5,
+    "excel_metadata_path": "/data/metadata.xlsx",
+    "is_recursive": False,
+    "creating_data_unit_batch_size": 50
+}
+
+action = UploadAction(
+    params=params,
+    plugin_config=plugin_config
 )
+
+# 실행 전 워크플로우 요약 가져오기
+workflow_info = action.get_workflow_summary()
+print(f"Workflow configured with {workflow_info['step_count']} steps")
+print(f"Total progress weight: {workflow_info['total_progress_weight']}")
+print(f"Steps: {workflow_info['steps']}")
+
+# 향상된 오류 처리로 실행
+try:
+    result = action.start()
+    if result['success']:
+        print("Upload completed successfully!")
+        print(f"Files: {result['uploaded_files_count']}")
+        print(f"Data units: {result['generated_data_units_count']}")
+    else:
+        print("Upload failed with errors:")
+        for error in result['errors']:
+            print(f"  - {error}")
+except Exception as e:
+    print(f"Upload action failed: {e}")
 ```
 
-### Excel 보안 구성
+### 사용자 정의 전략 업로드
 
 ```python
-# 엄격한 보안 설정
-excel_config = upload.ExcelSecurityConfig(
-    check_macros=True,
-    check_external_links=True,
-    max_file_size=25,  # 25MB 제한
-    allowed_extensions=[".xlsx"]  # .xls 파일 제외
-)
+from synapse_sdk.plugins.categories.upload.actions.upload.action import UploadAction
+from my_custom_strategies import CustomValidationStrategy
+
+# 사용자 정의 팩토리로 액션 생성
+class CustomUploadAction(UploadAction):
+    def _configure_strategies(self, context=None):
+        strategies = super()._configure_strategies(context)
+
+        # 사용자 정의 검증으로 오버라이드
+        if self.params.get('use_strict_validation'):
+            strategies['validation'] = CustomValidationStrategy()
+
+        return strategies
+
+# 사용자 정의 액션 사용
+params = {
+    "name": "Strict Validation Upload",
+    "path": "/data/sensitive_files",
+    "storage": 1,
+    "data_collection": 5,
+    "use_strict_validation": True,
+    "max_file_size_mb": 10  # 더 엄격한 제한
+}
 
-params = upload.UploadParams(
-    source_path="/path/to/excel/files",
-    storage_id="storage123",
-    collection_id="collection456",
-    project_id="project789",
-    excel_security_config=excel_config
+action = CustomUploadAction(
+    params=params,
+    plugin_config=plugin_config
 )
+
+result = action.start()
 ```
 
-## 오류 처리
+### 사용자 정의 구성을 포함한 배치 처리
 
-업로드 플러그인은 다양한 오류 상황에 대한 포괄적인 오류 처리를 제공합니다:
+```python
+import os
+
+# Excel 처리 제한 구성
+os.environ['EXCEL_MAX_FILE_SIZE_MB'] = '20'
+os.environ['EXCEL_MAX_ROWS'] = '20000'
+
+# 사용자 정의 설정을 포함한 대량 배치 업로드
+params = {
+    "name": "Large Batch Upload",
+    "path": "/data/large_dataset",
+    "storage": 2,
+    "data_collection": 10,
+    "is_recursive": True,
+    "max_file_size_mb": 500,
+    "creating_data_unit_batch_size": 200,
+    "use_async_upload": True
+}
+
+action = UploadAction(
+    params=params,
+    plugin_config=plugin_config
+)
+
+# 진행률 모니터링으로 실행
+result = action.start()
+
+# 결과 분석
+print(f"Batch upload summary:")
+print(f"  Success: {result['success']}")
+print(f"  Files processed: {result['uploaded_files_count']}")
+print(f"  Data units created: {result['generated_data_units_count']}")
+
+# 카테고리별 메트릭 확인
+metrics = result['metrics']
+if 'data_files' in metrics:
+    files_metrics = metrics['data_files']
+    print(f"  Files - Success: {files_metrics.get('success', 0)}")
+    print(f"  Files - Failed: {files_metrics.get('failed', 0)}")
+
+if 'data_units' in metrics:
+    units_metrics = metrics['data_units']
+    print(f"  Units - Success: {units_metrics.get('success', 0)}")
+    print(f"  Units - Failed: {units_metrics.get('failed', 0)}")
+```
 
-### 일반적인 예외
+### 오류 처리 및 롤백
 
 ```python
-from synapse_sdk.plugins.categories.upload.actions import upload
+# 자동 롤백을 포함한 향상된 오류 처리 시연
+params = {
+    "name": "Error Recovery Example",
+    "path": "/data/problematic_files",
+    "storage": 1,
+    "data_collection": 5,
+    "is_recursive": True
+}
+
+action = UploadAction(
+    params=params,
+    plugin_config=plugin_config
+)
 
 try:
-    params = upload.UploadParams(
-        source_path="/invalid/path",
-        storage_id="storage123",
-        collection_id="collection456",
-        project_id="project789"
-    )
-
-    action = upload.UploadAction(params=params)
-    result = action.run()
-
-except upload.UploadValidationError as e:
-    print(f"검증 오류: {e}")
-except upload.UploadExecutionError as e:
-    print(f"실행 오류: {e}")
-except upload.UploadSecurityError as e:
-    print(f"보안 오류: {e}")
-except upload.ExcelParsingError as e:
-    print(f"Excel 파싱 오류: {e}")
+    result = action.start()
+
+    if not result['success']:
+        print("Upload failed, but cleanup was automatic:")
+        print(f"Errors encountered: {len(result['errors'])}")
+        for i, error in enumerate(result['errors'], 1):
+            print(f"  {i}. {error}")
+
+        # 롤백이 수행되었는지 확인 (오케스트레이터 내부를 통해)
+        workflow_metrics = result['metrics'].get('workflow', {})
+        current_step = workflow_metrics.get('current_step', 0)
+        total_steps = workflow_metrics.get('total_steps', 0)
+        print(f"Workflow stopped at step {current_step} of {total_steps}")
+
+except Exception as e:
+    print(f"Critical upload failure: {e}")
+    # 예외 전파 전에 롤백이 자동으로 수행됨
 ```
 
+## 오류 처리
+
 ### 예외 타입
 
-#### ExcelSecurityError
+업로드 시스템은 특정 예외를 정의합니다:
 
-Excel 파일이 보안 제약 조건을 위반할 때 발생합니다.
+```python
+# 보안 위반
+try:
+    action.start()
+except ExcelSecurityError as e:
+    print(f"Excel security violation: {e}")
 
-**일반적인 원인:**
+# 파싱 오류
+except ExcelParsingError as e:
+    print(f"Excel parsing failed: {e}")
 
-- 파일 크기가 제한을 초과
-- 메모리 사용량 추정치가 너무 높음
-- 콘텐츠 보안 위반
+# 일반 업로드 오류
+except ActionError as e:
+    print(f"Upload action failed: {e}")
+```
 
-#### ExcelParsingError
+### 검증 오류
 
-Excel 파일을 파싱할 수 없을 때 발생합니다.
+매개변수 검증은 자세한 오류 메시지를 제공합니다:
 
-**일반적인 원인:**
+```python
+from pydantic import ValidationError
 
-- 파일 형식 손상
-- 잘못된 Excel 구조
-- 필수 열 누락
-- 콘텐츠 파싱 실패
+try:
+    params = UploadParams(**invalid_params)
+except ValidationError as e:
+    for error in e.errors():
+        print(f"Field {error['loc']}: {error['msg']}")
+```
 
-### 부분 실패 처리
+## API 레퍼런스
 
-```python
-result = action.run()
+### 핵심 컴포넌트
+
+#### UploadAction
+
+파일 처리 작업을 위한 전략 및 파사드 패턴을 구현하는 메인 업로드 액션 클래스입니다.
+
+**클래스 속성:**
+
+- `name = 'upload'` - 액션 식별자
+- `category = PluginCategory.UPLOAD` - 플러그인 카테고리
+- `method = RunMethod.JOB` - 실행 방법
+- `run_class = UploadRun` - 전문 실행 관리
+- `params_model = UploadParams` - 매개변수 검증 모델
+- `strategy_factory: StrategyFactory` - 전략 구현 생성
+- `step_registry: StepRegistry` - 워크플로우 단계 관리
+
+**주요 메서드:**
 
-if result.status == upload.UploadStatus.FAILED:
-    print(f"실패한 파일: {result.failed_files}")
-    print(f"성공한 파일: {result.successful_files}")
+- `start() -> Dict[str, Any]` - 오케스트레이션된 업로드 워크플로우 실행
+- `get_workflow_summary() -> Dict[str, Any]` - 구성된 워크플로우 요약 가져오기
+- `_configure_workflow() -> None` - 실행 순서로 워크플로우 단계 등록
+- `_configure_strategies(context=None) -> Dict[str, Any]` - 전략 인스턴스 생성
 
-    # 실패한 파일만 재시도
-    retry_params = upload.UploadParams(
-        source_path=result.failed_files,
-        storage_id=params.storage_id,
-        collection_id=params.collection_id,
-        project_id=params.project_id
-    )
+**진행률 카테고리:**
+
+```python
+progress_categories = {
+    'analyze_collection': {'proportion': 2},
+    'upload_data_files': {'proportion': 38},
+    'generate_data_units': {'proportion': 60},
+}
 ```
 
-## 성능 고려사항
+#### UploadOrchestrator
+
+자동 롤백을 포함한 완전한 업로드 워크플로우를 조정하는 파사드 컴포넌트입니다.
+
+**클래스 속성:**
+
+- `context: UploadContext` - 워크플로우 전반의 공유 상태
+- `step_registry: StepRegistry` - 워크플로우 단계 레지스트리
+- `strategies: Dict[str, Any]` - 전략 구현
+- `executed_steps: List[BaseStep]` - 성공적으로 실행된 단계
+- `current_step_index: int` - 워크플로우의 현재 위치
+- `rollback_executed: bool` - 롤백이 수행되었는지 여부
+
+**주요 메서드:**
+
+- `execute() -> Dict[str, Any]` - 오류 처리를 포함한 완전한 워크플로우 실행
+- `get_workflow_summary() -> Dict[str, Any]` - 실행 요약 및 메트릭 가져오기
+- `get_executed_steps() -> List[BaseStep]` - 성공적으로 실행된 단계 목록 가져오기
+- `is_rollback_executed() -> bool` - 롤백이 수행되었는지 확인
+- `_execute_step(step: BaseStep) -> StepResult` - 개별 워크플로우 단계 실행
+- `_handle_step_failure(step: BaseStep, error: Exception) -> None` - 단계 실패 처리
+- `_rollback_executed_steps() -> None` - 실행된 단계를 역순으로 롤백
+
+#### UploadContext
+
+워크플로우 컴포넌트 간의 공유 상태 및 통신을 유지하는 컨텍스트 객체입니다.
+
+**상태 속성:**
+
+- `params: Dict` - 업로드 매개변수
+- `run: UploadRun` - 실행 관리 인스턴스
+- `client: Any` - 외부 작업을 위한 API 클라이언트
+- `storage: Any` - 스토리지 구성 객체
+- `pathlib_cwd: Path` - 현재 작업 디렉토리 경로
+- `metadata: Dict[str, Dict[str, Any]]` - 파일 메타데이터 매핑
+- `file_specifications: Dict[str, Any]` - 데이터 컬렉션 파일 사양
+- `organized_files: List[Dict[str, Any]]` - 구성된 파일 정보
+- `uploaded_files: List[Dict[str, Any]]` - 성공적으로 업로드된 파일
+- `data_units: List[Dict[str, Any]]` - 생성된 데이터 단위
+
+**진행률 및 메트릭:**
+
+- `metrics: Dict[str, Any]` - 워크플로우 메트릭 및 통계
+- `errors: List[str]` - 축적된 오류 메시지
+- `step_results: List[StepResult]` - 실행된 단계의 결과
+
+**전략 및 롤백:**
+
+- `strategies: Dict[str, Any]` - 주입된 전략 구현
+- `rollback_data: Dict[str, Any]` - 롤백 작업을 위한 데이터
+
+**주요 메서드:**
+
+- `update(result: StepResult) -> None` - 단계 결과로 컨텍스트 업데이트
+- `get_result() -> Dict[str, Any]` - 최종 결과 딕셔너리 생성
+- `has_errors() -> bool` - 축적된 오류 확인
+- `get_last_step_result() -> Optional[StepResult]` - 가장 최근 단계 결과 가져오기
+- `update_metrics(category: str, metrics: Dict[str, Any]) -> None` - 메트릭 업데이트
+- `add_error(error: str) -> None` - 컨텍스트에 오류 추가
+- `get_param(key: str, default: Any = None) -> Any` - 기본값이 있는 매개변수 가져오기
 
-### 메모리 사용량
+#### StepRegistry
 
-- 대용량 Excel 파일의 경우 더 작은 `batch_size` 사용
-- 메모리 집약적인 작업을 위해 `max_workers` 제한
-- 스트리밍 처리를 위해 청크 업로드 사용
+워크플로우 단계의 컬렉션 및 실행 순서를 관리하는 레지스트리입니다.
 
-### 네트워크 최적화
+**속성:**
 
-- 네트워크 지연 시간이 높은 환경에서 배치 크기 증가
-- 신뢰할 수 없는 연결에 대해 재시도 메커니즘 구현
-- 대용량 파일에 대해 체크섬 검증 사용
+- `_steps: List[BaseStep]` - 실행 순서로 등록된 워크플로우 단계
 
-### 병렬 처리
+**주요 메서드:**
+
+- `register(step: BaseStep) -> None` - 워크플로우 단계 등록
+- `get_steps() -> List[BaseStep]` - 순서대로 모든 등록된 단계 가져오기
+- `get_total_progress_weight() -> float` - 총 진행률 가중치 계산
+- `clear() -> None` - 모든 등록된 단계 지우기
+- `__len__() -> int` - 등록된 단계 수 가져오기
+
+#### StrategyFactory
+
+매개변수를 기반으로 적절한 전략 구현을 생성하는 팩토리 컴포넌트입니다.
+
+**주요 메서드:**
+
+- `create_validation_strategy(params: Dict, context=None) -> BaseValidationStrategy` - 검증 전략 생성
+- `create_file_discovery_strategy(params: Dict, context=None) -> BaseFileDiscoveryStrategy` - 파일 발견 전략 생성
+- `create_metadata_strategy(params: Dict, context=None) -> BaseMetadataStrategy` - 메타데이터 처리 전략 생성
+- `create_upload_strategy(params: Dict, context: UploadContext) -> BaseUploadStrategy` - 업로드 전략 생성 (컨텍스트 필요)
+- `create_data_unit_strategy(params: Dict, context: UploadContext) -> BaseDataUnitStrategy` - 데이터 단위 전략 생성 (컨텍스트 필요)
+- `get_available_strategies() -> Dict[str, List[str]]` - 사용 가능한 전략 타입 및 구현 가져오기
+
+### 워크플로우 단계
+
+#### BaseStep (추상)
+
+공통 인터페이스 및 유틸리티를 제공하는 모든 워크플로우 단계의 기본 클래스입니다.
+
+**추상 속성:**
+
+- `name: str` - 고유한 단계 식별자
+- `progress_weight: float` - 진행률 계산을 위한 가중치 (합은 1.0이어야 함)
+
+**추상 메서드:**
+
+- `execute(context: UploadContext) -> StepResult` - 단계 로직 실행
+- `can_skip(context: UploadContext) -> bool` - 단계를 건너뛸 수 있는지 결정
+- `rollback(context: UploadContext) -> None` - 단계 작업 롤백
+
+**유틸리티 메서드:**
+
+- `create_success_result(data: Dict = None) -> StepResult` - 성공 결과 생성
+- `create_error_result(error: str, original_exception: Exception = None) -> StepResult` - 오류 결과 생성
+- `create_skip_result() -> StepResult` - 건너뛰기 결과 생성
+
+#### StepResult
+
+워크플로우 단계 실행에서 반환되는 결과 객체입니다.
+
+**속성:**
+
+- `success: bool` - 단계가 성공적으로 실행되었는지 여부
+- `data: Dict[str, Any]` - 단계 결과 데이터
+- `error: str` - 단계가 실패한 경우 오류 메시지
+- `rollback_data: Dict[str, Any]` - 롤백에 필요한 데이터
+- `skipped: bool` - 단계가 건너뛰어졌는지 여부
+- `original_exception: Optional[Exception]` - 디버깅을 위한 원본 예외
+- `timestamp: datetime` - 실행 타임스탬프
+
+**사용법:**
 
 ```python
-# Ray를 사용한 분산 처리
-params = upload.UploadParams(
-    source_path="/path/to/massive/dataset",
-    storage_id="storage123",
-    collection_id="collection456",
-    project_id="project789",
-    execution_method="ray",  # Ray 클러스터 사용
-    max_workers=10
-)
+# 불린 평가
+if step_result:
+    # 단계가 성공함
+    process_success(step_result.data)
 ```
 
-## 로깅 및 모니터링
+#### 구체적인 단계
 
-### 로그 코드 사용
+**InitializeStep** (`name: "initialize"`, `weight: 0.05`)
 
-업로드 플러그인은 모든 작업에 대해 구조화된 로깅을 제공합니다:
+- 스토리지 연결 및 pathlib 작업 디렉토리 설정
+- 기본 업로드 전제조건 검증
 
-```python
-from synapse_sdk.plugins.categories.upload.actions import upload
+**ProcessMetadataStep** (`name: "process_metadata"`, `weight: 0.05`)
 
-# 사용자 정의 로깅 핸들러
-def custom_log_handler(log_code: upload.LogCode, message: str, level: str):
-    print(f"[{log_code.value}] {level}: {message}")
+- 제공된 Excel 메타데이터 처리
+- 메타데이터 보안 및 형식 검증
 
-# 로그 핸들러와 함께 액션 실행
-action = upload.UploadAction(params=params)
-action.run.add_log_handler(custom_log_handler)
-result = action.run()
-```
+**AnalyzeCollectionStep** (`name: "analyze_collection"`, `weight: 0.05`)
 
-### 메트릭 수집
+- 데이터 컬렉션 파일 사양 검색 및 검증
+- 파일 구성 규칙 설정
 
-```python
-# 업로드 메트릭 수집
-result = action.run()
+**OrganizeFilesStep** (`name: "organize_files"`, `weight: 0.10`)
 
-metrics = {
-    "total_files": result.total_files,
-    "successful_files": len(result.successful_files),
-    "failed_files": len(result.failed_files),
-    "total_size": result.total_size_bytes,
-    "duration": result.duration_seconds,
-    "throughput": result.total_size_bytes / result.duration_seconds
-}
+- 파일 발견 전략을 사용한 파일 발견
+- 타입 및 사양별 파일 구성
 
-print(f"업로드 메트릭: {metrics}")
-```
+**ValidateFilesStep** (`name: "validate_files"`, `weight: 0.05`)
 
-## 테스팅
+- 검증 전략을 사용한 파일 검증
+- 보안 및 내용 검사 수행
 
-업로드 플러그인에는 포괄적인 테스트 스위트가 포함되어 있습니다:
+**UploadFilesStep** (`name: "upload_files"`, `weight: 0.30`)
 
-### 단위 테스트 실행
+- 업로드 전략을 사용한 파일 업로드
+- 배치 및 진행률 추적 처리
 
-```bash
-# 모든 업로드 테스트 실행
-python -m pytest tests/plugins/upload/ -v
+**GenerateDataUnitsStep** (`name: "generate_data_units"`, `weight: 0.35`)
 
-# 특정 테스트 파일 실행
-python -m pytest tests/plugins/upload/test_action.py -v
+- 데이터 단위 전략을 사용한 데이터 단위 생성
+- 업로드된 파일을 데이터 단위에 연결
 
-# 커버리지와 함께 테스트 실행
-python -m pytest tests/plugins/upload/ --cov=synapse_sdk.plugins.categories.upload
-```
+**CleanupStep** (`name: "cleanup"`, `weight: 0.05`)
 
-### 테스트 케이스 예제
+- 임시 리소스 및 파일 정리
+- 최종 검증 수행
 
-```python
-import pytest
-from synapse_sdk.plugins.categories.upload.actions import upload
+### 전략 기본 클래스
 
-def test_upload_params_validation():
-    """업로드 매개변수 검증을 테스트합니다."""
-    # 유효한 매개변수
-    params = upload.UploadParams(
-        source_path="/valid/path",
-        storage_id="storage123",
-        collection_id="collection456",
-        project_id="project789"
-    )
-    assert params.source_path == "/valid/path"
+#### BaseValidationStrategy (추상)
 
-    # 무효한 매개변수
-    with pytest.raises(ValidationError):
-        upload.UploadParams(
-            source_path="",  # 빈 경로
-            storage_id="storage123",
-            collection_id="collection456",
-            project_id="project789"
-        )
-```
+파일 검증 전략의 기본 클래스입니다.
 
-## 문제 해결
+**추상 메서드:**
 
-### 일반적인 문제
+- `validate_files(files: List[Path], context: UploadContext) -> bool` - 파일 컬렉션 검증
+- `validate_security(file_path: Path) -> bool` - 개별 파일 보안 검증
 
-#### 1. 권한 오류
+#### BaseFileDiscoveryStrategy (추상)
 
-```
-UploadSecurityError: Access denied to source path
-```
+파일 발견 및 구성 전략의 기본 클래스입니다.
 
-**해결책**: 소스 디렉터리와 대상 스토리지에 대한 적절한 권한이 있는지 확인하세요.
+**추상 메서드:**
 
-#### 2. Excel 파일 처리 실패
+- `discover_files(path: Path, context: UploadContext) -> List[Path]` - 경로에서 파일 발견
+- `organize_files(files: List[Path], specs: Dict[str, Any], context: UploadContext) -> List[Dict[str, Any]]` - 발견된 파일 구성
 
-```
-UploadExecutionError: Failed to process Excel file - corrupted or protected
-```
+#### BaseMetadataStrategy (추상)
 
-**해결책**:
+메타데이터 처리 전략의 기본 클래스입니다.
 
-- Excel 파일이 손상되지 않았는지 확인
-- 암호로 보호된 파일에 대한 올바른 자격 증명 제공
-- Excel 보안 구성 검토
+**추상 메서드:**
 
-#### 3. 메모리 부족 오류
+- `process_metadata(context: UploadContext) -> Dict[str, Any]` - 컨텍스트에서 메타데이터 처리
+- `extract_metadata(file_path: Path) -> Dict[str, Any]` - 파일에서 메타데이터 추출
 
-```
-MemoryError: Unable to allocate array
-```
+#### BaseUploadStrategy (추상)
 
-**해결책**:
+파일 업로드 전략의 기본 클래스입니다.
 
-- 배치 크기 줄이기 (`batch_size` 매개변수)
-- 최대 작업자 수 제한 (`max_workers` 매개변수)
-- 대용량 파일에 대해 스트리밍 업로드 사용
+**추상 메서드:**
 
-### 디버그 모드
+- `upload_files(files: List[Dict[str, Any]], context: UploadContext) -> List[Dict[str, Any]]` - 파일 컬렉션 업로드
+- `upload_batch(batch: List[Dict[str, Any]], context: UploadContext) -> List[Dict[str, Any]]` - 파일 배치 업로드
 
-```python
-import logging
+#### BaseDataUnitStrategy (추상)
 
-# 디버그 로깅 활성화
-logging.basicConfig(level=logging.DEBUG)
+데이터 단위 생성 전략의 기본 클래스입니다.
 
-# 상세한 로깅과 함께 업로드 실행
-params = upload.UploadParams(
-    source_path="/path/to/files",
-    storage_id="storage123",
-    collection_id="collection456",
-    project_id="project789",
-    debug_mode=True  # 상세한 로깅 활성화
-)
+**추상 메서드:**
 
-result = action.run()
-```
+- `generate_data_units(files: List[Dict[str, Any]], context: UploadContext) -> List[Dict[str, Any]]` - 데이터 단위 생성
+- `create_data_unit_batch(batch: List[Dict[str, Any]], context: UploadContext) -> List[Dict[str, Any]]` - 데이터 단위 배치 생성
 
-## 기여하기
+### 레거시 컴포넌트
 
-업로드 플러그인 개발에 기여하려면:
+#### UploadRun
 
-1. 개발 환경 설정:
+업로드 작업을 위한 전문 실행 관리 (레거시에서 변경 없음).
 
-   ```bash
-   git clone <repository-url>
-   cd synapse-sdk
-   pip install -e ".[dev]"
-   ```
+**로깅 메서드:**
 
-2. 테스트 실행:
+- `log_message_with_code(code, *args, level=None)` - 타입 안전 로깅
+- `log_upload_event(code, *args, level=None)` - 업로드 특정 이벤트
 
-   ```bash
-   python -m pytest tests/plugins/upload/ -v
-   ```
+**중첩 모델:**
 
-3. 코드 스타일 확인:
+- `UploadEventLog` - 업로드 이벤트 로깅
+- `DataFileLog` - 데이터 파일 처리 로그
+- `DataUnitLog` - 데이터 단위 생성 로그
+- `TaskLog` - 작업 실행 로그
+- `MetricsRecord` - 메트릭 추적
 
-   ```bash
-   black synapse_sdk/plugins/categories/upload/
-   flake8 synapse_sdk/plugins/categories/upload/
-   ```
+#### UploadParams
+
+Pydantic 통합을 포함한 매개변수 검증 모델 (레거시에서 변경 없음).
+
+**필수 매개변수:**
+
+- `name: str` - 업로드 이름
+- `path: str` - 소스 경로
+- `storage: int` - 스토리지 ID
+- `data_collection: int` - 데이터 컬렉션 ID
+
+**선택적 매개변수:**
+
+- `description: str | None = None` - 업로드 설명
+- `project: int | None = None` - 프로젝트 ID
+- `excel_metadata_path: str | None = None` - Excel 메타데이터 파일 경로
+- `is_recursive: bool = False` - 재귀적 파일 발견
+- `max_file_size_mb: int = 50` - 최대 파일 크기
+- `creating_data_unit_batch_size: int = 100` - 데이터 단위 배치 크기
+- `use_async_upload: bool = True` - 비동기 업로드 처리
+
+**검증 기능:**
 
-4. 새로운 기능 또는 버그 수정을 위한 풀 리퀘스트 생성
+- storage/data_collection/project에 대한 실시간 API 검증
+- 문자열 정화 및 길이 검증
+- 타입 검사 및 변환
+- 사용자 정의 검증자 메서드
 
-### 개발 지침
+### 유틸리티 클래스
+
+#### ExcelSecurityConfig
+
+Excel 파일 처리를 위한 보안 구성입니다.
+
+**구성 속성:**
+
+- 파일 크기 및 메모리 제한
+- 행 및 열 개수 제한
+- 문자열 길이 제한
+- 환경 변수 오버라이드
+
+#### ExcelMetadataUtils
+
+Excel 메타데이터 처리를 위한 유틸리티 메서드입니다.
+
+**주요 메서드:**
+
+- `validate_and_truncate_string()` - 문자열 정화
+- `is_valid_filename_length()` - 파일명 검증
+
+#### PathAwareJSONEncoder
+
+Path 및 datetime 객체를 위한 사용자 정의 JSON 인코더입니다.
+
+**지원되는 타입:**
+
+- Path 객체 (문자열로 변환)
+- Datetime 객체 (ISO 형식)
+- 표준 JSON 직렬화 가능한 타입
+
+### 열거형
+
+#### LogCode
+
+업로드 작업을 위한 타입 안전 로깅 코드입니다.
+
+**카테고리:**
 
-- 모든 새로운 기능에 대해 테스트 작성
-- 공개 API에 대한 docstring 업데이트
-- 타입 힌트 사용으로 코드 안전성 보장
-- 기존 로깅 패턴 및 LogCode 열거형 따르기
+- 검증 코드 (VALIDATION_FAILED, STORAGE_VALIDATION_FAILED)
+- 파일 처리 코드 (NO_FILES_FOUND, FILES_DISCOVERED)
+- Excel 처리 코드 (EXCEL_SECURITY_VIOLATION, EXCEL_PARSING_ERROR)
+- 진행률 코드 (UPLOADING_DATA_FILES, GENERATING_DATA_UNITS)
+
+#### UploadStatus
+
+업로드 처리 상태 열거형입니다.
+
+**값:**
+
+- `SUCCESS = 'success'` - 작업이 성공적으로 완료됨
+- `FAILED = 'failed'` - 작업이 오류로 실패함
+
+### 예외
+
+#### ExcelSecurityError
+
+Excel 파일이 보안 제약을 위반할 때 발생합니다.
+
+**일반적인 원인:**
+
+- 파일 크기가 제한을 초과함
+- 메모리 사용량 추정이 너무 높음
+- 내용 보안 위반
+
+#### ExcelParsingError
+
+Excel 파일을 파싱할 수 없을 때 발생합니다.
+
+**일반적인 원인:**
+
+- 파일 형식 손상
+- 유효하지 않은 Excel 구조
+- 필요한 열 누락
+- 내용 파싱 실패
 
 ## 모범 사례
 
+### 아키텍처 패턴
+
+1. **전략 선택**: 사용 사례 요구사항에 따라 적절한 전략을 선택하세요
+
+   - 깊은 디렉토리 구조에는 `RecursiveFileDiscoveryStrategy` 사용
+   - 표준 파일 검증에는 `BasicValidationStrategy` 사용
+   - 큰 파일 세트에는 `AsyncUploadStrategy` 사용
+
+2. **단계 순서**: 논리적 단계 종속성을 유지하세요
+
+   - Initialize → Process Metadata → Analyze Collection → Organize Files → Validate → Upload → Generate Data Units → Cleanup
+   - 사용자 정의 단계는 워크플로우의 적절한 지점에 삽입해야 함
+
+3. **컨텍스트 관리**: 상태 공유를 위해 UploadContext를 활용하세요
+   - 다운스트림 단계를 위해 컨텍스트에 중간 결과 저장
+   - 단계 간 통신에 컨텍스트 사용
+   - 정리 작업을 위해 롤백 데이터 보존
+
 ### 성능 최적화
 
-1. **배치 처리**: 대용량 업로드를 위해 적절한 배치 크기 사용
-2. **비동기 작업**: 더 나은 처리량을 위해 비동기 처리 활성화
-3. **메모리 관리**: Excel 보안 제한을 적절히 구성
-4. **진행률 모니터링**: 사용자 피드백을 위한 진행률 카테고리 추적
+1. **배치 처리**: 시스템 리소스를 기반으로 최적의 배치 크기를 구성하세요
+
+   ```python
+   params = {
+       "creating_data_unit_batch_size": 200,  # 메모리에 따라 조정
+       "upload_batch_size": 10,               # 업로드 전략을 위한 사용자 정의 매개변수
+   }
+   ```
+
+2. **비동기 작업**: I/O 바인딩 작업에 비동기 처리를 활성화하세요
+
+   ```python
+   params = {
+       "use_async_upload": True,  # 네트워크 작업의 더 나은 처리량
+   }
+   ```
+
+3. **메모리 관리**: 사용자 정의 전략에서 메모리 사용량을 모니터링하세요
+
+   - 모든 파일을 메모리에 로드하지 말고 청크 단위로 처리
+   - 큰 파일 컬렉션에 제너레이터 사용
+   - Excel 보안 제한을 적절히 구성
+
+4. **진행률 모니터링**: 자세한 진행률 추적을 구현하세요
+   ```python
+   # 진행률 업데이트가 포함된 사용자 정의 단계
+   def execute(self, context):
+       total_files = len(context.organized_files)
+       for i, file_info in enumerate(context.organized_files):
+           # 파일 처리
+           progress = (i + 1) / total_files * 100
+           context.update_metrics('custom_step', {'progress': progress})
+   ```
 
 ### 보안 고려사항
 
-1. **파일 검증**: 항상 파일 크기와 유형 검증
-2. **Excel 보안**: 적절한 보안 제한 구성
-3. **경로 삭제**: 파일 경로 검증 및 삭제
-4. **콘텐츠 필터링**: 콘텐츠 기반 보안 검사 구현
+1. **입력 검증**: 모든 입력 매개변수 및 파일 경로를 검증하세요
 
-### 오류 처리
+   ```python
+   # 전략에서 사용자 정의 검증
+   def validate_files(self, files, context):
+       for file_path in files:
+           if not self._is_safe_path(file_path):
+               return False
+       return True
+   ```
+
+2. **파일 내용 보안**: 내용 기반 보안 검사를 구현하세요
+
+   - 악성 파일 서명 스캔
+   - 파일 헤더가 확장자와 일치하는지 검증
+   - 임베디드 실행 파일 검사
+
+3. **Excel 보안**: 적절한 보안 제한을 구성하세요
+
+   ```python
+   import os
+   os.environ['EXCEL_MAX_FILE_SIZE_MB'] = '10'
+   os.environ['EXCEL_MAX_MEMORY_MB'] = '30'
+   ```
+
+4. **경로 정화**: 모든 파일 경로를 검증하고 정화하세요
+   - 경로 순회 공격 방지
+   - 파일 확장자 검증
+   - 파일 권한 확인
+
+### 오류 처리 및 복구
+
+1. **우아한 저하**: 부분 실패 시나리오를 위해 설계하세요
+
+   ```python
+   class RobustUploadStrategy(BaseUploadStrategy):
+       def upload_files(self, files, context):
+           successful_uploads = []
+           failed_uploads = []
+
+           for file_info in files:
+               try:
+                   result = self._upload_file(file_info)
+                   successful_uploads.append(result)
+               except Exception as e:
+                   failed_uploads.append({'file': file_info, 'error': str(e)})
+                   # 완전히 실패하지 말고 다른 파일로 계속 진행
+
+           # 부분 결과로 컨텍스트 업데이트
+           context.add_uploaded_files(successful_uploads)
+           if failed_uploads:
+               context.add_error(f"Failed to upload {len(failed_uploads)} files")
+
+           return successful_uploads
+   ```
+
+2. **롤백 설계**: 포괄적인 롤백 전략을 구현하세요
+
+   ```python
+   def rollback(self, context):
+       # 작업의 역순으로 정리
+       if hasattr(self, '_created_temp_files'):
+           for temp_file in self._created_temp_files:
+               try:
+                   temp_file.unlink()
+               except Exception:
+                   pass  # 정리 문제로 인한 롤백 실패 방지
+   ```
+
+3. **자세한 로깅**: 디버깅을 위한 구조화된 로깅을 사용하세요
+
+   ```python
+   def execute(self, context):
+       try:
+           context.run.log_message_with_code(
+               'CUSTOM_STEP_STARTED',
+               {'step': self.name, 'file_count': len(context.organized_files)}
+           )
+           # 여기에 단계 로직
+       except Exception as e:
+           context.run.log_message_with_code(
+               'CUSTOM_STEP_FAILED',
+               {'step': self.name, 'error': str(e)},
+               level=Context.DANGER
+           )
+           raise
+   ```
+
+### 개발 가이드라인
+
+1. **사용자 정의 전략 개발**: 확립된 패턴을 따르세요
+
+   ```python
+   # 항상 적절한 기본 클래스를 확장
+   class MyCustomStrategy(BaseValidationStrategy):
+       def __init__(self, config=None):
+           self.config = config or {}
+
+       def validate_files(self, files, context):
+           # 검증 로직 구현
+           return True
+
+       def validate_security(self, file_path):
+           # 보안 검증 구현
+           return True
+   ```
+
+2. **테스트 전략**: 포괄적인 테스트 커버리지
+
+   ```python
+   # 성공 및 실패 시나리오 모두 테스트
+   class TestCustomStrategy:
+       def test_success_case(self):
+           strategy = MyCustomStrategy()
+           result = strategy.validate_files([Path('valid_file.txt')], mock_context)
+           assert result is True
+
+       def test_security_failure(self):
+           strategy = MyCustomStrategy()
+           result = strategy.validate_security(Path('malware.exe'))
+           assert result is False
+
+       def test_rollback_cleanup(self):
+           step = MyCustomStep()
+           step.rollback(mock_context)
+           # 정리가 수행되었는지 확인
+   ```
+
+3. **확장 지점**: 확장성을 위해 팩토리 패턴 사용
+
+   ```python
+   class CustomStrategyFactory(StrategyFactory):
+       def create_validation_strategy(self, params, context=None):
+           validation_type = params.get('validation_type', 'basic')
+
+           strategy_map = {
+               'basic': BasicValidationStrategy,
+               'strict': StrictValidationStrategy,
+               'custom': MyCustomValidationStrategy,
+           }
+
+           strategy_class = strategy_map.get(validation_type, BasicValidationStrategy)
+           return strategy_class(params)
+   ```
+
+4. **구성 관리**: 환경 변수 및 매개변수 사용
+
+   ```python
+   class ConfigurableStep(BaseStep):
+       def __init__(self):
+           # 런타임 구성 허용
+           self.batch_size = int(os.getenv('STEP_BATCH_SIZE', '50'))
+           self.timeout = int(os.getenv('STEP_TIMEOUT_SECONDS', '300'))
+
+       def execute(self, context):
+           # 구성된 값 사용
+           batch_size = context.get_param('step_batch_size', self.batch_size)
+           timeout = context.get_param('step_timeout', self.timeout)
+   ```
+
+### 피해야 할 안티패턴
+
+1. **강한 결합**: 전략을 특정 구현에 결합하지 마세요
+2. **상태 변형**: update() 메서드 외부에서 컨텍스트 상태를 직접 수정하지 마세요
+3. **예외 삼킴**: 적절한 처리 없이 예외를 잡아서 무시하지 마세요
+4. **블로킹 작업**: 진행률 업데이트 없이 장시간 실행되는 동기 작업을 수행하지 마세요
+5. **메모리 누수**: 단계 인스턴스에서 큰 객체에 대한 참조를 보유하지 마세요
+
+### 문제 해결 가이드
 
-1. **우아한 저하**: 부분 업로드 실패 처리
-2. **상세한 로깅**: 일관된 로깅을 위해 LogCode 열거형 사용
-3. **사용자 피드백**: 명확한 오류 메시지 제공
-4. **복구 옵션**: 적절한 재시도 메커니즘 구현
+1. **단계 실패**: 단계 실행 순서 및 종속성 확인
+2. **전략 문제**: 전략 팩토리 구성 및 매개변수 전달 확인
+3. **컨텍스트 문제**: 적절한 컨텍스트 업데이트 및 상태 관리 확인
+4. **롤백 실패**: 멱등적 롤백 작업 설계
+5. **성능 문제**: 배치 크기 및 비동기 작업 사용량 프로파일링
 
-### 개발 지침
+### 마이그레이션 체크리스트
 
-1. **모듈 구조**: 확립된 모듈 패턴 따르기
-2. **타입 안전성**: Pydantic 모델 및 열거형 로깅 사용
-3. **테스팅**: 포괄적인 단위 테스트 커버리지
-4. **문서화**: 사용자 정의 검증자와 메서드 문서화
+레거시 구현에서 업그레이드할 때:
 
-## 라이센스
+- [ ] 매개변수 이름을 `collection`에서 `data_collection`으로 업데이트
+- [ ] 호환성을 위한 기존 워크플로우 테스트
+- [ ] 새 아키텍처 기회에 대한 사용자 정의 확장 검토
+- [ ] 새 롤백 기능을 활용하도록 오류 처리 업데이트
+- [ ] 특수 요구사항에 대한 사용자 정의 전략 구현 고려
+- [ ] 새 워크플로우 단계를 검증하도록 테스트 케이스 업데이트
+- [ ] 향상된 정보에 대한 로깅 및 메트릭 수집 검토
 
-이 플러그인은 Synapse SDK와 동일한 라이센스 하에 배포됩니다.
+BaseUploader 템플릿을 사용한 커스텀 업로드 플러그인 개발에 대한 자세한 정보는 [업로드 템플릿 개발하기](./developing-upload-template.md) 가이드를 참조하세요.