ㅓ# 게시판 관리 기능 구현 계획서

> 작성일: 2025-12-19
> 상태: 🔴 **계획 검토 대기**

---

## 1. 개요

### 1.1 기능 요약
게시판 리스트/등록/상세/댓글 기능 구현

### 1.2 참고 페이지
- **탭 네비게이션**: `src/components/items/ItemListClient.tsx` (품목관리)
- **테이블 필터 위치**: `src/components/accounting/SalesManagement/index.tsx` (매출관리)
- **공통 레이아웃**: `IntegratedListTemplateV2` 템플릿

### 1.3 디자인 스펙 (스크린샷 기준)

#### 리스트 페이지
| 항목 | 내용 |
|------|------|
| 페이지 타이틀 | 게시판 |
| 페이지 설명 | 게시판의 게시글을 등록하고 관리합니다. |
| 날짜 범위 | 2025-09-01 ~ 2025-09-03 |
| 탭 | 전체보드, 전자결재, 인쇄, 미역, 우울 + **게시글 등록** 버튼 |
| 게시판 필터 | 공지사항 (게시판명, 게시판명2, 나의 게시글) |
| 검색 | 검색 입력창 |
| 정렬 | 최신순 ▼ |
| 테이블 컬럼 | No., 제목, 작성자, 등록일, 조회수 |
| 행 클릭 | 게시글 상세 화면으로 이동 |

#### 등록/수정 페이지
| 항목 | 내용 |
|------|------|
| 페이지 타이틀 | 게시글 상세 |
| 페이지 설명 | 게시글을 등록하고 관리합니다. |
| **게시글 정보** (필수 섹션) | |
| - 게시판 | Select: "게시판을 선택해주세요" |
| - 상단 노출 | Radio: 사용안함 / **사용함** |
| - 제목 | Input: "제목을 입력해주세요" |
| - 내용 | **WYSIWYG 에디터** (B, I, U, S, 정렬, 목록, 링크, 이미지 등) |
| - 첨부파일 | 파일 찾기 버튼 |
| - 작성자 | 읽기 전용 (예: 홍길동) |
| - 댓글 | Radio: **사용안함** / 사용함 |
| - 등록일시 | 읽기 전용 (예: 2025-09-09 12:20) |
| 상단 노출 제한 | 최대 5개까지 설정 가능, 초과 시 Alert 표시 |

#### 상세 페이지
| 항목 | 내용 |
|------|------|
| 페이지 타이틀 | 게시글 상세 |
| 페이지 설명 | 게시글을 조회합니다. |
| 버튼 (본인 글만) | **삭제**, **수정** |
| 게시판명 라벨 | 게시판명 |
| 제목 | 제목 |
| 메타 정보 | 작성자 \| 날짜 \| 조회수 (예: 홍길동 \| 2025-09-03 12:23 \| 조회수 123) |
| 내용 | HTML 콘텐츠 (이미지 포함) |
| 첨부파일 | 다운로드 링크 (예: abc.pdf) |
| 댓글 등록 | Textarea + 등록 버튼 (댓글 사용함 설정 시만 표시) |

#### 댓글 섹션
| 항목 | 내용 |
|------|------|
| 댓글 수 | 댓글 N |
| 댓글 정보 | 프로필 이미지, 부서명 이름 직책, 등록일시, 댓글 내용 |
| 수정 버튼 (본인만) | 클릭 시 인풋박스에 기존 댓글 내용 입력 상태로 변경 |
| 삭제 버튼 (본인만) | 클릭 시 **"정말 삭제하시겠습니까?"** 확인 Alert 표시 |

---

## 2. WYSIWYG 에디터 추천

### 2.1 옵션 비교

| 라이브러리 | 장점 | 단점 | 추천도 |
|------------|------|------|--------|
| **TipTap** | 최신, Headless (커스텀 자유), React 네이티브, shadcn/ui 호환 | 학습 곡선 | ⭐⭐⭐⭐⭐ |
| **CKEditor 5** | 기능 풍부, 엔터프라이즈급, 이미지 업로드 내장 | 무거움, 스타일 충돌, 라이선스 | ⭐⭐⭐⭐ |
| **Quill** | 간단, 가벼움 | 구식 스타일, 유지보수 부족 | ⭐⭐⭐ |
| **Editor.js** | 블록 기반, 노션 스타일 | JSON 출력 (HTML 아님), 변환 필요 | ⭐⭐⭐ |
| **React-Quill** | Quill + React 래퍼 | Next.js SSR 이슈 | ⭐⭐ |

### 2.2 최종 추천: **TipTap**

**이유**:
1. **Headless 아키텍처**: shadcn/ui와 Tailwind CSS 완벽 호환
2. **모던 React**: useState/useEffect 패턴, TypeScript 완벽 지원
3. **확장성**: 필요한 기능만 설치 (경량화)
4. **커뮤니티**: 활발한 개발, 문서화 우수
5. **이미지 업로드**: 커스텀 핸들러로 S3/백엔드 연동 용이

