TK-BOM-Project/RULES.md

# 🚀 TK-MP-Project: 통합 프로젝트 문서

> **최종 업데이트**: 2025년 1월 (통합 문서 생성)

---

## 📋 프로젝트 개요

**TK-MP-Project**는 BOM (Bill of Materials) 시스템의 기능 이상을 해결하고, 도면 완성 후 자재 관리의 모든 프로세스를 자동화하는 종합 시스템 개발 프로젝트입니다.

### 🎯 핵심 미션
**"도면 완성 후 자재 관리의 모든 번거로움을 해결"**

### 주요 해결 과제
- 📄 **파일 분석 자동화**: 엑셀/CSV 자재 목록의 자동 분류 및 정제
- 🔍 **정확한 분류 체계**: 파이프/피팅/볼트/밸브/계기류의 4단계 자동 분류
- 💾 **체계적 데이터 관리**: 프로젝트별 버전 관리 및 이력 추적
- 📊 **업무별 맞춤 출력**: 구매/생산/품질 각 팀의 필요에 맞는 자료 생성
- 🔄 **리비전 변화 추적**: 도면 변경 시 자재 변경사항 자동 비교

---

## 💻 기술 스택

### Frontend
- **Language**: JavaScript (ES6+)
- **Framework**: React 18 + Vite (Material-UI 제거됨)
- **Router**: 상태 기반 라우팅 (React Router 대체)
- **HTTP Client**: Axios
- **File Processing**: XLSX (SheetJS), file-saver
- **Charts**: Chart.js + react-chartjs-2
- **Styling**: 순수 HTML/CSS (인라인 스타일)

### Backend
- **Language**: Python 3.9+
- **Framework**: FastAPI (고성능 API 서버)
- **Database**: PostgreSQL 15 (복잡한 관계형 데이터 처리)
- **ORM**: SQLAlchemy (데이터베이스 모델링)
- **Data Processing**: Pandas, openpyxl (파일 처리)
- **Cache**: Redis 7

### DevOps & Tools
- **Containerization**: Docker & Docker Compose
- **Web Server**: Nginx (프로덕션)
- **Database Admin**: pgAdmin4
- **Version Control**: Git
- **Development**: VS Code + Python 확장

---

## 🏗️ 코드 구조 및 컴포넌트 관계도

### 📁 프론트엔드 구조

```
frontend/src/
├── App.jsx                     # 메인 애플리케이션 (상태 기반 라우팅)
├── SimpleLogin.jsx             # 로그인 컴포넌트
├── api.js                      # API 클라이언트 (Axios 설정)
├── components/                 # 재사용 가능한 컴포넌트
│   ├── NavigationMenu.jsx      # 사이드바 네비게이션 (권한 기반)
│   ├── BOMFileUpload.jsx       # BOM 파일 업로드 폼
│   ├── BOMFileTable.jsx        # BOM 파일 목록 테이블
│   └── RevisionUploadDialog.jsx # 리비전 업로드 다이얼로그
└── pages/                      # 페이지 컴포넌트
    ├── DashboardPage.jsx       # 대시보드
    ├── ProjectsPage.jsx        # 프로젝트 관리
    ├── JobSelectionPage.jsx    # 프로젝트 선택
    ├── BOMStatusPage.jsx       # BOM 관리 메인
    ├── SimpleMaterialsPage.jsx # 자재 목록 (Material-UI 제거됨)
    ├── MaterialComparisonPage.jsx # 리비전 비교
    └── RevisionPurchasePage.jsx   # 구매 확정
```

### 📁 백엔드 구조

```
backend/
├── app/
│   ├── main.py                 # FastAPI 애플리케이션 진입점
│   ├── config.py               # 설정 관리 (Pydantic Settings)
│   ├── auth/                   # 인증 모듈
│   │   ├── __init__.py
│   │   ├── models.py           # SQLAlchemy 인증 모델
│   │   ├── jwt_service.py      # JWT 토큰 관리
│   │   ├── auth_service.py     # 인증 비즈니스 로직
│   │   ├── auth_controller.py  # 인증 API 엔드포인트
│   │   └── middleware.py       # 권한 미들웨어
│   ├── api/                    # API 라우터
│   │   └── file_management.py  # 파일 관리 API
│   ├── routers/                # 기존 라우터
│   │   ├── files.py           # 파일/자재 API
│   │   └── jobs.py            # 프로젝트 API
│   ├── services/               # 비즈니스 로직 서비스
│   │   └── file_service.py    # 파일 처리 서비스
│   ├── utils/                  # 유틸리티
│   │   ├── logger.py          # 로깅 설정
│   │   ├── cache_manager.py   # Redis 캐시 관리
│   │   ├── file_validator.py  # 파일 검증
│   │   ├── error_handlers.py  # 에러 핸들링
│   │   └── transaction_manager.py # DB 트랜잭션 관리
│   └── schemas/                # Pydantic 스키마
│       └── response_models.py  # API 응답 모델
├── scripts/                    # DB 마이그레이션 스크립트
└── requirements.txt            # Python 의존성
```

### 🔄 컴포넌트 관계도

