M-Project/PROJECT_OVERVIEW.md

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. 프로젝트 클론 및 실행

# 프로젝트 클론
git clone <repository-url>
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. 보고서 생성

• 기간별 통계
• 카테고리별 분석
• 작업 시간 집계
• 인쇄 기능

---

🛠️ 개발 가이드

백엔드 개발

# 백엔드 컨테이너 접속
docker-compose exec backend bash

# 의존성 설치
pip install -r requirements.txt

# 개발 서버 실행
uvicorn main:app --reload --host 0.0.0.0 --port 8000

프론트엔드 개발

• 정적 파일은 frontend/ 디렉토리에 위치
• Nginx를 통해 서빙됨
• 실시간 수정 가능 (볼륨 마운트)

데이터베이스 관리

# 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. 백엔드가 시작되지 않는 경우

# 로그 확인
docker-compose logs backend

# 컨테이너 재시작
docker-compose restart backend

2. 데이터베이스 연결 오류

# DB 상태 확인
docker-compose ps db

# DB 로그 확인
docker-compose logs db

# DB 재시작
docker-compose restart db

3. 마이그레이션 오류

# 수동 마이그레이션 실행
docker-compose exec db psql -U mproject -d mproject -f /docker-entrypoint-initdb.d/파일명.sql

4. 파일 업로드 오류

# uploads 디렉토리 권한 확인
docker-compose exec backend ls -la /app/uploads

# 권한 수정
docker-compose exec backend chmod 755 /app/uploads

---

📊 모니터링

헬스체크

# 백엔드 상태 확인
curl http://localhost:16000/api/health

# 프론트엔드 상태 확인
curl http://localhost:16080

로그 모니터링

# 전체 로그
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+