# 화면설계서: 알림톡템플릿관리

## 1. 기본 정보

| 항목       | 내용                                         |
| ---------- | -------------------------------------------- |
| 버전       | 1.0                                          |
| 프로세스명 | UI설계                                       |
| 화면명     | 알림톡템플릿관리                             |
| 화면 유형  | [x] 조회 [x] 입력 [x] 삭제 [ ] 수정 [ ] 출력 |
| 메뉴 경로  | home > 시스템관리 > 알림톡템플릿관리         |

---

## 2. 화면 목적

카카오 알림톡(또는 동일 채널) **템플릿 목록을 조회·관리**하고, 선택한 템플릿에 연결된 **치환 변수 목록**을 확인·관리한다.

---

## 3. 화면 구성

### 3-1. 전체 레이아웃

```
┌──────────────────────────────────────────────────────────────────────────────┐
│  페이지 제목: 알림톡템플릿관리                       브레드크럼 (우측 상단)  │
├──────────────────────────────────────────────────────────────────────────────┤
│  [영역 A] 검색 필터                                                          │
│   · 1행: 템플릿코드, 템플릿명, 템플릿내용 (텍스트)                           │
│   · 2행: 채널, 검수상태, 메시지유형 (드롭다운, 기본값: 전체) | 조회, 초기화  │
├──────────────────────────────────────────────────────────────────────────────┤
│  [영역 B] 알림톡 템플릿 관리                                                 │
│   · 섹션 제목 + 툴바(템플릿갱신, 템플릿등록, 선택 검수요청, 선택삭제, 저장)  │
│   · 템플릿 그리드 (체크박스 다중 선택)                                       │
├──────────────────────────────────────────────────────────────────────────────┤
│  [영역 C] 변수관리                                                           │
│   · 섹션 제목 + 툴바(변수추가, 선택삭제, 저장)                               │
│   · 변수 그리드                                                              │
└──────────────────────────────────────────────────────────────────────────────┘
```

---

## 4. 영역 A: 검색 필터

### 4-1. 필드 정의

| 표시명     | 입력 유형 | 필수 | 기본값 | API 파라미터 매핑  | 비고                                    |
| ---------- | --------- | ---- | ------ | ------------------ | --------------------------------------- |
| 템플릿코드 | 텍스트    | N    | 공백   | `templateCode`     |                                         |
| 템플릿명   | 텍스트    | N    | 공백   | `templateName`     |                                         |
| 템플릿내용 | 텍스트    | N    | 공백   | -                  | 현재 `NtftalkTempSearchParams`에 미정의 |
| 채널       | 드롭다운  | N    | 전체   | `senderKey`        |                                         |
| 검수상태   | 드롭다운  | N    | 전체   | `inspectionStatus` |                                         |
| 메시지유형 | 드롭다운  | N    | 전체   | -                  | 현재 `NtftalkTempSearchParams`에 미정의 |

### 4-2. 버튼

| 버튼명 | 동작                                                                    |
| ------ | ----------------------------------------------------------------------- |
| 조회   | 현재 필터 조건으로 영역 B 목록을 재조회한다. 페이지는 1페이지로 초기화. |
| 초기화 | 검색 필드를 기본값(공백·전체)으로 되돌린다.                             |

---

## 5. 영역 B: 알림톡 템플릿 관리

### 5-1. 툴바 버튼

| 버튼명        | 동작(요구사항)                                          |
| ------------- | ------------------------------------------------------- |
| 템플릿갱신    | API를 재조회하여 템플릿 목록을 갱신한다.                |
| 템플릿등록    | 신규 템플릿 등록 다이얼로그를 오픈한다.                 |
| 선택 검수요청 | 체크된 행에 대해 검수 요청 API를 호출한다.              |
| 선택삭제      | 체크된 행을 삭제한다. 데이터베이스에는 삭제되지 않는다. |
| 저장          | 그리드에서 변경된 내용을 일괄 저장한다.                 |

※ 실제 API·권한은 백엔드 정책에 따른다.

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

| 표시명     | Field                   | 비고                                      |
| ---------- | ----------------------- | ----------------------------------------- |
| (선택)     | —                       | 체크박스, 다중 선택                       |
| @채널      | `senderKey`             |                                           |
| 템플릿코드 | `templateCode`          |                                           |
| 템플릿명   | `templateName`          |                                           |
| 메시지유형 | `templateMessageType`   |                                           |
| 템플릿내용 | `templateContent`       | 긴 텍스트, 말줄임 처리                    |
| 강조유형   | `templateEmphasizeType` |                                           |
| 버튼정보   | `buttons`               |                                           |
| 검수상태   | `inspectionStatus`      |                                           |
| 상태       | `status`                |                                           |
| 등록일자   | `createdAt`             | ISO datetime 문자열 (YYYY-MM-DD HH:mm:ss) |

