[Feature] 업무함 근로자·Case 마스터–디테일 화면 구현

[hywznn]

배경

현재 /tasks의 WorkListPage는 Task 단위의 탭·필터·평면 목록입니다. 요청된 화면은 근로자 → 우선 Case → 지금 검토할 업무 → 현재 결정을 한 자리에서 확인하는 구조이므로, CSS 조정이 아니라 업무함의 정보 구조를 근로자 중심 마스터–디테일로 재구성해야 합니다.

공통 사이드바·헤더는 기존 AppLayout을 재사용하고 페이지 안에서 다시 만들지 않습니다.

목표 화면

상단

• 제목: 업무함
• 설명: 근로자별 진행 Case와 지금 처리할 업무를 확인하는 화면임을 안내
• 근로자·Case·업무 통합 검색
• 우선순위 정렬

왼쪽: 근로자/대상 목록

• 전체 근로자 수 표시
• 근로자명, 대표 업무, 기한, 상태 뱃지 표시
• 선택 행을 명확히 구분하고 키보드 포커스 제공
• 근로자와 연결되지 않은 업무가 지원될 경우 대상 미지정 업무 그룹 제공
• 선택 상태를 ?workerId= 등 URL에 보존하여 새로고침·뒤로가기 시 유지

오른쪽: 선택 대상 상세

• 근로자명, 국적·비자·근무 정보, 긴급도
• 우선 Case 제목·기한·진행률과 Case 열기
• 검토할 업무 목록과 상황별 CTA(초안 검토, 문서 확인 등)
• 현재 결정 요약, 남은 확인 항목, 근거 보기
• 데이터가 없는 영역은 샘플 문구를 실제 값처럼 표시하지 않고 명확한 안내 상태 제공

현재 코드 분석

• 대상: src/pages/WorkListPage/WorkListPage.tsx
• 현재 상세 이동: /tasks/:caseId → CaseDetailPage
  • 라우트 이름은 caseId지만 실제로는 fetchTaskById()에 Task ID를 전달하고 있어 Case/Task 용어 정리가 필요합니다.
• 재사용 가능:
  • SearchInput, Dropdown, StatusLabel, Button, EmptyState
  • useApiQuery, useDebouncedValue
  • daysUntil, getUrgencyTier
  • WorkerListPage의 2단 workspace / listPanel / detailPanel 패턴
