Files

SonarQube Analysis / SonarQube Scan (push) Has been cancelled

Details

- 파이프 수량 계산 로직 수정 (단관 개수가 아닌 실제 길이 기반 계산)
- UI 전면 개편 (DevonThink 스타일의 간결하고 세련된 디자인)
- 자재별 그룹핑 로직 개선:
  * 플랜지: 동일 사양별 그룹핑, WN 스케줄 표시, ORIFICE 풀네임 표시
  * 피팅: 상세 타입 표시 (니플 길이, 엘보 각도/연결, 티 타입, 리듀서 타입 등)
  * 밸브: 동일 사양별 그룹핑, 타입/연결방식/압력 표시
  * 볼트: 크기/재질/길이별 그룹핑 (8SET → 개별 집계)
  * 가스켓: 동일 사양별 그룹핑, 재질/상세내역/두께 분리 표시
  * UNKNOWN: 원본 설명 전체 표시, 동일 항목 그룹핑
- 전체 카테고리 버튼 제거 (표시 복잡도 감소)
- 카테고리별 동적 컬럼 헤더 및 레이아웃 적용

2025-09-09 09:24:45 +09:00

67 KiB

Raw Blame History

🚀 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      # 사이드바 네비게이션 (권한 기반)
│   ├── PersonalizedDashboard.jsx # 개인화된 대시보드 (역할별 맞춤)
│   ├── ProjectSelector.jsx     # 프로젝트 선택 드롭다운 (검색 기능)
│   ├── BOMFileUpload.jsx       # BOM 파일 업로드 폼
│   ├── BOMFileTable.jsx        # BOM 파일 목록 테이블
│   └── RevisionUploadDialog.jsx # 리비전 업로드 다이얼로그
└── pages/                      # 페이지 컴포넌트
    ├── DashboardPage.jsx       # 대시보드 (기존)
    ├── ProjectWorkspacePage.jsx # 프로젝트별 워크스페이스 (신규)
    ├── BOMUploadPage.jsx       # BOM 업로드 페이지 (신규)
    ├── 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 엔드포인트 전체 맵 (2025.01 최신)

중요: 새로운 API 추가 시 반드시 이 섹션을 업데이트하고, 버전 관리 및 하위 호환성을 고려해야 합니다.

📋 API 문서화 규칙

새 API 추가 시: 이 문서에 즉시 반영
API 변경 시: 변경 이력과 마이그레이션 가이드 포함
권한 표시: 각 엔드포인트별 필요 권한 명시
응답 형식: 표준 응답 구조 준수

🚨 API 사용 가이드라인 (혼동 방지) ⭐ 중요

1. 자재 관련 API 통합 사용법

// ✅ 올바른 사용법 - 통합된 API 사용
import { fetchMaterials } from '../api';

// 파일별 자재 조회
const materials = await fetchMaterials({ file_id: 123, limit: 1000 });

// 프로젝트별 자재 조회  
const materials = await fetchMaterials({ job_no: 'J24-001', limit: 1000 });

// 리비전별 자재 조회
const materials = await fetchMaterials({ 
  job_no: 'J24-001', 
  revision: 'Rev.1', 
  limit: 1000 
});

// ❌ 잘못된 사용법 - 직접 API 호출 금지
const response = await api.get('/files/materials-v2', { params });  // 금지
const response = await api.get('/files/materials', { params });     // 존재하지 않음

2. API 함수 vs 직접 호출 규칙

// ✅ 권장: api.js의 래퍼 함수 사용
import { fetchMaterials, fetchFiles, fetchJobs } from '../api';

// ❌ 비권장: 직접 API 호출 (특별한 경우에만)
const response = await api.get('/files/materials-v2');

3. 백엔드 API 엔드포인트 명명 규칙

기본 형태: /{모듈}/{리소스}
버전 관리: /{모듈}/{리소스}-v2 (하위 호환성 유지)
액션 기반: /{모듈}/{리소스}/{액션}

예시:

/files/materials-v2          # 자재 목록 (최신 버전)
/files/materials/summary     # 자재 요약 통계
/files/materials/compare-revisions  # 리비전 비교
/purchase/items/calculate    # 구매 수량 계산
/materials/compare-revisions # 자재 비교 (별도 모듈)

4. 프론트엔드 API 호출 표준화

// api.js - 모든 API 함수는 여기에 정의
export function fetchMaterials(params) {
  return api.get('/files/materials-v2', { params });
}

export function fetchFiles(params) {
  return api.get('/files', { params });
}

export function fetchJobs(params) {
  return api.get('/jobs/', { params });
}