### 5-3. 행 상호작용

- 행 **클릭** 시: 해당 템플릿의 상세 다이얼로그를 오픈한다.
- 다중 체크는 **삭제·검수요청** 등 일괄 작업용으로 사용한다.

---

## 6. 영역 C: 변수관리

알림톡 템플릿에 사용되는 공통 변수 목록을 관리한다.

### 6-1. 툴바 버튼

| 버튼명   | 동작                          |
| -------- | ----------------------------- |
| 변수추가 | 변수 행 추가(인라인).         |
| 선택삭제 | 선택된 변수 행 삭제.          |
| 저장     | 추가·수정·삭제 반영 API 호출. |

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

| 표시명   | Field     | 비고                                      |
| -------- | --------- | ----------------------------------------- |
| 순번     | —         | 화면 표시용 row index(서버 필드 없음)     |
| 변수코드 | `varCd`   |                                           |
| 변수명   | `varNm`   |                                           |
| 설명     | `varDesc` |                                           |
| 등록일자 | `regDt`   | ISO datetime 문자열 (YYYY-MM-DD HH:mm:ss) |
| 등록자   | `regr`    |                                           |

---

## 7. API/DTO 명세

### 7-1. 공통

- Base Endpoint Prefix: `/ntftalk-service/api/v1`

### 7-2. 템플릿 API

Base: `ENDPOINT.NTFTALK_SERVICE.NTFTALK_TEMP`(`/ntftalk-service/api/v1/ntftalk-temp`)

| 기능             | Method | URL                            | Request DTO                                            | Response DTO          | API                  |
| ---------------- | ------ | ------------------------------ | ------------------------------------------------------ | --------------------- | -------------------- |
| 템플릿 목록 조회 | GET    | `/ntftalk-temp`                | `NtftalkTempSearchParams`                              | `NtftalkTempPageList` | `getNtftalkTempPage` |
| 템플릿 상세 조회 | GET    | `/ntftalk-temp/{templateCode}` | Path: `templateCode`                                   | `NtftalkTemp`         | `getNtftalkTemp`     |
| 템플릿 등록      | POST   | `/ntftalk-temp`                | `NtftalkTempSavePayload`                               | `NtftalkTemp`         | `saveNtftalkTemp`    |
| 템플릿 수정      | PUT    | `/ntftalk-temp/{templateCode}` | Path: `templateCode`, Body: `NtftalkTempUpdatePayload` | `NtftalkTemp`         | `updateNtftalkTemp`  |
| 템플릿 삭제      | DELETE | `/ntftalk-temp/{templateCode}` | Path: `templateCode`                                   | 없음                  | `deleteNtftalkTemp`  |

### 7-3. 변수 API

Base: `ENDPOINT.NTFTALK_SERVICE.NTFTALK_VAR`(`/ntftalk-service/api/v1/ntftalk-var`)

| 기능           | Method | URL                    | Request DTO                                    | Response DTO         | API                 |
| -------------- | ------ | ---------------------- | ---------------------------------------------- | -------------------- | ------------------- |
| 변수 목록 조회 | GET    | `/ntftalk-var`         | `NtftalkVarSearchParams`                       | `NtftalkVarPageList` | `getNtftalkVarPage` |
| 변수 상세 조회 | GET    | `/ntftalk-var/{varCd}` | Path: `varCd`                                  | `NtftalkVar`         | `getNtftalkVar`     |
| 변수 등록      | POST   | `/ntftalk-var`         | `NtftalkVarSavePayload`                        | `NtftalkVar`         | `saveNtftalkVar`    |
| 변수 수정      | PUT    | `/ntftalk-var/{varCd}` | Path: `varCd`, Body: `NtftalkVarUpdatePayload` | `NtftalkVar`         | `updateNtftalkVar`  |
| 변수 삭제      | DELETE | `/ntftalk-var/{varCd}` | Path: `varCd`                                  | 없음                 | `deleteNtftalkVar`  |

---

## 8. UI 구현 가이드

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

- **UI**: `@common/components` 공통 컴포넌트 사용
- **테이블**: `@tanstack/react-table` + `useDataTable`(`src/shared/lib/use-data-table.tsx`)
- **데이터**: `@tanstack/react-query`(등록/수정 폼에 검증이 필요하면 `react-hook-form` + `zod` 사용)
- **레이아웃**: App Router `app/(with-base-layout)/.../page.tsx`에서 페이지 UI 컴포넌트만 마운트

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