### 2.3 필요 패키지 (TipTap)

```bash
npm install @tiptap/react @tiptap/pm @tiptap/starter-kit \
  @tiptap/extension-image @tiptap/extension-link \
  @tiptap/extension-underline @tiptap/extension-text-align \
  @tiptap/extension-placeholder
```

---

## 3. 파일 구조

```
src/
├── app/[locale]/(protected)/board/
│   ├── page.tsx                    # 게시판 리스트 페이지
│   ├── create/
│   │   └── page.tsx                # 게시글 등록 페이지
│   └── [id]/
│       ├── page.tsx                # 게시글 상세 페이지
│       └── edit/
│           └── page.tsx            # 게시글 수정 페이지
│
├── components/board/
│   ├── BoardList/
│   │   ├── index.tsx               # 리스트 메인 컴포넌트
│   │   └── types.ts                # 타입 정의
│   ├── BoardForm/
│   │   ├── index.tsx               # 등록/수정 폼
│   │   └── types.ts
│   ├── BoardDetail/
│   │   ├── index.tsx               # 상세 보기
│   │   └── types.ts
│   ├── CommentSection/
│   │   ├── index.tsx               # 댓글 섹션
│   │   ├── CommentItem.tsx         # 개별 댓글 컴포넌트
│   │   └── types.ts
│   └── RichTextEditor/
│       ├── index.tsx               # TipTap 에디터 래퍼
│       ├── MenuBar.tsx             # 에디터 툴바
│       └── extensions.ts           # TipTap 확장 설정
│
└── hooks/
    └── useBoardList.ts             # 게시판 목록 API 훅
```

---

## 4. 구현 체크리스트

### Phase 1: 기반 작업 (에디터 + 타입)

- [ ] **1.1** TipTap 패키지 설치
- [ ] **1.2** `RichTextEditor` 컴포넌트 구현
  - [ ] 1.2.1 기본 에디터 (Bold, Italic, Underline, Strike)
  - [ ] 1.2.2 텍스트 정렬 (좌/중/우)
  - [ ] 1.2.3 목록 (Bullet, Ordered)
  - [ ] 1.2.4 링크 삽입
  - [ ] 1.2.5 이미지 업로드 (파일 선택 → 백엔드 업로드 → URL 삽입)
- [ ] **1.3** `types.ts` 정의
  - [ ] 1.3.1 Board (게시판 타입)
  - [ ] 1.3.2 Post (게시글 타입)
  - [ ] 1.3.3 Comment (댓글 타입)

### Phase 2: 리스트 페이지

- [ ] **2.1** `BoardList/index.tsx` 구현
  - [ ] 2.1.1 IntegratedListTemplateV2 적용
  - [ ] 2.1.2 DateRangeSelector (날짜 범위)
  - [ ] 2.1.3 탭 네비게이션 (전체보드, 전자결재, 인쇄, 미역, 우울)
  - [ ] 2.1.4 게시판 필터 (공지사항 드롭다운)
  - [ ] 2.1.5 검색 입력창
  - [ ] 2.1.6 정렬 드롭다운 (최신순)
  - [ ] 2.1.7 총 N건 표시
- [ ] **2.2** 테이블 구현
  - [ ] 2.2.1 컬럼: No., 제목, 작성자, 등록일, 조회수
  - [ ] 2.2.2 체크박스 선택
  - [ ] 2.2.3 행 클릭 → 상세 이동
- [ ] **2.3** 모바일 카드 뷰 구현
- [ ] **2.4** 페이지네이션 구현
- [ ] **2.5** `page.tsx` 라우트 생성

### Phase 3: 등록/수정 페이지

- [ ] **3.1** `BoardForm/index.tsx` 구현
  - [ ] 3.1.1 게시판 Select (게시판 목록)
  - [ ] 3.1.2 상단 노출 Radio (사용안함/사용함)
    - [ ] 3.1.2.1 최대 5개 제한 Alert
  - [ ] 3.1.3 제목 Input
  - [ ] 3.1.4 내용 RichTextEditor
  - [ ] 3.1.5 첨부파일 업로드 (다중 파일)
  - [ ] 3.1.6 작성자 표시 (읽기 전용)
  - [ ] 3.1.7 댓글 Radio (사용안함/사용함)
  - [ ] 3.1.8 등록일시 표시 (읽기 전용)
  - [ ] 3.1.9 등록 버튼
- [ ] **3.2** 수정 모드 구현 (기존 데이터 로드)
- [ ] **3.3** 유효성 검사
  - [ ] 3.3.1 필수 필드: 게시판, 제목, 내용
- [ ] **3.4** `create/page.tsx` 라우트 생성
- [ ] **3.5** `[id]/edit/page.tsx` 라우트 생성

