5.0 KiB
5.0 KiB
배포 및 실행 가이드 (Deployment & Execution Guide)
🎯 목표
한 명령어로 전체 웹앱 실행 — Python의 main.py 하나만 실행하면 백엔드 + 프론트엔드 모두 자동 구동.
🚀 실행 방법 (How to Run)
1단계: 환경 설정 (One-time Setup)
# 프로젝트 루트로 이동
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)
# 프로젝트 루트에서 단일 명령:
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: 포트 이미 사용 중
# 기존 프로세스 찾기
netstat -ano | findstr :8000
# 강제 종료 (Windows)
taskkill /PID <PID> /F
문제 2: npm 빌드 오류
# 의존성 재설치
rm -rf node_modules package-lock.json
npm install
npm run build
문제 3: DB 연결 오류
# .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 → 완료! 🎉