@things-factory/integration-label-studio 9.1.19

package/IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,469 @@
+# Label Studio Integration - 구현 가이드
+
+## 개요
+
+Things-Factory와 Label Studio의 완전한 통합을 위한 구현이 완료되었습니다.
+
+## 구현된 기능
+
+### ✅ Phase 1: 프로젝트 및 태스크 관리
+
+#### 1. 프로젝트 관리 GraphQL API
+
+**Query:**
+```graphql
+# 프로젝트 목록 조회
+query {
+  labelStudioProjects {
+    id
+    title
+    description
+    taskCount
+    completedTaskCount
+    completionRate
+    createdAt
+    updatedAt
+  }
+}
+
+# 단일 프로젝트 조회
+query {
+  labelStudioProject(projectId: 1) {
+    id
+    title
+    labelConfig
+  }
+}
+
+# 프로젝트 통계
+query {
+  labelStudioProjectMetrics(projectId: 1) {
+    totalTasks
+    completedTasks
+    completionRate
+    annotatorStats {
+      email
+      annotationCount
+      avgTime
+    }
+  }
+}
+```
+
+**Mutation:**
+```graphql
+# 프로젝트 생성
+mutation {
+  createLabelStudioProject(input: {
+    title: "New Project"
+    description: "Project description"
+    labelConfig: "<View>...</View>"
+  }) {
+    id
+    title
+  }
+}
+
+# 프로젝트 삭제
+mutation {
+  deleteLabelStudioProject(projectId: 1)
+}
+```
+
+#### 2. 태스크 관리 GraphQL API
+
+**Query:**
+```graphql
+# 태스크 목록
+query {
+  labelStudioTasks(projectId: 1, page: 1, pageSize: 100) {
+    id
+    data
+    annotationCount
+    isCompleted
+  }
+}
+
+# 어노테이션 조회
+query {
+  labelStudioTaskAnnotations(taskId: 1) {
+    id
+    result
+    completedBy
+    leadTime
+  }
+}
+```
+
+**Mutation:**
+```graphql
+# 태스크 임포트
+mutation {
+  importTasksToLabelStudio(
+    projectId: 1
+    tasks: [
+      { data: "{\"text\": \"Sample text\"}" }
+    ]
+  ) {
+    imported
+    failed
+    taskIds
+  }
+}
+
+# 어노테이션 익스포트
+mutation {
+  exportLabelStudioAnnotations(projectId: 1, format: "JSON") {
+    exportPath
+    annotationCount
+    format
+  }
+}
+
+# 어노테이션 동기화
+mutation {
+  syncAnnotationsToDatabase(projectId: 1)
+}
+```
+
+### ✅ Phase 2: 웹훅 및 실시간 동기화
+
+#### 3. 웹훅 관리
+
+**GraphQL API:**
+```graphql
+# 웹훅 등록
+mutation {
+  registerLabelStudioWebhook(projectId: 1) {
+    id
+    url
+    isActive
+  }
+}
+
+# 웹훅 조회
+query {
+  labelStudioWebhooks(projectId: 1) {
+    id
+    url
+    isActive
+  }
+}
+
+# 웹훅 삭제
+mutation {
+  deleteLabelStudioWebhook(webhookId: 1)
+}
+```
+
+**REST API 엔드포인트:**
+```bash
+# 웹훅 수신 (Label Studio → Things-Factory)
+POST /label-studio/webhook
+
+# 웹훅 등록 (Things-Factory → Label Studio)
+POST /label-studio/webhook/register
+{
+  "projectId": 1
+}
+
+# 웹훅 조회
+GET /label-studio/webhook/:projectId
+```
+
+**지원하는 이벤트:**
+- `ANNOTATION_CREATED` - 어노테이션 생성
+- `ANNOTATION_UPDATED` - 어노테이션 수정
+- `ANNOTATION_DELETED` - 어노테이션 삭제
+- `TASK_CREATED` - 태스크 생성
+- `PROJECT_UPDATED` - 프로젝트 업데이트
+
+### ✅ Phase 3: ML Backend 연동
+
+#### 4. ML Backend 관리
+
+**GraphQL API:**
+```graphql
+# ML Backend 조회
+query {
+  labelStudioMLBackends(projectId: 1) {
+    id
+    url
+    title
+    isInteractive
+    modelVersion
+  }
+}
+
+# ML Backend 추가
+mutation {
+  addMLBackendToProject(
+    projectId: 1
+    input: {
+      url: "http://ml-backend:9090"
+      title: "Auto-labeling Model"
+      isInteractive: true
+    }
+  ) {
+    id
+    url
+  }
+}
+
+# 예측 실행
+mutation {
+  triggerLabelStudioPredictions(
+    projectId: 1
+    taskIds: [1, 2, 3]
+  )
+}
+
+# 모델 학습
+mutation {
+  trainLabelStudioModel(mlBackendId: 1)
+}
+```
+
+### ✅ Phase 4: 클라이언트 UI 컴포넌트
+
+#### 5. UI 컴포넌트
+
+**프로젝트 목록 컴포넌트:**
+```html
+<label-studio-project-list></label-studio-project-list>
+```
+
+**기능:**
+- 프로젝트 카드 그리드 뷰
+- 프로젝트 통계 표시 (완료율, 태스크 수)
+- 프로젝트 생성 버튼
+- 프로젝트 클릭 → Label Studio 오픈
+
+## 아키텍처
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Things-Factory                           │
+│                                                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
+│  │   GraphQL    │  │  Webhook     │  │  UI Components   │  │
+│  │   Resolvers  │  │  Handler     │  │                  │  │
+│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘  │
+│         │                 │                   │             │
+│         └─────────────────┴───────────────────┘             │
+│                           │                                 │
+│                  ┌────────▼────────┐                        │
+│                  │  API Client     │                        │
+│                  └────────┬────────┘                        │
+└───────────────────────────┼─────────────────────────────────┘
+                            │
+                   ┌────────▼────────┐
+                   │  Label Studio   │
+                   │  REST API       │
+                   └─────────────────┘
+```
+
+## 사용 방법
+
+### 1. 환경 설정
+
+**config/label-studio.config.js:**
+```javascript
+module.exports = {
+  labelStudio: {
+    serverUrl: process.env.LABEL_STUDIO_URL,
+    apiToken: process.env.LABEL_STUDIO_API_TOKEN
+  }
+}
+```
+
+**.env:**
+```bash
+LABEL_STUDIO_URL=https://label-studio.example.com
+LABEL_STUDIO_API_TOKEN=your-api-token
+SERVER_URL=https://things-factory.example.com
+```
+
+### 2. 프로젝트 생성 워크플로우
+
+```graphql
+# 1. 프로젝트 생성
+mutation {
+  createLabelStudioProject(input: {
+    title: "Image Classification"
+    labelConfig: """
+      <View>
+        <Image name="image" value="$image"/>
+        <Choices name="choice" toName="image">
+          <Choice value="Cat"/>
+          <Choice value="Dog"/>
+        </Choices>
+      </View>
+    """
+  }) {
+    id
+  }
+}
+
+# 2. 태스크 임포트
+mutation {
+  importTasksToLabelStudio(
+    projectId: 1
+    tasks: [
+      { data: "{\"image\": \"https://example.com/cat.jpg\"}" }
+    ]
+  ) {
+    imported
+  }
+}
+
+# 3. 웹훅 등록 (실시간 업데이트)
+mutation {
+  registerLabelStudioWebhook(projectId: 1) {
+    id
+  }
+}
+
+# 4. ML Backend 추가 (선택사항)
+mutation {
+  addMLBackendToProject(
+    projectId: 1
+    input: {
+      url: "http://ml-backend:9090"
+      title: "Image Classifier"
+    }
+  ) {
+    id
+  }
+}
+```
+
+### 3. 어노테이션 수집 워크플로우
+
+```graphql
+# 1. 어노테이션 조회
+query {
+  labelStudioTaskAnnotations(taskId: 1) {
+    id
+    result
+    completedBy
+  }
+}
+
+# 2. 익스포트
+mutation {
+  exportLabelStudioAnnotations(projectId: 1, format: "JSON") {
+    exportPath
+    annotationCount
+  }
+}
+
+# 3. Things-Factory DB에 저장
+mutation {
+  syncAnnotationsToDatabase(projectId: 1)
+}
+```
+
+## 확장 포인트
+
+### 1. 커스텀 웹훅 핸들러
+
+`server/route/webhook.ts`에서 핸들러 커스터마이징:
+
+```typescript
+async function handleAnnotationCreated(payload: WebhookPayload) {
+  // 1. Things-Factory DB에 저장
+  // 2. 비즈니스 로직 실행
+  // 3. 알림 발송
+  // 4. 외부 시스템 연동
+}
+```
+
+### 2. 데이터 소스 연동
+
+Things-Factory 데이터를 Label Studio로 자동 임포트:
+
+```typescript
+// server/service/storage/storage-sync.ts
+@Mutation()
+async syncBizplaceDataToLabelStudio(
+  @Arg('bizplaceId') bizplaceId: string,
+  @Arg('projectId') projectId: number
+) {
+  // Bizplace 데이터 조회
+  // Label Studio 태스크로 변환
+  // 자동 임포트
+}
+```
+
+### 3. 어노테이션 결과 활용
+
+```typescript
+// server/service/annotation/annotation-processor.ts
+@Mutation()
+async processAnnotationResults(
+  @Arg('projectId') projectId: number
+) {
+  // 어노테이션 익스포트
+  // 결과 분석
+  // Things-Factory 엔티티 업데이트
+}
+```
+
+## 테스트
+
+### GraphQL Playground에서 테스트
+
+```bash
+# Things-Factory 실행
+yarn workspace @things-factory/operato-mms run serve:dev
+
+# GraphQL Playground 접속
+http://localhost:3000/graphql
+```
+
+### 웹훅 테스트
+
+```bash
+# Webhook 엔드포인트 테스트
+curl -X POST http://localhost:3000/label-studio/webhook \
+  -H "Content-Type: application/json" \
+  -d '{
+    "action": "ANNOTATION_CREATED",
+    "project": {"id": 1, "title": "Test"},
+    "annotation": {
+      "id": 1,
+      "result": [...]
+    }
+  }'
+```
+
+## 다음 단계
+
+### 추가 개발 항목
+
+1. **실시간 대시보드**
+   - 프로젝트별 진행률 실시간 표시
+   - 사용자별 생산성 차트
+   - 어노테이션 품질 메트릭
+
+2. **데이터 소스 자동 연동**
+   - Things-Factory Storage → Label Studio
+   - 파일 업로드 자동 감지
+   - 태스크 자동 생성
+
+3. **어노테이션 검증**
+   - Inter-annotator agreement 계산
+   - 품질 관리 워크플로우
+   - 자동 리뷰 시스템
+
+4. **Advanced ML 통합**
+   - Active Learning 구현
+   - 모델 성능 모니터링
+   - A/B 테스트 지원
+
+## 참고 자료
+
+- [Label Studio API Documentation](https://labelstud.io/api)
+- [Things-Factory Module Development Guide](../../CLAUDE.md)
+- [Integration Examples](./docs/examples/)