gtsit/docs/architecture.md

GTSIT 사이트 설계안

최종 수정일: 2026-08-10

1. 구축 목표

• 회사와 서비스를 명확히 소개하는 반응형 웹사이트 구축
• 게시글과 문의를 운영자가 관리할 수 있는 관리자 기능 제공
• Cafe24 웹호스팅의 PHP 및 MariaDB 환경에 맞춘 단순하고 유지보수 가능한 구성
• 비밀번호와 문의 내용 등 민감정보를 브라우저 저장소가 아닌 서버에서 안전하게 처리

2. 확인된 운영 환경

항목	확인 내용	후속 작업
호스팅 계정	gts0201	인증 정보는 문서에 저장하지 않음
상품	뉴아우토반호스팅 일반형	현재 용량으로 초기 운영 가능
웹 환경	PHP 8.4	배포 전 필수 PHP 확장 확인
DB 환경	MariaDB 10.6.17, localhost:3306, 계정 gts0201	utf8mb4_unicode_ci, 스키마 생성 대기
서버 IP	112.175.85.162	DNS 생성 후 실제 응답과 대조
기본 도메인	gts0201.mycafe24.com	연결 도메인으로 유지, 운영 노출 정책 결정 대기
대표 도메인	gtsit.co.kr	2026-08-04 Cafe24 대표 도메인 변경 완료
대표 이메일	gts0201@naver.com	공개 화면 및 문의 안내에 사용
회사 주소	서울시 송파구 정의로7길 13, B동 오피스 1020호	공개 화면 사업자 정보에 사용
네임서버	Cafe24 네임서버 위임 확인	호스팅 연결 후 DNS 레코드 생성 확인
현재 DNS	루트·www가 112.175.85.162로 연결, 공개 DNS 전파 중	Cloudflare DNS 전파 재확인
SSL	Let’s Encrypt 적용, 루트·www 포함	자동 갱신 상태 지속 확인
웹 방화벽	ModSecurity 사용	적용 후 기능 오탐 점검
UploadGuard	사용	파일 업로드 기능과 호환성 점검
SSH/SFTP	RSA 4096 인증키, 만료일 2026-09-03	새 다운로드 키로 접속 성공
서버 홈·웹 루트	/home/hosting_users/gts0201, www	임시 페이지 배포 완료
PHP 안티웹쉘	미사용	본 사이트 배포 전 활성화 검토
외부 MySQL 접속	차단	서버 내부 PHP에서만 DB 사용 권장

3. 페이지 구조

공개 페이지

경로	역할	주요 구성
/	홈	회사 소개, 핵심 서비스, 최신 게시글, 문의 유도
/blog	게시글 목록	검색 또는 분류, 목록, 페이지네이션
/blog/{slug}	게시글 상세	제목, 본문, 이미지, 작성일, 이전·다음 글
/contact	문의 접수	작성자 정보, 문의 내용, 개인정보 동의
/inquiry/lookup	문의 확인	접수번호와 숫자 4자리 조회 PIN을 통한 본인 확인

관리자 페이지

경로	역할	주요 구성
/admin/login	관리자 인증	서버 세션 기반 로그인
/admin	대시보드	게시글 및 문의 요약
/admin/posts	게시글 관리	목록, 상태 변경, 수정, 삭제
/admin/posts/new	게시글 작성	제목, 본문, 대표 이미지, 공개 상태
/admin/posts/{id}/edit	게시글 수정	기존 데이터 편집
/admin/inquiries	문의 관리	목록, 검색, 처리 상태
/admin/inquiries/{id}	문의 상세	내용 확인, 답변 메모, 상태 변경
/admin/company	회사 정보	연락처와 사이트 공통 정보 관리

4. 권장 기술 구성

• 서버: PHP 8.4
• 데이터베이스: MariaDB 10.6.17, PDO MySQL과 prepared statement 사용
• 화면: 서버 렌더링 HTML, CSS, 필요한 범위의 경량 JavaScript
• 인증: PHP 세션, password_hash()와 password_verify() 사용
• URL: Apache rewrite 사용 가능 여부 확인 후 의미 있는 경로 적용
• 설정: DB 접속값을 공개 디렉터리 밖의 환경별 설정 파일로 분리

확인된 웹 PHP 환경은 PHP 8.4.21p1, UTF-8, Asia/Seoul, PDO MySQL, mysqli, mbstring, OpenSSL, fileinfo, 업로드 최대 100MB, 메모리 256MB입니다. DB 접속 설정은 서버 웹 루트 밖의 .gtsit-db.env에 권한 600으로 저장합니다.

Cafe24의 실제 웹 루트는 /home/hosting_users/gts0201/www로 확인했습니다. PHP 확장은 본 사이트 개발 단계에서 확정합니다. 아래 구조는 공유호스팅 권한 범위에 맞춰 조정합니다.

app/
  Controllers/
  Repositories/
  Views/
config/
database/
  schema.sql
