Files
frontend/apps/as/docs/attachment-management/SPEC.md
T

18 KiB

화면설계서: 필수첨부파일관리

1. 기본 정보

항목 내용
버전 0.1
프로세스명 UI설계
화면명 필수첨부파일관리
화면 유형 [v] 조회 [v] 입력 [v] 수정 [v] 삭제 [ ] 출력
메뉴 경로 디지털행정지원 > 사이트관리 > 필수첨부파일관리

2. 화면 목적

문서(업무) 구분별로 필수 첨부파일 항목을 등록·조회·수정·삭제한다. 상단 검색 영역에서 문서구분으로 목록을 필터링하고, 등록 또는 행별 수정·삭제로 마스터 데이터를 유지한다. 등록·수정 시 필수첨부파일아이디는 서버에서 자동 발급된다.


3. 화면 구성

3-1. 전체 레이아웃

┌───────────────────────────────────────────────────────────────────────────────────────────────┐
│  페이지 타이틀: 필수첨부파일관리                            브레드크럼: 디지털행정지원 > … >    │
├───────────────────────────────────────────────────────────────────────────────────────────────┤
│  [영역 A] 검색 / 액션                                                                         │
│  ┌─────────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ 문서구분 [전체 ▼]  [조회]                                              [등록]           │  │
│  └─────────────────────────────────────────────────────────────────────────────────────────┘  │
├───────────────────────────────────────────────────────────────────────────────────────────────┤
│  [영역 B] 필수첨부파일 목록                                                                   │
│  ┌─────────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ 필수첨부파일아이디 | 문서구분 | 필수첨부파일명 | 필수첨부여부 | 비고 | 등록일시 | 수정일시 | 관리 │
│  ├─────────────────────────────────────────────────────────────────────────────────────────┤  │
│  │ EAF-0001 | 설치인가 | 사업계획서 | 예 | 서명본 첨부 | 2026-04-22 10:10:00 | — | [수정][삭제] │
│  │ EAF-0002 | 기본계획 | 변경사유서 | 예 | — | 2026-04-22 11:00:00 | — | [수정][삭제]         │
│  └─────────────────────────────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────────────────────────────────┘

  (모달) [다이얼로그 C] 필수첨부파일 등록 / 수정
  ┌──────────────────────────────────────────────────────────────┐
  │ 필수첨부파일 등록                                    [닫기]  │
  ├──────────────────────────────────────────────────────────────┤
  │ 필수첨부파일아이디(자동발급)  [EAF-0004] (읽기 전용)         │
  │ 문서구분                      [설치인가 ▼]                   │
  │ 필수첨부파일명                [예: 사업계획서]               │
  │ 필수첨부여부                  [예 ▼]                         │
  │ 비고                          [비고를 입력하세요]            │
  ├──────────────────────────────────────────────────────────────┤
  │                                    [취소]  [저장]            │
  └──────────────────────────────────────────────────────────────┘

3-2. 화면 데이터 흐름

BEGIN

  // 최초 진입
  CALL 필수첨부파일 목록 조회 (TBD)
  DISPLAY 필수첨부파일 그리드 (영역 B)

  // 영역 A: 검색
  ON [조회] 버튼 CLICK DO
      CALL 필수첨부파일 목록 조회 (문서구분 = 선택값, TBD)
      DISPLAY 필수첨부파일 그리드 (영역 B)
  END ON

  // 영역 A: 등록
  ON [등록] 버튼 CLICK DO
      OPEN 필수첨부파일 등록 다이얼로그 (다이얼로그 C)
      DISPLAY 필수첨부파일아이디 = 자동발급 미리보기 또는 "저장 시 발급" (TBD)
      ON [저장] DO
          VALIDATE 문서구분, 필수첨부파일명, 필수첨부여부
          CALL 필수첨부파일 등록 (TBD)
          CALL 필수첨부파일 목록 조회
          CLOSE 다이얼로그
          TOAST "저장되었습니다."
      END ON
      ON [취소] / [닫기] DO
          CLOSE 다이얼로그
      END ON
  END ON

  // 영역 B: 수정
  ON 행 [수정] CLICK DO
      OPEN 필수첨부파일 수정 다이얼로그 (기존 값 초기화)
      ON [저장] DO
          VALIDATE 문서구분, 필수첨부파일명, 필수첨부여부
          CALL 필수첨부파일 수정 (TBD)
          CALL 필수첨부파일 목록 조회
          CLOSE 다이얼로그
      END ON
  END ON

  // 영역 B: 삭제
  ON 행 [삭제] CLICK DO
      CONFIRM "선택한 필수첨부파일을 삭제하시겠습니까?"
      CALL 필수첨부파일 삭제 (TBD)
      CALL 필수첨부파일 목록 조회
  END ON

