Aislo/.agent/migration_plan.md

B03~B06 기능 마이그레이션 계획서

갱신일: 2026-07-05 상태: 백엔드 마이그레이션 완료 — Stage 04 (B03B06) 백엔드 이전 완료. 남은 항목은 프론트엔드(Vanilla TS) 재작성과 실제 DB 연동 검증. 범위: B03_FileInput ~ B06_wf3_ProfileCross DB: MariaDB v10.6+ (aiomysql 드라이버, Raw SQL)

진척 요약:

• Stage 0 (공통 기반): ✅ 완료
• Stage 1 B03 (파일 입력): ✅ 백엔드 완료
• Stage 2 B04 (지표면 분석): ✅ 백엔드 완료 (필터 4종 + 모델 5종 + 스무딩 + 등고선 + 파이프라인)
• Stage 3 B05 (경로 설계): ✅ 백엔드 완료 (Dijkstra + ridge-valley + skeleton)
• Stage 4 B06 (종횡단 생성): ✅ 백엔드 완료 (sampler + 종횡단 + Repository/Router)
• 공통: 전 페이지 DB 접근을 aiomysql Raw SQL로 통일, 순수 계산부는 실데이터로 검증
• 남은 작업: B04~B06 프론트엔드(Vanilla TS/WebCAD), 실제 aislo_db 연동·구형 수치 비교

---

1. 확정 기준

• 기능 동작의 기준 원본은 0_old/main.py와 0_old/utils/이다.
• 0_old/backend/app/은 이전 프로토타입 참고 자료이며 최종 동작 기준으로 사용하지 않는다.
• 신규 배치 구조는 .agent/structure.md를 따른다. 구형 파일 구조는 승계하지 않는다.
• 백엔드는 .agent/backend.md, 프론트엔드는 .agent/frontend.md를 따른다.
• 저장 구조 및 DB 경로 열은 .agent/db_schema_simple.md의 단계별 파일시스템 구조를 따른다.
• DB 스키마 작성·수정은 별도 담당 작업이다. 이 마이그레이션은 확정된 DB 계약만 aiomysql와 Raw SQL로 사용한다.
• 루트 main.py에는 페이지 라우터 등록만 추가한다.
• 구형 React/TSX UI는 복사하지 않고 현재 Vanilla TypeScript 구조와 공통 UI 템플릿에 맞게 재작성한다.

---

2. 작업 원칙

2.1 함수 하나씩 이전

각 작업 단위는 다음 순서를 지킨다.

1. 대상 구형 함수와 직접 의존성 확인
2. 신규 페이지 폴더에 책임에 맞는 파일 하나 생성
3. 함수 하나만 이전·수정
4. 해당 함수 단위 테스트 또는 최소 실행 검증
5. 포맷터·린터 실행
6. 검증 완료 후 다음 함수 진행

한 번에 구형 모듈 전체를 복사하지 않는다. 구형 전역 경로, 동기식 파일 처리, 하드코딩 설정은 그대로 가져오지 않는다.

2.2 파일 분리

• *_Router.py: FastAPI 엔드포인트와 응답 변환
• *_Schema.py: Pydantic 요청·응답 검증
• *_Engine_*.py: 페이지 고유 연산
• *_Repository.py: asyncpg Raw SQL과 DB 경로 메타데이터 처리
• common_util/: 둘 이상의 페이지가 실제로 공유하는 경로·원자적 파일 쓰기·기하 유틸만 배치
• 단일 파일이 700줄에 도달하기 전에 기능별 파일 분할을 제안하고 승인 후 structure.md를 갱신한다.

2.3 저장소 경계

storage/{company_slug}/{user_slug}/{project_id}/
├── B03_FileInput/
├── B04_wf1_Surface/
├── B05_wf2_Route/
└── B06_wf3_ProfileCross/

각 페이지는 자기 폴더만 직접 생성·수정한다. 상위 단계 변경 시 하위 결과를 임의 삭제하지 않고 stale_from을 갱신한다.

---

3. 구형 기능 분석 결과

3.1 B03_FileInput

구형 원본:

• 0_old/main.py: check_sample, upload_files
• 보조 참고: 0_old/backend/app/analyzer.py의 파일 분석 함수

책임:

• LAS/TIF/TFW/PRJ/DXF 업로드 검증
• B03_FileInput/input/{file_type}/ 저장
• 파일 메타데이터 추출 및 input_files 기록
• 업로드 완료 상태 반환

B04로 넘길 기능:

• process_pipeline
• run_ground_analysis
• 포인트 필터링 및 지표면 모델 생성

3.2 B04_wf1_Surface

구형 원본:

• 0_old/main.py: process_pipeline, ensure_terrain_models, 지표면·포인트 API
• 0_old/utils/structurizer.py
• filter_grid_min_z.py, filter_csf.py, filter_pmf.py, filter_ransac.py
• terrain_model_converter.py, surface_smoother.py, contour_extractor.py

책임:

• LAS 구조화와 지면 필터 생성
• 변환 포인트클라우드 저장
• TIN/DTM/NURBS/implicit/meshfree 모델 생성
• 스무딩, 미리보기, 등고선 생성
• 지표면 모델 선택 확정 및 하위 단계 stale 전파

3.3 B05_wf2_Route

구형 원본:

• 0_old/main.py: 경로점 CRUD, solve/result/confirm, stale 서명 처리
• 0_old/utils/route_solver.py
• 0_old/utils/route_solver_ridgevalley.py
• 0_old/utils/terrain_skeleton.py

책임:

• BP/EP/CP/AP/FP 입력 검증과 저장
• Dijkstra 및 ridge-valley 경로 계산
• 경사·곡선반경·회피/금지 구역 검증
• 경로 결과 조회·확정 및 B06 stale 전파

3.4 B06_wf3_ProfileCross

구형 원본:

• 0_old/main.py: sections generate/get/confirm 및 입력 서명 처리
• 0_old/utils/surface_elevation_sampler.py
• 0_old/utils/section_generator.py

책임:

• 확정 경로와 확정 지표면 모델 검증
• 종단 표고 프로필 생성
• 지정 측점 간격의 횡단면 생성
• 결과 조회·확정 및 재현성 서명 관리

---

4. 함수 단위 실행 순서

Stage 0 — 공통 기반

• config_system.py의 저장 경로에서 불필요한 projects 경로 제거
• 프로젝트 루트와 B03~B06 단계별 경로를 안전하게 만드는 공통 경로 함수 추가
• JSON 원자적 쓰기 함수 이전
• workflow.json 읽기 및 stale 필드 원자적 갱신 함수 이전
• 공통 함수별 테스트 작성

Stage 1 — B03_FileInput

• B03_FileInput_Schema.py: 파일 종류·크기·확장자 검증 모델
• B03_FileInput_Engine.py: 안전한 파일명과 목적 경로 결정 함수
• B03_FileInput_Engine.py: 업로드 스트림 저장 함수
• B03_FileInput_Engine_Analyze.py: LAS 메타데이터 분석 함수
• B03_FileInput_Engine_Analyze.py: PRJ/TIF/TFW 메타데이터 분석 함수
• B03_FileInput_Repository.py: input_files 저장 함수
• B03_FileInput_Router.py: 업로드 엔드포인트
• B03 프론트 드롭존·목록·검증·로딩 UI를 공통 컴포넌트 기반으로 작성
• 업로드 통합 테스트

Stage 2 — B04_wf1_Surface

• LAS 구조화 함수 이전
• grid-min-z 필터 함수 이전 및 검증
• CSF 필터 함수 이전 및 검증
• PMF 필터 함수 이전 및 검증
• RANSAC 필터 함수 이전 및 검증
• 지표면 모델 공통 컨텍스트 생성 함수 이전 (ModelContext + 메시 유틸)
• TIN 생성 함수 이전
• DTM 생성 함수 이전
• NURBS 생성 함수 이전
• implicit 생성 함수 이전
• meshfree 생성 함수 이전
• DTM/TIN 스무딩 함수 이전
• 등고선 생성 함수 이전
• 미리보기·메타데이터·모델 확정 라우트 추가 (analyze/models 라우트 + 파이프라인 manifest)
• processed_point_cloud, surface_models, terrain_layers Raw SQL 저장 함수 추가 (aiomysql)
• B04 폼·WebCAD 뷰어를 Vanilla TypeScript로 재작성
• 샘플 LAS 결과를 구형 출력과 비교 검증

Stage 3 — B05_wf2_Route

• 경로점 Pydantic 모델 및 유효성 검사 이전 (Schema)
• 경로점 저장·조회·초기화 함수 이전 (Repository)
• 비용면 생성 및 캐시 함수 이전 (Solver)
• Dijkstra 단일 구간 탐색 함수 이전 (Geometry)
• 최적 경로 조립 함수 이전 (Solver solve_optimal_route)
• 지형 skeleton 생성 함수 이전 (Skeleton, D8 흐름누적)
• ridge-valley 탐색 함수 이전 (RidgeValley, 정속경사+fillet)
• 입력 서명·stale 판정 함수 이전
• 경로 확정 함수 이전 (Repository confirm_route + confirm 라우트)
• routes, route_points, route_statistics Raw SQL 저장 함수 추가 (aiomysql)
• B05 경로 편집·제약조건·결과 뷰어를 Vanilla TypeScript로 재작성
• 기존 route solver 테스트를 신규 구조로 이관·통과

