8.0 KiB
8.0 KiB
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 데코레이터
빌드 및 개발
빌드 명령어
# 컴파일 및 패키징 (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 계층형 아키텍처를 따릅니다:
-
컨트롤러 계층 (
*.web.*Controller)- 요청 처리 및 응답 생성
- URL 패턴:
*.do(Spring DispatcherServlet 매핑) *.web패키지에 위치
-
서비스 계층 (
*.service.*Service,*ServiceImpl)- 비즈니스 로직 구현
- 트랜잭션 경계 정의
- 인터페이스-구현체 패턴
-
DAO 계층 (
*.service.impl.*DAO)- iBATIS SqlMapClient를 사용한 데이터 접근
- 공통 작업을 위해
EgovComAbstractDAO상속 - SQL 매핑:
src/main/resources/egovframework/sqlmap/
-
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 기반)
개발 가이드
신규 기능 추가 절차
- VO 생성:
ComDefaultVO또는ComDefaultCodeVO상속 - SQL 매퍼 생성:
src/main/resources/egovframework/sqlmap/에 XML 추가 - SQL 설정 등록:
sql-map-config-mysql-{모듈명}.xml에 등록 - DAO 생성:
EgovComAbstractDAO상속 - 서비스 생성: 인터페이스 + 구현체 패턴
- 컨트롤러 생성:
@Controller또는@RestController사용 - JSP 생성:
src/main/webapp/WEB-INF/jsp/{모듈명}/에 배치
코드 규칙
- 전자정부 프레임워크 표준과 네이밍 규칙을 따름
- 서비스 인터페이스는
Service접미사 - 서비스 구현체는
ServiceImpl접미사 - DAO 클래스는
DAO접미사 - 컨트롤러 클래스는
Controller접미사 - 의존성 주입은
@Resource(name="빈이름")사용
iBATIS SQL 매핑
SQL 구문은 네임스페이스.구문ID 패턴으로 참조:
// EgovComAbstractDAO를 상속한 DAO에서
insert("모듈명.insertData", vo);
selectList("모듈명.selectDataList", searchVO);
주요 작업 패턴
페이징:
// VO에서
ComDefaultVO를 상속하여 페이징 필드 사용
// PaginationInfo와 ImagePaginationRenderer 활용
파일 업로드:
// 파일 작업은 EgovFileMngService 사용
// Globals.file.saveDir 속성 기반으로 파일 저장
로깅:
// LoggerAspect를 통한 AOP 기반 로깅
// log4jdbc를 통한 SQL 로깅
테스트
현재 Maven 설정에서 테스트가 비활성화되어 있습니다(pom.xml의 skipTests=true). 활성화하려면:
# pom.xml의 surefire 플러그인 설정 수정 후 실행:
mvn test
배포
애플리케이션은 WAR 파일(mjon.war)로 빌드되어 Tomcat에 배포됩니다:
- 배포 경로:
/usr/local/tomcat(운영) - 포트: Tomcat server.xml에서 설정
- 세션 타임아웃: 600분 (10시간)
- 에러 페이지:
/common/error.jsp
환경별 배포
- 적절한 프로파일 설정:
-Dspring.profiles.active={dev|prod} globals_{profile}.properties에 데이터베이스 자격증명 확인- properties에 파일 경로(ckeditor, fax 등) 설정
- WAR 파일을 Tomcat webapps 디렉토리에 배포
중요 사항
- 문자 인코딩: 레거시 결제 시스템을 위한 UTF-8/EUC-KR 혼용
- 데이터베이스: MySQL 5.x - 구버전 iBATIS 사용 (MyBatis 아님)
- 보안: Spring Security 통합,
EgovUserDetailsService를 통한 사용자 정보 - 프로파일 필수: 애플리케이션 시작 시
-Dspring.profiles.active필요 - 외부 라이브러리:
WEB-INF/lib에 일부 JAR 파일 (결제, 인증 모듈)