END

4. 영역 A: 검색 / 액션

문서구분 조건으로 목록을 조회하고, 신규 등록 다이얼로그를 연다.

4-1. 검색 필드

표시명 입력 유형 필수 기본값 API 파라미터 매핑 비고
문서구분 Select(공통코드) N 전체 docSeComCd? "전체" 선택 시 파라미터 미전송 (TBD)

4-2. 버튼

버튼명 위치 동작
조회 검색 필드 우측 현재 검색 조건으로 영역 B 목록 갱신
등록 영역 우측 끝 필수첨부파일 등록 다이얼로그(다이얼로그 C) 오픈

5. 영역 B: 필수첨부파일 목록

필수 첨부파일 마스터를 테이블로 표시한다. 페이지네이션 UI는 스크린샷에 없음 — TBD(백엔드 Pageable 정책 확인).

5-1. 헤더

항목 내용
섹션 타이틀 필수첨부파일 목록

5-2. 그리드 컬럼

컬럼명 Field (제안) 타입 비고
필수첨부파일아이디 esntlAtchFileId string 예: EAF-0001, 서버 자동 발급
문서구분 docSeComCd string 코드명 표시 — 공통코드 (TBD 상위코드)
필수첨부파일명 esntlAtchFileNm string
필수첨부여부 esntlAtchYn string Y→예, N→아니오
비고 rmk string 없으면 — 표시
등록일시 regDt string yyyy-MM-dd HH:mm:ss
수정일시 mdfcnDt string 미수정 시 빈 값 또는 —
관리 — — 행별 [수정] · [삭제]
  • 행 클릭 시 별도 상세 화면 없음. 편집은 [수정] 버튼으로 다이얼로그 C를 연다.

5-3. 버튼

버튼명 위치 동작
수정 행별 필수첨부파일 수정 다이얼로그 (기존 값)
삭제 행별 확인 후 삭제 API 호출 → 목록 갱신

6. 다이얼로그 C: 필수첨부파일 등록 / 수정

등록·수정 공용 폼 다이얼로그. 등록 시 제목 「필수첨부파일 등록」, 수정 시 「필수첨부파일 수정」.

6-1. 폼 필드

표시명 입력 유형 필수 기본값 API 파라미터 매핑 비고
필수첨부파일아이디(자동발급) Text (읽기 전용) — — — 등록: 저장 전 미리보기 또는 placeholder (TBD)
문서구분 Select(공통코드) Y — docSeComCd 예: 설치인가, 기본계획
필수첨부파일명 Text Y — esntlAtchFileNm placeholder: "예: 사업계획서"
필수첨부여부 Select Y Y esntlAtchYn Y/N, UI 표시: 예/아니오
비고 Textarea N — rmk placeholder: "비고를 입력하세요"

TBD: 등록 다이얼로그의 EAF-0004 표시가 저장 전 ID 미리보기인지, mock 데이터인지 백엔드 정책 확인.

6-2. 버튼

버튼명 동작
저장 POST(등록) 또는 PUT(수정) 후 목록 갱신
취소 다이얼로그 닫기, 입력값 폐기
닫기 다이얼로그 닫기 (헤더 우측)

7. API/DTO 명세

API 미확정. 백엔드 명세 확정 전까지 아래는 TBD placeholder이다.

7-1. 공통

항목 내용
서비스 TBD
Base prefix TBD
인증 JWT (Authorization), X-Site-Id 등
페이징 TBD — Spring Pageable 여부 확인
엔티티 TBD — @/entities/esntl-atch-file 등

