---
type: page-backend
status: stable
page_id: B03_FileInput
related_pages: ["[[B03_FileInput/B03_frontend]]", "[[B03_FileInput/B03_api]]", "[[B03_FileInput/B03_db]]", "[[B03_FileInput/B03_dependencies]]", "[[las_free_sheet_surface]]", "[[architecture/project_map]]", "[[architecture/workflow_data_flow]]"]
last_updated: 2026-08-30
source: ["docs/raw/verification/2026-08-08_verify_server_and_e2e_fixes.md", "docs/raw/verification/2026-08-29_verify_B03_reupload_reanalysis_cache.md"]
---

# B03_FileInput — Backend

`las_free=true`이면 LAS 필수검사를 면제하고 stage 0 params에 저장해 [[las_free_sheet_surface|도엽등고선 서피스 체인]]으로 분기한다. 청크 세션을 포함한 LAS 업로드는 세션·API·화면에서 차단한다.

## 입력 검증·파일 처리
| 항목 | 위치 | 역할 |
|---|---|---|
| `FileUploadDescriptor` | `B03_FileInput_Schema.py` | 경로 이탈·확장자·크기 검증 및 계획노선 CSV 헤더(`route_name`, `sequence`, `x`, `y`, `z`, `crs_epsg`), 순번, 수치, 단일 EPSG 일치성 검증 |
| `resolve_upload_destination()` | `B03_FileInput_Engine.py` | 프로젝트 WF0 저장 목적지 결정 |
| `save_upload_stream()` | `B03_FileInput_Engine.py` | 일반 업로드 스트림 저장 및 계획노선 CSV 원본 보존 |
| `resolve_chunk_session_dir()` | `B03_FileInput_Engine.py` | 임시 청크 디렉터리 결정 |
| `save_upload_chunk()` / `merge_upload_chunks()` | `B03_FileInput_Engine.py` | 청크 저장·순서 병합 |
| `remove_chunk_session()` | `B03_FileInput_Engine.py` | 청크 임시 디렉터리 정리 |
| `finalize_project_upload()` | `B03_FileInput_Router.py` | finalize 시 `upload_session` 변수 분리로 404 방지 및 WF1 자동 실행 복구 |
| `_complete_file_input_if_ready()` | `B03_FileInput_Router.py:153` | 동일 파일 전송 생략을 포함한 완료 요청에서 하위 산출물·초기설계 상태를 초기화하고 WF1 예약 |

## 메타데이터 분석 및 파일 지문
| 항목 | 위치 | 역할 |
|---|---|---|
| `normalize_crs_metadata()` | `B03_FileInput_Engine_Analyze.py` | 복합 CRS 수평/수직 분리 및 규격화 (사설 수직 CRS 보존 포함) |
| `analyze_las_metadata()` | `B03_FileInput_Engine_Analyze.py` | LAS 포인트 수·범위·밀도 분석 |
| `analyze_prj_metadata()` | `B03_FileInput_Engine_Analyze.py` | PRJ CRS 분석 |
| `analyze_tfw_metadata()` | `B03_FileInput_Engine_Analyze.py` | TFW 변환계수 분석 |
| `analyze_tif_metadata()` | `B03_FileInput_Engine_Analyze.py` | TIF 래스터·CRS·범위 분석 |
| `analyze_input_metadata()` | `B03_FileInput_Engine_Analyze.py` | 확장자별 분석 라우팅 |
| `B03_FileInput_Fingerprint.ts` | `B03_FileInput_Fingerprint.ts` | SHA-256 파일 지문 기반 중복 전송 스킵 및 다른 파일 변경 시 SUPERSEDED 처리 |

## 임시 보관함 (R2 Temp Upload)
| 항목 | 위치 | 역할 |
|---|---|---|
| `B03_FileInput_Router_Temp.py` | `B03_FileInput_Router_Temp.py` | 임시 보관함 묶음/파일 CRUD, attach API (`linked` 묶음 대시보드 목록 쿼리 제외) |
| `B03_FileInput_Schema_Temp.py` | `B03_FileInput_Schema_Temp.py` | 임시 보관함 Pydantic 스키마 |
| `B03_FileInput_Repository_Temp.py` | `B03_FileInput_Repository_Temp.py` | `temp_upload_batches`, `temp_upload_files` Access |
| `cleanup_expired_temp_uploads()` | `common_util_temp_cleanup.py` | 30일 경과 만료 임시 보관 자료 자동 삭제 |

## 저장소 및 초기화
| 항목 | 위치 | 역할 |
|---|---|---|
| `create_input_file()` | `B03_FileInput_Repository.py` | `input_files` 원본 메타데이터 및 계획노선 CSV 용도 등록 |
| `get_project_storage_relative_path()` | `B03_FileInput_Repository.py` | 프로젝트 상대 저장경로 조회 |
| `create_upload_session()` / `get_upload_session()` | `B03_FileInput_Repository.py` | 청크 세션 생성·조회 |
| `upsert_upload_chunk()` / `list_completed_chunk_indexes()` | `B03_FileInput_Repository.py` | 청크 기록·완료 인덱스 조회 |
| `reset_project_subsequent_stages()` | `common_util_project_reset.py` | 자료 교체/연결 시 stage 1 이후 하위 단계 산출물 자동 초기화 |

## workflow·알림
| 항목 | 위치 | 역할 |
|---|---|---|
| `trigger_wf1_analysis_and_email()` | `B03_FileInput_Router.py` | WF1 분석 실행과 완료·실패 이메일 연결 |
| `start_stage()` | `B03_FileInput_Router.py` | WF1 시작, stage 1 IN_PROGRESS 전이 (동시 실행 가드 및 stage 3 완료 스피너 잠금) |
| `complete_stage()` | `B03_FileInput_Router.py` | WF0/WF1 완료 전이 (계획노선 CSV 필수 검증 후 전이 허용) |
| `fail_stage()` | `B03_FileInput_Router.py` | WF1 실패 전이 (`fail_stage` 메시지 200자 제한 클램프) |
| `get_project_workflow_state()` | `B03_FileInput_Router.py` | 단일 프로젝트 workflow 상태 반환 |

workflow 정의: [[workflow_state]], 저장경로: [[storage_paths]], 임시보관함: [[temp_upload]].