226 lines
8.0 KiB
Markdown
226 lines
8.0 KiB
Markdown
# 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 파일 (결제, 인증 모듈)
|