ONAANDALL/frontend
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[st] docs: 필수첨부파일관리 페이지 스펙 문서 초안 작성

Browse Source
This commit is contained in:
chanii8
2026-05-26 17:22:08 +09:00
parent aa213ceead
commit 215d742270
1 changed files with 311 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/as/docs/attachment-management/SPEC.md
+311
View File
@@ -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)