chore(docs): docs 폴더 git 추적 전환 · PLAN·OWNERS 최상위 이관

- `docs/` 를 .gitignore 에서 빼 git 추적 대상으로 전환 (위키·완료 이력·검증 기록) - `docs/raw/PLAN.md` · `docs/raw/OWNERS.md` 를 저장소 최상위로 이동 후 .gitignore 에 등록 — 창끼리 공유하되 저장소에는 안 올리는 장부 - 살아 있는 경로 참조 7개 파일 정정 (아카이브 107건은 그때 사실이라 그대로 둠) - graphify 날짜별 산출물(`docs/wiki/graphify-out/20*/`) 제외 — `graphify update` 가 다시 만듦 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-09 18:19:07 +09:00
parent d7cb14f416
commit eb30b774f8
527 changed files with 43083 additions and 2 deletions
@@ -0,0 +1,16 @@
+---
+type: page-plan
+status: draft
+page_id: B03_FileInput
+related_pages: ["[[B03_FileInput/B03_backend]]", "[[storage_paths]]", "[[workflow_state]]"]
+last_updated: 2026-08-18
+source: ["docs/raw/PLAN.md"]
+---
+
+# B03 다중 라이다 파일·대용량 처리 보류 계획
+
+라이다 원본은 공사 면적에 따라 여러 도엽으로 나뉘지만 현재 파일 종류별 업로드 슬롯은 하나다. 확인된 운용 범위는 평상시 최대 2장·30GB 미만, 최대 3장·50GB 미만이다.
+
+현재 결정은 구현 보류다. 드론 라이다 프로그램 전처리에서 병합 가능 여부를 먼저 확인하며, 이번 범위에서는 병합 로직과 노선 버퍼 클리핑을 구현하지 않는다. 전처리 분석은 병합된 전체 범위를 대상으로 하는 방침이다.
+
+착수 전 완료 조건은 드론 프로그램의 병합 가능 여부 확인, 용량 대책 방식 합의, 별도 계획 수립이다.
@@ -0,0 +1,35 @@
+---
+type: page-api
+status: stable
+page_id: B03_FileInput
+related_pages: ["[[B03_FileInput/B03_frontend]]", "[[B03_FileInput/B03_backend]]", "[[B03_FileInput/B03_db]]", "[[architecture/project_map]]", "[[architecture/workflow_data_flow]]"]
+last_updated: 2026-07-31
+source: ["docs/raw/verification/2026-07-31_verify_B03_planned_route_csv.md"]
+---
+
+# B03_FileInput — API
+
+이 API는 [[B03_FileInput/B03_frontend]]의 업로드 요청을 [[B03_FileInput/B03_backend]]에 연결하고 [[workflow_state]]의 stage 0·1 상태를 조회·변경한다.
+
+기본 prefix: `/api/projects` (`B03_FileInput_Router.py:66`). 세션 인증과 공통 오류 형식은 [[auth_rbac]], [[api_common]]을 참조한다.
+
+## 일반 업로드
+| 항목 | 위치 | 역할 |
+|---|---|---|
+| `POST /{project_id}/files` | `B03_FileInput_Router.py:267` | 계획노선 CSV (필수) / LAS / TIF / TFW / PRJ / DXF 다중 업로드·검증·메타데이터 등록 |
+
+## 청크 업로드
+| 항목 | 위치 | 역할 |
+|---|---|---|
+| `POST /{project_id}/upload-sessions` | `B03_FileInput_Router.py:400` | 청크 업로드 세션 생성 |
+| `POST /{project_id}/chunks` | `B03_FileInput_Router.py:443` | 청크 1개 저장 및 진행률 반환 |
+| `POST /{project_id}/finalize` | `B03_FileInput_Router.py:507` | 모든 청크 병합·원본 파일 등록 |
+| `GET /{project_id}/upload-status/{session_id}` | `B03_FileInput_Router.py:623` | 세션 상태·완료 청크 인덱스 조회 |
+
+## workflow 조회
+| 항목 | 위치 | 역할 |
+|---|---|---|
+| `GET /{project_id}/workflow-state` | `B03_FileInput_Router.py:667` | `current_stage`와 7단계 상태 반환 (필수 계획노선 검증 연동) |
+
+전체 경로는 `/api/projects/{project_id}/...`이며, workflow 상태 공통 정의는 [[workflow_state]]에 둔다.
+
@@ -0,0 +1,63 @@
+---
+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]].
@@ -0,0 +1,29 @@
+---
+type: page-db
+status: draft
+page_id: B03_FileInput
+related_pages: ["[[B03_FileInput/B03_backend]]", "[[B03_FileInput/B03_api]]", "[[architecture/project_map]]", "[[architecture/workflow_data_flow]]"]
+last_updated: 2026-07-12
+source: 상위 프로젝트 B03_FileInput_Repository.py 실 코드 직접 확인 (2026-07-12)
+---
+
+# B03_FileInput — DB 사용 관계
+
+공유 테이블 정의는 [[db_schema/files_surface]]에서 1차 관리한다.
+
+| 항목 | 위치 | 역할 |
+|---|---|---|
+| `input_files` | `B03_FileInput_Repository.py:11` | 원본 파일 유형·상대경로·크기·메타데이터 등록 |
+| `upload_sessions` | `B03_FileInput_Repository.py:89` | 청크 업로드 세션과 전체 파일 정보 저장 |
+| `upload_chunks` | `B03_FileInput_Repository.py:165` | 청크 인덱스·해시·크기 저장 |
+| `projects` | `B03_FileInput_Router.py:111` | 업로드·WF1 진행상태 호환 캐시 갱신 |
+| `project_workflow_stages` | `B03_FileInput_Router.py:175` | stage 0/1 시작·완료·실패 전이와 상태 조회 |
+
+## 파일 경로
+| 항목 | 위치 | 역할 |
+|---|---|---|
+| 원본 입력 | `B03_FileInput_Engine.py:15` | `B03_FileInput/input/{file_type}/`에 저장 |
+| 청크 임시파일 | `B03_FileInput_Engine.py:64` | 프로젝트 저장소 하위 임시 세션 디렉터리 사용 |
+| DB 저장값 | `B03_FileInput_Repository.py:64` | 프로젝트 루트 기준 상대경로 저장 |
+
+경로 규칙 상세: [[storage_paths]].
@@ -0,0 +1,30 @@
+---
+type: page-dependencies
+status: draft
+page_id: B03_FileInput
+related_pages: ["[[B03_FileInput/B03_frontend]]", "[[B03_FileInput/B03_backend]]", "[[architecture/project_map]]", "[[architecture/workflow_data_flow]]"]
+last_updated: 2026-07-12
+source: 상위 프로젝트 B03_FileInput import 구문 직접 확인 (2026-07-12)
+---
+
+# B03_FileInput — Dependencies
+
+공유 의존성의 1차 정의는 [[dependencies]]에 둔다.
+
+| 항목 | 위치 | 역할 |
+|---|---|---|
+| FastAPI | `B03_FileInput_Router.py:10` | multipart 파일·폼 요청과 라우터 |
+| Pydantic | `B03_FileInput_Schema.py:6` | 파일명·크기·확장자·청크 요청 검증 |
+| aiomysql | `B03_FileInput_Router.py:9` | MariaDB 비동기 트랜잭션 |
+| laspy | `B03_FileInput_Engine_Analyze.py:7` | LAS 포인트클라우드 메타데이터 분석 |
+| rasterio | `B03_FileInput_Engine_Analyze.py:9` | TIF 래스터 메타데이터 분석 |
+| pyproj | `B03_FileInput_Engine_Analyze.py:10` | PRJ/TIF CRS 해석 |
+| numpy | `B03_FileInput_Engine_Analyze.py:8` | LAS 통계 계산 |
+
+## 공통 모듈
+| 항목 | 위치 | 역할 |
+|---|---|---|
+| `common_util_storage` | `B03_FileInput_Engine.py:11` | 단계별 저장경로 생성·해석 → [[storage_paths]] |
+| `common_util_workflow_state` | `B03_FileInput_Router.py:50` | stage 상태 전이 → [[workflow_state]] |
+| `common_util_email` | `B03_FileInput_Email.py:8` | 업로드·분석 완료/실패 이메일 발송 |
+| `common_util_json` | `B03_FileInput_Router.py:47` | workflow 보조 JSON 원자적 저장 |
@@ -0,0 +1,49 @@
+---
+type: page-frontend
+status: stable
+page_id: B03_FileInput
+related_pages: ["[[B03_FileInput/B03_backend]]", "[[B03_FileInput/B03_api]]", "[[B03_FileInput/B03_db]]", "[[las_free_sheet_surface]]", "[[architecture/project_map]]", "[[architecture/workflow_data_flow]]"]
+last_updated: 2026-08-30
+source: ["docs/raw/verification/2026-07-31_verify_B03_planned_route_csv.md", "docs/raw/verification/2026-08-29_verify_B03_reupload_reanalysis_cache.md"]
+---
+
+# B03_FileInput — Frontend
+
+`las_free` 토글은 LAS 카드와 필수검증을 비활성화하고 계획노선·도엽등고선만으로 WF1을 실행한다. 상세 계약은 [[las_free_sheet_surface]]를 따른다.
+
+## 페이지·업로드 흐름
+| 항목 | 위치 | 역할 |
+|---|---|---|
+| `renderB03FileInput()` | `B03_FileInput_UI_Page.ts:52` | 일반업무 레이아웃(`createGeneralLayout`) 적용 및 계획노선 CSV 선택 필수 입력 영역 조립 |
+| 청크 세션 생성 | `B03_FileInput_UI_Page.ts` | 대용량 파일을 청크 업로드로 시작 |
+| 청크 병합 완료 | `B03_FileInput_UI_Page.ts` | 서버 병합 결과를 상태에 저장 |
+| 필수 파일 검증 | `B03_FileInput_UI_Page.ts` | 계획노선 CSV 누락/오류 시 B04 이동 버튼 차단 |
+| WF1 진행률 폴링 | `B03_FileInput_UI_Page.ts` | 분석 상태와 진행률 갱신 |
+| 업로드 완료 캐시 정리 | `B03_FileInput_UI_Page.ts:71` | route 최신값·section detail·preload 표식을 제거해 B05가 재분석 결과를 조회 |
+| B04 이동 | `B03_FileInput_UI_Page.ts` | WF1 및 필수 계획노선 검증 완료 시 `ROUTES.B04_WF1_SURFACE`로 이동 |
+
+## UI 지원 유틸리티 (분할 완료)
+| 항목 | 위치 | 역할 |
+|---|---|---|
+| 카드 템플릿 및 포맷터 | `B03_FileInput_UI_Support.ts` | UI 생성 템플릿 및 파일 크기/ETA 포맷터 등 분리하여 단일 파일 700줄 제한 준수 |
+
+## API 클라이언트
+| 항목 | 위치 | 역할 |
+|---|---|---|
+| `uploadProjectFiles()` | `B03_FileInput_Api_Fetch.ts:60` | 계획노선 CSV 및 지형 다중 파일 업로드 |
+| `createUploadSession()` | `B03_FileInput_Api_Fetch.ts:82` | 청크 세션 생성 |
+| `uploadFileChunk()` | `B03_FileInput_Api_Fetch.ts:100` | 단일 청크 전송 |
+| `finalizeUploadSession()` | `B03_FileInput_Api_Fetch.ts:119` | 청크 병합 요청 |
+| `fetchUploadStatus()` | `B03_FileInput_Api_Fetch.ts:133` | 청크 업로드 상태 조회 |
+| `checkWF1AnalysisStatus()` | `B03_FileInput_Api_Fetch.ts:154` | WF1 분석 상태 조회 |
+
+## 브라우저 상태·오프라인 보조
+| 항목 | 위치 | 역할 |
+|---|---|---|
+| `loadB03ProjectState()` | `B03_FileInput_State.ts:23` | 프로젝트별 저장 상태 복원 |
+| `saveB03UploadedFile()` | `B03_FileInput_State.ts:34` | 업로드 파일 결과 저장 |
+| `updateB03AnalysisState()` | `B03_FileInput_State.ts:53` | 분석 상태·진행률 저장 |
+| `restoreB03ProjectState()` | `B03_FileInput_State.ts:71` | 재진입 시 상태와 완료 콜백 복원 |
+
+공통 UI는 [[ui_templates]], 단계 상태는 [[workflow_state]]를 참조한다.
+
@@ -0,0 +1,31 @@
+---
+type: page-backend
+status: stable
+page_id: B03_FileInput
+related_pages: ["[[B03_FileInput/B03_backend]]", "[[B03_FileInput/B03_frontend]]", "[[B04_PreProcess/B04_drainage_compass_crs]]", "[[completed_2026-09-03]]"]
+last_updated: 2026-09-03
+source: ["docs/raw/plans/2026-09-03_plan_completed_items.md"]
+---
+
+# B03 계획노선 정본·좌표계 후속
+
+## 계획노선 정본
+
+| 항목 | 위치 | 역할 |
+|---|---|---|
+| `save_initial_snapshot()` | `common_util/common_util_initial_snapshot.py` | 사업지 좌표계로 변환·트림·조밀화한 `planned_route.csv`를 초기값 정본으로 저장 |
+| 스냅샷 체인 | `B03_FileInput/B03_FileInput_Service_Chain.py` | 체인에서 만든 계획노선 점을 정본 저장 창구에 전달 |
+| `load_design_route()` | `common_util/common_util_route_geometry.py` | `surface_params`가 있는 설계 호출은 초기값 CSV를 우선 사용 |
+| `discard_initial_snapshot()` | `common_util/common_util_initial_snapshot.py` | 지표면·노선 변경 시 CSV를 포함한 초기 스냅샷 폐기 |
+
+프론트엔드는 업로드한 원본 파일명을 표시하고, 백엔드는 변환 CSV를 계산 정본으로 사용한다. 트림 전 범위가 필요한 호출은 원본 경로를 유지한다.
+
+## LAS 없는 설계와 업로드 상태
+
+| 항목 | 위치 | 역할 |
+|---|---|---|
+| `run_sheet_surface_analysis()` | `B04_PreProcess/B04_PreProcess_Engine_SheetSurface.py` | 공통 계획노선 로더와 지형 PRJ 좌표계로 도엽 서피스 생성 |
+| `download_geodata()` | `B04_PreProcess/` | 노선 PRJ가 아닌 지형 PRJ 폴더에서 도엽 좌표계 탐색 |
+| `lasFreeCheck` change | `B03_FileInput/B03_FileInput_UI_Page.ts` | 토글 직후 필수 슬롯과 업로드 버튼 활성 상태 재평가 |
+
+검증 자료에서는 변환 정본 643점, 최대 좌표차 0.00007m, 연장 2136.2m가 원본 처리 결과와 일치했고 LAS 없는 자동 체인이 완료됐다.
@@ -0,0 +1,32 @@
+---
+type: page-frontend
+status: stable
+page_id: B03_FileInput
+related_pages: ["[[B03_FileInput/B03_frontend]]", "[[B03_FileInput/B03_route_snapshot_crs]]", "[[ui_templates]]", "[[completed_2026-09-03_additional]]"]
+last_updated: 2026-09-03
+source: ["docs/raw/plans/2026-09-03_plan_completed_items_2.md"]
+---
+
+# B03 파일 입력 화면 정리
+
+## 화면 구성
+
+| 항목 | 위치 | 역할 |
+|---|---|---|
+| `B03_FileInput_UI_Guide.ts` | `B03_FileInput/` | 필요한 파일·선택 방법·주의사항을 공용 좌측 오버레이에 제공 |
+| `createWorkflowOverlays.optionsContent` | `ui_template/ui_template_overlay.ts` | B04~B07과 같은 접기·펴기 안내 패널 사용 |
+| `b03-file__pick-row` | B03 스타일 | 파일 선택·임시 보관함·업로드 버튼을 한 줄로 배치 |
+| 파일 카드 격자 | B03 스타일 | `auto-fill minmax(260px, 1fr)`로 패널 개방 시 제목 접힘 방지 |
+
+선택 영역은 47px 한 줄 바, 빈 카드는 66px, 파일이 있는 카드는 117px 기준이다. 진행률·속도·예상 완료는 전송 중에만 표시하고 별도 완료 결과 목록은 제거했다.
+
+## 입력 규칙
+
+| 항목 | 위치 | 역할 |
+|---|---|---|
+| LAS 없이 설계 | `B03_FileInput_UI_Page.ts` | 파일 입력 컨테이너에서 지형 자료 전체의 선택·필수 판정을 해제 |
+| 계획노선 선택 | B03 파일 카드 | 신규 입력은 `.shp`만 허용; 내부 계산 CSV는 사용자가 선택하지 않음 |
+| 구형 CSV 표시 | 서버 파일 매핑 | 기존 프로젝트의 업로드 CSV는 계획노선 도형 카드에 계속 표시 |
+| `updateUploadButton()` | B03 상태 갱신 | 토글·파일 선택 후 현재 필수 슬롯 기준으로 업로드 가능 여부 재판정 |
+
+비파괴 화면검증에서 SHP 부속 파일 배정, CSV 거부, 교체 확인 모달, 임시 보관함 모달과 원상복구가 확인됐다.
@@ -0,0 +1,22 @@
+---
+type: file-backend
+status: draft
+related_pages: ["[[architecture/project_map]]", "[[architecture/workflow_data_flow]]"]
+page_id: B03_FileInput
+source_file: "B03_FileInput/B03_FileInput_Router.py"
+last_updated: 2026-07-24
+---
+
+# B03_FileInput_Router.py
+
+라이다 포인트클라우드(LAS/LAZ), CAD 도면(DXF), 수목/수종 데이터 업로드, 좌표계 감지, 파싱 및 DB 기록을 서빙하는 FastAPI 백엔드 라우터입니다.
+
+## 🛠️ 주요 함수 목록
+
+| 항목 | 위치(상대 경로) | 역할 |
+|---|---|---|
+| `upload_project_input_file()` | `B03_FileInput/B03_FileInput_Router.py` | `POST /{project_id}/files/upload` 라이다/DXF 업로드 및 파일 시스템 저장 |
+| `list_project_input_files()` | `B03_FileInput/B03_FileInput_Router.py` | `GET /{project_id}/files` 프로젝트 업로드 데이터 파일 목록 조회 |
+
+## 🔗 연관 개념 및 의존성
+- `B03_FileInput_Repository.py` — `input_files` DB 기록