리드미 업데이트
This commit is contained in:
539
README.md
539
README.md
@@ -1,404 +1,299 @@
|
||||
# KOREA-RESEARCH 시스템
|
||||
|
||||
# KOREA-RESEARCH
|
||||
## 📌 프로젝트 개요
|
||||
|
||||
**KOREA-RESEARCH**는 임가 패널의 일계부 수집 및 관리를 위한 시스템입니다.
|
||||
이 시스템은 헥사고날 아키텍처(Ports & Adapters) 패턴을 적용한 Spring Boot 기반의 멀티모듈 프레임워크를 기반으로 하여 작성 되었습니다.
|
||||
|
||||
---
|
||||
|
||||
## ✅ Prerequisites
|
||||
|
||||
- JDK 17+
|
||||
- Maven
|
||||
- PostgreSQL
|
||||
|
||||
---
|
||||
|
||||
## 📂 프로젝트 구조
|
||||
|
||||
```
|
||||
┬─┐┌─┐┌─┐┬ ┬┌─┐┬ ┌─┐
|
||||
├┬┘├┤ │ └┬┘│ │ ├┤
|
||||
┴└─└─┘└─┘ ┴ └─┘┴─┘└─┘ - framework for spring developers exploring JPA
|
||||
├── admin # 관리자 어플리케이션
|
||||
├── core # 공통 도메인 및 로직
|
||||
├── front # 사용자 어플리케이션
|
||||
└── pom.xml
|
||||
|
||||
_____\ _______
|
||||
/ \ | /\
|
||||
/_______/ |_____/ \
|
||||
| \ / / /
|
||||
\ \ \/ /
|
||||
\ / \__/_
|
||||
\/ ____ /\
|
||||
/ \ / \
|
||||
/\ \ / /
|
||||
\ \/ /
|
||||
\___\__/
|
||||
|
||||
GNU GENERAL PUBLIC LICENSE
|
||||
Version 3, 29 June 2007
|
||||
|
||||
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
|
||||
Everyone is permitted to copy and distribute verbatim copies
|
||||
of this license document, but changing it is not allowed.
|
||||
```
|
||||
|
||||
## 프로젝트 개요
|
||||
> 모든 애플리케이션은 `core` 모듈을 중심으로 포트, 어댑터 구조로 구성됩니다.
|
||||
|
||||
본 프로젝트는 **헥사고날 아키텍처(Ports & Adapters)** 기반의 Spring Boot 멀티모듈 시스템입니다.
|
||||
도메인 로직과 외부 시스템(웹, DB, 파일 등)을 명확히 분리하여 유지보수성과 확장성을 극대화하였습니다.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* JDK 17+
|
||||
* Maven
|
||||
* PostgreSQL
|
||||
|
||||
## Structure
|
||||
|
||||
recycle 은 `core` 모듈을 기반으로 한 `admin`, `front`, `api` 어플리케이션으로 구성되어 있다.
|
||||
|
||||
```shell
|
||||
.
|
||||
|-- README.md
|
||||
|-- admin # 관리자 어플리케이션
|
||||
| |-- pom.xml
|
||||
| |-- src
|
||||
| `-- target
|
||||
|-- core # 공통 모듈
|
||||
| |-- pom.xml
|
||||
| |-- src
|
||||
| `-- target
|
||||
|-- front # 프론트 어플리케이션
|
||||
| |-- pom.xml
|
||||
| |-- src
|
||||
| `-- target
|
||||
`-- pom.xml
|
||||
`-- README.md
|
||||
```
|
||||
|
||||
⚡ AWS S3 업로드를 이용하지 않는다면, pom.xml 에서 `aws`모듈 관련 내용을 삭제하면 된다.
|
||||
⚡ `admin`, `front`, `api` 중 실제 프로젝트에서 사용할 모듈만 남기고 삭제해주세요.
|
||||
|
||||
✔️ Dockerfile 과 .gitlab-ci.yml 은 삭제해주세요 : ) recycle demo 용이기에 여려분의 프로젝트에서는 의미가 없습니다.
|
||||
|
||||
recycle 의 demo 가 궁금하다면 아래 URL 에서 확인 해주세요.
|
||||
- `recycle-admin` - https://recycle-admin.etribe.co.kr 계정정보 (recycle-super/recycle1@#$)
|
||||
- `recycle-api` - https://recycle-api.etribe.co.kr/swagger-ui/index.html
|
||||
- `recycle-front` - https://recycle-front.etribe.co.kr/ 계정정보 (generalUser/generalUser1@#$)
|
||||
|
||||
### 각 모듈의 내부 구조(헥사고날 아키텍처 예시)
|
||||
### 📦 헥사고날 구조 예시
|
||||
|
||||
```
|
||||
usecase/
|
||||
└── daily/
|
||||
└── expense/
|
||||
├── ports/
|
||||
│ ├── application/
|
||||
│ │ └── DailyExpenseService.java
|
||||
│ ├── DailyExpensePortIn.java
|
||||
│ └── DailyExpensePortOut.java
|
||||
└── adapters/
|
||||
├── persistence/
|
||||
│ └── DailyExpenseDao.java
|
||||
└── web/
|
||||
└── DailyExpenseController.java
|
||||
```
|
||||
- **ports/**: 도메인 서비스 및 인터페이스(Port)
|
||||
- **adapters/**: 외부 시스템(웹, DB 등) 연결 어댑터
|
||||
└── daily/
|
||||
└── expense/
|
||||
├── ports/
|
||||
│ ├── application/
|
||||
│ │ └── DailyExpenseService.java
|
||||
│ ├── DailyExpensePortIn.java
|
||||
│ └── DailyExpensePortOut.java
|
||||
└── adapters/
|
||||
├── persistence/
|
||||
│ └── DailyExpenseDao.java
|
||||
└── web/
|
||||
└── DailyExpenseController.java
|
||||
|
||||
````
|
||||
|
||||
## VM Options
|
||||
---
|
||||
|
||||
프레임워크 실행 시 필요한 자바 VM 옵션은 아래와 같다.
|
||||
## ⚙️ VM Options
|
||||
|
||||
| VM 변수 | 설명 | 설정 값 | 필수여부 |
|
||||
|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|-------------------------|------|
|
||||
| -Dspring.profiles.active | Spring active 프로파일 | local, dev, prod | Y |
|
||||
| -Dapp.initData.core | 어플리케이션 초기 구동에 필요한 필수 데이터 생성여부 | true, false | N |
|
||||
| -Dspring.sql.init.mode | SQL 초기화 모드를 설정 | always, embedded, never | N |
|
||||
| -Dpath.upload.public | 파일 업로드 경로 | 기본값 (~/upload/public) | N |
|
||||
| -Dpath.upload.tmpdir | 임시 파일 업로드 경로 | 기본값 (~/upload/tmpdir) | N |
|
||||
| -Dlogging.file.path | 로그 파일 생성 경로 | 기본값 (~/logs) | N |
|
||||
| -Dfile.encoding | JVM 속성 | `UTF-8` | Y |
|
||||
| -Djava.net.preferIPv4Stack | JVM 속성. 클라이언트 IP체크시 IPv4 형식을 사용하기 위함. | true | Y |
|
||||
| -Dcom.amazonaws.sdk.disableEc2Metadata | aws 모듈의 ec2 metadata 전송 끄기 | true | N |
|
||||
| **-Dserver.port** (2023-03-25 추가) | 서버 포트 (없다면 기본 8080) | 원하는 port | N |
|
||||
| **-Dserver.forward-headers-strategy** (2023-03-25 추가) | 프록시 서버(nginx, apache)에 정의된 `X-Forward-For`, `X-Forwarded-Proto` 설정값을 이용하려면 `native` 로 설정해주면 된다. (내장 컨테이너를 사용하는 경우에만 유효) | `native` | N |
|
||||
| **-Dspring.datasource.driver-class-name** (2023-03-25 추가) | JDBC Driver. 없다면 JDBC URL을 기준으로 JPA가 판단한다. | jdbc 드라이버 | Y |
|
||||
| **-Dspring.datasource.url** (2023-03-25 추가) | JDBC URL | jdbc url | N |
|
||||
| **-Dspring.datasource.username** (2023-03-25 추가) | DB Username | DB 사용자 | Y |
|
||||
| **-Dspring.datasource.password** (2023-03-25 추가) | DB Password | DB 패스워드 | Y |
|
||||
|
||||
|
||||
### VM Options 예시
|
||||
#### `admin`, `front` 모두 사용가능합니다.
|
||||
```
|
||||
-Dspring.profiles.active=local
|
||||
-Dapp.initData.core=false
|
||||
-Dspring.sql.init.mode=never
|
||||
```bash
|
||||
-Dspring.profiles.active=prod
|
||||
-Dserver.port=8081
|
||||
-Dfile.encoding=UTF-8
|
||||
-Djava.net.preferIPv4Stack=true
|
||||
-Dcom.amazonaws.sdk.disableEc2Metadata=true
|
||||
-Dserver.port=8080
|
||||
-Dserver.forward-headers-strategy=native
|
||||
-Dlogging.level.org.springframework.security=DEBUG
|
||||
-Daes.secret-key=092HW829O0A0AVR0
|
||||
-Dpath.upload.storage=LOCAL
|
||||
-Dpath.upload.sftp.public=/home/etribe/data/upload
|
||||
-Dfile.upload.sftp.ip=115.68.193.117
|
||||
-Dfile.upload.sftp.id=etribe
|
||||
-Dfile.upload.sftp.password=Etribe@3415
|
||||
-Dfile.upload.sftp.port=22
|
||||
-Dspring.datasource.hikari.maximum-pool-size=10
|
||||
-Dspring.datasource.hikari.minimum-idle=5
|
||||
-Dspring.datasource.hikari.idle-timeout=120000
|
||||
-Dspring.datasource.hikari.max-lifetime=900000
|
||||
-Dspring.datasource.hikari.connection-timeout=5000
|
||||
-Dspring.datasource.hikari.leak-detection-threshold=30000
|
||||
```
|
||||
** 주의 : 운영서버일 경우 vm옵션 추가
|
||||
-Dspring.profiles.active=prod
|
||||
-Dpath.upload.storage=SFTP
|
||||
-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
|
||||
````
|
||||
|
||||
## 💻 로컬 구동 시 필수 설정
|
||||
|
||||
## JDBC 및 데이터 핸들링 구성 옵션
|
||||
로컬 환경에서 구동 시 아래 JVM 옵션들을 환경에 맞게 설정해 주세요
|
||||
|
||||
### app.initData.core
|
||||
|
||||
```shell
|
||||
-Dapp.initData.core=true # true | false
|
||||
```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
|
||||
```
|
||||
|
||||
어플리케이션 초기 구동에 필요한 필수 데이터 생성여부. 공통코드, 메뉴 정보 및 개발에 필요한 기반 데이터 등이 여기에 해당한다.
|
||||
InitAdminData, InitUriFrontData 등 *ApplicationRunner* 구현체에서 내용을 확인할 수 있다.
|
||||
|
||||
### spring.sql.init.mode
|
||||
|
||||
```shell
|
||||
-Dspring.sql.init.mode=never # always | embedded | never
|
||||
```
|
||||
어플리케이션 초기 구동 시, schema.sql, data.sql 등 SQL 초기화 스크립트 실행 여부를 제어하는 설정.
|
||||
|
||||
* always : 애플리케이션 구동 시 항상 SQL 스크립트를 실행
|
||||
* embedded : 내장 DB(H2 등)일 경우에만 실행
|
||||
* never : SQL 스크립트를 실행하지 않음
|
||||
|
||||
## 데이터 호출 및 응답 처리 방식 가이드
|
||||
> 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` |
|
||||
> 💡 `-Djasypt.encryptor.password`와 `-Djasypt.encryptor.algorithm`는 환경에 따라 **수정 가능**합니다.
|
||||
|
||||
---
|
||||
### 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` |
|
||||
## ⚠️ 로컬 DB 연결 관련 안내
|
||||
|
||||
- #### 🖥️ 서버 렌더링 방식 (SSR)
|
||||
목록 및 상세 화면은 SSR 방식으로 처리할 수 있으며, 상황에 따라 선택적으로 사용합니다.
|
||||
현재 제공된 DB 설정은 **운영 서버용 정보**만 포함되어 있습니다.
|
||||
로컬 환경에서 구동하기 위해서는 **로컬 DB 설정을 별도로 구성해야 합니다.**
|
||||
|
||||
| 기능 | 메서드 | URI | 예시 |
|
||||
|------------|--------|------------------------------|------------------------|
|
||||
| 목록 조회 | GET | `/{resource-name}/list` | `/articles/list` |
|
||||
| 상세 조회 | GET | `/{resource-name}/{id}` | `/articles/1` |
|
||||
* `application-local.yml`에 로컬 DB 접속 정보를 입력해야 합니다.
|
||||
* 운영 DB에 직접 접근하여 개발하지 않도록 주의가 필요합니다
|
||||
* `Jasypt`로 암호화된 DB 계정 정보가 있는 경우, 로컬 비밀번호 복호화를 위한 `encryptor.password`가 반드시 필요합니다.
|
||||
|
||||
## LOG 생성 옵션
|
||||
---
|
||||
## 🔐 Jasypt 암호화
|
||||
|
||||
### logging.file.path
|
||||
* DB 커넥션 정보는 Jasypt로 암호화되어 사용됩니다.
|
||||
* `admin`, `front` 모듈 각각에 `JasyptConfig.java` 설정이 포함되어 있습니다.
|
||||
|
||||
```shell
|
||||
-Dlogging.file.path=~/logs # 기본값 ${user.home}/logs
|
||||
```yaml
|
||||
jasypt:
|
||||
encryptor:
|
||||
password: # 별도 관리
|
||||
algorithm: # 별도 관리
|
||||
```
|
||||
|
||||
로그 파일 생성 경로를 지정한다. 지정된 경로에 아래와 같은 로그 파일이 생성된다.
|
||||
예시:
|
||||
|
||||
```shell
|
||||
admin-app.log # 어드민 전체 로그
|
||||
admin-app-ERROR.log # 어드민 로그 중 ERROR 부분 필터링
|
||||
front-app.log # 프론트 전체 로그
|
||||
front-app-ERROR.log # 프론트 로그 중 ERROR 부분 필터링
|
||||
```yaml
|
||||
spring:
|
||||
datasource:
|
||||
kri:
|
||||
jdbc-url: ENC(...)
|
||||
username: ENC(...)
|
||||
password: ENC(...)
|
||||
mms:
|
||||
jdbc-url: ENC(...)
|
||||
username: ENC(...)
|
||||
password: ENC(...)
|
||||
```
|
||||
|
||||
## File 구성 옵션
|
||||
---
|
||||
|
||||
### 파일 업로드
|
||||
## 🗃️ DB 구성
|
||||
|
||||
```shell
|
||||
-Dpath.upload.public=~/upload/public # 파일 업로드 경로
|
||||
-Dpath.upload.tmpdir=~/upload/tmpdir # tmp 디렉토리 경로
|
||||
| 모듈 | 연결 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
|
||||
```
|
||||
|
||||
파일 업로드 경로가 지정되면 사용자가 업로드한 파일은 이 경로를 기준으로 `주제`/`년월일` 폴더 아래에 저장됩니다.
|
||||
tmpdir 은 서블릿 컨테이너가 multipart 파일 업로드 시 대용량 처리를 위해 임시파일을 저장하는 공간입니다.
|
||||
---
|
||||
|
||||
파일 시스템 외에 AWS S3 로도 업로드해야 한다면, 아래 AWS CLI 를 이용하기 위한 정보를 제공해주어야 합니다.
|
||||
|
||||
```shell
|
||||
-Dapp.aws.s3.accessKey=AKIAZF27HETWNITZBZOF # AMI 에서 발급한 사용자 엑세스 키
|
||||
-Dapp.aws.s3.secretKey=IhnTG0X7Wav8ak3cbYR1l8UAjL+gbnXdWJRM11cx # AMI 에서 발급한 사용자 시크릿 키
|
||||
-Dapp.aws.s3.bucketName=etribe # S3 버킷 이름
|
||||
-Dapp.aws.s3.bucketFolder=/recycle/upload # S3 버킷 디렉토리
|
||||
-Dapp.aws.s3.domain=dixjkmptx5pkm.cloudfront.net # S3 혹은 cloudfront 도메인
|
||||
```
|
||||
|
||||
🔑 위 accessKey 정보는 제가 만든 임시 정보이며, recycle 데모용으로만 사용되니 참고해주세요.
|
||||
|
||||
💡 recycle 은 파일 시스템 업로드와 S3 업로드를 사용 목적에 맞게 선택할 수 있는 유연성을 제공합니다.
|
||||
`FileUploadType`은 파일 업로드가 필요한 주제 도메인들이 정의된 enum 객체입니다. 여기 기술된 `FileStorageType` 속성에 따라 파일 업로드 경로가 결정됩니다.
|
||||
|
||||
### 파일 참조
|
||||
|
||||
업로드된 파일은 참조될 수 있어야 합니다. `fileUrlPortIn`는 파일이 파일 시스템에 있든 S3 에 있든 정확한 참조 URL 을 전달해주는 인터페이스입니다.
|
||||
## 🧩 MyBatis 다중 DB 설정 예시 (`MMSDBConfig.java`)
|
||||
|
||||
```java
|
||||
// 참조 URL 전달 - inline 방식
|
||||
fileUrlPortIn.getInline(
|
||||
uploadFile.getType().getFileStorageType(),
|
||||
uploadFile.getPath(),
|
||||
uploadFile.getName());
|
||||
|
||||
// 참조 URL 전달 - attachment 방식
|
||||
fileUrlPortIn.getAttachment(
|
||||
uploadFile.getType().getFileStorageType(),
|
||||
uploadFile.getId());
|
||||
@MapperScan(
|
||||
basePackages = "app.module.mms.**.persistence",
|
||||
sqlSessionFactoryRef = "mmsSqlSessionFactory")
|
||||
```
|
||||
|
||||
`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() { ... }
|
||||
}
|
||||
```bash
|
||||
-Dpath.upload.public=/home/etribe/data/upload
|
||||
```
|
||||
|
||||
### 2. AOP 기반 어노테이션 자동 주입
|
||||
service 또는 dao 내에
|
||||
@CreateCommand, @UpdateCommand, @DeleteCommand 어노테이션을 통해
|
||||
AOP가 자동으로 해당 메서드의 파라미터(AuditCommand 상속 객체)에 공통 필드를 주입합니다.
|
||||
파일 저장 구조는 `주제/년월일/파일명`이며, `FileUploadType` Enum에 따라 경로가 결정됩니다.
|
||||
|
||||
| 어노테이션 | 자동 설정되는 필드 |
|
||||
| ---------------- | -------------------------------------------------- |
|
||||
| `@CreateCommand` | `createdAt`, `createdBy`, `updatedAt`, `updatedBy` |
|
||||
| `@UpdateCommand` | `updatedAt`, `updatedBy` |
|
||||
| `@DeleteCommand` | `updatedAt`, `updatedBy`, `deletedAt`, `deletedBy` |
|
||||
```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 operate(UpdateCmd cmd) {
|
||||
mapper.update(cmd);
|
||||
public void update(UpdateCmd cmd) {
|
||||
mapper.update(cmd); // updatedAt, updatedBy 자동 주입
|
||||
}
|
||||
```
|
||||
### 3. AOP 외 수동 적용이 필요한 경우: AuditUtil 사용
|
||||
AOP 외에도, 하나의 DAO 메서드 내에서 여러 Insert/Delete 처리가 필요한 경우에는 아래처럼 직접 AuditUtil을 사용할 수 있습니다.
|
||||
#### AuditUtil 사용 예시
|
||||
```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()))
|
||||
);
|
||||
```
|
||||
---
|
||||
|
||||
### 4. XML에서 공통 필드 include로 재사용
|
||||
SQL 작성 시 공통필드의 반복 작성을 피하기 위해 `<sql>` 태그로 분리하여 `<include>` 방식으로 재사용합니다.
|
||||
자세한 정의는 `CommonFieldsMapper.xml` 파일에서 확인할 수 있습니다.
|
||||
## 🔁 XML 공통 필드 include
|
||||
|
||||
| SQL ID | 설명 | 사용 예시 |
|
||||
| ---------------------------- | -------------------------------------- | -------------------------------------------------------------- |
|
||||
| `CreateUpdateBaseColumns` | `INSERT` 시 공통 컬럼 정의 | `<include refid="common.fields.CreateUpdateBaseColumns" />` |
|
||||
| `CreateUpdateBaseValues` | `INSERT` 시 공통 컬럼의 값 정의 | `<include refid="common.fields.CreateUpdateBaseValues" />` |
|
||||
| `CreateUpdateListBaseValues` | `다건 INSERT` 시 공통 값 정의 (e.g. `foreach`) | `<include refid="common.fields.CreateUpdateListBaseValues" />` |
|
||||
| `UpdateBaseSet` | `UPDATE` 시 공통 `SET` 구문 | `<include refid="common.fields.UpdateBaseSet" />` |
|
||||
| `DeleteBaseSet` | `삭제 처리용 UPDATE` 시 공통 `SET` 구문 | `<include refid="common.fields.DeleteBaseSet" />` |
|
||||
|
||||
#### include 사용 예시
|
||||
```xml
|
||||
UPDATE household
|
||||
SET
|
||||
owner_name = #{ownerName},
|
||||
owner_age = #{ownerAge},
|
||||
tel = #{tel},
|
||||
phone = #{phone},
|
||||
region = #{region},
|
||||
city = #{city},
|
||||
address_detail = #{addressDetail},
|
||||
<include refid="common.fields.UpdateBaseSet" /> <!-- 공통 필드 include -->
|
||||
WHERE seq = ${seq}
|
||||
<include refid="common.fields.UpdateBaseSet" />
|
||||
```
|
||||
|
||||
공통 SQL은 `CommonFieldsMapper.xml` 에 정의되어 있습니다.
|
||||
|
||||
## PACKAGING
|
||||
---
|
||||
|
||||
배포방식 설정을 위해 두가지 maven 프로파일을 제공한다.
|
||||
## 📦 패키징 (WAR)
|
||||
|
||||
* `jar` (default)
|
||||
* `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
|
||||
```bash
|
||||
$ mvn clean package -P war
|
||||
```
|
||||
|
||||
## 개발 서버 환경
|
||||
---
|
||||
|
||||
### database - postgresql 14.17
|
||||
## 🔌 API 호출 방식
|
||||
|
||||
```
|
||||
URL: jdbc:postgresql://15.165.180.203:5432/korea_research
|
||||
USERNAME: ko_research
|
||||
PASSWORD: koresearch1@#4
|
||||
### 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 DEPLOY
|
||||
| 파일 이름 | 설명 |
|
||||
| --------------------- | ------------ |
|
||||
| `admin-app.log` | 관리자 전체 로그 |
|
||||
| `admin-app-ERROR.log` | 관리자 에러 전용 로그 |
|
||||
| `front-app.log` | 프론트 전체 로그 |
|
||||
| `front-app-ERROR.log` | 프론트 에러 전용 로그 |
|
||||
|
||||
#### `deploy_dev_admin` 브렌치로 merge! pipeline 실행 후 아래 URL 에서 확인가능.
|
||||
* https://ko-research-admin.etribe.co.kr
|
||||
---
|
||||
|
||||
### 🚀 FRONT DEPLOY
|
||||
## ⏱️ 배치 스케줄러
|
||||
|
||||
`AutoSchedulesController.java`에 정의되어 있으며, 총 3개의 배치가 존재합니다.
|
||||
|
||||
| 배치명 | 실행 주기 | 설명 |
|
||||
| ----------- | ------------ | -------------------------- |
|
||||
| 월별 입력 상태 등록 | 매월 1일 0시 0초 | 월별 입력 상태를 초기화 등록함 |
|
||||
| 문자 자동 발송 | 매일 17시 0분 | mms DB로부터 수신 대상 추출 후 문자 발송 |
|
||||
| 월초 이월금 등록 | 매월 16일 0시 0초 | 이전 달 데이터를 기준으로 이월금 등록 |
|
||||
|
||||
---
|
||||
|
||||
## 👤운영서버 테스트 계정
|
||||
계정 ID | 비밀번호 | 권한 |
|
||||
| ------------ | ------- | ------- |
|
||||
| `koadmin` | `0701!` | 관리자 권한 |
|
||||
| `kolocal` | `0701@` | 지방실사 권한 |
|
||||
| `kosearcher` | `0701#` | 조사원 권한 |
|
||||
|
||||
---
|
||||
|
||||
## 🧾 운영서버 임가 계정 목록
|
||||
|
||||
| 임가번호 | 비밀번호 |
|
||||
|---------| ------ |
|
||||
| `22221` | `1111` |
|
||||
| `22222` | `1111` |
|
||||
|
||||
---
|
||||
|
||||
## ❗ 실사지역 설정 주의사항
|
||||
|
||||
테스트 계정들은 **실사지역이 `테스트`로 지정**되어 있습니다.
|
||||
|
||||
> 이로 인해 해당 계정으로 수집된 데이터는 **통계에 반영되지 않습니다.**
|
||||
|
||||
**주의:**⚠️ 통계에 포함되도록 하려면 **실제 실사지역**으로 매핑이 필요합니다.
|
||||
|
||||
---
|
||||
|
||||
#### `deploy_dev_front` 브렌치로 merge! pipeline 실행 후 아래 URL 에서 확인가능.
|
||||
* https://ko-research-front.etribe.co.kr
|
||||
Reference in New Issue
Block a user