# @things-factory/integration-label-studio

Things-Factory와 Label Studio Custom을 완전 통합하는 엔터프라이즈급 모듈입니다.

[![Label Studio Version](https://img.shields.io/badge/Label%20Studio-1.20.0--sso.32-blue)](https://github.com/aidoop/label-studio-custom)
[![Docker Image](https://img.shields.io/badge/docker-ghcr.io%2Faidoop%2Flabel--studio--custom-blue)](https://github.com/aidoop/label-studio-custom/pkgs/container/label-studio-custom)

## 지원 버전

- **Label Studio Custom**: `ghcr.io/aidoop/label-studio-custom:1.20.0-sso.38`
- **label-studio-sso**: `v6.0.8` (내장)
- **Things-Factory**: `9.1.0+`

## 주요 기능

### ✅ 이미 구현된 기능

- **iframe 통합** - Label Studio를 Things-Factory 화면에 임베드
- **SSO 인증** - JWT 토큰 기반 자동 로그인 (label-studio-sso v6.0.8 내장)
- **사용자 동기화** - Things-Factory ↔ Label Studio 사용자 배치 동기화
- **권한 매핑** - Things-Factory 권한 → Label Studio 역할 자동 매핑
- **자동 Organization 할당** - SSO 로그인 시 자동으로 Organization 멤버 추가

### 🆕 새로 추가된 기능

- **프로젝트 관리** - 프로젝트 생성, 조회, 수정, 삭제 (CRUD)
- **태스크 관리** - 태스크 임포트, 익스포트, 어노테이션 조회
- **웹훅 연동** - Label Studio 이벤트 실시간 수신
- **ML Backend 통합** - 자동 예측 및 모델 학습 지원
- **통계 대시보드** - 프로젝트 진행률, 사용자 생산성 통계
- **UI 컴포넌트** - 프로젝트 목록, 생성 폼, 통계 위젯

## 아키텍처

### 전체 구조

```
┌─────────────────────────────────────────────────────────┐
│                   Things-Factory                        │
│                                                          │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐  │
│  │   GraphQL   │  │   Webhook    │  │ UI Components │  │
│  │   API       │  │   Handler    │  │               │  │
│  └──────┬──────┘  └──────┬───────┘  └───────┬───────┘  │
│         │                │                  │           │
│         └────────────────┴──────────────────┘           │
│                          │                              │
│                  ┌───────▼────────┐                     │
│                  │  API Client    │                     │
│                  └───────┬────────┘                     │
└──────────────────────────┼──────────────────────────────┘
                           │
                  ┌────────▼─────────┐
                  │  Label Studio    │
                  │  REST API        │
                  └──────────────────┘
```

### 유연한 확장 아키텍처

이 모듈은 **플러그인 기반의 유연한 아키텍처**를 제공합니다:

```
┌─────────────────────────────────────────────────────────┐
│              Application Layer                          │
│                                                          │
│  • registerWebhookHandler()    - 웹훅 핸들러 등록       │
│  • registerExportFormat()      - 익스포트 포맷 등록     │
│  • LabelConfigBuilder          - 프로젝트 설정 생성     │
│  • TaskTransformer             - 데이터 변환            │
└─────────────────────────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│         integration-label-studio (Base Layer)           │
│                                                          │
│  • LabelConfigBuilder      - 선언적 설정 생성           │
│  • TaskTransformer         - 유연한 데이터 변환         │
│  • AnnotationExporter      - 플러그인형 익스포트        │
│  • Webhook Extension       - 확장 가능한 웹훅           │
│  • GraphQL API             - 유연한 입력 지원           │
└─────────────────────────────────────────────────────────┘
```

## 빠른 시작

### 1. Label Studio Custom Docker 실행

```bash
# Docker Compose로 Label Studio Custom 실행
cd /path/to/label-studio-custom

# .env 파일 설정
cat > .env << 'EOF'
POSTGRES_DB=labelstudio
POSTGRES_USER=postgres
POSTGRES_PASSWORD=dev_postgres_2024

# Label Studio 접속 URL
LABEL_STUDIO_HOST=http://label.hatiolab.localhost:8080

# 서브도메인 간 쿠키 공유 (SSO 필수)
COOKIE_DOMAIN=.hatiolab.localhost
SESSION_COOKIE_DOMAIN=.hatiolab.localhost
CSRF_COOKIE_DOMAIN=.hatiolab.localhost

# iframe 임베딩 보안 헤더
CSP_FRAME_ANCESTORS='self' http://localhost:3000 http://hatiolab.localhost:3000

# API 토큰 (초기 사용자 생성 후 설정)
LABEL_STUDIO_API_TOKEN=your-api-token-here
EOF

# Docker Compose 실행
docker compose up -d

# 로그 확인
docker compose logs -f labelstudio

# 초기 Admin 사용자 생성 (최초 1회)
docker compose exec labelstudio python manage.py createsuperuser

# API 토큰 발급
# → http://label.hatiolab.localhost:8080 로그인
# → Account Settings → Access Token → Create new token
# → 생성된 토큰을 .env 파일의 LABEL_STUDIO_API_TOKEN에 설정
```

### 2. Things-Factory 설정

**packages/integration-label-studio/config/label-studio.config.js:**

```javascript
module.exports = {
  labelStudio: {
    serverUrl: process.env.LABEL_STUDIO_URL || 'http://label.hatiolab.localhost:8080',
    apiToken: process.env.LABEL_STUDIO_API_TOKEN || '',
    cookieDomain: process.env.LABEL_STUDIO_COOKIE_DOMAIN || '.hatiolab.localhost',
    interfaces: 'panel,controls,annotations:menu'
  }
}
```

**Things-Factory .env (Development):**

```bash
LABEL_STUDIO_URL=http://label.hatiolab.localhost:8080
LABEL_STUDIO_API_TOKEN=your-api-token-here
LABEL_STUDIO_COOKIE_DOMAIN=.hatiolab.localhost
```

**Things-Factory .env (Production):**

```bash
LABEL_STUDIO_URL=https://label.example.com
LABEL_STUDIO_API_TOKEN=your-api-token-here
LABEL_STUDIO_COOKIE_DOMAIN=.example.com
```

### 3. Things-Factory 빌드 및 실행

```bash
cd /path/to/things-factory

# integration-label-studio 모듈 빌드
cd packages/integration-label-studio
yarn build

# 루트로 돌아가서 실행
cd ../..
yarn workspace @things-factory/operato-mms run serve:dev
```

### 4. 접속

- **Things Factory**: http://hatiolab.localhost:3000 → 메뉴 → Label Studio
- **Label Studio**: http://label.hatiolab.localhost:8080 (직접 접속)
- **GraphQL Playground**: http://hatiolab.localhost:3000/graphql

**참고**: `*.localhost` 도메인은 브라우저가 자동으로 `127.0.0.1`로 해석하므로 `/etc/hosts` 수정이 필요 없습니다.

## 유연한 확장 기능

### 1. LabelConfigBuilder - 선언적 프로젝트 설정

XML을 직접 작성하지 않고, **선언적 사양**으로 Label Studio 설정을 생성:

```typescript
import { LabelConfigBuilder, LabelConfigTemplates } from '@things-factory/integration-label-studio'

// 방법 1: 템플릿 사용
const config = LabelConfigTemplates.imageRankN(3, ['Normal', 'Defect A', 'Defect B', 'Defect C'])
const xml = LabelConfigBuilder.build(config)

// 방법 2: 커스텀 설정
const customConfig = LabelConfigBuilder.build({
  dataType: 'image',
  controls: [
    {
      type: 'choices',
      name: 'rank1',
      toName: 'data',
      config: { choices: ['Normal', 'Defect'], choice: 'single', required: true }
    },
    {
      type: 'rating',
      name: 'confidence',
      toName: 'data',
      config: { maxRating: 5, icon: 'star' }
    }
  ]
})
```

### 2. TaskTransformer - 유연한 데이터 변환

임의의 소스 데이터를 Label Studio 태스크로 변환:

```typescript
import { TaskTransformer, TaskTransformTemplates } from '@things-factory/integration-label-studio'

// WBM 디바이스 데이터 → Label Studio 태스크
const sourceData = [
  {
    image_url: 'http://device/image1.jpg',
    device_id: 'WBM-001',
    wafer_id: 'W123',
    timestamp: '2025-01-01T10:00:00Z',
    ai_prediction: { rank1: 'Normal', rank2: 'Defect A', rank3: 'Defect B' },
    confidence: 0.95
  }
]

// 변환 규칙
const rule = TaskTransformTemplates.wbmImageClassification(true)

// 변환 실행
const lsTasks = TaskTransformer.transform(sourceData, rule)
// 결과: Label Studio 태스크 (data, predictions, meta)
```

**커스텀 변환 규칙:**

```typescript
const customRule = {
  dataFields: {
    image: 'images[0].url', // 중첩 배열 지원
    date: 'metadata.captured_at', // 중첩 객체 지원
    device: 'device.id'
  },
  predictions: {
    enabled: true,
    resultPath: 'ai.classification',
    scorePath: 'ai.confidence',
    modelVersion: 'v1.0.0',
    resultTransform: result => {
      // AI 결과를 Label Studio 포맷으로 변환
      return [{ from_name: 'label', to_name: 'data', type: 'choices', value: { choices: [result] } }]
    }
  },
  meta: {
    lot: 'production.lot_id',
    line: 'production.line_number'
  }
}
```

### 3. Webhook Handler 확장

웹훅 이벤트에 커스텀 로직 추가:

```typescript
import { registerWebhookHandler, WebhookAction } from '@things-factory/integration-label-studio'

// 어노테이션 완료 시 자동 처리
registerWebhookHandler(WebhookAction.ANNOTATION_CREATED, async (payload, ctx) => {
  console.log('New annotation:', payload.annotation.id)

  // 1. Things-Factory DB에 저장
  await saveAnnotationToDatabase(payload.annotation)

  // 2. 품질 시스템에 전송
  await sendToQualitySystem(payload.annotation)

  // 3. 임계값 초과 시 알림
  if (payload.annotation.result.includes('Defect')) {
    await sendAlertToManager(payload.project.id)
  }
})

// 여러 핸들러 등록 가능 (순차 실행)
registerWebhookHandler(WebhookAction.ANNOTATION_CREATED, async (payload, ctx) => {
  // 통계 업데이트
  await updateProjectStats(payload.project.id)
})
```

### 4. AnnotationExporter - 플러그인형 익스포트

커스텀 익스포트 포맷 추가:

```typescript
import { registerExportFormat, exportAnnotations } from '@things-factory/integration-label-studio'

// 커스텀 포맷 등록
registerExportFormat('wbm-report', (annotations, context) => {
  const report = {
    project: context.projectTitle,
    exported_at: context.exportedAt,
    summary: {
      total: annotations.length,
      defect_count: annotations.filter(a => a.result.includes('Defect')).length
    },
    details: annotations.map(a => ({
      task_id: a.task,
      wafer_id: a.meta?.wafer_id,
      classification: a.result[0].value.choices[0],
      annotator: a.completed_by.email,
      time: a.lead_time
    }))
  }

  return JSON.stringify(report, null, 2)
})

// 사용
const data = await exportAnnotations(annotations, 'wbm-report', { projectId: 1, exportedAt: new Date().toISOString() })
```

**기본 제공 포맷:**

- `json` - Label Studio 기본 JSON
- `jsonl` - JSON Lines (한 줄에 하나씩)
- `csv` - 이미지 분류 CSV
- `rank-csv` - Rank N 분류 CSV
- `coco` - COCO object detection
- `yolo` - YOLO object detection
- `ner-json` - Named Entity Recognition

## GraphQL API

### 기본 프로젝트 관리

```graphql
# 프로젝트 목록 조회
query {
  labelStudioProjects {
    id
    title
    description
    taskCount
    completedTaskCount
    completionRate
  }
}

# 프로젝트 생성 (XML 직접 작성)
mutation {
  createLabelStudioProject(
    input: {
      title: "Image Classification"
      description: "Classify product images"
      labelConfig: """
      <View>
        <Image name="image" value="$image"/>
        <Choices name="category" toName="image">
          <Choice value="Electronics"/>
          <Choice value="Clothing"/>
          <Choice value="Food"/>
        </Choices>
      </View>
      """
    }
  ) {
    id
    title
  }
}

# 🆕 프로젝트 생성 (선언적 사양 사용)
mutation {
  createLabelStudioProjectWithSpec(
    input: {
      title: "WBM Rank 3 Classification"
      description: "Wafer defect classification"
      labelConfigSpec: {
        dataType: "image"
        controls: """
        [
          {
            "type": "choices",
            "name": "rank1",
            "toName": "data",
            "config": {
              "choices": ["Normal", "Defect A", "Defect B", "Defect C"],
              "choice": "single",
              "required": true
            }
          },
          {
            "type": "choices",
            "name": "rank2",
            "toName": "data",
            "config": {
              "choices": ["Normal", "Defect A", "Defect B", "Defect C"],
              "choice": "single"
            }
          },
          {
            "type": "choices",
            "name": "rank3",
            "toName": "data",
            "config": {
              "choices": ["Normal", "Defect A", "Defect B", "Defect C"],
              "choice": "single"
            }
          }
        ]
        """
      }
    }
  ) {
    id
    labelConfig
  }
}

# 프로젝트 통계
query {
  labelStudioProjectMetrics(projectId: 1) {
    totalTasks
    completedTasks
    completionRate
    avgTimePerTask
    annotatorStats {
      email
      annotationCount
      avgTime
    }
  }
}

# 프로젝트 삭제
mutation {
  deleteLabelStudioProject(projectId: 1)
}
```

### 태스크 관리

```graphql
# 태스크 조회
query {
  labelStudioTasks(projectId: 1, page: 1, pageSize: 100) {
    id
    data
    annotationCount
    isCompleted
  }
}

# 태스크 임포트 (기본)
mutation {
  importTasksToLabelStudio(
    projectId: 1
    tasks: [
      { data: "{\"image\": \"https://example.com/image1.jpg\"}" }
      { data: "{\"image\": \"https://example.com/image2.jpg\"}" }
    ]
  ) {
    imported
    failed
    taskIds
    errors
  }
}

# 🆕 태스크 임포트 (데이터 변환 사용)
mutation {
  importTasksWithTransform(
    projectId: 1
    input: {
      sourceData: """
      [
        {
          "image_url": "http://device/img1.jpg",
          "device_id": "WBM-001",
          "wafer_id": "W123",
          "lot_id": "LOT-001",
          "timestamp": "2025-01-01T10:00:00Z",
          "ai_prediction": {
            "rank1": "Normal",
            "rank2": "Defect A",
            "rank3": "Defect B"
          },
          "confidence": 0.95
        }
      ]
      """
      transformRule: {
        dataFields: """
        {
          "image": "image_url",
          "date": "timestamp",
          "device_id": "device_id"
        }
        """
        predictions: """
        {
          "enabled": true,
          "resultPath": "ai_prediction",
          "scorePath": "confidence",
          "modelVersion": "v1.0"
        }
        """
        meta: """
        {
          "wafer_id": "wafer_id",
          "lot_id": "lot_id"
        }
        """
      }
    }
  ) {
    imported
    taskIds
  }
}

# 어노테이션 조회
query {
  labelStudioTaskAnnotations(taskId: 1) {
    id
    result
    completedBy
    leadTime
    createdAt
  }
}

# 어노테이션 익스포트 (기본)
mutation {
  exportLabelStudioAnnotations(
    projectId: 1
    format: "JSON" # JSON, CSV, COCO, YOLO 등
  ) {
    exportPath
    annotationCount
    format
  }
}

# 🆕 어노테이션 익스포트 (커스텀 포맷)
mutation {
  exportAnnotationsWithFormat(
    projectId: 1
    input: {
      format: "rank-csv" # json, jsonl, csv, rank-csv, coco, yolo, ner-json, 또는 커스텀
      taskIds: "[1, 2, 3]" # 선택적 필터
    }
  ) {
    data
    count
    format
  }
}

# Things-Factory DB에 동기화
mutation {
  syncAnnotationsToDatabase(projectId: 1)
}
```

### 웹훅 관리

```graphql
# 웹훅 등록 (실시간 이벤트 수신)
mutation {
  registerLabelStudioWebhook(projectId: 1) {
    id
    url
    isActive
  }
}

# 웹훅 조회
query {
  labelStudioWebhooks(projectId: 1) {
    id
    url
    isActive
  }
}

# 웹훅 삭제
mutation {
  deleteLabelStudioWebhook(webhookId: 1)
}
```

### ML Backend 연동

```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] # null이면 전체
  )
}

# 모델 학습
mutation {
  trainLabelStudioModel(mlBackendId: 1)
}
```

### 사용자 동기화

```graphql
# 내 계정 동기화
mutation {
  syncMyUserToLabelStudio {
    success
    email
    action
    lsUserId
    lsPermissions
  }
}

# 전체 사용자 동기화 (관리자만)
mutation {
  syncAllUsersToLabelStudio {
    total
    created
    updated
    deactivated
    skipped
    errors
    results {
      email
      action
      lsPermissions
    }
  }
}
```

## UI 컴포넌트

### 프로젝트 목록

```
메뉴 → Label Studio → Projects
```

- 프로젝트 카드 그리드 뷰
- 완료율 프로그레스 바
- 통계 표시 (태스크 수, 완료 수)
- 프로젝트 클릭 → Label Studio 오픈

### 프로젝트 생성

```
메뉴 → Label Studio → Projects → New Project
```

- 템플릿 지원 (Text Classification, Image Classification, NER)
- Label Config XML 편집기
- 실시간 검증

### Label Studio Viewer

```
프로젝트 카드 클릭 → iframe으로 Label Studio 오픈
```

- SSO 자동 로그인
- 최소화 UI (panel, controls, annotations:menu)

## 웹훅 이벤트

Things-Factory가 수신하는 Label Studio 이벤트:

| 이벤트               | 설명              | 핸들러                      |
| -------------------- | ----------------- | --------------------------- |
| `ANNOTATION_CREATED` | 어노테이션 생성   | `handleAnnotationCreated()` |
| `ANNOTATION_UPDATED` | 어노테이션 수정   | `handleAnnotationUpdated()` |
| `ANNOTATION_DELETED` | 어노테이션 삭제   | `handleAnnotationDeleted()` |
| `TASK_CREATED`       | 태스크 생성       | `handleTaskCreated()`       |
| `PROJECT_UPDATED`    | 프로젝트 업데이트 | `handleProjectUpdated()`    |

**웹훅 엔드포인트:**

```
POST https://your-things-factory.com/label-studio/webhook
```

**커스터마이징:**
`server/route/webhook.ts`의 핸들러 함수를 수정하여 비즈니스 로직 구현

## 권한 매핑

| Things-Factory         | Label Studio               |
| ---------------------- | -------------------------- |
| Owner + label-studio   | Admin (is_superuser=true)  |
| label-studio privilege | Staff (is_superuser=false) |
| No label-studio        | Inactive (is_active=false) |

## 사용 예제

### 1. 이미지 분류 프로젝트

```graphql
# 1. 프로젝트 생성
mutation {
  createLabelStudioProject(
    input: {
      title: "Product Image Classification"
      labelConfig: """
      <View>
        <Image name="image" value="$image"/>
        <Choices name="category" toName="image" choice="single">
          <Choice value="Electronics"/>
          <Choice value="Clothing"/>
          <Choice value="Food"/>
        </Choices>
      </View>
      """
    }
  ) {
    id
  }
}

# 2. 이미지 임포트
mutation {
  importTasksToLabelStudio(projectId: 1, tasks: [{ data: "{\"image\": \"https://cdn.example.com/product1.jpg\"}" }]) {
    imported
  }
}

# 3. 웹훅 등록
mutation {
  registerLabelStudioWebhook(projectId: 1) {
    id
  }
}

# 4. 완료 후 익스포트
mutation {
  exportLabelStudioAnnotations(projectId: 1, format: "JSON") {
    exportPath
  }
}
```

### 2. 텍스트 감성 분석

```graphql
mutation {
  createLabelStudioProject(
    input: {
      title: "Customer Review Sentiment"
      labelConfig: """
      <View>
        <Text name="text" value="$text"/>
        <Choices name="sentiment" toName="text" choice="single">
          <Choice value="Positive"/>
          <Choice value="Negative"/>
          <Choice value="Neutral"/>
        </Choices>
      </View>
      """
    }
  ) {
    id
  }
}
```

### 3. Named Entity Recognition

```graphql
mutation {
  createLabelStudioProject(
    input: {
      title: "Document NER"
      labelConfig: """
      <View>
        <Text name="text" value="$text"/>
        <Labels name="label" toName="text">
          <Label value="Person" background="red"/>
          <Label value="Organization" background="blue"/>
          <Label value="Location" background="green"/>
        </Labels>
      </View>
      """
    }
  ) {
    id
  }
}
```

## 파일 구조

```
integration-label-studio/
├── server/
│   ├── types/
│   │   ├── label-studio-types.ts      # GraphQL 타입 정의
│   │   └── global.d.ts                # 전역 타입
│   ├── utils/
│   │   ├── label-studio-api-client.ts # REST API 클라이언트
│   │   ├── label-config-builder.ts    # 🆕 선언적 설정 생성
│   │   ├── task-transformer.ts        # 🆕 유연한 데이터 변환
│   │   └── annotation-exporter.ts     # 🆕 플러그인형 익스포트
│   ├── service/
│   │   ├── project/
│   │   │   └── project-management.ts  # 프로젝트 CRUD + 유연한 생성
│   │   ├── task/
│   │   │   └── task-management.ts     # 태스크 관리 + 변환 임포트
│   │   ├── webhook/
│   │   │   └── webhook-management.ts  # 웹훅 관리
│   │   ├── ml/
│   │   │   └── ml-backend-service.ts  # ML Backend
│   │   └── user-provisioning/
│   │       └── user-sync-mutation.ts  # 사용자 동기화
│   ├── route/
│   │   └── webhook.ts                 # 웹훅 라우터 + 확장 포인트
│   ├── route.ts                       # 메뉴 등록
│   └── index.ts                       # 모든 유틸리티 export
├── client/
│   ├── label-studio-wrapper.ts        # iframe 래퍼
│   ├── label-studio-project-list.ts   # 프로젝트 목록
│   ├── label-studio-project-create.ts # 프로젝트 생성
│   └── index.ts
├── README.md
├── SETUP_GUIDE.md
├── IMPLEMENTATION_GUIDE.md
└── package.json
```

## 애플리케이션 레벨 커스터마이징 예제

### 1. server/index.ts에서 초기화

```typescript
import {
  registerWebhookHandler,
  registerExportFormat,
  WebhookAction,
  LabelConfigTemplates,
  TaskTransformTemplates
} from '@things-factory/integration-label-studio'

// 웹훅 핸들러 등록
registerWebhookHandler(WebhookAction.ANNOTATION_CREATED, async (payload, ctx) => {
  // WBM 품질 시스템에 어노테이션 전송
  await sendToWBMQualitySystem(payload.annotation)
})

// 커스텀 익스포트 포맷 등록
registerExportFormat('wbm-report', (annotations, context) => {
  // WBM 전용 리포트 포맷
  return generateWBMReport(annotations)
})
```

### 2. GraphQL Resolver에서 사용

```typescript
import { LabelConfigBuilder, TaskTransformer } from '@things-factory/integration-label-studio'

@Mutation(returns => LabelStudioProject)
async createWBMProject(@Ctx() context: ResolverContext) {
  // 템플릿으로 설정 생성
  const config = LabelConfigTemplates.imageRankN(3, getWBMDefectTypes())
  const xml = LabelConfigBuilder.build(config)

  // Label Studio 프로젝트 생성
  const project = await labelStudioApi.createProject({
    title: 'WBM Defect Classification',
    label_config: xml
  })

  return project
}

@Mutation(returns => TaskImportResult)
async importWBMImages(@Arg('deviceData') deviceData: string) {
  const sourceData = JSON.parse(deviceData)

  // WBM 디바이스 데이터를 Label Studio 태스크로 변환
  const rule = TaskTransformTemplates.wbmImageClassification(true)
  const lsTasks = TaskTransformer.transform(sourceData, rule)

  // Label Studio에 임포트
  return await labelStudioApi.importTasks(projectId, lsTasks)
}
```

### 3. 클라이언트에서 사용

```typescript
// 프로젝트 생성 (선언적 사양 사용)
const result = await client.mutate({
  mutation: gql`
    mutation CreateWBMProject {
      createLabelStudioProjectWithSpec(
        input: { title: "WBM Line 1", labelConfigSpec: { dataType: "image", controls: "[...]" } }
      ) {
        id
      }
    }
  `
})

// 디바이스 데이터 임포트 (변환 사용)
const importResult = await client.mutate({
  mutation: gql`
    mutation ImportWBMData($input: ImportTasksWithTransformInput!) {
      importTasksWithTransform(projectId: 1, input: $input) {
        imported
        taskIds
      }
    }
  `,
  variables: {
    input: {
      sourceData: JSON.stringify(wbmDeviceData),
      transformRule: wbmTransformRule
    }
  }
})
```

## 트러블슈팅

### 웹훅이 수신되지 않음

**원인:** Label Studio가 Things-Factory에 접근 불가

**해결:**

```bash
# Label Studio에서 Things-Factory URL 접근 가능한지 확인
curl -X POST https://your-things-factory.com/label-studio/webhook \
  -H "Content-Type: application/json" \
  -d '{"action":"TEST"}'
```

### 프로젝트 생성 실패

**원인:** Label Studio API 토큰 없음

**해결:**

```bash
# Label Studio에서 API 토큰 발급
# Settings → Account → Access Token 복사
export LABEL_STUDIO_API_TOKEN=your-token
```

### CORS 에러

**원인:** Label Studio CORS 설정 누락

**해결:**
Label Studio settings에 추가:

```python
CORS_ALLOWED_ORIGINS = [
    'https://your-things-factory.com',
]
```

## 추가 문서

- [설치 및 설정 가이드](./SETUP_GUIDE.md)
- [구현 가이드](./IMPLEMENTATION_GUIDE.md)
- [UI 커스터마이징](./UI_CUSTOMIZATION.md)
- [사용자 동기화](./USER_SYNC_GUIDE.md)

## 라이선스

MIT

## 기여

버그 리포트 및 기능 제안은 GitHub Issues로 부탁드립니다.