# M-Project 프로젝트 개요 ## 📋 프로젝트 소개 작업보고서 시스템 - 부적합 사항 관리 및 공수 계산을 위한 웹 애플리케이션 --- ## 🏗️ 시스템 아키텍처 ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Frontend │ │ Backend │ │ Database │ │ (HTML/JS) │◄──►│ (FastAPI) │◄──►│ (PostgreSQL) │ │ Port: 16080 │ │ Port: 16000 │ │ Port: 16432 │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ▲ ▲ ▲ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Nginx │ │ Docker │ │ File Storage │ │ (Reverse Proxy)│ │ (Container) │ │ (/uploads) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` --- ## 📁 프로젝트 구조 ``` M-Project/ ├── backend/ # FastAPI 백엔드 │ ├── database/ # 데이터베이스 관련 │ │ ├── database.py # DB 연결 설정 │ │ ├── models.py # SQLAlchemy 모델 │ │ └── schemas.py # Pydantic 스키마 │ ├── migrations/ # DB 마이그레이션 파일 │ │ ├── 001_init.sql │ │ ├── 002_add_second_photo.sql │ │ ├── 003_update_categories.sql │ │ ├── 004_fix_category_values.sql │ │ ├── 005_recreate_enum_type.sql │ │ └── 006_add_projects_table.sql │ ├── routers/ # API 라우터 │ │ ├── auth.py # 인증 관련 API │ │ ├── projects.py # 프로젝트 관리 API │ │ ├── issues.py # 부적합 사항 API │ │ ├── daily_work.py # 일일 공수 API │ │ └── reports.py # 보고서 API │ ├── services/ # 비즈니스 로직 │ │ ├── auth_service.py # 인증 서비스 │ │ └── file_service.py # 파일 처리 서비스 │ ├── uploads/ # 업로드된 파일 저장소 │ ├── main.py # FastAPI 애플리케이션 진입점 │ ├── requirements.txt # Python 의존성 │ └── Dockerfile # 백엔드 Docker 설정 ├── frontend/ # 프론트엔드 │ ├── static/ # 정적 파일 │ │ ├── css/ # 스타일시트 │ │ └── js/ # JavaScript 파일 │ │ ├── api.js # API 통신 │ │ ├── date-utils.js # 날짜 유틸리티 │ │ └── image-utils.js # 이미지 처리 │ ├── admin.html # 관리자 페이지 │ ├── index.html # 메인 페이지 │ ├── daily-work.html # 일일 공수 페이지 │ ├── chart.html # 차트 페이지 │ └── issue-view.html # 부적합 사항 상세 페이지 ├── nginx/ # Nginx 설정 │ ├── nginx.conf # Nginx 설정 파일 │ └── Dockerfile # Nginx Docker 설정 ├── docker-compose.yml # Docker Compose 설정 ├── DATABASE_SCHEMA.md # 데이터베이스 스키마 문서 ├── API_DOCUMENTATION.md # API 문서 ├── PROJECT_OVERVIEW.md # 프로젝트 개요 (이 파일) └── README.md # 프로젝트 설명 ``` --- ## 🚀 시작하기 ### 1. 시스템 요구사항 - Docker & Docker Compose - Git ### 2. 프로젝트 클론 및 실행 ```bash # 프로젝트 클론 git clone cd M-Project # Docker 컨테이너 실행 docker-compose up -d # 로그 확인 docker-compose logs -f ``` ### 3. 접속 정보 - **프론트엔드:** http://localhost:16080 - **백엔드 API:** http://localhost:16000 - **API 문서:** http://localhost:16000/docs - **데이터베이스:** localhost:16432 ### 4. 기본 계정 - **관리자:** hyungi / djg3-jj34-X3Q3 - **일반 사용자:** inspector1 / pass123, inspector2 / pass456 --- ## 👥 사용자 권한 ### 관리자 (admin) - ✅ 프로젝트 생성/수정/삭제 - ✅ 사용자 계정 관리 - ✅ 모든 부적합 사항 조회/수정 - ✅ 보고서 생성 - ✅ 시스템 설정 ### 일반 사용자 (user) - ✅ 부적합 사항 등록 - ✅ 자신이 등록한 부적합 사항 수정 - ✅ 일일 공수 입력 - ✅ 보고서 조회 - ❌ 프로젝트 관리 - ❌ 사용자 관리 --- ## 🔧 주요 기능 ### 1. 프로젝트 관리 (신규 추가) - **Job No.** 기반 프로젝트 생성 - 관리자만 접근 가능한 프로젝트 생성 배너 - 프로젝트 목록 조회 및 관리 ### 2. 부적합 사항 관리 - 사진 업로드 (최대 2장) - 카테고리별 분류 - 자재누락 (material_missing) - 설계미스 (design_error) - 입고자재 불량 (incoming_defect) - 검사미스 (inspection_miss) - 상태 관리 (신규/진행중/완료) - 작업 시간 기록 ### 3. 일일 공수 관리 - 작업자 수 입력 - 정규/야근 시간 계산 - 날짜별 공수 추적 ### 4. 보고서 생성 - 기간별 통계 - 카테고리별 분석 - 작업 시간 집계 - 인쇄 기능 --- ## 🛠️ 개발 가이드 ### 백엔드 개발 ```bash # 백엔드 컨테이너 접속 docker-compose exec backend bash # 의존성 설치 pip install -r requirements.txt # 개발 서버 실행 uvicorn main:app --reload --host 0.0.0.0 --port 8000 ``` ### 프론트엔드 개발 - 정적 파일은 `frontend/` 디렉토리에 위치 - Nginx를 통해 서빙됨 - 실시간 수정 가능 (볼륨 마운트) ### 데이터베이스 관리 ```bash # DB 접속 docker-compose exec db psql -U mproject -d mproject # 마이그레이션 실행 docker-compose exec db psql -U mproject -d mproject -f /docker-entrypoint-initdb.d/새파일.sql # 백업 docker-compose exec db pg_dump -U mproject mproject > backup.sql # 복구 docker-compose exec -T db psql -U mproject mproject < backup.sql ``` --- ## 🔍 트러블슈팅 ### 1. 백엔드가 시작되지 않는 경우 ```bash # 로그 확인 docker-compose logs backend # 컨테이너 재시작 docker-compose restart backend ``` ### 2. 데이터베이스 연결 오류 ```bash # DB 상태 확인 docker-compose ps db # DB 로그 확인 docker-compose logs db # DB 재시작 docker-compose restart db ``` ### 3. 마이그레이션 오류 ```bash # 수동 마이그레이션 실행 docker-compose exec db psql -U mproject -d mproject -f /docker-entrypoint-initdb.d/파일명.sql ``` ### 4. 파일 업로드 오류 ```bash # uploads 디렉토리 권한 확인 docker-compose exec backend ls -la /app/uploads # 권한 수정 docker-compose exec backend chmod 755 /app/uploads ``` --- ## 📊 모니터링 ### 헬스체크 ```bash # 백엔드 상태 확인 curl http://localhost:16000/api/health # 프론트엔드 상태 확인 curl http://localhost:16080 ``` ### 로그 모니터링 ```bash # 전체 로그 docker-compose logs -f # 특정 서비스 로그 docker-compose logs -f backend docker-compose logs -f db docker-compose logs -f nginx ``` --- ## 🔐 보안 고려사항 ### 1. 인증 - JWT 토큰 기반 인증 - 토큰 만료 시간: 7일 - bcrypt 해시를 사용한 비밀번호 암호화 ### 2. 권한 관리 - 역할 기반 접근 제어 (RBAC) - API 레벨에서 권한 검증 - 프론트엔드 UI 레벨에서 권한별 표시/숨김 ### 3. 데이터 보호 - SQL 인젝션 방지 (SQLAlchemy ORM 사용) - XSS 방지 (입력값 검증) - 파일 업로드 검증 --- ## 📈 성능 최적화 ### 1. 데이터베이스 - 자주 조회되는 컬럼에 인덱스 설정 - 페이지네이션 구현 - 연결 풀링 사용 ### 2. API - 응답 캐싱 - 압축 전송 - 비동기 처리 ### 3. 프론트엔드 - 이미지 최적화 - 지연 로딩 - 로컬 스토리지 활용 --- ## 🚀 배포 가이드 ### 프로덕션 환경 설정 1. 환경 변수 수정 (`docker-compose.yml`) - `SECRET_KEY` 변경 - `ADMIN_PASSWORD` 변경 - 데이터베이스 비밀번호 변경 2. SSL 인증서 설정 3. 방화벽 설정 4. 백업 스케줄 설정 ### 업데이트 절차 1. 코드 업데이트 2. 데이터베이스 백업 3. 마이그레이션 실행 4. 컨테이너 재시작 5. 헬스체크 확인 --- ## 📞 지원 및 문의 ### 개발자 정보 - **개발자:** M-Project Team - **이메일:** support@m-project.com - **문서 업데이트:** 2024-10-24 ### 버전 정보 - **현재 버전:** 1.0.0 - **최종 업데이트:** 2024-10-24 - **호환성:** Docker 20.10+, Python 3.11+