BP미디어

기본 원칙

변경은 안정성 우선이며, 버전은 `Va.bbb.cc` 규칙을 따릅니다. `A`는 오너가 판단하는 제품 단계로, 현재처럼 `0`이면 아직 완전판 전 단계라는 뜻이며 버전 기록에서는 `Super Nova` 계층으로 다룹니다. `bbb`는 주요 기능 변화나 구조 개편이 있을 때 올리는 `Update` 계층이고, `cc`는 `Hotfix` 또는 `Bugfix` 성격의 수정일 때만 올립니다. `bbb`가 증가하면 `cc`는 `00`으로 초기화합니다. 기본 운영 원칙은 preview 검수 후 production 퍼블리싱이지만, 오너가 명시적으로 요청한 관리자 페이지 긴급 개편은 예외적으로 바로 production에 반영할 수 있습니다.

작업 환경

저장소 경로는 `/Users/jimmy/gilwell-media`이며, Cloudflare Pages + Functions + D1 + R2 구조입니다. preview 배포는 `./scripts/deploy_preview.sh` 또는 `./scripts/deploy_pages.sh`, production 배포는 `./scripts/deploy_production.sh`로만 진행합니다.

중요 URL

관리자: `/admin.html` · 용어집: `/glossary.html` · 게시글: `/post/:id` · 사이트맵: `/sitemap.xml` · 로봇: `/robots.txt`

사이트 구조

공개 표면은 홈, 4개 카테고리 보드(Korea/APR/WOSM/Scout People), 기사 상세, 검색, 용어집, 도움 페이지로 구성됩니다. 관리자 페이지는 운영 개요, 콘텐츠, 사이트 설정 세 축으로 나뉩니다.

홈 구성

홈은 상단 마스트헤드, 티커, 히어로, 메인 스토리, 최신 소식, 인기 소식, 에디터 추천, 4개 카테고리 보드, 푸터 통계로 구성됩니다. 섹션 헤더 높이와 더보기 규칙은 전체 홈에서 일관되게 유지합니다.

홈 최신 갱신 규칙

홈 `최신 소식`은 첫 진입 때 항상 새 데이터를 다시 불러오고, 브라우저 탭 복귀, 페이지 복귀, 포커스 복귀 때도 재조회합니다. 강력 새로고침 없이도 최근 게시글이 반영되는 구조를 유지하고, 최소한 latest rail은 no-store 기준으로 갱신합니다.

공유 메타

일반 페이지 공유 메타는 `functions/[[path]].js`에서 주입되고, 대표 이미지는 `site_meta.image_url` 또는 기본 이미지로 설정됩니다.

관리자 제한

일부 관리자 계정은 히어로 설정만 접근 가능하며 게시글 작성/삭제 권한은 제한됩니다. 이 정책을 항상 유지합니다.

데이터 변경

설정 값 수정 시 `settings_history`에 스냅샷을 남기며, 충돌 가능성이 있으면 최신 데이터를 재로드하도록 처리합니다.

날짜 규칙

게시글 데이터는 `created_at`(실제 생성 시각)과 `publish_at`(실제 공개 시각)을 분리해 보관합니다. 공개 화면의 정렬 기준은 기본적으로 `publish_at` 우선이며, `publish_at`이 없는 기존 글만 `created_at`을 fallback으로 사용합니다.

사용자에게 보이는 날짜는 공개 페이지 어디서든 `YYYY년 M월 D일`까지만 보여주고, 관리자에서는 Created / Published / Modified를 `YYYY년 MM월 DD일 HH시 MM분 SS초` 형식으로 모두 노출합니다.

디자인 서체 규칙

이 사이트의 기본 서체는 전역적으로 `AliceDigitalLearning` 하나만 씁니다. 공개 페이지, 관리자 페이지, 버튼, 메타, 검색, 시스템 안내까지 모두 같은 서체 규칙을 유지하고, 예전 대체 서체 흔적이 남아 있으면 모두 제거합니다.

타이포 스케일 규칙

일반 홈페이지의 상단 메뉴 크기와 카드 제목 크기를 공통 기준으로 삼고, 관리자 페이지도 그 스케일을 따라갑니다. 관리자라고 별도 서체나 과한 크기를 쓰지 않고, 공통 토큰으로 같은 리듬을 유지합니다.

버튼 규칙

