ERP-node/.cursor/rules/troubleshooting-guide.mdc

---
description: 
globs: 
alwaysApply: true
---
# 트러블슈팅 가이드

## 일반적인 문제 해결

### 애플리케이션 시작 오류

#### 데이터베이스 연결 실패
```
원인: JNDI DataSource 설정 문제
해결: 
1. tomcat-conf/context.xml 확인
2. PostgreSQL 서비스 상태 확인
3. 데이터베이스 접속 정보 확인
```

#### 클래스 로딩 오류
```
원인: 컴파일되지 않은 Java 파일
해결:
1. Eclipse에서 프로젝트 Clean & Build
2. WebContent/WEB-INF/classes/ 디렉토리 확인
3. 누락된 라이브러리 확인 (WebContent/WEB-INF/lib/)
```

### 런타임 오류

#### 404 오류 (페이지를 찾을 수 없음)
```
원인: URL 매핑 문제
해결:
1. @RequestMapping 어노테이션 확인
2. JSP 파일 경로 확인 (/WEB-INF/view/)
3. web.xml의 servlet-mapping 확인 (*.do 패턴)
```

#### 500 오류 (서버 내부 오류)
```
원인: Java 코드 실행 오류
해결:
1. 로그 파일 확인 (log4j 설정)
2. MyBatis SQL 오류 확인
3. NullPointerException 체크
4. 데이터베이스 트랜잭션 오류 확인
```

### 데이터베이스 관련 문제

#### SQL 실행 오류
```
원인: MyBatis 매퍼 설정 문제
해결:
1. mapper XML 파일의 SQL 문법 확인
2. parameterType과 resultType 확인
3. 테이블/컬럼명 대소문자 확인 (PostgreSQL)
```

#### 트랜잭션 문제
```
원인: SqlSession 관리 문제
해결:
1. SqlSession.close() 호출 확인
2. try-finally 블록에서 리소스 정리
3. 트랜잭션 커밋/롤백 처리
```

### 프론트엔드 문제

#### JavaScript 오류
```
원인: jQuery/jqGrid 라이브러리 문제
해결:
1. 브라우저 개발자 도구 콘솔 확인
2. JavaScript 파일 로딩 순서 확인
3. jQuery 버전 호환성 확인
```

#### CSS 스타일 문제
```
원인: CSS 파일 로딩 또는 경로 문제
해결:
1. CSS 파일 경로 확인
2. 브라우저 캐시 클리어
3. all.css 파일 확인
```

## 개발 환경 문제

### Docker 환경
```bash
# 컨테이너 로그 확인
docker-compose logs app

# 컨테이너 내부 접속
docker-compose exec app bash

# 데이터베이스 접속 확인
docker-compose exec db psql -U postgres -d ilshin
```

### Eclipse 환경
```
문제: 프로젝트 인식 오류
해결:
1. .project 파일 확인
2. .classpath 파일 확인  
3. Project Properties > Java Build Path 확인
4. Server Runtime 설정 확인 (Tomcat 7.0)
```

## 로그 분석

### 주요 로그 위치
- 애플리케이션 로그: log4j 설정에 따름
- Tomcat 로그: `$CATALINA_HOME/logs/`
- Docker 로그: `docker-compose logs`

### 로그 설정 파일
- [log4j.xml](mdc:WebContent/WEB-INF/log4j.xml) - 로깅 설정
- 로그 레벨 조정으로 상세 정보 확인 가능

## 성능 문제

### 데이터베이스 성능
```sql
-- 슬로우 쿼리 확인
SELECT query, mean_time, calls 
FROM pg_stat_statements 
ORDER BY mean_time DESC;

-- 인덱스 사용률 확인
SELECT schemaname, tablename, indexname, idx_scan, idx_tup_read, idx_tup_fetch
FROM pg_stat_user_indexes;
```

### 메모리 문제
```
원인: 메모리 누수 또는 부족
해결:
1. JVM 힙 메모리 설정 확인
2. SqlSession 리소스 정리 확인
3. 대량 데이터 처리 시 페이징 적용
```

## 보안 관련

### 권한 문제
```
원인: 사용자 권한 설정 오류
해결:
1. MENU_AUTH_GROUP 테이블 확인
2. 사용자 세션 정보 확인
3. Spring Security 설정 확인 (있는 경우)
```

### SQL 인젝션 방지
```
주의사항:
1. MyBatis #{} 파라미터 바인딩 사용
2. ${} 직접 문자열 치환 지양
3. 사용자 입력값 검증
```