# 프로젝트 구조 명세서 (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_string.ts
│   └── common_util_format.py
├── db_management/                   # DB 관리 폴더 (PostgreSQL 마이그레이션 및 스키마 관리)
│   ├── schema.sql
│   └── migration_v1.py
├── 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_Style.css
├── A07_Register/                    # 로그인 전 07: 회원가입 (회사/이름/이메일/비밀번호 폼)
│   ├── A07_Register_UI_Page.ts
│   └── A07_Register_UI_Style.css
├── A08_Support/                     # 로그인 전 08: 기술지원 요청 (문의 폼 + textarea)
│   ├── A08_Support_UI_Page.ts
│   └── A08_Support_UI_Style.css
│
│                                    # ※ 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
├── B04_wf1_Surface/                 # 로그인 후 04: 1차 workflow (지표면 모델 분석) — 워크플로우 셸
│   └── B04_wf1_Surface_UI_Page.ts
├── B05_wf2_Route/                   # 로그인 후 05: 2차 workflow (경로설계) — 워크플로우 셸
│   └── B05_wf2_Route_UI_Page.ts
├── B06_wf3_ProfileCross/            # 로그인 후 06: 3차 workflow (종횡단 생성) — 워크플로우 셸
│   └── B06_wf3_ProfileCross_UI_Page.ts
├── 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)
```