`소식 읽기`, `공유하기`, `RSS 구독`, `사이트 검색`처럼 같은 레벨의 행동 버튼은 높이, 패딩, 폰트, 자간, 테두리 굵기를 통일합니다. 버튼 높이는 primary / secondary 단계로 구조화하고, 같은 기능 계층에서는 같은 높이를 유지합니다. primary / secondary 차이는 색과 채움 정도로만 구분하고, 버튼 모양과 크기는 유지합니다.

푸터 편집 규칙

푸터 좌측 문구는 raw HTML을 직접 수정하는 방식보다 구조화된 필드 편집기를 우선합니다. 제목, 소개 문구, 도메인, 기사제보 메일, 문의 메일을 각각 수정하고, public footer에서는 링크 줄바꿈과 줄간격이 과하게 벌어지지 않도록 촘촘한 타이포를 유지합니다.

공유 버튼 배치 규칙

홈 카드의 `공유하기`는 날짜 아래에, 기사 상세의 `공유하기`와 `수정하기`는 태그 라벨 줄 바로 아래의 같은 줄에 둡니다. 기사 상세 액션 버튼은 태그 칩과 같은 높이와 밀도를 쓰고, 태그 줄과 버튼 줄 사이에는 최소 5px 이상의 숨 쉴 여백을 둡니다.

더보기 규칙

홈 메인 내 `더보기` 링크는 모든 섹션에서 같은 서체, 같은 크기, 같은 정렬 규칙을 써야 합니다. `최신 소식`에 맞춘 스타일이 기준이며, 다른 섹션이 별도 폰트나 별도 분위기로 보이면 안 됩니다.

모바일 레이아웃 규칙

관리자 화면을 포함해 모바일에서는 가로 스크롤을 허용하지 않습니다. 다만 `1단 흐름`은 화면 전체 구조를 뜻하지, 모든 항목을 한 줄에 하나씩만 세운다는 뜻은 아닙니다. 통계, 빠른 액션, 탭, 메타 카드처럼 성격이 같은 정보는 카드 내부나 섹션 내부에서 2열/2줄로 묶어 밀도를 확보하고, 전체 페이지 흐름만 위에서 아래로 유지합니다.

한글 줄바꿈 규칙

한글 본문과 제목은 가능하면 단어 단위로 줄바꿈되게 유지합니다. 기본 규칙은 `word-break: keep-all`이며, 필요한 경우에만 `overflow-wrap`으로 긴 텍스트를 보조합니다.

관리자 정보 표시 규칙

관리자에서 Created / Published / Modified처럼 운영 판단에 중요한 메타는 숨기지 말고 `YYYY년 MM월 DD일 HH시 MM분 SS초` 형식으로 모두 노출합니다. 다만 메타는 제목보다 작고 얕게 보여야 하며, 제목이 첫 시선의 중심이 되도록 위계를 유지합니다.

관리자 타이포 규칙

관리자 페이지는 화면마다 제각각 크기를 쓰지 않고 공통 스케일을 유지합니다. 패널 제목, 본문, 도움문구, 입력창, 버튼, 탭, 목록 메타는 각각 정해진 단계 안에서만 움직이고, 인라인 스타일로 뒤엉키면 마지막 공통 레이어에서 다시 통일합니다.

관리자 구조 규칙

관리자 화면은 이제 뷰포트와 무관하게 `모바일 단일 폭 · 1단 흐름`을 기본으로 합니다. 데스크톱에서도 모바일 최적화된 폭과 간격을 그대로 사용하고, 좌우 2단 레이아웃은 두지 않습니다. 대신 한 카드 안에서는 2열 통계, 2열 액션, 2줄 탭처럼 정보를 압축 배치해 세로 길이를 줄이고 조작 효율을 높입니다.

관리자 리빌드는 부분 패치를 덧대는 대신, 공통 카드·툴바·입력·메타 칩·spacing 토큰을 중심으로 한 번에 재정리하는 방향을 기본 원칙으로 합니다. 상위 메뉴를 누르면 그 그룹의 하위 메뉴와 기본 본문이 함께 전환되는 구조를 유지하고, 선택되지 않은 상위 메뉴의 하위 메뉴는 화면에 보이지 않게 숨깁니다.

관리자 헤더 규칙

관리자 상단 액션은 흩어놓지 않고 하나의 카드 안에서 두 줄로 정리합니다. 첫 줄은 `홈페이지 보기 / 로그아웃`, 두 번째 줄은 `운영 개요 / 콘텐츠 / 사이트 설정`으로 고정하고, 글자 크기와 색상 리듬은 일반 홈페이지 상단 메뉴 가이드를 준용합니다. 로그아웃은 보이되 과장되지 않게, 홈페이지 보기와 같은 계열의 버튼 체계 안에서 식별돼야 합니다. 상위 메뉴와 하위 메뉴는 본문 카드와 구분되는 톤의 박스를 사용해 탐색 레이어임이 바로 드러나야 합니다.