// 컴포넌트에서 사용
import { fetchMaterials } from '../api';
const response = await fetchMaterials({ job_no: 'J24-001' });

🔐 인증 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}     # 사용자 수정 (관리자)
DELETE /auth/users/{id}     # 사용자 삭제 (관리자)

📋 프로젝트 관리 API (`/jobs/`)

GET    /jobs/               # 프로젝트 목록 (사용자)
POST   /jobs/               # 프로젝트 생성 (매니저+)
GET    /jobs/{id}           # 프로젝트 상세 (사용자)
PUT    /jobs/{id}           # 프로젝트 수정 (매니저+)
DELETE /jobs/{id}           # 프로젝트 삭제 (관리자)
GET    /jobs/stats          # 프로젝트 통계 (매니저+)
POST   /jobs/{id}/assign    # 담당자 할당 (매니저+)

실제 응답 구조:

// GET /jobs/ - 프로젝트 목록
{
  "success": true,
  "total_count": 2,
  "jobs": [
    {
      "job_no": "J24-001",
      "job_name": "울산 SK에너지 정유시설 증설 배관공사",
      "project_name": "울산 SK에너지 정유시설 증설 배관공사",
      "client_name": "삼성엔지니어링",
      "end_user": "SK에너지",
      "epc_company": "삼성엔지니어링",
      "project_site": "울산광역시 온산공단",
      "contract_date": "2024-03-15",
      "delivery_date": "2024-08-30",
      "delivery_terms": "FOB 울산항",
      "project_type": "냉동기",
      "status": "진행중",
      "description": "정유시설 증설을 위한 배관 자재 공급",
      "created_at": "2025-07-15T03:44:46.035325"
    }
  ]
}

📄 파일/자재 관리 API (`/files/`)

GET    /files                        # 파일 목록 (사용자)
POST   /files/upload                 # 파일 업로드 (설계자+) ⭐ 사용자 추적
DELETE /files/delete/{file_id}       # 파일 삭제 (설계자+)
GET    /files/stats                  # 파일/자재 통계 (사용자)
GET    /files/materials-v2           # 자재 목록 (사용자) ⭐ 최신 버전
GET    /files/materials/summary      # 자재 요약 통계 (사용자)
GET    /files/materials/compare-revisions  # 리비전 비교 (사용자)
GET    /files/pipe-details           # 파이프 상세 정보 (사용자)
GET    /files/fitting-details        # 피팅 상세 정보 (사용자)
GET    /files/valve-details          # 밸브 상세 정보 (사용자)
POST   /files/user-requirements      # 사용자 요구사항 생성 (사용자)
GET    /files/user-requirements      # 사용자 요구사항 조회 (사용자)
POST   /files/materials/{id}/verify  # 자재 분류 검증 (설계자+)
PUT    /files/materials/{id}/update-classification  # 자재 분류 수정 (설계자+)
POST   /files/materials/confirm-purchase  # 자재 구매 확정 (구매자+)

⚠️ 중요: 자재 API 사용 시 주의사항

✅ 사용: /files/materials-v2 (최신 버전, 모든 기능 지원)
❌ 사용 금지: /files/materials (존재하지 않음, 404 오류 발생)
🔄 마이그레이션: 모든 컴포넌트에서 fetchMaterials() 함수 사용 권장

🔧 자재 분류/비교 API (`/materials/`)

POST   /materials/compare-revisions    # 리비전 비교 (설계자+) ⭐ 사용자 추적
GET    /materials/comparison-history   # 비교 이력 조회 (사용자)
GET    /materials/inventory-status     # 재고 현황 (구매자+)
POST   /materials/confirm-purchase     # 구매 확정 (구매자+) ⭐ 사용자 추적
GET    /materials/purchase-status      # 구매 상태 (구매자+)

🛒 구매 관리 API (`/purchase/`)

GET    /purchase/items/calculate   # 구매 품목 계산 (구매자+)
POST   /purchase/confirm          # 구매 수량 확정 (구매자+) ⭐ 사용자 추적
POST   /purchase/items/save       # 구매 품목 저장 (구매자+)
GET    /purchase/items            # 구매 품목 목록 (구매자+)
GET    /purchase/revision-diff    # 리비전 차이 (구매자+)
POST   /purchase/orders/create    # 구매 주문 생성 (구매자+) ⭐ 사용자 추적
GET    /purchase/orders           # 구매 주문 목록 (구매자+)

📊 대시보드 API (`/dashboard/`) ⭐ 신규 (2025.01)