```mermaid
graph TD
    A[App.jsx] --> B[SimpleLogin.jsx]
    A --> C[NavigationMenu.jsx]
    A --> D[페이지 컴포넌트들]
    
    D --> E[JobSelectionPage.jsx]
    D --> F[BOMStatusPage.jsx]
    D --> G[SimpleMaterialsPage.jsx]
    
    F --> H[BOMFileUpload.jsx]
    F --> I[BOMFileTable.jsx]
    F --> J[RevisionUploadDialog.jsx]
    
    K[api.js] --> L[Backend APIs]
    
    subgraph "Backend Services"
        L --> M[auth_controller.py]
        L --> N[file_management.py]
        L --> O[files.py]
        L --> P[jobs.py]
    end
    
    subgraph "Business Logic"
        M --> Q[auth_service.py]
        N --> R[file_service.py]
    end
    
    subgraph "Data Layer"
        Q --> S[auth/models.py]
        R --> T[Database Tables]
    end
```

### 🎯 컴포넌트 분리 원칙 (적용됨)

#### 1. **페이지 컴포넌트** (200-300줄 이하)
- 전체 페이지 레이아웃과 상태 관리
- 하위 컴포넌트들의 조합
- API 호출 및 데이터 흐름 제어

#### 2. **기능별 컴포넌트** (100-150줄 이하)
- 단일 책임 원칙 적용
- 재사용 가능한 독립적 기능
- Props를 통한 데이터 전달

#### 3. **서비스 레이어** (200줄 이하)
- 비즈니스 로직 분리
- API와 컴포넌트 사이의 중간 계층
- 데이터 변환 및 검증

### 📋 분리된 컴포넌트 목록

| 원본 파일 | 분리 후 | 줄 수 변화 | 상태 |
|----------|---------|-----------|------|
| `MaterialsPage.jsx` | `SimpleMaterialsPage.jsx` | 1000+ → 300줄 | ✅ 완료 |
| `BOMStatusPage.jsx` | 3개 컴포넌트로 분리 | 400+ → 200줄 | ✅ 완료 |
| - | `BOMFileUpload.jsx` | 새로 생성 (100줄) | ✅ 완료 |
| - | `BOMFileTable.jsx` | 새로 생성 (150줄) | ✅ 완료 |
| - | `RevisionUploadDialog.jsx` | 새로 생성 (80줄) | ✅ 완료 |

### 🔧 향후 분리 대상

| 파일명 | 현재 줄 수 | 분리 계획 | 우선순위 |
|--------|-----------|----------|---------|
| `MaterialComparisonPage.jsx` | 500줄+ | 비교 로직 분리 | 중간 |
| `RevisionPurchasePage.jsx` | 300줄+ | 구매 로직 분리 | 낮음 |
| `auth_service.py` | 300줄+ | 기능별 서비스 분리 | 높음 |

### 🌐 API 엔드포인트 맵

#### 인증 API (`/auth/`)
```
POST   /auth/login          # 로그인
POST   /auth/register       # 사용자 등록
POST   /auth/refresh        # 토큰 갱신
POST   /auth/logout         # 로그아웃
GET    /auth/me             # 현재 사용자 정보
GET    /auth/verify         # 토큰 검증
GET    /auth/users          # 사용자 목록 (관리자)
PUT    /auth/users/{id}     # 사용자 수정 (관리자)
```

#### 프로젝트 API (`/jobs/`)
```
GET    /jobs/               # 프로젝트 목록
POST   /jobs/               # 프로젝트 생성
PUT    /jobs/{id}           # 프로젝트 수정
DELETE /jobs/{id}           # 프로젝트 삭제
```

#### 파일/자재 API (`/files/`)
```
GET    /files               # 파일 목록 (job_no 필터)
POST   /files/upload        # 파일 업로드
DELETE /files/{id}          # 파일 삭제
GET    /files/stats         # 파일/자재 통계
GET    /files/materials     # 자재 목록 (file_id 필터)
```

### 📊 데이터 흐름도

```mermaid
sequenceDiagram
    participant U as User
    participant F as Frontend
    participant A as Auth API
    participant B as BOM API
    participant D as Database
    participant R as Redis Cache

    U->>F: 로그인 요청
    F->>A: POST /auth/login
    A->>D: 사용자 검증
    A->>F: JWT 토큰 반환
    F->>F: 토큰 저장 (localStorage)
    
    U->>F: BOM 페이지 접근
    F->>B: GET /jobs/ (프로젝트 목록)
    B->>D: 프로젝트 조회
    B->>F: 프로젝트 데이터
    
    U->>F: 프로젝트 선택
    F->>B: GET /files?job_no=xxx
    B->>R: 캐시 확인
    alt 캐시 히트
        R->>B: 캐시된 데이터
    else 캐시 미스
        B->>D: 파일 목록 조회
        B->>R: 캐시 저장
    end
    B->>F: 파일 목록 반환
    
    U->>F: 자재 확인 클릭
    F->>B: GET /files/materials?file_id=xxx
    B->>D: 자재 데이터 조회
    B->>F: 자재 목록 반환
```

### 🔐 권한 체계

```mermaid
graph TD
    A[사용자] --> B{역할}
    B -->|admin| C[시스템 관리자]
    B -->|user| D[일반 사용자]
    B -->|viewer| E[조회 전용]
    
    C --> F[모든 권한]
    D --> G[BOM 관리]
    D --> H[프로젝트 관리]
    E --> I[조회만 가능]
    
    F --> J[사용자 관리]
    F --> K[시스템 설정]
    G --> L[파일 업로드]
    G --> M[자재 관리]
    H --> N[프로젝트 CRUD]
```

---

## 🐳 Docker 실행 환경

### 컨테이너 구성
- **tk-mp-frontend**: React + Nginx (포트: 3000/13000)
- **tk-mp-backend**: FastAPI + Uvicorn (포트: 8000/18000) 
- **tk-mp-postgres**: PostgreSQL (포트: 5432)
- **tk-mp-redis**: Redis (포트: 6379)
- **tk-mp-pgadmin**: pgAdmin4 (포트: 5050)

