# 템하 그누보드 Vue 컴포넌트 — AI 통합 가이드
> **대상:** Claude, Cursor 등 AI 코딩 어시스턴트
> **목적:** 템하(Temha) 플랫폼의 그누보드 연동 Vue 컴포넌트를 HTML에서 올바르게 구현하기 위한 단일 참조 문서
---
## 1. 공통 규칙 (모든 컴포넌트에 적용)
### 1-1. 서버 URL 선언
```html
```
- `data-gb-url`은 **`` 태그에 단 한 번만** 선언. 하위 컴포넌트가 자동 참조.
### 1-2. 초기화 함수 목록
| 컴포넌트 | 초기화 함수 | 루트 클래스 |
|----------|-------------|-------------|
| 로그인 | `vue_gnulogin(el)` | `.login-app` |
| 회원가입 | `vue_gnulogin(el)` | `.signup-app` |
| 목록/글쓰기/수정/상세 | `vue_gnuboard(el)` | `.gnuboard` |
| 프로필 수정 | `vue_gnuprofile(el)` | `.profile-app` |
```javascript
// 공통 초기화 패턴 (클래스명만 바꿔서 재사용)
(function() {
$(function() {
$(".내블록클래스").each(function() {
const $gnu = $(this).find(".gnuboard"); // 또는 .login-app 등
if ($gnu.length) vue_gnuboard($gnu[0]); // DOM 요소 직접 전달 (selector 문자열 불가)
});
});
})();
```
### 1-3. 에디터 환경 패턴 (isEditor)
에디터 미리보기에서는 `env === 'editor'`이며, 이때 화면 전환 영역이 동시에 표시되고 버튼이 항상 활성화되어야 한다.
```html
```
### 1-4. 화면 전환 디렉티브 (status 기반)
에디터에서는 모든 영역이 동시 표시되고, 실제 운영에서는 `status`에 따라 하나만 표시된다.
---
## 2. 로그인 (Login)
### HTML 구조
```html
```
### 핵심 변수/디렉티브
| 항목 | 설명 |
|------|------|
| `v-gb-terms` / `v-gb-signup` | 약관/폼 단계 영역 전환 |
| `v-gb-btn-signup` / `v-gb-btn-terms` | 단계 전환 버튼 |
| `agreeAll` + `@change="toggleAllAgree"` | 전체 동의 |
| `agreements.stipulation` / `.privacy` | 개별 약관 동의 여부 |
| `canProceedToSignup` | 두 약관 모두 동의 시 true |
| `validation.mb_id` / `.mb_nick` | null: 미확인 / true: 사용가능 / false: 사용불가 |
| `checkDuplicate('mb_id')` | 중복 확인 실행 |
| `isFormValid` | 가입 버튼 활성화 조건 (모든 필수 필드 + 중복 확인 완료) |
| `showXxx` / `reqXxx` | 서버 설정 기반 조건부 표시/필수 계산 속성 |
---
## 4. 목록 (List)
### HTML 구조
```html
```
### 핵심 규칙
| 규칙 | 설명 |
|------|------|
| `data-gb-tpl="필드명"` | `{{item.필드명}}`과 **항상 함께** 사용 (데이터 동기화) |
| `:data-gb-wr-id="item.wr_id"` | 이미지 로드에 필수. 누락 시 썸네일 미표시 |
| `v-gb-list-onload="true"` | 페이지 로드 시 자동 목록 조회. 누락 시 목록 안 나옴 |
| `data-gb-text-limit="50"` | 내용 글자 수 제한. `.gnuboard`에 선언하면 전체 적용 |
| `getListItemImage(item)` | 썸네일 반환 함수 (첨부이미지 → 본문img → 기본이미지 순) |
| `br.writes` | 게시글 배열 |
| `br.total_records` | 전체 게시글 수 |
---
## 5. 상세보기 (Read)
### HTML 구조
```html
```
### 핵심 변수/규칙
| 항목 | 설명 |
|------|------|
| `bw` 객체 | 글쓰기 폼 데이터 |
| `be` 객체 | 수정 폼 데이터 (mounted 시 `bs`에서 자동 복사) |
| `bs` 객체 | 기존 게시글 데이터 |
| `bi` 객체 | 게시판 설정 (`bi.bo_upload_count`, `bi.bo_use_category` 등) |
| `bw.wr_1`~`bw.wr_10` | 여분 필드. `submitWrite()` 시 자동 전송 |
| `be.wr_1`~`be.wr_10` | 수정 여분 필드. `submitEdit()` 시 자동 전송 |
| `id="editor"` | 글쓰기 Quill 에디터 고정 id |
| `id="edit-editor"` | 수정 Quill 에디터 고정 id |
| `bs.normal_files` | 기존 첨부파일 배열 (`bs.files` 사용 금지) |
| `deleteFile(bf_no)` | 삭제 목록에 추가 (저장 시 일괄 처리) |
| `data-gb-extra-fields-required` | 필수 여분 필드 목록 (쉼표 구분) |
| `data-gb-privacy-required` | 개인정보 동의 필드 필수 검사 활성화 |
| `data-gb-privacy-field` | 동의 필드명 (기본: `wr_9`) |
### submitWrite/submitEdit 내부 순서
1. 필수 항목(`wr_subject`, `wr_content`) 검사
2. 비로그인 이름·비밀번호 검사
3. `data-gb-*` 추가 필드·개인정보 동의 검사 (`gbCheckFormCustomRequired`)
4. 게스트 토큰 발급 (비로그인)
5. 파일 삭제 (수정 시) → 게시글 POST/PUT → 파일 업로드
6. 이동 (`getListLink()` / `getViewLink(wr_id)`)
---
## 7. 프로필 수정 (Profile)
### HTML 구조
```html
✓ 사용 가능합니다.
✗ 이미 사용 중입니다.
이메일 수신
SMS 수신
정보공개
```
### 핵심 규칙
| 항목 | 설명 |
|------|------|
| `v-gb-password-check` / `v-gb-profile-edit` | 화면 전환 디렉티브 |
| `v-gb-btn-password-check` | 비밀번호 확인 화면으로 돌아가기 버튼 |
| `password_check_form.password` | 비밀번호 확인 입력값 |
| `profile_form.*` | 프로필 수정 폼 데이터 |
| `original_profile.mb_nick` | 기존 닉네임 (동일하면 중복확인 불필요) |
| `profileImage` | 미리보기 또는 현재 이미지 URL (computed) |
| `clickImageInput()` | 이미지 변경 — **반드시 이 메서드 사용** (`$refs.imageInput.click()` 직접 사용 금지) |
| `clickImageDelete()` | 이미지 삭제 — **반드시 이 메서드 사용** |
| `handleUpdateProfile()` | 저장 실행 (이미지 처리 → 프로필 PUT → 리다이렉트) |
---
## 8. 공통 data-gb-* 속성 전체 목록
### body 레벨
| 속성 | 설명 |
|------|------|
| `data-gb-url` | 그누보드 서버 주소 (필수, body에 단 한 번) |
### 게시판 컴포넌트 (.gnuboard)
| 속성 | 설명 |
|------|------|
| `data-gb-table` | 게시판 테이블명 |
| `data-gb-table-name` | 게시판 표시명 |
| `data-gb-list-link` | 목록 페이지 경로 |
| `data-gb-view-link` | 상세보기 페이지 경로 |
| `data-gb-write-link` | 글쓰기 페이지 경로 |
| `data-gb-initial-status` | 초기 상태 (`list`/`read`/`write`/`edit`) |
| `data-gb-text-limit` | 목록 내용 글자 수 제한 |
| `data-gb-extra-fields-required` | 필수 여분 필드 (쉼표 구분, `wr_1`~`wr_10`) |
| `data-gb-write-extra-required` | 글쓰기 전용 필수 여분 필드 |
| `data-gb-edit-extra-required` | 수정 전용 필수 여분 필드 |
| `data-gb-extra-required-alert` | 여분 필드 검사 실패 시 alert 문구 |
| `data-gb-privacy-required` | 개인정보 동의 필수 (글쓰기+수정) |
| `data-gb-write-privacy-required` | 글쓰기 전용 개인정보 동의 필수 |
| `data-gb-edit-privacy-required` | 수정 전용 개인정보 동의 필수 |
| `data-gb-privacy-field` | 동의 필드명 (기본: `wr_9`) |
| `data-gb-privacy-alert` | 개인정보 동의 실패 시 alert 문구 |
### 회원 컴포넌트
| 속성 | 설명 |
|------|------|
| `data-gb-login-link` | 로그인 페이지 경로 |
| `data-gb-signup-link` | 회원가입 페이지 경로 |
| `data-gb-find-password-link` | 비밀번호 찾기 페이지 경로 |
| `data-gb-redirect` | 완료 후 이동 경로 |
| `data-gb-initial-status` | 초기 상태 |
---
## 9. 자주 하는 실수 — 전체 요약
| 증상 | 원인 | 해결 |
|------|------|------|
| 에디터 버튼이 비활성화됨 | `!isEditor &&` 조건 누락 | `:disabled="!isEditor && !isFormValid"` 패턴 사용 |
| 첨부파일 목록 오류 | `bs.files` 사용 | `bs.normal_files` 로 변경 |
| 본문이 HTML 태그로 출력 | `v-html` 미사용 | `v-html="bs.wr_content"` 사용 |
| 목록 이미지 미표시 | `:data-gb-wr-id` 누락 | `:data-gb-wr-id="item.wr_id"` 추가 |
| 목록 내용이 HTML로 출력 | `data-gb-tpl` 누락 | `data-gb-tpl="wr_content"` 추가 |
| 목록이 안 나옴 | `v-gb-list-onload` 누락 | `v-gb-list-onload="true"` 추가 |
| 수정 시 기존 내용 미표시 | URL에 `?wr_id` 없음 | `write.html?wr_id=1` 형태로 접근 |
| 상세보기 데이터 없음 | URL에 `?wr_id` 없음 | `viewer.html?wr_id=1` 형태로 접근 |
| 에디터 두 화면 동시 표시 | 에디터 환경의 의도된 동작 | 정상 (운영에서는 하나만 표시) |
| 이미지 변경 버튼 동작 안 함 | `$refs.imageInput.click()` 직접 사용 | `clickImageInput()` 메서드 사용 |
| 개인정보 약관에 태그 노출 | `v-html` 사용 | `{{ terms.privacy }}` 텍스트 보간 사용 |
| 완료 후 이동 안 됨 | `data-gb-redirect` 또는 `data-gb-list-link` 누락 | 해당 속성 확인 및 추가 |
| 중복 확인 후 값 변경 시 재확인 불필요 | 자동 초기화됨 | 별도 처리 불필요 |
| 비회원 목록 이미지 미표시 | 읽기 권한 부족 | 관리자에서 "목록에서 내용보기" 활성화 |