docs/
public/
  assets/
  uploads/
  index.php
storage/
  logs/

초기 임시 배포는 현재의 public/index.html 단일 파일을 유지합니다. 본 사이트는 public/index.php 프런트 컨트롤러와 공통 PHP 뷰로 구현하며, 운영 전환 시 Apache가 index.php를 우선 사용합니다.

5. 데이터 모델 초안

테이블	목적	핵심 데이터
admins	관리자 계정	로그인 ID, 비밀번호 해시, 상태, 마지막 로그인
posts	게시글	제목, slug, 본문, 공개 상태, 작성·수정일
post_images	게시글 이미지	게시글 ID, 파일 경로, 대체 텍스트, 정렬값
inquiries	고객 문의	접수번호, 작성자, 연락처, 내용, 조회 PIN 해시, 처리 상태, 조회 실패·잠금, 종료일
site_settings	회사 및 공통 설정	설정 키, 값, 수정일

2026-08-04 초기 스키마를 MariaDB에 적용했습니다. admins, posts, post_images, inquiries, site_settings 5개 테이블은 모두 utf8mb4_unicode_ci를 사용합니다. 문의는 접수번호와 숫자 4자리 조회 PIN의 해시로 공개 답변을 조회합니다. 2026-08-05 접수번호별 조회 실패 횟수와 잠금 시각, 처리 종료일을 추가했으며 5회 실패 시 15분 동안 해당 접수번호의 조회를 제한합니다.

5-1. 현재 구현 구조

app/
  Auth/AdminAuth.php
  Repositories/
  Support/helpers.php
  Views/
bin/create-admin.php
config/
database/schema.sql
public/
  assets/css/
  assets/images/company-logo-v3.png
  assets/js/
  index.html
  index.php

• 공개 페이지: 서버 렌더링, 페이지별 title·description·canonical·Open Graph 적용
• 브랜드 로고: 투명 배경 GTS 워드마크 PNG를 이미지로 사용하고, 법인명은 정확한 표기와 접근성을 위해 HTML 텍스트로 분리
• 서비스 아이콘: 네트워크·키폰·CCTV·유지보수 항목에 대응하는 인라인 SVG를 고정 UI 자산으로 관리하며 관리자 입력 대상에서 제외
• 메인 비주얼: 기존 사이트 백업의 실제 시공 이미지 4장을 public/assets/images/field/에 1200×900 JPEG로 최적화해 5초 간격 자동 슬라이드로 표시
• 슬라이드 접근성: 이전·다음·직접 선택·일시정지 제공, 포인터·키보드 조작 중 자동 전환 정지, prefers-reduced-motion 환경 자동재생 중지
• 이전 콘텐츠 이관: LAN·옥외 무선·키폰·CCTV·통신 랙 관리 5개 주제를 현재 표현으로 재구성하고 database/seed-legacy-content.sql로 멱등 반영
• 문의: 이메일은 아이디와 주요 도메인을 조합하고 직접입력에서만 전체 주소 작성, 연락처는 단일 필드에서 휴대전화·서울·기타 지역번호·대표번호·인터넷전화·안심번호 형식으로 자동 변환
• 문의 보안: 서버 필수값 검증, CSRF, 20초 중복 방지, 숫자 4자리 조회 PIN 해시, 세션 및 접수번호별 조회 실패 제한
• 개인정보: 2026 개인정보보호위원회 작성지침을 기준으로 처리 목적·항목·법적 근거·보유기간·제3자 제공·위탁·파기·권리 행사·안전조치·세션 쿠키·담당부서·시행일을 공개
• 개인정보 파기: 문의가 closed로 전환된 시각을 기록하고 1년이 지난 문의를 bin/purge-inquiries.php로 데이터베이스에서 완전 삭제
• 파기 실행 환경: 현재 뉴아우토반 공유 웹호스팅은 cron을 지원하지 않아 정리 명령을 수동 실행할 수 있도록 배포했으며, 외부 스케줄러 또는 지원 상품 전환 시 정기 실행 등록 필요
• 관리자: 서버 세션, 비밀번호 해시, 계정별 잠금, 세션 단위 시도 제한, 모든 하위 경로 인증 선행
• 초기 관리자: 24시간 유효한 토큰을 세션으로 교환한 뒤 비밀번호를 직접 설정하며, 생성 즉시 토큰 파일 삭제
• 게시글: slug, 분류, 초안·공개 상태, 소프트 삭제 기반
• 대표 이미지: JPG·PNG·WebP, 8MB, 6000px 제한, MIME 재검증, 임의 파일명, 대체 텍스트 적용
• 이미지 없는 게시글 카드: 글을 숨기지 않고 GTS 로고와 카테고리 색상을 사용한 16:9 브랜드 플레이스홀더 표시, 대표 이미지 등록 시 실제 이미지 우선
• 회사 정보: 관리자 화면에서 연락처·주소·사업자 정보를 DB 설정값으로 관리
• 오시는 길: NAVER Cloud Dynamic Map으로 주소 기반 지도와 회사 마커 표시, API 오류 시 네이버 지도 검색 링크 제공
• 운영 사이트: https://gtsit.co.kr에서 본 사이트 공개, 애플리케이션은 웹 루트 밖의 gtsit-app-20260810에 배치
• 이전 테스트 경로: /site-preview-7c2a91f4, 운영 전환 후 비교·복구용으로 유지하며 검색엔진 색인 차단