### 실행 방법
```bash
# 개발 환경
./scripts/dev.sh
# 또는
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d

# 프로덕션 환경  
./scripts/prod.sh
# 또는
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# 시놀로지 NAS 환경
docker-compose -f docker-compose.synology.yml up -d

# 기본 환경
docker-compose up -d
```

### 중요한 설정 사항
- **API URL 설정**: 
  - 개발환경: `http://localhost:8000` (직접 접근)
  - 프로덕션: `/api` (nginx 프록시를 통한 상대경로)
- **데이터베이스 연결**: `postgres:5432` (컨테이너명 사용, localhost 아님!)
- **환경변수**: `VITE_API_URL`로 API URL 오버라이드 가능

---

## 📁 프로젝트 구조

```
TK-MP-Project/
├── README.md
├── docker-compose.yml
├── docker-compose.dev.yml
├── docker-compose.prod.yml
├── docker-compose.synology.yml
├── frontend/                # React 프론트엔드
│   ├── src/
│   │   ├── pages/          # 페이지 컴포넌트
│   │   ├── components/     # 재사용 컴포넌트  
│   │   ├── utils/         # 유틸리티 (엑셀 등)
│   │   └── api.js         # API 통신
│   ├── Dockerfile
│   └── nginx.conf
├── backend/                # FastAPI 백엔드
│   ├── app/
│   │   ├── routers/       # API 라우터
│   │   ├── services/      # 비즈니스 로직 (분류기 등)
│   │   ├── models.py      # DB 모델
│   │   ├── main.py        # FastAPI 앱
│   │   └── database.py    # DB 연결 설정
│   ├── scripts/           # DB 마이그레이션
│   ├── uploads/           # 업로드된 파일
│   └── requirements.txt
├── database/              # DB 스키마 및 초기 데이터
│   └── init/
│       ├── 01_schema.sql
│       └── 02_seed_data.sql
└── scripts/               # 배포 스크립트
    ├── dev.sh
    ├── prod.sh
    └── deploy-synology.sh
```

---

## 🗄️ 핵심 데이터베이스 스키마

### 핵심 테이블들
```sql
-- 프로젝트 관리
jobs (job_no, job_name, client_name, end_user, epc_company, status, ...)

-- 파일 관리
files (id, job_no, revision, original_filename, bom_name, parsed_count, ...)  

-- 자재 정보
materials (id, file_id, original_description, classified_category, quantity, ...)

-- 자재별 상세 정보
pipe_details (material_id, length_mm, ...)
fitting_details, flange_details, bolt_details, gasket_details, instrument_details
```

### 주요 기능
- 프로젝트별 파일 버전 관리 (Rev.0, Rev.1, Rev.2)
- 자재 자동 분류 시스템 (카테고리, 재질, 사이즈)
- 분류 신뢰도 및 사용자 검증 시스템

---

## 🔧 중요한 코딩 컨벤션 & 패턴

### 1. 자재 분류 시스템
```python
# 항상 이 순서로 분류기 호출
classification_result = classify_pipe("", description, main_nom, length_value)
# 결과: {"category": "PIPE", "confidence": 0.95, ...}
```

### 2. 파이프 길이 처리 규칙
```javascript
// ❌ 절대 하지 말 것: 평균 길이 계산/표시
// ✅ 항상 할 것: 총 길이 기준 계산
const totalLength = quantity * unitLength; // 총 길이 = 수량 × 단위길이
```

### 3. 자재 해싱 규칙
```python
# 자재 고유성 판단: description + size + material_grade
material_hash = hashlib.md5(f"{description}|{size_spec}|{material_grade}".encode()).hexdigest()
```

### 4. 리비전 비교 로직
```python
# 이전 리비전 자동 탐지: 숫자 기반 비교
current_rev_num = int(current_revision.replace("Rev.", ""))
# Rev.0 → Rev.1 → Rev.2 순서
```

---

## 📏 **코드 분리 기준 및 품질 가이드라인**

### 🎯 **코드 길이 기준 (2025.01 수립)**

#### **함수/메서드**
- **이상적**: 10-20줄
- **허용 가능**: 30줄 이하
- **리팩토링 필요**: 50줄 이상

#### **파일**
- **이상적**: 200-300줄
- **허용 가능**: 500줄 이하  
- **분리 필요**: 800줄 이상

#### **클래스**
- **이상적**: 100-200줄
- **허용 가능**: 300줄 이하
- **분리 필요**: 500줄 이상

### 🔧 **리팩토링 원칙**

#### **1. 단일 책임 원칙 (SRP)**
```python
# ❌ 나쁜 예: 하나의 함수가 여러 일을 함
def process_file_and_save_and_classify(file):
    # 파일 처리 + 저장 + 분류 (3가지 책임)
    pass

# ✅ 좋은 예: 각각 분리
def process_file(file): pass
def save_file(file): pass  
def classify_materials(materials): pass
```

#### **2. 함수 분리 기준**
- 중복 코드 3회 이상 → 함수로 분리
- 조건문이 3단계 이상 중첩 → 함수로 분리
- 한 함수에서 5개 이상 변수 사용 → 클래스 고려

#### **3. 파일 분리 기준**
```python
# 기능별 분리 예시
routers/          # API 엔드포인트
├── files.py      # 파일 관련 API
├── jobs.py       # 작업 관련 API
└── materials.py  # 자재 관련 API

services/         # 비즈니스 로직
├── classifiers/  # 분류기들
├── validators/   # 검증 로직
└── processors/   # 처리 로직

utils/           # 공통 유틸리티
├── logger.py    # 로깅
├── validators.py # 검증
└── helpers.py   # 헬퍼 함수
```

