260706_1_계정, 로그인, 보안 초안 작성
This commit is contained in:
@@ -0,0 +1,191 @@
|
||||
# 배포 및 실행 가이드 (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` → 완료! 🎉
|
||||
Reference in New Issue
Block a user