6. 디자인 구현 전 수정 원칙

• 19개 HTML 시안의 공통 헤더, 푸터, 내비게이션을 공통 뷰로 통합
• 게시글 상세 페이지를 개별 정적 파일이 아닌 하나의 동적 템플릿으로 통합
• 공개 화면의 모바일 헤더 가로 넘침 수정
• 관리자 게시글 목록의 모바일 조작 영역 잘림 수정
• localStorage 기반 게시글과 문의 데이터를 MariaDB로 이전
• 클라이언트 코드에 포함된 관리자 인증값 제거
• 문의 등록 시 접수번호와 조회 PIN 해시를 서버에 저장하고 접수번호별 시도 제한을 적용한 조회 절차 구현
• 업로드 파일의 확장자, MIME, 용량, 저장 파일명을 서버에서 검증

7. 보안 원칙

• 모든 운영 페이지 HTTPS 강제
• 관리자 로그인 시도 제한과 세션 쿠키 보안 옵션 적용
• CSRF 토큰, 출력 이스케이프, SQL 파라미터 바인딩 적용
• 비밀번호와 개인키를 저장소, 로그, HTML, JavaScript에 포함하지 않음
• 업로드 디렉터리에서 PHP 실행 차단
• 관리자 경로에 검색엔진 차단 및 필요 시 추가 접근 제한 적용
• Cafe24 일일 백업과 별도의 외부 백업 병행

8. 배포 순서

1. SSH/SFTP 개인키 준비 및 서버 접속 확인
2. 기존 웹 루트 파일 확인 및 백업
3. 임시 index.html 업로드
4. gts0201.mycafe24.com에서 응답 및 모바일 화면 확인
5. 확정한 사용자 도메인을 호스팅에 연결
6. 루트 도메인과 www DNS 응답 확인
7. 무료 SSL 신청, 발급, HTTPS 리디렉션 확인
8. MariaDB 접속 확인 및 최소 권한 구성
9. 본 사이트 스키마와 애플리케이션 배포
10. 보안, 백업, 알림, 최종 회귀 QA

2026-08-10 운영 루트를 본 사이트로 전환했습니다. 웹 루트에는 공개 에셋·업로드 디렉터리·운영 진입 파일만 두고, PHP 애플리케이션은 웹 루트 밖에 배치합니다. 이전 테스트 경로는 비교·복구용으로 유지하며 경로 접두사와 검색엔진 차단 설정을 유지합니다.

9. 미확정 의사결정

현재 대표 주소는 https://gtsit.co.kr입니다. Cafe24 대표 도메인도 gtsit.co.kr로 변경했으며, HTTP와 www 요청은 public/.htaccess에서 대표 주소로 301 리디렉션합니다. 2026-08-04 확인한 Let’s Encrypt 인증서는 루트와 www를 포함하며 2026-11-02까지 유효합니다.

• 회사 대표 메일을 Cafe24 메일로 사용할지 외부 메일 서비스를 사용할지 결정
• 관리자 계정 수와 권한 구분 필요 여부 확정
• 게시글 분류, 검색, 임시저장, 예약발행 필요 여부 확정

10. 네이버 지도 연동

• NAVER Cloud Platform의 Maps Application에서 Dynamic Map 선택
• Web 서비스 URL은 공식 형식에 맞춰 http://gtsit.co.kr 등록(HTTP·HTTPS 구분 없음, www 제외)
• 브라우저 지도 로더에는 Client ID를 ncpKeyId로 사용
• Client Secret은 프런트엔드, 저장소, HTML에 포함하지 않음
• 고정 회사 위치는 확인된 위도 37.48524, 경도 127.11478을 사용해 Dynamic Map만 호출하고, 별도 Geocoding 상품과 일일 주소 변환 호출은 사용하지 않음
• 주소 표시는 서울시 송파구 정의로7길 13, B동 오피스 1020호, 네이버 지도 검색은 건물 주소를 기준으로 연결
• 지도 SDK가 컨테이너 위치 속성을 덮어써도 높이가 유지되도록 지도 요소에 height: 100% 적용
• NAVER 기본 컨트롤에 전체화면이 없으므로 Fullscreen API 기반 사용자 정의 아이콘을 지도 안에 제공하고, 미지원 환경에서는 네이버 지도 새 창 열기로 대체
• 정상 지도 상태에서는 별도 텍스트 링크를 숨기고, API 로드 실패 또는 JavaScript 비활성 환경에서만 주소가 지정된 네이버 지도 링크 제공