### Phase 4: 상세 페이지

- [ ] **4.1** `BoardDetail/index.tsx` 구현
  - [ ] 4.1.1 게시판명 라벨
  - [ ] 4.1.2 제목
  - [ ] 4.1.3 메타 정보 (작성자 | 날짜 | 조회수)
  - [ ] 4.1.4 내용 (HTML 렌더링)
  - [ ] 4.1.5 첨부파일 다운로드 링크
- [ ] **4.2** 삭제/수정 버튼 (본인 글만 표시)
  - [ ] 4.2.1 삭제 버튼 → **AlertDialog** ("정말 삭제하시겠습니까?")
  - [ ] 4.2.2 수정 버튼 → 수정 페이지 이동
- [ ] **4.3** `[id]/page.tsx` 라우트 생성

### Phase 5: 댓글 기능

- [ ] **5.1** `CommentSection/index.tsx` 구현
  - [ ] 5.1.1 댓글 등록 Textarea + 버튼
  - [ ] 5.1.2 댓글 수 표시 ("댓글 N")
- [ ] **5.2** `CommentItem.tsx` 구현
  - [ ] 5.2.1 프로필 이미지
  - [ ] 5.2.2 부서명 이름 직책
  - [ ] 5.2.3 등록일시
  - [ ] 5.2.4 댓글 내용
  - [ ] 5.2.5 수정 버튼 (본인만) → 인라인 수정 모드
  - [ ] 5.2.6 삭제 버튼 (본인만) → **AlertDialog**
- [ ] **5.3** 댓글 CRUD API 연동

### Phase 6: API 연동 + 마무리

- [ ] **6.1** Mock 데이터 → 실제 API 연동
- [ ] **6.2** 에러 핸들링 (toast 알림)
- [ ] **6.3** 로딩 상태 UI
- [ ] **6.4** 반응형 테스트 (모바일/태블릿/데스크톱)
- [ ] **6.5** 접근 권한 테스트 (본인 글/타인 글)

### Phase 7: 문서화

- [ ] **7.1** 테스트 URL 문서 업데이트 (`[REF] all-pages-test-urls.md`)
  - [ ] 7.1.1 게시판 섹션 신규 추가 (기존 구역과 별도)
  - [ ] 7.1.2 메인 리스트 URL만 등록
- [ ] **7.2** 이 문서 완료 처리

---

## 5. 주의사항 (버디가 자주 틀리는 것들)

### 5.1 디스크립션 확인 필수
- [ ] 리스트: "게시판의 게시글을 등록하고 관리합니다."
- [ ] 등록: "게시글을 등록하고 관리합니다."
- [ ] 상세: "게시글을 조회합니다."

### 5.2 테이블 컬럼 타이틀 정확히
- [ ] No. (번호 아님)
- [ ] 제목
- [ ] 작성자
- [ ] 등록일
- [ ] 조회수

### 5.3 카드/라벨 텍스트 정확히
- [ ] "게시판" (게시판명 아님, Select label)
- [ ] "상단 노출" (상단고정 아님)
- [ ] "댓글" (댓글허용 아님)
- [ ] "댓글 N" (댓글 수 표시)

### 5.4 팝업 메시지 정확히
- [ ] 삭제 확인: **"정말 삭제하시겠습니까?"**
- [ ] 상단 노출 초과: **"상단 노출은 5개까지 설정 가능합니다."**

### 5.5 본인 글/댓글 체크
- [ ] 게시글 삭제/수정 버튼 → 본인 글만
- [ ] 댓글 수정/삭제 버튼 → 본인 댓글만

---

## 6. 기술 스택

| 항목 | 기술 |
|------|------|
| 프레임워크 | Next.js 14 App Router |
| UI 컴포넌트 | shadcn/ui |
| 스타일링 | Tailwind CSS |
| 에디터 | **TipTap** |
| 폼 | React Hook Form (권장) |
| 상태 관리 | React useState/useCallback |
| API | Next.js API Routes (Proxy) |
| 팝업 | AlertDialog, Dialog (Radix UI) |

---

## 7. 작업 완료 후 필수 조치

### 7.1 테스트 URL 문서 업데이트

`claudedocs/[REF] all-pages-test-urls.md` 파일에 다음 내용 추가:

```markdown
## 게시판 (Board) - 🆕 NEW SECTION

| 페이지 | URL | 비고 |
|--------|-----|------|
| 게시판 목록 | `/ko/board` | 🆕 NEW |
```

> ⚠️ **참고**: 상세/수정/등록 페이지는 메인 리스트에서 접근 가능하므로 별도 등록하지 않음

### 7.2 _index.md 업데이트

`claudedocs/_index.md`에 board/ 폴더 섹션 추가

---

## 8. 승인 대기

- [ ] 사용자 확인 완료
- [ ] 작업 시작

---

*작성: Claude Code*