dpdpdndn 블로그

FE-37-submitted-document-linkage

NEW8 min read

[FE-37] 제출 서류 연결 섹션 · 선택 시트

작업 내용 (설계 의도)

근거: 지원 관리 확장 FE 웹 설계 S-25 제출 서류 연결·컴포넌트 트리·API 연동 > 2단계·Single Writer per File 검증 > 단계 2 wave 2·Testing Plan > 반드시 커버할 실패·엣지 경로(31·32), 지원 관리 확장 TDD 2단계 — 지원 건 ↔ 서류 연결 API 계약.

변경 사항

  • 지원 상세(S-07)에 제출 서류 섹션을 추가하고, 계열 → 버전 2단계 선택 시트를 components/application/에 신설합니다. “어떤 버전으로 지원했는지”를 나중에 확인할 수 있게 하는 것이 이 화면의 유일한 목적입니다.
  • 섹션 항목은 documentType 칩·seriesTitle·versionNumber·originalFileName·submittedAt을 한 줄로 노출하고 [해제] 액션 하나만 둡니다. 섹션 자체는 props만 받고 조회는 상세 페이지가 합니다.
  • 선택 시트는 계열을 먼저 고르고 그 안의 버전을 고르는 2단계입니다. 버전이 전역 목록으로 평평하게 나열되면 같은 파일명의 다른 계열을 구분할 수 없습니다. 시트는 자기 mutation을 소유하는 예외 컴포넌트입니다.
  • 이미 연결된 버전은 숨기지 않고 disabled + “이미 연결됨”으로 표시합니다. 숨기면 사용자가 “왜 v1이 안 보이지”를 겪고, 보여 주면 중복 연결을 사전에 차단하면서 이유까지 전달됩니다.
  • “연결한 버전은 새 버전이 생겨도 바뀌지 않아요” 안내를 시트 하단에 1줄 둡니다. 제출 시점 버전 고정(FR-85)은 계약의 핵심 성질인데 화면에서 보이지 않으면 사용자가 “최신으로 따라가겠지”라고 오해합니다.
  • 제출일은 DateField로 받고 기본값을 오늘로 둡니다. 계약상 submittedAt은 선택 값이므로 미지정도 허용합니다.
  • 사전 차단을 뚫고 서버가 409 DOCUMENT_ALREADY_SUBMITTED를 반환하면 시트를 닫지 않고 인라인 에러(“이미 연결된 버전이에요”)를 띄웁니다 — 사용자가 다른 버전을 바로 고를 수 있어야 합니다. 404 DOCUMENT_VERSION_NOT_FOUND는 토스트 + 계열 목록 무효화입니다(시트 안에서 고칠 수 없는 문제).
  • 해제는 확인 없이 즉시 실행하고 토스트로 알립니다. 연결 해제는 데이터 손실이 아니라 메모 성격의 연결을 끊는 것뿐이고, 다시 연결하는 비용이 낮습니다. 확인 다이얼로그를 붙이면 마찰만 늘어납니다.
  • 빈 상태는 섹션과 시트가 다릅니다 — 섹션 0건은 “연결한 서류가 없어요 / 어떤 버전으로 지원했는지 남겨 두면 나중에 확인할 수 있어요” + [+ 추가]이고, 시트에서 서류가 0건이면 “올린 서류가 없어요” + [서류 올리기]로 업로드 경로를 줍니다.
  • 연결·해제 성공 시 ['applications', applicationId, 'documents']를 무효화합니다. 이 티켓만 ApplicationDetailPage.tsx를 수정하며(단계 2 wave 2 내 유일), DocumentTypeChip은 FE-30(wave 1) 소유분을 import만 하고 수정하지 않습니다.

의존

  • FE-30 — SubmittedDocumentResponse·DocumentSeriesResponse·DocumentSeriesDetailResponse 타입, 제출 서류 queryKey, MSW 목(409 시나리오 포함).
  • FE-30 — DocumentTypeChip 공용 컴포넌트(import 전용, 수정 금지).
  • BE-64 — 지원 건 ↔ 서류 연결 API 구현.

다이어그램

처리 흐름

sequenceDiagram
    participant User as 사용자
    participant Section as SubmittedDocumentSection
    participant Sheet as PickerSheet
    participant Api as POST applications/{id}/documents
    User->>Section: + 추가
    Section->>Sheet: 계열·버전 선택 열기
    User->>Sheet: 계열 선택 후 버전 선택
    User->>Sheet: 연결
    Sheet->>Api: documentVersionId 전송
    Api-->>Sheet: 201 또는 409

컴포넌트 의존

flowchart LR
    Detail[ApplicationDetailPage] --> Section[SubmittedDocumentSection]
    Detail --> ListHook[useSubmittedDocuments]
    Section --> Sheet[SubmittedDocumentPickerSheet]
    Section --> Chip[DocumentTypeChip]
    Sheet --> LinkHook[useLinkSubmittedDocument]
    Section --> UnlinkHook[useUnlinkSubmittedDocument]
    LinkHook --> Api[api/application/submittedDocuments]
    UnlinkHook --> Api
    ListHook --> Api

테스트 케이스

  • 연결된 서류 2건이 있으면 각 항목에 유형 칩·계열 제목·버전 번호·파일명·제출일이 보인다.
  • 시트에서 계열을 고르면 그 계열의 버전 목록이 펼쳐지고, 버전을 고른 뒤 연결을 누르면 documentVersionId가 요청에 실린다.
  • 제출일을 지정하지 않아도 연결이 성공한다(선택 값).
  • 이미 연결된 버전이 시트 목록에서 disabled + “이미 연결됨”으로 보이고 숨겨지지 않는다.
  • 서버가 409 DOCUMENT_ALREADY_SUBMITTED를 반환하면 시트 내 인라인 에러가 보이고 시트가 닫히지 않는다.
  • 서버가 404 DOCUMENT_VERSION_NOT_FOUND를 반환하면 토스트가 뜨고 계열 목록 쿼리가 무효화된다.
  • 시트 하단에 “연결한 버전은 새 버전이 생겨도 바뀌지 않아요” 안내가 보인다.
  • [해제]를 누르면 확인 다이얼로그 없이 즉시 DELETE 요청이 나가고 토스트가 뜬다.
  • 연결·해제 성공 시 ['applications', id, 'documents'] 쿼리가 무효화된다.
  • 연결된 서류가 0건이면 섹션에 “연결한 서류가 없어요” 안내와 [+ 추가]가 보인다.
  • 시트에서 올린 서류가 0건이면 “올린 서류가 없어요” + [서류 올리기]가 보인다.
  • 연결 목록 조회가 실패하면 섹션 내 축소 에러가 보이고 지원 상세의 다른 섹션은 정상 렌더된다.
  • 섹션과 시트가 .dark 클래스 환경에서 렌더되고 하드코딩 색을 0건 사용한다.

그래프 뷰