🏭 워크샵 · 할당 · 검수

Workforce 척추의 뒷부분입니다: 워크샵(사람 배치) → 할당작업(Assignment) → 제출 → 검수(승인·반려). "작업자·검수자를 배치하고 싶다", "내 할당작업을 제출하겠다", "검수하고 승인/반려하겠다", "반려 사유·검수 이력을 보고 싶다" 같은 요청이 이 페이지의 도구로 흘러갑니다. 라벨링 내용 자체를 만드는 앞 구간은 프로젝트 · 라벨링을 보세요.

검수 여정은 다음과 같이 흐릅니다. 라벨링 자체는 annotate_task_data(projects-labeling 페이지)로 하고, 이 페이지는 그 산출물을 제출하고 검수하는 구간을 담당합니다.

flowchart LR
    A["할당<br/>(워크샵에 작업자·검수자 배치)"] --> B["라벨링<br/>annotate_task_data<br/><i>projects-labeling.md</i>"]
    B --> C["제출<br/>submit_assignment"]
    C --> D["검수 근거 수집<br/>inspect_labeling"]
    D --> E{판단}
    E -->|승인| F[approve_assignment]
    E -->|반려| G[reject_assignment]
    G --> B
    style C fill:#e8f0fe,stroke:#4285f4,color:#202124
    style D fill:#e8f0fe,stroke:#4285f4,color:#202124
    style F fill:#e6f4ea,stroke:#34a853,color:#202124
    style G fill:#fce8e6,stroke:#ea4335,color:#202124

불변식 — 미리 알아야 할 것

• 워크샵의 할당 단위(level_distribution)와 검수 단계 사용 여부(is_reviewable)는 생성 후 변경 불가입니다.
• 할당작업은 완료확정(is_confirmed) 후 수정 불가이며, 완료확정과 불량확정은 동시에 될 수 없습니다(상호배타).
• 권한은 관계의 역할입니다 — 워크샵에서는 Labeler(작업자) / Reviewer(검수자) 역할이 가능한 액션을 결정합니다.

상태전환 vs 데이터 정정 — 별개 도구

이 페이지에서 가장 자주 헷갈리는 지점입니다.

• 상태전환 (워크플로를 진행시키는 동작): submit_assignment · approve_assignment · reject_assignment (한 건, 작업자/검수자 역할)
• 매니저 일괄 상태전환·담당자 지정 (여러 건, 매니저 권한): perform_assignment_actions
• 데이터 정정 (어노테이션 내용을 고치는 동작): update_assignment_data
• 검수 코멘트/태그 정정: update_review — 이것도 상태전환이 아닙니다.

"반려한다"와 "라벨을 고친다"는 서로 다른 도구입니다.

두 태그 도구 혼동 주의

• manage_review_tags (이 페이지) — 검수 태그(ReviewTag).
• manage_project_tags — 작업 태그·할당작업 태그(TaskTag) 정의.

이름이 비슷하지만 대상이 완전히 다릅니다.

도구 한눈에

도구	무엇을 할 때	쓰기 여부
manage_workshop	워크샵 생성/수정/삭제/참여	✏️ 쓰기(confirm)
manage_workshop_workers	작업자(worker) 배정 관리	✏️ 쓰기(confirm)
manage_reviewer_covers	검수자(reviewer) 커버 배정 관리	✏️ 쓰기(confirm)
list_assignments	할당작업 목록·상태 확인	읽기
get_assignment	할당작업 1건 상세	읽기
get_assignment_llm_reviews	할당작업 LLM 검수 결과(참고용)	읽기
submit_assignment	작업 제출 (labeler) — 상태전환	✏️ 쓰기(confirm)
approve_assignment	작업 승인 (reviewer) — 상태전환	✏️ 쓰기(confirm)
reject_assignment	작업 반려 (reviewer) — 상태전환	✏️ 쓰기(confirm)
perform_assignment_actions	여러 할당작업을 매니저 권한으로 일괄 상태전환·작업자/검수자 지정	✏️ 쓰기(confirm)
update_assignment_data	할당작업 어노테이션 데이터 정정	⚠️ 파괴적(confirm)
list_reviews	검수(반려/코멘트) 이력 목록	읽기
get_review	검수 1건 상세	읽기
update_review	검수 코멘트/태그 정정	✏️ 쓰기(confirm)
manage_review_tags	검수 태그(ReviewTag) 관리	✏️ 쓰기(confirm)
inspect_labeling	스키마 대조 검수 리포트	읽기

