# CLAUDE.md

이 파일은 Claude Code (claude.ai/code)가 이 저장소에서 작업할 때 참고할 가이드입니다.

## 프로젝트 개요

전자정부 표준프레임워크(eGovFramework) v3.9.0 기반의 Maven 빌드 Java 웹 애플리케이션입니다. 문자ON("MunjaON")이라는 SMS/MMS/카카오톡 메시징 서비스의 관리자 플랫폼입니다.

**기술 스택:**
- Java 8
- Spring Framework 4.3.22
- 전자정부 표준프레임워크 3.9.0
- iBATIS (전자정부프레임워크 경유)
- MySQL 5.1.31
- Maven 빌드 시스템
- JSP/JSTL 뷰 + SiteMesh 데코레이터

## 빌드 및 개발

### 빌드 명령어

```bash
# 컴파일 및 패키징 (WAR 파일 생성)
mvn clean install

# 컴파일만 수행
mvn compile

# 내장 톰캣 실행 (설정된 경우)
mvn tomcat7:run
```

### 환경 설정

애플리케이션은 Spring 프로파일 기반 설정을 사용합니다:
- 환경 프로파일: `dev`, `local`, `prod`
- 시스템 속성으로 설정: `-Dspring.profiles.active=dev`
- 설정 파일 위치: `src/main/resources/egovframework/egovProps/globals_{profile}.properties`

데이터베이스 설정은 활성 프로파일에 따라 `globals_{profile}.properties`에서 로드됩니다.

## 프로젝트 아키텍처

### 패키지 구조

```
src/main/java/
├── egovframework.com/           # 전자정부 커스텀 서비스
│   └── idgen/                   # ID 생성 서비스
├── itn.com/                     # 공통 프레임워크 컴포넌트
│   ├── api/                     # REST API 컨트롤러
│   ├── cmm/                     # 공통 유틸리티 & 기본 클래스
│   │   ├── aspect/              # AOP 로깅
│   │   ├── filter/              # XSS/보안 필터
│   │   ├── interceptor/         # 요청 인터셉터
│   │   └── service/             # 공통 서비스 (파일, 사용자)
│   ├── sym/                     # 시스템 관리 (로깅)
│   ├── uss/                     # 사용자 지원 서비스
│   │   ├── ion/                 # 통합 (배너, 설정, API)
│   │   └── olh/                 # 온라인 도움말
│   └── utl/                     # 유틸리티
└── itn.let/                     # 비즈니스 로직 모듈
    ├── kakao/                   # 카카오톡 메시지 서비스
    ├── mail/                    # 이메일 서비스
    ├── mjo/                     # 핵심 메시징 (SMS/MMS)
    ├── cert/                    # 본인인증
    ├── fax/                     # 팩스 서비스
    └── schdlr/                  # 스케줄러 작업
```

### 계층형 아키텍처

표준 MVC 계층형 아키텍처를 따릅니다:

1. **컨트롤러 계층** (`*.web.*Controller`)
   - 요청 처리 및 응답 생성
   - URL 패턴: `*.do` (Spring DispatcherServlet 매핑)
   - `*.web` 패키지에 위치

2. **서비스 계층** (`*.service.*Service`, `*ServiceImpl`)
   - 비즈니스 로직 구현
   - 트랜잭션 경계 정의
   - 인터페이스-구현체 패턴

3. **DAO 계층** (`*.service.impl.*DAO`)
   - iBATIS SqlMapClient를 사용한 데이터 접근
   - 공통 작업을 위해 `EgovComAbstractDAO` 상속
   - SQL 매핑: `src/main/resources/egovframework/sqlmap/`

4. **VO/DTO 계층** (`*VO`, `*DTO`)
   - 데이터 전송 객체
   - 페이징을 위해 `ComDefaultVO` 상속

### 주요 기본 클래스

- **EgovComAbstractDAO**: iBATIS 작업(`insert`, `update`, `delete`, `select`, `selectList`)을 포함한 기본 DAO
- **ComDefaultVO**: 페이징 지원 기본 VO (`pageIndex`, `pageUnit`, `pageSize`)
- **ComDefaultCodeVO**: 코드 기반 엔티티용 기본 VO

### 설정 파일

**Spring 설정:**
- `src/main/resources/egovframework/spring/com/context-*.xml` - 애플리케이션 컨텍스트
- `src/main/webapp/WEB-INF/config/egovframework/springmvc/*.xml` - MVC 설정
- 주요 컨텍스트:
  - `context-datasource.xml` - 데이터베이스 연결 (프로파일 기반)
  - `context-sqlMap.xml` - iBATIS SQL 매핑 설정
  - `context-security.xml` - Spring Security 설정
  - `context-aspect.xml` - AOP 로깅 설정

