TK-BOM-Project/SCHEMA_ANALYSIS.md

# TK-MP-Project 데이터베이스 스키마 분석

## 1. 코드에서 정의된 테이블 (SQLAlchemy 모델)

### 인증 관련 테이블 (backend/app/auth/models.py)
- `users` - 사용자 정보
- `login_logs` - 로그인 기록
- `user_sessions` - 사용자 세션
- `permissions` - 권한 정보
- `role_permissions` - 역할별 권한

### 메인 테이블 (backend/app/models.py)
- `projects` - 프로젝트 정보
- `files` - 업로드된 파일 정보
- `materials` - 자재 정보
- `material_standards` - 자재 표준 규격
- `material_categories` - 자재 카테고리
- `material_specifications` - 자재 사양
- `material_grades` - 자재 등급
- `material_patterns` - 자재 패턴
- `special_materials` - 특수 자재
- `special_material_grades` - 특수 자재 등급
- `special_material_patterns` - 특수 자재 패턴
- `pipe_details` - 파이프 상세 정보
- `requirement_types` - 요구사항 타입
- `user_requirements` - 사용자 요구사항
- `tubing_categories` - 튜빙 카테고리
- `tubing_specifications` - 튜빙 사양
- `tubing_manufacturers` - 튜빙 제조사
- `tubing_products` - 튜빙 제품
- `material_tubing_mapping` - 자재-튜빙 매핑

## 2. 현재 DB에 존재하는 테이블

### 존재하는 테이블 (40개)
- bolt_details
- confirmed_purchase_items
- files
- fitting_details
- flange_details
- gasket_details
- instrument_details
- jobs
- login_logs
- material_categories
- material_comparison_details
- material_grades
- material_patterns
- material_purchase_mapping
- material_purchase_tracking
- material_revisions_comparison
- material_specifications
- material_standards
- material_tubing_mapping
- materials
- permissions
- pipe_details
- pipe_end_preparations
- projects
- purchase_confirmations
- purchase_items
- requirement_types
- role_permissions
- special_material_grades
- special_material_patterns
- special_materials
- tubing_categories
- tubing_manufacturers
- tubing_products
- tubing_specifications
- user_activity_logs
- user_requirements
- user_sessions
- users
- valve_details

## 3. 누락된 테이블 (코드에는 있지만 DB에는 없음)

**없음** - 모든 코드 정의 테이블이 DB에 존재함

## 4. 추가 테이블 (DB에는 있지만 코드에는 정의되지 않음)

- `bolt_details` - 볼트 상세 정보
- `confirmed_purchase_items` - 구매 확정 항목
- `fitting_details` - 피팅 상세 정보
- `flange_details` - 플랜지 상세 정보
- `gasket_details` - 가스켓 상세 정보
- `instrument_details` - 계기 상세 정보
- `jobs` - 작업 정보
- `material_comparison_details` - 자재 비교 상세
- `material_purchase_mapping` - 자재 구매 매핑
- `material_purchase_tracking` - 자재 구매 추적
- `material_revisions_comparison` - 자재 리비전 비교
- `pipe_end_preparations` - 파이프 끝단 가공
- `purchase_confirmations` - 구매 확정
- `purchase_items` - 구매 항목
- `user_activity_logs` - 사용자 활동 로그
- `valve_details` - 밸브 상세 정보

## 5. 컬럼 누락 문제

### users 테이블 문제 (✅ 해결됨)
**오류**: `column users.status does not exist`
- **해결**: `status` 컬럼 (VARCHAR(20), default='active') 추가 완료

### files 테이블 문제 (✅ 해결됨)
**오류**: `column "job_no" of relation "files" does not exist`

**누락된 컬럼들**:
- `job_no` (VARCHAR(100)) - 작업 번호
- `bom_name` (VARCHAR(255)) - BOM 이름
- `description` (TEXT) - 파일 설명
- `parsed_count` (INTEGER) - 파싱된 자재 개수

