# sori.studio 기술 명세 ## 프로젝트 개요 - **프로젝트명**: sori.studio - **유형**: 커스텀 블로그/CMS - **목표**: 개인 블로그 중심 운영, 기존 포털성 링크와 서비스 진입점은 블로그 내부 구조에 통합 - **참조**: Ghost(관리자 UX/글쓰기), Thred 테마(사용자 화면) - **현재 상태**: Nuxt 3.21(SSR)·PostgreSQL 저장소 계층 구성 완료. Node가 SSR 번들의 `#internal/nuxt/paths`를 해석하도록 루트 `package.json` `imports`와 `modules/nuxt-ssr-paths-write.mjs`(`.nuxt/paths.mjs` 디스크 기록)을 둔다. - **원격 저장소**: https://git.sori.studio/zenn/sori.studio.git - **스타일**: Tailwind 엔트리는 `assets/css/main.css` 한 곳(`nuxt.config`의 `tailwindcss.cssPath`)이며, `tailwind.config.js`의 `content`가 Vue·composables·modules·plugins를 스캔한다. ### 테스트 계층 - `npm test`와 `npm run test:unit`은 Node 내장 테스트 러너로 `tests/*.test.js` 단위·회귀 테스트를 실행한다. - `npm run test:api`는 Playwright API 프로젝트 10건을, `npm run test:e2e`는 Desktop Chrome 프로젝트 3건을 실행한다. Playwright는 `workers: 1`, 직렬 실행, 로컬 `http://127.0.0.1:43100` 전용 Nuxt 서버를 사용한다. - Playwright 실행기는 `docker-compose.test.yml`의 PostgreSQL 16 컨테이너를 매번 새 볼륨으로 생성하고 이름이 `_test`로 끝나는 `sori_studio_test` DB만 사용한다. 업로드는 시스템 임시 디렉터리의 `SORI_TEST_UPLOAD_ROOT`에만 저장하고 테스트 종료 시 DB 볼륨과 임시 파일을 제거한다. - Playwright 환경에서는 `PLAYWRIGHT_TEST=1`, `NUXT_POST_EXPORT_WORKER=0`, `NUXT_RECOMMENDED_FAVICON_CRON=0`을 적용해 백그라운드 worker가 테스트 상태를 바꾸지 않게 한다. - `npm run verify`는 문법 점검, 단위 테스트, 프로덕션 빌드를 실행한다. `npm run verify:ci`는 그 사이에 API와 E2E 테스트까지 포함한 전체 검증 명령이다. --- ## 화면 구조 ### 메인 화면 (3단 레이아웃) | 요소 | 크기/속성 | |------|-----------| | Header | 높이 57px, `sticky top-0`, `shrink-0`. 내부는 `grid-cols-3`로 **좌(브랜드·메뉴) / 중앙(검색, `md+`에서만 표시) / 우(사용자 메뉴)** 배치해 검색 패널을 가운데 열에 정렬한다. 검색 버튼은 중앙 열 안에서 `max-w-[min(470px,100%)]`로 폭을 제한한다. | | Shell | `min-height: 100vh`, `flex` 세로 컬럼 | | 그리드(데스크톱 `lg+`) | `items-start`, 3열 그리드(`287px / minmax(0,1fr) / 287px`)를 사용하고 열 간 `column-gap`은 두지 않는다(`gap-x-0`). 경계선은 사이드바 보더로만 구분해 이중 패딩처럼 보이는 여백을 방지한다. 긴 본문은 **문서(`html`/`body`) 스크롤**로 처리한다. | | 그리드(모바일 `lg` 미만) | 단일 세로 흐름: **본문 → 오른쪽 사이드** 순. 왼쪽 사이드는 레이아웃 흐름에서 분리된 고정 슬라이드 패널로 표시 | | Left Aside | 너비 287px, `sticky top-[57px]`, `h-[calc(100vh-57px)]`와 `max-h` 동일(뷰포트 기준 고정 높이), 내부 상단은 `.site-sidebar-scroll`(스크롤바 숨김), 하단 푸터 `shrink-0`·상단 보더로 스크롤 영역과 구분, 푸터 좌우는 `px-4`~`sm:px-5`로 본문 블록과 유사한 여백. 푸터의 API `footer` 링크 영역은 `flex-wrap`·`min-w-0 flex-1`로 항목이 많을 때 줄바꿈되어 패널 밖으로 넘치지 않는다 | | Left Aside(모바일) | `fixed` 좌측 패널, 열림 시 `translate-x-0`, 닫힘 시 화면 밖으로 이동. 열린 동안 백드롭과 `html.site-mobile-nav-open`으로 문서 스크롤 잠금 | | Main | 중앙 열 안에서 `max-width: 720px`·`justify-self: start`, 별도 `overflow-y` 없음. 공개 페이지의 가로 패딩은 레이아웃 그리드(`public-layout__grid`)의 `px-*` 한 번만 사용하고, 본문 섹션의 `px-*`는 두지 않는다. | | Right Aside | Left와 동일 패턴(스티키·고정 높이·내부 무스크롤바 스크롤·하단 카피라이트) | | Right Aside(모바일) | 본문 아래에 전체 너비로 배치, 상단 보더로 본문과 구분 | ### 메뉴 토글 - 헤더 좌측 아이콘은 브랜드 마크가 아니라 왼쪽 사이드바 열기/닫기 버튼 - 메뉴 상태는 Nuxt/Vue 상태로 관리 - 브라우저에서는 `localStorage.MENU_STATE`에 `open` 또는 `closed` 저장 - 닫힘 상태에서는 왼쪽 사이드바 폭을 0으로 줄이는 전환 애니메이션을 적용 - `lg` 미만에서는 왼쪽 사이드바를 화면 좌측 고정 슬라이드 패널로 표시하고, 열린 동안 백드롭을 탭하면 `closeMenu`로 닫는다. - 모바일 왼쪽 메뉴와 데스크톱 양쪽 고정 사이드바의 top·높이는 `SiteTopChrome`이 측정한 `--site-top-chrome-height`를 사용해 어나운스 바 줄바꿈·표시 여부가 바뀌어도 헤더 아래에 맞춘다. - `Escape` 키는 통합 검색 모달이 열려 있으면 최우선으로 닫고, 그다음 사용자 드롭다운, 이어서 모바일에서만 좌측 슬라이드 메뉴를 닫는다. - `/` 키는 `INPUT`·`TEXTAREA`·`SELECT`·`contenteditable`에 포커스가 없고 `Ctrl`/`Meta`/`Alt`와 함께 눌리지 않을 때 통합 검색 모달을 연다. 헤더 검색 영역(`md+`) 클릭으로도 동일하게 연다. - 통합 검색 입력은 한글 등 IME 조합 중에도 입력창에 표시되는 현재 값을 디바운스로 검색에 반영하고, 조합 종료 시 최종 입력값을 즉시 검색한다. 검색어는 앞뒤 공백 제거, 연속 공백 단일화, Unicode NFC 정규화를 거쳐 태그·게시물·페이지 검색에 사용한다. - 헤더 우측 사용자 아이콘 버튼은 로그인 상태면 회원 아바타/닉네임과 설정·로그아웃 메뉴를, 비로그인 상태면 Guest·Sign up·Sign in 메뉴를 표시한다. 회원 아바타 이미지가 없거나 비로그인 상태인 경우 사용자 메뉴 버튼에는 사람 아이콘을 표시한다. - 오른쪽 사이드바의 FOLLOW 영역은 사이트 설정의 SNS 링크 목록을 기준으로 표시한다. 관리자가 아이콘 프리셋 또는 직접 SVG 아이콘과 주소를 등록한 항목만 노출하며, 등록된 항목이 없으면 FOLLOW 영역 자체를 숨긴다. SNS 주소는 `https://`를 생략해도 저장 시 자동 보정한다. 관리자 편집 화면은 아이콘과 주소를 기본 입력으로 사용하며, 직접 SVG 프리셋을 선택했을 때만 SVG 코드 입력을 추가로 표시한다. 공개 FOLLOW 아이콘은 프리셋·직접 SVG 모두 16px 아이콘을 20px 버튼 중앙에 배치한다. ### 공개 화면 색상 - 라이트/다크 모드는 CSS 변수로 관리 - 기본 배경, 패널, 라인, 텍스트, 보조 텍스트, 입력, 강조 버튼 색상을 분리 - 브랜드 포인트 컬러는 사이트 설정의 `brandColor` 값을 공개 앱 루트의 `--site-accent` CSS 변수로 반영한다. 기본값은 `#ff4f2e`이며, 왼쪽 사이드 활성 네비게이션, 게시글 TOC 활성 항목, 댓글 등록 버튼 등 사용자 화면의 주요 강조 요소에 사용한다. - 어나운스 바는 사이트 설정의 문구·링크·배경색·텍스트 정렬을 반영한다. 배경색은 3/6자리 hex 값을 저장하며 기본값은 `#15171a`, 텍스트 정렬은 `center` 또는 `left`를 사용한다. - 라이트 모드 기본 배경은 `#fcfcfc`로 통일하고 패널 구분은 보더로 처리 - 시스템 다크 모드는 `prefers-color-scheme: dark` 기준으로 우선 대응 - 사용자 수동 테마 전환은 `html[data-theme]`와 `localStorage.SITE_THEME`로 관리한다. 첫 페인트 전 `lib/site-theme-init.js` 인라인 스크립트가 테마를 적용해 시스템 다크·저장 라이트 불일치 시 깜빡임을 줄인다. 공개 페이지 로딩 중에는 `#site-splash`에 캐시된 로고 이미지 URL(`SITE_BRAND_LOGO_URL`, localStorage) 또는 사이트 제목(`NUXT_PUBLIC_SITE_TITLE`)을 잠깐 표시하고, 앱 마운트 후 `site-app-ready`로 숨긴다. `site_settings.logo_text`(기본 `井`)는 **이미지 로고가 없을 때** 헤더·사이드바에 쓰는 짧은 기호이며 localStorage·스플래시와는 별개다. - Thred 참고 화면처럼 사이드바와 본문은 같은 화면 안에서 라인으로 구분한다. 사이드바 자체 배경은 라이트/다크 모두 기본 화면 배경(`--site-bg`)과 통일하고, 내부 카드형 요소만 패널 배경을 사용한다. ### 응답 보안 헤더 - 모든 응답은 `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin`, `X-Frame-Options: SAMEORIGIN`, 카메라·마이크·위치 권한 차단 `Permissions-Policy`를 적용한다. - 강제 CSP는 `base-uri 'self'`, `object-src 'none'`, `frame-ancestors 'self'`만 적용한다. 전체 HTML 문서의 자체 ``·자산 구성을 보존해야 하는 `/pages/**` 응답은 강제 CSP에서 제외한다. - 호환 정책은 모든 경로에서 `Content-Security-Policy-Report-Only`로 유지한다. 사용자 사이트 코드·광고·외부 미디어를 차단하지 않은 채 script/style/img/font/media/frame/connect/worker/manifest 위반을 `/api/csp-report`로 보고하며 `Reporting-Endpoints`와 `Report-To`도 같은 origin 수집 주소를 가리킨다. - `POST /api/csp-report`는 `application/csp-report`, `application/reports+json`, `application/json`, `application/*+json`만 허용하고 요청 본문은 32KB, Reporting API 배열은 최대 20건으로 제한한다. IP 원문을 보관하지 않는 해시 키 기준으로 분당 60회까지만 받는다. - CSP 위반은 정책 버전, 쿼리·fragment를 제거한 문서 경로, 지시어, 경로·쿼리를 제거한 차단 origin, 브라우저 계열만 `csp_violation_aggregates`에 누적한다. 원문 URL과 User-Agent는 저장하지 않으며 저장 실패가 일반 응답을 실패시키지 않는다. ### 홈 Featured (인덱스) - 가로 카드 트랙은 `overflow-x-auto`와 `snap-x`/`snap-mandatory`로 슬라이드 느낌을 낸다. - Featured 영역은 추천 글(`isFeatured=true`)이 1개 이상 있을 때만 표시한다. - 표시 개수는 사이트 설정 POST 설정의 `featuredPostLimit` 값을 따른다. 기본값은 6개다. - Featured 글에 대표 이미지가 없으면 목록 썸네일과 동일하게 카드 안에 게시물 제목을 표시하는 placeholder를 사용한다. - Featured 대표 이미지가 게시물 업로드 이미지이고 카드 썸네일이 생성되어 있으면 원본 대신 `featuredImageThumbnail`을 우선 표시한다. - 모바일 터치: `touch-pan-x`, `-webkit-overflow-scrolling: touch`, `overscroll-x-contain`으로 가로 스크롤 우선·부모로의 스크롤 전파 완화. - 헤더의 이전·다음 화살표는 `scrollLeft`와 최대 스크롤 거리로 양 끝에서 `disabled` 처리하며, `scroll` 이벤트와 `ResizeObserver`로 동기화한다. Pages 선반은 각 선반의 스크롤 컨테이너와 카드 크기 변화를 감시해 이미지 로딩·반응형 폭 변화 후에도 버튼 상태를 다시 계산한다. - 마우스/트랙패드 환경에서는 카드 트랙을 직접 드래그해 넘길 수 있고, 드래그 종료 시 가까운 카드 위치로 스냅한다. 트랙 안의 이미지 기본 드래그와 텍스트 선택은 막아 캐러셀 조작을 우선하며, 클릭과 구분되는 이동 임계값을 넘었을 때만 드래그로 처리한다. 포인터 캡처는 드래그가 확정된 뒤에만 적용해 일반 클릭의 링크 이동을 막지 않는다. 드래그 중 포인터가 카드 밖으로 이동해도 문서 레벨 포인터 추적으로 조작을 유지한다. 드래그 직후에는 카드 링크 클릭을 억제해 의도치 않은 이동을 막는다. ### 홈 Latest 피드 - 기본 보기 방식은 `compact`이며, Default 선택 시에도 `compact`로 복원한다. - 홈 Latest는 사이트 설정 POST 설정의 `homeLatestPostLimit` 값만큼 서버에서 최신 글을 가져온다. 기본값은 20개다. - 홈 Latest 하단에는 전체 게시물 목록(`/posts`)으로 이동하는 더보기 링크를 표시한다. - `compact`는 썸네일을 포함한 짧은 행 형태이며 설명은 최대 2줄로 제한한다. 모바일 compact 썸네일은 오른쪽 제목·요약·메타 높이에 맞춘 80px 정사각형으로 표시하고, `sm` 이상에서는 기존 비율형 썸네일을 사용한다. 대표 이미지가 없는 placeholder 제목은 모바일 3줄, `sm` 이상 4줄로 제한하며 긴 단어는 썸네일 안에서 줄바꿈한다. `list`는 텍스트 중심 목록 형태로 설명은 최대 2줄, `cards`는 카드 그리드 형태로 표시한다. - 홈 Latest·게시물 목록·태그 목록의 썸네일 영역은 대표 이미지 유무와 관계없이 같은 크기를 유지한다. - 홈 Latest·게시물 목록·태그 목록의 카드 이미지는 `featuredImageThumbnail`을 우선 사용하고, 값이 없으면 기존 `featuredImage` 원본 URL로 대체한다. - Latest 섹션은 게시물이 적어도 보기 방식 선택 메뉴가 아래쪽에서 잘리지 않도록 최소 높이를 둔다. - 사이트 설정 Ads의 메인 피드 광고 코드가 있으면 Featured 영역과 Latest 목록 사이에 광고 슬롯을 표시한다. 메인 인피드 광고 코드가 있으면 Latest 게시물 목록 사이 한 곳에 브라우저 렌더 시점 기준으로 무작위 삽입한다. 비어 있으면 슬롯 자체를 렌더링하지 않는다. ### Post 페이지 - 게시물 화면은 레이아웃 그리드의 좌우 패딩을 기본으로 사용하고, 섹션 단위 `px-*`는 내부 래퍼로만 두어 패딩이 2중 적용되지 않게 한다. - 사이트 설정 Ads의 게시물 본문 상단·하단 광고 코드가 있으면 본문 렌더링 전후에 광고 슬롯을 표시한다. 게시물 인아티클 광고 코드가 있으면 공백 제외 본문 길이 2,000자 미만에서는 표시하지 않고, 2,000자 이상은 전체 블록 40% 근처 일반 문단 뒤에 한 번, 6,000자 이상은 35%·70% 근처 일반 문단 뒤에 최대 두 번 표시한다. 광고 사이에는 최소 8개 블록 간격을 둔다. - 댓글 시작 섹션의 구분선(`border-y`)은 패딩 없이 전체 폭으로 표시하고, 내용만 내부 래퍼에 패딩을 둔다. - 본문 끝과 댓글 섹션 시작 사이 간격은 `48px`(`mt-12`)로 유지한다. - 댓글은 로그인 회원만 작성 가능하며, 대댓글은 1단까지만 허용한다. - 댓글·답글 등록 버튼은 입력값을 trim한 뒤 내용이 있을 때만 활성화한다. - 댓글은 작성자 썸네일(없으면 이니셜)과 좋아요 수를 표시한다. - 댓글 시간은 24시간 이내일 때 상대 시간(분/시간 전), 이후에는 날짜로 표시한다. - 댓글 정렬은 `인기순`(좋아요 우선), `최신순`, `오래된순`을 제공한다. - 댓글 아바타 이미지 로드 실패 시 이니셜 아바타로 즉시 대체한다. - 같은 댓글 컴포넌트에서 게시물 slug가 바뀌면 이전 댓글·입력·답글·오류·좋아요 요청 상태를 초기화하고 새 댓글을 조회한다. 이전 slug의 늦은 응답은 현재 상태에 반영하지 않는다. - 멤버십 게시물 댓글은 해당 본문을 볼 수 있는 VIP 이상 회원만 조회·작성·좋아요할 수 있다. - 공개 게시물 본문은 콘텐츠 타입별 컴포넌트로 분리해 추후 스타일 변경이 쉽도록 구성 - 공개 게시물 오른쪽 목차는 H1~H3 제목 표시 텍스트에서 링크·굵게·기울임·인라인 코드 같은 마크다운 장식만 제거하고 `~` 같은 일반 제목 문자는 보존한다. - 공개 Markdown 인라인 렌더러는 단일 루트와 `display: contents`를 사용해 사용자 화면 DOM의 Vue fragment 주석 반복을 줄이고, 기존 인라인 흐름은 유지한다. 링크·굵게·기울임·색상 토큰 내부의 굵게·기울임·링크·인라인 코드·색상·첨자 문법은 재귀적으로 렌더링한다. 여러 줄 문단은 첫 줄과 이후 줄을 분리해 첫 줄에 불필요한 `br` 조건 분기를 두지 않는다. - 공개 Markdown 본문 블록 파싱은 `lib/markdown-block-parser.js`에서 수행하고, 본문 블록 렌더링은 `ContentMarkdownBlockGroup`으로 블록 단위 루트를 정리한다. 인아티클 광고는 별도 `v-if` 대신 렌더 블록 목록에 삽입한다. - Markdown 리스트 마커는 항목이 여러 줄로 줄바꿈되어도 항목 전체 높이 중앙이 아니라 첫 줄 기준으로 정렬한다. - 표준 마크다운 표(`| 헤더 | ... |`, `| --- | ... |`)는 본문에서 가로 스크롤 가능한 HTML table로 렌더링한다. 정렬 구분선(`:---`, `:---:`, `---:`)은 각각 좌/중앙/우 정렬로 반영한다. 표 헤더와 셀 내부의 인라인 링크·굵게·기울임·인라인 코드를 렌더링하고, 셀 내부 `
` 또는 `
`은 줄바꿈으로 표시한다. 링크 텍스트 안의 `**굵게**` 같은 중첩 인라인 문법도 렌더링한다. - 인용문(`>`)은 왼쪽 세로 막대형 기본 스타일로 표시한다. 기본 인용 텍스트는 라이트·다크 모드 모두 사이트 본문 텍스트 색상(`--site-text`)을 따른다. 첫 줄 옵션 `> [!bg=blue]` 또는 `> {bg=blue}`는 인용 막대 색상으로 반영하며, 지원 값은 콜아웃과 같은 `gray`, `blue`, `green`, `yellow`, `red`, `purple`이다. 인용 본문 안의 `::red[**텍스트**]` 같은 색상·굵게·링크 등 인라인 문법은 일반 문단과 같은 규칙으로 렌더링한다. - 관리자 Markdown-first 글쓰기의 오른쪽 블록 설정 패널은 인용·콜아웃·코드 블록·토글 설정과 선택 텍스트 색상 설정을 지원한다. 단일 이미지는 전체 너비(자동)·갤러리 2장 1칸(356px)·갤러리 3장 1칸(235px)·갤러리 3장 2칸(477px)·직접 입력 셀렉트로 표시 너비를 고를 수 있으며 저장 시 이미지 마크다운 뒤에 `{size=숫자}` 옵션을 붙인다. 공개 본문은 이 값을 최대 너비로 적용하고 원본 비율은 유지한다. 직접 입력은 120~1600px 범위로 저장하되 입력 중에는 범위 보정을 즉시 강제하지 않는다. 콜아웃은 제목·아이콘 표시 ON/OFF 토글·아이콘·배경색, 코드 블록은 언어 셀렉트·줄번호 표시 ON/OFF 토글, 토글은 기본 펼침·닫힘 상태를 선언 줄에 저장한다. 콜아웃 아이콘 입력·프리셋은 아이콘 표시가 꺼진 상태에서 흐린 비활성 영역으로 표시하고, 토글을 켠 뒤에만 조작한다. 코드 블록 줄번호는 기본 숨김이며, 켠 경우에만 선언 줄에 `line-numbers`를 저장한다. 일반 텍스트 범위를 선택하면 텍스트 색상 패널이 열리고 회색·파랑·초록·노랑·빨강·보라 인라인 색상을 적용한다. 콜아웃 아이콘은 라이브·공개 화면 모두 왼쪽 상단에 배치하고, 아이콘·제목 헤더 아래에 본문을 줄바꿈해 표시한다. 아이콘 미사용 시 자리 표시자를 남기지 않는다. 인용·콜아웃·토글 본문은 라이브 모드에서 굵게·링크·색상 같은 인라인 문법과 기본 불릿/번호 목록을 표시한다. 라이브 문단에서는 `>` 입력으로 인용, ``` Enter로 코드 블록, `!!!` Enter로 콜아웃을 만들 수 있고, `/표` 또는 `/table` 슬래시 명령으로 기본 3열 표 마크다운을 삽입한다. `/html`은 `:::html`, `/link`는 `:::link`, `/iframe`은 `:::iframe` fenced 블록을 삽입한다. 소스·라이브 모드 모두 텍스트를 선택한 뒤 `Cmd/Ctrl+K`를 누르면 `[선택 텍스트](https://)` 인라인 링크 마크다운을 삽입하고 URL 부분을 선택한다. 소스 textarea의 선택 치환·인라인 감싸기·링크 삽입·줄 변환 계산은 `markdown-source-selection` helper가 담당하고, 라이브 전환 포커스 대상 보정과 코드 펜스 본문 줄 판별은 `markdown-editor-focus` helper가 담당한다. 슬래시 명령의 미디어 모달·마크다운 줄 삽입 적용 계획과 적용 후 에디터 효과 계획은 `markdown-slash-commands` helper가 계산한다. 미디어 선택 모달의 상태·표시 계산, 서버 목록 조회, 업로드 실행과 업로드 후 선택 상태 갱신은 `useAdminMarkdownMediaPicker`가 관리하고, 선택 미디어 삽입 계획과 업로드 입력·응답 정규화는 `markdown-editor-media` helper가 계산한다. 오른쪽 블록 패널의 미디어·임베드·인용·콜아웃·코드·토글 옵션 줄 교체와 인라인 색상 본문 변경 계산은 `markdown-editor-block-options` helper가 담당한다. 에디터는 선택·업로드·옵션 변경 결과의 본문 반영과 실제 포커스·스크롤 실행만 처리한다. 작성/라이브 모드 전환의 pending 포커스 상태와 복원 순서는 `useAdminMarkdownFocusBridge`가 관리하고, 라이브 미리보기 표면 DOM 접근·현재 source line 계산·줄 포커스 실행은 `useAdminMarkdownPreviewFocus`가 관리한다. 에디터 되돌리기·다시 실행은 `useAdminMarkdownHistory`에서 본문 값과 선택 위치를 함께 복원해 줄 앞 이동을 줄인다. 라이브 모드에서 위·아래 방향키로 인접 블록을 이동하면 커서가 화면 밖으로 벗어날 때 편집 스크롤 영역도 함께 이동한다. 라이브 코드·인용·콜아웃·토글 블록은 맨 위/맨 아래 방향키로 외부 기본 문단을 만들며 빠져나올 수 있고, 인용 첫 글자 앞 Backspace는 일반 문단으로 되돌린다. 한글 등 IME 조합 입력 중에는 줄바꿈 직후 블록 판별이 일시적으로 비어도 마지막 블록 컨텍스트를 유지해 설정 패널이 닫히지 않게 한다. 인용 편집 중 브라우저 자동 목록 보정으로 `>. ` 접두가 섞이면 커밋 시 정리한다. - 게시물 상세의 오른쪽 사이드바는 데스크톱에서 블로그 소개·Follow 대신 본문 H1~H3 제목 기반 목차를 최상단에 표시한다. 목차는 별도 최대 높이와 내부 스크롤을 두지 않고 전체 목록이 먼저 펼쳐지며, 왼쪽 기준선과 브랜드 컬러 활성 항목 표시선을 둔다. 목차 항목은 최소 24px 높이와 세로 중앙 정렬을 사용하며, 2줄 이상 제목에서는 항목 높이에 맞춰 활성 표시선도 함께 늘어난다. 활성 표시선은 항목의 가상 요소 배경 막대로 그려 텍스트 시작점이 밀리지 않게 한다. 목차 링크는 본문 제목에 부여된 앵커 ID로 부드럽게 이동하며, 고정 상단 헤더 높이와 여백을 반영해 제목이 화면 밖에 걸리지 않게 한다. 본문 스크롤 중에는 현재 제목에 해당하는 목차 항목을 강조하고, 목차 항목이 많으면 오른쪽 사이드바 스크롤이 활성 항목을 따라간다. 본문 제목이 없으면 목차 없음 문구를 표시한다. 오른쪽 사이드바가 본문 아래로 내려가는 모바일 폭에서는 목차를 숨긴다. 게시물 상세에서는 일반 오른쪽 사이드 광고 대신 게시물 사이드 광고 코드를 목차 아래에 표시하고, 왼쪽 사이드바에는 게시물 광고를 표시하지 않는다. 게시물 상세 목차와 게시물 사이드 광고 슬롯은 하단 구분선을 표시하지 않는다. - 제목 우측 공유 버튼을 누르면 게시물 공유 모달을 연다. - 공개 회원 로그인 세션의 회원 ID가 게시물 `author_id`와 같으면 제목 우측 공유 버튼 옆에 수정 아이콘을 표시하며, 클릭 시 `/admin/posts/:id` 편집 화면을 새 탭으로 연다. 별도 관리자 세션만 있거나 비로그인 상태에서는 표시하지 않는다. - 공유 모달은 게시물 썸네일/제목/요약 미리보기, X/Bluesky/Facebook/LinkedIn/Email 링크, 링크 복사 액션을 제공한다. - 공유·SEO 설명은 SEO 설명이 있으면 우선 사용하고, 없으면 게시물 요약, 요약도 없으면 본문에서 마크다운 기호를 제거한 짧은 텍스트를 사용한다. - 공개 페이지 ``은 개별 페이지 제목이 있으면 제목만 사용하고, 제목이 없는 기본 화면에서만 사이트 이름을 사용한다. 게시물 상세 제목 뒤에 사이트 이름을 자동으로 붙이지 않는다. - 홈 Latest·게시물 목록·태그 목록의 카드 설명도 동일하게 요약이 비어 있으면 본문에서 `createPostSummary`로 짧은 텍스트를 만든다. 이때 코드·HTML/iframe 블록, HTML 태그, 인라인 색상 토큰 같은 표시용 문법은 목록 설명에 노출하지 않는다. 목록용 설명은 문자열에 수동 말줄임을 붙이지 않고 `post-summary-clamp` 전용 클래스가 실제 표시 줄 끝에서 말줄임을 처리한다. 목록 카드의 제목·썸네일·오른쪽 아래 화살표는 게시물 상세로 이동하고, 태그 배지는 태그 고유 색상 배경으로 표시하며 `/tag/:slug`로 이동한다. - 게시물 상세 제목 아래 대표 이미지는 관리자 글쓰기 오른쪽 사이드의 `대표 이미지 표시` 옵션이 켜진 게시물에서만 표시한다. 해당 토글은 대표 이미지 유무와 상관없이 항상 활성 상태이며, 대표 이미지를 나중에 추가할 경우에도 미리 저장한 표시 설정을 유지한다. 대표 이미지는 목록·공유용으로는 계속 사용할 수 있으며, 본문 상단 표시 기본값은 꺼짐이다. - 관리자 글쓰기에서 비공개·초안 상태 글을 `published`로 직접 변경했는데 발행 시각이 비어 있으면 현재 시각을 기본값으로 채운다. 서버 저장 API도 공개 상태 입력의 `publishedAt`이 비어 있으면 현재 시각으로 보정한다. ### 게시물 업로드 이미지 썸네일 - 관리자 미디어 업로드 API는 JPG·PNG·WebP 파일을 `/uploads/posts/YYYY/MM/원본파일`에 저장한다. 업로드만으로는 카드 썸네일을 만들지 않고, 해당 이미지가 게시물 대표 이미지로 저장될 때 목록 카드용 WebP 썸네일을 `/uploads/posts/YYYY/MM/thumbs/원본파일명-card.webp`에 생성한다. - 카드 썸네일은 640×360 기준 `cover` 리사이즈와 WebP 품질 82를 사용한다. GIF·동영상·문서 파일은 썸네일을 자동 생성하지 않는다. - 본문 표시용 이미지는 1600px `thumbs/*-body-1600.webp`와 720px `thumbs/*-body-720.webp`를 함께 생성하고, 공개 본문 단일 이미지·갤러리는 `lib/content-image-urls.js`의 `srcset` 계산으로 화면 폭에 맞는 파일을 우선 사용한다. 공개 본문 라이트박스 대상 목록은 `useContentMarkdownBlocks`에서 `lib/content-gallery-images.js` 기준으로 계산하고, 갤러리 행 분할은 `lib/content-gallery-images.js`에서 계산한다. 관리자 라이브 모드의 단일 이미지·갤러리 드래그 상태와 병합·삽입·분리·정렬 이벤트 중개는 `useContentMarkdownImageDrag`에서 관리한다. 라이브 모드의 선택 확장·전체 선택·선택 삭제·포커스 복원·line focus/blur 중개는 `useContentMarkdownLiveSelection`에서 관리한다. 코드·콜아웃·토글 fenced 블록의 라이브 편집 이벤트는 `useContentMarkdownFencedBlocks`에서 관리한다. 문단·스페이서 편집과 `>`·코드·콜아웃 문단 단축 변환은 `useContentMarkdownParagraphs`에서 관리한다. 목록 번호 계산과 항목 커밋·분리·탈출 이벤트는 `useContentMarkdownLists`에서 관리한다. 인용 블록 커밋·아래 이탈·일반 문단 복귀 이벤트는 `useContentMarkdownQuotes`에서 관리한다. - 라이트박스용 이미지는 2560px `thumbs/*-body-2560.webp`를 생성해 크게 보기 화면에서 우선 사용한다. 별도 원본 보기 UI는 제공하지 않으며, `lib/content-image-urls.js`가 파생 URL을 선택하고 파생 이미지 로드 실패 시에만 원본으로 fallback한다. - 기존 운영 볼륨에 생성된 `thumbs/*-body.webp`, `thumbs/*-lightbox.webp`는 레거시 본문 파생 이미지로 계속 인식해 관리자 미디어의 본문 이미지 탭과 사용처 연결을 유지한다. 새 저장·재생성·백필은 해상도형 파일명만 만든다. - 관리자 미디어의 원본 이미지 사용처는 원본 URL 직접 참조뿐 아니라 해당 원본에서 생성된 카드·페이지 커버·본문 파생 이미지 URL 사용처까지 함께 반영한다. 사용처 계산은 관리자 글 목록 요약 API와 분리된 미디어 참조 전용 조회로 게시물·페이지의 본문과 대표 이미지만 확인한다. 따라서 공개 본문이 `body-1600` 같은 파생 이미지를 사용하더라도 원본은 미사용 삭제 대상에서 제외되고, 본문 파생 이미지도 실제 본문 사용처가 있으면 미사용으로 분류하지 않는다. 원본이 실제로 미사용이라 삭제될 때는 연결된 카드·페이지 커버·본문 자동 생성 이미지도 함께 삭제한다. - 카드·본문·라이트박스·Pages 커버 파생 이미지는 임시 파일에 먼저 생성하고 Sharp 메타데이터로 읽기 검증한 뒤 최종 파일로 교체한다. 생성 또는 검증에 실패하면 깨진 파생 파일이 남지 않도록 대상 파일을 제거하고 공개 화면은 원본 fallback을 사용한다. 파생 이미지는 같은 URL로 재생성될 수 있으므로 `/uploads/posts/YYYY/MM/thumbs/*.webp` 응답은 `no-cache`로 재검증하고, 공개 본문과 관리자 미디어 미리보기에는 파생 이미지 캐시 버전 쿼리를 붙여 기존 브라우저 캐시를 우회한다. - 공개 게시물 응답은 원본 대표 이미지 `featuredImage`를 유지하고, 대응 썸네일 파일이 실제로 존재할 때만 `featuredImageThumbnail`을 추가한다. - 기존 대표 이미지는 로컬에서 `npm run images:backfill-post-thumbnails`, NAS 운영에서 `sh scripts/backfill-post-thumbnails-production.sh`로 게시물 대표 이미지 URL만 스캔해 누락된 카드 썸네일을 생성한다. 관리자 미디어의 원본 이미지 상세에서도 카드 썸네일을 개별 생성·재생성할 수 있다. - 기존 본문 이미지는 로컬에서 `npm run images:backfill-post-body-thumbnails`, NAS 운영에서 `sh scripts/backfill-post-body-thumbnails-production.sh`로 전체 게시물 본문 URL을 스캔해 누락된 1600px 본문 표시용 WebP, 720px 작은 본문 표시용 WebP, 2560px 라이트박스용 WebP를 생성한다. - 기존 Pages 진열장 커버 이미지는 로컬에서 `npm run images:backfill-page-cover-thumbnails`, NAS 운영에서 `sh scripts/backfill-page-cover-thumbnails-production.sh`로 홈 노출 페이지의 누락된 3:4 WebP 썸네일을 생성한다. ### 미디어 카탈로그 - 파일시스템은 미디어 파일의 실체와 제공 기준이고 PostgreSQL은 목록 검색·사용처·상태를 위한 카탈로그다. `MEDIA_CATALOG_MODE`는 `filesystem`, `shadow`, `database`를 허용하며 그 외 값·미설정은 `filesystem`으로 처리한다. 개발·전환 완료 환경은 `database`로 고정하고, 운영도 reconcile 완료 뒤 `database`로 고정한다. - `filesystem`은 디스크 스캔 결과를 반환한다. `shadow`는 파일시스템 결과를 반환하면서 DB 카탈로그의 개수·bytes·종류 차이를 로그로 비교한다. `database`는 DB에서 목록을 반환하되 `media_catalog_state`가 준비되지 않았거나 reconcile 전, `staging`/`error` 행 존재, 개수·bytes 불일치, 쿼리 실패 시 파일시스템으로 fallback한다. - `media_metadata`는 URL·저장 키·파일명·확장자·종류·역할·용량·수정 시각·원본/파생 관계·생성 출처·`staging|active|missing|deleting|error` 상태를 저장한다. `media_references`는 게시물·페이지·태그·회원·사이트 설정·네비게이션의 URL 참조와 표시 메타를 저장하고, `media_catalog_state` 단일 행은 reconcile 시각과 파일시스템/카탈로그 개수·bytes·준비 상태를 저장한다. - 관리자 일반 업로드는 multipart 파일명을 UTF-8로 복구한 뒤 NFC 정규화·안전 문자 치환으로 저장한다. macOS NFD 한글 파일명도 `스크린샷-…` 형태로 유지되며, busboy Latin-1 오해로 인한 `á-á-³…` 깨짐을 막는다. - 앱이 관리하는 업로드·Import·썸네일·아바타·파일명 변경·삭제는 디스크 성공 뒤 카탈로그에 최선 노력으로 dual-write한다. 게시물·페이지·태그·회원·사이트 설정·네비게이션 저장은 해당 대상의 `media_references`를 현재 필드 값으로 교체한다. 보조 카탈로그 기록 실패는 이미 성공한 파일·콘텐츠 작업을 되돌리지 않는다. - reconcile은 업로드 파일을 삭제하거나 이동하지 않는다. 지원 파일을 스캔해 upsert하고 콘텐츠 참조를 백필하며, 스캔에서 사라진 기존 행은 삭제 대신 `missing`과 `missing_since`로 표시한다. 파일시스템과 active 카탈로그의 개수·bytes가 같고 미완료 행이 없을 때만 `ready=true`로 기록한다. - 관리자는 `POST /admin/api/media/reconcile`로 수동 reconcile할 수 있다. 로컬 스크립트 `npm run media:reconcile:dev`는 loopback DB, 비운영 환경, 접속 URL과 실제 DB 이름 일치, DB 이름에 `prod|production` 미포함 조건을 모두 확인한 뒤 같은 작업을 실행한다. - 개발 DB 검증 기준 파일시스템 124개·77,019,754 bytes와 active 카탈로그의 개수·bytes 차이는 모두 0이다. - DB 모드의 원본 항목 `thumbnailStatus`/`bodyThumbnailStatus`는 파일시스템 모드와 같은 계약이다. `hasThumbnail`은 각각 `*-card.webp`/`*-page-cover.webp`와 `*-body-1600.webp` 존재 여부로만 판별하며, 레거시 `*-body.webp`만 있는 경우는 썸네일 없음·필요 시 `원본` 폴백으로 처리한다. 관리자 그리드 미리보기는 `body-720`이 있을 때만 우선 사용하고, 파생 URL 로드 실패 시 원본 URL로 되돌린다. ### 공개 목록·상세의 발행일 표시 - API의 ISO 8601 `publishedAt`를 공개 UI에서는 로컬 날짜 기준 `YYYY.MM.DD`로 표시한다. - 변환은 `composables/formatPostDate.js`의 `formatPostDate`를 사용한다. - 관리자 목록·수정일 보조 라벨은 `formatPostDateTime`(`YYYY.MM.DD 오전/오후 HH:MM`)을 사용한다. 발행 후 수정 여부는 `wasPostUpdatedAfterPublish`로 판별하며, `site_settings.show_post_updated_at`이 true일 때만 관리자 글 목록에 「수정: …」를 노출한다. 공개 게시글 상세에는 수정 시각을 표시하지 않는다. - `<time>`에는 표시용 문자열과 함께 가능한 경우 원본 시각을 `datetime` 속성으로 둔다. ### Page 페이지 - About, Projects, Links, Contact, 서비스 소개 페이지 등 고정 콘텐츠에 사용 - 기본 게시물 목록에는 노출하지 않음 - 페이지 설정의 `홈에 표시`가 켜진 공개 페이지는 홈 화면의 Pages 진열장 영역에 노출한다. 진열장은 `섹션명` 기준으로 여러 선반을 만들고, 각 페이지는 도서/게임 라이브러리처럼 세로형 커버 카드로 표시한다. 각 선반은 Featured와 같은 이전·다음 버튼과 드래그 슬라이드·스냅 이동을 지원하며, 선반별로 독립 동작한다. 카드 폭은 데스크톱 기준 약 164px로 여러 페이지가 있을 때 가로 탐색이 명확히 생기도록 한다. 섹션별 표시 개수는 사이트 설정 POST 설정의 `pageSectionItemLimit` 값을 따른다. 기본값은 12개다. - Pages 진열장 커버는 3:4 세로 비율을 기준으로 표시한다. 제작 권장 크기는 `900×1200px`이며, 고해상도 원본을 준비할 때는 `1200×1600px`을 권장한다. 최소 권장 크기는 `600×800px`이다. 페이지 저장 시 원본 커버 이미지에서 홈 진열장용 WebP 썸네일(`thumbs/*-page-cover.webp`, 450×600, cover)을 생성하고, 공개 페이지 목록 응답은 `listingImageThumbnail`이 있으면 원본 `featuredImage`보다 우선 사용한다. - 페이지 섹션 생성·이름 변경·삭제·표시 순서는 관리자 네비게이션 관리의 `페이지 섹션` 탭에서 다룬다. 섹션 추가는 모달에서 이름을 입력해 생성하고, 이름 변경과 섹션 표시 순서는 탭 안의 `페이지 섹션 저장`으로 한 번에 저장한다. 페이지 작성·수정 화면에서는 등록된 섹션을 검색형 입력으로 선택한다. - 섹션 내부 페이지 표시 순서는 관리자 네비게이션 관리의 `페이지 섹션` 탭에서 섹션별 `페이지 순서` 모달로 조정하며, 페이지 작성·수정 화면에서는 직접 입력하지 않는다. 순서 모달은 페이지 썸네일 카드형 가로 목록으로 표시하고, 추천 페이지를 먼저 보여 주며, 추천 페이지가 비추천 페이지 뒤로 드롭되면 즉시 추천 우선 순서로 보정한다. 페이지를 해당 섹션에서 바로 제거할 수 있다. - `추천으로 강조`된 페이지는 같은 섹션 안에서 먼저 정렬하며, 홈 Pages 진열장 카드 왼쪽 위에 SVG 아이콘 배지로 표시한다. - 목록 설명은 홈 카드에는 표시하지 않고 공개 검색 결과와 관리용 메타로 사용한다. - 헤더와 사이드바를 사용하지 않고 본문 중심 전체 화면으로 표시 - 페이지는 `renderMode`로 렌더링 방식을 구분한다. 기본값은 `html_document`이며 관리자에서 붙여넣은 전체 HTML 문서를 공개 `/pages/:slug` 요청에서 `text/html` 원문으로 응답한다. `markdown`은 관리자 UI에서 `일반 텍스트`로 표시하며 기존 Markdown 콘텐츠 렌더러를 사용한다. - HTML 문서 모드는 관리자만 저장하는 신뢰 콘텐츠를 전제로 하며, `<head>`, `<style>`, `<body>`를 포함한 단일 랜딩 페이지 용도로 사용한다. HTML 태그 내부의 스마트 따옴표는 저장 전 표준 따옴표로 정규화해 `href`·`class` 같은 속성 해석이 깨지지 않게 한다. - HTML 문서 모드 페이지로 Nuxt 클라이언트 라우팅을 통해 진입한 경우 현재 URL을 `reload()`해 서버 미들웨어의 원문 HTML 응답으로 재진입한다. 브라우저 뒤로가기는 직전 Nuxt 화면을 복원해야 한다. - 진입 경로는 추후 메뉴/링크 설정을 통해 연결 ### 공개 URL 구조 - `/posts` - 게시물 전체 목록. 사이트 설정 POST 설정의 `postListPageSize` 값 기준으로 서버 페이지네이션을 사용하며, 페이지 번호가 바뀌면 화면을 상단으로 이동한다. 하단 페이지네이션은 이전·다음 화살표와 페이지 번호 직접 이동을 함께 제공하며, 전체 페이지가 많으면 첫 페이지·끝 페이지·현재 페이지 주변 번호를 유지하고 중간 구간은 `...`으로 접는다. 현재 페이지는 브랜드 포인트 배경색으로 표시한다. 같은 path에서 `page` query만 바뀌는 이동은 Nuxt 페이지 컴포넌트가 재사용될 수 있으므로 전역 전환 베일을 켜지 않는다. - `/post/:slug` - 개별 게시물 상세. 직접 접속·SSR과 클라이언트 내부 이동 모두 본문을 먼저 조회한 뒤 완성된 상세 화면으로 진입한다. 이동 시작 시 불투명 전환 베일을 즉시 표시하고, `page:finish` 이후 베일 뒤에서 스크롤을 최상단으로 맞춘 뒤 베일을 해제한다. 뒤로가기는 저장 스크롤 위치를 베일 뒤에서 복원한다. `history.scrollRestoration`은 `manual`로 두어 브라우저 자동 복원과 충돌하지 않게 한다. 이전·다음 글은 상세 API 응답의 `previous`·`next`로 표시하며, `previous`는 더 과거 글, `next`는 더 최신 글을 뜻한다. - `/` - 홈. 클라이언트 복귀 시에도 주요 데이터를 블로킹 조회한 뒤 전환한다. - 공개 전환 베일은 Nuxt `page:finish`뿐 아니라 브라우저 `pagehide`/`pageshow` BFCache 이벤트에서도 해제해, HTML 문서 페이지 이동 뒤 뒤로가기로 복원된 화면에 로딩 오버레이가 남지 않게 한다. - `/sitemap.xml` - 공개 sitemap XML. 홈, 게시물 목록, 태그 목록, 공개 발행글, 공개 고정 페이지, 글이 있는 태그 URL을 요청 시점 DB 기준으로 자동 생성한다. 멤버십·비공개·초안·예약 대기 글과 `noindex` 글은 포함하지 않는다. - `/robots.txt` - 크롤러 안내 파일. 관리자·API·회원 설정·로그인 경로를 제외하고 `Sitemap: /sitemap.xml` 절대 URL을 제공한다. - `/rss.xml`, `/feed.xml`, `/rss` - 최근 공개 발행글 RSS 2.0 피드. 멤버십·비공개·초안·예약 대기 글은 포함하지 않으며, 최신순 최대 50개를 XML로 응답한다. 게시물에 대표 이미지 또는 OG 이미지가 있으면 절대 URL로 변환해 `media:thumbnail`과 `media:content medium="image"`를 함께 포함한다. - `/tags` - 태그 전체 목록 - `/tag/:slug` - 태그별 게시물 목록. 사이트 설정 POST 설정의 `tagPostListPageSize` 값 기준으로 서버 태그 필터와 페이지네이션을 사용하며, 페이지 번호가 바뀌면 화면을 상단으로 이동한다. 하단 페이지네이션은 게시물 전체 목록과 같은 번호형 빠른 이동 UI를 사용한다. 등록되지 않은 태그 slug는 빈 목록 200이 아니라 404로 응답한다. - 태그명에 `/`를 입력하면 태그명은 그대로 저장하고 슬러그에서는 `/`를 `-`로 변환한다. 예: `Xenoblade3/Hero` 태그명은 `xenoblade3-hero` 슬러그로 저장한다. - `/tag/:slug` 화면의 헤더와 게시물 목록은 공개 목록 공통 섹션 패딩(`site-section-header`, `site-section-body`)을 사용해 메인 컬럼 좌우 여백을 다른 목록 화면과 맞춘다. - 태그에 `headerImageUrl`이 있으면 `/tag/:slug` 상단에는 기본 태그명·설명 대신 태그 헤더 이미지를 표시한다. `headerTitle`, `headerText`는 이미지 위 오버레이로 표시하며, 둘 다 비어 있으면 이미지 단독으로 표시한다. - `/signup` - 회원가입(3단계: 환영/입력/이메일 확인) - `/signin` - 로그인 - `/settings` - 회원 설정(썸네일 미리보기/변경/제거, 닉네임, 비밀번호, 회원 탈퇴) - 기존 `/posts/:slug`, `/tags/:slug` 상세 경로는 새 단수형 상세 경로로 리다이렉트한다. - 게시물·페이지 관리자 슬러그는 같은 입력 규칙을 사용한다. 허용 문자는 영문 소문자, 숫자, 한글, 하이픈(`-`), 언더바(`_`)이며 하이픈·언더바는 문자 사이 구분자로만 사용할 수 있다. ### 사이트 광고 슬롯 - 관리자 사이트 설정의 Ads 카드는 `adHomeFeedCode`, `adHomeInfeedCode`, `adSidebarCode`, `adPostSidebarCode`, `adPostTopCode`, `adPostInArticleCode`, `adPostBottomCode` 일곱 위치의 HTML 코드를 저장한다. `adPostSidebarCode`는 게시물 상세 오른쪽 사이드바의 TOC 아래 광고로 사용한다. - 관리자 사이트 설정의 **사이트 용량** 카드는 방문·유입 분석이 아니라 콘텐츠 수량과 업로드 파일 용량 점검용 텍스트 요약이다. 게시글·페이지·태그·댓글·회원 수와 이미지(원본·자동생성·프로필)·영상·보내기·오디오·첨부 파일·합계 개수·용량을 표시개수 설정과 같은 행 카드로 표시한다. - 각 값은 관리자만 입력하는 신뢰 콘텐츠를 전제로 하며, 애드센스에서 제공하는 반응형 또는 고정 크기 HTML 코드를 그대로 붙여 넣는다. - 공개 화면은 `SiteAdSlot` 컴포넌트로 광고 슬롯을 렌더링한다. 값이 비어 있으면 DOM을 만들지 않고, 값이 있으면 클라이언트에서 HTML을 삽입한 뒤 내부 script를 실행 가능한 노드로 교체해 Nuxt 클라이언트 라우팅 후에도 광고 코드가 동작하게 한다. - 공통 헤더·푸터 코드와 ads.txt는 기존 사이트 코드 카드에서 관리하고, 화면 위치가 필요한 광고 단위는 Ads 카드에서 관리한다. - 관리자 대시보드의 AdSense 요약은 `/admin/api/adsense/summary`에서 조회한다. 서버는 `GOOGLE_ADSENSE_CLIENT_ID`, `GOOGLE_ADSENSE_CLIENT_SECRET`, `GOOGLE_ADSENSE_REFRESH_TOKEN`, `GOOGLE_ADSENSE_ACCOUNT_NAME`을 사용해 Google access token을 발급하고 AdSense Management API `reports:generate`로 오늘 현재까지·어제·지난 7일·이번 달·최근 28일의 `ESTIMATED_EARNINGS`, `PAGE_VIEWS`, `IMPRESSIONS`, `CLICKS`, `PAGE_VIEWS_RPM`을 조회한다. 보고서 값은 `ReportResult.totals`를 우선 사용하고, 통화 표시는 응답 헤더의 currencyCode를 우선 따른다. 잔고는 AdSense Management API `payments.list`의 unpaid payment를 사용하며 Google이 지급 계정 통화로 포맷한 문자열을 그대로 표시한다. `GOOGLE_ADSENSE_CURRENCY_CODE`가 있으면 보고서 통화 코드로 전달하지만 지급 잔고에는 적용되지 않는다. 설정 누락 또는 API 오류 시 대시보드 전체를 실패시키지 않고 AdSense 카드 내부 상태로 제한한다. ### 공개 인증 화면(초기) - 회원가입 화면은 AFFiNE 참고 다크 테마 3단계 플로우를 제공한다. - 3단계는 인증 메일 발송 안내와 재전송 버튼(쿨다운)을 제공한다. - 이메일 링크 확인 전에는 회원가입이 완료되지 않으며, 인증 완료 액션 이후 로그인 화면으로 이동한다. - 로그인 화면은 동일한 다크 톤 폼 레이아웃을 사용한다. - 관리자 로그인 화면도 같은 다크 톤 폼 레이아웃을 사용하되, 일반 로그인과 구분되도록 폼을 화면 오른쪽에 배치하고 내부 타이틀·설명·필드·버튼도 오른쪽 정렬한다. - 로그인·회원가입(2단계)·관리자 로그인 비밀번호 입력은 `AuthPasswordVisibilityToggle` SVG(눈 열림/가림) 토글로 표시 여부를 바꾼다. 스크린 리더용 `aria-label`은 필드별 `field-name`으로 구분한다. 텍스트 입력은 `.auth-form-input`으로 글자색·캐럿 등을 보정한다. 회원가입 OTP 입력은 모바일 세로 배치에서 `flex-1`을 쓰지 않아 높이가 줄어들지 않게 한다. - 인증 화면 상태 메시지는 오류/안내를 분리해 `aria-live`로 노출한다. - 회원가입 1단계의 타이틀/설명은 `GET /api/site-settings`의 `title`, `description` 값을 우선 사용한다. - 회원 세션 쿠키 서명에는 `MEMBER_SESSION_SECRET`만 사용하며, 관리자 비밀번호를 fallback으로 쓰지 않는다. ### 레이아웃 파일 ``` layouts/ ├── default.vue # 메인/목록 화면 ├── post.vue # 게시물 화면 └── admin.vue # 관리자 화면 ``` - 존재하지 않는 공개 경로 또는 공개되지 않는 콘텐츠는 Nuxt 전역 오류 화면(`error.vue`)으로 처리한다. 404 화면은 상태 코드, 안내 문구, 홈 이동 버튼을 표시한다. ### 관리자 레이아웃 - 관리자 사이드바는 밝은 Ghost형 톤을 기준으로 하며, 메뉴 행은 아이콘+라벨 구조를 사용한다. - 관리자 로그인(`/admin/login`)을 제외한 관리자 화면은 공개 사이트 라이트/다크 테마와 분리된 라이트 UI로 고정한다. `admin-layout` 스코프에서 공개 테마 CSS 변수를 재정의하고, 글쓰기 화면을 제외한 일반 관리자 화면에만 폼 컨트롤 `color-scheme`을 라이트 값으로 재정의해 사용자 페이지 다크모드가 관리자 입력·테이블·패널 색상에 영향을 주지 않게 한다. - 관리자 사이드바는 데스크톱에서 320px 너비를 사용한다. - 관리자 우측 캔버스는 기본 `min-h-screen`과 `bg-paper`를 유지해 콘텐츠 높이가 짧아도 배경이 화면 전체를 채운다. 일반 관리자 화면은 레이아웃 레벨에서 넉넉한 외부 여백을 둔다. - 대시보드 메뉴는 관리자 기본 페이지(`/admin`)로 이동하는 활성 링크로 표시한다. - 게시글 메뉴 라벨은 `게시글`로 표시하고, 우측 `+` 아이콘은 `/admin/posts/new`로 바로 이동한다. - 관리자 글 목록의 태그 컬럼은 게시물 태그 배열의 첫 번째 항목만 대표 태그로 표시하며, 배지는 태그 고유 색상을 반영한다. - 관리자 글 목록의 태그 필터는 태그 증가에 대비해 검색형 combobox로 표시한다. 후보는 전체 태그 API의 사용 중 태그 기준으로 보여 주며, 검색어가 없으면 `전체 태그`와 태그명을 정렬한 목록을, 입력 중에는 태그명·슬러그 부분 일치 결과를 표시한다. 방향키와 Enter로 선택할 수 있고, 선택된 태그는 토큰의 `×`로 전체 태그 상태로 되돌린다. - 관리자 글 목록 API(`/admin/api/posts`)는 목록 최적화를 위해 게시물 본문 `content`를 반환하지 않는다. 기본 호출은 기존 호환용 배열을 반환하고, `paged=true` 쿼리를 보내면 `{ items, pagination, counts }` 구조를 반환한다. `page`, `pageSize`, `q`, `status`, `tag`, `featured`, `sort` 쿼리로 서버 검색·상태·태그·추천·정렬 필터를 적용하며 각 항목에 해당 글의 `/post/:slug` 공개 주소를 본문에 링크한 게시물·페이지 수 `backlinkCount`를 포함한다. 목록 검색은 제목·슬러그·요약·태그 기준으로 수행하고, 본문이 필요한 편집 화면은 `/admin/api/posts/:id` 상세 API를 사용한다. 관리자 전용 `adminPinned` 글은 공개 추천과 별개로 글 목록 정렬 최상단에 표시하며, 행 메뉴의 `상단 고정`·`고정 해제`에서 `/admin/api/posts/:id/pinned`로 토글한다. 백링크 열의 개수를 클릭하면 `/admin/api/posts/:id/references`로 링크한 게시물·페이지 목록을 조회해 고정 크기 모달로 표시하고, 모달 내부에서 제목·슬러그 검색과 관리자 수정 화면 이동 아이콘을 제공한다. - 관리자 글 목록의 추천 토글은 전체 게시물 저장 API가 아니라 `/admin/api/posts/:id/featured` 전용 PUT API에 `{ isFeatured }`만 보내 수정한다. - 관리자 글 목록의 대표 이미지 미리보기는 작은 카드 썸네일이 있으면 `featuredImageThumbnail`을 우선 사용하고, 없을 때만 원본 `featuredImage`를 fallback으로 사용한다. - 관리자 글 목록에서 입력창·모달 포커스가 아닐 때 `F` 또는 한글 키보드 `ㄹ` 키를 누르면 글 검색 입력창으로 포커스를 이동한다. - 관리자 페이지 목록은 게시글 목록과 같은 상단 구조를 사용한다. 제목 아래에는 전체·홈 표시·추천·필터 적용 표시 개수를 보여 주고, 오른쪽에는 검색·상태 필터·노출 필터·정렬·새 페이지 버튼을 한 줄 흐름으로 배치한다. 테이블은 추천 별, 페이지 커버 썸네일, 제목, 상태, 조회수, 수정일, 행 메뉴 순서로 표시한다. - 관리자 글쓰기의 Tags 입력은 배지형 다중 입력을 유지하며, 오른쪽 트리거로 태그 추천 목록을 열 수 있다. 입력이 비어 있으면 공개 발행글 기준 최근 사용 태그 5개를 먼저 표시한 뒤 메인 태그를 이어서 보여 주고, 입력 중에는 기존 태그 이름·슬러그 부분 일치 결과를 추천한다. 추천 목록은 방향키와 Enter로 선택할 수 있으며, 추천 항목을 선택한 뒤에도 태그를 더 추가할 수 있으면 남은 후보 목록을 유지한다. 선택된 태그 배지는 태그 고유 색상을 반영한다. 게시물별 태그 최대 개수는 기본 5개이며, 사이트 설정 POST 설정의 `postTagLimit` 값으로 1~10개 범위에서 조절한다. - 관리자 글쓰기 상단 왼쪽 상태 영역은 `Published`, `Scheduled`, `Members`, `Private`, 초안 저장 상태 등 현재 상태 텍스트만 표시하며, 공개 게시물 이동은 오른쪽 설정 패널의 `View Post` 링크에서만 제공한다. 초안 자동 저장이 중복 슬러그 등으로 실패하면 같은 입력값은 반복 재시도하지 않고, 사용자가 슬러그나 본문을 바꿔 저장 payload가 달라졌을 때 다시 자동 저장을 시도한다. 중복 슬러그 오류는 헤더 오류나 토스트가 아니라 Post URL 입력창 아래 빨간 텍스트로 표시하고, 슬러그를 다시 입력하면 숨긴다. 중복 슬러그 오류가 표시된 동안 Publish/Update/최종 저장 버튼은 비활성화한다. 오른쪽 설정 패널 하단에는 본문 기준 단어 수, 공백 제외 문자 수와 공백 수, 예상 읽기 시간, 블록 수, 이미지 수를 작은 통계로 표시한다. - 관리자 미디어 검색창은 글·멤버 목록과 같은 돋보기 아이콘 포함 입력 스타일을 사용한다. 미디어 라이브러리 탭에서는 파일 추가 버튼으로 `/admin/api/uploads`에 직접 업로드할 수 있고, 현재 폴더를 보고 있으면 업로드 후 해당 폴더로 배치한다. 미디어 관리 화면은 `/admin/api/media?paged=1` 응답을 사용해 서버에서 탭·폴더·파일 종류·미사용·검색 조건을 적용한 뒤 50·100·200개 단위 페이지네이션을 제공하며 번호와 이전·다음 버튼으로 이동한다. 현재 페이지 선택은 화면에 표시된 삭제 가능 항목만 대상으로 하며, 선택 삭제는 사용 중이거나 회원 프로필에 연결된 잠금 항목을 제외하고 삭제한다. 미디어 그리드와 글쓰기 이미지 선택 모달은 원본 삽입·상세 확인은 유지하되, 목록 미리보기에는 가능한 작은 본문 720px 파생 이미지나 카드 썸네일을 우선 사용한다. 글쓰기 이미지 선택 모달의 라이브러리 탭도 `/admin/api/media?paged=1&tab=library` 서버 페이지 응답을 사용하며 파일명과 사용처 제목(게시물·페이지 제목) 검색, 번호형 페이지 이동을 제공한다. 갤러리 미디어 선택 항목에는 선택 순서를 오른쪽 상단 배지로 표시하며, 선택 해제 시 뒤 항목 순서를 자동으로 당긴다. 게시글 대표 이미지 선택 모달도 `/admin/api/media?paged=1&tab=library&kind=image` 서버 페이지 응답, 파일명/사용처 검색, 번호형 페이지 이동, 작은 파생 이미지 우선 미리보기를 사용한다. 두 글쓰기 미디어 모달은 검색 결과 개수와 무관하게 패널 높이를 고정하고 내부 목록만 스크롤한다. - 메뉴 관리 항목은 `네비게이션`으로 표시한다. - 게시글·페이지·태그·미디어·네비게이션·멤버·설정 메뉴는 전용 SVG 아이콘을 사용한다. - 멤버 메뉴는 우측에 현재 총 멤버 수를 표시한다. - 로그아웃은 사이드바 상단 메뉴가 아니라 하단 사용자 썸네일 드롭다운 안에서 제공한다. 하단에는 사용자 썸네일 트리거와 설정 아이콘을 둔다. --- ## 컴포넌트 구조 ### 사이트 컴포넌트 ``` components/site/ ├── SiteHeader.vue # 상단 헤더 ├── SiteSearchModal.vue # 통합 검색 모달(`/`·헤더 검색 영역, Tags·Posts 결과) ├── LeftSidebar.vue # 왼쪽 사이드바 ├── RightSidebar.vue # 오른쪽 사이드바 ├── MainColumn.vue # 메인 컬럼 ├── PostCard.vue # 게시물 카드 └── TagHeader.vue # 태그 헤더 ``` ### 콘텐츠 렌더러 ``` components/content/ ├── ContentRenderer.vue # 콘텐츠 렌더러 ├── ProseHeading.vue # h1~h6 ├── ProseImage.vue # 이미지 (Regular/Wide/Full-width) ├── ProseList.vue # Ordered/Unordered List ├── ProseBlockquote.vue # 인용구 ├── ProseButton.vue # 버튼 (Left-aligned/Centered) ├── ProseCallout.vue # Callout 카드 ├── ProseToggle.vue # Toggle 카드 ├── ProseVideo.vue # Video 카드 ├── ProseAudio.vue # Audio 카드 ├── ProseFile.vue # File 카드 ├── ProseProduct.vue # Product 카드 ├── ProseBookmark.vue # 북마크 카드(썸네일·제목·도메인) ├── ProseSignup.vue # 회원가입/뉴스레터 CTA 카드 ├── ProseHeaderCard.vue # Header 카드 (Simple/Wide/Full-width/Split) └── ProseEmbed.vue # HTML embeds (YouTube iframe, Twitter/X iframe, 사용자 iframe, 기타 링크) ``` ### 공개 본문 스타일 가이드(Thred 기준) - 리스트 - Unordered: `- 항목` - Ordered: `1. 항목` - 렌더링: `ProseList.vue` (마커 컬러는 글쓰기 화면과 같은 파란 계열, 간격, 줄높이 통일) - 인용구 - 기본: `> 한 줄` 또는 `>` 연속 여러 줄(멀티라인) - 대체 스타일(Alternative): `>>>`로 시작해 `<<<`로 끝나는 블록 - 렌더링: `ProseBlockquote.vue` (`variant=default|alt`, 기본 인용은 다크모드에서도 밝은 배경 위 어두운 텍스트 유지) - 기본 인용 배경은 회색이며, `> [!bg=gray|blue|green|yellow|red|purple]` 옵션 줄로 색상을 지정한다. 분홍 옵션은 사용하지 않는다. - 관리자 라이브 작성 모드에서도 인용 블록에 포커스가 들어오면 오른쪽 블록 설정 패널에서 배경색을 수정한다. - 이미지 - 기본: `![](url)` — 이미지 아래 캡션 없음 - 캡션(표시용): `![](url "캡션")` — 따옴표 안 문자열만 `ProseImage` figcaption으로 표시 - **파일명을 캡션으로 사용** 토글: URL 파일명을 캡션으로 저장·표시(`![](url "파일명")`). 레거시 `![파일명](url)`도 동일하게 해석 - 와이드/풀: `![alt](url){width=wide|full}` 또는 캡션·width 조합 - 렌더링: `ProseImage.vue` (라운드/보더/패널 배경). 클릭 시 라이트박스로 확대하며, 같은 게시물 안의 단일 이미지와 갤러리 이미지를 `lib/content-gallery-images.js` 기준 문서 순서대로 하나의 그룹으로 묶어 Esc 닫기·←/→ 이전·다음 탐색을 지원한다. 라이트박스 상태와 키보드 이벤트 연결은 `useContentMarkdownLightbox`에서 관리한다. - 이미지 갤러리 - `:::gallery` ~ `:::` fenced block 내부에 이미지 마크다운 행을 여러 개 작성 - 렌더링: `ContentMarkdownRenderer.vue` (최대 3개 단위 행 + 게시물 전체 이미지 라이트박스, Esc 닫기·←/→ 이전·다음). 행 분할은 `lib/content-gallery-images.js`에서 수행하고, 라이트박스 목록 생성은 `useContentMarkdownBlocks`, 라이트박스 상태 관리는 `useContentMarkdownLightbox`, 라이브 모드 단일 이미지·갤러리 드래그 이벤트 중개는 `useContentMarkdownImageDrag`에서 수행한다. - 갤러리 행은 1개일 때 전체 폭, 2~3개일 때 행 전체 폭을 나눠 쓰며 이미지 로드 후 자연 비율(가로/세로)에 따라 셀 너비를 조정한다. - 비디오·오디오·파일 카드 - 비디오: `:::video` ~ `:::` (`url`, `title`, `poster`, `caption` 키값 또는 URL 단독 줄) - 오디오: `:::audio` ~ `:::` (`url`, `title`, `description`) - 파일: `:::file` ~ `:::` (`url`, `title`, `description`, `name`, `size`) — 다운로드 링크 카드 - 렌더링: `ProseVideo.vue`, `ProseAudio.vue`, `ProseFile.vue` - 관리자 슬래시: `/video`, `/audio`, `/file`로 빈 템플릿 삽입 후 URL·메타 수정 - 관리자 미디어 화면은 미디어 라이브러리·카드 썸네일·본문 이미지·프로필 이미지 탭으로 구분한다. 미디어 라이브러리 탭은 원본 업로드 파일만 표시하고, 게시물 목록용 `thumbs/*-card.webp` 파생 파일은 카드 썸네일 탭에만, 본문용 `thumbs/*-body-1600.webp`·`*-body-720.webp`·`*-body-2560.webp` 파생 파일과 레거시 `*-body.webp`·`*-lightbox.webp` 파일은 본문 이미지 탭에만 표시한다. 게시물 글쓰기의 대표 이미지와 본문 `/이미지`·`/갤러리` 선택 모달은 파생 파일을 숨기고 원본 이미지만 선택하게 한다. 본문 미디어 모달은 업로드 탭을 먼저 열고, 업로드 완료 후 라이브러리에서 새 파일을 자동 선택한다. - 게시물 생성·수정 API는 `thumbs/*-card.webp` 카드 썸네일 URL을 대표 이미지로 저장하지 못하게 검증한다. 카드 썸네일은 원본 대표 이미지 저장 후 목록 표시용으로만 자동 생성한다. - 링크·iframe·HTML 블록은 위 블록과 불필요하게 벌어지지 않도록 상단 외부 여백 없이 표시하고, 다음 블록과 구분되는 하단 여백만 유지한다. - 관리자 미디어 화면의 미디어 라이브러리 탭은 전체·이미지·영상·음악·파일 종류 필터와 미사용 필터를 제공한다. 미사용은 게시물·페이지·사이트 설정·태그 헤더·네비게이션 추천 사이트 파비콘·회원 프로필에서 참조되지 않는 항목을 의미한다. 비디오 항목은 브라우저에서 초반 프레임을 캔버스로 추출해 목록 썸네일로 표시하고, 추출 실패 시 `video` placeholder를 유지한다. 서버의 디스크 파일·콘텐츠 사용처 전체 스캔 결과는 30초 동안 공유하며 동시 요청은 같은 조회 Promise를 사용한다. 업로드·삭제·이름/폴더 변경·파생 이미지 재생성은 캐시를 즉시 무효화한다. - 카드 썸네일 탭의 항목은 원본 대표 이미지가 사용 중이면 `목록 카드 썸네일` 사용처를 가진 것으로 판정한다. 원본 대표 이미지가 사용 중이지만 카드 썸네일 파일이 없으면 원본 항목에 `원본` 배지와 “목록에서 원본 이미지를 불러옴” 상태를 표시한다. 페이지 대표 이미지는 페이지 커버 썸네일 상태를 우선하고, 커버 파일이 없으면 같은 `원본` 배지로 표시한다. 카드 썸네일은 원본과의 연결을 유지하기 위해 폴더 이동과 파일명 변경을 막고, 사용 중이면 삭제도 막는다. - 프로필 이미지 사용 개수 배지는 `avatarOwner`(회원 프로필 연결) 1과 게시물·페이지 등 다른 사용처만 합산한다. 같은 프로필 URL의 `user.avatarUrl` 참조를 사용처 배열에 다시 넣어 중복 합산하지 않는다. - 문단과 줄바꿈 - 관리자 Markdown-first 에디터에서 Enter는 새 문단(마크다운 한 줄)만 사용한다. Shift+Enter·문단 내 hard break는 지원하지 않는다. - 공개 본문 렌더러는 마크다운 한 줄을 한 문단으로 렌더링한다(레거시 줄끝 `\\`/공백 2개 표식은 표시 시 제거). - 내용 없는 빈 줄과 레거시 빈 문단 마커(`<!--sori:blank-paragraph-->`)는 spacer 블록으로 렌더링해 작성자가 비운 줄 수만큼 공백을 보존한다. - 문단 하단 기본 간격은 10px(`mb-2.5`) 기준이며, 문단 글자 크기는 `ContentMarkdownRenderer` 문단에 `text-base`(16px·`1rem`)만 지정하고 행간은 Tailwind·브라우저 기본에 맡긴다. - 제목은 `ProseHeading`에서 단계별 크기·굵기를 적용하고, 첫 제목(`first:`)을 제외한 상단 추가 여백은 컴포넌트 스타일로만 조정한다. - 카드류 - Callout: `:::callout` ~ `:::` (왼쪽 강조선은 `var(--site-accent)`) - Toggle: `:::toggle 제목` ~ `:::` - Bookmark: `:::bookmark` ~ `:::` (본문은 `url=`, `title=`, `description=`, `thumbnail=` 키값 또는 첫 줄 URL·이어지는 제목/설명 줄) - Signup: `:::signup` ~ `:::` (선택: `title=`, `description=`, `button=`, `placeholder=`) - Link: `:::link` ~ `:::`. YouTube·YouTube Shorts URL은 iframe, `twitter.com`·`x.com` 게시물 URL은 X 공식 embed iframe, 그 외 URL은 외부 링크 카드 - iframe: `:::iframe` ~ `:::`. iframe HTML에서 안전 속성만 추출해 sandbox iframe으로 표시 - HTML: `:::html` ~ `:::`. 표·문단·목록·기본 이미지 등 허용 목록의 HTML만 표시한다. script, iframe, SVG, form 계열 태그, 이벤트 속성, 인라인 style, 실행 URL은 parser 기반 sanitizer가 제거한다. - 렌더링: `ProseCallout.vue`, `ProseToggle.vue`, `ProseBookmark.vue`, `ProseSignup.vue`, `ProseEmbed.vue`, `ProseHtml.vue` --- ## 데이터베이스 구조 ### 환경 분리 원칙 - 데이터베이스는 PostgreSQL을 기준으로 한다. - 로컬 개발 환경과 NAS 운영 환경은 서로 다른 DB를 사용 - 로컬 개발 서버는 개발 DB만 연결 - NAS 배포 환경은 운영 DB만 연결 - 운영 환경(`NODE_ENV=production`)에서는 `DATABASE_URL` 누락 시 샘플 콘텐츠로 대체하지 않고 서버 오류로 즉시 실패 - Docker Compose는 전용 브리지 네트워크를 사용하며 기본 subnet은 `DOCKER_SUBNET`(`10.250.50.0/24`)으로 관리 - Docker Compose의 PostgreSQL 호스트 포트는 기본 `DB_BIND_ADDRESS=127.0.0.1`에만 바인딩한다. 앱 컨테이너는 호스트 공개 포트가 아니라 `sori-studio-db:5432` 내부 네트워크를 사용한다. - 운영 DB 접속 정보는 로컬 기본 `.env`에 기록하지 않음 - DB 관리 도구는 CloudBeaver 등을 사용할 수 있도록 접속 정보를 환경별로 분리 ### 마이그레이션 적용 이력 - `schema_migrations` 테이블은 적용 완료된 SQL 파일명을 `file_name` 기준으로 기록한다. - `npm run db:migrate:dev`와 `npm run db:migrate:prod`는 `db/migrations/*.sql` 중 `schema_migrations`에 없는 파일만 순서대로 실행한다. - 각 마이그레이션 파일 실행과 `schema_migrations` 이력 INSERT는 하나의 `psql --single-transaction` 안에서 처리해 둘 중 하나가 실패하면 함께 롤백한다. - `sh scripts/migrate-production-db.sh status`는 npm이 없는 NAS 호스트에서도 운영 DB의 적용/대기 파일 목록을 출력한다. - 기존 운영 DB에 `posts` 테이블은 있지만 `schema_migrations`가 없으면 `sh scripts/migrate-production-db.sh migrate`는 데이터 보호를 위해 001부터 자동 실행하지 않고 중단한다. - 기존 운영 DB가 현재 코드 기준으로 이미 최신이면 `sh scripts/migrate-production-db.sh baseline`으로 현재 마이그레이션 파일들을 실행 없이 적용 완료로 기록한 뒤 이후 새 파일만 적용한다. ### Posts (블로그 글) | 필드 | 타입 | 설명 | |------|------|------| | id | UUID | Primary Key | | title | String | 제목 | | slug | String | URL 슬러그 | | content | Text | Markdown 콘텐츠 | | excerpt | String | 요약 | | featured_image | String nullable | 목록·공유용 대표 이미지 | | show_featured_image | Boolean | 게시물 상세 제목 아래 대표 이미지 표시 여부 | | is_featured | Boolean | 홈 Featured 및 목록 번개 표시용 추천 글 여부 | | seo_title | String | SEO 제목 | | seo_description | String | SEO 설명 | | canonical_url | String | canonical URL | | noindex | Boolean | 검색엔진 노출 제외 여부 | | og_image | String nullable | OG 이미지 | | search_text | Text | 공개 통합 검색용 정규화 텍스트. DB 트리거가 제목·요약·본문에서 자동 생성 | | status | Enum | `published` / `draft` / `members` / `private`(예약은 `published` + 미래 `published_at`) | | published_at | DateTime | 발행일 | | created_at | DateTime | 생성일 | | updated_at | DateTime | 수정일 | > API 응답의 게시물 객체는 원본 대표 이미지 `featuredImage`, 상세 상단 표시 여부 `showFeaturedImage`, 목록용 카드 썸네일 `featuredImageThumbnail`, `isFeatured`, `commentCount`를 함께 반환한다. `commentCount`는 `published` 상태 댓글 수를 기준으로 한다. `tags`는 게시물에 저장된 태그 연결 순서(`post_tags.sort_order`)를 따른다. > 공개 게시물 목록·상세는 `published` 상태만 기본 노출하며, `members` 상태는 VIP 이상 등급(`vip`/`admin`/`owner`) 회원에게만 노출한다. `private`와 `draft`는 공개 화면에서 노출하지 않는다. ### PostExportJobs / PostExportFiles | 필드 | 타입 | 설명 | |------|------|------| | post_export_jobs.id | UUID | Export 작업 ID | | post_export_jobs.requested_by | UUID nullable | 요청 관리자 회원 ID | | post_export_jobs.requested_email | String | 요청 당시 관리자 이메일 | | post_export_jobs.status | Enum | `queued` / `processing` / `ready` / `failed` / `expired` | | post_export_jobs.scope | Enum | `all` / `author` | | post_export_jobs.post_count | Integer | 작업 대상 게시물 수 | | post_export_jobs.processed_count | Integer | 처리 완료 게시물 수 | | post_export_jobs.current_part_index | Integer nullable | 현재 처리 중인 분할 순번 | | post_export_jobs.chunk_size | Integer | ZIP당 최대 게시물 수 안전 상한 | | post_export_jobs.max_file_size_bytes | BigInt | 분할 ZIP 목표 최대 용량 바이트 | | post_export_jobs.retention_days | Integer | 보존 일수, 최대 100 | | post_export_jobs.date_from | DateTime nullable | Export 대상 게시물 기준일 시작 시각, null이면 시작 제한 없음 | | post_export_jobs.date_to | DateTime nullable | Export 대상 게시물 기준일 종료 시각(exclusive), null이면 종료 제한 없음 | | post_export_jobs.range_label | String | 관리자 화면과 파일명에 표시할 범위 라벨 | | post_export_jobs.expires_at | DateTime | 만료 예정 시각 | | post_export_jobs.message | Text | 작업 메시지 | | post_export_jobs.progress_message | Text | 진행 상세 메시지 | | post_export_jobs.error_detail | Text | 실패 시 상세 오류 로그 | | post_export_jobs.started_at | DateTime nullable | 작업 시작 시각 | | post_export_files.id | UUID | 분할 파일 ID | | post_export_files.job_id | UUID | FK → PostExportJobs | | post_export_files.part_index | Integer | 분할 순번 | | post_export_files.post_start | Integer | 해당 zip의 시작 게시물 순번 | | post_export_files.post_end | Integer | 해당 zip의 끝 게시물 순번 | | post_export_files.file_name | String | `사이트명_범위_시작번호-끝번호.zip` 파일명 | | post_export_files.file_path | String | 실제 생성 파일 경로, 생성 전 빈 값 | | post_export_files.file_size_bytes | BigInt | 파일 크기, 생성 전 0 | | post_export_files.status | Enum | `pending` / `processing` / `ready` / `failed` / `expired` | ### Users | 필드 | 타입 | 설명 | |------|------|------| | id | UUID | Primary Key | | username | String | 사용자명 | | email | String | 로그인 이메일(유니크) | | password_hash | String | bcrypt 해시 비밀번호 | | avatar_url | String | 프로필 썸네일 URL | | is_admin | Boolean | 관리자 권한 여부 | | user_role | Enum | 권한 단계(`owner`/`admin`/`vip`/`member`) | | session_version | Integer | 현재 유효한 로그인 세션 버전. 비밀번호 변경 시 1 증가 | | last_seen_at | DateTime nullable | 마지막 접속 시각 | | last_seen_ip | String | 마지막 접속 IP | | created_at | DateTime | 생성일 | | updated_at | DateTime | 수정일 | ### Comments | 필드 | 타입 | 설명 | |------|------|------| | id | UUID | Primary Key | | post_id | UUID | FK → Posts | | user_id | UUID | FK → Users | | parent_id | UUID nullable | FK → Comments, 대댓글 1단 | | body | Text | 댓글 본문 | | status | Enum | published/pending/blocked | | created_at | DateTime | 생성일 | | updated_at | DateTime | 수정일 | ### CommentLikes | 필드 | 타입 | 설명 | |------|------|------| | comment_id | UUID | FK → Comments | | user_id | UUID | FK → Users | | created_at | DateTime | 생성일 | ### Pages (고정 페이지) | 필드 | 타입 | 설명 | |------|------|------| | id | UUID | Primary Key | | title | String | 제목 | | slug | String | URL 슬러그 | | content | Text | HTML 문서 원문 또는 일반 텍스트 콘텐츠 | | render_mode | String | 렌더링 방식(`html_document`, `markdown`) | | featured_image | String nullable | 홈 Pages 진열장 커버 이미지 | | is_listed | Boolean | 홈 Pages 진열장 노출 여부 | | is_featured | Boolean | 홈 Pages 진열장 추천 표시 및 우선 정렬 | | listing_section | String | 홈 Pages 진열장 섹션명 | | listing_title | String | 홈 Pages 진열장·검색 결과용 제목(비어 있으면 페이지 제목 사용) | | listing_description | String | 검색 결과·관리용 목록 설명 | | listing_sort_order | Integer | 섹션 내 정렬 순서 | | search_text | Text | 공개 통합 검색용 정규화 텍스트. DB 트리거가 제목·섹션·목록 설명·본문에서 자동 생성 | | status | Enum | `published` / `draft` / `private` | | created_at | DateTime | 생성일 | | updated_at | DateTime | 수정일 | ### Page Listing Sections | 필드 | 타입 | 설명 | |------|------|------| | id | UUID | 섹션 ID | | name | String | 홈 Pages 진열장 섹션명. 페이지의 `listing_section`과 매칭 | | sort_order | Integer | 홈 Pages 진열장 섹션 표시 순서 | | created_at | DateTime | 생성일 | | updated_at | DateTime | 수정일 | ### Tags | 필드 | 타입 | 설명 | |------|------|------| | id | UUID | Primary Key | | name | String | 태그명 | | slug | String | URL 슬러그 | | description | String | 설명 | | sort_order | Integer | 메인 태그 정렬 순서 | | color | String | 태그 색상 코드 | | tag_type | Enum | 태그 유형(`managed`/`general`) | | created_at | DateTime | 생성일 | | updated_at | DateTime | 수정일 | ### SiteSettings | 필드 | 타입 | 설명 | |------|------|------| | id | Integer | 단일 설정 레코드 ID, 항상 1 | | title | String | 사이트 이름 | | description | String | 사이트 설명 | | site_url | String | 사이트 기본 URL | | logo_text | String | 레거시 텍스트 로고 fallback | | logo_url | String | 공개 로고 이미지 URL | | favicon_url | String | 파비콘 이미지 URL | | show_post_updated_at | Boolean | 관리자 글 목록 수정일 보조 표시 여부 | | post_tag_limit | Integer | 게시물별 태그 최대 개수, 기본 5, 허용 범위 1~10 | | upload_max_file_count | Integer | 관리자 미디어 1회 업로드 최대 파일 수, 기본 20, 허용 범위 1~50 | | upload_max_total_size | BigInt | 관리자 미디어 1회 업로드 최대 전체 용량 바이트, 기본 300MB, 허용 범위 1MB~1GB | | home_cover_image_url | String | 라이트모드 홈 커버 이미지 URL | | home_cover_dark_image_url | String | 다크모드 홈 커버 이미지 URL | | home_cover_title | String | 홈 커버 오버레이 제목 | | home_cover_text | Text | 홈 커버 오버레이 본문 | | announcement_enabled | Boolean | 공개 어나운스 바 사용 여부 | | announcement_text | Text | 어나운스 바 문구 | | announcement_url | String | 어나운스 바 링크 URL | | announcement_background_color | String | 어나운스 바 배경색 | | signup_blocked_usernames | JSON Text | 가입 금지 닉네임 목록 | | ads_txt | Text | 루트 `/ads.txt` 응답 본문 | | custom_head_code | Text | 공개 HTML head 끝에 삽입할 코드 | | custom_footer_code | Text | 공개 HTML body 끝에 삽입할 코드 | | copyright_text | String | 저작권 문구 | | updated_at | DateTime | 수정일 | ### NavigationItems | 필드 | 타입 | 설명 | |------|------|------| | id | UUID | Primary Key | | label | String | 메뉴 표시 이름 | | url | String | 내부 경로 또는 외부 URL | | location | Enum | primary / footer / recommended | | sort_order | Integer | 표시 순서 | | is_visible | Boolean | 공개 화면 표시 여부 | | created_at | DateTime | 생성일 | | updated_at | DateTime | 수정일 | ### MediaMetadata | 필드 | 타입 | 설명 | |------|------|------| | url | String | 업로드 미디어 URL | | category | String | 논리 폴더 경로(게시물 업로드 이미지는 `미분류`, 회원 아바타는 예약값 `썸네일` 등) | | created_at | DateTime | 생성일 | | updated_at | DateTime | 수정일 | ### MediaFolders | 필드 | 타입 | 설명 | |------|------|------| | path | String | 미디어 폴더 경로 | | created_at | DateTime | 생성일 | | updated_at | DateTime | 수정일 | ### PostTags (다대다) | 필드 | 타입 | 설명 | |------|------|------| | post_id | UUID | FK → Posts | | tag_id | UUID | FK → Tags | | sort_order | Integer | 게시물 내 태그 표시 순서 | | created_at | DateTime | 생성일 | ### Analytics (자체 최소 통계) > 마이그레이션 `030_analytics_daily_stats.sql`. 원문 IP·User-Agent·쿠키 ID는 저장하지 않는다. 서버는 `date + IP + User-Agent + secret`으로 일 단위 `visitor_hash`만 생성·저장한다. | 테이블 | 필드 | 설명 | |--------|------|------| | site_analytics_daily | day, page_views, visitors, engaged_views, total_engaged_seconds | 사이트 일별 페이지뷰·방문자·체류 집계 | | post_analytics_daily | day, post_id, views, reads, visitors, engaged_views, total_engaged_seconds, scroll_25~100 | 게시물 일별 조회·읽음·스크롤 구간 | | post_analytics_traffic_daily | day, post_id, source_group, source_name, device_type, os_name, keyword, page_views, visitors | 게시물별 유입원·디바이스·키워드 일별 축약 집계 | | page_analytics_daily | day, page_id, views, visitors, engaged_views, total_engaged_seconds, scroll_25~100 | 페이지 일별 조회·방문자·스크롤 구간 | | analytics_traffic_daily | day, source_group, source_name, device_type, os_name, keyword, page_views, visitors | 유입원·디바이스·키워드 일별 축약 집계 | | analytics_daily_visitors | day, scope(`site`/`post`/`page`/`traffic`), post_id?, page_id?, visitor_hash, source_group?, source_name?, device_type?, os_name?, keyword? | 일별 방문자 해시 등록(중복 방문 제거용) | | analytics_active_sessions | session_hash, user_id?, path, post_id?, post_slug, page_id?, page_slug, ip_address, duration_seconds, max_scroll_ratio, last_seen_at | 실시간 접속 세션(TTL 90초) | - 추적 대상: 공개 경로만. `/admin`, `/signin`, `/signup`, `/forgot-password`, `/settings`는 제외. - 관리자 세션(`sori_admin_session`)이 있는 요청은 공개 경로라도 페이지뷰, 게시물 읽음, heartbeat 체류·스크롤, 실시간 접속자 집계에 포함하지 않는다. - 봇 User-Agent는 서버에서 무시. - 페이지뷰 수집은 탭 최초 referrer와 현재 URL을 서버로 보내며, 서버는 원문 referrer를 저장하지 않고 검색·SNS·직접·기타, 디바이스·OS, 검색 키워드로 축약해 `analytics_traffic_daily`에 집계한다. - 검색 유입은 네이버·다음·구글·줌·빙을 우선 분류하고, SNS 유입은 카카오톡·페이스북·인스타그램·트위터/X·유튜브를 우선 분류한다. 검색 키워드는 referrer query에 남아 있는 경우만 표시한다. - 게시물 `reads`는 클라이언트에서 15초 이상 체류·50% 이상 스크롤 후 별도 전송. - `POST /api/analytics/heartbeat`는 20초 간격으로 체류시간·스크롤·현재 경로를 전송한다. 로그인 사용자는 서버 세션으로 `user_id`를 연결한다. - 관리자 대시보드는 `GET /admin/api/analytics/realtime`으로 현재 접속자 목록(닉네임·아바타·대표 게시물 제목·접속 유지시간·IP·열린 페이지 수·열린 페이지 제목 목록)을 조회한다. 현재 접속자는 로그인 사용자는 회원 기준, 익명 방문자는 IP 기준으로 묶어 같은 사람이 여러 페이지를 열어도 1명으로 표시하되, 묶음 안의 활성 페이지는 목록으로 함께 표시한다. 상단 요약은 현재 접속자·오늘 방문자·누적 방문자·게시물 수를 표시한다. - 관리자 대시보드 **통계 추이**는 `trends` 데이터를 3개 막대 차트(방문자수·평균 체류시간·50% 스크롤 도달)로 표시한다. 선택지는 일간·주간·월간·년간이며 기본값은 일간이다. 집계는 `ANALYTICS_COLLECTED_SINCE` 환경 변수(기본 `2026-06-01`) 이후 데이터만 합산하고 그 이전 구간은 0으로 표시한다. **방문자수** 막대는 검색(빨강)·SNS(청록)·기타(회색) 유입 비율을 스택으로 표시하며, hover 시 해당 막대만 색상을 강조한다. 안내 문구는 `통계는 2026년 6월 1일부터 집계한 데이터를 표시합니다.` 형식이다. 막대 hover/focus 시 기간과 정확한 값을 툴팁으로 표시하며, 막대 클릭 시 하단 **선택한 기간 상세** 패널을 해당 날짜 또는 묶음 구간 기준으로 갱신한다. 표(table)나 외부 차트 라이브러리는 사용하지 않는다. - 관리자 대시보드 **선택한 기간 상세**는 기본값으로 오늘 통계를 표시하고, 차트 막대 클릭 시 선택 범위의 페이지뷰·방문자·평균 체류·50% 스크롤·검색/SNS/직접 포함 유입원·디바이스/OS·인기 게시물·인기 페이지를 표시한다. 자동 갱신 중에는 사용자가 선택한 날짜·기간을 유지하고, 상세 재조회 중에도 기존 내용을 유지해 화면 높이가 줄어들지 않게 한다. 인기 게시물·인기 페이지는 데스크톱에서 왼쪽 75% 영역에 세로 목록으로 표시하고, 유입·디바이스는 오른쪽 25% 영역에 세로 배치한다. 디바이스는 모바일·PC 같은 상위 기기 기준으로 한 카드에 합산하고, 상위 기기 제목 오른쪽에 방문자 수·조회수·전체 디바이스 방문자 대비 비율을 한 줄로 표시한다. 카드 안의 Android/iOS/Windows 같은 OS별 목록은 방문자 수와 전체 디바이스 방문자 대비 비율만 표시한다. 인기 콘텐츠 메타는 `V 조회`, `R 읽음/방문자`, `M 최근 30일 조회`, `C 작성일`, `S 50/75/100% 스크롤` 형식의 한 줄 압축 표기를 사용한다. `V/R/M` 알파벳만 서로 다른 색상으로 강조하고 숫자는 보조 텍스트 색상으로 표시한다. 구분자 `|`는 연한 회색으로 표시하며, `S`의 50/75/100 스크롤 값은 단계가 깊어질수록 진하게 표시한다. 관리자 통계 응답은 표시 안정성을 위해 `읽음 <= 조회`, `100% 스크롤 <= 75% 스크롤 <= 50% 스크롤 <= 조회` 범위로 정규화한다. 유입 프로그래스 바는 보조 지표로 보이도록 카드 폭의 절반만 사용한다. 검색엔진이 대부분 검색어를 전달하지 않는 현실을 반영해 대시보드의 유입 키워드 영역은 표시하지 않는다. - 관리자 글 목록은 게시물별 `post_analytics_daily.views` 누적 합계를 별도 조회수 열에 `1,000`처럼 숫자만 표시하고, 같은 셀 아래 작은 회색 통계 버튼으로 게시물별 통계 모달을 연다. 통계 버튼은 hover 시에만 파란색으로 표시한다. - 관리자 게시물별 통계 모달과 상세 화면은 누적 조회수, 조회수/방문자 추이, 읽음·평균 체류·스크롤 지표, 게시물별 유입원·디바이스·유입 키워드를 표시한다. 추이는 일간(최근 14일), 주간(최근 12주, 일요일~토요일), 월간(최근 12개월) 단위로 전환한다. 게시물별 유입은 `059_post_analytics_traffic_daily.sql` 적용 이후 새로 수집되는 페이지뷰부터 집계된다. - 관리자 대시보드 추이 차트는 일일 7개, 주간 최대 8개, 월간 12개, 년간 최대 8개 버킷을 조회한다. 게시물별 통계와 기타 인기/유입 목록 API는 기존 최대 365일 조회 제한을 유지한다. - `site_analytics_daily`, `post_analytics_daily`, `analytics_traffic_daily`는 사이트 전체 방문자와 게시물별 조회수, 유입 통계 누적 원본이므로 자동 삭제하지 않는다. - `analytics_daily_visitors`는 일별 중복 방문 제거용이며, 수집·조회 흐름에서 32일보다 오래된 행을 주기적으로 삭제한다. - `analytics_active_sessions`는 현재 접속자 목록용이며, 90초보다 오래된 행을 삭제한다. IP는 실시간 익명 접속자 묶음 표시용으로만 저장하고, 방문자 통계 고유성은 기존 해시 기반 집계를 유지한다. --- ## API 구조 > 현재 API는 Nuxt `server/api` 내부에 샘플 데이터 기반으로 구현되어 있다. DB 연결 후 같은 응답 구조를 유지하되 저장소만 교체한다. ### 백엔드 구성 - 별도 `backend/` 앱을 두지 않고 Nuxt/Nitro 서버 기능을 사용 - 공개 API는 `server/api`에 작성 - 서버 공통 스키마와 샘플 데이터는 `server/utils`에 작성 - PostgreSQL 연결과 조회 로직은 `server/repositories`에 작성 - `DATABASE_URL`이 없으면 샘플 데이터 저장소를 사용 - 초기 단계에서는 같은 앱 배포로 관리 비용을 낮춤 - 독립 API 서버가 필요해지는 시점에만 백엔드 분리를 재검토 ### 공개 API (`/api/`) - `GET /api/posts` - 게시물 목록. `limit`, `featured=1`, `tag=:slug` 쿼리로 서버 목록 범위를 제한할 수 있다. `limit`을 생략해도 서버 기본 표시 개수 상한을 적용하며 목록 항목에는 전체 `content`를 포함하지 않고 최대 320자의 정리된 `excerpt`만 반환한다. `paginated=1&page=N&limit=N`이면 `{ items, pagination }` 형태로 응답하고, 없으면 기존처럼 배열을 반환한다. - `GET /api/posts/:slug` - 게시물 상세. 응답에 목록과 같은 발행일 정렬 기준의 인접 글을 `previous`(더 최신)·`next`(더 예전) 객체(`{ title, slug }` 또는 `null`)로 포함해, 게시물 상세 하단 이전·다음 글 이동에 전체 목록 조회 없이 바로 사용한다. - `GET /api/posts/:slug/comments` - 게시물 댓글 목록. 일반 공개 글 또는 현재 회원이 본문 접근 가능한 멤버십 글만 허용한다. - `POST /api/posts/:slug/comments` - 게시물 댓글 작성(회원 세션 필요, 대댓글 1단). 멤버십 글은 VIP 이상 본문 접근 권한을 함께 확인한다. - `POST /api/posts/:slug/comments/:commentId/like` - 댓글 좋아요 토글(회원 세션 필요). 대상 게시물의 일반/멤버십 접근 정책을 댓글 목록과 동일하게 적용한다. - `GET /api/pages` - 공개 고정 페이지 목록. `?listed=1`이면 홈 Pages 진열장에 노출할 공개 페이지만 반환하며, 홈 목록 성능을 위해 `content`는 빈 문자열로 내려준다. `listed=1&limit=N`이면 섹션별 최대 N개만 반환한다. - `GET /api/pages/:slug` - 고정 페이지 상세 - `GET /api/tags` - 태그 목록. 기본값은 메인 태그(`managed`)만 반환하며, `?tagType=all`은 일반 태그를 포함한 전체 태그 메타를 반환한다. `postCount`는 공개 발행 게시물 기준이다. - `GET /api/search?q=` - 통합 검색. 태그는 `name`·`slug`, 게시물은 DB 트리거가 갱신하는 `posts.search_text`, 홈 표시 페이지는 `pages.search_text` 기준으로 부분 일치한다. `search_text`는 제목·요약·본문·페이지 섹션/목록 설명에서 업로드 경로와 이미지 마크다운 토큰을 제거한 정규화 문자열이며 `pg_trgm` GIN 인덱스를 사용한다. - `GET /api/site-settings` - 공개 사이트 설정(어나운스 바·홈 커버 등 포함) - `GET /api/homepage-widget` - gethomepage customapi용 공개 블로그 통계. 기본 필드 `title`, `updatedAt`, `todayVisitors`, `totalVisitors`, `todayPageViews`, `totalPageViews`, `visitorsLast7Days`, `visitorsLast30Days`, `visitorsLast180Days`, `visitorsLast365Days`, `pageViewsLast30Days`, `onlineNow`, `loggedInNow`, `avgEngagedSeconds`, `totalPosts`, `totalComments`, `totalPages`, `totalTags`, `totalMembers`, `items[]`를 반환한다. 기간별 방문자는 최근 7·30·180·365일의 일별 순방문자 합계다. `totalVisitors`는 날짜별 순방문자 수의 누적 합계라 동일 방문자가 다른 날짜에 다시 포함될 수 있다. 게시글·댓글·페이지 수는 현재 공개 가능한 항목만 집계한다. - `POST /api/analytics/pageview` - 공개 방문·게시물·페이지 조회/읽음 집계. 본문: `path`(필수), `postSlug`(게시물일 때), `pageSlug`(페이지일 때), `referrer`, `currentUrl`, `read`(읽음 이벤트). 발행된 게시물과 공개 페이지만 개별 집계한다. 응답 `{ ok: true }`. 관리자 세션 요청은 저장하지 않고 `{ ok: true }`만 반환한다. HTML 문서 모드 페이지는 Nuxt 클라이언트 플러그인을 거치지 않으므로 서버 미들웨어가 GET 요청 시 페이지 조회를 직접 기록하되, 관리자 세션은 제외한다. 단일 IP 해시는 1분에 최대 120개 쓰기 요청만 처리하고 초과 요청은 성공 응답만 반환한다. - `POST /api/analytics/heartbeat` - 실시간 세션·체류·스크롤 집계. 본문: `path`, `postSlug`, `pageSlug`, `clientSessionId`, `durationSeconds`(최대 1800), `maxScrollRatio`(0~1). 로그인 시 서버가 회원 세션으로 사용자 연결하며, 관리자 세션 요청은 저장하지 않는다. 단일 IP 해시는 1분에 최대 240개 쓰기 요청만 처리한다. - `GET /api/navigation` - 공개 네비게이션(`primary`는 트리·`footer`·`recommended`는 평면, 상세는 위 메뉴/네비게이션 절) - `GET /ads.txt` - 사이트 설정의 ads.txt 본문을 `text/plain`으로 반환한다. 값이 없으면 빈 본문을 반환한다. - `POST /api/auth/signup` - 회원 가입. 본문: `username`, `email`, `password`, 선택 `emailOtp`(6자리 숫자). **`GET /api/auth/bootstrap-status`의 `emailOtpConfigured`가 true이고 `needsAdminSetup`이 false일 때**(서버에 Resend·pepper 설정됨) `emailOtp`가 필수이며, 직전에 `POST /api/auth/email-otp/request`로 같은 이메일·`purpose: "signup"` 발송분과 일치해야 한다. 최초 관리자 부트스트랩(`needsAdminSetup: true`)에서는 `emailOtp` 없이 가입 가능. 이메일은 저장 시 소문자로 정규화한다. - `GET /api/auth/bootstrap-status` - 최초 관리자 등록 필요 여부(`hasUsers`, `needsAdminSetup`) 및 **이메일 OTP 사용 가능 여부** `emailOtpConfigured`(서버 `RESEND_API_KEY`·`RESEND_FROM_EMAIL` 및 pepper: 비어 있지 않은 `EMAIL_OTP_PEPPER` **또는** `MEMBER_SESSION_SECRET`)를 반환한다. pepper는 OTP 6자리를 DB에 해시해 둘 때만 쓰이는 서버 비밀(긴 난문자열 권장)이다. - `POST /api/auth/email-otp/request` - 본문: `email`, `purpose`(`"signup"` | `"password_reset"`). Resend로 6자리 OTP 메일을 보낸다. 미설정 시 503. `signup`은 이미 가입된 이메일이면 409, 최초 관리자 단계에서는 400. `password_reset`은 존재하지 않는 이메일도 동일한 성공 메시지를 반환하며(이메일 미발송), 요청 빈도 제한을 위해 DB에 더미 챌린지를 남길 수 있다. 55초 쿨다운·시간당 5회 한도. 실제 메일 발송이 실패하면 방금 생성한 챌린지는 즉시 삭제한다. 발송 성공 후 같은 이메일·용도의 이전 pending 챌린지는 무효화한다. DB 테이블 `email_otp_challenges`(마이그레이션 `018_email_otp_challenges.sql`) 필요. - `POST /api/auth/password-reset/confirm` - 본문: `email`, `code`(6자리), `newPassword`(8~32자). `password_reset` OTP 검증·소진 후 해당 이메일 회원 비밀번호를 갱신한다. - `POST /api/auth/login` - 회원 로그인. 15분 동안 동일 계정 5회 또는 동일 IP 20회 실패 시 429와 `Retry-After`를 반환한다. - `GET /api/auth/me` - 현재 회원 세션 조회(`id`, `username`, `email`, `avatarUrl`, `isAdmin`, `role`). `optional=1` 쿼리를 붙이면 비로그인 상태에서 401 대신 `null`을 반환한다. - `POST /api/auth/logout` - 회원 로그아웃 - `GET /api/auth/profile` - 회원 설정 조회 - `PUT /api/auth/profile` - 회원 프로필 수정(닉네임, `avatarUrl`). 이전 값이 `/uploads/members/avatars/` URL이고 새 값과 달라지면 `removeManagedAvatarAsset`으로 **메타만** 끊고 디스크 파일은 유지한다(`DELETE /api/auth/avatar`와 동일한 자산 정리 규칙). - `POST /api/auth/avatar` - 회원 썸네일 이미지 업로드 - `DELETE /api/auth/avatar` - 회원 썸네일 제거 - `GET /api/auth/check-username?username=` - 닉네임 중복 확인 - `PUT /api/auth/password` - 회원 비밀번호 변경. 성공 시 `users.session_version`을 증가시키고 기존 회원·관리자 세션을 모두 무효화한다. - `DELETE /api/auth/account` - 회원 탈퇴. 마지막 `owner` 계정은 삭제할 수 없으며, 탈퇴 성공 시 회원 세션과 관리자 세션 쿠키를 함께 정리한다. > 회원 썸네일 이미지는 `/uploads/members/avatars/YYYY/MM` 경로로 저장하며, 업로드 시 WebP로 변환하고 `AVATAR_MIN_WIDTH`/`AVATAR_MIN_HEIGHT` 최소 해상도 검증 후 중앙 기준 1:1 정사각형으로 크롭한다. > 최종 저장 크기는 `AVATAR_MAX_WIDTH`, `AVATAR_MAX_HEIGHT` 중 작은 값을 사용해 `N x N` 정사각형으로 맞춘다. > `AVATAR_WEBP_QUALITY`는 1~100 범위로 보정하며, 최대 해상도 설정이 최소 해상도보다 작으면 서버에서 최소값 이상으로 자동 보정한다. > 회원 썸네일을 새로 업로드하거나 제거·탈퇴할 때, 이전 썸네일 URL에 대한 `media_metadata` 행은 `removeManagedAvatarAsset`으로 제거하되 **디스크 파일은 삭제하지 않는다.** 관리자 미디어 **썸네일** 탭에서 미사용 파일을 확인·삭제한다. > 관리자 미디어 화면의 **썸네일** 탭에서만 회원 썸네일을 목록·검색하며, `GET /admin/api/media` 응답에 `avatarOwner`(닉네임·이메일·등급·마지막 접속·IP)가 포함될 수 있다. 프로필 이미지 목록 카드 배지는 등급(소유자·관리자·VIP·멤버)으로 표시한다. ### 업로드 파일 제공 - `GET /uploads/**` - 런타임 업로드 파일 제공. 운영 Docker에서는 빌드 산출물 `.output/public`이 아니라 `public/uploads` 볼륨의 실제 파일을 읽어 로고·게시물 이미지·회원 썸네일을 즉시 제공한다. 응답은 `ETag`, `Last-Modified`를 제공하고 조건부 요청이 일치하면 304를 반환한다. 원본·시스템·회원 썸네일처럼 새 URL로 생성되는 업로드 파일은 `public, max-age=31536000, immutable`을 사용하며, 같은 URL로 재생성될 수 있는 게시물 `thumbs/*-(card|body|body-720|lightbox).webp` 파생 파일은 `public, max-age=3600, stale-while-revalidate=86400`을 사용한다. ### 관리자 API (`/admin/api/`) - `POST /admin/api/auth/login` - 로그인. 회원 로그인과 분리된 계정·IP 실패 횟수 제한을 적용하며 한도를 넘으면 429를 반환한다. - `POST /admin/api/auth/logout` - 로그아웃 - `GET /admin/api/auth/me` - 현재 관리자 세션 조회. `optional=1` 쿼리를 붙이면 비로그인 상태에서 401 대신 `null`을 반환하며, 관리자 라우트 보호용 기본 호출은 401을 유지한다. - `GET /admin/api/analytics/summary?period=weekly&days=56` - 통계 요약(오늘 및 최근 7/30/180/365일 방문, 누적 방문자·누적 조회수·공개 게시물 수, 30일 조회, 현재 접속자, 평균 체류, 50% 스크롤 도달, `collectedSince`, 선택 집계 단위 `trends`). `period`는 `daily`, `weekly`, `monthly`, `yearly`를 사용하며 대시보드는 일일·주간·월간·년간으로 전환한다. - `GET /admin/api/analytics/posts?days=30&limit=5` - 기간 내 인기 게시물(조회·최근 30일 월간 조회·작성일·읽음·평균 체류·스크롤 구간) - `GET /admin/api/analytics/pages?days=30&limit=5` - 기간 내 인기 페이지(조회·방문자·평균 체류·스크롤 구간) - `GET /admin/api/analytics/realtime?limit=20` - 현재 접속자 요약·목록(로그인 사용자 닉네임·아바타, IP, 열린 페이지 수와 열린 페이지 목록 포함) - `GET /admin/api/analytics/traffic?days=30` - 기간 내 유입원·디바이스·유입 키워드 통계 - `GET /admin/api/analytics/range-detail?startDay=YYYY-MM-DD&endDay=YYYY-MM-DD&limit=5` - 통계 추이 막대 상세(요약·유입·디바이스·인기 게시물·인기 페이지). 인기 콘텐츠는 조회·읽음/방문자·최근 30일 조회·작성일·스크롤 도달 지표를 포함한다. 최대 31일 범위로 제한한다. - `GET /admin/api/analytics/posts/:id?period=daily&days=14` - 게시물별 통계(누적·기간 요약, 일간/주간/월간 조회·방문자 추이, 게시물별 유입·디바이스·키워드) - `GET /admin/api/analytics/pages/:id?period=daily&days=14` - 페이지별 통계(누적·기간 요약, 일간/주간/월간 조회·방문자 추이, 체류·스크롤 구간) - `GET /admin/api/posts` - 글 목록. 기본은 본문 없는 배열 응답이며, `paged=true&page=1&pageSize=50&q=검색어&status=published&tag=slug&featured=featured&sort=newest|oldest` 쿼리를 보내면 서버 필터링된 `{ items, pagination, counts }` 페이지 응답을 반환한다. - `POST /admin/api/posts` - 글 작성 - `GET /admin/api/posts/:id` - 글 상세 - `GET /admin/api/posts/:id/references` - 해당 글의 `/post/:slug` 공개 주소를 본문에 링크한 게시물 목록 - `PUT /admin/api/posts/:id` - 글 수정 - `DELETE /admin/api/posts/:id` - 글 삭제 - `GET /admin/api/posts/export-jobs` - 게시물 Export 작업 목록 - `POST /admin/api/posts/export-jobs` - 게시물 Export 작업 요청. `dateRangeMode=all|year|month|custom`와 연도·월·날짜 범위, `maxFileSizeBytes`, `chunkSize`를 받아 작업 레코드와 용량 기준 분할 파일 계획을 만들고 백그라운드 ZIP 생성을 시작한다. ZIP은 디스크로 스트리밍 생성하며 Markdown만 deflate 압축하고 이미지·영상·첨부 파일은 원본 바이트를 유지하는 store 방식으로 담는다. - `DELETE /admin/api/posts/export-jobs/:jobId` - 완료·실패한 게시물 Export 작업과 생성 ZIP 파일 삭제 - `POST /admin/api/posts/export-jobs/:jobId/retry` - 실패한 게시물 Export 작업을 준비 완료 파일은 유지한 채 나머지 분할 파일부터 재시도 - `GET /admin/api/posts/export-jobs/:fileId/download` - 준비 완료된 게시물 Export 분할 ZIP 파일 다운로드 - `POST /admin/api/posts/import` - Export ZIP 파일 Import 작업 생성. multipart `file` 필드의 ZIP을 최대 300MB까지 작업 폴더에 스트리밍하고 `post_import_jobs` 작업을 생성한 뒤 즉시 작업 객체를 반환한다. 실제 Markdown 복원은 백그라운드 워커가 처리한다. - `GET /admin/api/posts/import-jobs` - 최근 게시물 Import 작업 목록 조회. 대기 중이거나 중단된 작업이 있으면 백그라운드 실행을 다시 예약하고, 작업별 게시물 행(`items`)을 함께 반환한다. - `DELETE /admin/api/posts/import-jobs/:jobId` - 완료·실패한 게시물 Import 작업과 보관 ZIP 삭제. 대기·진행 중 작업은 삭제하지 않는다. - `GET /admin/api/pages` - 고정 페이지 목록 - `POST /admin/api/pages` - 고정 페이지 작성 - `GET /admin/api/pages/:id` - 고정 페이지 상세 - `PUT /admin/api/pages/:id` - 고정 페이지 수정 - `DELETE /admin/api/pages/:id` - 고정 페이지 삭제 - `GET /admin/api/page-sections` - 홈 Pages 진열장 페이지 섹션 목록 - `POST /admin/api/page-sections` - 페이지 섹션 생성 - `PUT /admin/api/page-sections/:id` - 페이지 섹션 이름 수정. 연결된 페이지의 `listing_section`도 함께 변경 - `DELETE /admin/api/page-sections/:id` - 미사용 페이지 섹션 삭제 - `PUT /admin/api/page-sections/reorder` - 페이지 섹션 표시 순서 저장 - `PUT /admin/api/page-sections/:id/pages/reorder` - 페이지 섹션 내부의 홈 표시 페이지 순서 저장. `removedPageIds`를 함께 보내면 해당 페이지의 섹션 연결을 해제 - `GET /admin/api/media` - 업로드 미디어 전체 배열(게시물용 이미지와 회원 아바타 포함; 회원 아바타에는 `avatarOwner` 요약이 붙을 수 있음). 글쓰기·대표 이미지 선택 등 기존 선택 모달 호환용으로 유지한다. - `GET /admin/api/media?paged=1` - 관리자 미디어 관리 화면용 페이지 응답. `tab`, `page`, `pageSize`, `search`, `folder`, `kind`, `unused` 쿼리를 받아 `{ items, pagination, counts }`를 반환한다. `pageSize`는 50·100·200 중 하나를 사용한다. - `POST /admin/api/media/thumbnail` - 게시물 대표 이미지 원본 URL에서 목록 카드용 썸네일을 생성 또는 재생성 - `PUT /admin/api/media` - 업로드 미디어 파일명 변경 또는 단일/복수 미디어 폴더 변경(회원 아바타 URL은 논리 폴더 `썸네일`만 허용, 일반 미디어를 `썸네일`로 옮기는 것은 거부; 썸네일 파일명 변경은 `users.avatar_url`이 해당 URL을 참조할 때만 거부) - `DELETE /admin/api/media` - 업로드 미디어 삭제(게시물·페이지에서 사용 중이면 거부; `/members/avatars/` URL은 `users.avatar_url`이 해당 URL을 참조할 때만 거부) - `GET /admin/api/media-folders` - 미디어 폴더 목록 - `POST /admin/api/media-folders` - 미디어 폴더 생성 - `DELETE /admin/api/media-folders` - 미디어 폴더 삭제(해당 경로·하위 경로로 분류된 `media_metadata`는 `미분류`로 되돌림) - `POST /admin/api/uploads` - 관리자 게시물·페이지용 다중 파일 업로드. multipart 전체를 Buffer로 읽지 않고 `/uploads/posts/YYYY/MM` 아래 요청별 임시 폴더에 스트리밍하며, 파일 수·전체 용량·종류별 파일 용량을 수신 중 제한한다. 검증된 파일은 원본명 기반으로 이동하고 같은 이름은 hard link 배타 생성으로 `이름-2`처럼 넘버링해 동시 요청 덮어쓰기를 막는다. 실패 시 해당 요청의 임시 파일과 이미 이동한 파일을 정리한다. 종류별 크기는 환경 변수, 1회 파일 수·전체 용량은 사이트 설정 `uploadMaxFileCount`, `uploadMaxTotalSize`를 따른다. - `POST /admin/api/member-avatar` - 관리자 멤버 썸네일 사전 업로드(신규·편집 공통, `/uploads/members/avatars/YYYY/MM`, WebP 변환·중앙 1:1 크롭). 편집 화면에서는 미리보기만 반영하고 **저장**(`PUT /admin/api/members/:id`) 시 회원에 연결한다. - `GET /admin/api/tags` - 태그 목록(옵션: `tagType`, `q`, `limit`) - `POST /admin/api/tags` - 태그 생성 - `GET /admin/api/tags/:id` - 태그 상세 - `PUT /admin/api/tags/:id` - 태그 수정 - `DELETE /admin/api/tags/:id` - 태그 삭제 - `PUT /admin/api/tags/reorder` - 메인 태그 순서 일괄 저장 - `GET /admin/api/settings` - 사이트 설정 조회(`showPostUpdatedAt`, `postTagLimit`, 업로드 제한, 라이트·다크 홈 커버, 어나운스 바, 사이트 코드 필드 포함) - `GET /admin/api/settings/backup-summary` - 관리자 사이트 용량 조회. 콘텐츠 수량은 PostgreSQL에서 집계하고, 업로드 파일 용량은 `public/uploads`를 스캔해 이미지·영상·오디오·첨부 파일·보내기로 분류하고, 합계는 표시 항목의 합으로 계산한다. - `PUT /admin/api/settings` - 사이트 설정 수정(`showPostUpdatedAt`, `postTagLimit`, 업로드 제한, 라이트·다크 홈 커버, 어나운스 바, `signupBlockedUsernames`, `adsTxt`, `customHeadCode`, `customFooterCode` 포함). `postTagLimit`은 1~10 정수만 허용한다. 업로드 최대 파일 수는 1~50, 업로드 전체 용량은 1MB~1GB 정수만 허용한다. `announcementEnabled`가 true이면 `announcementText` 필수. 배경색은 `#15171a`·`#ffffff`·`#ff4f2e`만 허용. - `PATCH /admin/api/settings` - 전달된 사이트 설정 필드만 검증·수정한다. 설정 카드별 저장은 이 API를 사용해 다른 카드의 미저장 값이나 먼저 완료된 저장 결과를 덮어쓰지 않는다. - `POST /admin/api/settings/home-cover` - 메인 화면 커버 이미지 파일만 업로드(720px WebP, `{ homeCoverImageUrl }` 반환). 라이트·다크 어느 슬롯에 반영할지는 클라이언트 폼에서 결정하며, `site_settings` 반영은 해당 카드의 `PATCH` 저장 시 함께 처리한다. - `POST /admin/api/settings/logo` - 로고·파비콘 파일만 업로드(`{ logoUrl, faviconUrl }` 반환). `site_settings` 반영은 사이트 정보 카드의 `PATCH` 저장으로 처리한다. - `GET /api/site-settings` - 공개 사이트 설정 조회(`showPostUpdatedAt`, 라이트·다크 홈 커버·어나운스 바·사이트 코드 필드 포함) - `GET /admin/api/navigation` - 네비게이션 항목 목록 - `PUT /admin/api/navigation` - 네비게이션 항목 일괄 저장 - `POST /admin/api/navigation/:id/favicon-refresh` - 추천 사이트 파비콘 수동 갱신(`{ cachedFaviconUrl, faviconCachedAt }` 반환) - `GET /admin/api/members` - 회원 목록(권한 코드, 최근 접속, 접속 IP, 댓글 수 포함) - `POST /admin/api/members` - 관리자 회원 생성. 본문: `username`, `email`, 선택 `avatarUrl`, `labels`, `note`. 생성된 회원은 `member` 권한이며 초기 비밀번호는 임의 해시로 저장한다. - `GET /admin/api/members/:id` - 관리자 회원 상세(썸네일, 이름, 이메일, 레이블, 관리자 노트, 활동 요약 포함) - `PUT /admin/api/members/:id` - 관리자 회원 기본 정보 수정. 본문: `username`, `email`, 선택 `avatarUrl`, `labels`, `note`. 이전 값이 회원 전용 썸네일 URL이고 새 값과 달라지면 `media_metadata` 연결을 분리한다. - `POST /admin/api/members/:id/avatar` - 관리자 회원 썸네일 업로드 및 즉시 DB 반영(레거시 API; 관리자 UI는 `member-avatar` + `PUT` 흐름 사용) - `PUT /admin/api/members/:id/role` - 회원 권한 변경(`owner`/`admin`/`vip`/`member`). 소유자 권한 이전은 `POST /admin/api/members/:id/ownership-transfer` 사용. - `POST /admin/api/members/:id/ownership-transfer` - 소유자 권한 이전(대상→소유자, 요청자→관리자) - 글 발행/초안 전환은 `PUT /admin/api/posts/:id`의 `status`와 `published_at`으로 처리한다. 예약 글은 별도 enum이 아니라 `published`와 미래 시각의 `published_at` 조합이다. - 게시물 상태는 `draft`, `published`, `members`, `private`를 사용한다. `members`는 VIP 이상 등급 회원에게만 공개한다. 로그인은 댓글 작성을 위한 기본 회원 기능이며, 멤버십 글 공개 기준으로 사용하지 않는다. `private`는 관리자 편집 화면에서는 보이지만 공개 사용자 화면에서는 노출하지 않는다. - 관리자 글 목록의 `published` 상태 표시와 상태 필터 문구는 페이지 목록과 같은 `공개`로 표시한다. 제목 링크는 관리자 수정 화면으로 이동하고, 공개 가능한 글은 제목 아래 주소 오른쪽에 hover/focus 시 공개 보기 아이콘을 표시해 `/post/:slug`를 새 탭으로 연다. - 관리자 글 목록 맨 오른쪽 **관리** 열은 more vert(⋮) 버튼으로 행 메뉴를 연다. 메뉴에서 **게시글 추천**·**추천 제거**·**게시글 삭제**를 선택한다(사이드바 사용자 메뉴와 같은 팝오버 스타일). - 관리자 글 목록 상단은 좌측에 제목·**총 N개**(추천 M개·필터 시 표시 K개) 요약, 우측에 검색, 상태·태그·**추천(전체/추천만)**·정렬 필터와 «새 글» 버튼을 한 줄(좁은 화면에서는 줄바꿈)로 둔다. 목록 검색은 빠른 조회를 위해 제목·슬러그·요약·태그 기준 부분 일치로 적용한다. - 관리자 글 목록 표 첫 열은 `is_featured`(추천 글)일 때만 금색 별 아이콘을 표시한다. 추천 여부는 글 편집 설정의 «추천 글» 토글로 지정한다. 추천 열과 제목 열 사이에는 대표 이미지 썸네일을 작은 크기로 표시하며, 이미지가 없으면 회색 placeholder만 유지한다. - 관리자 글 목록의 날짜 열은 **발행일**(`published_at`, 시·분 포함)이며, `showPostUpdatedAt`이 true이고 발행 후 수정이 있으면 아래에 `수정: …` 보조 줄을 표시한다. - 관리자 글 목록 기본 정렬(최신순·오래된순)은 **발행일** 기준이며, `published_at`이 없는 초안 등은 **수정일**(`updated_at`)로 대체한다. API(`listAdminPosts`)와 화면 필터 정렬 모두 동일 규칙을 쓴다. - 태그 삭제 시 `post_tags` 연결도 데이터베이스 외래 키 규칙에 따라 함께 삭제된다. - 게시물 생성·수정 API는 사이트 설정의 `postTagLimit`보다 많은 태그가 전달되면 400 오류로 저장을 거부한다. - 공개 `GET /api/tags`는 기본적으로 `managed`(메인 태그)만 반환한다. 태그 상세·게시물 배지처럼 일반 태그 메타가 필요한 화면은 `?tagType=all`을 사용한다. - 관리자 태그 목록 응답은 각 태그의 `postCount`, `lastUsedAt`, `updatedAt`을 포함한다. - 관리자 태그 목록은 `managed` 우선, `sort_order ASC, 최근 사용/수정 DESC, name ASC` 기준으로 정렬한다. - 메인 태그 순서 저장은 드래그 드롭 직후 자동으로 실행되며, 드래그 순서를 받아 `sort_order`를 순차 값으로 다시 저장한다. - 메인 태그 순서 저장 중에는 추가 드래그를 잠시 막고 저장 상태를 표시한다. - 관리자 태그 추가 화면에서 직접 생성한 태그는 기본적으로 `general`(일반 태그)로 생성하고, 저장 후 수정 화면이 아니라 태그 관리 목록으로 이동해 일반 태그 목록에 바로 표시한다. - 게시물 작성에서 새로 생기는 태그는 기본적으로 `general`(일반 태그)로 생성한다. - 관리자 페이지 목록의 공개 상태는 `공개`로 표시한다. 제목 링크는 관리자 수정 화면으로 이동하고, 공개 페이지는 제목 아래 주소 오른쪽에 hover/focus 시 공개 보기 아이콘을 표시해 `/pages/:slug`를 새 탭으로 연다. - 메인 태그는 목록에서 `일반 태그로 변경` 액션으로 강등하며, 일반 태그는 배지형 전체 목록에서 확인·필터·최근 사용순·많이 사용순·이름순 정렬·메인 전환·삭제를 수행한다. - 태그 관리 화면에서 순서 저장·메인 전환·강등·삭제, 태그 생성·수정 저장 등의 성공·실패 피드백은 우측 상단 토스트로 표시한다. 태그 수정 화면의 `변경 저장` 버튼은 실제 변경사항이 있을 때만 활성화한다. - 태그 `color`는 `#RRGGBB` 형식이며 사용자 화면 태그 색상 표시와 배지 배경색에 사용한다. - 태그 헤더는 `headerImageUrl`, `headerTitle`, `headerText`를 사용한다. 관리자 태그 폼에서 이미지를 업로드하면 `/uploads/system/tag-cover-*.webp`로 저장하고, 해당 이미지가 미디어 사용처로 보호된다. ### 관리자 글 편집 - 글 작성/수정 화면은 Markdown-first 에디터(`AdminMarkdownEditor`)를 사용한다. - 작성 모드 textarea 왼쪽 바깥에 **논리 줄 번호** 거터(`\\n` 기준 줄 수, 빈 본문은 1줄)를 absolute 영역으로 두고 textarea와 거터의 세로 스크롤을 동기화한다. 거터 스크롤바는 숨긴다. 한 논리 줄이 화면에서 여러 줄로 줄바꿈될 때는 옵시디언·CodeMirror처럼 시각 줄마다 번호가 늘지 않으며, 논리 줄 단위로만 맞춘다. - 저장 데이터는 기존 `content` 필드의 마크다운 문자열을 그대로 유지한다. - 관리자 게시물/페이지 저장 API는 레거시 블록 배열·객체 본문 값이 들어와도 마크다운 문자열로 정규화한 뒤 저장한다. - 본문 작성 모드는 textarea 기반으로 범위 선택, 다중 문단 복사/붙여넣기, 외부 마크다운 붙여넣기를 브라우저 기본 동작에 가깝게 처리한다. - 본문 작성 모드에서 Enter·Shift+Enter 모두 브라우저 기본 줄바꿈(한 줄)으로 동작한다. 문단 구분은 빈 줄로 한다. - 클립보드에 `text/html`이 있으면 제목, 문단, 목록, 인용, 코드, 링크, 굵게, 기울임, 이미지를 기본 마크다운 조각으로 변환해 삽입한다. - 본문 미리보기 모드는 공개 본문과 같은 `ContentMarkdownRenderer`를 사용하며, 툴바와 카드형 패널 외곽을 숨겨 본문만 표시한다. - 툴바는 제목 1/2/3, 굵게, 기울임, 인라인 코드, 인용, 목록, 코드 블록, 구분선 삽입을 제공한다. - `Cmd/Ctrl+B`, `Cmd/Ctrl+I`는 현재 선택 텍스트에 각각 굵게, 기울임 마크다운을 적용한다. - `Cmd/Ctrl+E`는 작성 모드와 미리보기 모드를 전환하며, 미리보기에서 작성 모드로 돌아올 때 기존 커서 위치와 textarea 스크롤을 복원한다. - 관리자 미리보기 패널은 공개 렌더러를 쓰되 밝은 관리자 배경 기준의 본문 색상 변수를 별도로 지정한다. - 관리자 미리보기에서 `ContentMarkdownRenderer`에 `interactive`를 켠다. 갤러리 이미지는 드래그로 순서를 바꿀 수 있으며, 드래그 중 다른 셀 위에 올리면 해당 셀에 주황 테두리와 「여기로 이동」 표시로 드롭 위치를 보여 준 뒤 `gallery-reorder`로 마크다운을 갱신한다. - 라이브 모드 단일 이미지 블록은 드래그 가능하다. `![](...)` 이미지 줄과 단독 이미지 URL 줄 모두 같은 이미지 블록으로 다룬다. 다른 이미지 블록 위에 드롭하면 두 줄을 `:::gallery` fenced block 한 개로 병합하며(`merge-images-to-gallery`), 문서 순서를 유지해 위쪽 이미지가 먼저 들어간다. 자동 인접 병합은 하지 않는다. - 라이브 모드 갤러리 블록은 이미지 블록과 같은 선택형 카드로 취급한다. Tab/클릭으로 포커스할 수 있고, 포커스 상태에서 방향키 위/아래 이동을 지원한다. 갤러리 이미지 hover/focus 시 개별 편집/삭제 버튼을 제공하며, 편집 버튼은 해당 이미지 줄 기준으로 갤러리 블록 설정 패널을 연다. - 라이브 모드 단일 이미지 블록을 기존 갤러리 이미지 셀에 드롭하면 해당 셀 뒤에 이미지를 추가하고 원래 단일 이미지 줄은 제거한다(`insert-image-to-gallery`). - 라이브 모드 갤러리 이미지를 블록 사이 얇은 삽입선(또는 문서 맨 아래 삽입선)에 드롭하면 해당 위치에 단일 이미지 마크다운 줄을 삽입하고 갤러리에서 제거한다(`extract-gallery-image`). 갤러리에 이미지가 1장만 남으면 갤러리 블록을 단일 이미지 줄로 바꾸고, 0장이면 갤러리 블록을 제거한다. - `ProseImage`는 URL이 비어 있거나 로드에 실패해도 최소 높이 placeholder와 「이미지를 불러올 수 없음」 안내를 표시해 라이브 모드에서 블록 선택·편집이 가능하다. - 인용(`>`) 블록은 첫 인용 줄에 `> [!bg=yellow]` 또는 `> {bg=yellow}` 옵션 줄을 두면 해당 줄은 숨기고 블록 배경을 바꾼다. 지원 배경 프리셋은 콜아웃과 같은 `gray`, `blue`, `green`, `yellow`, `red`, `purple`이며, 옵션이 없으면 회색 기본 인용 스타일을 쓴다. - 관리자 **라이브 모드**(미리보기) 인라인 편집: 문단·빈 줄·제목·인용·목록·코드 블록·콜아웃·토글을 렌더 스타일 그대로 contenteditable로 수정한다. blur·문단 이동(방향키) 시 편집 영역의 `<strong>`·`<em>` 등을 `**`·`*` 마크다운으로 다시 직렬화해 저장한다. 인용·콜아웃 멀티라인 편집 영역도 일반 인라인 렌더러를 사용해 색상·굵게·링크 등 인라인 문법을 표시한다. **Enter**·**Shift+Enter** 모두 다음 문단(블록) 분리. 문단 안 `/`로 슬래시 명령 메뉴(`/image`+Enter 이미지 삽입 등). **소스(작성) 모드** textarea에서도 동일한 `/` 슬래시 메뉴를 사용하되, 코드 fenced 블록 본문 안에서는 `/`를 일반 텍스트로 둔다. 슬래시 메뉴에 일치하는 명령 후보가 없으면 Enter·방향키를 메뉴가 가로채지 않고 일반 텍스트 줄바꿈·커서 이동으로 처리한다. 슬래시 메뉴를 ESC로 닫으면 취소 당시 줄 내용이 유지되는 동안만 다시 열리지 않고, `/`를 지웠다가 다시 입력하는 등 줄 내용이 바뀌면 새 입력으로 보고 다시 연다. 상단 마크다운 툴바는 두지 않는다. 슬래시 기본 제목은 **h2·h3·h4**만 표시하며, 본문 **h1**은 `/h1` 검색 시에만 삽입한다(게시물 **제목 필드**가 페이지의 유일한 h1). `Cmd+Shift+K`는 소스 모드와 라이브 모드에서 현재 줄을 삭제하며, 소스 모드에서 여러 줄이 선택되어 있으면 선택 범위가 걸친 줄을 함께 삭제한다. 코드·콜아웃·토글 블록 내부에서는 커서가 있는 본문 줄을 삭제하고, 남은 본문 줄이 1개뿐이면 fenced 블록 전체를 삭제한다. `Cmd/Ctrl+Z`는 에디터 본문 변경을 되돌리고, `Cmd/Ctrl+Shift+Z` 또는 `Ctrl+Y`는 다시 실행한다. 콜아웃 옵션은 첫 줄 `:::callout emoji=none bg=blue title="주의사항"`처럼 `emoji`·`bg`(gray|blue|green|yellow|red|purple)·`title`로 지정하며, 라이브 모드에서는 블록에 포커스가 들어오면 오른쪽 설정 패널에서 수정한다. 코드 블록은 기본 줄번호 숨김이고, 줄번호 표시를 켜면 선언 줄에 `line-numbers`를 저장한다. 기존 `linenos`, `nolinenos`, `no-line-numbers` 토큰은 읽기 호환으로만 유지한다. 라이브·공개 모두 `ProseCodeBlock`(`#15171a`, `px-4 py-3`, `text-sm leading-6`)으로 동일하게 표시한다. 라이브 모드 호버·포커스 시 Language 입력·줄번호 토글이 보인다. 공개 화면에는 언어 라벨 옆 **복사** 버튼으로 본문을 클립보드에 넣는다. 본문 하단 클릭으로 새 문단을 추가한다. - 라이브 모드 공통 편집기는 한글 IME 조합 확정 Enter를 문단·빈 줄의 분리, 제목·목록의 아래 줄 삽입, 토글 제목의 본문 이동, 인용·콜아웃·코드·토글 본문의 텍스트 줄바꿈에 동일하게 연결한다. IME가 확정 Enter의 `keydown`을 전달하지 않고 `keyup`만 남기는 경우에도 조합 종료 직후 Enter로 보고 같은 동작을 실행한다. Shift+방향키 범위 선택은 `ContentMarkdownRenderer` Selection Bridge가 인접 편집 블록까지 확장한다. 단일 줄 블록의 Shift+위/아래는 커서 위치와 상관없이 현재 열 기준으로 이전·다음 편집 블록까지 확장하고, 멀티라인 편집 영역은 첫 줄·마지막 줄 경계에서 `data-source-line`~`data-source-line-end` 줄 범위로 탐색한다. `Cmd/Ctrl+A` 1회는 현재 블록 전체, 짧은 시간 안 2회는 라이브 본문 전체를 선택한다. 교차 블록·전체 선택 상태에서 **Backspace**·**Delete**·**Cmd/Ctrl+X**는 선택 범위를 마크다운 줄로 변환해 `content-replace`로 본문을 갱신한다. 콜아웃·인용 내부 전체 선택 삭제는 블록을 제거하지 않고 빈 본문 줄을 남긴다. 블록 이동 단축키는 Shift 조합일 때 실행하지 않으며, 선택 제스처가 우선한다. 콜아웃 본문은 하나의 멀티라인 편집 영역으로 유지해 `Shift+방향키` 선택이 내부 여러 줄을 가로지를 수 있게 한다. 라이브 멀티라인 블록은 브라우저 기본 DOM 줄 생성 대신 텍스트 값 치환 방식으로 줄바꿈을 삽입하며, contenteditable 값을 읽을 때 끝 줄바꿈을 보존해 첫 줄 빈 줄과 후행 빈 줄이 소스·라이브 모드 전환 또는 저장 중 유실되지 않게 한다. 인용 마지막 줄에서 아래 방향키를 누르면 외부 빈 문단을 만들고 커서를 해당 문단으로 이동하지만, 콜아웃 아래 방향키는 본문 줄을 새로 만들지 않는다. - 인라인 마크다운은 Obsidian식 `$...$` 첨자 토큰과 `::color[텍스트]` 색상 토큰을 지원한다. `$H_2O$`는 `H`+아래첨자 `2`+`O`, `$2^8$`은 `2`+위첨자 `8`, `$_B^AR$`는 아래첨자 `B`와 위첨자 `AR`로 렌더링한다. 첨자 본문에 공백·기호가 필요하면 `$_{...}$`, `$^{...}$` 형식도 허용한다. 색상 토큰은 `::gray[덜 중요한 말]`, `::red[**중요한 말**]`처럼 저장하며 `gray`, `blue`, `green`, `yellow`, `red`, `purple`만 허용한다. 색상 토큰 내부의 굵게·기울임·인라인 코드·링크·첨자와 `**[링크](url)**` 같은 굵은 링크는 재귀적으로 렌더링한다. - 라이브 모드 `:::` fenced 블록의 원본 범위는 여는 줄부터 닫는 `:::` 줄까지만 포함한다. 연속된 콜아웃·토글·갤러리 등은 앞 블록 편집 시 다음 블록의 선언 줄을 교체 범위에 포함하지 않는다. - 이미지 파일을 붙여넣거나 드롭하면 관리자 업로드 API로 저장한 뒤 현재 커서 위치에 이미지 또는 갤러리 마크다운을 삽입한다. - 툴바 `이미지`·`갤러리`는 미디어 모달을 연다. 모달 기본 탭은 **미디어 라이브러리**이며 **업로드** 탭에서 드래그·파일 선택 후 라이브러리 목록을 갱신한다. 업로드 중에는 추가 드롭·파일 선택과 모달 닫기를 막고 로딩 스피너를 표시하며, 업로드 완료 후에는 모달을 자동으로 닫거나 본문에 자동 삽입하지 않는다. 본문 삽입은 라이브러리 목록에서 파일을 직접 선택한 뒤 `삽입` 버튼을 눌렀을 때만 실행한다. 미디어 선택 목록에는 원본 파일만 표시하고, 게시물 카드·본문 1600px·본문 720px·라이트박스·Pages 커버 자동 생성 이미지는 숨긴다. - 미디어 라이브러리에서 단일 이미지를 선택하면 `![alt](url)` 형식으로 삽입한다. - 미디어 라이브러리에서 여러 이미지를 선택하면 `:::gallery` fenced block으로 삽입한다. - 작성 모드에서 커서가 이미지 마크다운 줄, `:::gallery`, `:::link`, `:::iframe`, `:::html`, 인용문, `:::callout`, 코드 fenced 블록, `:::toggle` 블록 안에 있고 textarea(또는 블록 패널)에 포커스가 있으면 게시물 설정 사이드바(420px) 위에 **블록 설정 패널**(`AdminEditorBlockPanel`)이 오른쪽에서 슬라이드 인한다. 본문·패널 바깥을 클릭하면 슬라이드 아웃한다. 라이브 모드 멀티라인 편집기는 실제 커서가 있는 원본 줄을 패널 상태에 반영하며, 커서가 지원 블록 밖으로 이동하면 직전 코드·콜아웃·인용 설정 패널을 닫는다. 코드 fenced 블록 판별은 위에서 아래로 여는 펜스와 닫는 펜스를 짝지어 처리해, 닫는 ` ``` ` 줄을 다음 코드 블록 시작으로 오인하지 않는다. 갤러리 이미지 추가 미디어 모달을 여는 동안에는 활성 갤러리 컨텍스트와 패널 상태를 유지한다. - 블록 설정 패널: 이미지·갤러리(캡션, **파일명을 캡션으로 사용** 토글·기본 끔, URL, 갤러리 순서·삭제·추가), 링크 URL, iframe 코드, HTML 코드, 인용 배경색, 콜아웃 제목·아이콘·배경색, 코드 언어·줄번호, 토글 기본 펼침 상태, 선택 텍스트 색상. `AdminMarkdownEditor`는 `block-panel` 이벤트로 상태를 `AdminPostForm`에 전달한다. - 미디어 라이브러리 갤러리 다중 선택 시 선택 항목은 **주황(`#ff7a00`) 굵은 테두리**로 표시한다. - 옵시디언식 토큰 숨김/백스페이스 복원 Live Preview는 후속 단계로 둔다. - 제목은 별도 라벨 영역이 아니라 에디터 상단의 큰 제목 입력으로 표시한다. - 글 작성/수정 화면은 페이지 제목 헤더를 별도로 두지 않고, 폼 상단의 Ghost 스타일 도구막대에서 목록 이동, 상태 문구, Preview, 상태별 주요 액션(Publish / Update·Unpublish / Update·Unschedule), 설정 패널 토글을 제공한다. - 도구막대 상태 문구는 영어로 표시한다. **초안**: 편집 중 `Draft`, 저장(수동·서버 자동 저장) 진행 중 `Saving...`, 서버 기준과 동일할 때 `Draft - Saved`(신규 작성에서도 첫 `POST` 저장 후에는 `Draft - Saved`를 사용할 수 있다). **즉시 발행**: 공개 URL이 있으면 `Published ↗`를 링크로, 없으면 동일 문구만 표시한다. **예약 발행**: `Scheduled`를 `#2BBA3C`·보통 굵기로 표시하고 마우스 오버 시 영문 한 줄로 예약 시각을 `title` 툴팁에 보여 준다. **멤버십**은 `Members`, **비공개**는 `Private`로 표시한다. - **초안**(예약 발행 제외)은 입력 변경 후 약 1.2초 디바운스로 서버 자동 저장을 호출한다(슬러그가 유효할 때만). 제목이 비어 있으면 DB/API 저장 시에만 `(제목 없음)` 플레이스홀더를 쓰고, 관리자 폼·목록 API 응답의 `title`은 빈 문자열로 내려 준다. 임시 슬러그(`d`+24자리 hex)는 제목을 직접 수정하기 전까지 제목 입력에 따라 슬러그가 따라가며, 사용자가 슬러그를 직접 고친 뒤에는 자동 연동하지 않는다. 신규 작성 화면 마운트 시 슬러그가 비어 있으면 임시 슬러그를 채운다. 기존 글은 `PUT /admin/api/posts/:id`, **신규 작성**은 첫 저장 시 `POST /admin/api/posts`로 행을 만든 뒤 `replace`로 `/admin/posts/:id` 편집 화면으로 옮긴다. 신규 글 첫 자동 저장 중에는 초안 저장 준비 안내 오버레이를 표시하고, 첫 `POST` 이후 이동 직전 현재 폼의 최신 제목·본문·태그·옵션이 첫 요청 payload와 다르면 생성된 글에 `PUT`으로 한 번 더 반영한다. 저장 요청 중 사용자가 추가 입력한 본문·태그는 성공 응답 시 저장 완료로 오판하지 않고, 저장 완료 후 남은 변경으로 다시 자동 저장한다. 미저장 변경 비교는 태그 표시명 보조값(`tagNames`)처럼 비동기 태그 API 로딩으로만 바뀌는 값을 제외하고 실제 저장 필드 기준으로 판단한다. **이미 발행·예약으로 서버에 반영된 글**은 사이드바 등으로 폼만 초안처럼 바뀌어도 자동 저장하지 않으며, `Update`를 눌렀을 때만 `PUT`으로 반영한다(툴바의 `Publish`/`Update`/`Unpublish`/`Unschedule` 분기도 서버에 반영된 게시 형태를 기준으로 한다). 다른 화면으로 나가기 직전에는 디바운스 대기 중인 초안 변경이 있으면 타이머를 취소하고 한 번에 `POST` 또는 `PUT`으로 플러시한다. 이 저장이 실패하거나 이미 저장 중이거나 유효한 payload를 만들 수 없으면 화면 이동을 중단하고 미저장 확인을 표시한다. - `Publish`는 **서버에 아직 초안으로만 저장된 글**에만 표시되며 클릭 시 전체 화면 발행 모달을 연다. 초안에서 연 모달의 기본 선택은 **발행·지금 바로**이다. 모달 본문은 뷰포트 세로 중앙에 가깝게 배치하고, 상단에는 제목·닫기만 둔다(도구막대의 `Preview` 버튼은 두지 않는다). 모달에서는 상태(발행/초안)와 발행 시점(즉시/예약)을 최종 선택한 뒤 확정하며, 예약 시각은 날짜·시간(KST 표기) 입력을 분리한다. 모달에서는 행마다 접힌 상태로 현재 선택 요약만 보이고, 행을 눌러 펼친 뒤 버튼으로 값을 고른다. 게시 상태 행에는 Ghost와 같은 종이비행기 아이콘·펼침 화살표 SVG를 쓰고, 발행 시점 행에는 시계 아이콘·동일 화살표를 쓴다. 발행이 아닌 상태에서는 발행 시점 행 자체를 숨긴다. 발행 저장 요청이 진행되는 동안 다른 화면으로 이동하려 하면 미저장 이탈 확인을 표시한다. - `Update`는 발행·예약·멤버십·비공개 글에 표시되며, 마지막 저장 이후 변경이 있을 때만 활성화된다(활성 텍스트 `#394047`, 비활성 `#8E9CAC`). `Publish`·활성화된 `Update`·`Unpublish`·`Unschedule`에는 호버 시 배경 `#f1f3f4`를 적용한다. - `Unpublish`·`Unschedule` 클릭 시 Ghost형 전체 화면 확인 화면을 연다. 발행·예약 시각 요약과 **발행 취소하고 초안으로 되돌리기 →**(또는 예약 취소 문구) 링크를 눌렀을 때만 `status`를 초안으로 되돌리고 `published_at`을 비운 뒤 `PUT`으로 저장한다. - 글 작성/수정 화면은 관리자 사이드바 네비게이션을 숨기고, 관리자 공통 내부 패딩 없이 전체 화면 편집 모드로 표시한다. - 글 작성/수정 화면은 브라우저 문서가 아니라 에디터 작업 영역 내부에서만 세로 스크롤한다. - 글 작성/수정 폼은 에디터 작업 영역과 우측 설정 패널을 먼저 좌우로 나누고, 에디터 작업 영역 안에 상단 도구막대와 본문 스크롤 영역을 배치한다. - 본문 에디터는 데스크톱에서 좌우 32px 패딩을 포함한 804px 중앙 컬럼으로 배치해 실제 입력 영역 최대 폭을 740px로 유지한다. - 게시물 설정은 데스크톱에서 420px 우측 패널로 표시하며, 도구막대 버튼으로 열고 닫을 수 있고 너비 전환 애니메이션을 적용한다. - 공개 가능한 글의 보기 액션은 게시물 설정 패널의 Post URL 라벨 오른쪽에 표시한다. - 글 삭제 액션은 게시물 설정 패널 하단에 기본 중립 톤 버튼으로 제공하고 hover 시 위험 색상으로 강조한다. - 대표 이미지는 본문 제목 위의 에디터 흐름 안에서 추가, 변경, 삭제한다. - 대표 이미지가 설정된 상태의 변경/삭제 액션은 실제 이미지 레이아웃을 바꾸지 않도록 이미지 hover 또는 focus 오버레이로 표시한다. - 대표 이미지 선택 모달은 이미지 업로드 탭과 미디어 라이브러리 탭을 제공한다. - 제목 입력에서 Enter를 누르면 본문 첫 블록으로 포커스를 이동한다. - 새 글 작성처럼 본문이 비어 있는 경우에도 빈 문단 블록을 먼저 생성한다. - 미리보기 버튼은 현재 작성 폼 값을 `SORI_ADMIN_POST_PREVIEW` 브라우저 저장소에 기록한 뒤 `/admin/posts/preview` 새 탭에서 렌더링한다. - 미리보기 화면은 공개 게시물 상세와 같은 본문 렌더링 컴포넌트를 사용하되, 데이터베이스에는 임시 글을 저장하지 않는다. - 미리보기 본문·헤로 영역은 공개 상세와 동일하게 중앙 `max-w-[720px]` 컬럼과 `px-4 sm:px-5` 수평 패딩을 적용한다. - 글 저장/수정/삭제 진행과 성공/실패 상태는 화면 우측 상단 토스트로 표시한다. - 발행 상태에서 발행 시각을 미래로 지정하면 예약 발행으로 저장한다. - 예약 발행 글은 관리자 목록에서 예약 상태로 표시하되 공개 게시물 목록과 상세 API에는 발행 시각 이후부터 노출한다. - 관리자 글 에디터의 실제 입력 텍스트 색상은 placeholder보다 진하게 표시한다. - 관리자 작성 화면과 공개 본문은 같은 마크다운 렌더링 기준을 사용한다. - 태그 입력은 배지형 입력으로 제공하며 Enter 또는 쉼표 입력 시 태그를 추가하고, 배지의 x 버튼으로 삭제한다. - 태그 배지 삭제 버튼은 SVG 닫기 아이콘으로 표시한다. - 태그 토큰은 게시물 URL용 `toSlug`(한글 로마자화)와 분리하여 한글을 유지하고, 공백은 하이픈으로만 정리하며 `a-z0-9가-힣` 및 하이픈만 허용한다. - 제목 입력에서 한글 IME 조합 중 Enter는 조합 확정으로만 처리하고 본문 에디터 포커스 이동을 실행하지 않는다. - 관리자 게시글 목록의 태그는 쉼표 구분 문자열이 아니라 읽기 전용 배지 목록으로 표시한다. - 대표 이미지는 URL 직접 입력이 아니라 미디어 선택 또는 이미지 업로드 탭으로 설정한다. - 대표 이미지 선택 모달에서 미디어를 클릭하면 선택 상태만 표시하고, 하단 대표 이미지로 적용 버튼을 눌렀을 때 글 폼에 반영한다. - 대표 이미지가 설정되면 관리자 글 폼에 썸네일과 hover 오버레이 삭제/변경 액션을 표시한다. - 글 SEO 메타(`seo_title`, `seo_description`)는 별도 입력 없이 저장 시 글 제목·요약과 동일하게 기록한다. - 관리자 폼에서는 검색엔진 노출 제외(`noindex`)만 설정할 수 있다. - Canonical URL은 별도 입력을 받지 않고 기본 글 주소를 사용한다. - 공개 게시물 상세 화면은 SEO 제목이 없으면 글 제목, SEO 설명이 없으면 요약을 메타 태그 기본값으로 사용한다. - 저장된 태그가 없는 게시물에는 상세 메타 행·홈 Latest·`/posts` 목록 카드에 태그 배지나 더미 라벨을 표시하지 않는다. - 검색엔진 노출 제외가 켜진 글은 robots 메타를 `noindex, nofollow`로 출력한다. - 공개 상세 화면의 `og:image`와 Twitter large image 카드는 대표 이미지를 기본값으로 사용한다. - 이미지 블록은 관리자 업로드 API로 이미지를 업로드하고 `![](url)` 또는 파일명 캡션 토글 시 `![](url "파일명")` 형식으로 저장한다. 단독 이미지 파일 URL(`jpg`, `png`, `webp`, `gif`, `avif`, `svg`) 한 줄은 임베드가 아니라 이미지 블록으로 렌더링한다. 게시물 저장 시 `/uploads/posts/YYYY/MM/` 아래의 본문 `jpg`·`png`·`webp` 이미지는 원본 옆 1600px `thumbs/*-body-1600.webp`, 720px `thumbs/*-body-720.webp`, 2560px `thumbs/*-body-2560.webp` 파생 이미지로 자동 생성한다. 공개 본문 단일 이미지와 갤러리는 720px·1600px 표시용 이미지를 우선 사용하고 실패하면 원본 URL로 대체하며, 라이트박스는 2560px 파생 이미지를 우선 사용하고 실패하면 원본 URL로 대체한다. - 이미지/갤러리 삽입 시 캡션은 기본 비우며, 블록 설정 패널에서 **파일명을 캡션으로 사용** 토글로 이미지 아래에 URL 파일명을 표시한다. - 라이브 모드 이미지 블록은 hover/focus 시 우측 상단에 `삭제` 버튼만 표시한다. 이미지 URL·캡션·파일명 캡션 사용 여부 수정은 해당 이미지 블록에 포커스했을 때 오른쪽 이미지 설정 패널에서 처리한다. - 이미지 블록 표시 옵션은 `regular`, `wide`, `full` 값을 사용하며 `regular`는 width 옵션을 생략한다. - 갤러리 블록은 `:::gallery` fenced block 안에 이미지 마크다운 행을 여러 개 저장한다. - 관리자 갤러리 미디어 선택은 여러 이미지를 선택한 뒤 확인 버튼으로 적용한다. - 관리자 갤러리 블록은 이미지 1개일 때 1열, 2개일 때 2열, 3개 이상일 때 3열로 표시한다. - 관리자 갤러리 블록의 이미지 순서는 드래그 앤 드롭으로 변경하며, 드래그 중 삽입 위치를 이미지 사이 라인으로 표시한다. - 공개 갤러리는 한 줄에 2~3개 이미지 그리드로 표시하고 클릭 시 라이트박스로 크게 확인한다. - 이미지와 갤러리 블록은 기존 업로드 미디어 선택 또는 새 이미지 업로드를 제공한다. - 관리자 미디어 업로드 API는 이미지(`jpg`, `png`, `webp`, `gif`), 비디오(`mp4`, `webm`, `mov`), 오디오(`mp3`, `wav`, `ogg`, `m4a`), 파일(`pdf`, `zip`, `txt`, `csv`, `docx`, `xlsx`, `pptx`)을 지원한다. - 콜아웃 블록은 `:::callout` fenced block 안에 본문을 저장한다. - 콜아웃 블록은 선언부 옵션으로 `emoji`, `bg`, `title`을 저장할 수 있다. 예: `:::callout emoji=none bg=blue title="주의사항"` - `emoji=none`이면 공개 렌더러에서 이모지를 숨긴다. - 콜아웃 본문은 일반 문단과 같은 인라인 마크다운 규칙을 사용하며, 공개 화면과 라이브 편집 화면 모두 여러 줄·굵게·링크·색상·기본 불릿/번호 목록 조합을 렌더링한다. 라이브 편집 목록은 공개 목록과 같은 마커 색상을 사용하고, 위/아래 방향키는 목록 항목 줄을 원문 줄 기준으로 이동한다. - 콜아웃 배경 프리셋은 인용 블록과 같은 `gray`, `blue`, `green`, `yellow`, `red`, `purple`를 지원한다. - 토글 블록은 `:::toggle 제목` fenced block 안에 펼침 본문을 저장한다. 라이브 모드에서는 저장된 기본 펼침·닫힘 상태로 처음 표시한 뒤 제목·본문을 인라인 편집하며, 공개 화면에서는 chevron 또는 제목 클릭으로 펼침·접힘 시 본문이 애니메이션된다. - 링크 블록은 `:::link` fenced block 안에 URL을 저장하고 `ProseEmbed`로 렌더링한다. 이미지 파일 URL은 링크 블록이 아니라 이미지 블록으로 저장한다. - iframe 블록은 `:::iframe` fenced block 안에 iframe HTML을 저장한다. 렌더링 시 `src`, `title`, `allow`, `width`, `height` 등 제한된 속성만 추출해 sandbox iframe으로 표시한다. `allowfullscreen`은 DOM 속성으로 중복 출력하지 않고 `allow`의 `fullscreen` 권한으로 정규화한다. - HTML 블록은 `:::html` fenced block 안에 사용자 HTML을 저장하고 `ProseHtml`로 렌더링한다. 렌더링 직전에 `sanitize-html` parser의 허용 목록으로 표·문단·제목(h2~h6)·목록·인라인 서식·기본 이미지와 안전한 링크 속성만 남긴다. script, style, iframe, SVG, object, form 계열 태그와 이벤트 속성, 인라인 style, `javascript:` 등 비허용 URL scheme을 제거하며, `target="_blank"` 링크에는 `noopener noreferrer`를 추가한다. iframe은 `/iframe` 블록을 사용한다. 고정 페이지의 `html_document`는 별도의 완전한 HTML 문서 기능이므로 이 본문 블록 정책을 적용하지 않는다. - 관리자 Markdown-first 에디터의 라이브/스타일 모드에서 링크·iframe·HTML 블록은 입력 카드 없이 즉시 실제 프리뷰로 표시된다. 링크·iframe·HTML·비디오·오디오·파일 프리뷰 카드는 hover/focus 시 우측 상단 삭제 버튼을 표시한다. 블록 래퍼에 포커스한 상태에서 `Backspace`·`Delete`·`Ctrl/Cmd+Shift+K`로 삭제하고, `Enter`로 아래 빈 줄을 추가하며, `ArrowUp`·`ArrowDown`은 브라우저 스크롤 대신 이전/다음 편집 줄로 이동한다. - 라이브/스타일 모드에서 제목 블록 Enter는 현재 제목 내용을 저장한 뒤 바로 아래 빈 문단을 추가하고, 원문 마크다운 편집 상태로 전환하지 않는다. - 게시물 작성 화면 상단 제목 입력 후 Enter는 현재 에디터 모드를 유지한 채 본문 첫 줄(마크다운 첫 줄이 제목이면 그 다음 줄)로 포커스를 옮긴다. - 소스 모드 라인 번호는 논리 줄 수를 표시하되, 긴 문장 자동 줄바꿈으로 textarea의 한 줄 높이가 늘어나면 라인 번호 칸도 같은 높이로 맞춘다. - 소스 모드에서 라이브 모드로 전환하면 현재 textarea 커서 줄과 줄 안 오프셋을 기준으로 대응하는 라이브 편집 블록에 포커스를 두고, 대상 줄이 화면 중앙에 가깝게 보이도록 스크롤한다. - 라이브 모드에서 소스 모드로 전환하면 현재 포커스된 블록 또는 화면 상단에 가까운 원본 줄을 기준으로 textarea 커서와 스크롤 위치를 복원한다. - YouTube 임베드 URL은 공개 화면에서 본문 폭 기준 16:9 iframe으로 렌더링한다. - Twitter/X 게시물 URL(`twitter.com`·`x.com`·`mobile.twitter.com`, 경로에 `status` 포함)은 `platform.twitter.com/embed/Tweet.html` iframe으로 렌더링하며, 테마는 `useThemeMode()`와 동기화한다. X 공식 iframe의 내부 최대 폭 때문에 공개 화면에서는 카드 폭을 좁혀 중앙 정렬한다. - Mastodon 공개 게시물 URL(`/@user/id`, `/users/user/statuses/id`)은 `{원본 URL}/embed` iframe으로 렌더링한다. iframe 로드 후 Mastodon 공식 embed 방식과 같은 `postMessage` 높이 요청을 보내 응답 높이를 반영한다. 인스턴스가 embed를 차단하거나 지원하지 않으면 브라우저 iframe 정책에 따라 표시되지 않을 수 있다. - 그 외 URL은 외부 링크 텍스트 카드로 표시한다. - 비디오 블록은 `:::video` fenced block 안에 `url`, `title`, `poster`, `caption` 값을 저장하며 공개 화면에서 가로형 비디오 카드로 렌더링한다. 관리자 `/video` 슬래시 명령은 비디오 미디어 선택·업로드 모달을 열고 선택 파일 URL을 자동으로 채운다. - 오디오 블록은 `:::audio` fenced block 안에 `url`, `title`, `description` 값을 저장하며 공개 화면에서 아이콘+플레이어 카드로 렌더링한다. 관리자 `/audio` 슬래시 명령은 오디오 미디어 선택·업로드 모달을 열고 선택 파일 URL을 자동으로 채운다. - 파일 블록은 `:::file` fenced block 안에 `url`, `title`, `description`, `name`, `size` 값을 저장하며 공개 화면에서 다운로드 카드로 렌더링한다. 관리자 `/file` 슬래시 명령은 문서 파일 선택·업로드 모달을 열고 URL·파일명·크기를 자동으로 채운다. - 북마크 블록은 `:::bookmark` fenced block으로 저장할 수 있으며 공개 화면에서 Thred형 가로 카드로 렌더링한다. - 회원가입(뉴스레터) CTA는 `:::signup` fenced block으로 저장할 수 있으며 실제 폼 연동은 후속 작업으로 분리한다. ### 관리자 페이지 편집 - 고정 페이지 작성/수정 화면은 게시글 작성 화면과 같은 전체 화면 에디터 구조를 사용한다. 상단 툴바에 목록 이동, 저장 상태, 저장 버튼, 설정 패널 토글을 두고 오른쪽 설정 패널은 접고 펼칠 수 있다. - 고정 페이지 작성/수정 화면의 기본 모드는 HTML 문서 모드이며, `markdown` 모드는 `일반 텍스트`로 표시한다. - 고정 페이지 HTML 문서 모드는 전체 HTML 붙여넣기용 textarea를 사용하고, 공개 URL에서 Nuxt 레이아웃 없이 원문 HTML로 응답한다. HTML 문서 textarea에서 본문이 비어 있거나 `!`만 입력된 상태로 Tab을 누르면 기본 HTML 골격을 실제 본문에 자동 완성한다. - 페이지 슬러그는 게시글처럼 한글 제목을 영문으로 로마자화해 자동 생성한다. - 페이지 상태, 페이지 형식, Page URL, HTML 자산 업로드, 삭제 액션은 오른쪽 설정 패널에서 관리한다. - 페이지 작성·수정 중 저장되지 않은 입력이 있으면 내부 라우트 이동과 브라우저 새로고침·닫기를 확인한다. 저장 완료 기준은 응답 시점의 폼 전체가 아니라 서버 요청에 실제로 전달한 payload이므로, 저장 중 추가 입력은 미저장 변경으로 유지한다. 새 페이지가 생성된 뒤 이탈 확인으로 이동이 보류되면 이후 저장은 생성된 ID를 `PUT`으로 수정해 중복 페이지 생성을 막는다. - 페이지 형식 선택은 HTML 문서/일반 텍스트 모드와 무관하게 항상 표시한다. HTML 자산 업로드는 HTML 문서 모드에서만 표시한다. - HTML 자산 업로드는 기존 관리자 업로드 API(`/admin/api/uploads`)를 사용하며, 성공한 파일 URL을 HTML textarea 현재 커서 위치에 삽입한다. 업로드 파일은 현재 에디터 업로드 정책에 따라 `/uploads/posts/YYYY/MM/` 아래 저장되고 미디어 라이브러리 논리 폴더는 `미분류`로 기록된다. - 고정 페이지는 제목, 슬러그, 렌더링 방식, 본문을 저장한다. 썸네일 등록 이미지는 홈 Pages 진열장 커버로 사용한다. - 고정 페이지는 게시물 목록과 태그 목록에 노출하지 않는다. - 고정 페이지 공개 보기 경로는 `/pages/:slug`를 사용한다. - 고정 페이지 상태는 `published`, `draft`, `private`를 사용한다. 공개 목록·상세·HTML 문서 미들웨어는 `published` 상태만 응답하고, `draft`와 `private`는 공개 URL에서 찾을 수 없는 페이지로 처리한다. ### 사이트 설정 - 관리자 사이트 설정 UI는 `/admin/settings`에서 제공한다. Ghost Admin과 유사하게 **전체 화면**으로 표시하며, 좌측 내비와 우측 본문을 **한 덩어리로 중앙 정렬**(`max-w` 래퍼, 본문 카드 영역은 약 760px 상한)하고, 페이지 배경은 밝은 회색·본문 열은 흰색으로 구분한다. 우측 본문을 스크롤하면 현재 보이는 구역에 맞춰 좌측 메뉴 활성 배경을 갱신한다. **우측 상단 고정** 닫기 버튼과 `Escape` 키로 설정 화면을 닫으며, 브라우저 히스토리가 있으면 `뒤로 가기`, 없으면 `/admin`으로 이동한다. 콘텐츠·안전 영역의 **사이트 용량**은 그래프 없이 텍스트 카드로 표시하고, 기준 시각·콘텐츠 수량·파일 용량을 새로고침할 수 있다. 게시물 백업 도구는 `게시물 내보내기`와 `게시물 가져오기` 독립 카드로 표시한다. 내보내기 기본 화면은 제목·설명·내보내기 버튼만 표시하고, 상세 설정은 버튼을 눌렀을 때만 펼쳐진다. 내보내기 상세는 전체·특정년·특정월·직접 지정 범위, 목표 ZIP 용량, ZIP당 최대 게시물 수 지정을 제공한다. 내보내기 작업 목록은 작업이 있을 때만 내보내기 설정 카드 아래 별도 카드로 표시하며, 완료 작업은 상태 배지를 숨기고 만료일과 준비 완료 파일 선택 목록을 중심으로 표시한다. 전체 선택·선택 파일 다운로드·실패 작업 재시도·실패 상세 오류·완료/실패 작업 삭제를 제공하며, 진행도 영역은 대기·생성 중 작업에서만 표시한다. 가져오기 기본 화면은 제목·설명·가져오기 버튼만 표시하고, 버튼을 누르면 ZIP 드롭존과 `적용` 버튼이 펼쳐진다. 가져오기는 파일 선택만으로 실행하지 않고 `적용` 버튼을 눌렀을 때만 Import 작업 생성 API를 호출한다. 생성된 Import 작업은 작업 센터 모달에서 전체 진행률과 게시물별 대기·진행중·완료·스킵·오류 상태를 표로 표시하며, 완료·실패 작업 기록은 모달에서 삭제할 수 있다. 대기 중·생성 중 작업이 있으면 새 내보내기 요청 버튼을 비활성화한다. **사이트 코드** 카드는 ads.txt, 공통 헤더 코드, 공통 푸터 코드의 등록 여부를 라벨/값 세로 행으로 보여 주고, `편집`을 눌렀을 때만 textarea와 저장/취소가 나타난다. **스팸 필터**는 가입 금지 닉네임을 저장한다. **블로그 제목·설명** 카드는 기본적으로 사이트 이름·설명을 라벨/값 세로 행으로 읽기 전용 표시하고, `편집`을 눌렀을 때만 입력 필드·미리보기·저장/취소가 나타난다. 제목·설명 편집 중 `Escape`는 설정 닫기 대신 편집 취소로 동작한다. **사이트 정보** 카드는 로고, 공개 URL, 푸터 저작권 문구를 관리하며, 읽기 화면의 로고는 등록 상태 문구 없이 이미지 또는 점선 미등록 박스로 표시한다. **POST 설정**·**어나운스 바**는 읽기 모드에서도 토글 UI를 비활성화 상태로 보여 주며, 켜짐 상태도 조작 가능한 활성 스위치처럼 보이지 않도록 낮은 대비와 `cursor-not-allowed`를 사용한다. - 게시물 Import/Export 1차 포맷은 Obsidian 호환 백업 번들을 기준으로 한다. Export는 게시물마다 별도 폴더를 만들고, 폴더 안에 `제목.md` 메인 파일과 `images/`, `files/` 같은 자산 폴더를 함께 둔다. 본문은 기존 Markdown을 최대한 유지하되 `/uploads/...`로 연결된 내부 이미지·파일은 번들 안의 로컬 파일로 복사하고, Markdown 참조는 `./images/...` 또는 `./files/...` 같은 상대 경로로 재작성한다. 제목·슬러그·상태·발행일·요약·대표 이미지·대표 이미지 본문 상단 표시 여부·SEO·태그는 YAML frontmatter에 저장한다. Import는 같은 구조의 ZIP을 읽어 frontmatter를 게시물 메타데이터로 복원하고, 로컬 자산은 `/uploads/posts/YYYY/MM/`에 저장한 뒤 본문 경로를 새 `/uploads/...` URL로 다시 매핑한다. 태그는 inline 배열(`tags: ["a"]`)과 Obsidian식 블록 배열(`tags:\n- a`)을 모두 읽는다. 기존 ZIP처럼 `show_featured_image`가 없으면 `false`로 가져온다. 같은 슬러그가 이미 있으면 기존 글을 덮어쓰거나 `slug-2`처럼 복제하지 않고 건너뛰며, 해당 게시물의 자산도 다시 저장하지 않는다. 같은 Import 실행 안에서 여러 게시물이 같은 ZIP 자산을 참조하면 한 번 저장한 URL을 재사용하고, 재시도 중 같은 파일명 계열과 같은 해시의 자산이 이미 있으면 기존 파일 URL을 재사용한다. ZIP 안에서 참조 자산을 찾지 못한 게시물은 불완전한 글을 만들지 않고 해당 게시물 행을 오류로 남긴 뒤 다음 게시물을 계속 처리한다. 1회 Import는 최대 1000개 Markdown 게시물까지 처리한다. - 대용량 게시물 Export는 즉시 응답 다운로드가 아니라 백그라운드 작업으로 처리한다. 관리자가 Export를 요청하면 서버는 작업 레코드를 만들고, 게시물을 목표 zip 용량 기준으로 나누어 여러 zip 파일을 순차 생성한다. 계획 단계에서는 본문 문자열 바이트와 내부 `/uploads` 자산 파일 크기를 합산해 `max_file_size_bytes`를 넘기기 전에 새 분할 파일을 만들며, `chunk_size`는 한 ZIP에 들어갈 게시물 수의 안전 상한으로만 사용한다. 현재 구현은 요청 시 `post_export_jobs` 작업과 `post_export_files` 분할 파일 계획을 생성하고, worker가 대기 작업을 순차 실행해 `processed_count`, `current_part_index`, `progress_message`, `started_at`을 갱신한다. worker는 서버 시작과 30초 주기로 `queued` 및 재시작으로 중단된 `processing` 작업을 찾고, 작업 ID별 PostgreSQL advisory lock을 전용 연결에 유지해 여러 앱 인스턴스가 같은 작업을 동시에 생성하지 못하게 한다. Export 대상은 전체 또는 `COALESCE(published_at, created_at)` 기준 특정년·특정월·직접 지정 날짜 범위로 제한할 수 있다. 설정 화면은 대기 중·생성 중 작업이 있을 때 5초 간격으로 작업 목록을 새로고침한다. 파일명은 기본적으로 `사이트명_범위_시작번호-끝번호.zip` 형식을 사용한다(예: `sori.studio_2026-05_1-100.zip`). 각 zip에는 해당 범위 게시물 폴더와 자산 폴더가 들어가며, 준비 완료된 분할 파일은 관리자 다운로드 API로 받을 수 있다. 준비 완료 파일은 체크박스로 선택한 뒤 전체 선택 또는 선택 파일 다운로드로 브라우저에서 순차 다운로드할 수 있다. 실패 작업은 이미 준비된 파일을 유지하고 실패·대기 파일만 다시 생성하도록 재시도할 수 있으며, 실패 상세 로그는 작업 카드에서 확인한다. Resend 환경 변수가 설정되어 있으면 모든 분할 파일 생성 완료 후 요청 관리자 이메일로 알림을 보낸다. 완료·실패한 작업은 관리자가 즉시 삭제할 수 있고, 삭제 시 DB 레코드와 생성 ZIP 파일을 함께 정리한다. 서버 용량 보호를 위해 export 산출물 보존 기간은 최대 100일로 제한하며, 만료된 완료·실패 작업은 목록 조회나 새 요청 시 생성 ZIP 파일과 함께 자동 정리된다. - 사이트 설정은 `site_settings` 테이블의 단일 레코드로 관리한다. - 설정 카드 저장은 카드가 담당하는 필드만 `PATCH /admin/api/settings`로 전달하며, 서버는 전달된 컬럼만 단일 `UPDATE`로 수정한다. 저장 성공 응답도 해당 필드만 현재 폼에 반영한다. - 관리자는 사이트 이름, 설명, 사이트 URL, 로고 이미지, 저작권 문구를 수정할 수 있다. - **메인 화면**(`home_cover_image_url`, `home_cover_dark_image_url`, `home_cover_title`, `home_cover_text`): 홈(`/`) 상단 720px 커버 배너. 라이트 이미지는 기본 커버이며, 다크 이미지가 있으면 시스템 다크모드 또는 `html[data-theme='dark']`에서 다크 이미지를 표시한다. 다크 이미지가 없으면 라이트 이미지를 그대로 사용한다. 이미지가 있을 때만 `HomeHero`를 표시하며, 제목·짧은 본문은 이미지 왼쪽 하단 그라데이션 오버레이로 겹친다. 오버레이 본문은 textarea에서 입력한 줄바꿈(`\n`)을 저장·표시하며, `HomeHero` 본문은 `whitespace-pre-line`으로 여러 줄을 렌더링한다. 관리자 UI에서는 라이트모드와 다크모드 프리뷰를 상하로 모두 표시하고, 각 모드 제목 오른쪽의 이미지 변경·삭제 버튼으로 개별 이미지를 관리한다. 이미지가 비어 있는 모드는 점선 드롭존으로 표시하며 파일 선택과 드래그 앤 드롭 업로드를 지원한다. 커버 파일 업로드·제목·본문은 편집 뒤 **저장** 한 번에 `PATCH /admin/api/settings`로 반영한다. 파일 업로드 API는 디스크에만 올리고 URL을 돌려준다(가로 720px WebP, `/uploads/system/home-cover-YYYYMM-random.webp`). - **POST 설정**(`show_post_updated_at`, `post_tag_limit`, `home_latest_post_limit`, `post_list_page_size`, `tag_post_list_page_size`, `featured_post_limit`, `page_section_item_limit`, `upload_max_file_count`, `upload_max_total_size`): 발행 후 본문·메타 수정이 있을 때 관리자 글 목록에 수정 시각 보조 줄을 표시할지 여부와 게시물별 태그 최대 개수, 공개 목록 표시 개수, 관리자 미디어 1회 업로드 제한을 관리한다. `post_tag_limit` 기본값은 5이며 1~10 범위로 제한한다. 표시개수 설정은 Latest, Posts, 태그 게시물, Featured, Pages 섹션의 공개 목록 로드·표시 개수를 관리하며 1~50 범위의 셀렉트 값만 사용한다. 업로드 제한은 기본 파일 20개·전체 300MB이며 파일 수는 1~50, 전체 용량은 1MB~1GB 범위에서 관리한다. 공개 게시글 상세에는 수정 시각을 표시하지 않는다. - **가입 금지 닉네임**(`signup_blocked_usernames`, JSON 문자열): 회원가입·회원 프로필 닉네임 변경 시 닉네임에 목록 단어가 포함되면 거부한다(대소문자 무시, 부분 일치). 안내 문구는 `{단어}은 사용할 수 없는 단어입니다.` 형식이다. 기본값: `admin`, `master`, `zenn`, `sori`, `sori.studio`. - **어나운스 바**(`announcement_enabled`, `announcement_text`, `announcement_url`, `announcement_background_color`): `announcement_enabled`가 true이고 문구가 비어 있지 않으면 공개 레이아웃(`default`·`post`) 헤더 위에 전체 너비 배너를 표시한다. `announcement_url`이 있으면 문구를 링크로 감싼다(내부 `/…` 또는 `http(s)://`). 배경색은 `#15171a`·`#ffffff`·`#ff4f2e` 중 하나. 방문자는 **이번 방문 동안 닫기**(X, `sessionStorage`) 또는 **7일간 보지 않기**(`localStorage`, 만료 시각 저장)를 선택할 수 있다. 공지 내용이 바뀌어 `updatedAt`이 달라지면 다시 노출된다. - **사이트 코드**(`ads_txt`, `custom_head_code`, `custom_footer_code`): `ads_txt`는 루트 `/ads.txt`에서 `text/plain`으로 응답한다. `custom_head_code`는 공개 Nuxt HTML 응답의 `head` 끝에, `custom_footer_code`는 `body` 끝에 원문 HTML로 삽입한다. 관리자 페이지, `/api`, `/uploads`, `/_nuxt`, `/ads.txt` 응답에는 삽입하지 않는다. - 로고 이미지는 1:1 비율로 저장하며 `/admin/api/settings/logo` 업로드 시 `/uploads/system/logo-YYYYMM-random.webp`와 `/uploads/system/favicon-YYYYMM-random.png`를 고유 파일명으로 함께 생성한다. 업로드 API는 파일 URL만 반환하고, 실제 `logo_url`·`favicon_url` DB 반영은 사이트 정보 카드의 **저장** 버튼에서 처리한다. 같은 URL 덮어쓰기로 인한 브라우저·운영 정적 캐시 문제를 피하기 위해 로고 교체마다 새 URL을 저장한다. - 공개 헤더와 오른쪽 사이드바는 공개 사이트 설정 API 값을 사용한다. - 공개 헤더와 오른쪽 사이드바는 `logo_url`이 있으면 이미지 로고를 표시하고, 없으면 `logo_text` fallback을 쓴다. 오른쪽 사이드바 로고는 48px 정사각형으로 고정해 옆 텍스트에 밀려 줄어들지 않게 한다. `favicon_url`은 head의 icon 링크로 연결한다. - DB 연결이 없는 환경에서는 환경 변수와 기본값 기반 설정을 사용한다. - 공개 앱·헤더·오른쪽 사이드바·어나운스 바·홈·목록·태그·상세·회원가입 화면의 공개 사이트 설정 조회는 `usePublicSiteSettings` composable의 `site-settings-public` key와 공통 기본값을 공유한다. ### 메뉴/네비게이션 - 네비게이션은 `navigation_items` 테이블로 관리한다. - 컬럼: `parent_id`(nullable, self FK, `ON DELETE CASCADE`), `is_folder`(boolean, **자식이 있는 상단 항목이면 저장 시 서버가 true로 설정**), `location`(`primary`|`footer`|`recommended`), `sort_order`, `label`, `url`, `is_visible`(저장 시 항상 true로 정리). `(location, label, url)` 유니크 제약은 제거되었다. - 동일 `location`·`parent_id`·`label`·`url` 조합은 중복 저장하지 않는다. 반복 마이그레이션으로 생긴 중복은 `019_dedupe_navigation_items.sql`이 정리하고, 표현식 유니크 인덱스로 재발을 막는다. - `GET /api/navigation` 응답: `primary`는 **트리**(각 노드에 `children` 배열이 있을 수 있음, 리프는 `children` 없음). 노드 필드: `id`, `label`, `url`, `isFolder`, `isVisible`. 트리 조립 시 **동일 `id`는 한 번만 반영**하고, DB 평면 행에 `parent_id`가 있어 자식으로 붙은 항목은 **루트에 두지 않는다**. **상단은 루트 직속 자식만** 트리에 붙이며(부모의 부모가 있는 행은 자식으로 무시), `footer`·`recommended`는 **평면** 배열(`parent_id` 없음)이다. `recommended`는 `id`, `label`, `url`, `descriptionText`, `thumbnailUrl`, `cachedFaviconUrl`, `isVisible`을 내려준다. 관리자 `GET /admin/api/navigation`에는 추가로 `faviconCachedAt`을 포함한다. - `PUT /admin/api/navigation` 요청 본문의 각 항목은 반드시 `id`(UUID)를 포함한다. 저장 시 `sort_order`는 `primary`·`footer`·`recommended` 각각 위치별 트리(또는 평면 루트) DFS 순으로 다시 부여한다. `parent_id`는 `primary`에서만 허용되며 **상단은 한 단계(루트→자식)만** 허용한다. `footer`·`recommended` 항목은 항상 루트다. `is_visible`·`is_folder`는 요청값과 무관하게 서버에서 **항상 표시·자식 유무 기준 폴더**로 덮어쓴다. - URL은 `/`로 시작하는 내부 경로, `http(s)://` 외부 URL, 폴더 전용 자리 표시 `#`를 허용한다. 저장 시 `uniare.sori.studio`처럼 프로토콜 없는 외부 호스트는 `https://`를 자동으로 붙인다. 관리자 추천 사이트 편집 모달은 URL 접두사(`https://`·`http://`·내부 경로) 선택과 본문 입력으로 나눈다. - 관리자 메뉴 화면은 **메인 네비게이션**·**페이지 섹션**·**하단 네비게이션**·**추천 사이트** 탭으로 구분한다. 메인·하단·추천 사이트 추가는 모두 추가 버튼 클릭 후 모달에서 필요한 정보를 입력하고 적용해야 목록에 반영된다. 각 탭 작업줄은 왼쪽에 추가 버튼, 오른쪽에 저장 버튼을 두며, 메인·하단·추천 사이트 변경사항은 `네비게이션 저장`, 페이지 섹션 변경사항은 `페이지 섹션 저장`으로 저장한다. 편집 UI는 **태그 관리 메인 태그**와 같은 테이블·`cursor-move` 행 드래그 패턴을 쓰며, 드래그는 입력·버튼 위가 아닌 행 여백·개요 열에서 시작한다. 메인 네비게이션은 `buildNavigationEditorTree` 결과를 `flattenNavigationEditorWrappers`로 한 테이블에 평면 표시하고, **같은 행의 위 1/3·가운데·아래 1/3**에 드롭하면 각각 대상 **앞**(동일 부모)·**하위**(대상의 자식, **루트 행에만**)·**뒤**(동일 부모)로 이동한다. **메인 네비게이션은 루트→자식 한 단계만** 허용하며(하위 행에는 가운데 드롭이 형제 앞·뒤로 대체됨, 이미 하위가 있는 항목은 다른 항목의 하위로 넣을 수 없음), 드래그 중 하이라이트는 **형제 앞·뒤**를 파란 가로 끝선·연한 파란 배경, **하위 편입**을 앰버 링·연한 앰버 배경으로 구분하고, 개요 열에 `앞에 끼움` / `뒤에 끼움` / `하위로 넣기` 짧은 문구를 덧붙인다. 개요 열 표기는 `1`, `2.1`, `2.2`, `3`처럼 깊이별 계층 번호로 보이며, 라벨 열은 깊이만큼 `padding-left`로 들여쓴다. 자기 자신·자기 하위로의 편입은 거부한다. 페이지 섹션·하단·추천 사이트는 평면 목록만 드래그 정렬한다. **추천 사이트** 탭 목록은 공개 Recommended와 같은 **카드**(아이콘·제목·설명 또는 URL) 형태이며, 캐시 갱신 시각은 카드 오른쪽 끝에 표시한다. 추천 사이트 드래그는 카드 **위·아래 절반**에 드롭하면 각각 대상 **앞·뒤**로 삽입되며, 파란 가로 삽입선·`앞에 삽입` / `뒤에 삽입` 안내를 표시한다. 추천 사이트는 공개 화면 **왼쪽 사이드바** Categories 아래 Recommended 영역에 카드로 노출되며, 대체 텍스트가 있으면 URL 대신 대체 텍스트를 표시한다. 아이콘 우선순위는 **수동 썸네일 URL > 서버 캐시 파비콘(`cached_favicon_url`) > 외부 faviconV2 프록시**이다. 서버는 외부 `https://` URL의 파비콘을 `/uploads/system/recommended-favicon-*.png`로 저장하고 `favicon_cached_at`을 기록한다. 자동 갱신은 **매월 1일 03:00(KST)** 에 전체 추천 사이트를 대상으로 수행하며, **관리자 추천 사이트 탭**은 공개와 같은 **카드 목록**으로 미리보기하고 **편집** 버튼으로 모달에서 제목·URL·대체 텍스트·썸네일 URL 전체를 확인·수정한다. 삭제·취소(배경 클릭 포함)는 브라우저 `confirm`으로 한 번 더 확인하며, 모달에서 **적용** 전 입력 변경이 있으면 닫기 전에 안내한다. 편집 모달에서 `POST /admin/api/navigation/:id/favicon-refresh`로 파비콘을 수동 갱신할 수 있다. 네비게이션 저장 시 캐시 없는 추천 사이트는 백그라운드로 최초 캐시를 시도한다. 운영 수동 일괄 갱신은 `npm run navigation:refresh-recommended-favicons`를 사용한다. 오른쪽 사이드바는 추천 사이트를 렌더하지 않고 광고와 게시물 목차 영역에 집중한다. - `parent_id` / `is_folder` 컬럼이 DB에 없을 때 저장은 실패한다. `npm run db:migrate:dev`로 `017_navigation_hierarchy.sql`을 적용해야 한다(저장 API는 해당 경우 한국어 안내 메시지를 반환할 수 있다). - 공개 왼쪽 사이드바 상단은 `SidebarPrimaryNavList`로 렌더링한다. **하위가 있는 노드**는 한 줄 `button`으로, **행 전체(이름·왼쪽 세로 데코·chevron) 클릭**으로 접기/펼친다. 부모·리프 모두 왼쪽 장식은 **기본 세로 막대(`--site-line`)**, **호버 시에만** 리프와 동일하게 **작은 원형**으로 전환한다. **내부 경로**(`/`로 시작, `//`·`http(s)` 제외)이고 현재 `route.path`와 정규화한 경로가 같으면 장식 색을 **`--site-accent`(브랜드 오렌지)**로 둔다. 외부 URL은 비교하지 않는다. 펼침 상태는 `localStorage` 키 `sori-primary-nav-expanded`에 저장된다. 상단·리프 링크·부모 버튼 행은 **`w-full`**로 `site-sidebar-nav-row` 호버 배경이 가로 전체를 쓴다(라이트 `#F7F4EF`, 다크는 `site-panel-hover`와 동일한 `color-mix` 패턴). - 관리자 메뉴 관리 화면에서 저장 API로 보내는 직렬화 결과가 서버에서 불러온 직후와 동일하면 `메뉴 저장` 버튼이 비활성화된다. ### 관리자 인증 - 관리자 인증은 `users.is_admin=true` 회원의 이메일/비밀번호(bcrypt 해시) 기반으로 처리한다. - DB에 사용자가 없으면 `/signup`에서 관리자 등록 모드(관리자 이름/이메일/비밀번호/비밀번호 확인)로 첫 계정을 생성한다. - DB에 owner/admin 계정이 없는 최초 상태에서 `/admin/login`에 `ADMIN_EMAIL`/`ADMIN_PASSWORD`와 같은 값을 입력하면 첫 owner 계정을 DB에 생성한 뒤 로그인한다. 같은 이메일의 일반 회원이 이미 있으면 해당 회원을 owner로 승격하고 비밀번호를 `ADMIN_PASSWORD` 기준 bcrypt 해시로 갱신한다. 이미 owner/admin 계정이 있으면 환경 변수 계정으로 우회 로그인하지 않고 DB의 관리자 계정만 사용한다. - 최초 owner 생성 시 `is_admin=true`, `user_role=owner`를 자동 부여한다. 최초 관리자 판정은 동시 요청에서 중복 owner가 생기지 않도록 `users` 테이블 잠금 안에서 처리한다. - 관리자 로그인 성공 시 httpOnly 세션 쿠키(`sori_admin_session`)를 `/` 경로에 설정한다. Secure는 실제 HTTPS 요청(`x-forwarded-proto` 포함)일 때만 사용한다. - `/admin/login` 로그인 제출 버튼은 제출 중일 때만 비활성화한다. 빈 값은 브라우저 `required`와 서버 검증으로 처리하며, 자동완성 값은 제출 직전 동기화한다. - 관리자 로그인 성공 시 관리자/회원 세션 쿠키를 함께 설정하고 `users.previous_last_seen_at`/`previous_last_seen_ip`에 직전 로그인 값을 보존한 뒤 `last_seen_at`/`last_seen_ip`를 현재 로그인으로 갱신한다. 요청 IP는 프록시 헤더(`x-forwarded-for`)를 포함해 기록한다. - 관리자 설정 화면은 사이트 자체 설정만 관리한다. 관리자 프로필과 비밀번호는 멤버 편집 화면의 계정 작업에서 처리한다. - 관리자 사이드바 하단 사용자 메뉴의 `내 프로필`은 `/admin/members/:id` 멤버 편집 화면으로 이동한다. - 관리자 멤버 목록은 Ghost형 테이블 기준으로 닉네임 아래 이메일, 가입일 아래 최근 활동을 함께 표시한다. 상태 열은 멤버 등급을 먼저 표시하고, 비활성 회원만 작은 보조 상태로 표시한다. - 관리자 멤버 목록은 글 목록과 같은 테두리형 검색 입력, 멤버 추가 버튼, 조건 필터를 제공한다. 필터는 이름·이메일·레이블 텍스트 조건, 활성/비활성 상태 조건, 최근 접속·가입일 날짜 조건을 지원하며 여러 조건은 AND로 적용한다. - 관리자 멤버 목록은 뉴스레터 지표 대신 댓글 작성 개수를 표시한다. - 관리자 멤버 상세/추가 화면은 Ghost형 편집 화면을 기준으로 썸네일, 이름, 이메일, 레이블, 관리자 노트를 편집한다. 본문은 3분할 그리드로 요약 영역 1fr, 입력 영역 2fr 비율을 사용한다. 기존 회원 상세는 처음에는 읽기 전용 보기 모드로 현재 값만 표시하고, 상단 `수정하기`를 누르면 입력 필드·셀렉트가 편집 컨트롤로 전환된다. 저장 버튼은 수정 모드에서 기존 값과 달라진 내용이 있을 때만 활성화한다. 썸네일은 URL 입력 대신 요약 영역의 원형 썸네일 hover 액션으로 등록·변경·제거한다. 기존 회원 상세는 멤버 등급 선택, 가입 정보와 활동 요약을 표시하고, 신규 회원 화면은 활동 영역을 표시하지 않는다. 멤버 등급은 셀렉트 변경 즉시 저장하지 않고 저장 버튼을 눌렀을 때 기본 정보와 함께 반영한다. 소유자 본인이나 관리자가 다른 관리자·소유자를 보는 등 서버에서 변경 불가한 경우 등급 셀렉트는 비활성화하고, 등급 변경 권한이 없는 세션에서는 등급을 일반 텍스트로 표시한다. 저장·업로드·비밀번호 변경 피드백은 우측 상단 관리자 토스트로 표시한다. 기존 회원 상세의 설정 메뉴는 관리자 직접 비밀번호 변경(`PUT /admin/api/members/:id/password`)과 멤버 삭제(`DELETE /admin/api/members/:id`)를 제공한다. - 관리자 멤버 추가/수정 화면은 저장되지 않은 변경사항이 있을 때 내부 라우트 이동을 공통 확인 모달로 막는다. 관리자 게시글 작성/수정 화면은 **서버에 이미 즉시 발행 또는 예약으로 저장된 글**에서 미저장 변경이 있을 때만 동일 방식으로 내부 이동을 막고, 초안(서버 기준)은 서버 자동 저장과 라우트 이탈 직전 플러시로 처리하여 해당 경우에는 모달을 쓰지 않는다. 브라우저 새로고침·탭 닫기는 브라우저 기본 `beforeunload` 확인을 사용한다. 게시글 화면에서 이탈을 승인하면 레거시 키 `SORI_ADMIN_POST_AUTOSAVE:*`가 있으면 삭제한다. - `users.member_labels`는 관리자용 문자열 배열이며, 이후 사용자별 칭호/분류 용도로 확장한다. `users.member_note`는 관리자에게만 보이는 500자 이하 메모다. - 관리자 멤버 권한은 `소유자(owner)`, `관리자(admin)`, `VIP(vip)`, `멤버(member)` 단계를 사용한다. VIP는 관리자 권한이 없지만 멤버십 게시물을 볼 수 있는 등급이며, 상세 화면에서 변경한다. 권한 변경은 소유자와 관리자만 가능하다. **관리자**는 VIP·멤버의 정보만 수정·삭제·비밀번호 변경할 수 있으며, 소유자·관리자·본인 계정은 조회만 한다. 관리자는 소유자·관리자 등급을 부여할 수 없다. **소유자**는 모든 등급 회원 정보를 수정할 수 있고 본인 정보 수정도 가능하나, 본인 등급은 직접 낮출 수 없다. 소유자는 다른 회원을 소유자로 지정할 수 있으며, 이때 확인 모달 후 `POST /admin/api/members/:id/ownership-transfer`로 권한을 이전하고 기존 소유자는 관리자가 된다. 소유자는 항상 1명만 유지된다. - 관리자 페이지 접근은 `/admin/api/auth/me` 확인 후 허용한다. - 관리자 세션 토큰은 `ADMIN_PASSWORD` 기반 HMAC 서명으로 검증하며 발급 시점의 `users.session_version`을 포함한다. - `/admin/api/auth/login`, `/admin/api/auth/logout`을 제외한 관리자 API 요청은 서버 미들웨어에서 세션 사용자 ID의 현재 DB 권한이 `owner` 또는 `admin`인지, 세션 버전이 현재 DB 값과 일치하는지 함께 확인한다. 권한 변경·계정 삭제·비밀번호 변경 이후 남아 있는 기존 관리자 쿠키는 이 단계에서 차단한다. ### 게시물 작성자 - `posts.author_id`는 게시물을 만든 회원 ID이며 `users.id`를 참조한다(`ON DELETE SET NULL`). - 관리자 게시물 생성 시 현재 관리자 세션의 `userId`를 `author_id`로 저장한다. - 기존 게시물은 마이그레이션 `032_add_post_author.sql`에서 owner/admin 계정이 정확히 1개일 때만 해당 계정으로 `author_id`를 채운다. 여러 관리자 계정이 있으면 임의 배정을 피하기 위해 자동 backfill하지 않는다. - 공개 게시글 상세의 편집 아이콘 노출은 관리자 여부가 아니라 현재 로그인 회원 ID와 `posts.author_id` 일치 여부를 기준으로 한다. ### 회원 인증 - 회원 인증은 `users` 테이블의 이메일/비밀번호(bcrypt 해시) 기반으로 처리한다. - `/signin` 로그인 제출 버튼은 이메일·비밀번호가 모두 입력된 경우에만 활성화한다. - 로그인 성공 시 httpOnly 세션 쿠키(`sori_member_session`)를 `/` 경로에 설정하고 발급 시점의 `users.session_version`을 서명된 페이로드에 포함한다. - 회원 API(`POST /api/auth/signup`, `POST /api/auth/login`, `GET /api/auth/me`, `GET/PUT /api/auth/profile`, `POST /api/auth/logout`, `GET /api/auth/bootstrap-status`, `POST /api/auth/email-otp/request`, `POST /api/auth/password-reset/confirm`)로 세션·이메일 OTP를 관리한다. - 회원 로그인 성공 시 `previous_last_seen_at`/`previous_last_seen_ip`에 직전 로그인 값을 보존한 뒤 `last_seen_at`/`last_seen_ip`를 현재 로그인으로 갱신한다. 요청 IP는 프록시 헤더(`x-forwarded-for`)를 포함해 기록한다. `/api/auth/me`는 세션 확인만 수행하고 로그인 이력을 갱신하지 않는다. - 사용자 설정 화면은 공개 본문 폭에 맞춰 프로필 요약을 상단에 두고, 프로필 입력과 활동 정보를 하단에 배치한다. 비밀번호 변경과 회원 탈퇴는 설정 버튼의 모달 액션으로만 노출한다. 활동 정보의 `마지막 로그인`은 현재 로그인 이전에 저장된 `previous_last_seen_at`을 표시한다. - 첫 회원가입 시 관리자 세션도 함께 설정되어 관리자 화면(`/admin`)으로 바로 진입할 수 있다. - 회원 세션 서명은 `MEMBER_SESSION_SECRET`만 사용하며, 값이 없으면 서버 오류로 실패한다. 인증이 필요한 회원 API와 멤버십 콘텐츠 조회는 토큰 버전과 DB의 `session_version`이 일치하는지 확인한다. - Docker 운영 서버 환경 변수는 이미지 빌드 시점 `runtimeConfig`보다 컨테이너 런타임 `process.env` 값을 우선한다. --- ## 미디어 관리 ### 업로드 경로 규칙 ``` /uploads/posts/YYYY/MM/filename.webp /uploads/pages/YYYY/MM/filename.webp /uploads/members/avatars/YYYY/MM/filename.webp /uploads/system/logo-YYYYMM-random.webp /uploads/system/favicon-YYYYMM-random.png /uploads/system/home-cover-YYYYMM-random.webp ``` - 관리자 에디터 이미지 업로드 API는 디스크상 `public/uploads/posts/YYYY/MM/`에 저장하지만, DB가 있을 때 `media_metadata`에는 논리 폴더 **`미분류`**로 기록한다. 메타가 없을 때도 서버 목록에서는 `posts/...` 경로를 **`미분류`**로 표시한다(디스크 1단계 `posts`와 이중 표기하지 않음). 저장 파일명은 업로드 원본 파일명(Unicode 문자·숫자와 `._-`만 유지)을 우선 쓰고, 같은 월 디렉터리에 동일 이름이 있으면 `이름-2`, `이름-3` 식으로 넘버링한다. - `미분류`는 예약된 논리 폴더이며, 사용자가 폴더를 지정하지 않았거나 폴더 삭제 후 되돌림 등으로 `media_metadata.category`가 `미분류`로 저장된 항목이 여기에 모인다. - 회원 썸네일은 `public/uploads/members/avatars/YYYY/MM/`에 WebP로 저장되며, 저장 파일명은 원본명 기반(Unicode 문자·숫자와 `._-`만 유지, 동일 폴더 충돌 시 `-2` 넘버링)이다. 업로드 시 `media_metadata.category`는 논리 폴더 **`썸네일`**로 저장한다. `썸네일`은 예약 폴더로 `media_folders`에 수동 생성·삭제할 수 없다. - 사이트 로고·파비콘·홈 커버는 `public/uploads/system/`에 저장되며, 업로드 시 `media_metadata.category`는 논리 폴더 **`시스템`**으로 저장한다. 현재 사이트 설정의 `logo_url`, `favicon_url`, `home_cover_image_url`, `home_cover_dark_image_url`이 가리키는 파일은 사용 중인 미디어로 표시하고 파일명 변경·삭제를 차단한다. - 레거시 메타 값 `posts`, `회원/썸네일`은 마이그레이션 `016_media_category_normalize.sql` 및 서버 정규화로 각각 `미분류`, `썸네일`에 맞춘다. - 관리자 미디어 업로드 API는 이미지·비디오·오디오·문서 확장자를 허용한다(에디터 슬래시·미디어 모달과 동일 목록). - 업로드 파일 크기 제한은 종류별 환경 변수를 따른다. 이미지·아바타·로고 등은 `MAX_FILE_SIZE`(기본 10MB), 비디오는 `MAX_VIDEO_FILE_SIZE`(기본 200MB), 오디오는 `MAX_AUDIO_FILE_SIZE`(기본 50MB), 문서·ZIP 등은 `MAX_DOCUMENT_FILE_SIZE`(기본 50MB). 관리자 게시물·페이지용 미디어 업로드의 1회 파일 수와 전체 용량은 사이트 설정 POST 설정의 업로드 제한을 따른다. - 로컬 개발 업로드 파일은 `public/uploads/posts/YYYY/MM/` 아래 저장하고 `/uploads/posts/YYYY/MM/filename` URL로 제공한다. - 관리자 미디어 화면 상단에 **미디어 라이브러리**·**대표 이미지**·**본문 이미지**·**프로필 이미지** 탭을 두어, 라이브러리 탭에서는 원본 업로드 파일만, 대표 이미지 탭에서는 `/posts/YYYY/MM/thumbs/*-card.webp`와 `*-page-cover.webp` 파일만, 본문 이미지 탭에서는 `/posts/YYYY/MM/thumbs/*-body-1600.webp`, `*-body-720.webp`, `*-body-2560.webp` 파일과 레거시 `*-body.webp`, `*-lightbox.webp` 파일만, 프로필 이미지 탭에서는 `/members/avatars/` 파일만 검색·탐색한다. 본문 이미지 탭의 상세 정보는 1600px, 720px, 2560px 용도를 구분해 표시한다. 라이브러리 탭의 파일 종류 필터는 `전체/이미지/영상/음악/파일`을 표시하고 사용 상태 필터는 중복 `전체` 배지를 피하기 위해 `미사용` 토글만 표시한다. 시스템 파생 탭에서는 전체/미사용 배지형 필터를 표시하고, 목록 카드 오른쪽 위에는 실제 사용 개수 숫자 배지를 표시한다. 대표 이미지 탭과 본문 이미지 탭에서는 모든 항목이 해당 파생 파일이므로 각각 `카드`, `본문` 역할 배지는 표시하지 않으며, 탭 전환 중 이전 응답 항목이 잠깐 남아도 파생 파일 URL 기준으로 역할 배지를 숨긴다. 미디어 그리드는 서버 페이지 응답 기준 50·100·200개 단위 페이지네이션을 사용하며, 페이지당 표시 개수 셀렉트는 다른 관리자 셀렉트와 같은 SVG chevron 화살표를 사용한다. 원본 이미지 항목도 가능한 경우 720px 본문 파생 이미지 또는 카드·Pages 커버 썸네일을 우선 표시하고 실패 시 원본으로 되돌린다. 파생 이미지 목록·상세 미리보기는 파일 수정 시각과 용량을 캐시 버전으로 붙여 재생성 직후에도 새 파일을 확인할 수 있게 한다. - 미디어 라이브러리 탭은 왼쪽 폴더 트리와 오른쪽 고밀도 썸네일 갤러리, 검색, 파일명 변경, 개별 삭제를 제공한다. - 관리자는 폴더 추가 버튼으로 모달에서 새 폴더·하위 폴더 이름을 입력해 만들 수 있으며, `미분류`·`썸네일`(및 그 하위)을 제외한 폴더는 목록에서 삭제할 수 있다. 폴더 삭제 시 해당 경로 및 하위 경로로 분류돼 있던 미디어 메타는 모두 `미분류`로 되돌린다. - 썸네일 본문(이미지·파일명) 한 번 클릭 시 상세(미리보기) 모달이 열리고, 썸네일 좌측 상단 **선택 토글**로 개별 선택한다. Shift+클릭으로 현재 페이지 안의 범위 선택이 가능하다. 현재 페이지 선택은 화면에 보이는 항목 중 사용 중이 아니어서 삭제 가능한 항목만 대상으로 한다. - 미디어 라이브러리 탭에서만 선택한 미디어를 폴더로 드래그하면 해당 미디어들의 폴더 경로가 일괄 변경된다. - 관리자 미디어 화면 검색은 **저장 파일명**과 게시물·페이지 **사용처 제목**만 대상으로 한다(URL 경로·논리 폴더명 문자열은 검색에 쓰지 않는다). - 미디어 파일 경로, 사용 현황(라이브러리), 연결 회원(프로필 이미지 탭), 용량 등 세부 정보는 상세 모달에서 표시한다. - API 실패·클라이언트 검증 실패 등 사용자 피드백은 본문 상단 고정 배너가 아니라 `useAdminToast` 우측 상단 토스트로 표시해 모달에 가리지 않는다. - 상세 모달의 **다운로드**는 공개 `/uploads/...` URL을 `download` 속성으로 브라우저에 내려받는다(썸네일·게시물 이미지 공통). - 미디어 폴더는 실제 파일 경로를 옮기지 않고 `media_metadata` 테이블에 URL별 경로 메타데이터로 저장한다. - 글쓰기 미디어 선택 창은 업로드 미디어 목록에서 이미지를 선택해 단일 이미지 또는 갤러리에 삽입한다. - 미디어 사용 현황은 게시물/페이지의 대표 이미지·본문 내 URL과 사이트 설정의 로고·파비콘·홈 커버 URL을 기준으로 표시한다. - 사용 중인 미디어는 저장된 콘텐츠 URL이 깨지지 않도록 파일명 변경과 삭제를 차단한다. - 회원 프로필 썸네일 파일은 `users.avatar_url`이 해당 URL을 가리킬 때만 관리자 화면에서 파일명 변경·삭제를 차단한다. 프로필에서 교체·해제된 파일은 디스크에 남으며 프로필 이미지 탭에서 정리할 수 있다. --- ## 환경 변수 (.env) ### 공통 키 ```env # Database DATABASE_URL=postgres://sori_studio:replace-with-random-password@sori-studio-db:5432/sori_studio DATABASE_NAME=sori_studio POSTGRES_DB=sori_studio POSTGRES_USER=sori_studio POSTGRES_PASSWORD=replace-with-random-password DB_PORT=43081 # Auth ADMIN_EMAIL=admin@example.com ADMIN_PASSWORD=replace-with-random-password MEMBER_SESSION_SECRET=replace-with-random-password ANALYTICS_HASH_SECRET=replace-with-random-password ANALYTICS_COLLECTED_SINCE=2026-06-01 # Upload UPLOAD_DIR=/uploads MAX_FILE_SIZE=10485760 MAX_VIDEO_FILE_SIZE=209715200 MAX_AUDIO_FILE_SIZE=52428800 MAX_DOCUMENT_FILE_SIZE=52428800 MAX_VIDEO_FILE_SIZE=209715200 MAX_AUDIO_FILE_SIZE=52428800 MAX_DOCUMENT_FILE_SIZE=52428800 AVATAR_MIN_WIDTH=96 AVATAR_MIN_HEIGHT=96 AVATAR_MAX_WIDTH=512 AVATAR_MAX_HEIGHT=512 AVATAR_WEBP_QUALITY=82 # Site NUXT_PUBLIC_SITE_URL=https://sori.studio NUXT_PUBLIC_SITE_TITLE=sori.studio # Server APP_PORT=43080 ``` ### 환경 파일 기준 | 파일 | 용도 | DB | |------|------|----| | `.env.development` | 로컬 개발, Git 제외 | 개발 DB | | `.env.production` | NAS 운영, Git 제외 | 운영 DB | | `.env.example` | 공유 예시, Git 포함 | 실제 접속 정보 없음 | - `.env.example`에는 실제 이메일, 비밀번호, 토큰, 운영 서버 주소를 기록하지 않음 - `.env.development`와 `.env.production`의 DB 비밀번호와 관리자 비밀번호는 서로 다른 랜덤 값을 사용 - 로컬 개발 `DATABASE_URL`은 호스트 기준 `127.0.0.1:43081`을 사용 - NAS Docker 내부 `DATABASE_URL`은 서비스명 기준 `sori-studio-db:5432`를 사용 - 로컬 DB 확인은 PostgreSQL 클라이언트에서 `127.0.0.1:43081`로 접속하거나 `docker exec sori-studio-db psql` 명령으로 확인한다. ### 포트 기준 | 용도 | 포트 | |------|------| | 로컬 개발 서버 | 43080 | | NAS Docker 외부 포트 | 43080 | | 컨테이너 내부 포트 | 3000 | | PostgreSQL 외부 포트 | 43081 | --- ## 버전 관리 - 현재 버전: v0.0.85 - 첫 커밋 이후 변경사항을 커밋할 때마다 패치 버전 증가 - 메이저/마이너 버전은 구조 변경 또는 기능 묶음 단위로 결정