도구 상세

manage_workshop

🏭 Workforce. 워크샵(작업자·검수자가 모이는 작업 단위)을 생성/수정/삭제하거나 본인이 참여합니다 (action=create|update|delete|participate).

불변식: level_distribution(할당 단위 0/1/2)과 is_reviewable(검수 단계 사용 여부)는 생성 후 변경 불가 — 변경을 시도하면 서버가 거부하며 사유를 그대로 보여줍니다. 워크샵을 만들 때 신중히 정하세요.

• 주요 인자: action, workshop_id (update/delete/participate 대상), project, name, visibility (public|private), level_distribution, is_reviewable, can_skip_labeler/can_skip_reviewer, access_code, role (labeler|reviewer, 참여 시), llm_review_enabled·llm_review_prompt
• LLM 검수 오버라이드: 워크샵에 값을 주면 프로젝트 LLM 검수 설정보다 우선합니다. 워크샵 값을 지워 다시 프로젝트 설정을 따르게 하는 것은 웹 UI 에서 합니다.
• 안전장치: 기본 dry-run 미리보기(검증만, 미적용) → confirm=true 재호출 시 실제 적용
• 함께 보기: 사람 배치는 manage_workshop_workers · manage_reviewer_covers

manage_workshop_workers

🏭 Workforce. 워크샵의 작업자(worker) 배정을 조회/추가/수정/제거합니다(action=list|add|update|remove). 배정(WorkerAssignment)은 할당작업(Assignment)과 다른 개념입니다 — 이 도구는 "누가 이 워크샵에서 일할 수 있는지"만 다루고, 실제 작업 배정은 별도입니다. 제거 시 미확정 할당을 보유한 작업자는 서버가 거부하며 사유를 그대로 보여줍니다.

• 주요 인자: workshop_id, action, worker_id (update/remove 대상), user (추가할 사용자 ID), count_max_tasks
• 안전장치: 기본 dry-run 미리보기 → confirm=true 재호출 시 실제 적용
• 함께 보기: 검수자 배정은 manage_reviewer_covers · 실제 할당작업 확인은 list_assignments

manage_reviewer_covers

🏭 Workforce. 워크샵의 검수자(reviewer) 커버 배정을 조회/추가/수정/제거합니다(action=list|add|update|remove). can_self_review 는 본인이 라벨링한 건을 본인이 검수할 수 있는지를 결정합니다. 제거 시 미확정 할당을 보유한 검수자는 서버가 거부하며 사유를 그대로 보여줍니다.

• 주요 인자: workshop_id, action, cover_id (update/remove 대상), user, count_max_tasks, can_self_review
• 안전장치: 기본 dry-run 미리보기 → confirm=true 재호출 시 실제 적용
• 함께 보기: 작업자 배정은 manage_workshop_workers

list_assignments

할당작업(작업자에게 배정된 어노테이션 건) 목록을 봅니다. 작업 진행·상태를 확인할 때 부릅니다. 라벨링 상태(status_label)와 검수 상태(status_review)를 각각 필터할 수 있습니다.

• 주요 인자: project, workshop, status_label (stand_by·in_progress·completed·skipped), status_review (stand_by·in_progress·rejected·completed·skipped), is_confirmed (완료확정 여부), search, ids/ids_ex, classes (라벨된 클래스 code, 콤마 구분·하나라도 포함), sort, 페이지네이션(cursor/per_page)
• 검색: search 는 서버 검색입니다 — 작업자·검수자 이름/이메일, 파일 원본 경로, 데이터 그룹명은 부분일치, 할당작업 ID·태스크 ID 는 정확일치. 예) "김 작업자의 할당작업" → search="kim".
• ID 지정: ids/ids_ex 는 콤마·범위 형식 — 예) ids="1-100,200", ids_ex="50".
• 정렬: sort 는 created·-created·id·-id(기본 -created 최신순). 오래 방치된 할당작업부터 보려면 sort="created".
• 함께 보기: 상세는 get_assignment

get_assignment

할당작업 1건 상세를 봅니다. list_assignments에서 얻은 id 로 조회합니다.

