# Labeling Workflow Refactoring Summary

## 목적

`integration-label-studio` 패키지에 있던 `labeling-scenario` 기능을 별도의 `labeling` 패키지로 분리하고, 기존 `scenario` 엔티티와의 용어 충돌을 방지하기 위해 모든 용어를 `workflow`로 변경했습니다.

## 요구사항

1. **용어 분리**: `scenario`는 이미 존재하는 엔티티이므로 혼용 금지
2. **모듈 분리**: `integration-label-studio`와는 별도의 독립적인 `labeling` 모듈 생성
3. **명명 변경**: `labeling-scenario` → `labeling-workflow`

## 변경 사항

### 1. 새 패키지 생성

**경로**: `/Users/super/Documents/GitHub/things-factory/packages/labeling/`

**구조**:
```
labeling/
├── package.json                    # 패키지 정의
├── things-factory.config.js        # Things-Factory 설정
├── README.md                       # 사용 가이드
├── MIGRATION_GUIDE.md              # 마이그레이션 가이드
├── CHANGELOG.md                    # 변경 이력
├── REFACTORING_SUMMARY.md          # 리팩토링 요약 (현재 문서)
├── .npmignore                      # NPM 배포 제외 파일
├── server/
│   ├── tsconfig.json
│   ├── index.ts                    # 서버 엔트리포인트
│   ├── route.ts                    # HTTP 라우트 (없음)
│   ├── types/
│   │   ├── workflow-types.ts       # Workflow 타입 정의 (scenario-types.ts에서 변환)
│   │   └── global.d.ts             # 전역 타입 선언
│   └── service/
│       ├── index.ts                # 서비스 내보내기
│       └── labeling-workflow-service.ts  # Workflow 서비스 (labeling-scenario-service.ts에서 변환)
├── client/
│   ├── tsconfig.json
│   └── index.ts                    # 클라이언트 엔트리포인트
└── dist-server/                    # 빌드 결과 (TypeScript 컴파일 출력)
    └── dist-client/
```

### 2. 용어 변경 매핑

모든 `Scenario` 관련 용어를 `Workflow`로 변경:

| 기존 (Scenario) | 변경 (Workflow) |
|----------------|----------------|
| `LabelingScenario` | `LabelingWorkflow` |
| `ScenarioStep` | `WorkflowStep` |
| `ScenarioStepType` | `WorkflowStepType` |
| `ScenarioStatus` | `WorkflowStatus` |
| `ScenarioExecution` | `WorkflowExecution` |
| `ScenarioExecutionStep` | `WorkflowExecutionStep` |
| `ScenarioExecutionResult` | `WorkflowExecutionResult` |
| `CreateScenarioRequest` | `CreateWorkflowRequest` |
| `ExecuteScenarioRequest` | `ExecuteWorkflowRequest` |
| `LabelingScenarioList` | `LabelingWorkflowList` |
| `ScenarioExecutionList` | `WorkflowExecutionList` |
| `ScenarioStatusRequest` | `WorkflowStatusRequest` |
| `LabelingScenarioService` | `LabelingWorkflowService` |

### 3. GraphQL API 변경

#### Mutations

| 기존 | 변경 |
|-----|-----|
| `createLabelingScenario` | `createLabelingWorkflow` |
| `executeScenario` | `executeLabelingWorkflow` |
| `pauseScenario` | `pauseLabelingWorkflow` |
| `resumeScenario` | `resumeLabelingWorkflow` |

#### Queries

| 기존 | 변경 |
|-----|-----|
| `labelingScenario(scenarioId)` | `labelingWorkflow(workflowId)` |
| `labelingScenarios(projectId)` | `labelingWorkflows(projectId)` |
| `scenarioExecution(executionId)` | `workflowExecution(executionId)` |
| `scenarioExecutions(scenarioId)` | `workflowExecutions(workflowId)` |

#### Privilege Category

- **기존**: `@privilege(category: "label-studio", privilege: "mutation")`
- **변경**: `@privilege(category: "labeling", privilege: "mutation")`

### 4. integration-label-studio 패키지 정리

다음 파일들을 deprecated로 표시:

```
integration-label-studio/server/
  ├── types/scenario-types.ts.deprecated
  └── service/labeling-scenario-service.ts.deprecated
```

`server/service/index.ts`에서 `LabelingScenarioService` import 및 등록 제거.

### 5. 의존성 관계

