Files
korea-research/README.md
2025-07-30 14:13:17 +09:00

397 lines
12 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
```bash
-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 옵션들을 환경에 맞게 설정해 주세요
```bash
-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` 설정이 포함되어 있습니다.
```yaml
jasypt:
encryptor:
password: # 별도 관리
algorithm: # 별도 관리
```
예시:
```yaml
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 매퍼는 별도 위치로 구분됩니다.
```yaml
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`)
```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파일 제공
---
## 📤 파일 업로드
```bash
-Dpath.upload.public=/home/etribe/data/upload
```
파일 저장 구조는 `주제/년월일/파일명`이며, `FileUploadType` Enum에 따라 경로가 결정됩니다.
```java
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 메서드에 어노테이션만 붙이면 자동으로 필드에 값이 주입됩니다.
```java
@UpdateCommand
public void update(UpdateCmd cmd) {
mapper.update(cmd); // updatedAt, updatedBy 자동 주입
}
```
```java
public class UpdateCmd extends AuditCommand {
private Long seq;
}
```
### ✅ 복합적인 CRUD 처리 시
하나의 로직 안에서 insert, update, delete 등 여러 DB 작업이 함께 처리되는 경우, `AuditUtil`의 유틸 메서드를 사용합니다.
```java
// 관리자 등록
mapper.insertAdmin(AuditUtil.create(cmd));
// 관리자 역할 매핑 (다건)
mapper.insertAdminHasRoles(
AuditUtil.create(new SaveAdminHasRoleParam(cmd.getSeq(), cmd.getRoleIds()))
);
```
---
## 🔁 XML 공통 필드 include
```xml
<include refid="common.fields.UpdateBaseSet" />
```
공통 SQL은 `CommonFieldsMapper.xml` 에 정의되어 있습니다.
---
## 📦 패키징 (WAR)
```bash
$ 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}` 등 |
---
## 📋 로그 설정
```bash
-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` |
---
## ❗ 실사지역 설정 주의사항
테스트 계정들은 **실사지역이 `테스트`로 지정**되어 있습니다.
> 이로 인해 해당 계정으로 수집된 데이터는 **통계에 반영되지 않습니다.**
**주의:**⚠️ 통계에 포함되도록 하려면 **실제 실사지역**으로 매핑이 필요합니다.
---