# 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`

#### 기본 키 생성 규칙
```sql
-- 총 20자리: 데이터 약어(4자리) + 시퀀스(16자리)
SELECT CONCAT('BBSN', LPAD(NEXTVAL(seq_notice_id), 16, '0'))
```

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

## 빌드 및 개발 명령어

### 빌드 명령어
```bash
# 테스트 포함 전체 빌드
./gradlew clean build

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

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

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

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

### 개발 서버 실행
```bash
# 로컬 내장 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`을 사용하여 일관된 응답 제공:
```java
// 데이터와 함께 성공 응답
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 배포
```bash
# 외부 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만)

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