🏭 데이터 준비 · 업로드

Workforce 척추의 앞부분입니다 — 라벨링할 데이터를 담을 컬렉션(그릇) 을 만들고, 파일을 업로드해서 데이터유닛(개별 데이터 항목)으로 등록하는 구간. "데이터를 올리고 싶다", "어떤 데이터셋이 있는지 보고 싶다", "이 컬렉션에 뭐가 들어 있나" 가 궁금할 때 이 페이지입니다. 업로드는 2단계(presign → finalize)이며, 서버는 파일 바이트를 직접 받지 않습니다.

flowchart LR
    S["`get_file_specifications`"] --> C["`create_data_collection`"] --> P["`prepare_data_upload`"] --> PUT["호스트가 직접 PUT<br/>(out-of-band)"] --> F["`finalize_data_upload`"]

불변식 — 미리 알아야 할 것

• 컬렉션의 category(image/video/audio/pcd/text)는 생성 후 불변 — 이 종류가 프로젝트·어노테이터·라벨링 유형·스키마까지 사슬로 전파됩니다.
• 업로드는 2단계(presign → finalize)이며, 원격 서버는 파일 바이트를 직접 받지 않습니다 — 실제 PUT 은 호스트/CLI 가 수행합니다.
• 임포트 시 중복 파일은 자동 스킵됩니다(content-addressed).
• 데이터유닛 삭제 = 파생된 작업·할당작업·정답데이터 접근 불가 — 파괴적 경계이므로 반드시 경고 대상입니다.

도구 한눈에

도구	무엇을 할 때	쓰기 여부
list_data_collections	데이터 컬렉션(데이터셋) 찾기·둘러보기	읽기
get_data_collection	컬렉션 1건 상세	읽기
create_data_collection	새 컬렉션(그릇) 만들기	✏️ 쓰기(confirm)
update_data_collection	컬렉션 이름/설명 수정 · 파일 사양 추가(병합)	✏️ 쓰기(confirm)
delete_data_collection	컬렉션 삭제	⚠️ 파괴적(confirm)
list_data_units	컬렉션 안 개별 데이터 항목 목록	읽기
get_data_unit	데이터유닛 1건 상세	읽기
get_file_specifications	카테고리별 파일 스펙·허용 확장자 확인	읽기
prepare_data_upload	업로드 1단계 — presigned URL 발급	✏️ 쓰기
finalize_data_upload	업로드 2단계 — 확정 + 데이터유닛 생성	✏️ 쓰기(confirm)

도구 상세

list_data_collections

데이터 컬렉션(원천 데이터 묶음) 목록입니다. 데이터셋을 찾을 때 부릅니다. name 인자는 현재 페이지 안에서만 부분일치로 거릅니다(서버 검색 아님) — 매칭이 없으면 cursor 로 다음 페이지를 계속 조회하세요.

• 주요 인자: category (audio·data·image·pcd·text·video), is_archived, name (페이지 내 부분일치), 페이지네이션(cursor/per_page).
• 함께 보기: 1건 상세는 get_data_collection.

get_data_collection

데이터 컬렉션 1건 상세 — list_data_collections 목록의 id 로 조회합니다.

• 주요 인자: id (컬렉션 ID).

create_data_collection

데이터 컬렉션을 생성합니다. category(image·video·audio·text·pcd·data)만 고르면 필수 파일 스펙(MAIN 1개)이 자동 합성되므로 보통은 그대로 두면 됩니다. 새 데이터를 담을 그릇이 필요할 때 부릅니다. category 는 생성 후 바꿀 수 없으니 데이터 종류가 정해졌을 때 만드세요.

• 주요 인자: name, category, description/caution/access_level (선택), file_specifications (선택).
• 안전장치: 기본은 dry-run 미리보기(검증만, 미생성) → confirm=true 로 재호출해야 실제 생성됩니다.
• 함께 보기: 카테고리별 스펙 확인은 get_file_specifications, 생성 후 업로드는 prepare_data_upload.

파일 사양을 직접 지정하기 (메타 파일 포함)

원본 파일 외에 메타 파일(촬영 정보 JSON 등)을 함께 관리하려면 file_specifications 로 구조를 직접 지정합니다.

[
  {"name": "image_1", "file_type": "image", "is_primary": true, "function_type": "main"},
  {"name": "data_meta_1", "file_type": "data", "function_type": "meta"}
]

• function_type: meta 사양은 카테고리 제약을 받지 않습니다. image 컬렉션에도 data_meta_1(file_type=data)처럼 임의 접두사·임의 file_type 으로 넣을 수 있습니다. 카테고리 템플릿(get_file_specifications 의 표)에 매이는 것은 main/sub 사양뿐입니다.
• 이름 규칙: <접두사>_<번호>. 같은 접두사 그룹 안에서 번호는 1부터 연속이어야 합니다(data_meta_1, data_meta_2).
• 필수 불변식: is_primary=true 1개 + function_type="main" 1개 (정확히 하나씩).
• 자동 채움: index 는 이름에서, function_type 은 is_primary=true 일 때 main 으로, is_required 는 main 일 때만 true 로 채워집니다. 미리보기 표에서 확인하세요.
• 업로드 연결: 여기서 정한 사양 이름이 곧 prepare_data_upload/finalize_data_upload 의 spec_name 입니다(예: data_meta_1 사양에 붙일 JSON 파일은 spec_name="data_meta_1").

