397 lines
12 KiB
Markdown
397 lines
12 KiB
Markdown
# 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` |
|
||
|
||
---
|
||
|
||
## ❗ 실사지역 설정 주의사항
|
||
|
||
테스트 계정들은 **실사지역이 `테스트`로 지정**되어 있습니다.
|
||
|
||
> 이로 인해 해당 계정으로 수집된 데이터는 **통계에 반영되지 않습니다.**
|
||
|
||
**주의:**⚠️ 통계에 포함되도록 하려면 **실제 실사지역**으로 매핑이 필요합니다.
|
||
|
||
---
|
||
|