177 lines
13 KiB
Markdown
177 lines
13 KiB
Markdown
# 프로젝트 구조 명세서 (structure.md)
|
|
|
|
## 1. 폴더 및 파일 명명 규칙 (Naming Convention)
|
|
|
|
- **기본 원칙:** 프론트엔드(TypeScript)와 백엔드(Python) 파일을 수직 통합 관리
|
|
- **페이지 폴더 명명:** 로그인 전은 `A01_`, 로그인 후는 `B01_` 형태 적용, 워크플로우는 `wf[번호]` 접두사를 사용
|
|
- **시스템 폴더 명명:** 공통 유틸, DB, 리소스, 영구저장소 등 시스템 및 데이터 인프라 폴더는 접두사 ID 없이 명확한 영문명 분리
|
|
- **파일 명명:** 반드시 `폴더명(페이지명)_기능_기타사양.확장자` 형태 작성
|
|
- **공통 모듈:** 공통 유틸 코드는 `common_util` 폴더 내에 `common_util_기능.확장자` 형태 보관
|
|
|
|
---
|
|
|
|
## 2. 전체 디렉토리 트리 구조
|
|
|
|
```text
|
|
my-project/
|
|
├── .agent/
|
|
│ ├── agent.md
|
|
│ └── structure.md # 본 파일
|
|
├── A00_Common/ # 프론트엔드 공통 인프라 (부트스트랩, 라우팅, 셸)
|
|
│ ├── main.ts # 앱 진입점 (스타일 주입 → 테마 복원 → 셸 → 라우터)
|
|
│ ├── router.ts # 해시 기반 SPA 라우터 + 인증 가드 + 지연 로딩 (A·B 전 라우트 등록)
|
|
│ ├── app_shell.ts # 공통 헤더/푸터 (로고, 네비, 언어·테마·로그인 토글)
|
|
│ ├── b_page_scaffold.ts # B 그룹 공통 스캐폴드 (헤더+준비중 안내 / 워크플로우 셸 래퍼)
|
|
│ └── vite-env.d.ts # Vite 클라이언트 타입 선언
|
|
├── common_util/ # 공통 유틸리티 (공통 기능 코드)
|
|
│ ├── common_util_validate.ts # 프론트 1차 유효성 검사 (이메일/빈값/최소길이)
|
|
│ ├── common_util_auth.py # 비밀번호·OTP·세션 쿠키·권한 검증
|
|
│ ├── common_util_auth_repository.py # 인증·조직·관리 Raw SQL 저장소
|
|
│ ├── common_util_email.py # 비동기 SMTP 발송 및 재시도
|
|
│ ├── common_util_email_templates.py # 인증·조직 알림 이메일 템플릿
|
|
│ ├── common_util_string.ts
|
|
│ ├── common_util_storage.py # 프로젝트 및 워크플로우 단계별 저장 경로
|
|
│ ├── common_util_json.py # JSON 원자적 저장
|
|
│ ├── common_util_workflow.py # 공유 workflow.json 상태 처리
|
|
│ └── common_util_format.py
|
|
├── db_management/ # DB 관리 폴더 (PostgreSQL 마이그레이션 및 스키마 관리)
|
|
│ ├── schema.sql
|
|
│ ├── migration_v1.py
|
|
│ └── 002_auth_security.sql # 기존 DB 로그인·보안 증분 마이그레이션
|
|
├── resources/ # 웹앱 UI 구성 리소스 (사진, 회사 로고 등 에셋)
|
|
│ ├── logo.png
|
|
│ └── banner.jpg
|
|
├── storage/ # 영구 저장소 (데이터 커서 및 대용량 파일 별도 저장 로직용)
|
|
│ └── [고객사명]/
|
|
│ └── [사용자명]/
|
|
│ └── [프로젝트ID]/ # 프로젝트별 내부 폴더/파일 자동 생성 (별도 폴더 ID 미사용)
|
|
├── ui_template/ # 공통 UI 템플릿 및 테마
|
|
│ ├── ui_template_theme.css # 글로벌 디자인 테마 및 CSS 변수 (라이트/다크)
|
|
│ ├── ui_template_locale.ts # 다국어 텍스트 배열 방식 관리 파일
|
|
│ └── ui_template_elements.ts # 공통 컴포넌트 및 그룹 템플릿 정의
|
|
├── templates/ # 보고서 출력용 마스터 양식 (DWG, Excel, PPT 등 기본 원본 템플릿 파일)
|
|
│ ├── template_report_form.xlsx
|
|
│ └── template_drawing_base.dwg
|
|
├── config/ # 프로그램 내부 제어 및 시스템 환경 설정 폴더
|
|
│ ├── config_system.py # 백엔드 작동 제어 및 알고리즘 파라미터
|
|
│ ├── config_db.py # 데이터베이스 연결 제어 설정
|
|
│ ├── config_frontend.ts # 프론트엔드 제어 및 웹 환경 설정
|
|
│ ├── package.json # Node.js 의존성 (npm/vite)
|
|
│ ├── tsconfig.json # TypeScript 설정
|
|
│ └── vite.config.ts # Vite 빌드 설정
|
|
├── A01_Home/ # 로그인 전 01: 홈 (소개, 소식, 사이트맵 등)
|
|
│ ├── A01_Home_UI_Page.ts
|
|
│ ├── A01_Home_UI_Style.css
|
|
│ └── A01_Home_Api_Fetch.py
|
|
├── A02_ProgDetail/ # 로그인 전 02: 프로그램 상세 (6단계 워크플로우 + 핵심 기술)
|
|
│ ├── A02_ProgDetail_UI_Page.ts
|
|
│ └── A02_ProgDetail_UI_Style.css
|
|
├── A03_CompDetail/ # 로그인 전 03: 회사 상세 (미션 + 핵심 가치 + 연락처)
|
|
│ ├── A03_CompDetail_UI_Page.ts
|
|
│ └── A03_CompDetail_UI_Style.css
|
|
├── A04_NewsHistory/ # 로그인 전 04: 최신소식 및 개선 이력 (타임라인)
|
|
│ ├── A04_NewsHistory_UI_Page.ts
|
|
│ └── A04_NewsHistory_UI_Style.css
|
|
├── A05_EduDetail/ # 로그인 전 05: 교육 상세 (과정 소개 + 문의 CTA)
|
|
│ ├── A05_EduDetail_UI_Page.ts
|
|
│ └── A05_EduDetail_UI_Style.css
|
|
├── A06_Login/ # 로그인 전 06: 로그인 (이메일 + 비밀번호 폼)
|
|
│ ├── A06_Login_UI_Page.ts
|
|
│ ├── A06_Login_UI_Auth_Page.ts # 세션 쿠키·OTP 로그인 UI
|
|
│ ├── A06_Login_UI_Style.css
|
|
│ ├── A06_Login_Api_Fetch.ts
|
|
│ ├── A06_Login_Schema.py
|
|
│ └── A06_Login_Router.py
|
|
├── A07_Register/ # 로그인 전 07: 회원가입 (회사/이름/이메일/비밀번호 폼)
|
|
│ ├── A07_Register_UI_Page.ts
|
|
│ ├── A07_Register_UI_Auth_Page.ts # 조직 유형·약관·OTP 회원가입 UI
|
|
│ ├── A07_Register_UI_Style.css
|
|
│ ├── A07_Register_Api_Fetch.ts
|
|
│ ├── A07_Register_Schema.py
|
|
│ └── A07_Register_Router.py
|
|
├── A08_Support/ # 로그인 전 08: 기술지원 요청 (문의 폼 + textarea)
|
|
│ ├── A08_Support_UI_Page.ts
|
|
│ └── A08_Support_UI_Style.css
|
|
├── A09_Security/ # 로그인 전 09: 보안 및 약관 동의 (필수/선택 약관 확인)
|
|
│ ├── A09_Security_UI_Page.ts # 약관 동의 페이지 (이용약관/개인정보/마케팅/보안정책)
|
|
│ ├── A09_Security_UI_Style.css # A09 고유 약관 박스/체크박스 스타일
|
|
│ ├── A09_Security_Api_Fetch.ts # 동의 내용 제출 API 클라이언트
|
|
│ ├── A09_Security_Terms.ts # 약관 텍스트 데이터 (한/영 다국어)
|
|
│ ├── A09_Security_Schema.py # 조직·관리자 보안 요청 검증
|
|
│ └── A09_Security_Router.py # 마스터·시스템 관리자·활동 로그 API
|
|
│
|
|
│ # ※ B01·B02 본문 완성 / B03~B11 헤더·셸만 (본문은 0_old 참고 후 구체화)
|
|
├── B01_AccountDetail/ # 로그인 후 01: 계정 상세 (기본정보 수정 + 비밀번호 변경)
|
|
│ ├── B01_AccountDetail_UI_Page.ts
|
|
│ └── B01_AccountDetail_UI_Style.css
|
|
├── B02_ProjRegister/ # 로그인 후 02: 프로젝트 등록 (기본정보 입력 폼)
|
|
│ ├── B02_ProjRegister_UI_Page.ts
|
|
│ └── B02_ProjRegister_UI_Style.css
|
|
├── B03_FileInput/ # 로그인 후 03: 파일 입력 (헤더+준비중 안내)
|
|
│ ├── B03_FileInput_UI_Page.ts
|
|
│ ├── B03_FileInput_UI_Style.css
|
|
│ ├── B03_FileInput_Api_Fetch.ts # 다중 파일 업로드 API 클라이언트
|
|
│ ├── B03_FileInput_Schema.py # 업로드 파일 Pydantic 검증
|
|
│ ├── B03_FileInput_Engine.py # 업로드 저장 경로·스트림 처리
|
|
│ ├── B03_FileInput_Engine_Analyze.py # 원본 파일 메타데이터 분석
|
|
│ ├── B03_FileInput_Repository.py # input_files asyncpg Raw SQL
|
|
│ └── B03_FileInput_Router.py # 다중 파일 업로드 API
|
|
├── B04_wf1_Surface/ # 로그인 후 04: 1차 workflow (지표면 모델 분석)
|
|
│ ├── B04_wf1_Surface_UI_Page.ts # 3단 레이아웃 (필터/표현 선택 폼 + 모델 목록)
|
|
│ ├── B04_wf1_Surface_UI_Style.css # B04 고유 폼 그룹/모델 카드 스타일
|
|
│ ├── B04_wf1_Surface_Api_Fetch.ts # surface/analyze·models API 클라이언트
|
|
│ ├── B04_wf1_Surface_Schema.py # 분석 요청/응답 Pydantic 검증
|
|
│ ├── B04_wf1_Surface_Engine.py # 지표면 분석 오케스트레이터
|
|
│ ├── B04_wf1_Surface_Engine_Structurize.py # LAS/LAZ 구조화
|
|
│ ├── B04_wf1_Surface_Engine_Ground.py # 지면 분석 진입
|
|
│ ├── B04_wf1_Surface_Engine_Filter_Grid.py # grid minimum-Z 필터
|
|
│ ├── B04_wf1_Surface_Engine_Filter_CSF.py # CSF 필터
|
|
│ ├── B04_wf1_Surface_Engine_Filter_PMF.py # PMF 필터
|
|
│ ├── B04_wf1_Surface_Engine_Filter_RANSAC.py # RANSAC 필터
|
|
│ ├── B04_wf1_Surface_Engine_ModelContext.py # 모델 공통 컨텍스트/메시 유틸
|
|
│ ├── B04_wf1_Surface_Engine_ModelBuild.py # TIN/DTM/NURBS/implicit/meshfree 생성
|
|
│ ├── B04_wf1_Surface_Engine_Smooth.py # DTM/TIN 스무딩
|
|
│ ├── B04_wf1_Surface_Engine_Contour.py # 등고선 생성
|
|
│ ├── B04_wf1_Surface_Engine_Pipeline.py # 파이프라인 manifest
|
|
│ ├── B04_wf1_Surface_Repository.py # processed_point_cloud/surface_models aiomysql Raw SQL
|
|
│ └── B04_wf1_Surface_Router.py # surface/analyze·models API
|
|
├── B05_wf2_Route/ # 로그인 후 05: 2차 workflow (경로설계)
|
|
│ ├── B05_wf2_Route_UI_Page.ts # 3단 레이아웃 (제어점/제약 폼 + 결과 메트릭)
|
|
│ ├── B05_wf2_Route_UI_Style.css # B05 고유 제어점 행/제약 그룹 스타일
|
|
│ ├── B05_wf2_Route_Api_Fetch.ts # route/solve·confirm API 클라이언트
|
|
│ ├── B05_wf2_Route_Schema.py # 경로 탐색 요청/응답 Pydantic 검증
|
|
│ ├── B05_wf2_Route_Engine.py # 경로 설계 오케스트레이터
|
|
│ ├── B05_wf2_Route_Engine_Geometry.py # Dijkstra 단일 구간 탐색
|
|
│ ├── B05_wf2_Route_Engine_Solver.py # 비용면 생성 + 최적 경로 조립
|
|
│ ├── B05_wf2_Route_Engine_Skeleton.py # 지형 skeleton (D8 흐름누적)
|
|
│ ├── B05_wf2_Route_Engine_RidgeValley.py # ridge-valley 탐색
|
|
│ ├── B05_wf2_Route_Repository.py # routes/route_points/route_statistics aiomysql Raw SQL
|
|
│ └── B05_wf2_Route_Router.py # route/solve·confirm API
|
|
├── B06_wf3_ProfileCross/ # 로그인 후 06: 3차 workflow (종횡단 생성)
|
|
│ ├── B06_wf3_ProfileCross_UI_Page.ts # 3단 레이아웃 (측점/횡단 옵션 폼 + 결과 메트릭)
|
|
│ ├── B06_wf3_ProfileCross_UI_Style.css # B06 고유 옵션 그룹/결과 메트릭 스타일
|
|
│ ├── B06_wf3_ProfileCross_Api_Fetch.ts # sections/generate·get·confirm API 클라이언트
|
|
│ ├── B06_wf3_ProfileCross_Schema.py # 종횡단 생성 요청/응답 Pydantic 검증
|
|
│ ├── B06_wf3_ProfileCross_Engine.py # 종횡단 생성 오케스트레이터
|
|
│ ├── B06_wf3_ProfileCross_Engine_Sampler.py # 표고 sampler (Protocol + DTM/보간 5종)
|
|
│ ├── B06_wf3_ProfileCross_Engine_Section.py # 종횡단 생성 (측점/접선/횡단 샘플)
|
|
│ ├── B06_wf3_ProfileCross_Repository.py # longitudinal/cross_sections aiomysql Raw SQL
|
|
│ └── B06_wf3_ProfileCross_Router.py # sections/generate·get·confirm API
|
|
├── B07_wf4_DesignDetail/ # 로그인 후 07: 4차 workflow (상세설계) — 워크플로우 셸
|
|
│ └── B07_wf4_DesignDetail_UI_Page.ts
|
|
├── B08_wf5_Quantity/ # 로그인 후 08: 5차 workflow (수량 산출) — 워크플로우 셸
|
|
│ └── B08_wf5_Quantity_UI_Page.ts
|
|
├── B09_wf6_Estimation/ # 로그인 후 09: 6차 workflow (견적/문서) — 워크플로우 셸
|
|
│ └── B09_wf6_Estimation_UI_Page.ts
|
|
├── B10_Payment/ # 로그인 후 10: 결재 페이지 (헤더+준비중 안내)
|
|
│ └── B10_Payment_UI_Page.ts
|
|
└── B11_Status/ # 로그인 후 11: 상태 출력 페이지 (헤더+준비중 안내)
|
|
└── B11_Status_UI_Page.ts
|
|
│
|
|
├── main.py # FastAPI 애플리케이션 진입점
|
|
├── requirements.txt # Python 의존성 (pip)
|
|
├── .env.example # 환경 변수 템플릿
|
|
└── node_modules/ # Node.js 패키지 (.gitignore)
|
|
└── .build/ # Vite 빌드 결과 (.gitignore)
|
|
```
|