# 배포 및 실행 가이드 (Deployment & Execution Guide)

## 🎯 목표
**한 명령어로 전체 웹앱 실행** — Python의 `main.py` 하나만 실행하면 백엔드 + 프론트엔드 모두 자동 구동.

---

## 🚀 실행 방법 (How to Run)

### 1단계: 환경 설정 (One-time Setup)

```bash
# 프로젝트 루트로 이동
cd d:\02_Software_Prog\임도설계\ 및\ 견적자동화\ 프로그램\ 개발

# Python 가상환경 활성화
.\venv\Scripts\activate

# Node.js 패키지 설치 (처음 한 번만)
npm install

# Python 패키지 설치 (이미 설치됨, 필요시)
pip install -r requirements.txt

# MariaDB 데이터베이스 초기화 (처음 한 번만)
# MariaDB CLI에서:
# > USE aislo_db;
# > SOURCE db_management/001_create_schema.sql;
# > SOURCE db_management/002_auth_security.sql;
```

### 2단계: 웹앱 실행 (Startup)

```bash
# 프로젝트 루트에서 단일 명령:
python main.py

# 출력 예시:
# INFO:__main__:[development] 앱 시작 중...
# INFO:__main__:[Frontend] npm run build 시작...
# ✓ built in 256ms
# INFO:__main__:✓ 프론트엔드 개발 서버 백그라운드 실행
# INFO:__main__:✓ DB 풀 초기화 완료
# INFO:     Application startup complete.
# INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
```

### 3단계: 브라우저 접속

```
http://localhost:8000
```

---

## 📁 프로젝트 구조 (Project Layout)

### 루트 레벨 (Root-level — Build Configuration)
```
.
├── package.json           ← 프론트엔드 패키지 (루트에만 있음)
├── vite.config.ts        ← Vite 빌드 설정 (루트에만 있음)
├── tsconfig.json         ← TypeScript 설정 (루트에만 있음)
├── node_modules/         ← npm 의존성
└── main.py               ← FastAPI 진입점 (백엔드 + 프론트엔드 자동 실행)
```

### 프론트엔드 (Frontend)
```
A00_Common/              ← 페이지 진입점 (index.html)
├── main.ts
├── router.ts            ← SPA 라우터
├── app_shell.ts         ← 헤더/네비/푸터
└── ...

A01_Home/                ← 로그인 전 페이지
A02_ProgDetail/
A03_CompDetail/
...
B01_AccountDetail/       ← 로그인 후 페이지
B02_ProjRegister/
B03_FileInput/
...

ui_template/             ← 공유 컴포넌트 & 스타일
├── ui_template_elements.ts
├── ui_template_locale.ts
└── ui_template_theme.css

config/config_frontend.ts  ← 프론트엔드 설정 (API 주소, 경로, 상수 등)
```

### 백엔드 (Backend)
```
main.py                     ← 앱 진입점
config/
├── config_system.py       ← 환경 변수 로드
├── config_db.py           ← DB 풀 설정
└── config_frontend.ts     ← 프론트엔드 설정 (TypeScript)

common_util/
├── common_util_auth.py
├── common_util_auth_repository.py
├── common_util_email.py
└── ...

A06_Login/
├── A06_Login_Router.py   ← 로그인 API
├── A06_Login_Schema.py
└── A06_Login_Api_Fetch.ts  ← 프론트엔드 API 호출

A07_Register/
A09_Security/
B03_FileInput/
...
```

### 데이터베이스 (Database)
```
db_management/
├── 001_create_schema.sql       ← 기본 스키마 (users, companies 등)
└── 002_auth_security.sql       ← 인증 테이블 (sessions, email_otps 등)
```

---

## ✅ 주의사항 (Important Notes)

### 빌드 설정
| 파일 | 위치 | 설명 |
|------|------|------|
| `package.json` | **루트만** | npm 의존성 관리 |
| `vite.config.ts` | **루트만** | 프론트엔드 번들 설정 |
| `tsconfig.json` | **루트만** | TypeScript 컴파일 설정 |
| ❌ config/ 폴더 | **금지** | 빌드 설정 이중화 방지 |

### 실행 명령어
| 명령 | 위치 | 용도 |
|------|------|------|
| `python main.py` | 루트 | 웹앱 전체 실행 (추천) |
| `npm run build` | 루트 | 프론트엔드 빌드만 (dev용) |
| `npm run dev` | 루트 | Vite 개발 서버만 (필요시) |

### 코드 작성 시
- ❌ 루트의 `package.json`, `vite.config.ts` 두지 말 것
- ❌ `config/` 폴더에 `node_modules` 두지 말 것
- ✅ 프론트엔드 코드는 `A00_Common/`, `A0*/`, `B0*/` 에만 작성
- ✅ 백엔드 라우터는 모듈별 폴더에 `*_Router.py` 로 작성

---

## 🔧 문제 해결 (Troubleshooting)

### 문제 1: 포트 이미 사용 중
```bash
# 기존 프로세스 찾기
netstat -ano | findstr :8000

# 강제 종료 (Windows)
taskkill /PID <PID> /F
```

### 문제 2: npm 빌드 오류
```bash
# 의존성 재설치
rm -rf node_modules package-lock.json
npm install
npm run build
```

### 문제 3: DB 연결 오류
```bash
# .env 파일 확인
# DB_HOST, DB_USER, DB_PASSWORD 정확한지 확인

# MariaDB 상태 확인
mysql -u root -p -h localhost
```

---

## 📚 추가 읽기

- **로그인/보안**: `.agent/login_security_plan.md`
- **DB 스키마**: `.agent/db_schema_simple.md`
- **코더 핸드오프**: `.agent/CODER_HANDOFF.md`
- **프로젝트 규칙**: `CLAUDE.md` (프로젝트 루트)

---

**최종 정리**: `python main.py` → 브라우저 `http://localhost:8000` → 완료! 🎉