• WorkItemRow는 평면 목록 전용이므로 새 내부 카드에 억지로 맞추지 말고, 반복되는 최소 단위만 별도 컴포넌트로 분리합니다.
• 기존 로딩·빈 데이터·오류·재시도 처리와 실제 Task API 연동([Feature] 업무 목록/상세/생성 실제 API 연동 (Task) #153, PR 업무 목록/상세/생성 실제 Task API 연동 #164)은 유지해야 합니다.

API 계약 확인이 필요한 이유

현재 응답만으로는 시안 전체를 정확히 표현할 수 없습니다.

• TaskSummaryResponse에 근로자명·국적, 담당자/승인자, 체크리스트 진행률, 판단 근거, 추천 CTA가 없음
• worker_id가 필수여서 대상 미지정 업무를 표현할 수 없음
• Case 목록·Case 개수·대표 Case를 제공하는 조회가 없음
• 체크리스트 진행률은 Task 상세에만 있어 목록 전체를 상세 조회하면 N+1 요청 위험이 있음
• 업무와 문서의 연결 ID가 없어 문서 확인의 목적지를 결정할 수 없음
• WorkerResponse에 비자 유형·근무 라인/부서가 없음
• 근로자 검색은 서버 검색이 없어 현재 최대 100건 안에서만 동작함

구현 전에 다음 중 한 방향을 확정합니다.

1. 업무함 전용 projection API/ViewModel을 백엔드와 정의한다.
2. MVP에서는 workers + tasks를 worker_id로 결합하고 선택된 대표 Task만 상세 조회하되, 100건 제한·누락 필드를 UI에 명시한다.

어느 방향이든 화면 샘플 데이터(예: 12명, 특정 근로자, 진행률)를 하드코딩해 실제 데이터처럼 표시하지 않으며, 목록 항목마다 상세 API를 호출하지 않습니다.

구현 범위

• WorkListPage를 근로자 중심 마스터–디테일 구조로 재구성
• 검색·우선순위 정렬·선택 상태와 데이터 결합 로직을 렌더링 코드에서 분리
• Case/Task 식별자와 상세 라우팅 명칭 정리
• 좌·우 패널별 loading / empty / error / partial-success 상태 제공
• 근로자 선택, Case 열기, 검토 CTA, 근거 보기의 실제 이동 경로 연결
• 상태·기한·진행률의 의미를 텍스트와 함께 제공
• 단위/통합 테스트 추가

완료 조건

• /tasks에 요청 화면과 같은 근로자 목록 + 선택 상세 2단 구조가 표시된다.
• 근로자를 선택하면 오른쪽 내용과 URL 선택 상태가 함께 변경된다.
• 검색이 근로자명·Case명·업무명 기준으로 실제 결과를 좁히며 디바운스된다.
• 우선순위 정렬이 상태·기한 기준의 문서화된 규칙으로 결정적으로 동작한다.
• Case 열기가 올바른 Task/Case 상세로 이동한다.
• 검토·문서·근거 CTA가 식별자가 있을 때만 올바른 목적지로 이동한다.
• Worker 또는 Task API 일부만 실패해도 복구 가능한 상태와 다시 시도를 제공한다.
• 데이터가 없거나 필드가 누락된 경우 허위 샘플 대신 안내 상태를 표시한다.
• 목록 행과 CTA를 키보드로 조작할 수 있고 포커스가 보인다.
• 데이터 결합, 정렬, 검색, 선택, 이동, loading/empty/error 테스트를 추가한다.
• npm run lint, npm test -- --run, npm run build가 통과한다.

범위 제외

• 공통 사이드바 메뉴 구조 변경 및 Agent/티켓 처리 방향([Chore] Agent 패널·티켓 화면이 Figma PWF v3 사이드바에 없음 — 처리 방향 결정 필요 #206)
• 공통 헤더 전역 개편
• 백엔드 엔드포인트 자체 구현
• 모바일 전용 디자인 및 애니메이션
  • 기존 좁은 화면에서 콘텐츠가 겹치거나 잘리는 회귀는 만들지 않습니다.

선행/연관

• [Feature] 업무 목록/상세/생성 실제 API 연동 (Task) #153 — 실제 Task API 연동 이력
• PR 업무 목록/상세/생성 실제 Task API 연동 #164 — 현재 WorkListPage/CaseDetailPage API 구현
• [Chore] Agent 패널·티켓 화면이 Figma PWF v3 사이드바에 없음 — 처리 방향 결정 필요 #206 — PWF v3 사이드바 정보 구조 결정
• docs/SCREEN_CATALOG.md의 6a 업무 카드 보드

[hywznn]

확정된 최소 변경 방향

Workflow 설계서와 현재 Server 계약을 기준으로 다음처럼 구현합니다.

• 기존 GET /api/v1/workers, GET /api/v1/tasks, GET /api/v1/workflow-catalogs를 조합합니다.
• worker_id로 근로자별 업무를, case_id로 Case를 묶습니다.
• 진행률은 Case 안의 COMPLETED / 전체 Task로 계산합니다.
• 긴급도와 우선순위는 우선 status + due_date로 결정하며 샘플 값을 하드코딩하지 않습니다.
• Case 열기는 fowoco/server#71의 선택형 caseId 필터와 연결합니다.
• 대상 미지정 업무는 Task의 worker_id를 nullable로 바꾸지 않고, AiRun Candidate 계약 전까지 숨기거나 명확한 준비 상태로 표시합니다.

새 업무함 전용 API·Case 테이블·priority 컬럼은 이번 범위에서 추가하지 않습니다.