운영 기능 및 GA4 대시보드 반영

docs/architecture.md

@@ -1,6 +1,6 @@
 # GTSIT 사이트 설계안
 
-최종 수정일: 2026-08-10
+최종 수정일: 2026-08-18
 
 ## 1. 구축 목표
 
@@ -132,9 +132,23 @@ public/
 - 개인정보 파기: 문의가 `closed`로 전환된 시각을 기록하고 1년이 지난 문의를 `bin/purge-inquiries.php`로 데이터베이스에서 완전 삭제
 - 파기 실행 환경: 현재 뉴아우토반 공유 웹호스팅은 cron을 지원하지 않아 정리 명령을 수동 실행할 수 있도록 배포했으며, 외부 스케줄러 또는 지원 상품 전환 시 정기 실행 등록 필요
 - 관리자: 서버 세션, 비밀번호 해시, 계정별 잠금, 세션 단위 시도 제한, 모든 하위 경로 인증 선행
+- 방문 통계: 무료 GA4 표준 속성으로 운영 공개 페이지만 측정하고 관리자·테스트 경로 제외, Analytics Data API는 서버의 읽기 전용 서비스 계정과 15분 캐시를 통해 관리자 대시보드에 집계값만 제공
+- 통계 개인정보 경계: 문의 이름·연락처·이메일·본문과 관리자 식별정보는 GA4 이벤트에 포함하지 않고, 통계 쿠키 동의 전에는 Analytics 저장을 비활성화
+- GA4 식별자: 계정 `(주)지티에스정보통신`, 속성 ID `549573245`, 운영 웹 스트림 ID `15422491033`, 측정 ID `G-92XBR314YD`
+- 통계 동의 흐름: 최초 선택 전 Google 태그 미로딩, 허용 시 운영 호스트에서만 측정, 거부·철회 시 Analytics 저장 거부와 회사 도메인 `_ga` 쿠키 삭제 시도, 광고 저장·Google 신호·광고 개인화는 항상 비활성화
+- 관리자 통계: Google Cloud 프로젝트 `gtsit-ga4-dashboard-20260812`의 전용 서비스 계정에 GA4 속성 `뷰어` 권한만 부여하고, 서버에서 Analytics Data API를 조회해 15분간 비공개 파일 캐시
+- GA4 키 보관: JSON 개인키는 Git과 웹 루트 밖의 앱 `.secrets/`에 권한 `600`으로 보관하며 브라우저 HTML·JavaScript·로그에 포함하지 않음
+- 통계 장애 대응: API 오류 시 마지막 정상 캐시를 표시하고, 캐시도 없을 때는 관리자 화면에 일반 안내만 표시해 자격 증명·API 오류 세부 정보 비노출
+- 전체 방문자 기준: GA4 측정 시작일 `2026-08-12`부터 오늘까지의 `totalUsers`를 표시하며 이전 방문 기록은 포함하지 않음
 - 초기 관리자: 24시간 유효한 토큰을 세션으로 교환한 뒤 비밀번호를 직접 설정하며, 생성 즉시 토큰 파일 삭제
-- 게시글: slug, 분류, 초안·공개 상태, 소프트 삭제 기반
+- 게시글: 신규·기존 slug는 DB 게시글 번호 기반 `post-{id}` 자동 생성, 종전 slug는 정적 별칭을 통한 301 이동, 분류, 초안·공개 상태, 소프트 삭제 기반
 - 대표 이미지: JPG·PNG·WebP, 8MB, 6000px 제한, MIME 재검증, 임의 파일명, 대체 텍스트 적용
+- 게시글 미디어 실험: 테스트 경로에서 대표 이미지 최대 6장 슬라이드와 본문 이미지 최대 10장을 지원하고, 본문은 독립 줄의 `[[image:번호]]` 토큰 위치에 안전하게 렌더링
+- 관리자 본문 편집: 범용 HTML 에디터 대신 textarea 문단과 이미지 카드만 제공하는 전용 블록 UI 사용, 위·아래 이동과 삭제 후 기존 텍스트·토큰 형식으로 직렬화
+- 작성 화면 미리보기: 저장 전 폼 상태와 선택 파일의 브라우저 임시 URL을 모달에 안전한 DOM API로 렌더링하며, 미리보기 조작은 서버 요청이나 DB 저장을 발생시키지 않음
+- 본문 보안 경계: 임의 HTML·`contenteditable`·`innerHTML`을 사용하지 않고 텍스트는 기존 출력 이스케이프, 이미지는 서버 검증 파일과 DB 연결 정보만 렌더링
+- 운영 호환성: 공유 DB 스키마 변경 없이 `post_images.caption`의 `@gtsit:gallery`, `@gtsit:inline:번호` 내부 표식과 정렬순서를 사용하며, 운영 코드가 항상 첫 대표 이미지를 선택하도록 유지
+- 실험 공개 제한: 다중 대표 이미지 또는 본문 이미지가 포함된 게시글은 운영 반영 승인 전까지 초안으로만 저장
 - 이미지 없는 게시글 카드: 글을 숨기지 않고 `GTS` 로고와 카테고리 색상을 사용한 16:9 브랜드 플레이스홀더 표시, 대표 이미지 등록 시 실제 이미지 우선
 - 회사 정보: 관리자 화면에서 연락처·주소·사업자 정보를 DB 설정값으로 관리
 - 오시는 길: NAVER Cloud Dynamic Map으로 주소 기반 지도와 회사 마커 표시, API 오류 시 네이버 지도 검색 링크 제공