**해결**: 모든 누락 컬럼 추가 완료

### materials 테이블 문제 (✅ 해결됨)
**오류**: `column "main_nom" of relation "materials" does not exist`

**대규모 누락된 컬럼들 (22개)**:
- 사이즈 정보: `main_nom`, `red_nom`, `row_number`
- 재질 정보: `full_material_grade`, `standard`, `grade`, `subcategory`
- 사용자 입력: `brand`, `user_requirement`
- 메타데이터: `material_hash`, `classified_by`, `updated_by`, `revision_status`
- 추가 필드들: `length`, `total_length`, `is_active`, `purchase_confirmed` 등

**해결**: 테스팅 서버 기준으로 모든 누락 컬럼 추가 완료 (22개 → 44개 컬럼)

## 6. 해결 방안

### 즉시 해결 필요
1. `users` 테이블에 `status` 컬럼 추가
2. 기존 사용자 데이터의 `status` 값을 'active'로 설정

### 장기 해결 방안
1. 모든 상세 테이블들에 대한 SQLAlchemy 모델 정의 추가
2. 자동 마이그레이션 시스템 구축
3. 스키마 검증 시스템 구축

## 7. 마이그레이션 스크립트 필요사항

```sql
-- 즉시 필요한 수정 (✅ 완료됨)
ALTER TABLE users ADD COLUMN status VARCHAR(20) DEFAULT 'active';
UPDATE users SET status = 'active' WHERE status IS NULL;

-- files 테이블 누락 컬럼 추가 (✅ 완료됨)
ALTER TABLE files ADD COLUMN job_no VARCHAR(100);
ALTER TABLE files ADD COLUMN bom_name VARCHAR(255);
ALTER TABLE files ADD COLUMN description TEXT;
ALTER TABLE files ADD COLUMN parsed_count INTEGER;
```

## 8. 구축된 자동화 도구들

### 스키마 분석기 (`backend/scripts/schema_analyzer.py`)
- 코드와 DB 스키마를 자동으로 비교 분석
- 누락된 테이블/컬럼을 자동으로 감지
- 마이그레이션 SQL을 자동 생성

### 자동 마이그레이션 도구 (`backend/scripts/auto_migrator.py`)
- 분석 결과를 바탕으로 자동으로 DB 업데이트
- 트랜잭션 기반 안전한 마이그레이션
- 마이그레이션 로그 자동 생성

### Docker 환경 마이그레이션 (`backend/scripts/docker_migrator.py`)
- Docker 컨테이너 내에서 실행 가능한 간단한 마이그레이션 도구
- 중요 테이블 존재 여부 자동 확인
- 즉시 해결 필요한 스키마 문제 자동 수정

### 스키마 모니터링 시스템 (`backend/scripts/schema_monitor.py`)
- 코드 변경사항을 실시간으로 감지
- 스키마 불일치 발생 시 자동 알림
- 배포 준비 상태 자동 검증

## 9. 사용법

### 즉시 스키마 체크 및 수정
```bash
docker exec tk-mp-backend python3 scripts/docker_migrator.py
```

### 전체 스키마 분석 (로컬)
```bash
cd backend/scripts
python3 schema_analyzer.py
```

### 자동 마이그레이션 실행 (로컬)
```bash
cd backend/scripts
python3 auto_migrator.py
```

### 배포 준비 상태 검증
```bash
cd backend/scripts
python3 schema_monitor.py --mode validate
```

### 배포용 마이그레이션 생성
```bash
cd backend/scripts
python3 schema_monitor.py --mode deploy
```

## 10. 지속적인 관리 방안

1. **개발 중**: `schema_monitor.py --mode monitor`로 실시간 모니터링
2. **배포 전**: `schema_monitor.py --mode validate`로 준비 상태 확인
3. **배포 시**: `schema_monitor.py --mode deploy`로 안전한 마이그레이션 스크립트 생성
4. **운영 중**: 정기적으로 `docker_migrator.py` 실행하여 스키마 동기화 확인