**labeling 패키지의 의존성**:
```json
{
  "@things-factory/integration-label-studio": "^9.1.2",
  "@things-factory/dataset": "^9.1.1",
  "@things-factory/ai-inference": "^9.1.1",
  "@things-factory/auth-base": "^9.1.0",
  "@things-factory/env": "^9.1.0"
}
```

**labeling-workflow-service.ts가 사용하는 서비스**:
- `DatasetLabelingIntegration` (from integration-label-studio)
- `ExternalDataSourceService` (from integration-label-studio)
- `LabelStudioAIPredictionService` (from integration-label-studio)

## 분리 이유

### 1. 용어 충돌 방지
Things-Factory에는 이미 `scenario` 엔티티가 존재합니다. `labeling-scenario`와 혼용하면 개발자 혼란과 타입 충돌이 발생할 수 있습니다.

### 2. 관심사 분리
- **integration-label-studio**: Label Studio 자체의 통합 (프로젝트, 태스크, 사용자 동기화 등)
- **labeling**: 레이블링 워크플로우 오케스트레이션 (고수준 자동화)

`labeling-workflow`는 Label Studio뿐만 아니라 DataSet, AI 추론 등 여러 서비스를 조율하는 고수준 개념입니다.

### 3. 확장성
향후 다른 레이블링 도구(Labelbox, Scale AI 등)를 지원할 때도 `labeling` 패키지를 확장할 수 있습니다.

### 4. 명확한 책임
- `integration-label-studio`: Label Studio API와의 직접적인 통신
- `labeling`: 레이블링 프로세스의 전체적인 워크플로우 관리

## 마이그레이션 영향

### Breaking Changes

1. **패키지 변경**: `@things-factory/integration-label-studio` → `@things-factory/labeling`
2. **Import 경로 변경**: `scenario-types` → `workflow-types`
3. **타입명 변경**: 모든 `Scenario*` → `Workflow*`
4. **GraphQL 작업명 변경**: 모든 쿼리/뮤테이션 이름 변경
5. **권한 카테고리 변경**: `"label-studio"` → `"labeling"`

### 마이그레이션 필요 대상

1. 백엔드 코드에서 scenario 타입을 import하는 모든 곳
2. GraphQL 쿼리/뮤테이션을 사용하는 프론트엔드 코드
3. 권한 설정 (Role/Permission)
4. 저장된 scenario 데이터 (있는 경우)

자세한 마이그레이션 방법은 [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)를 참조하세요.

## 테스트 결과

### 빌드 성공

```bash
cd /Users/super/Documents/GitHub/things-factory/packages/labeling
npm run build:server  # ✓ 성공
npm run build:client  # ✓ 성공
```

### 생성된 파일

- `dist-server/`: 컴파일된 서버 코드
- `dist-client/`: 컴파일된 클라이언트 코드
- TypeScript 선언 파일 (`.d.ts`)
- Source maps (`.js.map`)

## 문서

1. **README.md**: 사용법, API 예제, 아키텍처 설명
2. **MIGRATION_GUIDE.md**: 상세한 마이그레이션 가이드
3. **CHANGELOG.md**: 버전별 변경 이력
4. **REFACTORING_SUMMARY.md**: 이 문서, 리팩토링 요약

## 향후 작업

### 즉시 필요한 작업

- [ ] 기존 코드에서 scenario 참조를 workflow로 변경
- [ ] 프론트엔드 GraphQL 쿼리/뮤테이션 업데이트
- [ ] 권한 설정 업데이트
- [ ] 통합 테스트 실행

### 개선 사항 (Optional)

- [ ] 데이터베이스 영속성 추가 (현재는 in-memory)
- [ ] 스케줄 기반 트리거 구현 (cron)
- [ ] 이벤트 기반 트리거 구현 (webhook)
- [ ] 고급 조건 평가 로직 (JSON Logic)
- [ ] 워크플로우 템플릿 시스템
- [ ] 워크플로우 버전 관리
- [ ] 병렬 스텝 실행
- [ ] 사람 승인 스텝

## 결론

`labeling-scenario` 기능을 독립적인 `@things-factory/labeling` 패키지로 성공적으로 분리하고, 모든 용어를 `workflow`로 변경하여 기존 `scenario` 엔티티와의 충돌을 방지했습니다.

이 변경으로 인해:
- ✅ 용어 충돌 해결
- ✅ 명확한 관심사 분리
- ✅ 확장 가능한 아키텍처
- ✅ 독립적인 모듈 관리

다만, 이는 **Breaking Change**이므로 기존 코드의 업데이트가 필요합니다.