관리자 Hover 규칙

관리자 페이지에서는 hover 상태가 텍스트 가독성을 해치면 안 됩니다. 버튼, 링크, 탭, 하위 메뉴, 카드 액션의 hover는 배경과 같은 색으로 글자가 사라지는 상태를 만들지 말고, hover 전보다 같은 색 또는 더 읽기 쉬운 색으로만 바뀌어야 합니다.

관리자 용어집 규칙

관리자 용어집은 긴 용어가 있어도 레이아웃이 깨지지 않아야 합니다. 분류 칸은 과하게 넓히지 않고, 한글 용어와 설명은 단어 단위 줄바꿈을 우선하며, 영문/불문 용어는 가능한 범위에서 hyphenation과 줄바꿈으로 겹침을 최소화합니다.

관리자 리디자인 규칙

관리자 페이지는 기능이 늘어나도 패널, 툴바, 카드, 메타 칩, 액션 버튼을 공통 컴포넌트로 재사용합니다. 목록 카드, 히어로/메인스토리 선택기, 번역 카드, 기여자 카드처럼 데이터 성격이 달라도 동일한 간격, 반경, 타이포 위계를 따라야 합니다.

헤더 밀도 규칙

홈의 메인 스토리, 최신 소식, 인기 소식, 에디터 추천, Korea/APR/WOSM/스카우트 인물 보드 제목 박스는 과하게 높지 않게 유지합니다. 관리자 최상단 헤더도 서브 메뉴 카드보다 커지지 않게 압축해, 정보보다 장식이 먼저 보이는 상태를 피합니다.

관리자 개요 규칙

운영 개요 상단 통계와 빠른 액션은 페이지 전체로는 1단 흐름을 유지하되, 카드 묶음 내부에서는 2열 또는 2줄 배치를 적극 활용합니다. 통계는 한 화면에서 빠르게 훑히는 밀도가 중요하고, 라벨은 숫자보다 조용해야 하며 숫자가 주인공이어야 합니다.

관리자 Preview 진입 규칙

관리자 상단 액션에는 `홈페이지 보기`, `프리뷰 보기`, `로그아웃`이 함께 있어야 하며, `프리뷰 보기`는 별도 개발자 페이지 없이도 현재 preview 공개 화면으로 가는 기본 진입점으로 유지합니다. 다만 production에 아직 반영되지 않은 기능적 변경이 없으면 이동하지 않고 `아직 추가 수정이나 개발된 사항이 없는 최신버전이에요.` 토스트만 띄웁니다.

분석 유입 규칙

관리자 분석의 `유입 경로`는 가능한 범위에서 카카오, 구글, 네이버 검색, 소셜, 외부 사이트처럼 식별 가능한 단위로 묶어 보여줍니다. 다만 홈페이지 내부 순환은 세부 페이지로 쪼개지 말고 `내부 이동` 하나로 통합합니다. referrer가 비어 있거나 앱 브라우저가 정보를 숨기면 `직접 방문`으로 남을 수 있습니다.

관리자 태그 규칙

글머리 태그는 설정 화면뿐 아니라 글 작성/수정 화면에서도 현재 카테고리 기준으로 바로 추가할 수 있어야 합니다. 다만 삭제는 해당 태그를 쓰는 글이 하나도 없을 때만 허용하고, 사용 중인 태그면 어떤 글 때문에 막히는지 안내한 뒤 먼저 그 글의 태그에서 제외하도록 유도합니다.

공개 글쓰기 태그 규칙

공개 페이지의 글쓰기/수정 모달도 관리자와 같은 수준으로 글머리 태그를 다뤄야 합니다. 게시판 글쓰기 모달과 기사 상세 수정 모달에서는 현재 카테고리에 새 태그를 추가하고 바로 선택할 수 있어야 하며, 권한 없는 계정이면 태그 추가를 막고 토스트로 안내합니다.

용어집 검색 규칙

용어집 검색은 기본적으로 `용어 + 설명`을 함께 검색하고, 체크박스로 범위를 좁힐 수 있어야 합니다. `용어`와 `설명`을 모두 해제한 채 검색을 시도하면, 검색을 막고 `검색 색인을 설정해달라고` 안내하는 토스트를 띄웁니다.

공개 기사 수정 규칙