GET    /dashboard/stats           # 사용자별 맞춤 통계 (인증 필요)
GET    /dashboard/activities      # 사용자 활동 이력 (인증 필요)
GET    /dashboard/recent-activities  # 전체 최근 활동 (매니저+)
GET    /dashboard/quick-actions   # 역할별 빠른 작업 (인증 필요)

실제 응답 구조:

// GET /dashboard/stats - 사용자별 맞춤 통계
{
  "success": true,
  "user_role": "admin",
  "stats": {
    "total_projects": 45,
    "active_users": 12,
    "system_status": "정상",
    "today_uploads": 8
    // 주의: quickActions, metrics 등은 프론트엔드에서 목 데이터로 보완됨
  }
}

// GET /dashboard/activities - 사용자 활동 이력
{
  "success": true,
  "activities": [
    {
      "id": 1,
      "activity_type": "FILE_UPLOAD",
      "activity_description": "파일 업로드: ProjectX_Rev0.xlsx",
      "created_at": "2025-08-30T08:30:00Z",
      "target_id": 123,
      "target_type": "FILE"
    }
  ]
}

🔧 튜빙 시스템 API (`/tubing/`)

GET    /tubing/categories         # 튜빙 카테고리 (사용자)
GET    /tubing/manufacturers      # 제조사 목록 (사용자)
GET    /tubing/specifications     # 사양 목록 (사용자)
GET    /tubing/products          # 튜빙 제품 목록 (사용자)
POST   /tubing/products          # 튜빙 제품 생성 (설계자+)
POST   /tubing/material-mapping  # 자재-튜빙 매핑 생성 (설계자+)
GET    /tubing/material-mappings/{material_id}  # 자재별 튜빙 매핑 조회 (사용자)
GET    /tubing/search            # 튜빙 제품 검색 (사용자)

📝 API 개발 가이드라인 (2025.01 신규)

1. 새 API 모듈 추가 절차

# 1. 라우터 파일 생성
# backend/app/routers/new_module.py

from fastapi import APIRouter, Depends, HTTPException
from ..auth.middleware import get_current_user
from ..services.activity_logger import log_activity_from_request

router = APIRouter(prefix="/new-module", tags=["new-module"])

@router.post("/action")
async def new_action(
    request: Request,
    current_user: dict = Depends(get_current_user),
    db: Session = Depends(get_db)
):
    # 사용자 추적 필수
    log_activity_from_request(
        db, request, current_user['username'],
        "NEW_ACTION", "새 액션 실행"
    )
    # 비즈니스 로직...

# 2. main.py에 라우터 등록
try:
    from .routers import new_module
    app.include_router(new_module.router, tags=["new-module"])
except ImportError:
    logger.warning("new_module 라우터를 찾을 수 없습니다")

# 3. RULES.md 업데이트 (이 문서)
#### **🆕 새 모듈 API (`/new-module/`)**
GET    /new-module/list     # 목록 조회 (사용자)
POST   /new-module/action   # 액션 실행 (권한) ⭐ 사용자 추적

2. API 응답 표준 형식

// 성공 응답
{
  "success": true,
  "message": "작업이 완료되었습니다",
  "data": { ... },
  "timestamp": "2025-01-XX 12:00:00"
}

// 에러 응답
{
  "success": false,
  "error": "에러 메시지",
  "error_code": "ERROR_CODE",
  "detail": "상세 에러 정보"
}

2-1. 실제 응답 구조 문서화 규칙 ⭐ 중요

모든 API는 실제 응답 구조를 RULES.md에 명시 필수
프론트엔드 개발 시 참조할 수 있도록 JSON 예시 포함
필드명, 데이터 타입, 중첩 구조 모두 정확히 기록
목 데이터 사용 시 주석으로 명시
API 변경 시 문서도 즉시 업데이트

문서화 예시:

// GET /jobs/ - 프로젝트 목록 (실제 응답)
{
  "success": true,
  "total_count": 2,
  "jobs": [
    {
      "job_no": "J24-001",
      "project_name": "프로젝트명",
      "status": "진행중",
      "client_name": "고객사명"
      // ... 모든 필드 명시
    }
  ]
}

3. 권한 레벨 정의

공개: 인증 불필요
사용자: 로그인한 모든 사용자
설계자+: designer, manager, admin
구매자+: purchaser, manager, admin
매니저+: manager, admin
관리자: admin만

4. 사용자 추적 필수 API ⭐

다음 작업은 반드시 활동 로그를 기록해야 함:

파일 업로드/삭제
프로젝트 생성/수정/삭제
구매 확정/주문 생성
자재 분류/검증
시스템 설정 변경

