xit-framework/CLAUDE.md

CLAUDE.md

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

기본 중요 가이드라인

🚨 반드시 지켜야 할 규칙

• 한글로 대화: 모든 응답과 진행상황은 한글로 작성
• 테스트 소스 작성 불가: 테스트 코드는 생성하지 않음
• 중요 로직 주석 필수: 모든 중요한 로직에 한글 주석 작성
• 스웨거 적용: 모든 컨트롤러 클래스에 스웨거 어노테이션 적용
• 기존 소스 수정 제한: 공백 제거 등 로직에 불필요한 수정 금지

🏛️ 아키텍처 패턴

• MVC 패턴: Spring Boot + MyBatis + JSP 구조
• 템플릿 엔진: Apache Tiles 사용
• 보안: 세션 기반 인증/인가
• 코딩 스타일: noticeSample 모듈을 참조 표준으로 사용

🎨 프론트엔드 가이드

• URL 태그: 모든 URL은 <c:url value="" /> 태그 사용 필수
• 정적 리소스: src/main/webapp/resources/css, js, xit 등 해당 위치 사용
• 모달: /system/loginLog/list.jsp 참조
• 팝업: /system/user/auth_popup.jsp 참조
• CSS 위치:
  • 모달/메인 윈도우: xit-common.css
  • 팝업: xit-popup.css

🗄️ 데이터베이스 규칙

컬럼 단어사전 준수 (필수)

• 참조: DB-DDL/maria/dictionary/column_word_dictionary.md 반드시 확인
• 신규 단어: 사전에 없는 단어는 반드시 사전에 추가
• 시간 표기: LocalDateTime 컬럼은 "일시(dttm)"로 명명
• 예시: 일시 → reg_dttm, 시간 → reg_dttm

MyBatis 설정