Stage 4 — B06_wf3_ProfileCross

• 지표면 sampler 인터페이스 이전 (Engine_Sampler: SurfaceElevationSampler Protocol)
• DTM grid sampler 함수 이전 (DtmGridSampler, 4-꼭짓점 valid 검증)
• 보간 sampler 함수 이전 (InterpolatedSurfaceSampler + build_surface_sampler 5종)
• 측점 배열 생성 함수 이전 (Engine_Section: _chainages)
• 경로 보간 및 접선 계산 함수 이전 (_interpolate_xy, _tangent_at)
• 종단·횡단 생성 함수 이전 (generate_sections)
• 입력 서명·중복 실행 방지 함수 이전 (delete_sections_for_route로 멱등 재실행만 구현)
• 결과 조회·확정 라우트 추가 (sections/generate·get·confirm 라우트)
• longitudinal_sections, cross_sections Raw SQL 저장 함수 추가 (aiomysql Repository)
• B06 종단도·횡단 카드 UI를 Vanilla TypeScript로 재작성
• 구형 section 결과와 수치 비교 검증

B06 백엔드 구현 파일:

• B06_wf3_ProfileCross_Engine_Sampler.py — 표고 sampler (Protocol + DTM/보간 5종)
• B06_wf3_ProfileCross_Engine_Section.py — 종횡단 생성 (측점/접선/횡단 샘플)
• B06_wf3_ProfileCross_Engine.py — 오케스트레이터 (경로 GeoJSON→종횡단→파일 저장)
• B06_wf3_ProfileCross_Repository.py — aiomysql Raw SQL (2 테이블)
• B06_wf3_ProfileCross_Schema.py / _Router.py — Pydantic + FastAPI 라우트

검증 상태: B04(DTM)→B05(경로 70.71m)→B06(종단면+횡단면 5건) end-to-end 파일 생성 확인. DB 저장 함수는 FakeCursor 기반 문법 검증만 수행 (실제 aislo_db 연동은 나스 서버 준비 후).

---

5. API 및 상태 원칙

• API 경로는 /api/projects/{project_id}/... 형태를 유지하되 페이지별 Router에서 선언한다.
• 모든 JSON 요청은 Pydantic 검증 후 Engine으로 전달한다.
• 긴 지형 연산은 이벤트 루프를 막지 않도록 실행 방식을 별도 검토한다.
• 오류 응답은 {"status": "error", "message": "원인"} 형식을 유지한다.
• 프론트 API 호출은 로딩 Overlay를 항상 시작·해제한다.
• UI 문자열은 ui_template_locale.ts에 먼저 등록한 뒤 참조한다.
• 상위 단계 재계산 시 하위 결과는 stale 처리하며 다른 페이지 폴더를 직접 삭제하지 않는다.

---

6. 검증 체크리스트

각 함수 이전 후:

• 구형 함수의 입력·출력 계약 비교
• 하드코딩 설정 제거 및 config_system.py 연결
• 신규 단계별 저장 경로 사용 확인
• 경로 이탈 및 파일명 공격 방지 확인
• 예외 처리와 표준 오류 응답 확인
• Python: ruff format, ruff check --fix
• TypeScript/CSS: npx prettier --write
• 단위 테스트 실행
• 관련 통합 테스트 실행
• 단일 파일 700줄 미만 확인

단계 완료 후:

• B03 업로드 파일과 DB 메타데이터 일치
• B04 지표면 모델의 범위·점 수·표고 통계 비교
• B05 경로 길이·경사·곡선반경·제약 위반 비교
• B06 측점 수·종단 표고·횡단 좌표 비교
• 다중 브라우저 polling 및 stale 전파 확인

---

7. 작업 경계와 보류 항목

• DB 테이블·FK·인덱스 정의 변경은 본 작업에서 수행하지 않는다.
• .agent/db_schema_simple.md는 DB 담당자의 작업 영역이므로 직접 수정하지 않는다.
• DB 스키마가 확정되지 않은 Repository 함수는 인터페이스만 계획하고 임의 열을 만들지 않는다.
• B07 이후 기능은 이번 마이그레이션 범위에서 제외한다.
• 구형 샘플 데이터는 검증 입력으로만 사용하고 신규 영구저장소로 자동 복사하지 않는다.

---

8. 다음 실행 단위

첫 구현은 Stage 0의 저장 경로 함수 하나로 시작한다. 함수와 테스트를 검증한 뒤 다음 공통 함수로 이동한다.