주수현 885b97f4bf Merge branch 'dev' into first_open_fetch
# Conflicts:
#	README.md
#	admin/src/main/resources/mappers/researcher/ResearcherMapper.xml
#	core/src/main/java/app/module/core/usecase/file/updateFile/adapters/persistence/UpdateFileDao.java
2025-07-30 14:43:33 +09:00
2025-07-30 11:00:39 +09:00
2025-07-17 16:55:17 +09:00
2025-05-27 16:34:20 +09:00
2025-06-23 17:32:25 +09:00
2025-05-27 16:34:20 +09:00
2025-05-27 16:34:20 +09:00
2025-05-27 16:34:20 +09:00
2025-07-10 09:18:15 +09:00
2025-07-30 14:13:17 +09:00

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 옵션 설정이 반드시 필요합니다.


🛠️ 적용 방법

  1. VM 옵션 추가

    -Dspring.sql.init.mode=always
    
  2. 서버 재기동

    • 위 옵션을 적용하고 서버를 재기동하면 다음과 같은 동작이 수행됩니다:

      • 모든 테이블 DROP
      • 스키마 재생성 (CREATE)
      • 01.init-data.sql 등의 초기화 SQL 실행
  3. 초기화 완료 후 필수 작업‼️

    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

❗ 실사지역 설정 주의사항

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

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

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


Description
임가경제조사 일계부 시스템
Readme MIT 20 MiB
Languages
HTML 49.6%
JavaScript 31.5%
Java 18.6%
CSS 0.2%
PLpgSQL 0.1%