e5fd89049e1a8d2d5d8b5fd082dc4414a8933cdf
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
-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는 환경에 따라 수정 가능합니다.
🔐 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")
📤 파일 업로드
-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 |
❗ 실사지역 설정 주의사항
테스트 계정들은 실사지역이 테스트로 지정되어 있습니다.
이로 인해 해당 계정으로 수집된 데이터는 통계에 반영되지 않습니다.
주의:⚠️ 통계에 포함되도록 하려면 실제 실사지역으로 매핑이 필요합니다.
Languages
HTML
49.6%
JavaScript
31.5%
Java
18.6%
CSS
0.2%
PLpgSQL
0.1%