psy
/
xit-framework
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

깃 이그노어 조정

Browse Source
dev
박성영 4 months ago
parent 30eda15c9e
commit d835caa38b
3 changed files with 400 additions and 2 deletions
Show Stats Download Patch File Download Diff File

2
.gitignore vendored
Unescape Escape View File

@ -24,11 +24,9 @@
hs_err_pid*
replay_pid*
/.junie/
/logs/
/build/
/.idea/
/.gradle/
/.idea/
/.fastRequest/
/CLAUDE.md

110
.junie/guidelines.md
Unescape Escape View File

@ -0,0 +1,110 @@
# Project Guidelines
## 기본 중요 가이드
### 한글로 대화, 한글 필수
### junie 의 중간 진행상황도 한글로 작성해서 보여줘
### 테스트소스는 작성 불가!!
### 중요로직 주석 필수 (한글)
### 각 컨트롤러 클래스에 스웨거 적용
### 기존소스의 공백제거 등 로직에 필요없는 부분은 수정 불가!!
### mvc 패턴, springboot + mybatis + jsp 구조, tiles 사용
### session 보안
### 기본적인 코딩 스타일은 noticeSample 참조 (xml, java, jsp)
### url 은 기본적으로 <c:url/> 사용
### 정적 리소스는 src/main/webapp/resources/css,js,xit 등등 해당 위치에 있음.
- 모달은 src/main/webapp/WEB-INF/views/system/loginLog/list.jsp :: 로그인로그 목록 조회 페이지 참조
- 팝업은 src/main/webapp/WEB-INF/views/system/user/auth_popup.jsp :: 팝업 호출 참조
- 모달과 메인윈도우는 src/main/webapp/resources/xit/xit-common.css 에 css 추가
- 팝업은 src/main/webapp/resources/xit/xit-popup.css 에 css 추가
### 신규 sql, DDL 생성시 DB-DDL/maria/dictionary/column_word_dictionary.md, 컬럼 단어사전 무조건 참조!!
### 단어사전에 없다면 단어사전 신규 추가!! (규칙은 무조건 지켜야함 특히, 일시->dttm, 같은 경우)
### 시간이란 명칭의 컬럼도 LocalDateTime 일경우 일시(dttm) 으로 변경하여 저장
### mybatis 기본적으로 camelCase 적용되어 있어 컬럼의 알리아스(별시) 별도로 사용하지 않아도 돼
### DB 구조는 DB-DDL/maria/ddl/xitframework/*.sql 참조
### 기본적인 key 는 시컨스를 이용, 총 20자리, 데이터약어 4자리, 시컨스포함 16자리
```mariadb
SELECT CONCAT('BBSN', LPAD(NEXTVAL(seq_notice_id), 16, '0'))
```
### paging 처리 시 controller 에서 1.totalCount 구하기, 2.setTotalCount, 3.setPagingYn 순서 중요!! 해당순서를 지켜야지만 에러 발생안함.
```java
// 1. 총 개수 조회
int totalCount = excelSampleService.selectExcelSampleListTotalCount(paramVO);
// 2. 응답 데이터 구성
paramVO.setTotalCount(totalCount);
// 3. 페이징 처리
paramVO.setPagingYn("Y");
```
## 2 주요 기술 및 라이브러리
### 2.1 핵심 기술 스택
| 기술 | 버전 | 설명 |
|------|------|------|
| Java | 개발: 1.8, 배포: 1.8 | 자바 개발 및 실행 환경 |
| Spring Boot | 2.7.18 | 스프링 기반 애플리케이션 개발 프레임워크 |
| 전자정부 프레임워크 | 4.3.0 | 한국 정부 표준 웹 개발 프레임워크 |
| Servlet | 3.1 | 웹 애플리케이션 표준 |
| Gradle | - | 빌드 및 의존성 관리 도구 |
| MariaDB | - | 관계형 데이터베이스 |
## 2.2 주요 라이브러리
| 라이브러리 | 버전 | 설명 |
|------------|------|------|
| MyBatis | 2.3.1 | SQL 매핑 프레임워크 |
| Apache Tiles | 3.0.8 | 레이아웃 템플릿 엔진 |
| TOAST UI Grid | 4.19.2 | 자바스크립트 그리드 라이브러리 |
| Lombok | - | 자바 코드 생성 라이브러리 |
| Apache Commons Text | 1.10.0 | 텍스트 처리 유틸리티 |
| Apache POI | 5.3.0 | 엑셀 파일 처리 라이브러리 |
## 3. 프로젝트 구조
### 3.1 디렉토리 구조
```
xit-framework/
├── DB-DDL/ # 데이터베이스 스크립트
│ └── maria/ # MariaDB 스크립트
│ ├── ddl/ # 테이블 정의 스크립트
│ └── dml/ # 샘플 데이터 스크립트
├── src/
│ ├── main/
│ │ ├── java/ # 자바 소스 코드
│ │ │ ├── egovframework/ # 전자정부 프레임워크 확장 코드
│ │ │ └── go/kr/project/ # 프로젝트 소스 코드
│ │ ├── resources/ # 리소스 파일
│ │ │ ├── mybatis/ # MyBatis 설정 및 매퍼
│ │ │ └── application.yml # 애플리케이션 설정 파일
│ │ └── webapp/ # 웹 리소스
│ │ ├── resources/ # 정적 리소스 (CSS, JS, 이미지 등)
│ │ └── WEB-INF/views/ # JSP 뷰 파일
│ └── test/ # 테스트 코드
└── build.gradle # Gradle 빌드 스크립트
```
### 3.2 패키지 구조
```
go.kr.project/
├── common/ # 공통 컴포넌트
├── login/ # 로그인 관련 기능
│ ├── controller/ # 컨트롤러 클래스
│ ├── mapper/ # MyBatis 매퍼 인터페이스
│ ├── model/ # 데이터 모델 클래스
│ └── service/ # 서비스 클래스
└── system/ # 시스템 관리 기능
├── auth/ # 권한 관리
├── code/ # 코드 관리
├── group/ # 그룹 관리
├── menu/ # 메뉴 관리
├── role/ # 역할 관리
└── user/ # 사용자 관리
├── controller/ # 컨트롤러 클래스
├── mapper/ # MyBatis 매퍼 인터페이스
├── model/ # 데이터 모델 클래스
└── service/ # 서비스 클래스
egovframework/
├── config/ # 프레임워크 설정
├── exception/ # 예외 처리
├── filter/ # 필터
├── interceptor/ # 인터셉터
└── util/ # 유틸리티 클래스
```

290
CLAUDE.md
Unescape Escape View File

@ -0,0 +1,290 @@
# 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만)
이 시스템은 포괄적인 감사 추적, 배치 작업 모니터링, 알림 시스템, 파일 처리, 엑셀 처리, 데이터 유효성 검사를 위한 광범위한 유틸리티 기능을 포함합니다.
Write Preview
Loading…
Cancel
Save