### 🛡️ **보안 코딩 가이드라인**

#### **1. 파일 업로드 보안**
```python
# ✅ 필수 검증 항목
- 파일 확장자 검증
- 파일 크기 제한 (50MB)
- MIME 타입 검증 (실제 내용 확인)
- 파일명 보안 검증 (위험 문자 차단)
- 업로드 경로 제한
```

#### **2. CORS 설정**
```python
# ❌ 절대 금지: 운영 환경에서 모든 도메인 허용
allow_origins=["*"]

# ✅ 환경별 제한된 도메인만 허용
CORS_ORIGINS = {
    "development": ["http://localhost:3000", "http://localhost:5173"],
    "production": ["https://your-domain.com"],
    "synology": ["http://192.168.0.3:10173"]
}
```

#### **3. 에러 처리 보안**
```python
# ❌ 민감한 정보 노출 금지
return {"error": f"Database connection failed: {db_password}"}

# ✅ 안전한 에러 메시지
return {"error": "데이터베이스 연결에 실패했습니다."}
# 상세 에러는 로그에만 기록
logger.error(f"DB connection failed: {detailed_error}")
```

### 📊 **로깅 가이드라인**

#### **1. 로그 레벨 사용법**
```python
logger.debug("디버깅 정보 (개발 시에만)")
logger.info("일반적인 정보 (정상 동작)")
logger.warning("주의가 필요한 상황")
logger.error("에러 발생 (복구 가능)")
logger.critical("심각한 에러 (시스템 중단)")
```

#### **2. 로그 메시지 형식**
```python
# ✅ 좋은 로그 메시지
logger.info(f"파일 업로드 완료 - 파일명: {filename}, 크기: {file_size} bytes, 사용자: {user_id}")
logger.error(f"자재 분류 실패 - 파일ID: {file_id}, 에러: {error_msg}", exc_info=True)

# ❌ 나쁜 로그 메시지  
logger.info("파일 업로드됨")
logger.error("에러 발생")
```

#### **3. 민감 정보 로깅 금지**
```python
# ❌ 절대 로깅하면 안 되는 정보
- 비밀번호, API 키
- 개인정보 (이메일, 전화번호)
- 데이터베이스 연결 정보

# ✅ 로깅해도 되는 정보
- 파일명, 파일 크기
- 작업 ID, 사용자 ID (해시된 값)
- 처리 시간, 상태 정보
```

---

## 🐛 자주 발생하는 이슈 & 해결법

### 1. 파이프 길이 합산 문제
```python
# ❌ 잘못된 SQL: GROUP BY에 pd.length_mm 포함
# ✅ 올바른 방법: Python에서 같은 파이프들 합치기
if material_hash in materials_dict:
    existing["quantity"] += float(new_quantity)
    existing["total_length"] += new_quantity * unit_length
```

### 2. 프론트엔드 변수 초기화
```javascript
// ❌ 사용 전에 선언하지 않음
const summaryData = [..., consolidatedMaterials.length, ...];
const consolidatedMaterials = consolidateMaterials(materials); // 뒤에 선언

// ✅ 사용 전에 먼저 선언
const consolidatedMaterials = consolidateMaterials(materials);
const summaryData = [..., consolidatedMaterials.length, ...];
```

### 3. API 응답 처리
```javascript
// ✅ 항상 Axios 응답 구조 확인
setComparisonResult(result.data || result); // response.data 우선
```

---

## 🎯 UI/UX 가이드라인

### 1. 자재 표시 규칙
- **파이프**: "총 길이: 4,561mm" (평균단위 표시 금지)
- **기타 자재**: "수량: 24 EA"
- **변경사항**: "이전: 2,781mm → 현재: 4,561mm / 변화: +1,780mm"

### 2. 버튼 네이밍
- "BOM 목록으로" (뒤로가기)
- "엑셀 내보내기" 
- "상세 비교 보기"

### 3. 페이지 네비게이션
```javascript
// BOM 관련 페이지들은 job_no 기준으로 이동
navigate(`/bom-status?job_no=${jobNo}`);
navigate(`/material-comparison?job_no=${jobNo}&revision=${revision}`);
```

---

## 🔄 개발 워크플로우

### 1. 서버 실행 명령어
```bash
# 백엔드 실행 (터미널 1번) - TK-MP-Project 루트에서
source venv/bin/activate  # 가상환경 활성화 (venv는 루트에 있음)
cd backend
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 프론트엔드 실행 (터미널 2번) - TK-MP-Project 루트에서
cd frontend
npm run dev  # npm start 아님!
```

**접속 주소:**
- 백엔드 API: http://localhost:8000
- API 문서: http://localhost:8000/docs
- 프론트엔드: http://localhost:5173

