@things-factory/integration-label-studio 9.1.19

package/server/SERVER_STRUCTURE.md

@@ -0,0 +1,351 @@
+# Label Studio Integration - Server 모듈 구조
+
+Things-Factory Label Studio 통합 서버 모듈의 최종 정리된 구조입니다.
+
+---
+
+## 📁 디렉토리 구조
+
+```
+server/
+├── controller/                          # 비즈니스 로직
+│   └── label-studio-role-mapper.ts     # 권한 매핑 로직
+├── service/                             # GraphQL 서비스
+│   ├── user-provisioning/
+│   │   ├── user-provisioning-service.ts # 사용자 동기화 서비스
+│   │   ├── user-sync-mutation.ts        # GraphQL Mutation
+│   │   └── index.ts
+│   └── index.ts                         # 서비스 통합
+├── index.ts                             # 서버 모듈 진입점
+└── route.ts                             # 메뉴 등록
+```
+
+---
+
+## 📋 파일별 역할
+
+### 1. **controller/label-studio-role-mapper.ts**
+
+Things-Factory 사용자 권한을 Label Studio 권한으로 매핑
+
+**주요 기능**:
+
+- `mapUserPermissions(domain, user)`: 권한 매핑
+- `getPermissionsDescription(permissions)`: 권한 설명
+
+**매핑 규칙**:
+
+```typescript
+// 1. label-studio 카테고리 권한 있음 → Staff
+// 2. user.owner === true → Admin
+```
+
+**반환값**:
+
+```typescript
+interface LabelStudioPermissions {
+  is_superuser: boolean // Admin 여부
+  is_staff: boolean // Django admin 접근
+  is_active: boolean // 활성화 여부
+}
+```
+
+---
+
+### 2. **service/user-provisioning/user-provisioning-service.ts**
+
+Label Studio API를 통한 사용자 동기화 서비스
+
+**주요 메서드**:
+
+#### `syncUser(domain, user): Promise<SyncResult>`
+
+개별 사용자를 Label Studio에 동기화
+
+```typescript
+// 1. 권한 확인
+const hasLSPrivilege = await User.hasPrivilege('label-studio', ...)
+
+// 2. 권한 매핑
+const lsPermissions = await LabelStudioRoleMapper.mapUserPermissions(domain, user)
+
+// 3. Label Studio API 호출
+const result = await createOrUpdateLabelStudioUser(...)
+```
+
+#### `syncAllUsers(domain): Promise<SyncSummary>`
+
+도메인의 모든 사용자를 일괄 동기화
+
+```typescript
+const users = await getDomainUsers(domain)
+for (const user of users) {
+  await syncUser(domain, user)
+}
+```
+
+#### `getDomainUsers(domain): Promise<User[]>`
+
+도메인의 모든 사용자 조회 (users_domains 테이블 조인)
+
+**Helper 메서드**:
+
+- `createOrUpdateLabelStudioUser()`: 사용자 생성/수정
+- `deactivateUser()`: 사용자 비활성화
+- `buildApiUrl()`: API URL 생성
+- `generateRandomPassword()`: 랜덤 패스워드 생성
+- `sleep()`: Rate Limiting 방지
+
+---
+
+### 3. **service/user-provisioning/user-sync-mutation.ts**
+
+GraphQL Mutation 정의
+
+**Mutations**:
+
+#### `syncMyUserToLabelStudio`
+
+```graphql
+mutation {
+  syncMyUserToLabelStudio {
+    success
+    email
+    action
+    lsPermissions
+  }
+}
+```
+
+**권한**: `@privilege(category: "label-studio", privilege: "staff")`
+
+#### `syncAllUsersToLabelStudio`
+
+```graphql
+mutation {
+  syncAllUsersToLabelStudio {
+    total
+    created
+    updated
+    deactivated
+    skipped
+    errors
+    results {
+      email
+      action
+      lsPermissions
+    }
+  }
+}
+```
+
+**권한**: `@privilege(category: "label-studio", privilege: "admin")`
+
+---
+
+### 4. **service/index.ts**
+
+GraphQL 리졸버 통합
+
+```typescript
+export const resolvers = [UserSyncMutation]
+export * from './user-provisioning/index.js'
+```
+
+---
+
+### 5. **index.ts**
+
+서버 모듈 진입점
+
+```typescript
+export * from './service/index.js'
+import './route.js'
+```
+
+---
+
+## 🔄 데이터 흐름
+
+### 사용자 동기화 플로우
+
+```
+1. GraphQL Mutation 호출
+   ↓
+2. user-sync-mutation.ts
+   - 설정 검증 (apiToken 확인)
+   ↓
+3. user-provisioning-service.ts
+   - 권한 확인 (User.hasPrivilege)
+   ↓
+4. label-studio-role-mapper.ts
+   - 권한 매핑 (label-studio 카테고리 → Staff/Admin)
+   ↓
+5. Label Studio API 호출
+   - POST/PATCH /api/users
+   - is_superuser, is_staff, is_active 설정
+   ↓
+6. 결과 반환
+   - SyncResult / SyncSummary
+```
+
+---
+
+## 🔧 설정
+
+### config/config.development.js
+
+```javascript
+labelStudio: {
+  serverUrl: 'http://localhost:8080',
+  apiToken: '',  // Label Studio API Token
+  interfaces: 'panel,controls,annotations:menu'
+}
+```
+
+### 설정 사용
+
+```typescript
+import { config } from '@things-factory/env'
+
+const labelStudioConfig = config.get('labelStudio', {
+  serverUrl: '',
+  apiToken: '',
+  interfaces: 'panel,controls,annotations:menu'
+})
+```
+
+---
+
+## 🗑️ 제거된 항목
+
+### 1. **LabelStudioConfig Entity**
+
+- 엔티티 DB 저장 제거
+- config 파일로 대체
+
+### 2. **label-studio-config 폴더**
+
+- `label-studio-config.ts` (Entity)
+- `label-studio-config-query.ts` (Query)
+- `label-studio-config-mutation.ts` (Mutation)
+
+### 3. **role-mapping 폴더**
+
+- `label-studio-role-mapper.ts` → controller로 이동
+
+### 4. **불필요한 메서드**
+
+- `getOrganizationId()` - Community Edition 미사용
+- `createOrganizationMembership()` - Community Edition 미사용
+- `updateOrganizationMembership()` - Community Edition 미사용
+
+### 5. **entities 배열**
+
+- `service/index.ts`의 빈 entities 배열 제거
+
+---
+
+## 📊 권한 체계
+
+### Things-Factory 권한
+
+| Privilege Category      | 설명                   |
+| ----------------------- | ---------------------- |
+| `label-studio:query`    | Label Studio 조회 권한 |
+| `label-studio:mutation` | Label Studio 수정 권한 |
+| `label-studio:staff`    | Staff 전용 mutation    |
+| `label-studio:admin`    | Admin 전용 mutation    |
+
+### Label Studio 권한 (Community Edition)
+
+| 플래그                | 설명              |
+| --------------------- | ----------------- |
+| `is_superuser: true`  | Admin (모든 권한) |
+| `is_superuser: false` | Staff (라벨링만)  |
+| `is_active: false`    | 비활성화          |
+
+---
+
+## 🧪 테스트
+
+### 1. 개인 동기화
+
+```graphql
+mutation {
+  syncMyUserToLabelStudio {
+    success
+    email
+    action
+    lsPermissions
+  }
+}
+```
+
+### 2. 전체 동기화
+
+```graphql
+mutation {
+  syncAllUsersToLabelStudio {
+    total
+    created
+    updated
+    results {
+      email
+      lsPermissions
+      error
+    }
+  }
+}
+```
+
+---
+
+## 📝 코드 규칙
+
+### 1. 권한 확인
+
+```typescript
+// User.hasPrivilege 사용
+const hasPrivilege = await User.hasPrivilege('label-studio', 'query', domain, user)
+```
+
+### 2. 설정 가져오기
+
+```typescript
+// config.get 사용
+const config = config.get('labelStudio', {
+  serverUrl: '',
+  apiToken: '',
+  interfaces: 'panel,controls,annotations:menu'
+})
+```
+
+### 3. API 호출
+
+```typescript
+// axios 사용
+await axios.patch(`${apiUrl}/users/${id}/`, data, {
+  headers: {
+    Authorization: `Token ${config.apiToken}`,
+    'Content-Type': 'application/json'
+  }
+})
+```
+
+---
+
+## 🚀 향후 확장
+
+### 가능한 개선사항
+
+1. **Batch API 지원**: 여러 사용자 한 번에 동기화
+2. **Webhook 연동**: Label Studio → Things-Factory 이벤트
+3. **동기화 스케줄러**: 주기적 자동 동기화
+4. **에러 재시도 로직**: 실패 시 재시도
+
+---
+
+**문서 버전**: 1.0
+**작성일**: 2025-10-03
+**정리 완료**: ✅