• 주요 인자: id
• 함께 보기: 검수 근거 리포트는 inspect_labeling (assignment_id 로 바로 조회 가능) · LLM 자동 검수 결과는 get_assignment_llm_reviews

get_assignment_llm_reviews

할당작업이 제출될 때 실행된 LLM 검수 결과를 최신순으로 봅니다. 판정(통과/확인 필요/판단 불가)·요약· 지적 목록(행마다 5개까지)을 보여 주고, 건너뛴 경우 사유(설정 꺼짐·LLM 연결 없음·시간당 한도 초과)를 풀어 줍니다.

• 주요 인자: assignment_id, cursor, per_page (최대 200)
• 참고용: 작업 상태를 바꾸지 않습니다 — 승인/반려는 approve_assignment / reject_assignment.
• 기록이 없으면: 프로젝트/워크샵에서 검수가 꺼져 있거나 아직 제출되지 않은 것입니다(설정).

submit_assignment

작업(assignment)을 제출합니다 — labeler 역할의 상태전환입니다. 라벨링을 마친 할당작업을 검수(또는 완료) 단계로 진행시킬 때 부릅니다. 상태전환은 워크플로를 진행시키는 동작이며, 어노테이션 내용 수정은 update_assignment_data가 담당합니다(별개). v1 영구 API (action system 예외 — 마이그레이션 대상 아님).

• 주요 인자: id
• 안전장치: 기본 미리보기(현재 상태·가용 액션 조회만, 미변경) → confirm=true 재호출 시 실제 상태전환
• 함께 보기: 이후 검수는 inspect_labeling → approve_assignment / reject_assignment

approve_assignment

작업(assignment)을 승인합니다 — reviewer 역할의 상태전환입니다. 검수 결과 문제가 없을 때 부릅니다. 승인·반려 판단의 근거는 inspect_labeling 리포트로 수집하세요. v1 영구 API (action system 예외 — 마이그레이션 대상 아님).

• 주요 인자: id
• 안전장치: 기본 미리보기(현재 상태·가용 액션 조회만, 미변경) → confirm=true 재호출 시 실제 상태전환
• 함께 보기: 반대 판단은 reject_assignment

reject_assignment

작업(assignment)을 반려합니다 — reviewer 역할의 상태전환입니다. 검수 결과 보완이 필요할 때 부릅니다. 반려는 상태전환일 뿐이며, 데이터를 직접 고치려면 update_assignment_data를 쓰세요(별개 도구). v1 영구 API (action system 예외 — 마이그레이션 대상 아님).

• 주요 인자: id
• 안전장치: 기본 미리보기(현재 상태·가용 액션 조회만, 미변경) → confirm=true 재호출 시 실제 상태전환
• 함께 보기: 검수 태그 관리는 manage_review_tags · 반려 이력은 list_reviews

perform_assignment_actions

여러 할당작업을 매니저 권한으로 한꺼번에 처리합니다(v2 매니저 bulk action). 한 건을 작업자/검수자로 처리하는 submit_assignment · approve_assignment · reject_assignment와 역할이 다릅니다.

action	하는 일	처리
start	작업 시작 상태로	비동기 작업
label_complete	라벨 완료(검수 대기)로	비동기 작업
approve	검수 승인	즉시 완료
reject	검수 반려	즉시 완료
set_rejected	반려 상태로 되돌림	비동기 작업
confirm / unconfirm	완료 확정 / 확정 취소	즉시 완료
set_labeler	작업자 지정 (labeler_id 필수)	비동기 작업
set_reviewer	검수자 지정 (reviewer_id 필수)	비동기 작업
remove_reviewer	검수자 해제	비동기 작업

대상 조건 필수

ids(예: "1,2,10-20")·filters·search 중 하나 이상을 지정해야 합니다 — 조건 없이 프로젝트 전체가 대상이 되는 호출은 API 호출 없이 거부합니다. 불량 확정·취소는 일괄 처리 대상이 아닙니다(백엔드가 거부).

