diff --git a/apps/as/docs/attachment-management/SPEC.md b/apps/as/docs/attachment-management/SPEC.md new file mode 100644 index 000000000..abc6416f4 --- /dev/null +++ b/apps/as/docs/attachment-management/SPEC.md @@ -0,0 +1,311 @@ +# 화면설계서: 필수첨부파일관리 + +## 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)