KOREA-RESEARCH 시스템
📌 프로젝트 개요
KOREA-RESEARCH는 임가 패널의 일계부 수집 및 관리를 위한 시스템입니다. 이 시스템은 헥사고날 아키텍처(Ports & Adapters) 패턴을 적용한 Spring Boot 기반의 멀티모듈 프레임워크를 기반으로 하여 작성 되었습니다.
✅ Prerequisites
- JDK 17+
- Maven
- PostgreSQL
📂 프로젝트 구조
├── admin # 관리자 어플리케이션
├── core # 공통 도메인 및 로직
├── front # 사용자 어플리케이션
└── pom.xml
모든 애플리케이션은
core모듈을 중심으로 포트, 어댑터 구조로 구성됩니다.
📦 헥사고날 구조 예시
usecase/
└── daily/
└── expense/
├── ports/
│ ├── application/
│ │ └── DailyExpenseService.java
│ ├── DailyExpensePortIn.java
│ └── DailyExpensePortOut.java
└── adapters/
├── persistence/
│ └── DailyExpenseDao.java
└── web/
└── DailyExpenseController.java
⚙️ VM Options
-Dspring.profiles.active=prod
-Dserver.port=8081
-Dfile.encoding=UTF-8
-Dspring.sql.init.mode=never
-Djava.net.preferIPv4Stack=true
-Dlogging.level.org.springframework.security=DEBUG
-Daes.secret-key=092HW829O0A0AVR0
-Dpath.upload.storage=LOCAL
-Dpath.upload.public=/home/etribe/data/upload
-Dpath.upload.tmpdir=/home/etribe/data/upload/tmp
-Djasypt.encryptor.password=ko-research
-Djasypt.encryptor.algorithm=PBEWITHHMACSHA512ANDAES_256
💻 로컬 구동 시 필수 설정
로컬 환경에서 구동 시 아래 JVM 옵션들을 환경에 맞게 설정해 주세요
-Dspring.profiles.active=local
-Dpath.upload.public=/home/etribe/data/upload
-Dpath.upload.tmpdir=/home/etribe/data/upload/tmp
-Djasypt.encryptor.password=ko-research
-Djasypt.encryptor.algorithm=PBEWITHHMACSHA512ANDAES_256
💡
-Djasypt.encryptor.password와-Djasypt.encryptor.algorithm는 환경에 따라 수정 가능합니다.
⚠️ 로컬 DB 연결 관련 안내
현재 제공된 DB 설정은 운영 서버용 정보만 포함되어 있습니다. 로컬 환경에서 구동하기 위해서는 로컬 DB 설정을 별도로 구성해야 합니다.
application-local.yml에 로컬 DB 접속 정보를 입력해야 합니다.- 운영 DB에 직접 접근하여 개발하지 않도록 주의가 필요합니다
Jasypt로 암호화된 DB 계정 정보가 있는 경우, 로컬 비밀번호 복호화를 위한encryptor.password가 반드시 필요합니다.
--
다음은 -Dspring.sql.init.mode=always 옵션 관련 내용을 인수인계 문서 형식으로 정리한 예시입니다. 운영 환경에서의 위험성까지 강조해서 작성했습니다.
⚙️ 로컬 DB 초기화 및 initData 적용 방법
✅
Spring Boot 프로젝트에서는 initData SQL 스크립트를 통해 로컬 DB에 초기 데이터를 삽입할 수 있습니다. 이를 위해 VM 옵션 설정이 반드시 필요합니다.
🛠️ 적용 방법
-
VM 옵션 추가
-Dspring.sql.init.mode=always -
서버 재기동
-
위 옵션을 적용하고 서버를 재기동하면 다음과 같은 동작이 수행됩니다:
- 모든 테이블 DROP
- 스키마 재생성 (CREATE)
01.init-data.sql등의 초기화 SQL 실행
-
-
초기화 완료 후 필수 작업‼️
VM 옵션을 반드시 아래와 같이 변경: -Dspring.sql.init.mode=never- 계속
always상태로 두면, 서버 기동 시마다 데이터가 모두 삭제됨 ⚠️⚠️⚠️
- 계속
⚠️ 운영 환경 주의사항
💥 운영 서버에는 절대
-Dspring.sql.init.mode=always설정을 사용하지 마세요!! 이 설정은 모든 테이블과 데이터를 제거하고 다시 생성하므로, 운영 DB에 적용 시 치명적인 데이터 손실이 발생할 수 있습니다.
ℹ️ 옵션 설명
| 옵션값 | 설명 |
|---|---|
never |
SQL 초기화 스크립트 실행하지 않음 (기본) |
always |
SQL 초기화 스크립트 항상 실행함 |
📁 초기화 스크립트 위치 예시
core/src/main/resources/sql/schema/02_create-table.sql(DDL)core/src/main/resources/sql/schema/02_create-function.sql(DDL)core/src/main/resources/sql/schema/02_create-view.sql(DDL)core/src/main/resources/sql/data/01_init_data.sql(DML)
🔐 Jasypt 암호화
- DB 커넥션 정보는 Jasypt로 암호화되어 사용됩니다.
admin,front모듈 각각에JasyptConfig.java설정이 포함되어 있습니다.
jasypt:
encryptor:
password: # 별도 관리
algorithm: # 별도 관리
예시:
spring:
datasource:
kri:
jdbc-url: ENC(...)
username: ENC(...)
password: ENC(...)
mms:
jdbc-url: ENC(...)
username: ENC(...)
password: ENC(...)
🗃️ DB 구성
| 모듈 | 연결 DB |
|---|---|
admin |
kri DB, mms DB (문자 발송용) |
front |
kri DB |
🔄 다중 DB 설정 (admin)
admin모듈에는MMSDBConfig.java를 통한 mms 전용 DataSource 설정이 있습니다.- MyBatis 매퍼는 별도 위치로 구분됩니다.
mybatis:
mapper-locations:
kri: classpath*:mappers/**/*Mapper.xml
mms: classpath*:mappers/mms/*Mapper.xml
configuration:
log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
🧩 MyBatis 다중 DB 설정 예시 (MMSDBConfig.java)
@MapperScan(
basePackages = "app.module.mms.**.persistence",
sqlSessionFactoryRef = "mmsSqlSessionFactory")
🔧 일계부 등록 가능 날짜
DailyRecordConstants.java는 일계부 등록 및 수정 가능 시점에 대한 정책 상수를 정의하고 있습니다.
✅ 정책 정의
| 항목 | 정책 설명 | 상수명 | 값 |
|---|---|---|---|
| 등록 가능 월 | 해당 월 기준, 이전 월만 등록 가능 | REGISTER_LIMIT_MONTH |
1 → 임시로 4 설정 중 |
| 등록 가능 일 | 해당 월 15일까지만 등록 가능 | REGISTER_LIMIT_DAY |
15 → 임시로 31 설정 중 |
| 수정 가능 월 | 해당 월 기준, 이전 월만 수정 가능 | MODIFY_LIMIT_MONTH |
1 → 임시로 4 설정 중 |
| 수정 가능 일 | 해당 월 15일까지만 수정 가능 | MODIFY_LIMIT_DAY |
15 → 임시로 31 설정 중 |
⚠️ 현재 임시 설정 사항
현재 시스템에서는 등록 가능 월(REGISTER_LIMIT_MONTH) 및 수정 가능 월(MODIFY_LIMIT_MONTH) 값을 **임시로 4달 등록 가능 일(REGISTER_LIMIT_DAY) 및 수정 가능 일(MODIFY_LIMIT_DAY) 값을 임시로 31일로 설정해 두었으며,
정책상 원래는 15일로 제한되어야 합니다.
📌 향후 운영 정책에 따라 **
이전월15일로 복원 예정으로 해당값으로 수정한 war파일 제공
📤 파일 업로드
-Dpath.upload.public=/home/etribe/data/upload
파일 저장 구조는 주제/년월일/파일명이며, FileUploadType Enum에 따라 경로가 결정됩니다.
fileUrlPortIn.getInline(type, path, name);
fileUrlPortIn.getAttachment(type, id);
🧾 Audit 공통 필드 자동 주입
- AOP 기반 자동 주입 방식으로 생성/수정/삭제 시 필드 반복을 최소화합니다.
- 공통 필드:
createdAt,createdBy,updatedAt,updatedBy,deletedAt,deletedBy,isDeleted
| 어노테이션 | 주입 필드 |
|---|---|
@CreateCommand |
createdAt, createdBy, updatedAt, updatedBy |
@UpdateCommand |
updatedAt, updatedBy |
@DeleteCommand |
deletedAt, deletedBy |
✅ 기본 사용법
모든 Command는 AuditCommand를 상속하고, Service/DAO 메서드에 어노테이션만 붙이면 자동으로 필드에 값이 주입됩니다.
@UpdateCommand
public void update(UpdateCmd cmd) {
mapper.update(cmd); // updatedAt, updatedBy 자동 주입
}
public class UpdateCmd extends AuditCommand {
private Long seq;
}
✅ 복합적인 CRUD 처리 시
하나의 로직 안에서 insert, update, delete 등 여러 DB 작업이 함께 처리되는 경우, AuditUtil의 유틸 메서드를 사용합니다.
// 관리자 등록
mapper.insertAdmin(AuditUtil.create(cmd));
// 관리자 역할 매핑 (다건)
mapper.insertAdminHasRoles(
AuditUtil.create(new SaveAdminHasRoleParam(cmd.getSeq(), cmd.getRoleIds()))
);
🔁 XML 공통 필드 include
<include refid="common.fields.UpdateBaseSet" />
공통 SQL은 CommonFieldsMapper.xml 에 정의되어 있습니다.
📦 패키징 (WAR)
$ mvn clean package -P war
🔌 API 호출 방식
BO (관리자)
| 기능 | 방식 | URI 예시 |
|---|---|---|
| 목록/등록 등 | Ajax | /api/household/daily/list, /save 등 |
| 상세 조회 | SSR | /household/{id} |
FO (사용자)
| 기능 | 방식 | URI 예시 |
|---|---|---|
| 등록/수정/삭제 | Ajax | /api/record/income/{searchMonth}/{groupNo}/form/{id} 등 |
| 목록/상세 조회 | SSR | /record/income/{searchMonth}/{groupNo}, /form/{id} 등 |
📋 로그 설정
-Dlogging.file.path=~/logs
| 파일 이름 | 설명 |
|---|---|
admin-app.log |
관리자 전체 로그 |
admin-app-ERROR.log |
관리자 에러 전용 로그 |
front-app.log |
프론트 전체 로그 |
front-app-ERROR.log |
프론트 에러 전용 로그 |
⏱️ 배치 스케줄러
AutoSchedulesController.java에 정의되어 있으며, 총 3개의 배치가 존재합니다.
| 배치명 | 실행 주기 | 설명 |
|---|---|---|
| 월별 입력 상태 등록 | 매월 1일 0시 0초 | 월별 입력 상태를 초기화 등록함 |
| 문자 자동 발송 | 매일 17시 0분 | mms DB로부터 수신 대상 추출 후 문자 발송 |
| 월초 이월금 등록 | 매월 16일 0시 0초 | 이전 달 데이터를 기준으로 이월금 등록 |
👤운영서버 테스트 계정
| 계정 ID | 비밀번호 | 권한 |
|---|---|---|
koadmin |
0701! |
관리자 권한 |
kolocal |
0701@ |
지방실사 권한 |
kosearcher |
0701# |
조사원 권한 |
🧾 운영서버 임가 계정 목록
| 임가번호 | 비밀번호 |
|---|---|
22221 |
1111 |
22222 |
1111 |
22223 |
1111 |
22224 |
1111 |
22225 |
1111 |
22226 |
1111 |
❗ 실사지역 설정 주의사항
테스트 계정들은 실사지역이 테스트로 지정되어 있습니다.
이로 인해 해당 계정으로 수집된 데이터는 통계에 반영되지 않습니다.
주의:⚠️ 통계에 포함되도록 하려면 실제 실사지역으로 매핑이 필요합니다.