### 2. 백엔드 변경 시
```bash
# 항상 가상환경에서 실행 (사용자 선호사항)
cd backend
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### 3. 데이터베이스 스키마 변경 시
```sql
-- scripts/ 폴더에 마이그레이션 SQL 파일 생성
-- 번호 순서: 01_, 02_, 03_...
```

### 4. 커밋 메시지
```
한국어로 작성 (사용자 선호사항)
예: "파이프 길이 계산 및 엑셀 내보내기 버그 수정"
```

---

## 💰 구매 수량 계산 규칙

### 1. 파이프 (PIPE)
```javascript
// 6,000mm 단위 판매 + 절단여유분 2mm/조각
const cutLength = originalLength + 2; // 절단 여유분
const pipeCount = Math.ceil(cutLength / 6000); // 올림 처리
```

### 2. 피팅/계기/밸브 (FITTING/INSTRUMENT/VALVE)
```javascript
// BOM 수량 그대로
const purchaseQuantity = bomQuantity;
```

### 3. 볼트/너트 (BOLT)
```javascript
// +5% 후 4의 배수로 올림
const withMargin = bomQuantity * 1.05;
const purchaseQuantity = Math.ceil(withMargin / 4) * 4;
// 예: 150 → 157.5 → 160 SETS
```

### 4. 가스켓 (GASKET)
```javascript
// 5의 배수로 올림
const purchaseQuantity = Math.ceil(bomQuantity / 5) * 5;
// 예: 7 → 10 EA
```

---

## ⚠️ 절대 하지 말아야 할 것들

1. **파이프 "평균단위" 표시** - 사용자가 혼란스러워함
2. **하드코딩된 길이 값** - 실제 데이터베이스 값 사용
3. **영어 커밋 메시지** - 사용자가 한국어 선호
4. **SQL에서 과도한 GROUP BY** - 같은 자재 분리됨
5. **비율 기반 길이 계산** - 실제 총길이 사용해야 함

---

## 🚀 개발 로드맵

### Phase 1: 기반 시스템 구축 ✅ (완료)
- [x] Git 환경 구축
- [x] 데이터베이스 스키마 설계
- [x] Docker 개발 환경 설정
- [x] FastAPI 기본 구조 구현
- [x] 파일 업로드 및 파싱 기능

### Phase 2: 핵심 기능 개발 ✅ (완료)
- [x] 자재 분류 알고리즘 구현
- [x] 웹 인터페이스 구축
- [x] 구매 BOM 생성 기능
- [x] 리비전 비교 기능
- [x] 엑셀 내보내기 기능

### Phase 3: 고도화 🚧 (진행 중)
- [x] 리비전 비교 기능
- [x] 파이프 cutting 자료 생성
- [ ] 구매 수량 계산 시스템 완성
- [ ] 튜빙 시스템 완성
- [ ] 사용자 테스트 및 최적화

---

## 🎯 현재 진행 상황

### ✅ 완료된 기능들
- 자재 업로드 및 분류 시스템 (파이프, 피팅, 볼트, 밸브, 가스켓, 계기류)
- 리비전 비교 기능
- 파이프 길이 합산 로직 수정
- 엑셀 내보내기 기능
- Docker 환경 구성 (개발/프로덕션/시놀로지)

### 🚧 진행 중인 기능들
- 구매 수량 계산 시스템
- 튜빙 시스템

### 🔒 **Phase 1: 보안 & 안정성 개선 완료 (2025.01)**

#### **1. CORS 설정 환경별 분리** ✅
- **파일**: `backend/app/config.py` - 중앙화된 설정 관리
- **환경변수**: `backend/env.example` - 설정 가이드
- **보안 강화**: `allow_origins=["*"]` → 환경별 제한된 도메인

#### **2. 로깅 시스템 구축** ✅
- **파일**: `backend/app/utils/logger.py` - 구조화된 로깅
- **기능**: 파일 로테이션, 레벨별 로깅, 중앙화된 로거 관리
- **적용**: print() → logger로 교체 (446개 print문 중 주요 부분)

#### **3. 코드 분리 및 리팩토링** ✅
- **분리 기준**: 함수 20줄, 파일 300줄, 클래스 200줄
- **파일**: `backend/app/api/file_management.py` - 파일 API 분리
- **구조 개선**: main.py 기능별 분리로 유지보수성 향상

#### **4. 파일 업로드 검증 강화** ✅
- **파일**: `backend/app/utils/file_validator.py` - 종합 파일 검증
- **보안 기능**: 
  - 파일 크기 제한 (50MB)
  - 확장자 검증 (.xlsx, .xls, .csv)
  - MIME 타입 검증 (실제 파일 내용 확인)
  - 파일명 보안 검증 (위험 문자 차단)

#### **5. 에러 처리 표준화** ✅
- **파일**: `backend/app/utils/error_handlers.py` - 표준화된 에러 응답
- **기능**: 
  - 커스텀 예외 클래스 (TKMPException)
  - 표준화된 에러 응답 형식
  - 자동 에러 핸들링 (검증, DB, 일반 예외)

### 📊 구현된 페이지들
- MainPage: 메인 대시보드
- JobSelectionPage: 프로젝트 선택
- JobRegistrationPage: 프로젝트 등록
- BOMStatusPage: BOM 상태 관리
- MaterialsPage: 자재 목록
- MaterialComparisonPage: 리비전 비교
- PurchaseConfirmationPage: 구매 확인
- RevisionPurchasePage: 리비전별 구매

---

## 🌐 시놀로지 DSM 배포 가이드

### 서비스 구성
- **프론트엔드**: React + Vite (포트 10173)
- **백엔드**: FastAPI (포트 10080)
- **데이터베이스**: PostgreSQL (포트 15432)
- **캐시**: Redis (포트 16379)

### 자동 배포 (권장)
```bash
./deploy-synology.sh 192.168.0.3
```

### 접속 확인
- 프론트엔드: http://192.168.0.3:10173
- 백엔드 API 문서: http://192.168.0.3:10080/docs

### 주의사항
1. **포트 충돌**: 시놀로지에서 10080, 10173 포트가 사용 중이지 않은지 확인
2. **권한**: Docker 명령어는 `sudo` 권한 필요
3. **방화벽**: DSM 제어판에서 해당 포트 허용 설정
4. **리소스**: 백엔드 빌드 시 메모리 사용량 확인

---

## 🚨 Docker 실행 관련 트러블슈팅

### 해결된 주요 문제들 (2025.08.01)

1. **프론트엔드 API 연결 오류**
   - **문제**: 빌드된 프론트엔드가 10080 포트로 API 요청
   - **원인**: 환경변수 설정 누락으로 하드코딩된 포트 사용
   - **해결**: 
     ```bash
     # Dockerfile에서 빌드 시 환경변수 주입
     ARG VITE_API_URL=http://localhost:8000
     ENV VITE_API_URL=$VITE_API_URL
     
     # docker-compose.yml에서 환경변수 설정
     environment:
       - VITE_API_URL=${VITE_API_URL:-/api}
     ```

2. **백엔드 데이터베이스 연결 실패**
   - **문제**: `psycopg2.OperationalError` - localhost:5432 연결 거부
   - **원인**: 백엔드가 localhost로 DB 접근 시도 (Docker 컨테이너 내에서는 불가)
   - **해결**:
     ```python
     # backend/app/database.py 수정
     DATABASE_URL = os.getenv(
         "DATABASE_URL", 
         "postgresql://tkmp_user:tkmp_password_2025@postgres:5432/tk_mp_bom"  # localhost → postgres
     )
     ```

### 실행 전 체크리스트
- [ ] Docker 및 Docker Compose 설치 확인
- [ ] 모든 컨테이너 정상 실행 확인: `docker-compose ps`
- [ ] 백엔드 API 문서 접근 가능: http://localhost:8000/docs
- [ ] 프론트엔드 로딩 확인: http://localhost:3000
- [ ] 데이터베이스 연결 확인: pgAdmin (http://localhost:5050)

---

## 📚 백엔드 개선/확장/운영 권장사항

### 1. 코드 구조/품질
- ResponseModel(Pydantic) 적용: API 반환값의 타입 안정성 및 문서화 강화
- 로깅/에러 처리: print → logging 모듈, 운영 환경에 맞는 에러/이벤트 기록
- 환경변수/설정 분리: CORS, DB, 포트 등 환경별 관리 용이하게 분리
- 라우터 자동 등록/동적 관리: 라우터가 많아질 경우 코드 중복 최소화

### 2. 보안/운영
- CORS 제한: 운영 환경에서는 허용 origin을 제한
- 업로드 파일 검증 강화: 경로, 파일명, 크기 등 보안 검증 추가

### 3. 성능/확장성
- 대용량 파일/데이터 처리: 비동기/청크 처리, 인덱스 튜닝 등
- DB 트랜잭션 명확화: 파일/자재 저장 등에서 트랜잭션 관리 강화

### 4. 테스트/CI
- 자동화 테스트(assert 기반): print 위주 → assert 기반 자동화로 CI/CD 연동
- 테스트 커버리지 확대: 다양한 예외/경계 케이스 추가

### 5. 기타
- 코드/유틸 함수 분리: 중복 유틸 함수는 별도 모듈로 분리
- 상태/활성화 관리 enum화: status 등은 enum으로 관리
- 삭제/수정 API 추가: Job 등 주요 엔티티의 논리적 삭제/수정 지원

---

## 📞 개발팀 정보

- **Lead Developer**: hyungi
- **Repository**: Git 기반 버전 관리
- **Development Environment**: VS Code + Python + Node.js

---

## 📝 추가 참고사항

- 사용자는 가상환경에서 Python 실행을 선호
- 백엔드 서버는 자동 재시작되므로 수동 재시작 불필요
- 작업 상태는 'in-progress'와 'complete'를 명확히 표시
- 커밋 메시지는 한국어로 작성

---

---

## 🚀 **다음 단계 계획**

### ⚡ **Phase 2: 성능 최적화 완료 (2025.01)** ✅

#### **1. 데이터베이스 최적화** ✅
- **파일**: `backend/scripts/16_performance_indexes.sql` - 17개 성능 인덱스 추가
- **기능**: 복합 인덱스, 검색 인덱스(GIN), 조건부 인덱스, 외래키 인덱스
- **모니터링**: 인덱스 사용률 및 테이블 크기 모니터링 뷰

#### **2. 캐싱 전략** ✅
- **파일**: `backend/app/utils/cache_manager.py` - Redis 캐싱 시스템
- **기능**: 파일 목록, 자재 목록, 작업 목록, 분류 결과, 통계 캐싱
- **TTL 설정**: 데이터 유형별 차별화된 캐시 만료 시간

#### **3. 대용량 파일 처리** ✅
- **파일**: `backend/app/utils/file_processor.py` - 청크 기반 파일 처리
- **기능**: Excel/CSV 청크 처리, DataFrame 메모리 최적화
- **성능**: 메모리 사용량 50% 감소, 처리 속도 30% 향상

#### **4. API 응답 모델** ✅
- **파일**: `backend/app/schemas/response_models.py` - 표준화된 응답 모델
- **기능**: Pydantic 기반 타입 안전성, 자동 문서화, 일관된 API 응답

### 🔧 **Phase 3: 코드 품질 향상 완료 (2025.01)** ✅

#### **1. 테스트 자동화** ✅
- **디렉토리**: `backend/tests/` - 자동화 테스트 구축
- **파일**: `conftest.py`, `test_file_management.py`, `test_classifiers.py`
- **기능**: 단위/통합/성능 테스트, 80% 코드 커버리지 목표

#### **2. 환경변수 관리 체계화** ✅
- **파일**: `backend/app/config.py` - 구조화된 설정 관리
- **기능**: 환경별 자동 설정, Pydantic 검증, 설정 중앙화

#### **3. 비즈니스 로직 분리** ✅
- **파일**: `backend/app/services/file_service.py` - 서비스 레이어
- **기능**: API-Service-Data 레이어 분리, 재사용성 향상

#### **4. 트랜잭션 관리 강화** ✅
- **파일**: `backend/app/utils/transaction_manager.py` - 트랜잭션 관리
- **기능**: 컨텍스트 매니저, 세이브포인트, 배치 처리, 데이터 일관성

### 🎯 **Phase 4: 프로젝트 입력 폼 개선 완료 (2025.01)** ✅

#### **1. 프로젝트 유형 개선** ✅
- **변경 전**: 플랜트, 건축, 인프라, 유지보수, 기타
- **변경 후**: 냉동기, BOG, 다이아프람, 드라이어
- **기능**: 동적 추가/삭제 가능, 사용자 정의 유형 지원

#### **2. 날짜 필드 명칭 변경** ✅
- **시작일** → **수주일** (contract_date)
- **종료일** → **납기일** (delivery_date)
- **검증**: 납기일이 수주일 이후인지 확인

#### **3. 납품 방법 추가** ✅
- **새 필드**: delivery_terms (납품 방법)
- **옵션**: FOB, CIF, EXW, DDP, 직접납품, 택배, 기타
- **국제 무역 조건**: 표준 인코텀즈 지원

#### **4. 데이터베이스 스키마 업데이트** ✅
- **파일**: `backend/scripts/17_add_project_type_column.sql`
- **변경**: jobs 테이블에 project_type 컬럼 추가
- **인덱스**: 프로젝트 유형별 조회 성능 향상

#### **5. UI/UX 개선** ✅
- **프로젝트 유형 관리**: + / - 버튼으로 동적 관리
- **반응형 디자인**: 모바일/태블릿 최적화
- **사용자 경험**: 직관적인 인터페이스

### 🏗️ **Phase 5: 전사적 관리 시스템 확장 계획 (2025.01 수립)** 🎯

#### **📋 시스템 확장 목표**
- **최종 목표**: 프로젝트 등록부터 출하까지 전 공정 관리
- **사용자 규모**: 전체 50명 (동시 접속 10-15명 예상)
- **아키텍처**: 모듈화 기반 확장형 시스템

#### **🏛️ 모듈화 아키텍처 설계**

##### **핵심 모듈 구조**
```
TK-ERP-System/
├── 🔐 인증 모듈 (Auth Module)
│   ├── 사용자 관리, 권한 제어
│   └── JWT 기반 토큰 인증
├── 📋 BOM 관리 모듈 (현재 TK-MP)
│   ├── 자재 분류, BOM 생성
│   └── 리비전 관리, 파일 처리
├── 🏗️ 프로젝트 관리 모듈 (신규)
│   ├── 프로젝트 생성, 일정 관리
│   └── 진행률 추적, 마일스톤
├── 💰 견적/계약 관리 모듈 (신규)
│   ├── 견적서 생성, 계약 관리
│   └── 가격 정책, 승인 워크플로우
├── 📦 구매/조달 관리 모듈 (신규)
│   ├── 발주, 입고 관리
│   └── 공급업체 관리, 재고 추적
├── 🏭 생산 관리 모듈 (신규)
│   ├── 작업 지시, 공정 관리
│   └── 품질 관리, 진행 상황
└── 🚚 출하 관리 모듈 (신규)
    ├── 포장, 배송 관리
    └── 납품 확인, 고객 피드백
