@things-factory/labeling 9.1.19

package/REFACTORING_SUMMARY.md

@@ -0,0 +1,212 @@
+# 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**이므로 기존 코드의 업데이트가 필요합니다.