frontend/apps/as/docs/essential-attachment-file-management/SPEC.md

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

## 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 필수첨부파일 목록 조회 (findPage)
  DISPLAY 필수첨부파일 그리드 (영역 B)

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

  // 영역 A: 등록
  ON [등록] 버튼 CLICK DO
      OPEN 필수첨부파일 등록 다이얼로그 (다이얼로그 C)
      ON [저장] DO
          CONFIRM "등록하시겠습니까?"
          VALIDATE 문서구분, 필수첨부파일명, 필수첨부여부
          CALL 필수첨부파일 등록 (create)
          CALL 필수첨부파일 목록 조회
          CLOSE 다이얼로그
          TOAST "저장되었습니다."
      END ON
      ON [취소] / [닫기] DO
          CLOSE 다이얼로그
      END ON
  END ON

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

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

END
```

---

## 4. 영역 A: 검색 / 액션

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

### 4-1. 검색 필드

| 표시명   | 입력 유형  | 필수 | 기본값 | API 파라미터 매핑 | 비고                           |
| -------- | ---------- | ---- | ------ | ----------------- | ------------------------------ |
| 문서구분 | CodeSelect | N    | 전체   | `docSeComCd?`     | "전체" 선택 시 파라미터 미전송 |

### 4-2. 버튼

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

---

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

필수 첨부파일 마스터를 테이블로 표시한다. 페이지네이션 UI 적용.

### 5-1. 헤더

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

### 5-2. 그리드 컬럼

| 컬럼명             | Field               | 타입   | 비고                                  |
| ------------------ | ------------------- | ------ | ------------------------------------- |
| 필수첨부파일아이디 | `esntlAtchFileId`   | string | 예: `EAF-0001`, 클라이언트 생성/입력  |
| 문서구분           | `docSeComCd`        | string | 코드명 표시 — 공통코드 (TBD 상위코드) |
| 필수첨부파일명     | `esntlAtchFileNm`   | string |                                       |
| 필수첨부여부       | `esntlAtchYn`       | string | `Y`→예, `N`→아니오                    |
| 비고               | `esntlAtchFileRmrk` | string | 없으면 `—` 표시                       |
| 등록일시           | `regDt`             | string | `yyyy-MM-dd HH:mm:ss`                 |
| 수정일시           | `mdfcnDt`           | string | 미수정 시 빈 값 또는 `—`              |
| 관리               | —                   | —      | 행별 **[수정] · [삭제]**              |

- 행 클릭 시 별도 상세 화면 없음. 편집은 **[수정]** 버튼으로 다이얼로그 C를 연다.

### 5-3. 버튼

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

---

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

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

### 6-1. 폼 필드

| 표시명             | 입력 유형  | 필수 | 기본값 | API 파라미터 매핑   | 비고                             |
| ------------------ | ---------- | ---- | ------ | ------------------- | -------------------------------- |
| 필수첨부파일아이디 | (Readonly) | Y    | —      | `esntlAtchFileId`   | 등록 시 미노출                   |
| 문서구분           | CodeSelect | Y    | —      | `docSeComCd`        | 예: 설치인가, 기본계획           |
| 필수첨부파일명     | Text       | Y    | —      | `esntlAtchFileNm`   | placeholder: "예: 사업계획서"    |
| 필수첨부여부       | RadioGroup | Y    | Y      | `esntlAtchYn`       | Y/N, UI 표시: 예/아니오          |
| 비고               | Textarea   | N    | —      | `esntlAtchFileRmrk` | placeholder: "비고를 입력하세요" |

### 6-2. 버튼

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

---

## 7. API/DTO 명세

### 7-1. 공통

| 항목        | 내용                                                  |
| ----------- | ----------------------------------------------------- |
| 서비스      | AS Common Service                                     |
| Base prefix | `/as-service/api/v1/esntl-atch-file`                  |
| 인증        | JWT (`Authorization`), `X-Site-Id` 등                 |
| 페이징      | Spring `Pageable` 사용 (`page`, `size`, `sort`)       |
| 엔티티      | `@/entities/esntl` (`esntl-service.ts`, `queries.ts`) |

### 7-2. 필수첨부파일 API

| 기능      | Method | URL                  | Request DTO                   | Response DTO                        | API (클라이언트 함수명) |
| --------- | ------ | -------------------- | ----------------------------- | ----------------------------------- | ----------------------- |
| 트리 조회 | GET    | `/list/tree`         | Query: `docSeComCd`(필수)     | `EsntlAtchFileMngTreeResponseDto[]` | `findTree`              |
| 목록 조회 | GET    | `/`                  | Query: Search + Pageable      | `PageResponse<EsntlAtchFileMng>`    | `findPage`              |
| 단건 조회 | GET    | `/{esntlAtchFileId}` | Path: `esntlAtchFileId`       | `EsntlAtchFileMng`                  | `findById`              |
| 등록      | POST   | `/`                  | `EsntlAtchFileMngSaveRequest` | `string` (생성된 ID)                | `create`                |
| 수정      | PUT    | `/{esntlAtchFileId}` | `EsntlAtchFileMngSaveRequest` | `string` (수정된 ID)                | `update`                |
| 삭제      | DELETE | `/{esntlAtchFileId}` | Path: `esntlAtchFileId`       | `string` (삭제된 ID)                | `remove`                |

**응답 DTO**

| Field               | 타입    | 설명                             |
| ------------------- | ------- | -------------------------------- |
| `esntlAtchFileId`   | string  | 필수첨부파일아이디               |
| `docSeComCd`        | string  | 문서구분공통코드                 |
| `esntlAtchFileNm`   | string  | 필수첨부파일명                   |
| `esntlAtchYn`       | string  | 필수첨부여부 (Y/N)               |
| `esntlAtchFileRmrk` | string? | 필수첨부파일비고                 |
| `rgtr`              | string? | 등록자 UUID                      |
| `rgtrNm`            | string? | 등록자명                         |
| `mdfr`              | string? | 수정자 UUID                      |
| `regDt`             | string? | 등록일시 (`yyyy-MM-dd HH:mm:ss`) |
| `mdfcnDt`           | string? | 수정일시                         |

**저장 Request**

| Field               | 필수 | 설명               |
| ------------------- | ---- | ------------------ |
| `esntlAtchFileId`   | Y    | 필수첨부파일아이디 |
| `docSeComCd`        | N    | 문서구분           |
| `esntlAtchFileNm`   | N    | 필수첨부파일명     |
| `esntlAtchYn`       | N    | 필수첨부여부       |
| `esntlAtchFileRmrk` | N    | 비고               |

**검색 Query**

| Field             | 필수 | 설명                          |
| ----------------- | ---- | ----------------------------- |
| `docSeComCd`      | N    | 문서구분 (전체 시 미전송)     |
| `esntlAtchFileNm` | N    | 필수첨부파일명 부분/일치 검색 |
| `esntlAtchYn`     | N    | 필수첨부여부 (`Y`/`N`)        |
| `page`            | N    | 페이지 번호 (0-base)          |
| `size`            | N    | 페이지 크기 (기본값: 100)     |
| `sort`            | N    | 정렬 조건 (예: `regDt,desc`)  |

### 7-3. 공통코드

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

---

## 8. UI 구현 가이드

### 8-1. 기술 스택·원칙

- **공통 컴포넌트**: `@common/components` (`Dialog`, `Button`, `Input`, `Select`, `Textarea`, `Label` 등)
- **테이블**: `@tanstack/react-table` + `useDataTable`
- **폼**: `react-hook-form`
- **데이터**: React Query — `@/entities/esntl/api/queries.ts` 훅 사용
- **공통코드**: `@/entities/code` — `CodeSelect`, `findCodeLabel`
- **확인**: `@frontend-opensource/use-react-hooks` — `useConfirm` (등록·삭제 확인)

### 8-2. 모듈·파일 배치

| 구분   | 경로                                                                                                 |
| ------ | ---------------------------------------------------------------------------------------------------- |
| 라우트 | `apps/as/app/(with-base-layout)/esntl-atch-file-mng/page.tsx`                                        |
| 페이지 | `apps/as/src/pages/esntl-atch-file-mng/` (Public API: page만 export)                                 |
| UI     | `.../ui/esntl-atch-file-mng-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/` (`esntl-service.ts`, `queries.ts`, `esntl-interface.ts`)               |
| 문서   | `apps/as/docs/essential-attachment-file-management/SPEC.md`                                          |

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

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