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 의존성

🔄 컴포넌트 관계도

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 필터)

📊 데이터 흐름도

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: 자재 목록 반환

🔐 권한 체계

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)

실행 방법

# 개발 환경
./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

---

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

핵심 테이블들

-- 프로젝트 관리
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. 자재 분류 시스템

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

2. 파이프 길이 처리 규칙

// ❌ 절대 하지 말 것: 평균 길이 계산/표시
// ✅ 항상 할 것: 총 길이 기준 계산
const totalLength = quantity * unitLength; // 총 길이 = 수량 × 단위길이

3. 자재 해싱 규칙

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

4. 리비전 비교 로직

# 이전 리비전 자동 탐지: 숫자 기반 비교
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)

# ❌ 나쁜 예: 하나의 함수가 여러 일을 함
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. 파일 분리 기준

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

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

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

🛡️ 보안 코딩 가이드라인

1. 파일 업로드 보안

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

2. CORS 설정

# ❌ 절대 금지: 운영 환경에서 모든 도메인 허용
allow_origins=["*"]

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

3. 에러 처리 보안

# ❌ 민감한 정보 노출 금지
return {"error": f"Database connection failed: {db_password}"}

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

📊 로깅 가이드라인

1. 로그 레벨 사용법

logger.debug("디버깅 정보 (개발 시에만)")
logger.info("일반적인 정보 (정상 동작)")
logger.warning("주의가 필요한 상황")
logger.error("에러 발생 (복구 가능)")
logger.critical("심각한 에러 (시스템 중단)")

2. 로그 메시지 형식

# ✅ 좋은 로그 메시지
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. 민감 정보 로깅 금지

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

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

---

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

1. 파이프 길이 합산 문제

# ❌ 잘못된 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. 프론트엔드 변수 초기화

// ❌ 사용 전에 선언하지 않음
const summaryData = [..., consolidatedMaterials.length, ...];
const consolidatedMaterials = consolidateMaterials(materials); // 뒤에 선언

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

3. API 응답 처리

// ✅ 항상 Axios 응답 구조 확인
setComparisonResult(result.data || result); // response.data 우선

---

🎯 UI/UX 가이드라인

1. 자재 표시 규칙

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

2. 버튼 네이밍

• "BOM 목록으로" (뒤로가기)
• "엑셀 내보내기"
• "상세 비교 보기"

3. 페이지 네비게이션

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

---

🔄 개발 워크플로우

1. 서버 실행 명령어

# 백엔드 실행 (터미널 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. 백엔드 변경 시

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

3. 데이터베이스 스키마 변경 시

-- scripts/ 폴더에 마이그레이션 SQL 파일 생성
-- 번호 순서: 01_, 02_, 03_...

4. 커밋 메시지

한국어로 작성 (사용자 선호사항)
예: "파이프 길이 계산 및 엑셀 내보내기 버그 수정"

---

💰 구매 수량 계산 규칙

1. 파이프 (PIPE)

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

2. 피팅/계기/밸브 (FITTING/INSTRUMENT/VALVE)

// BOM 수량 그대로
const purchaseQuantity = bomQuantity;

3. 볼트/너트 (BOLT)

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

4. 가스켓 (GASKET)

// 5의 배수로 올림
const purchaseQuantity = Math.ceil(bomQuantity / 5) * 5;
// 예: 7 → 10 EA

---

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

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

---

🚀 개발 로드맵

Phase 1: 기반 시스템 구축 ✅ (완료)

• Git 환경 구축
• 데이터베이스 스키마 설계
• Docker 개발 환경 설정
• FastAPI 기본 구조 구현
• 파일 업로드 및 파싱 기능

Phase 2: 핵심 기능 개발 ✅ (완료)

• 자재 분류 알고리즘 구현
• 웹 인터페이스 구축
• 구매 BOM 생성 기능
• 리비전 비교 기능
• 엑셀 내보내기 기능

Phase 3: 고도화 🚧 (진행 중)

• 리비전 비교 기능
• 파이프 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)

자동 배포 (권장)

./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 요청
   • 원인: 환경변수 설정 누락으로 하드코딩된 포트 사용
   • 해결:

     # 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 컨테이너 내에서는 불가)
   • 해결:

     # 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일)

-- 사용자 테이블
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 파일 사용

라이브러리 설치 예시

# ❌ 잘못된 방법: 로컬에만 설치
# 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월 (코드 구조 정리 및 컴포넌트 분리 완료)