5. API 버전 관리

# 현재 버전 (기본)
GET /files/upload

# 새 버전 (하위 호환성 유지)
GET /v2/files/upload

# 헤더 기반 버전 관리
GET /files/upload
Accept: application/vnd.tkmp.v2+json

6. 성능 고려사항

페이지네이션: 목록 API는 limit/offset 지원
필터링: 쿼리 파라미터로 필터 조건 제공
캐싱: 자주 조회되는 데이터는 Redis 캐싱
비동기 처리: 대용량 파일 처리는 백그라운드 작업

🔄 API 변경 이력 (2025.01)

v2.2.0 (2025.09.05) ⭐ 최신

✅ 정리: API 엔드포인트 표준화 및 통합
✅ 문서화: 전체 API 맵 업데이트 (실제 구현 기준)
✅ 개선: 프론트엔드 API 호출 표준화 (fetchMaterials 함수 사용)
✅ 수정: /files/materials → /files/materials-v2 마이그레이션 완료
✅ 추가: API 사용 가이드라인 및 혼동 방지 규칙
✅ 추가: 튜빙 시스템 API 문서화

v2.1.1 (2025.08.30)

✅ 문서화: /jobs/ API 실제 응답 구조 명시
✅ 문서화: /dashboard/ API 실제 응답 구조 명시
✅ 개선: 프론트엔드-백엔드 API 응답 구조 불일치 해결
✅ 추가: 실제 응답 구조 문서화 규칙 및 가이드라인

v2.1.0 (2025.01.XX)

✅ 추가: /dashboard/ API 모듈 (사용자별 맞춤 대시보드)
✅ 개선: 모든 업로드/수정 API에 사용자 추적 추가
✅ 변경: /files/upload - uploaded_by 필드 필수화
⚠️ 중단 예정: /old-endpoint (v3.0에서 제거 예정)

v2.0.0 (2025.01.XX)

✅ 추가: 인증 시스템 (/auth/) 완전 구현
✅ 추가: 사용자 활동 로그 시스템
✅ 변경: 모든 API에 JWT 토큰 인증 적용
🔄 마이그레이션: 기존 API 호출 시 Authorization 헤더 필수

📋 개발자 체크리스트

새 API 개발 시 다음 사항을 확인:

문서화: RULES.md API 맵에 추가
인증: 적절한 권한 레벨 설정
추적: 중요 작업은 활동 로그 기록
검증: 입력 데이터 검증 (Pydantic)
에러: 표준 에러 응답 형식 준수
테스트: 단위/통합 테스트 작성
로깅: 적절한 로그 레벨로 기록
성능: 대용량 데이터 처리 고려

📊 데이터 흐름도

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. 리비전 비교 로직 (2025.01 신규 ⭐)

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

# 자재 해싱 규칙 (RULES 준수)
material_hash = hashlib.md5(f"{description}|{size}|{material}".encode()).hexdigest()

# 리비전 비교 워크플로우
if revision != "Rev.0":  # 리비전 업로드인 경우만
    revision_comparison = get_revision_comparison(db, job_no, revision, materials_data)
    
    if revision_comparison.get("has_previous_confirmation"):
        # 변경없음: 기존 분류 결과 재사용 (confidence = 1.0)
        # 변경됨 + 신규: 재분류 필요
        materials_to_classify = changed_materials + new_materials
    else:
        # 이전 확정 자료 없음: 전체 분류
        materials_to_classify = all_materials

5. 구매 수량 확정 워크플로우 (2025.01 신규 ⭐)

# 확정 데이터 저장 구조
purchase_confirmations (마스터) → confirmed_purchase_items (상세)

# 확정 시 파일 상태 업데이트
files.purchase_confirmed = TRUE
files.confirmed_at = timestamp
files.confirmed_by = username

# 리비전 업로드 시 최적화
- 확정된 자료 있음: 변경된 자재만 분류 (성능 향상)
- 확정된 자료 없음: 전체 자재 분류 (기존 방식)

6. 대용량 데이터 처리 규칙 (2025.01 신규 ⭐)

# 413 오류 방지: 요청 데이터 최적화
# ❌ 전체 데이터 전송 (용량 초과)
purchase_items: List[dict]  # 모든 필드 포함

# ✅ 필수 필드만 전송 (용량 최적화)
class PurchaseItemMinimal(BaseModel):
    item_code: str
    category: str
    specification: str
    size: str = ""
    material: str = ""
    bom_quantity: float
    calculated_qty: float
    unit: str = "EA"
    safety_factor: float = 1.0