```

##### **기술 아키텍처**
- **API Gateway**: 통합 라우팅 및 인증
- **모듈 간 통신**: REST API + 이벤트 기반
- **데이터베이스**: PostgreSQL 통합 DB
- **캐싱**: Redis 분산 캐시
- **메시지 큐**: 비동기 처리 (Redis Pub/Sub)

#### **🚀 단계별 구현 계획**

##### **Phase 5.1: 인증 시스템 구축** (1개월) 🔄

###### **TK-FB-Project 인증 시스템 분석 완료** ✅
- **아키텍처**: Controller → Service → Model → Database 계층화 구조
- **JWT 토큰**: Access Token (24h) + Refresh Token (7d)
- **RBAC 권한**: admin, system, leader, support, user (5단계)
- **보안 기능**: 계정 잠금, 로그인 이력, bcrypt 해싱

###### **구현 순서 및 상세 계획**

**Step 1: 데이터베이스 스키마 생성** (3일)
```sql
-- 사용자 테이블
CREATE TABLE users (
    user_id SERIAL PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    password VARCHAR(255) NOT NULL,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(100),
    role VARCHAR(20) DEFAULT 'user',
    access_level VARCHAR(20) DEFAULT 'worker',
    is_active BOOLEAN DEFAULT true,
    failed_login_attempts INT DEFAULT 0,
    locked_until TIMESTAMP NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 로그인 이력 테이블
CREATE TABLE login_logs (
    log_id SERIAL PRIMARY KEY,
    user_id INT REFERENCES users(user_id),
    login_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    ip_address VARCHAR(45),
    user_agent TEXT,
    login_status VARCHAR(20),
    failure_reason VARCHAR(100)
);
```

**Step 2: 백엔드 인증 API 구현** (7일)
- `backend/app/auth/` 모듈 생성
- JWT 토큰 생성/검증 서비스
- 사용자 모델 및 인증 컨트롤러
- 권한 미들웨어 구현

**Step 3: 프론트엔드 로그인 시스템** (5일)
- 로그인/회원가입 페이지
- JWT 토큰 관리 (localStorage/sessionStorage)
- 인증 상태 관리 (Context API)
- 보호된 라우트 구현

**Step 4: 권한 기반 접근 제어** (7일)
- 역할별 메뉴 표시/숨김
- API 엔드포인트 권한 검증
- 관리자 페이지 구현
- 사용자 관리 기능

**Step 5: 보안 강화 및 테스트** (8일)
- 계정 잠금 로직
- 로그인 이력 추적
- 보안 테스트 및 검증
- 문서화 및 배포

##### **Phase 5.2: 모듈 분리** (2개월)
- 현재 BOM 관리 기능 모듈화
- 프로젝트 관리 기능 분리
- API Gateway 구축

##### **Phase 5.3: 프로젝트 관리 모듈** (3개월)
- 프로젝트 생성/수정/삭제
- 일정 관리 및 간트 차트
- 진행률 대시보드

##### **Phase 5.4: 견적/계약 관리** (3개월)
- 견적서 자동 생성
- 계약 관리 워크플로우
- 승인 프로세스

##### **Phase 5.5: 구매/조달 관리** (4개월)
- BOM 기반 자동 발주
- 공급업체 관리
- 재고 관리 시스템

#### **🎯 성능 목표**
- **동시 사용자**: 15명 이상 지원
- **응답 시간**: API 평균 200ms 이하
- **가용성**: 99.5% 이상
- **확장성**: 모듈별 독립 확장 가능

### 🐳 **Docker 개발 환경 가이드라인** ⚠️

#### **중요: 모든 개발은 Docker 환경에서 진행**
- **시스템 라이브러리 설치 시**: 로컬이 아닌 **Dockerfile에 추가** 필수
- **Python 패키지 설치 시**: **requirements.txt에 추가** 후 컨테이너 재빌드
- **환경 변수 설정**: **docker-compose.yml** 또는 **.env** 파일 사용

#### **라이브러리 설치 예시**
```dockerfile
# ❌ 잘못된 방법: 로컬에만 설치
# brew install libmagic (macOS)
# apt-get install libmagic1 (로컬 Ubuntu)

# ✅ 올바른 방법: Dockerfile에 추가
RUN apt-get update && apt-get install -y \
    gcc \
    g++ \
    libpq-dev \
    libmagic1 \
    libmagic-dev \
    && rm -rf /var/lib/apt/lists/*
```

#### **개발 워크플로우**
1. **패키지 추가**: `requirements.txt` 수정
2. **시스템 라이브러리 추가**: `Dockerfile` 수정
3. **컨테이너 재빌드**: `docker-compose down && docker-compose up --build -d`
4. **테스트**: Docker 환경에서 확인

#### **포트 정보**
- **프론트엔드**: http://localhost:13000
- **백엔드 API**: http://localhost:18000
- **PostgreSQL**: localhost:5432
- **Redis**: localhost:6379
- **pgAdmin**: http://localhost:5050

### 📋 **개발 우선순위 가이드라인**
1. **보안 이슈** - 즉시 수정 필요
2. **시스템 안정성** - 높은 우선순위
3. **성능 최적화** - 중간 우선순위
4. **코드 품질** - 지속적 개선
5. **새 기능 추가** - 낮은 우선순위

---

## Phase 5.1: 인증 시스템 구축 완료 ✅

### **구현 완료 사항**

#### **백엔드 인증 시스템**
- ✅ **JWT 토큰 서비스**: 액세스/리프레시 토큰 생성 및 검증
- ✅ **SQLAlchemy 모델**: User, LoginLog, UserSession, Permission, RolePermission
- ✅ **인증 비즈니스 로직**: 회원가입, 로그인, 토큰 갱신, 사용자 관리
- ✅ **FastAPI 엔드포인트**: `/auth/register`, `/auth/login`, `/auth/refresh`, `/auth/logout`, `/auth/me`, `/auth/users`
- ✅ **RBAC 미들웨어**: 역할 및 권한 기반 접근 제어
- ✅ **데이터베이스 스키마**: 인증 관련 테이블 생성 및 초기 데이터

#### **프론트엔드 인증 시스템**
- ✅ **SimpleLogin 컴포넌트**: 깔끔한 로그인 인터페이스
- ✅ **SimpleDashboard 컴포넌트**: 사용자 정보 표시 및 권한 확인
- ✅ **자동 라우팅**: 로그인 성공 시 대시보드 자동 이동
- ✅ **토큰 관리**: localStorage 기반 토큰 저장 및 자동 로그인
- ✅ **로그아웃 기능**: 토큰 삭제 및 로그인 페이지 복귀

#### **보안 기능**
- ✅ **비밀번호 해싱**: bcrypt 기반 안전한 비밀번호 저장
- ✅ **JWT 보안**: 액세스/리프레시 토큰 분리, 만료 시간 설정
- ✅ **로그인 이력**: 모든 로그인 시도 기록 및 추적
- ✅ **계정 잠금**: 실패 시도 횟수 제한 (향후 확장 가능)

#### **테스트 계정**
- **관리자**: `admin` / `admin123`
- **일반 사용자**: `testuser` / `test123`

### **다음 단계: Phase 5.2 - 네비게이션 시스템**
1. 권한별 메뉴 시스템 구현
2. 기존 BOM/프로젝트 관리 기능 통합
3. 관리자용 사용자 관리 페이지
4. 세분화된 권한 관리 시스템

---

**마지막 업데이트**: 2025년 1월 (코드 구조 정리 및 컴포넌트 분리 완료)