2.2. 코딩가이드

2.2. 코딩가이드

---

2.2.1 프로젝트 개요

항목	내용
프로젝트명	SP100주년 기념 뮤지엄 사이트
URL	https://spsamhwa.com/museum/ (운영) / https://samhwa.sknkwoxs.com/museum/ (개발)
플랫폼	WordPress Multisite (blog_id=3)
테마	sknk_80 (sknk 차일드 테마)
템플릿 엔진	Timber/Twig
MIS 연동	없음

---

2.2.2 기술 스택

A. Backend

• CMS: WordPress 6.x
• PHP: 8.1+
• 템플릿: Timber 2.x + Twig
• 플러그인: ACF Pro, Yoast SEO, WP Batch Processing

B. Frontend

• CSS: Custom CSS + Tailwind 유틸리티
• JavaScript: Vanilla JS + GSAP (애니메이션)
• 스크롤: Lenis (스무스 스크롤)

C. 개발 환경

• 로컬: DDEV (Docker 기반)
• 버전관리: Git
• 배포: Git Push → Production Pull

---

2.2.3 디렉토리 구조

web/app/themes/sknk_80/
├── style.css              # 테마 메타 (Template: sknk)
├── functions.php          # 테마 초기화, inc/ 로드
├── home.php               # 메인 페이지 컨트롤러
├── page-*.php             # 페이지 템플릿 컨트롤러 (9개)
├── single-*.php           # CPT 상세 템플릿 (2개)
├── 404.php                # 404 페이지
├── inc/                   # PHP 모듈
│   ├── register.php       # 스크립트/스타일 등록
│   ├── ajax.php           # AJAX 엔드포인트
│   ├── event-cpt.php      # Custom Post Type 정의
│   ├── event-comments.php # 이벤트 댓글 시스템
│   └── event-comments-admin.php  # 댓글 관리자 기능
├── twigs/                 # Twig 템플릿 (16개)
│   ├── home.twig
│   ├── 80-years.twig
│   ├── partials/          # 공통 파셜
│   │   ├── anniversary-header.twig
│   │   ├── anniversary-footer.twig
│   │   └── mega-menu.twig
│   └── ...
└── src/                   # 프론트엔드 소스
    ├── css/               # 스타일시트
    ├── js/                # JavaScript 모듈 (15개+)
    ├── images/            # 이미지 에셋
    ├── videos/            # 비디오 에셋
    └── fonts/             # 웹폰트 (Pretendard, Google Sans)

---

2.2.4 코딩 컨벤션

A. PHP

<?php
// PSR-12 스타일 준수
// 클래스명: PascalCase
// 함수명: snake_case (WordPress 컨벤션)
// 변수명: $snake_case

// 예시: 페이지 템플릿
$context = Timber::context();
$context['post'] = Timber::get_post();
$context['custom_data'] = get_field('custom_field');

Timber::render('template-name.twig', $context);

B. Twig

{# 컴포넌트 기반 구조 #}
{% include 'partials/anniversary-header.twig' %}

{# 조건부 렌더링 #}
{% if post.custom_field %}
    <div class="content">{{ post.custom_field }}</div>
{% endif %}

{# 반복문 #}
{% for item in items %}
    <article class="item">{{ item.title }}</article>
{% endfor %}

C. JavaScript

// ES6+ 문법 사용
// 모듈 패턴 권장
// GSAP은 전역으로 로드됨

// 예시: 애니메이션 초기화
document.addEventListener('DOMContentLoaded', () => {
    gsap.registerPlugin(ScrollTrigger);

    gsap.from('.hero-title', {
        opacity: 0,
        y: 50,
        duration: 1,
        ease: 'power3.out'
    });
});

D. CSS

/* BEM 네이밍 권장 */
.section-hero { }
.section-hero__title { }
.section-hero__title--large { }

/* 반응형 브레이크포인트 */
/* Mobile: < 768px */
/* Tablet: 768px ~ 1024px */
/* Desktop: > 1024px */

---

2.2.5 Git 브랜치 전략

main (운영)
  └── develop (개발 통합)
        └── features/80th-anniversary (SP100주년 개발)
              └── features/output (산출물)

A. 커밋 메시지 규칙

feat: 새 기능 추가
fix: 버그 수정
style: 스타일/포맷팅 변경
refactor: 코드 리팩토링
docs: 문서 수정
chore: 빌드/설정 변경

B. 브랜치 운영

1. features/* 브랜치에서 개발
2. PR 생성 → develop 머지
3. 테스트 완료 후 main 머지
4. 운영 서버에서 git pull

---

2.2.6 로컬 개발 환경 설정

Git 저장소 정보

항목	내용
저장소 URL	https://github.com/sknkwoxs/samhwa/
접근 권한	승인된 GitHub 계정만 접근 가능

필수: 프로젝트 클론을 위해 승인된 GitHub 계정이 필요합니다.

A. DDEV 설치 및 실행

# 프로젝트 클론 (승인된 GitHub 계정 필요)
git clone https://github.com/sknkwoxs/samhwa/ samhwa
cd samhwa

# DDEV 시작
ddev start

# Composer 의존성 설치
ddev composer install

# DB 스냅샷 복원
ddev snapshot restore --latest

# 사이트 접속
open https://samhwa.sknkwoxs.com/museum/

B. 테마 활성화 확인

# 뮤지엄 사이트 테마 확인
ddev wp --url=samhwa.sknkwoxs.com/museum theme list

# 테마 활성화 (필요시)
ddev wp --url=samhwa.sknkwoxs.com/museum theme activate sknk_80

---

2.2.7 배포 절차

A. 개발 → 스테이징

# 변경사항 커밋
git add .
git commit -m "feat: 기능 설명"

# develop 브랜치로 머지
git checkout develop
git merge features/80th-anniversary
git push origin develop

B. 스테이징 → 운영

운영 서버는 SM2네트웍스가 관리하는 SSH 웹서버입니다. 배포는 SM2네트웍스로부터 발급받은 SSH 계정으로 운영 웹서버에 접속하여 진행합니다.

# 1. SM2네트웍스 운영 웹서버 SSH 접속
ssh <발급받은-계정>@<운영-웹서버-호스트>

# 2. 운영 사이트 디렉터리로 이동
cd <운영-사이트-경로>

# 3. main(또는 운영) 브랜치 최신화
git fetch origin
git checkout main
git pull origin main

# 4. 의존성 설치 및 캐시 정리(필요 시)
composer install --no-dev --optimize-autoloader
wp cache flush

SSH 접속 정보(호스트·계정·키)는 SM2네트웍스로부터 별도 전달받아 사용하며, 외부 공유 및 저장소 커밋을 금지합니다.

---

2.2.8 주의사항

A. blog_id 관련

// 뮤지엄 사이트 체크
if (get_current_blog_id() === 3) {
    // 뮤지엄 전용 로직
}

// MIS 연동은 blog_id=3에서 제외됨
// sknk/inc/register.php의 배치 분기 참조

B. 차일드 테마 구조

• sknk_80은 sknk의 차일드 테마
• 부모 테마 기능 상속
• 오버라이드 시 동일 파일명으로 차일드에 생성

C. ACF 필드

• ACF 필드는 WordPress 관리자(DB)에서 관리
• 코드에서는 get_field(), update_field() 사용
• 필드 그룹 변경 시 관리자 화면에서 수정

---

2.2.9 문의

• 개발사: 스컹크웍스
• 담당자 이메일: developer@skunkworks.co.kr