dpdpdndn 블로그

BE-64-submitted-document-api

NEW3 min read

[BE-64] 지원 건 서류 연결 API (FR-85)

작업 내용 (설계 의도)

근거 TDD: 20260808-지원관리-확장-tdd.md — “API 계약 2단계 지원 건 ↔ 서류 연결”

변경 사항

  1. POST /api/applications/{applicationId}/documents, GET, DELETE {submittedDocumentId}를 신설합니다.
  2. 크로스 컨텍스트 조합은 application 레이어입니다 — UseCase가 ApplicationQueryDomainService(지원 존재 404)와 DocumentDomainService(버전 존재 404)를 각각 호출한 뒤 SubmittedDocumentDomainService에 넘깁니다. DomainService끼리 직접 부르지 않습니다.
  3. 응답 조립에 계열 제목·문서 유형·버전 번호·원본 파일명이 필요하므로 documentVersionId 집합으로 document 배치 조회 1회를 수행합니다(N+1 금지).
  4. 신규 컨트롤러 파일(SubmittedDocumentApiController.kt)로 만들어 기존 ApplicationApiController.kt·BE-49의 ApplicationContactApiController.kt와 충돌하지 않습니다.

의존

  • BE-60 (연결 도메인)
  • BE-57 (문서 버전 조회)

다이어그램

처리 흐름

sequenceDiagram
    participant FE as web(SPA)
    participant C as SubmittedDocumentApiController
    participant U as LinkSubmittedDocumentUseCase
    participant AQ as ApplicationQueryDomainService
    participant DD as DocumentDomainService
    participant SD as SubmittedDocumentDomainService
    FE->>C: POST /api/applications/{id}/documents
    C->>U: execute(command)
    U->>AQ: getBy(applicationId)
    U->>DD: getVersionBy(documentVersionId)
    U->>SD: link(applicationId, versionId, submittedAt)
    SD-->>U: SubmittedDocument
    U->>DD: findAllVersionsBy(ids) 배치 1회 (응답 조립)
    U-->>C: SubmittedDocumentResponse
    C-->>FE: 201

클래스 의존

flowchart LR
    subgraph Presentation["presentation/application"]
        Api[SubmittedDocumentApiController]
    end
    subgraph Application["application/application"]
        Link[LinkSubmittedDocumentUseCase]
        List[ListSubmittedDocumentsUseCase]
        Unlink[UnlinkSubmittedDocumentUseCase]
    end
    subgraph Domain["domain"]
        AQ[ApplicationQueryDomainService]
        DD[DocumentDomainService]
        SD[SubmittedDocumentDomainService]
    end
    Api --> Link
    Api --> List
    Api --> Unlink
    Link --> AQ
    Link --> DD
    Link --> SD
    List --> SD
    List --> DD

테스트 케이스

  • 지원 건에 서류 버전을 연결하면 201과 계열 제목·유형·버전 번호가 함께 반환된다
  • 존재하지 않는 지원 건이면 404 APPLICATION_NOT_FOUND다
  • 존재하지 않는 문서 버전이면 404 DOCUMENT_VERSION_NOT_FOUND다
  • 같은 버전을 두 번 연결하면 409 DOCUMENT_ALREADY_SUBMITTED다
  • 같은 버전을 다른 지원 건에 연결하면 성공한다 (재사용)
  • 목록 조회 시 서류 3건에 대해 document 조회가 1회만 발생한다 (N+1 방지)
  • 연결을 삭제하면 204이고 문서 버전 자체는 남는다
  • 다른 지원 건의 연결 id로 삭제를 시도하면 404다 (소유 검증)
  • 연결이 없으면 빈 배열을 반환한다 (0건 경계)
  • 계열에 새 버전이 생겨도 기존 연결 응답의 버전 번호가 변하지 않는다

그래프 뷰