278 lines
7.2 KiB
Markdown
278 lines
7.2 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")
|
|
```
|
|
|
|
## 📤 파일 업로드
|
|
|
|
```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`
|
|
|
|
```java
|
|
@UpdateCommand
|
|
public void update(UpdateCmd cmd) {
|
|
mapper.update(cmd);
|
|
}
|
|
```
|
|
|
|
복수 등록 또는 복합 로직은 `AuditUtil.create()` 방식 사용
|
|
|
|
---
|
|
|
|
## 🔁 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` |
|
|
|
|
---
|
|
|
|
## ❗ 실사지역 설정 주의사항
|
|
|
|
테스트 계정들은 **실사지역이 `테스트`로 지정**되어 있습니다.
|
|
|
|
> 이로 인해 해당 계정으로 수집된 데이터는 **통계에 반영되지 않습니다.**
|
|
|
|
**주의:**⚠️ 통계에 포함되도록 하려면 **실제 실사지역**으로 매핑이 필요합니다.
|
|
|
|
---
|
|
|