14 KiB
14 KiB
프로젝트 리팩토링 및 마이그레이션 계획서
작성일: 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작성 (라우터 등록만)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 백엔드 파이썬 스타일
# 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 스타일
// 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/ 작성