diff --git a/README.md b/README.md index b3ebca51..b6ffcb91 100644 --- a/README.md +++ b/README.md @@ -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-시연-영상) --- @@ -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** 역할을 수행하는 이중 레이어 아키텍처를 채택했습니다. @@ -48,7 +93,7 @@ --- -## 4. 유스케이스 다이어그램 +## 5. 유스케이스 다이어그램 시스템의 주요 액터는 **관리자(Admin)** 와 **스케줄러(Scheduler)** 입니다. 관리자는 워크플로우와 스케줄을 관리하고 수동 실행이 가능하며, 스케줄러는 자동 실행을 담당합니다. @@ -57,9 +102,9 @@ --- -## 5. 시퀀스 다이어그램 +## 6. 시퀀스 다이어그램 -### 5.1. 워크플로우 실행 흐름 (스케줄/수동) +### 6.1. 워크플로우 실행 흐름 (스케줄/수동) 1. **트리거**: Quartz 스케줄러 또는 사용자의 `POST /v0/workflows/{id}/run` 요청으로 워크플로우 실행 시작 2. **비동기 실행**: `WorkflowController`가 `WorkflowExecutionService`를 `@Async`로 호출하고 즉시 `202 Accepted` 응답 @@ -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 배포까지 자동화되어 있습니다. @@ -86,7 +131,7 @@ GitHub Actions 기반으로 빌드 → 테스트 → Docker 빌드 및 푸시 --- -## 6. 기술 스택 +## 7. 기술 스택 ### Backend (Orchestrator - `user-service`) @@ -119,7 +164,7 @@ GitHub Actions 기반으로 빌드 → 테스트 → Docker 빌드 및 푸시 --- -## 7. 주요 구성 요소 및 역할 +## 8. 주요 구성 요소 및 역할 * **WorkflowExecutionService**: 워크플로우 전체 실행 흐름 제어 * **TaskExecutionService**: Task 실행 및 재시도 정책 관리 @@ -130,7 +175,7 @@ GitHub Actions 기반으로 빌드 → 테스트 → Docker 빌드 및 푸시 --- -## 8. 프로젝트 디렉토리 구조 +## 9. 프로젝트 디렉토리 구조 Monorepo 형태로, `apps` 하위에 서비스별 디렉토리가 존재합니다. @@ -173,7 +218,7 @@ pre-processing-service/ --- -## 9. 환경 변수 관리 전략 +## 10. 환경 변수 관리 전략 추후 작성 예정 @@ -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)