Files
korea-research/README.md
2025-07-29 16:05:50 +09:00

7.5 KiB

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

❗ 실사지역 설정 주의사항

테스트 계정들은 실사지역이 테스트로 지정되어 있습니다.

이로 인해 해당 계정으로 수집된 데이터는 통계에 반영되지 않습니다.

주의:⚠️ 통계에 포함되도록 하려면 실제 실사지역으로 매핑이 필요합니다.