# 서버 요청 크기 제한 설정
app.add_middleware(RequestSizeLimitMiddleware, max_request_size=100 * 1024 * 1024)  # 100MB

# Nginx 프록시 설정 (중요!)
server {
    client_max_body_size 100M;  # 전역 설정
    
    location /api/ {
        proxy_pass http://backend:8000/;
        client_max_body_size 100M;  # API 경로별 설정
        proxy_request_buffering off;  # 대용량 요청 최적화
    }
}

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

🎯 코드 길이 기준 (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}`);

4. 프로젝트 중심 워크플로우 (2025.01 신규) ⭐

기본 원칙

프로젝트 우선: 사용자는 먼저 프로젝트를 선택하고, 그 다음에 업무를 선택
컨텍스트 유지: 선택된 프로젝트 정보는 모든 하위 페이지에서 유지
권한 기반 메뉴: 사용자 역할에 따라 사용 가능한 업무만 표시

워크플로우 구조

메인 대시보드 → 프로젝트 선택 → 프로젝트 워크스페이스 → 업무 진행

주요 컴포넌트

1. ProjectSelector (프로젝트 선택기)

드롭다운 형태의 프로젝트 선택 UI
검색 기능 지원 (프로젝트명, Job 번호)
진행률 표시 및 상태 표시
선택된 프로젝트 정보 하이라이트

2. ProjectWorkspacePage (프로젝트 워크스페이스)

프로젝트별 맞춤 대시보드
권한 기반 업무 메뉴 (카드 형태)
프로젝트 통계 및 최근 활동 표시
빠른 작업 버튼

3. 권한별 업무 메뉴

// 설계자 업무
- BOM 파일 업로드
- BOM 관리
- 자재 분류 검증

// 구매자 업무  
- 구매 관리
- 리비전 비교
- 구매 확정

// 공통 업무
- 프로젝트 현황
- 리포트 생성

사용자 경험 개선사항

직관적 흐름: 실제 업무 흐름과 일치하는 네비게이션
컨텍스트 인식: 프로젝트 정보가 자동으로 전달됨
효율성 증대: 불필요한 프로젝트 선택 단계 제거
시각적 피드백: 선택된 프로젝트와 진행률 시각화

🔄 개발 워크플로우

⭐ 1. 도커 실행 (권장 - 프로덕션 환경과 동일)

# TK-MP-Project 루트 디렉토리에서 실행
docker-compose up -d

# 로그 확인
docker-compose logs -f

# 서비스 재시작 (코드 변경 시)
docker-compose restart

# 완전 재빌드 (Dockerfile 변경 시)
docker-compose down
docker-compose up --build -d

도커 접속 주소:

프론트엔드: http://localhost:13000
백엔드 API: http://localhost:18000
API 문서: http://localhost:18000/docs
PostgreSQL: localhost:5432
Redis: localhost:6379
pgAdmin: http://localhost:5050

2. 로컬 개발 실행 (개발/디버깅 전용)

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

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

로컬 개발 접속 주소:

백엔드 API: http://localhost:18000
API 문서: http://localhost:18000/docs
프론트엔드: http://localhost:13000 (포트 충돌 시 자동 변경됨)

3. 백엔드 변경 시

# 도커 환경 (권장)
docker-compose restart backend

# 로컬 환경 (디버깅용)
cd backend
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 18000

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

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

4. 커밋 메시지

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

⚠️ 중요: 개발 환경 선택 가이드

🐳 도커 환경 (권장)

사용 시기: 일반적인 개발, 테스트, 프로덕션 배포
장점: 환경 일관성, NAS 배포와 동일한 환경
단점: 디버깅이 약간 복잡

💻 로컬 환경 (제한적 사용)

사용 시기: 백엔드 디버깅, 새로운 패키지 테스트
장점: 빠른 디버깅, IDE 통합
단점: 환경 차이로 인한 배포 문제 가능성

💰 구매 수량 계산 규칙

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

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

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

🚀 개발 로드맵

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: 리비전별 구매

🌐 시놀로지 NAS 배포 가이드 ⭐

🐳 도커 기반 배포 (권장)

서비스 구성

프론트엔드: React + Nginx (포트 13000)
백엔드: FastAPI + Uvicorn (포트 18000)
데이터베이스: PostgreSQL (포트 5432)
캐시: Redis (포트 6379)
관리도구: pgAdmin4 (포트 5050)

배포 명령어

# 1. 프로젝트 파일을 NAS로 복사
scp -r TK-MP-Project/ admin@[NAS_IP]:/volume1/docker/

# 2. NAS SSH 접속
ssh admin@[NAS_IP]

# 3. 프로젝트 디렉토리로 이동
cd /volume1/docker/TK-MP-Project/

# 4. 도커 컴포즈 실행
docker-compose up -d

# 5. 서비스 상태 확인
docker-compose ps

접속 주소 (NAS IP 기준)

프론트엔드: http://[NAS_IP]:13000
백엔드 API: http://[NAS_IP]:18000
API 문서: http://[NAS_IP]:18000/docs
pgAdmin: http://[NAS_IP]:5050

자동 배포 스크립트 (곧 구현 예정)

./deploy-synology.sh [NAS_IP]

주의사항

포트 충돌: NAS에서 13000, 18000 포트가 사용 중이지 않은지 확인
권한: Docker 명령어는 sudo 권한 필요
방화벽: DSM 제어판에서 해당 포트 허용 설정
리소스: 백엔드 빌드 시 메모리 사용량 확인

🚨 Docker 실행 관련 트러블슈팅

해결된 주요 문제들 (2025.08.01)

프론트엔드 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}

백엔드 데이터베이스 연결 실패
- 문제: 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/*

개발 워크플로우

패키지 추가: requirements.txt 수정
시스템 라이브러리 추가: Dockerfile 수정
컨테이너 재빌드: docker-compose down && docker-compose up --build -d
테스트: Docker 환경에서 확인

포트 정보

프론트엔드: http://localhost:13000
백엔드 API: http://localhost:18000
PostgreSQL: localhost:5432
Redis: localhost:6379
pgAdmin: http://localhost:5050

📋 개발 우선순위 가이드라인

보안 이슈 - 즉시 수정 필요
시스템 안정성 - 높은 우선순위
성능 최적화 - 중간 우선순위
코드 품질 - 지속적 개선
새 기능 추가 - 낮은 우선순위

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 - 네비게이션 시스템

권한별 메뉴 시스템 구현
기존 BOM/프로젝트 관리 기능 통합
관리자용 사용자 관리 페이지
세분화된 권한 관리 시스템

📊 사용자 추적 및 담당자 기록 가이드라인 (2025.01 신규)

🎯 기본 원칙

모든 업무 활동은 담당자가 기록되어야 함
추적 가능한 업무 이력 관리
개인별 맞춤형 대시보드 제공
권한별 차별화된 정보 표시

📋 필수 기록 대상

1. 파일 관리

-- 파일 업로드 시 필수 기록
uploaded_by VARCHAR(100) NOT NULL,        -- 업로드한 사용자
upload_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_by VARCHAR(100),                  -- 수정한 사용자 (파일 수정 시)
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP

2. 프로젝트 관리

-- 프로젝트 생성/수정 시 필수 기록
created_by VARCHAR(100) NOT NULL,         -- 프로젝트 생성자
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_by VARCHAR(100),                  -- 마지막 수정자
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
assigned_to VARCHAR(100),                 -- 프로젝트 담당자

3. 자재 관리

-- 자재 분류/검증 시 필수 기록
classified_by VARCHAR(100),               -- 자재 분류 담당자
classified_at TIMESTAMP,
verified_by VARCHAR(100),                 -- 검증 담당자
verified_at TIMESTAMP,
updated_by VARCHAR(100),                  -- 수정 담당자
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP

4. 구매 관리

-- 구매 확정/발주 시 필수 기록
confirmed_by VARCHAR(100) NOT NULL,       -- 구매 확정자
confirmed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
ordered_by VARCHAR(100),                  -- 발주 담당자
ordered_at TIMESTAMP,
approved_by VARCHAR(100),                 -- 승인자 (고액 구매 시)
approved_at TIMESTAMP

🔐 권한별 접근 제어

관리자 (admin)

모든 프로젝트 조회/수정 가능
사용자 관리 및 권한 설정
시스템 설정 및 백업 관리
전체 활동 로그 조회

프로젝트 매니저 (manager)

담당 프로젝트 전체 관리
팀원 업무 할당 및 진행 상황 모니터링
구매 승인 권한 (일정 금액 이하)
프로젝트별 리포트 생성

설계 담당자 (designer)

담당 프로젝트 BOM 업로드/수정
자재 분류 및 검증
리비전 관리
구매 요청서 작성

구매 담당자 (purchaser)

구매 품목 조회 및 발주
공급업체 관리
구매 현황 추적
입고 관리

조회 전용 (viewer)

할당된 프로젝트 조회만 가능
리포트 다운로드
진행 상황 확인

📈 개인별 대시보드 구성

1. 맞춤형 배너 시스템

// 사용자별 맞춤 정보 표시
const personalizedBanner = {
  admin: {
    title: "시스템 관리자",
    metrics: ["전체 프로젝트 수", "활성 사용자 수", "시스템 상태"],
    quickActions: ["사용자 관리", "시스템 설정", "백업 관리"]
  },
  manager: {
    title: "프로젝트 매니저",
    metrics: ["담당 프로젝트", "팀 진행률", "승인 대기"],
    quickActions: ["프로젝트 생성", "팀 관리", "진행 상황"]
  },
  designer: {
    title: "설계 담당자",
    metrics: ["내 BOM 파일", "분류 완료율", "검증 대기"],
    quickActions: ["BOM 업로드", "자재 분류", "리비전 관리"]
  },
  purchaser: {
    title: "구매 담당자", 
    metrics: ["구매 요청", "발주 완료", "입고 대기"],
    quickActions: ["구매 확정", "발주 관리", "공급업체"]
  }
};

2. 활동 이력 추적

-- 사용자 활동 로그 테이블
CREATE TABLE user_activity_logs (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(user_id),
    username VARCHAR(100) NOT NULL,
    activity_type VARCHAR(50) NOT NULL,      -- 'FILE_UPLOAD', 'PROJECT_CREATE', 'PURCHASE_CONFIRM' 등
    activity_description TEXT,               -- 상세 활동 내용
    target_id INTEGER,                       -- 대상 ID (파일, 프로젝트 등)
    target_type VARCHAR(50),                 -- 'FILE', 'PROJECT', 'MATERIAL' 등
    ip_address VARCHAR(45),
    user_agent TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

3. 개인 작업 현황

내가 업로드한 파일: 최근 업로드한 BOM 파일 목록
내가 담당한 프로젝트: 할당된 프로젝트 진행 상황
내 업무 대기: 분류/검증/승인 대기 중인 업무
최근 활동: 최근 7일간 활동 요약

🚀 구현 우선순위

Phase 1: 기본 사용자 추적 (1주)

현재 테이블에 담당자 필드 추가
파일 업로드 시 사용자 정보 기록
기본 활동 로그 시스템 구축

Phase 2: 개인별 대시보드 (2주)

권한별 맞춤형 배너 구현
개인 작업 현황 페이지
활동 이력 조회 기능

Phase 3: 고도화 (3주)

상세 권한 관리 시스템
팀별/부서별 대시보드
업무 할당 및 알림 시스템

⚠️ 주의사항

개인정보 보호: 사용자 활동 로그는 업무 목적으로만 사용
데이터 보존: 활동 로그는 최대 1년간 보존 후 자동 삭제
접근 권한: 개인 활동 이력은 본인과 관리자만 조회 가능
감사 추적: 중요 업무(구매 확정, 프로젝트 삭제 등)는 별도 감사 로그 유지

🚨 프로덕션 배포 전 필수 보안 체크리스트 (2025.01 신규)

⚠️ 중요: 현재 설정은 테스트 환경용입니다. 실제 서비스 배포 전 반드시 아래 항목들을 수정해야 합니다.

🔐 Critical Security Items (배포 전 필수)

1. JWT 시크릿 키 환경변수화

# ❌ 현재 (테스트용)
SECRET_KEY = "test-secret-key"

# ✅ 배포 전 필수 변경
JWT_SECRET_KEY=your-super-secure-random-key-here  # .env 파일에 추가

2. 데이터베이스 비밀번호 보안

# ❌ 현재 (테스트용)
POSTGRES_PASSWORD: tkmp_password_2025

# ✅ 배포 전 필수 변경  
POSTGRES_PASSWORD: ${DB_PASSWORD}  # 환경변수로 분리

3. CORS 도메인 설정

# ❌ 현재 (테스트용)
"production": [
    "https://your-domain.com",
    "https://api.your-domain.com"
]

# ✅ 배포 전 필수 변경
"production": [
    "https://실제도메인.com",
    "https://api.실제도메인.com"
]

4. 기본 관리자 계정 변경

-- ❌ 현재 (테스트용)
INSERT INTO users (username, password) VALUES ('admin', 'admin123');

-- ✅ 배포 전 필수 변경
-- 강력한 비밀번호로 변경 및 테스트 계정 삭제

🛡️ 배포 전 보안 체크리스트

환경변수 분리: 모든 민감 정보를 .env 파일로 분리
HTTPS 적용: SSL 인증서 설치 및 HTTP → HTTPS 리다이렉트
방화벽 설정: 필요한 포트만 개방 (80, 443, SSH)
데이터베이스 접근 제한: 외부 접근 차단, 애플리케이션에서만 접근
로그 파일 보안: 민감 정보 로깅 방지, 로그 파일 권한 설정
백업 전략: 정기 백업 및 복구 테스트
모니터링: 시스템 상태 및 보안 이벤트 모니터링
업데이트 계획: 보안 패치 및 의존성 업데이트 계획

📋 배포 환경별 설정 가이드

개발 환경 (현재)

ENVIRONMENT=development
DEBUG=true
CORS_ORIGINS=http://localhost:3000,http://localhost:13000

스테이징 환경

ENVIRONMENT=staging  
DEBUG=false
CORS_ORIGINS=https://staging.your-domain.com

프로덕션 환경

ENVIRONMENT=production
DEBUG=false
CORS_ORIGINS=https://your-domain.com
JWT_SECRET_KEY=강력한-랜덤-키
DB_PASSWORD=강력한-데이터베이스-비밀번호

📋 API 정리 요약 (2025.09.05 완료)

✅ 해결된 문제들

404 오류 해결: /files/materials → /files/materials-v2 마이그레이션
API 호출 표준화: 직접 호출 → fetchMaterials() 함수 사용
혼동 방지: 명확한 API 사용 가이드라인 수립
문서화 완성: 실제 구현된 모든 API 엔드포인트 정리

🎯 표준화된 사용법

// ✅ 권장 방법
import { fetchMaterials, fetchFiles, fetchJobs } from '../api';

// 파일별 자재 조회
const materials = await fetchMaterials({ file_id: 123 });

// 프로젝트별 자재 조회
const materials = await fetchMaterials({ job_no: 'J24-001' });

// 리비전별 자재 조회
const materials = await fetchMaterials({ 
  job_no: 'J24-001', 
  revision: 'Rev.1' 
});

🚨 중요 규칙

모든 자재 API 호출은 fetchMaterials() 함수 사용
직접 API 호출 금지 (특별한 경우 제외)
새 API 추가 시 RULES.md 즉시 업데이트
API 변경 시 하위 호환성 고려

🔍 자재 분류 규칙

핵심 분류 원칙

1. 니플(NIPPLE) 특수 규칙 ⚠️

분류 방식: 파이프 분류기(pipe_classifier)로 분류하지만 카테고리는 FITTING으로 처리
이유: 니플은 파이프와 동일한 재질/스펙을 가지지만, 용도상 피팅류로 취급
길이 기반 그룹핑: 같은 스펙이라도 길이가 다르면 별도 항목으로 분리
- 예: NIPPLE 1" 75mm vs NIPPLE 1" 100mm
총길이 계산: 개별 니플 길이 × 수량을 합산하여 실제 총길이 표시
끝단 가공 처리: 파이프와 동일하게 PBE, BBE, POE 등 끝단 가공 정보 분리 저장
그룹핑 키: clean_description|size_spec|material_grade|length_mm

2. 파이프(PIPE) 분류 규칙

그룹핑 키: clean_description|size_spec|material_grade
끝단 가공 제외: 구매용 그룹핑에서는 BBE, POE, PBE 등 끝단 가공 정보 제외
개별 정보 보존: 각 파이프의 끝단 가공 정보는 pipe_end_preparations 테이블에 별도 저장
총길이 계산: 동일 스펙 파이프들의 개별 길이 합산

3. 기타 피팅(FITTING) 분류 규칙

일반 피팅: 수량 기반 집계 (ELBOW, TEE, REDUCER 등)
길이 정보 없음: 니플을 제외한 일반 피팅은 길이 기반 그룹핑 불필요

분류 우선순위

PIPE: 파이프 분류기 우선 적용
FITTING: 니플 포함, 피팅 분류기 적용
VALVE: 밸브 분류기 적용
FLANGE: 플랜지 분류기 적용
BOLT: 볼트 분류기 적용
GASKET: 가스켓 분류기 적용
INSTRUMENT: 계기 분류기 적용

끝단 가공 코드 정의

PBE: Plain Both Ends (양쪽 무개선) - 기본값
BBE: Both Ends Beveled (양쪽 개선)
POE: Plain One End (한쪽 무개선)
BOE: Beveled One End (한쪽 개선)
TOE: Threaded One End (한쪽 나사)

마지막 업데이트: 2025년 9월 (자재 분류 규칙 및 API 정리 완료)

67 KiB Raw Blame History Unescape Escape