• 주요 인자: project_id, action, 대상 조건(위), labeler_id/reviewer_id
• 안전장치: 기본 dry-run 미리보기 — 대상·수행 가능 건수와 항목별 거절 사유(최대 20건, 넘치면 "외 n건")를 보여줍니다. confirm=true 재호출 시 실행합니다. 즉시 완료 액션은 결과(처리 건수·거절 표)를 바로 돌려주고, 비동기 액션은 job_id 를 돌려주므로 get_async_job으로 진행을 확인합니다.
• 전건 거절: 실행 시 모든 대상이 거절되면 "전건 거절" 요약을 보여줍니다. 항목별 사유는 confirm=false 로 다시 호출해 확인하세요.
• 권한·선택 오류: 프로젝트 매니저(변경) 권한이 필요합니다. 다른 프로젝트의 할당작업이 ids 에 섞이거나 대상이 없으면 서버 메시지와 함께 점검 항목을 안내합니다.
• 예시: "프로젝트 12에서 검수 대기 중인 1~50번 할당작업을 일괄 승인해줘" → action=approve, ids="1-50" (먼저 미리보기)

update_assignment_data

🏭 Workforce. 할당작업(assignment)의 어노테이션 데이터(data)를 정정합니다.

라벨링 산출물을 덮어씁니다

기존 라벨링 산출물을 덮어쓰며 되돌리기 어렵습니다. 반드시 미리보기로 확인 후 진행하세요.

상태전환은 별도 액션입니다 — 제출/승인/반려는 submit_assignment / approve_assignment / reject_assignment 를 쓰고, 이 도구는 데이터 정정만 합니다.

• 주요 인자: assignment_id, data (어노테이션 payload)
• 안전장치: 기본 dry-run 미리보기(검증만, 미변경) → confirm=true 재호출 시 실제 적용
• 함께 보기: 태스크 단위 저장/제출은 annotate_task_data

list_reviews

🏭 Workforce. 검수(Review) 목록 — 반려/코멘트 이력을 확인할 때 부릅니다. 조회 전용이며, 코멘트·태그 정정은 update_review를 씁니다.

• 주요 인자: assignment (할당작업 ID), scope (annotation·assignment·group·project), 페이지네이션(cursor/per_page)
• 함께 보기: 상세는 get_review

get_review

🏭 Workforce. 검수 1건 상세 — list_reviews에서 얻은 id 로 조회합니다. 조회 전용이며, 정정은 update_review(review_id=id)를 씁니다.

• 주요 인자: id

update_review

🏭 Workforce. 검수(Review)의 코멘트/태그를 정정합니다 — 상태전환이 아닙니다. 승인/반려는 approve_assignment / reject_assignment 를 쓰고, 조회는 list_reviews / get_review 를 씁니다.

• 주요 인자: review_id, description (코멘트), tags (태그 ID 배열)
• 안전장치: 기본 dry-run 미리보기 → confirm=true 재호출 시 실제 적용
• 함께 보기: 태그 자체의 생성·관리는 manage_review_tags

manage_review_tags

🏭 Workforce. 검수 태그(ReviewTag)를 조회/생성/수정/삭제합니다(action=list|create|update|delete). 작업 태그·할당작업 태그(TaskTag, manage_project_tags)와는 다른 대상입니다 — 이 도구는 검수에서 붙이는 태그 전용입니다. 태그는 tag_code 가 아니라 name+background_color 로 식별합니다.

• 주요 인자: action, project_id, tag_id (update/delete 대상), name, background_color, description
• 안전장치: 기본 dry-run 미리보기 → confirm=true 재호출 시 실제 적용
• 함께 보기: 반려 통계는 get_project_statistics (kind=rejection) · 태그를 리뷰에 붙이는 건 update_review

inspect_labeling

🔗 T3 여정 워크플로. 태스크의 어노테이션을 프로젝트 라벨링 스키마와 대조해 검수 리포트를 냅니다: 클래스 분포 · 스키마 미정의 코드 · 필수 속성 누락 · 중복 id. 검수자가 승인/반려를 판단하기 전 근거를 모을 때 부릅니다. task_id 또는 assignment_id(할당작업→작업 자동 해소) 중 하나를 주면 되고, focus_class 로 특정 클래스만 좁혀볼 수 있습니다.

도구는 사실만 보고합니다 — 승인·반려 판단은 이 리포트를 근거로 approve_assignment / reject_assignment 로 실행하세요.

• 주요 인자: task_id 또는 assignment_id (택1), focus_class (선택)
• 함께 보기: 스키마 자체는 get_labeling_schema · 내용 요약은 get_task_data