공개 기사 상세의 수정은 관리자 페이지로 이동시키지 않고, 같은 페이지 안에서 모달로 처리합니다. `수정` 클릭 시 관리자 비밀번호를 요구하고, `full` 권한이 아닌 비밀번호나 잘못된 비밀번호면 토스트로 안내한 뒤 수정 모달을 열지 않습니다.

Preview 배포 규칙

기능 개발 후에는 `./scripts/deploy_preview.sh`로 preview 배포를 만들고, 그 URL에 대해 `./scripts/post_deploy_check.sh ` 검증과 수동 화면 확인을 먼저 진행합니다. 이 스크립트는 현재 HEAD를 `origin/preview`에도 동기화해, preview에서 본 코드와 GitHub의 preview 브랜치가 같은 커밋을 가리키게 유지해야 합니다. 오너 확인 전에는 production 배포를 하지 않습니다. 단, 관리자 페이지 UI만 수정되거나 관리자/API 계열만 수정되는 경우는 preview 없이 바로 production에 반영하는 운영 예외를 기본 규칙으로 둡니다.

Preview 최종 확인 규칙

preview 검수리스트의 `본 페이지에 반영하기`와 복구 계열 동작은, 현재 브라우저가 이미 관리자 로그인 상태여도 full 관리자 비밀번호를 다시 입력해야 합니다. 검수 모달을 열어둔 채 자리를 비워도 바로 실행되지 않게, 최종 동작 직전에 비밀번호 재입력을 요구하는 구조를 유지합니다.

메인 슬라이드 태그 규칙

메인 슬라이드의 카테고리 칩, 글머리 태그, `NEW` 태그는 같은 높이·같은 서체·같은 자간 규칙을 따릅니다. 대표 슬라이드에는 게시글의 글머리 태그를 가능한 한 모두 보여주고, 특정 태그만 혼자 더 커 보이거나 다른 리듬으로 보이지 않게 맞춥니다.

대표 이미지 프레이밍 규칙

홈 `메인 스토리 직접 지정`과 메인 히어로 슬라이드는 대표 이미지를 PC와 모바일에서 서로 다른 포인트로 보여줄 수 있어야 합니다. 관리자에서는 두 화면의 좌우 위치·상하 위치·확대값을 각각 따로 저장하고, 공개 화면은 같은 이미지를 쓰더라도 기기 폭에 맞는 프레이밍 값을 자동으로 선택합니다.

이미지 확대/축소 범위는 60%~150%로 유지합니다. 100% 미만으로 줄이거나 `contain`으로 보여줘 여백이 생기는 경우에는, 같은 이미지를 뒤에 40% 블러 배경으로 깔아 빈 공간이 단색으로 비지 않게 보정합니다.

히어로 관리 규칙

관리자 `사이트 설정` 그룹에서는 `설정`, `히어로 기사 설정`, `메인 스토리 직접 지정`, `도움을 주신 분들`, `UI 번역 관리`, `버전 기록`을 별도 세부메뉴로 분리합니다. 히어로는 기사 선택, 순서, 노출 시간, PC/모바일 이미지 위치를 한 영역에서 조정하고, 카드 하단의 명확한 저장 버튼으로 반영 여부를 판단할 수 있어야 합니다.

관리자 히어로 미리보기 프레임은 실제 공개 배너 비율과 가까워야 하며, 홈 메인 슬라이드에는 인디케이터 옆 `일시정지/재생` 버튼을 두어 자동 전환을 운영자가 직접 멈출 수 있게 합니다.

게시판 정렬 규칙

Korea, APR, WOSM, Scout People, `1개월 소식` 같은 공개 게시판 목록은 작성 시각 `created_at`이 아니라 공개 기준 시각인 `publish_at`을 우선으로 정렬합니다. `publish_at`이 비어 있는 기존 글만 `created_at`을 fallback으로 사용합니다.

삭제 정리 규칙

게시글 삭제는 글 row만 지우고 끝내지 않습니다. 대표 이미지와 본문 이미지의 저장 파일, 조회/공감/기록 데이터, 게시글 상세 URL 방문 로그처럼 연관 데이터도 함께 정리해 고아 데이터와 남는 파일이 쌓이지 않게 유지합니다.

관리자 간격 규칙

관리자 페이지의 상하 여백은 `섹션 간격 > 패널 내부 블록 간격 > 폼 필드 간격 > 라벨/보조문구 간격` 순으로 단계가 분명해야 합니다. 일부 카드만 지나치게 붙거나 넓어지지 않도록 공통 spacing 변수로 묶어, 위계가 같으면 같은 간격을 사용합니다.

