275 lines
12 KiB
Markdown
275 lines
12 KiB
Markdown
# B03~B06 기능 마이그레이션 계획서
|
|
|
|
**갱신일:** 2026-07-05
|
|
**상태:** 백엔드 마이그레이션 완료 — Stage 0~4 (B03~B06) 백엔드 이전 완료. 남은 항목은 프론트엔드(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 저장소 경계
|
|
|
|
```text
|
|
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 — 공통 기반
|
|
|
|
- [x] `config_system.py`의 저장 경로에서 불필요한 `projects` 경로 제거
|
|
- [x] 프로젝트 루트와 B03~B06 단계별 경로를 안전하게 만드는 공통 경로 함수 추가
|
|
- [x] JSON 원자적 쓰기 함수 이전
|
|
- [x] `workflow.json` 읽기 및 stale 필드 원자적 갱신 함수 이전
|
|
- [x] 공통 함수별 테스트 작성
|
|
|
|
### Stage 1 — B03_FileInput
|
|
|
|
- [x] `B03_FileInput_Schema.py`: 파일 종류·크기·확장자 검증 모델
|
|
- [x] `B03_FileInput_Engine.py`: 안전한 파일명과 목적 경로 결정 함수
|
|
- [x] `B03_FileInput_Engine.py`: 업로드 스트림 저장 함수
|
|
- [x] `B03_FileInput_Engine_Analyze.py`: LAS 메타데이터 분석 함수
|
|
- [x] `B03_FileInput_Engine_Analyze.py`: PRJ/TIF/TFW 메타데이터 분석 함수
|
|
- [x] `B03_FileInput_Repository.py`: `input_files` 저장 함수
|
|
- [x] `B03_FileInput_Router.py`: 업로드 엔드포인트
|
|
- [x] B03 프론트 드롭존·목록·검증·로딩 UI를 공통 컴포넌트 기반으로 작성
|
|
- [x] 업로드 통합 테스트
|
|
|
|
### Stage 2 — B04_wf1_Surface
|
|
|
|
- [x] LAS 구조화 함수 이전
|
|
- [x] grid-min-z 필터 함수 이전 및 검증
|
|
- [x] CSF 필터 함수 이전 및 검증
|
|
- [x] PMF 필터 함수 이전 및 검증
|
|
- [x] RANSAC 필터 함수 이전 및 검증
|
|
- [x] 지표면 모델 공통 컨텍스트 생성 함수 이전 (ModelContext + 메시 유틸)
|
|
- [x] TIN 생성 함수 이전
|
|
- [x] DTM 생성 함수 이전
|
|
- [x] NURBS 생성 함수 이전
|
|
- [x] implicit 생성 함수 이전
|
|
- [x] meshfree 생성 함수 이전
|
|
- [x] DTM/TIN 스무딩 함수 이전
|
|
- [x] 등고선 생성 함수 이전
|
|
- [x] 미리보기·메타데이터·모델 확정 라우트 추가 (analyze/models 라우트 + 파이프라인 manifest)
|
|
- [x] `processed_point_cloud`, `surface_models`, `terrain_layers` Raw SQL 저장 함수 추가 (aiomysql)
|
|
- [ ] B04 폼·WebCAD 뷰어를 Vanilla TypeScript로 재작성
|
|
- [ ] 샘플 LAS 결과를 구형 출력과 비교 검증
|
|
|
|
### Stage 3 — B05_wf2_Route
|
|
|
|
- [x] 경로점 Pydantic 모델 및 유효성 검사 이전 (Schema)
|
|
- [x] 경로점 저장·조회·초기화 함수 이전 (Repository)
|
|
- [x] 비용면 생성 및 캐시 함수 이전 (Solver)
|
|
- [x] Dijkstra 단일 구간 탐색 함수 이전 (Geometry)
|
|
- [x] 최적 경로 조립 함수 이전 (Solver solve_optimal_route)
|
|
- [x] 지형 skeleton 생성 함수 이전 (Skeleton, D8 흐름누적)
|
|
- [x] ridge-valley 탐색 함수 이전 (RidgeValley, 정속경사+fillet)
|
|
- [ ] 입력 서명·stale 판정 함수 이전
|
|
- [x] 경로 확정 함수 이전 (Repository confirm_route + confirm 라우트)
|
|
- [x] `routes`, `route_points`, `route_statistics` Raw SQL 저장 함수 추가 (aiomysql)
|
|
- [ ] B05 경로 편집·제약조건·결과 뷰어를 Vanilla TypeScript로 재작성
|
|
- [x] 기존 route solver 테스트를 신규 구조로 이관·통과
|
|
|
|
### Stage 4 — B06_wf3_ProfileCross
|
|
|
|
- [x] 지표면 sampler 인터페이스 이전 (Engine_Sampler: SurfaceElevationSampler Protocol)
|
|
- [x] DTM grid sampler 함수 이전 (DtmGridSampler, 4-꼭짓점 valid 검증)
|
|
- [x] 보간 sampler 함수 이전 (InterpolatedSurfaceSampler + build_surface_sampler 5종)
|
|
- [x] 측점 배열 생성 함수 이전 (Engine_Section: _chainages)
|
|
- [x] 경로 보간 및 접선 계산 함수 이전 (_interpolate_xy, _tangent_at)
|
|
- [x] 종단·횡단 생성 함수 이전 (generate_sections)
|
|
- [ ] 입력 서명·중복 실행 방지 함수 이전 (delete_sections_for_route로 멱등 재실행만 구현)
|
|
- [x] 결과 조회·확정 라우트 추가 (sections/generate·get·confirm 라우트)
|
|
- [x] `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의 저장 경로 함수 하나로 시작한다. 함수와 테스트를 검증한 뒤 다음 공통 함수로 이동한다.
|