Release v0.1.0-stable

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)