• camelCase 자동 적용: 컬럼 별칭(alias) 불필요
• DB 구조 참조: DB-DDL/maria/ddl/xitframework/*.sql

기본 키 생성 규칙

-- 총 20자리: 데이터 약어(4자리) + 시퀀스(16자리)
SELECT CONCAT('BBSN', LPAD(NEXTVAL(seq_notice_id), 16, '0'))

페이징 처리 순서 (중요!)

// 1. 총 개수 조회
int totalCount = excelSampleService.selectExcelSampleListTotalCount(paramVO);
// 2. 총 개수 설정
paramVO.setTotalCount(totalCount);
// 3. 페이징 활성화 (반드시 이 순서로!)
paramVO.setPagingYn("Y");

빌드 및 개발 명령어

빌드 명령어

# 테스트 포함 전체 빌드
./gradlew clean build

# 테스트 제외 빌드
./gradlew clean build -x test

# 표준 WAR 파일 생성
./gradlew war

# 실행 가능한 bootWar 파일 생성
./gradlew bootWar

# 압축 해제된 WAR 추출 (디버깅용)
./gradlew exploded

개발 서버 실행

# 로컬 내장 Tomcat으로 실행
./gradlew bootRun

# 특정 프로필과 포트로 실행
java -jar build/libs/xit-framework-boot.war --spring.profiles.active=local --server.port=9090

# 백그라운드 실행 (Linux/macOS)
nohup java -jar build/libs/xit-framework-boot.war > app.log 2>&1 &

아키텍처 개요

Spring Boot 2.7.18 + 전자정부프레임워크 4.3.0 기반 애플리케이션:

핵심 기술 스택

기술	버전	설명
Java	1.8	자바 개발 및 실행 환경
Spring Boot	2.7.18	스프링 기반 애플리케이션 개발 프레임워크
전자정부 프레임워크	4.3.0	한국 정부 표준 웹 개발 프레임워크
MariaDB	-	관계형 데이터베이스
MyBatis	2.3.1	SQL 매핑 프레임워크
Apache Tiles	3.0.8	레이아웃 템플릿 엔진
TOAST UI Grid	4.19.2	자바스크립트 그리드 라이브러리
Quartz	-	JDBC 기반 클러스터 스케줄러

주요 라이브러리

라이브러리	버전	설명
Lombok	-	자바 코드 생성 라이브러리
Apache Commons Text	1.10.0	텍스트 처리 유틸리티
Apache POI	5.3.0	엑셀 파일 처리 라이브러리
Gradle	-	빌드 및 의존성 관리 도구

프로젝트 구조 패턴

go.kr.project/
├── {module}/
│   ├── controller/     # REST/MVC 컨트롤러
│   ├── service/        # 비즈니스 로직 (인터페이스 + 구현체)
│   ├── mapper/         # MyBatis 데이터 접근 인터페이스
│   ├── model/          # 데이터 전송 객체 (VO 클래스)
│   └── config/         # 모듈별 설정
├── common/            # 공통 유틸리티 및 컴포넌트
├── batch/             # Quartz 기반 배치 작업 시스템
├── system/            # 시스템 관리 (사용자, 역할, 메뉴 등)
└── template/          # 템플릿/샘플 코드

egovframework/         # 프레임워크 확장
├── config/            # Spring 설정
├── util/              # 유틸리티 클래스
├── filter/            # 보안 필터 (XSS, 세션)
├── interceptor/       # 요청 인터셉터 (인증, 리퍼러 체크)
└── exception/         # 커스텀 예외 및 핸들러

디렉토리 구조

xit-framework/
├── DB-DDL/                    # 데이터베이스 스크립트
│   └── maria/                 # MariaDB 스크립트
│       ├── ddl/               # 테이블 정의 스크립트
│       ├── dml/               # 샘플 데이터 스크립트
│       └── dictionary/        # 컬럼 단어사전
├── src/
│   ├── main/
│   │   ├── java/              # 자바 소스 코드
│   │   │   ├── egovframework/ # 전자정부 프레임워크 확장 코드
│   │   │   └── go/kr/project/ # 프로젝트 소스 코드
│   │   ├── resources/         # 리소스 파일
│   │   │   ├── mybatis/       # MyBatis 설정 및 매퍼
│   │   │   └── application.yml # 애플리케이션 설정 파일
│   │   └── webapp/            # 웹 리소스
│   │       ├── resources/     # 정적 리소스 (CSS, JS, 이미지 등)
│   │       └── WEB-INF/views/ # JSP 뷰 파일
│   └── test/                  # 테스트 코드 (작성 불가)
└── build.gradle               # Gradle 빌드 스크립트

데이터베이스 설계

역할 기반 접근 제어 시스템을 사용:

• **사용자(Users)**는 **그룹(Groups)**에 속함
• **그룹(Groups)**은 여러 **역할(Roles)**을 가짐
• **역할(Roles)**은 메뉴(Menus) 접근 권한을 부여
• **메뉴(Menus)**는 접근 제어를 위한 URL 패턴을 정의

핵심 테이블: tb_user, tb_group, tb_role, tb_menu, tb_group_role, tb_role_menu

주요 컴포넌트 및 패턴

MVC 패턴

각 기능 모듈은 다음 구조를 따름:

1. Controller: HTTP 요청 처리, 서비스로 위임
2. Service: 비즈니스 로직 포함, @Service("ServiceName") 어노테이션 사용
3. Mapper: 데이터베이스 작업을 위한 MyBatis 인터페이스
4. Model: 데이터 전송을 위한 VO 클래스

API 응답 패턴

모든 AJAX 엔드포인트는 ApiResponseUtil을 사용하여 일관된 응답 제공:

// 데이터와 함께 성공 응답
return ApiResponseUtil.success(data, "성공 메시지");

// 페이징과 함께 그리드 데이터 응답
return ApiResponseUtil.successWithGrid(list, pagingVO);

// 오류 응답
return ApiResponseUtil.error("오류 메시지");

파일 구성 규칙

• 컨트롤러: {모듈명}Controller.java
• 서비스: {모듈명}Service.java (인터페이스), {모듈명}ServiceImpl.java (구현체)
• 매퍼: {모듈명}Mapper.java + {모듈명}Mapper_maria.xml
• 모델: {모듈명}VO.java
• 뷰: /WEB-INF/views/{module}/{page}.{layout}.jsp

보안 기능

• XSS 보호: 모든 요청 매개변수 자동 필터링
• 인증: 5회 로그인 실패 후 계정 잠금이 있는 세션 기반 인증
• 인가: 역할/메뉴를 통한 URL 패턴 기반 접근 제어
• CSRF 보호: 리퍼러 헤더 검증
• 세션 관리: 자동 갱신, 동시 로그인 제어

배치 시스템 (Quartz 기반)

포괄적인 배치 작업 관리 시스템을 포함:

• 웹 UI: 작업 관리를 위한 /batch/list.do
• REST APIs: 작업 등록, 실행, 일시정지/재개, 로그
• 데이터베이스 추적: 전체 실행 기록 및 로깅
• 클러스터링: 다중 인스턴스 배포 지원
• 작업 클래스: AbstractBatchJob 확장 또는 Job 인터페이스 구현

설정 및 환경

프로필

• local: 로컬 개발환경, 핫 리로드, 로컬 데이터베이스
• dev: 개발 서버 환경
• prd: 최적화된 로깅이 있는 운영 환경

주요 설정 파일

• application.yml: 공통 설정, Quartz 설정, 보안 설정
• application-{profile}.yml: 환경별 데이터베이스, 경로, 로깅
• mybatis/mybatis-config.xml: MyBatis 설정 (camelCase 매핑 활성화)
• tiles.xml: 레이아웃 템플릿 정의

데이터베이스 연결

HikariCP 커넥션 풀 사용. 환경별 YAML 파일에 연결 설정. 현재 4코어/32GB 풀 설정: max-pool-size: 10, connection-timeout: 30s

개발 가이드라인

코드 컨벤션

• /system/ 모듈의 기존 패턴을 참조로 사용
• 모든 데이터베이스 테이블명은 snake_case 사용 (예: tb_user)
• 모든 Java 속성은 camelCase 사용 (MyBatis가 변환 처리)
• 컨트롤러는 "{module}/{page}.{layout}" 형식의 뷰 이름 반환
• JSP에서 모든 URL은 <c:url value="" /> 태그 사용
• AJAX 응답은 response.result 사용 (response.success 아님)

데이터베이스 스키마

• 새 테이블은 DB-DDL/maria/ddl/xitframework/에 위치
• 샘플 데이터는 DB-DDL/maria/dml/에 위치
• ON DELETE CASCADE 사용 금지 - 애플리케이션 코드에서 처리
• ID 생성은 시퀀스 테이블 사용 (패턴: seq_{table}_id)

프론트엔드 통합

• UI 프레임워크: 커스텀 XIT 스타일링이 적용된 Bootstrap
• 그리드 컴포넌트: TOAST UI Grid (xit-tui-grid.js 참조)
• 유효성 검사: 폼 유효성 검사에 xit-validation.js 사용
• 파일 업로드: 드래그 앤 드롭 지원 다중 파일 업로드
• 아이콘: Material Design Icons + FontAwesome

보안 모범 사례

• 로그에 비밀번호나 민감한 데이터 노출 금지
• 모든 파일 업로드는 타입과 크기 검증
• 사용자 비밀번호는 EgovFileScrty.encryptPassword()로 암호화
• 세션 타임아웃: 30분(dev), 60분(prd)

배포

WAR 배포

# 외부 Tomcat용 표준 WAR
./gradlew war
# 출력: build/libs/xit-framework.war

# 내장 서버가 있는 실행 가능한 WAR
./gradlew bootWar
# 출력: build/libs/xit-framework-boot.war

환경 설정

다음을 통해 프로필 설정:

• application.yml: spring.profiles.active: local
• 명령줄: --spring.profiles.active=dev
• 환경변수: SPRING_PROFILES_ACTIVE=dev

외부 WAS 배포 (Tomcat)

1. xit-framework.war를 webapps/에 복사
2. JVM 옵션 설정: -Dspring.profiles.active=dev
3. Java 1.8+ 및 충분한 메모리 할당 확인

중요 참고사항

• 기본 관리자: 초기 데이터 스크립트에서 관리자 사용자 설정 확인
• 데이터베이스 설정: 첫 시작 전 DB-DDL/maria/ddl/의 DDL 스크립트 실행
• 파일 저장소: 환경 YAML에서 file.upload.path 설정
• 로깅: 설정된 경로에 로그, 30일 보관으로 일일 순환
• 모니터링: /actuator/health, /actuator/metrics에서 액츄에이터 엔드포인트 사용 가능
• API 문서: Swagger UI는 /swagger-ui.html에서 사용 가능 (dev/local만)

이 시스템은 포괄적인 감사 추적, 배치 작업 모니터링, 알림 시스템, 파일 처리, 엑셀 처리, 데이터 유효성 검사를 위한 광범위한 유틸리티 기능을 포함합니다.