# KOREA-RESEARCH
```
┬─┐┌─┐┌─┐┬ ┬┌─┐┬ ┌─┐
├┬┘├┤ │ └┬┘│ │ ├┤
┴└─└─┘└─┘ ┴ └─┘┴─┘└─┘ - framework for spring developers exploring JPA
_____\ _______
/ \ | /\
/_______/ |_____/ \
| \ / / /
\ \ \/ /
\ / \__/_
\/ ____ /\
/ \ / \
/\ \ / /
\ \/ /
\___\__/
GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc.
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
```
## 프레임워크 개요
본 프로젝트는 **헥사고날 아키텍처(Ports & Adapters)** 기반의 Spring Boot 멀티모듈 시스템입니다.
도메인 로직과 외부 시스템(웹, DB, 파일 등)을 명확히 분리하여 유지보수성과 확장성을 극대화하였습니다.
## Prerequisites
* JDK 17+
* Maven
* PostgreSQL
## Structure
recycle 은 `core` 모듈을 기반으로 한 `admin`, `front` 어플리케이션으로 구성되어 있다.
```shell
.
|-- README.md
|-- admin # 관리자 어플리케이션
| |-- pom.xml
| |-- src
| `-- target
|-- core # 공통 모듈
| |-- pom.xml
| |-- src
| `-- target
|-- front # 프론트 어플리케이션
| |-- pom.xml
| |-- src
| `-- target
`-- pom.xml
`-- README.md
```
### 각 모듈의 내부 구조(헥사고날 아키텍처 예시)
```
usecase/
└── daily/
└── expense/
├── ports/
│ ├── application/
│ │ └── DailyExpenseService.java
│ ├── DailyExpensePortIn.java
│ └── DailyExpensePortOut.java
└── adapters/
├── persistence/
│ └── DailyExpenseDao.java
└── web/
└── DailyExpenseController.java
```
- **ports/**: 도메인 서비스 및 인터페이스(Port)
- **adapters/**: 외부 시스템(웹, DB 등) 연결 어댑터
## VM Options
프레임워크 실행 시 필요한 자바 VM 옵션은 아래와 같다.
| VM 변수 | 설명 | 설정 값 | 필수여부 |
|---------------------------------------------|---------------------------------------|-------------------------|------|
| -Dspring.profiles.active | Spring active 프로파일 | local, dev, prod | Y |
| -Dpath.upload.public | 파일 업로드 경로 | 기본값 (~/upload/tmpdir) | N |
| -Dfile.encoding | JVM 속성 | `UTF-8` | Y |
| -Djava.net.preferIPv4Stack | JVM 속성. 클라이언트 IP체크시 IPv4 형식을 사용하기 위함. | true | Y |
| -Dlogging.level.org.springframework.security | 디버깅 레벨 | true | Y |
| -Daes.secret-key | 암호화 시크릿 키 | true | Y |
| **-Dserver.port** | 서버 포트 (없다면 기본 8080) | 원하는 port | Y |
| **-Dpath.upload.storage** | 파일 저장 방법 | LOCAL | Y |
### VM Options 예시
#### `admin`, `front` 모두 사용가능합니다.
```
-Dspring.profiles.active=local
-Dfile.encoding=UTF-8
-Djava.net.preferIPv4Stack=true
-Dserver.port=8081
-Dlogging.level.org.springframework.security=DEBUG
-Daes.secret-key=092HW829O0A0AVR0
-Dpath.upload.storage=LOCAL
-Djasypt.encryptor.password=ko-research (변경 필요)
-Djasypt.encryptor.algorithm=PBEWITHHMACSHA512ANDAES_256
```
** 주의 : 현재 코리아 리서치의 운영서버밖에 존재하지않으므로 개발서버의 세팅 필요 **
```
-Dspring.profiles.active=local
-Dpath.upload.storage=LOCAL
-Djasypt.encryptor.password=ko-research
-Djasypt.encryptor.algorithm=PBEWITHHMACSHA512ANDAES_256
```
## DB 설정
### admin
kri DB, mms DB(문자 발송) 두개의 DB 커넥션 존재
### front
kri DB 한개의 DB 커넥션 존재
datasource:
kri:
driver-class-name: org.postgresql.Driver
jdbc-url: ENC(mF3Z0fgCagFruOk/F2Z2PYzXhwGedE1secfYDgci+ke9z8xFEZ/GWbgXA4XeSq5D+k9/oRLOxzwx/D24tswdoHdQugHmGb0UqrW4vGBa7YFJvcnWylOpd5ppUeEIUJGv)
username: ENC(cNXntROGOeM115QfLlVhhBz8+qY70eTWwmwLM+7AMslWmfWTq9ZPl4pVnDopJauM)
password: ENC(kUIzqWTu0+bqjYH4Jq9TFOOh3UwY+XVvA2OlT4VXJvxWCas66UNdGRmWDQKri5fI)
mms:
driver-class-name: org.postgresql.Driver
jdbc-url: ENC(TZ7H8DIFZDbsNp3PRWbz3bkJbjsx3580ljmELMJInASgpiEH66Lb8adpjt5WGXoIdZbHetlgtEFo8F+U8XUa9fjYWNOpiZ+D99XoXJUOP3s=)
username: ENC(cNXntROGOeM115QfLlVhhBz8+qY70eTWwmwLM+7AMslWmfWTq9ZPl4pVnDopJauM)
password: ENC(kUIzqWTu0+bqjYH4Jq9TFOOh3UwY+XVvA2OlT4VXJvxWCas66UNdGRmWDQKri5fI)
maximum-pool-size: 2
minimum-idle: 1
app.module.admin.config.application.bean.JasyptConfig
## JDBC 및 데이터 핸들링 구성 옵션
### app.initData.core
```shell
-Dapp.initData.core=true # true | false
```
## 데이터 호출 및 응답 처리 방식 가이드
> BO(Back Office)와 FO(Front Office) 화면에서는 기능에 따라 **Ajax 호출 방식**과 **서버 렌더링 방식(Server-Side Rendering, SSR)을** 구분하여 사용합니다.
### BO (Back Office: 관리자 화면)
- #### 📡 Ajax 호출 방식 (REST API, JSON 응답)
다음 기능은 Ajax를 통해 REST API(JSON)를 호출합니다
| 기능 | 메서드 | URI | 예시 |
|----------|----------|------------------------------------|------------------------|
| 목록 조회 | GET | `/api/{resource-name}/list` | `/api/articles/list` |
| 등록 | POST | `/api/{resource-name}/create` | `/api/articles/create` |
| 수정 | PUT/PATCH | `/api/{resource-name}/update` | `/api/articles/update` |
| 삭제 | DELETE | `/api/{resource-name}/remove` | `/api/articles/remove` |
| 등록 & 수정 |POST | `/api/{resource-name}/save` | `/api/articles/save` |
- #### 🖥️ 서버 렌더링 방식 (SSR)
상세 조회(view) 화면은 SSR 방식으로 처리합니다.
| 기능 | 메서드 | URI | 예시 |
|------------|--------|------------------------|---------------|
| 상세 조회 | GET | `/{resource-name}/{id}` | `/articles/1` |
---
### FO (Front Office: 사용자 화면)
- #### 📡 Ajax 호출 방식 (REST API, JSON 응답)
다음 기능은 Ajax 기반 REST API 호출로 처리합니다.
| 기능 | 메서드 | URI | 예시 |
|------|------------|-------------------------|--------------------------|
| 등록 | POST | `/api/{resource-name}/create` | `/api/articles/create` |
| 수정 | PUT/PATCH | `/api/{resource-name}/update` | `/api/articles/update` |
| 삭제 | DELETE | `/api/{resource-name}/remove` | `/api/articles/remove` |
- #### 🖥️ 서버 렌더링 방식 (SSR)
목록 및 상세 화면은 SSR 방식으로 처리할 수 있으며, 상황에 따라 선택적으로 사용합니다.
| 기능 | 메서드 | URI | 예시 |
|------------|--------|------------------------------|------------------------|
| 목록 조회 | GET | `/{resource-name}/list` | `/articles/list` |
| 상세 조회 | GET | `/{resource-name}/{id}` | `/articles/1` |
## LOG 생성 옵션
### logging.file.path
```shell
-Dlogging.file.path=~/logs # 기본값 ${user.home}/logs
```
로그 파일 생성 경로를 지정한다. 지정된 경로에 아래와 같은 로그 파일이 생성된다.
```shell
admin-app.log # 어드민 전체 로그
admin-app-ERROR.log # 어드민 로그 중 ERROR 부분 필터링
front-app.log # 프론트 전체 로그
front-app-ERROR.log # 프론트 로그 중 ERROR 부분 필터링
```
## File 구성 옵션
### 파일 업로드
```shell
-Dpath.upload.public=~/upload/public # 파일 업로드 경로
```
파일 업로드 경로가 지정되면 사용자가 업로드한 파일은 이 경로를 기준으로 `주제`/`년월일` 폴더 아래에 저장됩니다.
🔑 위 accessKey 정보는 제가 만든 임시 정보이며, recycle 데모용으로만 사용되니 참고해주세요.
💡
`FileUploadType`은 파일 업로드가 필요한 주제 도메인들이 정의된 enum 객체입니다. 여기 path.upload.storage 옵션에 따라 파일 업로드 경로가 결정됩니다.
### 파일 참조
업로드된 파일은 참조될 수 있어야 합니다. `fileUrlPortIn`는 파일이 파일 시스템에 있든 S3 에 있든 정확한 참조 URL 을 전달해주는 인터페이스입니다.
```java
// 참조 URL 전달 - inline 방식
fileUrlPortIn.getInline(
uploadFile.getType().getFileStorageType(),
uploadFile.getPath(),
uploadFile.getName());
// 참조 URL 전달 - attachment 방식
fileUrlPortIn.getAttachment(
uploadFile.getType().getFileStorageType(),
uploadFile.getId());
```
`inline` 과 `attachment` 는 응답 헤더의 content-disposition 속성 값을 의미합니다.
업로드된 파일은 사용자에게 전달할 때 `inline` 과 `attachment` 두 방식 중 요건에 맞게 사용하면 됩니다.
## 공통 필드(Audit) 자동 주입 방법 (AOP기반)
createdAt, createdBy, updatedAt, updatedBy, deletedAt, deletedBy, isDeleted 와 같은 공통 이력 필드는
매번 수동으로 설정하지 않아도 되도록, AOP를 활용해 자동으로 주입되도록 구성했습니다.
### 1. 기본 구조
create, update, delete 시 Command 객체에 AuditCommand를 상속합니다.
#### AuditCommand 사용 예시
``` java
// 필수: AuditCommand 상속
public class UpdateCmd extends AuditCommand {
private Long seq;
...
}
```
AuditCommand는 아래 메서드를 제공하며, 각각 생성/수정/삭제 작업에 필요한 필드를 자동으로 설정합니다.
``` java
public class AuditCommand {
private LocalDateTime createdAt;
private String createdBy;
private LocalDateTime updatedAt;
private String updatedBy;
private LocalDateTime deletedAt;
private String deletedBy;
public void create() { ... }
public void update() { ... }
public void delete() { ... }
}
```
### 2. AOP 기반 어노테이션 자동 주입
service 또는 dao 내에
@CreateCommand, @UpdateCommand, @DeleteCommand 어노테이션을 통해
AOP가 자동으로 해당 메서드의 파라미터(AuditCommand 상속 객체)에 공통 필드를 주입합니다.
| 어노테이션 | 자동 설정되는 필드 |
| ---------------- | -------------------------------------------------- |
| `@CreateCommand` | `createdAt`, `createdBy`, `updatedAt`, `updatedBy` |
| `@UpdateCommand` | `updatedAt`, `updatedBy` |
| `@DeleteCommand` | `updatedAt`, `updatedBy`, `deletedAt`, `deletedBy` |
#### 어노테이션 사용 예시
```java
@UpdateCommand
public void operate(UpdateCmd cmd) {
mapper.update(cmd);
}
```
### 3. AOP 외 수동 적용이 필요한 경우: AuditUtil 사용
AOP 외에도, 하나의 DAO 메서드 내에서 여러 Insert/Delete 처리가 필요한 경우에는 아래처럼 직접 AuditUtil을 사용할 수 있습니다.
#### AuditUtil 사용 예시
```java
// 관리자 등록
mapper.insertAdmin(AuditUtil.create(cmd));
// 관리자의 역할 매핑
mapper.insertAdminHasRoles(
AuditUtil.create(new SaveAdminHasRoleParam(cmd.getSeq(), cmd.getRoleIds()))
);
```
### 4. XML에서 공통 필드 include로 재사용
SQL 작성 시 공통필드의 반복 작성을 피하기 위해 `` 태그로 분리하여 `` 방식으로 재사용합니다.
자세한 정의는 `CommonFieldsMapper.xml` 파일에서 확인할 수 있습니다.
| SQL ID | 설명 | 사용 예시 |
| ---------------------------- | -------------------------------------- | -------------------------------------------------------------- |
| `CreateUpdateBaseColumns` | `INSERT` 시 공통 컬럼 정의 | `` |
| `CreateUpdateBaseValues` | `INSERT` 시 공통 컬럼의 값 정의 | `` |
| `CreateUpdateListBaseValues` | `다건 INSERT` 시 공통 값 정의 (e.g. `foreach`) | `` |
| `UpdateBaseSet` | `UPDATE` 시 공통 `SET` 구문 | `` |
| `DeleteBaseSet` | `삭제 처리용 UPDATE` 시 공통 `SET` 구문 | `` |
#### include 사용 예시
```xml
UPDATE household
SET
owner_name = #{ownerName},
owner_age = #{ownerAge},
tel = #{tel},
phone = #{phone},
region = #{region},
city = #{city},
address_detail = #{addressDetail},
WHERE seq = ${seq}
```
## PACKAGING
배포방식 설정을 위해 두가지 maven 프로파일을 제공한다.
* `war` Jeus, WebLogic, Tomcat 등 별도 외장 컨테이너 이용시 사용
maven 빌드 시 프로파일을 지정하지 않으면 기본 `jar` 프로파일로 동작하고, `war` 의 경우 명시적인 지정이 필요하다.
아래는 admin 빌드시 `war` 프로파일을 지정한 예시이다.
```shell
$ mvn --projects admin --also-make clean package -DskipTests -P war
# 빌드 후, admin/target 디렉토리에 war 가 생성된걸 확인할 수 있다.
$ ll admin/target
-rw-r--r-- 1 user 197121 94905770 4월 22 09:59 admin-0.0.1-SNAPSHOT.war
```
### 운영서버 배포 스크립트
## SFTP 접근
```
sftp로 접속 가능
IP: 115.68.193.117
ID: etribe
PW: Etribe@3415
```
### 1. war 파일 생성
```
mvn clean package -P war
```
### 2. SFTP 파일 업로드
```
/home/etribe/data/upload/tmp
```
### 3. putty 접속 : root 계정으로 변경
```
sudo su-
```
### 4. war 파일 옮기기
```
sudo mv /home/etribe/data/upload/tmp/admin/ROOT.war /opt/admin-tomcat/webapps/
sudo mv /home/etribe/data/upload/tmp/front/ROOT.war /opt/front-tomcat/webapps/
```
### 5. 파일 소유자 변경
```
sudo chown -R root:root /opt/admin-tomcat
sudo chown -R root:root /opt/front-tomcat
```
### 6. 권한 확인
```
ls -l /opt/admin-tomcat/webapps/
ls -l /opt/front-tomcat/webapps/
```
### 7. 톰캣 shutdown
```
sudo /opt/admin-tomcat/bin/shutdown.sh
sudo /opt/front-tomcat/bin/shutdown.sh
or
sudo netstat -tulnp | grep 3415
sudo netstat -tulnp | grep 3416
sudo kill -9
```
### 8. 배포 되었던 ROOT 파일 백업본으로
```
sudo mv /opt/admin-tomcat/webapps/ROOT /opt/admin-tomcat/webapps/ROOT.bak
sudo mv /opt/front-tomcat/webapps/ROOT /opt/front-tomcat/webapps/ROOT.bak
```
### 9. 기존 war 파일 삭제
```
rm -r /opt/admin-tomcat/webapps/ROOT.war
rm -r /opt/front-tomcat/webapps/ROOT.war
```
### 10. 톰캣 start
```
sudo /opt/admin-tomcat/bin/startup.sh
sudo /opt/front-tomcat/bin/startup.sh
```
## vm option
```
sudo vi /opt/admin-tomcat/bin/setenv.sh
sudo vi /opt/front-tomcat/bin/setenv.sh
```