**SQL 매핑:**
- 위치: `src/main/resources/egovframework/sqlmap/config/mysql/`
- 패턴: `sql-map-config-mysql-{모듈명}.xml`
- SQL 정의: `src/main/resources/egovframework/sqlmap/com/**/*_SQL_Mysql.xml`

**뷰 설정:**
- JSP 위치: `src/main/webapp/WEB-INF/jsp/`
- SiteMesh 데코레이터: `src/main/webapp/WEB-INF/decorators.xml`
- 레이아웃 템플릿: `src/main/webapp/WEB-INF/jsp/layout/`

## 주요 기능

### 보안 및 필터

- **Spring Security**: `context-security.xml`을 통해 설정
- **XSS 필터**: `XssFilter`가 요청을 래핑하여 입력값 검증
- **문자 인코딩**: 기본 UTF-8, 특정 결제 엔드포인트는 EUC-KR
- **CORS**: `CORSFilter`를 통해 활성화

### 외부 연동

- **결제 게이트웨이**: KG 모빌리언스 (`globals.properties`에 설정)
- **본인인증**: NiceID, KMC, ARS 인증
- **메시징 API**: 카카오톡, SMS/MMS 서비스
- **파일 업로드**: Apache Commons FileUpload
- **PDF 처리**: Apache PDFBox
- **엑셀**: Apache POI

### 스케줄 작업

- Quartz 스케줄러 설정: `context-scheduling-*.xml`
- 작업 구현: `itn.let.schdlr` 패키지
- 분산 작업 잠금을 위해 ShedLock 사용 (JDBC 기반)

## 개발 가이드

### 신규 기능 추가 절차

1. **VO 생성**: `ComDefaultVO` 또는 `ComDefaultCodeVO` 상속
2. **SQL 매퍼 생성**: `src/main/resources/egovframework/sqlmap/`에 XML 추가
3. **SQL 설정 등록**: `sql-map-config-mysql-{모듈명}.xml`에 등록
4. **DAO 생성**: `EgovComAbstractDAO` 상속
5. **서비스 생성**: 인터페이스 + 구현체 패턴
6. **컨트롤러 생성**: `@Controller` 또는 `@RestController` 사용
7. **JSP 생성**: `src/main/webapp/WEB-INF/jsp/{모듈명}/`에 배치

### 코드 규칙

- 전자정부 프레임워크 표준과 네이밍 규칙을 따름
- 서비스 인터페이스는 `Service` 접미사
- 서비스 구현체는 `ServiceImpl` 접미사
- DAO 클래스는 `DAO` 접미사
- 컨트롤러 클래스는 `Controller` 접미사
- 의존성 주입은 `@Resource(name="빈이름")` 사용

### iBATIS SQL 매핑

SQL 구문은 네임스페이스.구문ID 패턴으로 참조:
```java
// EgovComAbstractDAO를 상속한 DAO에서
insert("모듈명.insertData", vo);
selectList("모듈명.selectDataList", searchVO);
```

### 주요 작업 패턴

**페이징:**
```java
// VO에서
ComDefaultVO를 상속하여 페이징 필드 사용
// PaginationInfo와 ImagePaginationRenderer 활용
```

**파일 업로드:**
```java
// 파일 작업은 EgovFileMngService 사용
// Globals.file.saveDir 속성 기반으로 파일 저장
```

**로깅:**
```java
// LoggerAspect를 통한 AOP 기반 로깅
// log4jdbc를 통한 SQL 로깅
```

## 테스트

현재 Maven 설정에서 테스트가 비활성화되어 있습니다(`pom.xml`의 `skipTests=true`). 활성화하려면:
```bash
# pom.xml의 surefire 플러그인 설정 수정 후 실행:
mvn test
```

## 배포

애플리케이션은 WAR 파일(`mjon.war`)로 빌드되어 Tomcat에 배포됩니다:
- 배포 경로: `/usr/local/tomcat` (운영)
- 포트: Tomcat server.xml에서 설정
- 세션 타임아웃: 600분 (10시간)
- 에러 페이지: `/common/error.jsp`

### 환경별 배포

1. 적절한 프로파일 설정: `-Dspring.profiles.active={dev|prod}`
2. `globals_{profile}.properties`에 데이터베이스 자격증명 확인
3. properties에 파일 경로(ckeditor, fax 등) 설정
4. WAR 파일을 Tomcat webapps 디렉토리에 배포

## 중요 사항

- **문자 인코딩**: 레거시 결제 시스템을 위한 UTF-8/EUC-KR 혼용
- **데이터베이스**: MySQL 5.x - 구버전 iBATIS 사용 (MyBatis 아님)
- **보안**: Spring Security 통합, `EgovUserDetailsService`를 통한 사용자 정보
- **프로파일 필수**: 애플리케이션 시작 시 `-Dspring.profiles.active` 필요
- **외부 라이브러리**: `WEB-INF/lib`에 일부 JAR 파일 (결제, 인증 모듈)