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