Skip to content

docs: ERD 추가 및 시퀀스 다이어그램 경로 수정 #244

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jihukimme merged 1 commit into from
Oct 9, 2025
Merged

docs: ERD 추가 및 시퀀스 다이어그램 경로 수정 #244

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 65 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,15 @@

1. [서비스 개요](#1-서비스-개요)
2. [시스템 개요](#2-시스템-개요)
3. [시스템 아키텍처](#3-시스템-아키텍처)
4. [유스케이스 다이어그램](#4-유스케이스-다이어그램)
5. [시퀀스 다이어그램](#5-시퀀스-다이어그램)
6. [기술 스택](#6-기술-스택)
7. [주요 구성 요소 및 역할](#7-주요-구성-요소-및-역할)
8. [프로젝트 디렉토리 구조](#8-프로젝트-디렉토리-구조)
9. [환경 변수 관리 전략](#9-환경-변수-관리-전략)
10. [시연 영상](#10-시연-영상)
3. [데이터 베이스 설계(ERD)](#3-데이터베이스-설계-erd)
4. [시스템 아키텍처](#4-시스템-아키텍처)
5. [유스케이스 다이어그램](#5-유스케이스-다이어그램)
6. [시퀀스 다이어그램](#6-시퀀스-다이어그램)
7. [기술 스택](#7-기술-스택)
8. [주요 구성 요소 및 역할](#8-주요-구성-요소-및-역할)
9. [프로젝트 디렉토리 구조](#9-프로젝트-디렉토리-구조)
10. [환경 변수 관리 전략](#10-환경-변수-관리-전략)
11. [시연 영상](#11-시연-영상)

---

Expand All @@ -36,7 +37,51 @@

---

## 3. 시스템 아키텍처
## 3. 데이터베이스 설계 (ERD)

서비스의 모든 데이터를 관리하고 워크플로우의 실행 상태를 추적하기 위해, 역할과 책임에 따라 정규화된 데이터베이스 스키마를 설계했습니다.

### 3.1. 최종 ERD

* **ERD 다이어그램**: [ERDCloud 바로가기](https://www.erdcloud.com/d/xkfSpzL2LrRQyCShx)

### 3.2. ERD 설명 및 설계 원칙

데이터베이스는 크게 **'워크플로우 정의', '실행 이력', '사용자 및 조직'** 세 가지 핵심 영역으로 구성됩니다.

#### **1. 핵심 도메인 테이블**
* **워크플로우 정의 계층**: `WORKFLOW`, `JOB`, `TASK` 및 관계 테이블(`WORKFLOW_JOB`, `JOB_TASK`)
* **실행 이력 계층**: `WORKFLOW_RUN`, `JOB_RUN`, `TASK_RUN`, `TASK_IO_DATA`, `EXECUTION_LOG`
* **사용자 및 권한 계층**: `USER`, `ORGANIZATION`, `ROLE`, `PERMISSION`

#### **2. JSON 타입을 활용한 동적 설정 관리**

워크플로우의 **유연성과 재사용성**을 극대화하기 위해, `TASK`와 `WORKFLOW` 테이블의 설정 관련 컬럼에 `JSON` 데이터 타입을 적극적으로 활용했습니다.

* **`TASK` 테이블의 `parameters` 컬럼**:
* **역할**: Task의 **'정적 설계도(Blueprint)'** 역할을 합니다.
* **내용**: 해당 Task를 실행하기 위해 필요한 고정 정보(예: `endpoint`, `method`)와, Request Body의 **구조 및 각 필드의 데이터 타입**을 JSON 형태로 정의합니다.
* **예시**: `{"endpoint": "/keywords/search", "method": "POST", "body": {"tag": "String"}}`

* **`WORKFLOW` 테이블의 `default_config` 컬럼**:
* **역할**: 워크플로우가 실행될 때 각 Task에 주입될 **'동적 설정값(Dynamic Configuration)'** 역할을 합니다.
* **내용**: JSON 객체 형태로, `key`는 `task_id`, `value`는 해당 Task에만 적용될 설정값을 가집니다. 이 값은 `TASK`의 `parameters`에 정의된 구조를 덮어쓰거나(override) 보완합니다.
* **예시**: `{"1": {"tag": "google_trends"}, "2": {"some_param": 123}}`

* **JSON 타입 채택 이유 (유연성 및 재사용성)**:
* **스키마 변경 없는 확장**: 만약 새로운 Task에 `timeout`이라는 파라미터가 추가되더라도, DB 스키마를 변경(`ALTER TABLE`)할 필요 없이 `parameters` JSON의 내용만 수정하면 됩니다. 이는 잦은 변경과 확장이 예상되는 플랫폼에서 **변경에 대한 유연성**을 극대화합니다.
* **Task의 재사용성 증대**: `TASK`는 순수한 '템플릿'으로 존재하고, 실제 동작에 필요한 구체적인 값은 `WORKFLOW`의 `default_config`를 통해 주입됩니다. 이 덕분에 동일한 '키워드 검색 태스크'를 A 워크플로우에서는 `naver`로, B 워크플로우에서는 `google_trends`로 **재배포 없이** 다르게 동작시킬 수 있어 **Task의 재사용성**이 크게 향상됩니다.
* **구조적 데이터 저장**: 단순 `TEXT` 타입과 달리, Key-Value 형태의 구조적인 데이터를 저장할 수 있어 애플리케이션에서 데이터를 파싱하고 사용하기 용이합니다.

#### **3. 기타 설계 원칙**

* **네이밍 컨벤션**: 일관성을 위해 테이블 이름은 **단수형**(`user`, `workflow`)으로, PK는 `[table_name]_id` 형식(`workflow_id`)으로 통일했습니다.
* **외래 키(FK) 제약 조건 미설정**: 물리적인 FK 제약 대신 **애플리케이션 레이어에서 참조 무결성을 보장**하여, 데이터 마이그레이션과 배포 유연성을 확보했습니다.
* **인조키(Surrogate Key) 사용**: 다대다 관계의 중간 테이블에도 독립적인 인조키를 PK로 사용하여 **JOIN 성능을 향상**시키고 유지보수성을 높였습니다.

---

## 4. 시스템 아키텍처

역할과 책임을 명확히 분리하기 위해 `Spring Boot`가 **Orchestrator**, `FastAPI`가 **Worker** 역할을 수행하는 이중 레이어 아키텍처를 채택했습니다.

Expand All @@ -48,7 +93,7 @@

---

## 4. 유스케이스 다이어그램
## 5. 유스케이스 다이어그램

시스템의 주요 액터는 **관리자(Admin)** 와 **스케줄러(Scheduler)** 입니다.
관리자는 워크플로우와 스케줄을 관리하고 수동 실행이 가능하며, 스케줄러는 자동 실행을 담당합니다.
Expand All @@ -57,9 +102,9 @@

---

## 5. 시퀀스 다이어그램
## 6. 시퀀스 다이어그램

### 5.1. 워크플로우 실행 흐름 (스케줄/수동)
### 6.1. 워크플로우 실행 흐름 (스케줄/수동)

1. **트리거**: Quartz 스케줄러 또는 사용자의 `POST /v0/workflows/{id}/run` 요청으로 워크플로우 실행 시작
2. **비동기 실행**: `WorkflowController`가 `WorkflowExecutionService`를 `@Async`로 호출하고 즉시 `202 Accepted` 응답
Expand All @@ -69,13 +114,13 @@

#### 수동 실행

![Sequence Diagram](assets/시퀀스 다이어그램(수동 실행).png)
![Sequence Diagram](assets/시퀀스_다이어그램(수동_실행).png)

#### 스케줄 실행

![Sequence Diagram](assets/시퀀스 다이어그램(스케줄 실행).png)
![Sequence Diagram](assets/시퀀스_다이어그램(스케줄_실행).png)

### 5.2. CI/CD 파이프라인
### 6.2. CI/CD 파이프라인

GitHub Actions 기반으로 빌드 → 테스트 → Docker 빌드 및 푸시 → EC2 배포까지 자동화되어 있습니다.

Expand All @@ -86,7 +131,7 @@ GitHub Actions 기반으로 빌드 → 테스트 → Docker 빌드 및 푸시

---

## 6. 기술 스택
## 7. 기술 스택

### Backend (Orchestrator - `user-service`)

Expand Down Expand Up @@ -119,7 +164,7 @@ GitHub Actions 기반으로 빌드 → 테스트 → Docker 빌드 및 푸시

---

## 7. 주요 구성 요소 및 역할
## 8. 주요 구성 요소 및 역할

* **WorkflowExecutionService**: 워크플로우 전체 실행 흐름 제어
* **TaskExecutionService**: Task 실행 및 재시도 정책 관리
Expand All @@ -130,7 +175,7 @@ GitHub Actions 기반으로 빌드 → 테스트 → Docker 빌드 및 푸시

---

## 8. 프로젝트 디렉토리 구조
## 9. 프로젝트 디렉토리 구조

Monorepo 형태로, `apps` 하위에 서비스별 디렉토리가 존재합니다.

Expand Down Expand Up @@ -173,7 +218,7 @@ pre-processing-service/

---

## 9. 환경 변수 관리 전략
## 10. 환경 변수 관리 전략

추후 작성 예정

Expand All @@ -182,7 +227,7 @@ pre-processing-service/

---

## 10. 시연 영상
## 11. 시연 영상

[https://www.youtube.com/watch?v=1vApNttVxVg](https://www.youtube.com/watch?v=1vApNttVxVg)
[![Video Label](http://img.youtube.com/vi/1vApNttVxVg/0.jpg)](https://www.youtube.com/watch?v=1vApNttVxVg)
Loading