RSS 규칙

RSS 피드에서는 작성자 실명을 노출하지 않습니다. RSS 항목의 날짜는 `publish_at`이 아니라 실제 생성 시각인 `created_at` 기준으로 보내고, 글머리 태그도 함께 포함해 리더와 수집기가 기사 성격을 더 잘 이해할 수 있게 유지합니다.

Production 배포 규칙

preview 승인 후에는 preview 페이지의 `본 페이지에 반영하기` 버튼으로 GitHub Actions 승격 워크플로우를 시작하는 것을 기본으로 합니다. 이 버튼은 모든 체크박스가 완료되고 full 관리자 인증이 끝났을 때만 동작하며, 누락 항목이 있으면 토스트가 아니라 차단 모달로 먼저 막아야 합니다. 승격은 preview 브랜치 HEAD를 단순 병합하는 방식이 아니라, 검수 화면이 들고 있는 승인된 preview SHA 자체를 `main`에 올리는 방식으로 유지합니다. 예외적으로 수동 production 배포가 필요할 때만 깨끗한 워크트리의 `main`에서 `./scripts/deploy_production.sh`를 실행합니다.

프리뷰 검수 모달 규칙

preview 환경에서는 모든 공개 페이지의 브라우저 제목 앞에 `[프리뷰]`를 붙입니다. 검수 모달은 홈에서만 자동으로 띄우고, 기사/게시판/기타 공개 페이지에서는 하단 `검수리스트` 플로팅 버튼으로 다시 열게 합니다. 관리자 페이지에는 검수 모달과 플로팅 버튼을 띄우지 않습니다.

프리뷰 자동화 규칙

preview 검수 모달의 기준은 항상 현재 production 메인 홈페이지에 실제 빌드된 최신 버전 이후 changelog입니다. 상세 섹션은 최신 버전만이 아니라 그 기준 이후 누적된 모든 변경을 체크리스트로 보여줘야 합니다.

만약 preview와 production 버전이 같고 production 이후 누적 changelog가 없다면, 검수 모달과 관리자 `프리뷰 보기` 모두 `변경 없음` 상태를 명확히 보여줘야 합니다. 이때는 반영 버튼도 실제로 동작하면 안 됩니다.

또한 각 changelog 항목은 가능하면 `요청 / 결과 / 피드백 / 상태(유지·변경·삭제)`를 남겨, 나중에 어떤 요청이 유지됐고 어떤 요청이 피드백으로 바뀌거나 삭제됐는지를 preview 모달의 요청 히스토리에서 바로 추적할 수 있어야 합니다.

preview 환경에는 `ADMIN_PASSWORD`, `ADMIN_SECRET`, `GITHUB_WORKFLOW_TOKEN`, `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`가 별도로 설정돼 있어야 하며, 반영 버튼은 GitHub Actions의 `promote-preview.yml`을 호출해 `preview -> main -> production deploy`를 실행합니다. 버튼은 pending changes, branch HEAD 일치, GitHub dispatch 가능 여부, Cloudflare 배포 접근성까지 readiness 검사를 통과했을 때만 실제 승격 가능 상태가 됩니다. 최근 20개 코드 스냅샷과 배포 이력은 `release-history` 브랜치에 보관하고, 복구는 preview 모달 히스토리에서 시작할 수 있어야 합니다.

검수 루틴

preview에서는 최소한 홈, 대표 기사 상세, 카테고리 보드, 검색, 용어집, 관리자 진입 화면, 모바일 레이아웃을 확인합니다. 최근 작업이 홈 최신 갱신, 공유 버튼 위치, 공개 기사 수정 모달처럼 상호작용을 건드렸다면, hard refresh 없이 최신 반영 여부와 공개 상세에서 수정 인증/저장 흐름까지 직접 검수합니다. 검수 결과는 preview 모달 체크박스에 바로 반영하고, 마지막 판단까지 끝낸 뒤에만 본 페이지 반영 버튼을 누릅니다.

스모크 체크 규칙

배포 후 스모크 체크는 단순 HTML 응답만 보지 않습니다. 최소한 홈/관리자/대표 기사/카테고리 페이지 응답, RSS 응답, 공개 posts API의 `publish_at`, 관리자 세션 401, D1의 `created_at`·`publish_at`·`updated_at` 컬럼 존재까지 확인해 날짜 체계와 접근 규칙 회귀를 함께 점검합니다.