# 프로젝트 리팩토링 및 마이그레이션 계획서 **작성일:** 2026-07-05 **상태:** 계획 수립 완료 **목표:** 기존 POC(Proof of Concept) 코드를 정식 프로덕션 구조로 전환 --- ## 1. 현황 분석 (Baseline Assessment) ### 1.1 기존 상태 - **위치:** `0_old/` 폴더에 백업 완료 - **제외 사항:** `venv/`, `node_modules/` 미포함 (별도 재설치 필요) - **특성:** 프로토타입 개발용 단순 구조 ### 1.2 신 구조 목표 - **거대 모듈 금지:** 기능별/페이지별 분할 자동화 - **수직 통합 관리:** 프론트엔드(TypeScript) + 백엔드(Python) 페어링 - **명확한 책임 분리:** 시스템 폴더 vs. 페이지 폴더 격리 --- ## 2. 신 디렉토리 구조 (New Structure) ``` 프로젝트_루트/ ├── .agent/ # 에이전트 명세서 │ ├── structure.md # 폴더/파일 명명규칙 │ ├── agent.md # 기술스택 및 제약조건 │ ├── backend.md # 백엔드 명세서 │ ├── frontend.md # 프론트엔드 명세서 │ └── migration_plan.md # 본 파일 (마이그레이션 가이드) │ ├── common_util/ # 공통 유틸리티 모듈 │ ├── common_util_geometry.py # 기하학 연산 (Trimesh, Shapely) │ ├── common_util_gis.py # GIS 유틸 (PostGIS, Geopandas) │ ├── common_util_file.py # 파일 I/O 및 경로 관리 │ ├── common_util_validation.py # 데이터 검증 (Pydantic) │ ├── common_util_math.py # 수학/통계 함수 │ └── common_util_string.ts # 문자열 처리 (TypeScript) │ ├── db_management/ # DB 스키마 및 마이그레이션 │ ├── schema.sql # PostgreSQL + PostGIS 초기 스키마 │ ├── migration_001_init.py # 마이그레이션 스크립트 v1 │ └── README.md # DB 운영 가이드 │ ├── resources/ # UI 리소스 (로고, 이미지, 폰트) │ ├── images/ │ │ ├── logo.svg │ │ ├── favicon.ico │ │ └── banners/ │ └── fonts/ │ └── noto-sans-kr.woff2 │ ├── storage/ # 영구 저장소 (물리 파일) │ └── README.md # 저장소 구조 설명 │ ├── ui_template/ # 공통 UI 템플릿 및 테마 │ ├── ui_template_theme.css # 글로벌 색상/폰트 변수 │ ├── ui_template_locale.ts # 다국어 관리 (i18n) │ ├── ui_template_elements.ts # 공통 컴포넌트 정의 │ └── ui_template_styles.css # 기본 컴포넌트 스타일 │ ├── templates/ # 보고서/도면 템플릿 │ ├── template_report_standard.xlsx # 표준 보고서 │ ├── template_drawing_base.dwg # CAD 기본 도면 │ └── template_quantity_sheet.xlsx # 수량 산출서 │ ├── config/ # 환경 설정 │ ├── config_system.py # 백엔드 파라미터 │ ├── config_db.py # DB 연결 설정 │ ├── config_frontend.ts # 프론트엔드 상수 │ └── .env.example # 환경 변수 템플릿 │ ├── A01_Home/ # 로그인 전 01: 홈 │ ├── A01_Home_UI_Page.ts # 페이지 UI 컴포넌트 │ ├── A01_Home_UI_Style.css # 페이지 스타일 │ ├── A01_Home_Api_Fetch.py # API 라우터 │ └── A01_Home_Schema.py # Pydantic 스키마 │ ├── A02_ProgDetail/ ... A08_Support/ # 로그인 전 페이지들 (동일 구조) │ ├── B01_AccountDetail/ # 로그인 후 01: 계정 ├── B02_ProjRegister/ # 로그인 후 02: 프로젝트 등록 ├── B03_FileInput/ # 로그인 후 03: 파일 입력 │ ├── B04_wf1_Surface/ # Workflow 1: 지표면 분석 │ ├── B04_wf1_Surface_UI_View.ts # UI 뷰어 │ ├── B04_wf1_Surface_UI_Form.ts # 입력 폼 │ ├── B04_wf1_Surface_UI_Style.css │ ├── B04_wf1_Surface_Api_Router.py # API 라우터 │ ├── B04_wf1_Surface_Engine.py # 연산 엔진 (Trimesh, PostGIS) │ └── B04_wf1_Surface_Schema.py # 데이터 스키마 │ ├── B05_wf2_Route/ ... B09_wf6_Estimation/ # 워크플로우 2-6 (동일 구조) │ ├── B10_Payment/ & B11_Status/ # 로그인 후 최종 페이지 │ ├── main.py # FastAPI 애플리케이션 진입점 ├── pyproject.toml # Python 의존성 (Poetry) ├── package.json & package-lock.json # Node.js 의존성 ├── CLAUDE.md # 프로젝트 기본 정보 ├── README.md # 프로젝트 개요 └── .gitignore # Git 제외 목록 ``` --- ## 3. 마이그레이션 단계별 계획 (Phased Migration) ### Phase 1: 기초 인프라 (Infrastructure Setup) - 1-2주 **담당:** 전체 **목표:** 설정 및 공통 유틸 정리 #### 1.1 설정 파일 정리 - [ ] `config_system.py` 작성 - FastAPI 포트, 로깅 레벨, 알고리즘 파라미터 - 예: `MESH_GRID_SIZE`, `UPLOAD_MAX_MB`, `LOG_LEVEL` - [ ] `config_db.py` 작성 - PostgreSQL 연결 문자열 (asyncpg) - PostGIS 테이블 정의 위치 - [ ] `config_frontend.ts` 작성 - API 기본 URL, 파일 업로드 제한 크기 - WebCAD 렌더링 옵션 #### 1.2 공통 유틸 마이그레이션 - [ ] **0_old/** 에서 기존 유틸 함수 추출 - [ ] `common_util/` 내 분류: - `common_util_geometry.py` ← Trimesh, Shapely 관련 - `common_util_gis.py` ← PostGIS 쿼리, Geopandas 변환 - `common_util_file.py` ← LAS, DEM, DWG 읽기/쓰기 - `common_util_validation.py` ← Pydantic 모델, 데이터 검증 #### 1.3 UI 템플릿 기초 설정 - [ ] `ui_template_theme.css` 작성 - CSS 변수 정의 (라이트/다크 모드) - 예: `--color-bg`, `--color-text`, `--color-primary` - [ ] `ui_template_locale.ts` 작성 - 한글 / 영문 키-값 쌍 - 예: `A01_Home_Title: ["반갑습니다", "Welcome"]` - [ ] `ui_template_elements.ts` 작성 - 공통 버튼, 입력창, 카드 컴포넌트 정의 #### 1.4 DB 스키마 및 마이그레이션 준비 - [ ] `db_management/schema.sql` 작성 - 사용자, 프로젝트, 파일 정보 테이블 - PostGIS 기하학 타입 (geometry, raster) - [ ] `db_management/migration_001_init.py` 작성 - asyncpg 기반 초기화 스크립트 #### 1.5 FastAPI 메인 애플리케이션 구조 - [ ] `main.py` 작성 (라우터 등록만) ```python from fastapi import FastAPI # A01_Home, B04_wf1_Surface 등에서 라우터 import # app.include_router(a01_router, prefix="/api/a01") ``` --- ### Phase 2: 로그인 전 페이지 (Pre-Login Pages) - 2-3주 **담당:** 프론트엔드 + 백엔드 (페이지별 페어) **목표:** A01~A08 페이지 완성 #### 2.1 페이지별 구조 (A01_Home 예시) 각 페이지는 다음 파일 구성: **프론트엔드 (TypeScript)** - `A01_Home_UI_Page.ts` ← 페이지 진입점 + 컴포넌트 조립 - `A01_Home_UI_Style.css` ← 페이지별 커스텀 스타일 **백엔드 (Python)** - `A01_Home_Api_Fetch.py` ← FastAPI 라우터 (`/api/a01/...`) - `A01_Home_Schema.py` ← Pydantic 요청/응답 모델 #### 2.2 A01_Home (홈) - Week 1 - [ ] `A01_Home_UI_Page.ts` 작성 - 로고, 최신 소식 패널, 사이트맵 링크 - [ ] `A01_Home_Api_Fetch.py` 작성 - `GET /api/a01/news` ← 최신 소식 조회 - [ ] 기본 스타일 적용 #### 2.3 A02_ProgDetail ~ A08_Support - Week 2-3 동일 구조로 순차 진행: - [ ] A02_ProgDetail (프로그램 상세) - [ ] A03_CompDetail (회사 상세) - [ ] A04_NewsHistory (뉴스/이력) - [ ] A05_EduDetail (교육) - [ ] A06_Login (로그인) ← **핵심: JWT 토큰 발급** - [ ] A07_Register (회원가입) ← **핵심: 사용자 생성, 이메일 검증** - [ ] A08_Support (기술 지원) --- ### Phase 3: 로그인 후 기초 페이지 (Post-Login Basic Pages) - 1-2주 **담당:** 프론트엔드 + 백엔드 **목표:** B01~B03 페이지 완성 #### 3.1 B01_AccountDetail (계정 상세) - [ ] 사용자 정보 조회/수정 - [ ] 구독 상태, 다운로드 이력 #### 3.2 B02_ProjRegister (프로젝트 등록) - [ ] 프로젝트 생성 폼 - [ ] 고객사명 / 사용자명 / 프로젝트ID 관리 - [ ] **핵심:** `storage/[고객사]/[사용자]/[프로젝트ID]/` 자동 생성 #### 3.3 B03_FileInput (파일 입력) - [ ] 파일 업로드 UI (Drag & Drop) - [ ] LAS, DEM, DWG 파일 검증 - [ ] `storage/` 경로에 물리 저장 --- ### Phase 4: Workflow 엔진 (1-4) - 4-6주 **담당:** 백엔드 주 (프론트엔드 보조) **목표:** B04~B07 워크플로우 엔진 완성 #### 4.1 B04_wf1_Surface (지표면 분석) - Week 1-2 **구조:** ``` B04_wf1_Surface/ ├── B04_wf1_Surface_UI_View.ts # WebCAD 뷰어 ├── B04_wf1_Surface_UI_Form.ts # 입력 폼 (좌측 패널) ├── B04_wf1_Surface_UI_Style.css ├── B04_wf1_Surface_Api_Router.py # GET/POST 엔드포인트 ├── B04_wf1_Surface_Engine.py # Trimesh 메쉬 생성 로직 └── B04_wf1_Surface_Schema.py # Pydantic 모델 ``` **구현:** - [ ] LAS 포인트클라우드 → Trimesh 메쉬 변환 - [ ] 메쉬 좌표 직렬화 (JSON) - [ ] WebGL 캔버스에서 렌더링 - [ ] 메쉬 정보 DB 저장 (경로만) #### 4.2 B05_wf2_Route (경로 설계) - Week 2-3 - [ ] 지도 UI (2D 평면도) - [ ] 드래그로 경로 그리기 - [ ] Geopandas + PostGIS 거리 계산 - [ ] 경로 점 배열 저장 #### 4.3 B06_wf3_ProfileCross (종횡단) - Week 3-4 - [ ] 경로 기반 고도 프로필 생성 - [ ] 종단도 + 횡단도 계산 (PostGIS) - [ ] 기울기, 높이차 자동 산출 #### 4.4 B07_wf4_DesignDetail (상세 설계) - Week 4-5 - [ ] 도로 포장 두께, 기울기 입력 - [ ] Whitebox 토양 분석 - [ ] 3D 설계 도면 생성 --- ### Phase 5: 워크플로우 후반 (5-6) + 최종 페이지 - 2-3주 **담당:** 백엔드 주 + 프론트엔드 **목표:** B08~B11 완성 #### 5.1 B08_wf5_Quantity (수량 산출) - [ ] 포장재, 흙 깍기/쌓기 수량 계산 - [ ] Excel 템플릿 자동 채우기 #### 5.2 B09_wf6_Estimation (견적/문서) - [ ] 단가 × 수량 = 금액 계산 - [ ] PDF 보고서 생성 (Jinja2 템플릿) - [ ] DWG 도면 생성 (pyDWG) #### 5.3 B10_Payment (결재) - [ ] 견적서 검토 및 승인 - [ ] 결재자 서명 프로세스 #### 5.4 B11_Status (상태/다운로드) - [ ] 프로젝트 상태 조회 - [ ] 최종 산출물 다운로드 --- ## 4. 기술 구현 가이드 (Technical Guidelines) ### 4.1 백엔드 파이썬 스타일 ```python # config 반드시 import from config.config_system import MESH_GRID_SIZE from config.config_db import DB_URL # 공통 유틸 사용 from common_util.common_util_geometry import create_mesh_from_points from common_util.common_util_validation import validate_project_id # Raw SQL (ORM 금지) query = "SELECT ST_Volume(geom) FROM surfaces WHERE project_id = $1" result = await db_pool.fetchval(query, project_id) # 에러 처리 try: mesh = create_mesh(points) except ValueError as e: return {"status": "error", "message": str(e)} ``` ### 4.2 프론트엔드 TypeScript 스타일 ```typescript // CSS 변수 사용 (색상 하드코딩 금지) const styles = ` .panel { background-color: var(--color-bg); color: var(--color-text); } `; // 다국어 (i18n 필수) const title = ui_locales.A01_Home_Title[currentLanguageIndex]; // 이벤트 핸들러 명명법 function onB04_Surface_Calculate_Click() { ... } // 로딩 스피너 (API 호출 시 필수) showLoadingOverlay(); const result = await fetchAPI("/api/b04/calculate", data); hideLoadingOverlay(); ``` ### 4.3 파일 정보 저장 규칙 - **DB에 저장:** 메타데이터만 - 파일명, 원본 경로, 업로드 시간, 파일 크기 - **물리 저장:** `storage/[고객사]/[사용자]/[프로젝트ID]/` - LAS, DEM, 중간 계산 파일, 최종 메쉬 --- ## 5. 의존성 (Dependencies) ### Python 라이브러리 ``` fastapi==0.104.1 pydantic==2.5.0 asyncpg==0.29.0 trimesh==3.23.0 geopandas==0.14.0 shapely==2.0.1 rasterio==1.3.8 laspy==2.4.1 whitebox==2.3.0 python-multipart==0.0.6 jinja2==3.1.2 pydwg==0.2.0 ``` ### Node.js 라이브러리 ``` typescript@5.x react@18.x (또는 vanilla TS) webpack@5.x tailwindcss@3.x (또는 커스텀 CSS) ``` --- ## 6. 체크리스트 (Checklist) ### 시작 전 (Pre-Migration) - [ ] `0_old/` 백업 확인 - [ ] git 커밋 (`"Refactor: Start migration to new structure"`) - [ ] 모든 폴더 생성 완료 (Phase 1에서 수행) ### 각 Phase별 마무리 - [ ] 코드 포맷팅 (`ruff format`, `prettier --write`) - [ ] 린터 체크 (`ruff check`) - [ ] 단위 테스트 작성 - [ ] git 커밋 (Phase별로 구분) ### 최종 (Post-Migration) - [ ] 전체 시스템 통합 테스트 - [ ] 프로덕션 배포 (Docker) - [ ] 사용자 승인 --- ## 7. 참고 자료 - **폴더 구조:** `.agent/structure.md` - **백엔드 명세:** `.agent/backend.md` - **프론트엔드 명세:** `.agent/frontend.md` - **기술 스택:** `.agent/agent.md` --- **다음 단계:** Phase 1 시작 → `config/` 및 `common_util/` 작성