| 구분          | 경로                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| 라우트 엔트리 | `apps/cs/app/(with-base-layout)/ntftalk-temp/page.tsx`                  |
| 페이지 셸     | `apps/cs/src/pages/ntftalk-temp/ui/ntftalk-temp-page.tsx`               |
| 컬럼 정의     | `apps/cs/src/pages/ntftalk-temp/model/*-table-columns.tsx`              |
| API·타입      | `apps/cs/src/entities/ntftalk/model/*-interface.ts`, `api/*-service.ts` |
| 다이얼로그    | `apps/cs/src/pages/ntftalk-temp/ui/*-dialog.tsx`                        |

### 8-3. 영역별 UI 매핑

| 영역 | 화면 요소     | 권장 컴포넌트·훅                                             | 구현 비고                                                                                     |
| ---- | ------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| A    | 검색 폼       | `Input`, `Label`, `Select`, `Button`                         |                                                                                               |
| B    | 템플릿 그리드 | `useDataTable` + `ColumnDef`, `RowSelectionState`(컬럼 선택) | `manualPagination`, `onRowClick` → **8-4** 상세 다이얼로그                                    |
| B    | 툴바          | `Button` 그룹                                                | 검수요청·삭제 등 확인은 `useConfirm` + `src/shared/ui/confirm-dialog.tsx` 등 기존 패턴 재사용 |
| C    | 변수 그리드   | `useDataTable` + `ColumnDef`, `Input` + `zod`                | **변수추가는 인라인**(6-1절). 선택 행 삭제·저장은 변수 API(7-3절)와 매핑. 검증은 `zod` 사용   |
| 공통 | 로딩·빈 목록  | `LoadingWithAnimation`, 빈 데이터 안내 문구                  | 기타 목록 페이지와 동일 수준 처리                                                             |

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

| UX                                | 구현 단위                 | 컨테이너·비고                                                                |
| --------------------------------- | ------------------------- | ---------------------------------------------------------------------------- |
| 템플릿등록 (5-1)                  | `NtftalkTempRegistDialog` | `Dialog` + 폼. `saveNtftalkTemp`(7-2)                                        |
| 행 클릭 상세 (5-3)                | `NtftalkTempDetailDialog` | **별도 라우트가 아닌 다이얼로그**로 구현. `getNtftalkTemp`(7-2)로 상세 로드  |
| 선택 검수요청·선택삭제·저장 (5-1) | mutation + confirm        | 각각 대응 API(7-2) 및 백엔드 정책에 따름. 미확정 엔드포인트는 **TBD**로 표기 |

### 8-5. 데이터 흐름

```
BEGIN

  // 최초 진입
  CALL 템플릿목록조회(기본 검색 조건)
  DISPLAY 알림톡템플릿그리드 (영역 B)

  CALL 변수목록조회(검색 조건)
  DISPLAY 변수그리드 (영역 C)

  // 영역 A: 조회·초기화
  ON [조회] 버튼 CLICK DO
      CALL 템플릿목록조회(템플릿코드, 템플릿명, 템플릿내용, 채널, 검수상태, 메시지유형)  // → 영역 B 갱신, 페이지 1로 초기화
  END ON

  ON [초기화] 버튼 CLICK DO
      RESET 검색 조건 → 기본값(공백·전체)
  END ON

  // 영역 B: 알림톡 템플릿 (7-2절 참고)
  ON [템플릿갱신] CLICK DO
      CALL 템플릿목록조회(현재 검색 조건)  // → 영역 B 갱신
  END ON

  ON [템플릿등록] CLICK DO
      OPEN 템플릿등록 다이얼로그
  END ON

  ON 영역 B 행 CLICK DO
      CALL 템플릿상세조회(선택된 templateCode)
      DISPLAY 템플릿상세 다이얼로그
  END ON

  ON [선택 검수요청] CLICK DO
      CONFIRM 사용자
      CALL 검수요청 API(체크된 행)
  END ON

  ON [선택삭제] CLICK DO
      CONFIRM 사용자
      CALL 템플릿삭제 API(체크된 행)
  END ON

  ON [저장] CLICK DO
      CALL 템플릿 일괄저장 API(그리드 변경분)
  END ON

  // 영역 C: 변수 (7-3절 참고)
  ON [변수추가] CLICK DO
      ADD 변수 행 (인라인 편집)
  END ON

  ON [선택삭제] CLICK DO (영역 C)
      CONFIRM 사용자
      CALL 변수삭제 API(선택 행)
  END ON

  ON [저장] CLICK DO (영역 C)
      CALL 변수 등록·수정 API(변경분)
  END ON

END
```

---

## 9. 템플릿 등록 다이얼로그

대상 UI: `NtftalkTempRegistDialog` (`apps/cs/src/pages/ntftalk-temp/ui/ntftalk-temp-regist-dialog.tsx`)

### 9-1. 목적/오픈 조건