update_data_collection

데이터 컬렉션의 name/description 을 수정하고, file_specifications 로 파일 사양을 추가·수정합니다. 컬렉션을 만든 뒤에 메타 파일 사양을 붙이고 싶을 때도 이 도구를 씁니다.

• 주요 인자: id, name/description (바꿀 값만), file_specifications (추가·수정할 사양만).
• 병합 동작: 넘긴 사양은 기존 사양과 병합됩니다 — 같은 이름은 교체, 새 이름은 추가, 넘기지 않은 기존 사양은 유지. 이 도구는 파일 사양을 삭제하지 않습니다 — 웹 UI 에도 삭제 경로는 없습니다. 데이터 구조는 컬렉션 생성 시에만 정해지고 이후 변경 불가이며(설정 화면에서 바꿀 수 있는 것은 '파일셋 설명'뿐), 구조를 바꾸려면 새 컬렉션을 만들어야 합니다.
• 제약: 이미 데이터가 업로드된 컬렉션에는 필수(is_required=true) 사양을 새로 추가할 수 없고, 메인 사양은 수정할 수 없습니다.
• 안전장치: 기본은 dry-run 미리보기(검증만, 미변경 — 추가/수정/유지 표시) → confirm=true 로 재호출해야 실제 수정됩니다.

delete_data_collection

데이터 컬렉션을 삭제합니다. 더 이상 쓰지 않는 컬렉션을 정리할 때만 신중하게 부릅니다.

• 주요 인자: id, name (선택).
• 안전장치: 기본은 dry-run 미리보기(검증만, 미삭제) → confirm=true 로 재호출해야 실제 삭제됩니다.

list_data_units

데이터유닛(컬렉션 내 개별 데이터 항목) 목록입니다. "이 컬렉션에 어떤 데이터가 들어 있나" 를 볼 때 부릅니다.

• 주요 인자: data_collection (컬렉션 ID 로 필터), 페이지네이션(cursor/per_page).
• 함께 보기: 1건 상세는 get_data_unit.

get_data_unit

데이터유닛 1건 상세 — list_data_units 목록의 id 로 조회합니다.

• 주요 인자: id (데이터유닛 ID).

get_file_specifications

🔗 공용. 컬렉션 생성(create_data_collection)·업로드(prepare_data_upload) 시 file_specifications payload 구성에 필요한 카테고리별 스펙·허용 확장자·검증 규칙을 조회합니다 — "파일 스펙에 맞춘 정리 후 업로드" 워크플로의 전제이므로, 업로드를 시작하기 전에 먼저 부릅니다.

• 주요 인자: 없음(전체 카테고리 응답).

prepare_data_upload

데이터 업로드 1단계 — presigned URL 발급. 파일별 filename/size/spec_name 을 받아 백엔드에 presign 을 요청하고, 호스트가 직접 PUT 할 URL 을 반환합니다. 이 도구는 파일 바이트를 받지 않으며(바이트 전송은 out-of-band), 발급된 file_key 는 다음 단계에 넘깁니다.

• 주요 인자: collection_id, files (파일별 filename/size/spec_name 목록).
• 함께 보기: 스펙 확인은 get_file_specifications, PUT 완료 후 확정은 finalize_data_upload.

finalize_data_upload

데이터 업로드 2단계 — 업로드 확정 + 데이터유닛 생성. PUT 이 끝난 file_key/checksum 을 받아 확정하고, 컬렉션에 데이터유닛을 생성합니다. 같은 파일 구성의 유닛이 이미 있으면 재사용하므로 반복 호출이 안전합니다.

• 주요 인자: collection_id, files (PUT 완료된 file_key/checksum 목록. 원본 경로를 남기려면 path 도 함께).
• 안전장치: confirm=false(기본)는 file→spec 매핑 미리보기만 렌더하고 네트워크를 치지 않습니다 → confirm=true 로 재호출해야 실제 확정됩니다.
• 함께 보기: 1단계는 prepare_data_upload, 작업 생성은 create_tasks_from_units.

create_tasks_from_units

생성된 데이터유닛으로 작업(태스크)을 일괄 생성합니다. 업로드 경로의 마지막 단계이자, 이미 있는 유닛으로도 쓸 수 있는 독립 도구입니다.

• 주요 인자: project, data_unit_ids (작업을 만들 유닛 id 목록).
• 제약: 대상 유닛은 모두 같은 컬렉션이어야 하고, 그 컬렉션이 project 의 컬렉션과 같아야 합니다(아니면 400).
• 멱등: 이미 그 프로젝트에 작업이 있는 유닛은 건너뜁니다(skipped_count) — 반복 호출이 안전합니다.
• 안전장치: confirm=false(기본)는 서버 dry-run 으로 검증만 합니다(프로젝트↔컬렉션 호환·권한·유닛 존재를 서버가 판단) → confirm=true 로 재호출해야 실제 생성됩니다.
• 함께 보기: 생성된 작업 확인은 list_tasks.