7-2. 필수첨부파일 — TBD

기능 Method URL Request DTO Response DTO API (클라이언트 함수명)
목록 조회 GET TBD TBD TBD TBD
단건 조회 GET TBD TBD TBD TBD
등록 POST TBD TBD TBD TBD
수정 PUT TBD TBD TBD TBD
삭제 DELETE TBD TBD TBD TBD

응답 DTO (제안 필드)

Field 타입 설명
esntlAtchFileId string 필수첨부파일아이디
docSeComCd string 문서구분공통코드
esntlAtchFileNm string 필수첨부파일명
esntlAtchYn string? 필수첨부여부 (Y/N)
rmk string? 비고
regDt string? 등록일시
mdfcnDt string? 수정일시

저장 Request (제안)

Field 필수 설명
docSeComCd Y 문서구분
esntlAtchFileNm Y 필수첨부파일명
esntlAtchYn Y 필수첨부여부
rmk N 비고

검색 Query (제안)

Field 필수 설명
docSeComCd N 문서구분 (전체 시 미전송)
page N TBD
size N TBD
sort N TBD — 예: regDt,desc

7-3. 공통코드 (보조)

UI 필드 코드 그룹 (TBD) 예시 값 (스크린샷)
문서구분 TBD 설치인가, 기본계획
필수첨부여부 고정 Y(예), N(아니오)

공통코드 조회: @/entities/code — codeService, CodeSelect


8. UI 구현 가이드

8-1. 기술 스택·원칙

  • 공통 컴포넌트: @common/components (Dialog, Button, Input, Select, Textarea, Label 등)
  • 테이블: @tanstack/react-table + useDataTable
  • 폼: react-hook-form
  • 데이터: React Query — TBD 엔티티 hooks
  • 공통코드: @/entities/code — CodeSelect, findCodeLabel
  • 확인: @frontend-opensource/use-react-hooks — useConfirm (삭제 확인)
  • 모의 데이터: API 연동 전 @faker-js/faker (ID 형식 EAF-####)

8-2. 모듈·파일 배치(제안)

구분 경로
라우트 apps/as/app/(with-base-layout)/attachment-management/page.tsx
페이지 apps/as/src/pages/attachment-management/ (Public API: page만 export)
UI .../ui/attachment-management-page.tsx, esntl-atch-file-list.tsx, esntl-atch-file-form-dialog.tsx
model .../model/esntl-atch-file-columns.tsx, esntl-atch-file-search-params.ts
엔티티 apps/as/src/entities/esntl-atch-file/ (TBD — service·hooks)
문서 apps/as/docs/attachment-management/SPEC.md

8-3. 영역별 UI 매핑

영역 주요 UI
A CodeSelect(문서구분) + [조회] + [등록]
B DataTable + 행별 [수정][삭제]
C Dialog + react-hook-form (등록/수정 공용)

8-4. 다이얼로그·라우팅

다이얼로그명 트리거 API 연동 (TBD)
필수첨부파일 등록 [등록] create mutation
필수첨부파일 수정 행 [수정] update mutation
삭제 확인 행 [삭제] delete mutation

라우트: /attachment-management (메뉴 URL은 CMS 등록값과 일치시킴)

8-5. 데이터 흐름(요약)

  • 진입: 검색 params 기본값(docSeComCd = 전체) → 목록 query → 영역 B DataTable.
  • 조회: [조회] 클릭 시 search state 반영 → 목록 query refetch.
  • 등록: [등록] → Dialog mode=create → [저장] → POST → 목록 invalidate.
  • 수정: [수정] → Dialog mode=edit + row 초기값 → [저장] → PUT → 목록 invalidate.
  • 삭제: confirm → DELETE → 목록 invalidate.

8-6. 미확정 / 검증 필요

  • 백엔드 서비스명·Base URL·리소스 path
  • esntlAtchFileId 자동발급 시점 (등록 API 응답 vs 저장 전 미리보기 API)
  • 문서구분 공통코드 상위코드 ID
  • 목록 페이지네이션·정렬 UI 노출 여부
  • 동일 문서구분 내 필수첨부파일명 중복 허용 여부
  • 권한(역할별 CRUD)