package/server/controller/label-studio-role-mapper.ts

@@ -0,0 +1,76 @@
+import { Domain } from '@things-factory/shell'
+import { User } from '@things-factory/auth-base'
+/**
+ * Label Studio Community Edition 권한
+ * Community Edition은 Django의 is_superuser 플래그만 사용
+ */
+export interface LabelStudioPermissions {
+  is_superuser: boolean // true: 관리자, false: 일반 사용자
+  is_staff: boolean // Django admin 페이지 접근 (일반적으로 is_superuser와 동일)
+  is_active: boolean // 활성화 여부
+}
+
+/**
+ * Things-Factory Role → Label Studio Permissions 매핑
+ * Community Edition용 (2단계 권한)
+ */
+export class LabelStudioRoleMapper {
+  /**
+   * Things-Factory 사용자의 권한을 분석하여 Label Studio 권한 결정
+   *
+   * 매핑 규칙:
+   * 1. privilege category에 'label-studio'가 포함되어 있으면 → Staff 권한
+   * 2. user.admin === true 이면 → Admin 권한
+   *
+   * @param user Things-Factory 사용자
+   * @returns Label Studio 권한 (is_superuser, is_staff, is_active)
+   */
+  static async mapUserPermissions(domain: Domain, user: User): Promise<LabelStudioPermissions> {
+    // 사용자의 권한 조회
+    // 1. Label Studio 관련 권한이 있는지 확인 (category에 'label-studio' 포함)
+    const hasLabelStudioPrivilege =
+      (await User.hasPrivilege('label-studio', 'query', domain, user)) ||
+      (await User.hasPrivilege('label-studio', 'mutation', domain, user))
+
+    // Label Studio 권한이 없으면 비활성화
+    if (!hasLabelStudioPrivilege) {
+      return {
+        is_superuser: false,
+        is_staff: false,
+        is_active: false
+      }
+    }
+
+    // 2. user.owner 플래그 확인
+    if (user.owner === true) {
+      return {
+        is_superuser: true,
+        is_staff: true,
+        is_active: true
+      }
+    }
+
+    // 3. Label Studio 권한은 있지만 owner가 아닌 경우 → Staff
+    return {
+      is_superuser: false,
+      is_staff: false,
+      is_active: true
+    }
+  }
+
+  /**
+   * Label Studio 권한 설명 반환 (디버깅/로깅용)
+   *
+   * @param permissions Label Studio 권한
+   * @returns 권한 설명
+   */
+  static getPermissionsDescription(permissions: LabelStudioPermissions): string {
+    if (!permissions.is_active) {
+      return 'Inactive (No Label Studio access)'
+    }
+    if (permissions.is_superuser) {
+      return 'Admin (Full access)'
+    }
+    return 'Staff (Labeling only)'
+  }
+}