# WordPress 쇼핑몰 홈페이지 개발 문서

> MangBoard 기반 WordPress 쇼핑몰의 템플릿 구조, 플러그인 아키텍처, 배포/백업 방법을 정리한 실전 가이드입니다.

---

# # 목차

1. [프로젝트 개요](#1-프로젝트-개요)

2. [파일 구성 현황](#2-파일-구성-현황)

3. [개발한 플러그인](#3-개발한-플러그인)

4. [배포 및 백업 방법](#4-배포-및-백업-방법)

5. [Git 커밋 구성안](#5-git-커밋-구성안)

6. [개발 가이드](#6-개발-가이드)

7. [아키텍처 참고](#7-아키텍처-참고)

8. [보안 체크리스트](#8-보안-체크리스트)

9. [변경 이력](#9-변경-이력)

---

# # 1. 프로젝트 개요

## # 1.1 시스템 구성

| 구성요소 | 기술스택 |

|---------|---------|

| 웹서버 | Docker (WordPress:latest) |

| DB | MariaDB 11 |

| 테마 | Hometory (커스텀 수정) |

| 게시판 | MangBoard 플러그인 |

| PHP | 8.x (WordPress 컨테이너) |

| 실시간 통신 | Socket.io (Express, pm2, socket.wellcoms.co.kr) |

| 분석 | Umami (PostgreSQL, stats.wellcoms.co.kr) |

## # 1.2 디렉토리 구조

```mermaid

flowchart LR

    ROOT["WordPress 루트"] --> THEME["themes/hometory/"]

    ROOT --> PLUGINS["plugins/"]

    ROOT --> MU["mu-plugins/"]

    ROOT --> UPLOADS["uploads/"]

    ROOT -.->|"Git 제외"| WP["wp-admin/ wp-includes/"]

    PLUGINS --> KK["wellcoms-kkung"]

    PLUGINS --> TJ["wellcoms-taja"]

    PLUGINS --> EST["wellcoms-estimate"]

    PLUGINS --> INV["wellcoms-invoice"]

    PLUGINS --> MD["mangboard-markdown"]

    PLUGINS --> MB["mangboard (설치)"]

    MU --> MU_FILES["wellcoms-*.php"]

    style WP fill:#FFCDD2

    style THEME fill:#C8E6C9

    style MU_FILES fill:#C8E6C9

```

## # 1.3 홈페이지 주요 구성 요소

| 구성 | 설명 |

|------|------|

| 메인 홈 | Hero / 고객 후기 / 인기 제품(컴팩트 여백) / 추천 조립PC 쇼케이스 / 꿀팁·공지(카테고리 배지) / CTA |

| 추천 PC 조립 | 4종 샘플PC 카드 + 제작 프로세스 + 상세 진입점 |

| 쇼핑몰 | 일반 상품 + 샘플PC 매핑 상품 통합 + 상담 게시판 (Q&A standalone 라우팅) |

| 정보 문서 | 마크다운 렌더링 + 망보드 댓글 연동 + 카테고리 배지 스타일링 |

| 원격 지원 | 원격 지원 안내 + 카카오톡 상담 |

| 오시는 길 | 네이버맵(PC) / OSM(모바일) + 카카오맵·네이버맵 검색 버튼 |

---

# # 2. 파일 구성 현황

## # 2.1 테마 커스텀 파일

### # 페이지 템플릿

| 파일명 | 용도 |

|--------|------|

| `page-wellcoms-home.php` | 메인 홈페이지 (Hero/후기/제품/CTA/꿀팁·공지) |

| `page-wellcoms-repair.php` | 수리/추천 조립PC 랜딩 |

| `page-wellcoms-remote.php` | 원격 지원 |

| `page-shop.php` | 쇼핑몰 (일반 상품 + 샘플PC 통합 + 상담 게시판 Q&A) |

| `page-info-docs.php` | 정보/문서 페이지 (마크다운 + 댓글) |

| `page-notics.php` | 공지사항 |

| `page-repair-custom.php` | 수리 커스텀 |

| `page-recommand-qna.php` | 추천 PC 조립 Q&A |

### # CSS 파일

| 파일명 | 용도 |

|--------|------|

| `style.css` | 테마 기본 스타일 |

| `wellcoms-custom.css` | 커스텀 스타일 (주요 디자인) |

| `wellcoms-fix.css` | 스타일 수정 패치 (버그 수정 + 카테고리 배지 스타일링) |

| `mangboard-nav-fix.css` | 망보드 네비게이션 수정 |

### # PHP 파일

| 파일명 | 용도 |

|--------|------|

| `functions.php` | 템플릿 함수 (MangBoard stub + 코스피/환율 AJAX 엔드포인트) |

| `header.php` | 기본 헤더 |

| `header-fluid.php` | 전체폭 헤더 |

| `footer.php` | 푸터 (커스텀) |

## # 2.2 홈페이지 섹션 구조

```mermaid

flowchart TD

    A["page-wellcoms-home.php"] --> B["Hero Section"]

    A --> C["Why Choose Us"]

    A --> D["고객 후기"]

    A --> E["제품 안내 (모든 상품 보기 버튼)"]

    A --> F["추천 조립PC 쇼케이스"]

    A --> G["컴퓨터 꿀팁 + 공지 (카테고리 배지, 6개 제한)"]

    A --> H["CTA Section"]

    style A fill:#E3F2FD

    style B fill:#C8E6C9

    style H fill:#C8E6C9

```

## # 2.3 푸터 섹션 구조

```mermaid

flowchart TD

    A["footer.php"] --> B["법률 정보 바 (대표자/사업자번호/주소)"]

    A --> C["4열 그리드"]

    C --> D["회사 정보"]

    C --> E["서비스 링크"]

    C --> F["정보 링크"]

    C --> G["고객지원"]

    A --> H["이용약관 / 개인정보처리방침 / 오시는 길"]

    A --> NAV["모바일 페이지 네비게이션 (← → 고정 버튼)"]

    style NAV fill:#FFF9C4

```

## # 2.4 설치된 플러그인 목록

| 플러그인 | 타입 | 용도 |

|---------|------|------|

| `mangboard-markdown` | 개발 | 마크다운 렌더링 |

| `wellcoms-estimate` | 개발 | PC 견적서 시스템 |

| `wellcoms-kkung` | 개발 | 쿵쿵따 끝말잇기 게임 |

| `wellcoms-taja` | 개발 | 한글 타자 연습 게임 |

| `wellcoms-invoice` | 개발 | 거래명세서/견적서 관리 |

| `mangboard` | 설치 | 게시판 시스템 (필수) |

| `litespeed-cache` | 설치 | 캐싱 |

| `seo-by-rank-math` | 설치 | SEO |

| `wordfence` | 설치 | 보안 |

| `duplicator` | 설치 | 백업/이전 |

| `wp-mail-smtp` | 설치 | 메일 SMTP |

## # 2.5 MangBoard Q&A 커스텀 스킨

Q&A 게시판 전용 스킨으로 MangBoard 기본 스킨을 대폭 수정.

```mermaid

flowchart TD

    SKIN["bbs_qanda_m1/"] --> V["view.php - 게시글 조회"]

    SKIN --> L["list.php - 목록 (반응형)"]

    SKIN --> W["write.php - 글쓰기/답변"]

    SKIN --> CPP["comment-per-post.php - 개별 댓글"]

    SKIN --> C["comment.php - 기본 댓글"]

    SKIN --> CSS2["css/custom.css"]

    SKIN --> INC["includes/skin-model.php"]

    V --> V1["본문 + 답변 + 댓글 통합"]

     CPP --> CPP1["IIFE 스코프 JS (변수 충돌 방지)"]

```

## # 2.6 MangBoard 코어 수정 사항

> ⚠️ MangBoard 코어 파일 수정분. 플러그인 업데이트 시 덮어씌워질 수 있으므로 주의.

| 파일 | 수정 내용 |

|------|----------|

| `mangboard/includes/skin-template.php` | 카테고리 텍스트 `[카테고리명]` → `카테고리명` (괄호 제거, 3곳) |

| `mangboard/templates/tpl.board.php` | 카테고리 텍스트 `[카테고리명]` → `카테고리명` (괄호 제거, 3곳) + 공지 `[공지]` → `공지]` (1곳) |

카테고리 배지 스타일은 `wellcoms-fix.css`와 `page-info-docs.php` 인라인에서 높은 CSS 명시도로 오버라이드:

```css

/* 배지 스타일 (높은 명시도) */

.category1-text {

    display: inline-block;

    font-size: 0.72rem;

    font-weight: 600;

    color: #00a2cc;

    background: rgba(0,162,204,0.08);

    padding: 2px 7px;

    border-radius: 4px;

}

```

---

# # 3. 개발한 플러그인

## # 3.1 마크다운 렌더링 (mangboard-markdown)

### # 구조

```mermaid

flowchart TD

    MAIN2["mangboard-markdown.php"] --> HOOKS["wp_head / wp_footer 훅"]

    HOOKS --> INJECT["CSS/JS 주입"]

    INJECT --> DETECT["마크다운 감지"]

    DETECT --> RENDER["클라이언트 사이드 HTML 변환"]

    RENDER --> PARSE["자체 파서 (4함수)"]

    RENDER --> MERMAID["Mermaid.js (다이어그램)"]

    RENDER --> PRISM["Prism.js (코드 하이라이트)"]

    RENDER --> HIGHLIGHT["highlight.js (예약어)"]

```

### # 주요 기능

- 망보드 게시판 마크다운 자동 렌더링

- 코드 블록 구문 강조 + 복사 버튼 (빈줄 자동 제거)

- Mermaid 다이어그램 지원

- GFM (GitHub Flavored Markdown) 지원

## # 3.2 PC 견적서 (wellcoms-estimate)

| 항목 | 설명 |

|------|------|

| 위치 | `wp-content/plugins/wellcoms-estimate/` |

| GitLab | `https://gitlab.wellcoms.co.kr/jskim/wp-wellcoms-estimate` |

| 기능 | 13개 부품 카테고리, 견적서 PDF/이메일, 샘플PC 동기화 |

| 의존 | MangBoard 필수 |

## # 3.3 쿵쿵따 끝말잇기 (wellcoms-kkung)

| 항목 | 설명 |

|------|------|

| 위치 | `wp-content/plugins/wellcoms-kkung/` |

| GitLab | `https://gitlab.wellcoms.co.kr/jskim/wp-wellcoms-kkung` |

| 기능 | 끝말잇기 게임, 멀티플레이어 방, 두음법칙, 금지어, 전적/리더보드 |

| 실시간 | Socket.io `/kkung` namespace |

## # 3.4 한글 타자 연습 (wellcoms-taja)

| 항목 | 설명 |

|------|------|

| 위치 | `wp-content/plugins/wellcoms-taja/` |

| GitLab | `https://gitlab.wellcoms.co.kr/jskim/wp-wellcoms-taja` |

| 기능 | Canvas 타자 게임, 6개 템플릿, 등급 시스템, 리더보드 |

| 실시간 | Socket.io `/taja` namespace |

## # 3.5 거래명세서 (wellcoms-invoice)

| 항목 | 설명 |

|------|------|

| 위치 | `wp-content/plugins/wellcoms-invoice/` |

| GitLab | `https://gitlab.wellcoms.co.kr/jskim/wp-wellcoms-invoice` |

## # 3.6 Socket.io 실시간 서버

```mermaid

flowchart LR

    PHP["PHP (AJAX 쓰기)"] -->|"HTTP POST<br/>kk_socket_notify()"| SIO["Socket.io 서버<br/>/srv/docker/wellcoms-socket/"]

    SIO -->|"/kkung"| KK["쿵쿵따 클라이언트"]

    SIO -->|"/taja"| TJ["타자 클라이언트"]

    SIO -->|"MariaDB"| DB["WordPress transient 읽기"]

    style SIO fill:#C8E6C9

```

| 항목 | 값 |

|------|-----|

| 위치 | `/srv/docker/wellcoms-socket/` (호스트, Docker 외부) |

| 런타임 | pm2 (`wellcoms-socket`), 포트 3002 |

| 도메인 | `socket.wellcoms.co.kr` (Caddy WebSocket 프록시) |

| 네임스페이스 | `/kkung` (쿵쿵따), `/taja` (타자) |

| 배포 | `pm2 restart wellcoms-socket` |

## # 3.7 Umami 웹 분석

| 항목 | 값 |

|------|-----|

| 위치 | `/srv/docker/umami/` (Docker Compose) |

| DB | PostgreSQL 16 (Umami 전용) |

| 도메인 | `stats.wellcoms.co.kr` → `umami:3000` |

| 추적 사이트 | wellcoms.co.kr, maxign.co.kr |

## # 3.8 MU 플러그인 (mu-plugins)

mu-plugins는 WordPress가 일반 플러그인보다 **먼저 로드**하는 필수 플러그인입니다.  

MangBoard 코어 파일 수정 없이 기능을 오버라이드합니다.

```mermaid

flowchart LR

    MU_ROOT["mu-plugins/"] --> AUTH["인증/권한"]

    MU_ROOT --> UI["프론트엔드"]

    MU_ROOT --> BIZ["비즈니스"]

    AUTH --> A1["admin-ajax-fix"]

    AUTH --> A2["user-panel"]

    UI --> U1["image-compress"]

    UI --> U2["point-toast"]

    UI --> U3["mu-fix"]

    BIZ --> B1["sync-passwords"]

    BIZ --> B2["harden-security"]

    BIZ --> B3["point-fix"]

    BIZ --> B4["admin-point"]

    BIZ --> B5["nocache"]

    style AUTH fill:#C8E6C9

    style UI fill:#E3F2FD

    style BIZ fill:#FFF9C4

```

### # MU 플러그인 상세

| 파일명 | 용도 |

|--------|------|

| `wellcoms-admin-ajax-fix.php` | 관리자 AJAX 인증 수정 — nonce/권한 오버라이드 + MB 사용자 부트스트랩 |

| `wellcoms-user-panel.php` | 프론트엔드 유저 패널 — 로그인/회원가입/탈퇴/배송지 폼 재정의 |

| `sync-mangboard-passwords.php` | 비밀번호 동기화 — WP 비밀번호 변경 시 mb_users 자동 동기화 |

| `harden-security.php` | 보안 강화 — wp-login.php 브루트포스 방어, xmlrpc 차단 |

| `fix-rest-api.php` | REST API 수정 |

| `wellcoms-image-compress.php` | 이미지 자동 압축 + 배송비 수정 — 업로드 1MB 이하 압축, 기본 배송비/제주도 추가 배송비 |

| `wellcoms-mu-fix.php` | 장바구니 버튼 강제 추가 — 망보드 코어 미렌더링 버그 JS 주입 |

| `wellcoms-nocache.php` | 결제 페이지 no-cache — 브라우저 캐시로 설정 미반영 문제 해결 |

| `wellcoms-point-fix.php` | 포인트 중복 환불 방지 + PHP 8.x 경고 억제 |

| `wellcoms-admin-point.php` | 관리자 포인트 직접 수정 — 회원관리 폼에 포인트 입력 필드 추가 |

| `wellcoms-point-toast.php` | 포인트 토스트 알림 — 회원가입/글쓰기/댓글/구매 시 토스트 표시 |

### # 관리자 AJAX 인증 구조

```mermaid

flowchart TD

    REQ["WP 관리자 AJAX 요청"] --> V["mbw_verify_nonce()"]

    V -->|"관리자"| BYPASS1["nonce 검증 우회"]

    V -->|"일반"| CHECK["nonce 검증"]

    BYPASS1 --> P["mbw_is_permission_level()"]

    CHECK --> P

    P -->|"관리자"| BYPASS2["권한 체크 우회"]

    P -->|"일반"| LEVEL["레벨 확인"]

    BYPASS2 --> INIT["mbw_board_api_init 훅"]

    LEVEL --> INIT

    INIT --> RESTORE["set_user_data() 인증 복원"]

    RESTORE --> OK["정상 처리"]

    style BYPASS1 fill:#C8E6C9

    style BYPASS2 fill:#C8E6C9

    style RESTORE fill:#C8E6C9

```

## # 3.9 플러그인 설치 방법

```bash

# 1. GitLab에서 클론

cd /var/www/html/wp-content/plugins/

git clone <GITLAB_REPO_URL>/wp-mangboard-markdown.git

# 2. 권한 설정

sudo chown -R www-data:www-data wp-mangboard-markdown

# 3. 워드프레스 관리자에서 활성화

# 플러그인 > 설치된 플러그인 > 활성화

```

> MangBoard가 설치되어 있어야 작동합니다.

---

# # 4. 배포 및 백업 방법

## # 4.1 Docker 환경

```bash

# 실행

docker compose up -d

# 중지

docker compose down

# 로그 확인

docker compose logs -f wordpress

docker compose logs -f <DB_CONTAINER>

```

### # Socket.io 서버

```bash

pm2 restart wellcoms-socket    # 재시작

pm2 logs wellcoms-socket       # 로그 확인

pm2 status                     # 상태 확인

```

### # Umami

```bash

cd /srv/docker/umami/

docker compose up -d           # 시작

# 관리자: https://stats.wellcoms.co.kr

```

## # 4.2 데이터베이스 백업

```bash

# 백업 (gzip 압축)

docker compose exec -T <DB_CONTAINER> mysqldump -u<USER> -p<PASSWORD> <DB_NAME> | gzip > backup_$(date +%Y%m%d).sql.gz

# 복원

gunzip < backup_20260228.sql.gz | docker compose exec -T <DB_CONTAINER> mysql -u<USER> -p<PASSWORD> <DB_NAME>

```

## # 4.3 파일 백업

```bash

# 업로드 파일 + 커스텀 테마 + 개발 플러그인

tar -czvf backup_$(date +%Y%m%d).tar.gz \

  wp-content/uploads/ \

  wp-content/themes/hometory/ \

  wp-content/plugins/wellcoms-kkung/ \

  wp-content/plugins/wellcoms-taja/ \

  wp-content/plugins/wellcoms-estimate/ \

  wp-content/plugins/mangboard-markdown/

```

## # 4.4 Duplicator 플러그인 사용 (권장)

```mermaid

flowchart LR

    A["관리자 > Duplicator"] --> B["패키지 생성"]

    B --> C["Installer + Archive 다운로드"]

    C --> D["새 서버에 업로드"]

    D --> E["installer.php 실행"]

```

## # 4.5 Git을 통한 버전 관리

```bash

# 변경사항 확인

git status

git diff wp-content/themes/hometory/page-wellcoms-home.php

# 스테이징 + 커밋

git add wp-content/themes/hometory/page-wellcoms-home.php

git commit -m "style: 홈페이지 Hero 섹션 문구 수정"

# 원격 저장소로 push

git push origin main

```

---

# # 5. Git 커밋 구성안

## # 5.1 .gitignore 요약

```mermaid

flowchart TD

    A["Git 추적 대상"] --> A1["wp-content/themes/hometory/"]

    A --> A2["wp-content/plugins/wellcoms-kkung/"]

    A --> A3["wp-content/plugins/wellcoms-taja/"]

    A --> A4["wp-content/plugins/wellcoms-estimate/"]

    A --> A5["wp-content/plugins/wellcoms-invoice/"]

    A --> A6["wp-content/mu-plugins/"]

    A --> A7["wp-content/uploads/최근연도/"]

    A --> A8["문서 (*.md)"]

    B["Git 추적 제외"] --> B1["wp-admin/ wp-includes/"]

    B --> B2["db-data/"]

    B --> B3["*.png *.jpg *.log"]

    B --> B4["망보드 코어 (스킨만 git add -f)"]

    style A fill:#C8E6C9

    style B fill:#FFCDD2

```

## # 5.2 커밋 카테고리

| Prefix | 용도 | 예시 |

|--------|------|------|

| `feat:` | 새 기능 | `feat: 신규 페이지 템플릿 추가` |

| `fix:` | 버그 수정 | `fix: 모바일 메뉴 토글 오류 수정` |

| `style:` | 스타일 변경 | `style: 홈페이지 Hero 섹션 디자인 수정` |

| `docs:` | 문서 | `docs: 배포 가이드 추가` |

| `refactor:` | 리팩토링 | `refactor: API 클래스 구조 개선` |

| `chore:` | 기타 | `chore: .gitignore 업데이트` |

## # 5.3 브랜치 전략

```mermaid

flowchart TD

    MAIN["main (프로덕션)"] --> DEV["develop (개발)"]

    DEV --> F["feature/xxx (기능 개발)"]

    DEV --> H["hotfix/xxx (긴급 수정)"]

    style MAIN fill:#C8E6C9

```

---

# # 6. 개발 가이드

## # 6.1 홈페이지 콘텐츠 수정

홈페이지는 **페이지 템플릿 방식**으로, 워드프레스 관리자가 아닌 **파일 직접 수정**이 필요합니다.

```mermaid

flowchart TD

    A["워드프레스 페이지 (DB)"] -->|"URL 라우팅"| B["슬러그: /home"]

    B -->|"템플릿 지정"| C["page-wellcoms-home.php"]

    C --> D["HTML 직접 하드코딩"]

    D --> E["the_content() 호출 없음"]

    E --> F["DB 내용 무시, 파일만 렌더링"]

    style E fill:#FFF9C4

    style F fill:#FFCDD2

```

### # 섹션별 수정 위치

| 섹션 | 수정 내용 |

|------|----------|

| Hero | 메인 타이틀, 서브타이틀, CTA 버튼 |

| Why Choose Us | 4개 항목 내용 |

| 고객 후기 | 후기 카드 내용 |

| 제품 카드 | 서비스 안내 |

| 추천PC | 샘플PC 카드 내용 |

| CTA | 문의 버튼 링크/텍스트 |

## # 6.2 테마 수정 후 반영

```bash

# 1. 파일 수정

vim wp-content/themes/hometory/page-wellcoms-home.php

# 2. OPcache 초기화 (Docker 환경)

docker exec <WP_CONTAINER> php -r 'opcache_reset();'

# 3. 캐시 클리어 (LiteSpeed Cache 사용 시)

# 관리자 > LiteSpeed Cache > 도구 > 모든 캐시 삭제

# 4. 브라우저 캐시 클리어 (Ctrl+Shift+R)

# 5. Git 커밋

git add wp-content/themes/hometory/page-wellcoms-home.php

git commit -m "style: 홈페이지 콘텐츠 수정"

```

## # 6.3 플러그인 개발 후 배포

```mermaid

flowchart LR

    A["로컬 개발"] --> B["Git 커밋 + push"]

    B --> C["서버에서 git pull"]

    C --> D["OPcache 초기화"]

    D --> E["동작 확인"]

```

---

# # 7. 아키텍처 참고

## # 7.1 WordPress + MangBoard 사용자 인증 통합

```mermaid

flowchart TD

    LOGIN["로그인 요청"] --> TYPE{"접근 경로"}

    TYPE -->|"wp-admin"| WP_ADMIN["WP 사용자 인증"]

    TYPE -->|"프론트엔드"| MB_LOGIN["MangBoard 사용자 인증"]

    WP_ADMIN --> ADMIN_SYNC["MB 사용자 자동 바인딩"]

    MB_LOGIN --> FRONT["MB 세션 유지"]

    ADMIN_SYNC --> API["관리자 AJAX API"]

    FRONT --> NORMAL["일반 페이지 렌더링"]

    API --> B1["nonce 검증 우회"]

    API --> B2["권한 체크 우회"]

    API --> B3["MB 사용자 복원"]

    B1 --> OK["정상 처리"]

    B2 --> OK

    B3 --> OK

    style B1 fill:#C8E6C9

    style B2 fill:#C8E6C9

    style B3 fill:#C8E6C9

```

## # 7.2 포인트 토스트 알림 흐름

```mermaid

flowchart TD

    ACTION["회원가입/글쓰기/댓글/구매"] --> HOOK["mbw_user_point2 훅 발동"]

    HOOK --> SAVE["WordPress transient에 토스트 데이터 저장"]

    SAVE --> REDIRECT["AJAX 완료 후 페이지 이동"]

    REDIRECT --> CHECK["wp_footer에서 transient 확인"]

    CHECK -->|"데이터 있음"| TOAST["토스트 알림 표시"]

    CHECK -->|"데이터 없음"| SKIP["표시 안 함"]

```

## # 7.3 상품 상세 페이지 렌더링

```mermaid

flowchart TD

    REQ2["/shop/?vid=N 또는 /shop/?sample_pc=X"] --> PAGE["page-shop.php"]

    PAGE --> CHECK2{"sample_pc 파라미터?"}

    CHECK2 -->|"있음"| SAMPLE["추천PC 상세 레이아웃"]

    CHECK2 -->|"없음"| NORMAL2["일반 상품 상세 레이아웃"]

    SAMPLE --> S1["기본구성 표 (공임비 포함 총액)"]

    SAMPLE --> S2["견적서 보기 패널"]

    SAMPLE --> S3["망보드 리뷰/Q&A/배송/위시리스트"]

    NORMAL2 --> N1["상품정보/리뷰/Q&A 탭"]

    NORMAL2 --> N2["이미지 캐러셀 + 라이트박스"]

    NORMAL2 --> N3["구매하기/장바구니/견적서보기 버튼"]

    style SAMPLE fill:#E3F2FD

    style NORMAL2 fill:#FFF9C4

```

## # 7.4 쇼핑몰 상담 게시판 (Q&A) 라우팅

```mermaid

flowchart TD

    REQ["/shop/ 요청"] --> ROUTE{"mode + vid 파라미터"}

    ROUTE -->|"mode=list 또는 vid=0"| HOME["쇼핑몰 홈 (히어로 + 제품 + Q&A 리스트)"]

    ROUTE -->|"vid > 0 (shop_qna 아님)"| DETAIL["제품 상세 페이지"]

    ROUTE -->|"vid=0 & mode=write"| STANDALONE_W["Q&A 글쓰기 (standalone)"]

    ROUTE -->|"vid=0 & mode=view"| STANDALONE_V["Q&A 게시글 보기 (standalone)"]

    STANDALONE_W --> SUBMIT["글쓰기 제출"]

    SUBMIT --> AJAX1["GET /shop/?wc_action=latest_qna_pid"]

    AJAX1 --> REDIR1["redirect → /shop/?mode=view&board_pid=N#wc-shop-qna"]

    STANDALONE_V --> MODIFY["수정 제출"]

    MODIFY --> REDIR2["redirect → /shop/?mode=view&board_pid=N#wc-shop-qna"]

    STANDALONE_V --> REPLY["답변 제출"]

    REPLY --> RELOAD["moveURL(reload) → 현재 view 유지"]

    HOME --> LIST["Q&A 목록 (#wc-shop-qna 앵커)"]

    LIST --> CLICK["글 클릭 → mode=view (standalone)"]

    style STANDALONE_W fill:#E3F2FD

    style STANDALONE_V fill:#E3F2FD

    style HOME fill:#FFF9C4

```

### # 핵심 라우팅 조건

```php

// page-shop.php 상단

$is_qna_form_view = ($vid == 0) && in_array($qna_mode, array('write', 'view'));

// true → standalone 페이지 (.wc-qna-standalone)

// false → 쇼핑몰 홈 또는 제품 상세

```

### # 폼 제출 후 리다이렉트

| 액션 | 제출 후 이동 |

|------|-------------|

| 글쓰기 (write) | `GET /shop/?wc_action=latest_qna_pid` → `/shop/?mode=view&board_pid=N#wc-shop-qna` |

| 수정 (modify) | `/shop/?mode=view&board_pid=N#wc-shop-qna` |

| 답변 (reply) | `moveURL("reload")` — 현재 view 페이지 새로고침 |

## # 7.5 코스피/환율 AJAX 엔드포인트

```mermaid

flowchart TD

    PAGE["홈/쇼핑몰 페이지 로드"] --> AJAX["WP AJAX 요청"]

    AJAX --> ENDPOINT{"엔드포인트"}

    ENDPOINT -->|"wc_kospi"| KOSPI["get_transient('wc_kospi')"]

    ENDPOINT -->|"wc_rates"| RATES["get_transient('wc_exchange_rates')"]

    KOSPI --> JSON["wp_send_json() 반환"]

    RATES --> JSON

    JSON --> RENDER["클라이언트에서 위젯 렌더링"]

    style KOSPI fill:#C8E6C9

    style RATES fill:#C8E6C9

```

- `functions.php`에 `wp_ajax_wc_kospi` / `wp_ajax_nopriv_wc_kospi` 훅 등록

- `functions.php`에 `wp_ajax_wc_rates` / `wp_ajax_nopriv_wc_rates` 훅 등록

- 캐시 TTL: 장중 5분, 장전 30분, 장후 2시간 (transient)

## # 7.6 소셜 로그인 + 배송지 정보 흐름

```mermaid

flowchart TD

    SOCIAL["소셜 로그인 (Naver/Kakao/Google)"] --> NEW{"신규 사용자?"}

    NEW -->|"예"| REDIRECT["배송지 정보 입력 페이지로 이동"]

    NEW -->|"아니오"| HOME["홈으로 이동"]

    REDIRECT --> FORM["연락처 + 배송 주소 폼"]

    FORM --> SAVE2["mb_users에 저장"]

    SAVE2 --> COOKIE["쿠키 삭제 + 홈으로 이동"]

    SOCIAL2["카카오 소셜 로그인"] --> SCOPE["phone_number + shipping_address scope"]

    SCOPE --> AUTO["카카오에서 연락처/배송지 자동 수신"]

    AUTO --> UPDATE["mb_users 자동 업데이트"]

    UPDATE --> HOME

    style REDIRECT fill:#FFF9C4

    style AUTO fill:#C8E6C9

```

---

# # 8. 보안 체크리스트

## # 8.1 서버 보안

| 항목 | 설명 |

|------|------|

| wp-login.php 브루트포스 방어 | GET 요청 시 필수 파라미터 없으면 홈으로 리다이렉트 |

| xmlrpc.php 차단 | GET 요청 시 404 반환 |

| Caddy debug 모드 제거 | 정보 노출 방지 |

| Portainer IP 제한 | 사설 IP만 접근 가능 |

| WP_DEBUG | 운영 환경에서 `false` 설정 |

| PHP 업로드 제한 | `upload_max_filesize=10M`, `post_max_size=10M` |

## # 8.2 망보드 보안

| 항목 | 설명 |

|------|------|

| WP 관리자/프론트엔드 분리 | wp-admin에서는 MB 쿠키 무시, 프론트엔드에서 WP 세션 유지 |

| 소셜 로그인 레벨 버그 방지 | 소셜 사용자가 level=10으로 설정되지 않도록 가드 |

| 비회원 답변 차단 | `reply_level=1`로 로그인 사용자만 답변 가능 |

| 정보문서 수정 권한 | MB 유저 레벨 >= 10만 수정 가능 |

---

# # 9. 변경 이력

## # 2026-05-15 — 서버 리소스 정리 + 실시간 통신

| 변경 | 내용 |

|------|------|

| **Supabase 제거** | 12개 컨테이너 전체 삭제 |

| **Plausible 제거** | 3개 컨테이너 전체 삭제 |

| **Umami 설치** | PostgreSQL 16 + Umami v3.1.0 (stats.wellcoms.co.kr) |

| **Socket.io 서버** | Express + Socket.io, pm2, 포트 3002 (socket.wellcoms.co.kr) |

| **쿵쿵따 Socket.io 전환** | 방 목록/상태/채팅/온라인 실시간 업데이트 (/kkung namespace) |

| **타자 Socket.io 전환** | 채팅/온라인 실시간 업데이트 (/taja namespace) |

| **PHPUnserialize 수정** | Buffer 기반 바이트 오프셋 (한국어 멀티바이트) |

| **나가기 예약 기능** | 게임 중 나가기 차단, 나가기 예약 토글, 프로필 배지 |

| **GitLab 리포 정리** | 플러그인별 독립 리포 (wp-wellcoms-kkung, wp-wellcoms-taja) |

| **추적 스크립트 교체** | Plausible → Umami (wellcoms + maxign) |

## # 2026-05-07 — UI/UX 전면 개선 + 쇼핑몰 Q&A 게시판

| 변경 | 내용 |

|------|------|

| **쇼핑몰 상담 게시판** | `page-shop.php`에 Q&A 섹션 추가 — standalone 라우팅 (write/view 분리) |

| **Q&A 폼 리다이렉트** | `sendBoardWriteDataHandler` 오버라이드 — write→최신글 view, modify→view, reply→reload |

| **AJAX 엔드포인트** | `/shop/?wc_action=latest_qna_pid` — 글쓰기 후 최신 PID 조회 |

| **코스피/환율 AJAX** | `functions.php`에 `wp_ajax_wc_kospi`, `wp_ajax_wc_rates` 추가 (transient 캐시) |

| **코스피 캐시 TTL** | 장중 5분, 장전 30분, 장후 2시간 |

| **Pretendard 폰트 통일** | 전체 페이지 기본 폰트 Pretendard 적용 |

| **히어로 CTA 버튼 통일** | frosted glass 스타일 (수리 페이지 포함) |

| **카테고리 배지** | MangBoard 코어 `[카테고리]` 괄호 제거 + CSS 배지 스타일링 |

| **홈 섹션 여백 축소** | `--wc-section-padding` 80→56px(PC), 60→44px(태블릿), 48→36px(모바일) |

| **홈 꿀팁/공지** | 심플 리스트 + 글머리 기호 + 카테고리 배지, LIMIT 6 |

| **"모든 상품 보기" 이동** | 하단 → 인기제품 섹션 헤더 우측 배치 |

| **쇼핑몰 여백 축소** | padding/margin 축소, 헤더/제목 크기 조정 |

| **푸터 개선** | "오시는 길" 링크 추가, "Powered by WELLCOMS" 제거 |

| **모바일 페이지 네비** | footer.php에 ← → 고정 버튼 (모바일 only) |

| **오시는 길** | 모바일 지도 높이 220px + 네이버/카카오맵 검색 버튼 |

| **마크다운 코드블록** | `renderCodeBlock()` 앞뒤 빈줄 자동 제거 |

| **빌트인 아이콘** | `functions.php`에 `hometax` SVG 아이콘 추가 |