- 목적: 신규 알림톡 템플릿 1건을 등록한다.
- 오픈 조건: 영역 B 툴바의 `템플릿등록` 클릭 시 모달 오픈.
- 저장 성공 시: 목록 캐시 무효화 후 영역 B 재조회 상태로 복귀(모달 닫힘).

### 9-2. 다이얼로그 레이아웃

```
┌──────────────────────────────────────────────────────────────────────┐
│ 알림 템플릿 등록                                                     │
├──────────────────────────────────────────────────────────────────────┤
│ 메시지 유형       [기본형(고정)]                                     │
│ 채널              [Select(senderKey)]                                │
│ 템플릿코드        [Input]                                            │
│ 템플릿명          [Input]                                            │
│ 보안템플릿여부    ( )설정  ( )미설정                                 │
│ 템플릿내용        [+ 변수추가]                                       │
│                   [Textarea]                                         │
│ 버튼              Table(버튼타입|버튼명|버튼링크)                    │
│                   [CodeSelect(upCd: NTFBUTTONTYPE) | Input | Input]  │
│ 바로연결          Table(바로연결타입|바로연결명|바로연결링크)        │
│                   [CodeSelect(upCd: NTFQRTYPE) | Input | Input]      │
├──────────────────────────────────────────────────────────────────────┤
│                                                       [저장] [취소]  │
└──────────────────────────────────────────────────────────────────────┘
```

### 9-3. 필드 상세

| 표시명         | Form Key                | 입력 유형   | 필수 | 기본값                                | 검증/제약            | 저장 Payload 매핑     |
| -------------- | ----------------------- | ----------- | ---- | ------------------------------------- | -------------------- | --------------------- |
| 메시지 유형    | `templateMessageType`   | 고정 텍스트 | Y    | `BA`                                  | UI에서 `기본형` 고정 | `templateMessageType` |
| 채널           | `senderKey`             | Select      | Y    | `senderQuery.data.senderKey` 자동세팅 | 미선택 불가          | `senderKey`           |
| 발신키 유형    | `senderKeyType`         | hidden 상수 | Y    | `S`                                   | submit 시 강제 `S`   | `senderKeyType`       |
| 템플릿코드     | `templateCode`          | Input       | Y    | `""`                                  | 1자 이상             | `templateCode`        |
| 템플릿명       | `templateName`          | Input       | Y    | `""`                                  | 1자 이상             | `templateName`        |
| 보안템플릿여부 | `templateEmphasizeType` | Radio       | N    | `false`                               | `true` / `false`     | `pcflag`              |
| 템플릿내용     | `templateContent`       | Textarea    | Y    | `""`                                  | 1자 이상             | `templateContent`     |
| 버튼           | `buttons`               | Table       | N    | `[]`                                  | 빈 배열              | `buttons`             |
| 바로연결       | `quickReplies`          | Table       | N    | `[]`                                  | 빈 배열              | `quickReplies`        |

### 9-4. 버튼/이벤트 상세

| 트리거           | 처리 로직                                       | 비고                                 |
| ---------------- | ----------------------------------------------- | ------------------------------------ |
| 템플릿등록(외부) | 다이얼로그 open = true, form reset              | 진입 시 초기화                       |
| 저장             | zod 검증 통과 후 `saveNtftalkTemp` 호출         | 성공 시 `등록되었습니다.` 알림       |
| 저장 성공        | `invalidateQueries([NTFTALK_TEMP])` → 모달 닫기 | 목록 최신화                          |
| 저장 실패        | 공통 mutation error 처리                        | 에러 메시지 표시 정책 공통 모듈 따름 |
| + 변수추가       | 변수 선택 팝업 open                             | 9-5 참조                             |

### 9-5. 변수추가 팝업 상세

| 항목        | 내용                                                                 |
| ----------- | -------------------------------------------------------------------- |
| 팝업명      | 변수 목록                                                            |
| 데이터 소스 | `NtftalkVarApi.getNtftalkVarPage`                                    |
| 조회 조건   | `sort=regDt,desc`, 페이지네이션(`pageIndex/pageSize`)                |
| 선택 방식   | 다중 선택 (`RowSelectionState`)                                      |
| [추가] 동작 | 선택된 `varCd`를 줄바꿈(`\n`)으로 `templateContent` 하단에 append    |
| 유효성 체크 | 선택 0건: "추가할 변수를 선택해 주세요." / `varCd` 공백 포함 시 에러 |
| [취소] 동작 | 팝업 닫기(선택값 유지 안 함)                                         |

### 9-6. API 명세

| 기능        | Method | URL             | Request DTO              | Response DTO  | 클라이언트 API                   |
| ----------- | ------ | --------------- | ------------------------ | ------------- | -------------------------------- |
| 템플릿 등록 | POST   | `/ntftalk-temp` | `NtftalkTempSavePayload` | `NtftalkTemp` | `NtftalkTempApi.saveNtftalkTemp` |