🏭 워크샵 · 할당 · 검수

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
• 데이터 정정 (어노테이션 내용을 고치는 동작): update_assignment_data
• 검수 코멘트/태그 정정: update_review — 이것도 상태전환이 아닙니다.

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

두 태그 도구 혼동 주의

• manage_review_tags (이 페이지) — 검수 반려 사유 태그.
• manage_project_tags — task 분류용 프로젝트 태그.

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

도구 한눈에

도구	무엇을 할 때	쓰기 여부
manage_workshop	워크샵 생성/수정/삭제/참여	✏️ 쓰기(confirm)
manage_workshop_workers	작업자(worker) 배정 관리	✏️ 쓰기(confirm)
manage_reviewer_covers	검수자(reviewer) 커버 배정 관리	✏️ 쓰기(confirm)
list_assignments	할당작업 목록·상태 확인	읽기
get_assignment	할당작업 1건 상세	읽기
submit_assignment	작업 제출 (labeler) — 상태전환	✏️ 쓰기(confirm)
approve_assignment	작업 승인 (reviewer) — 상태전환	✏️ 쓰기(confirm)
reject_assignment	작업 반려 (reviewer) — 상태전환	✏️ 쓰기(confirm)
update_assignment_data	할당작업 어노테이션 데이터 정정	⚠️ 파괴적(confirm)
list_reviews	검수(반려/코멘트) 이력 목록	읽기
get_review	검수 1건 상세	읽기
update_review	검수 코멘트/태그 정정	✏️ 쓰기(confirm)
manage_review_tags	검수 반려 사유 태그 관리	✏️ 쓰기(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, 참여 시)
• 안전장치: 기본 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 (완료확정 여부), 페이지네이션(cursor/per_page)
• 함께 보기: 상세는 get_assignment

get_assignment

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

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

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

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. 검수 반려 사유 태그를 조회/생성/수정/삭제합니다(action=list|create|update|delete). task 를 분류하는 프로젝트 태그(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