sori.studio/docs/spec.md

sori.studio 기술 명세

프로젝트 개요

• 프로젝트명: sori.studio
• 유형: 커스텀 블로그/CMS
• 목표: 개인 블로그 중심 운영, 기존 포털성 링크와 서비스 진입점은 블로그 내부 구조에 통합
• 참조: Ghost(관리자 UX/글쓰기), Thred 테마(사용자 화면)
• 현재 상태: Nuxt 3 초기 스캐폴딩 완료
• 원격 저장소: https://git.sori.studio/zenn/sori.studio.git

---

화면 구조

메인 화면 (3단 레이아웃)

요소	크기/속성
Header	높이 57px
Left Aside	너비 287px, 최소 높이 calc(100vh - 57px), 패딩 12px 12px 12px 0
Main	너비 720px, 패딩 32px 24px (헤더), 16px 24px (섹션)
Right Aside	너비 287px, 최소 높이 calc(100vh - 57px), 패딩 20px 0 20px 20px

메뉴 토글

• 헤더 좌측 아이콘은 브랜드 마크가 아니라 왼쪽 사이드바 열기/닫기 버튼
• 메뉴 상태는 Nuxt/Vue 상태로 관리
• 브라우저에서는 localStorage.MENU_STATE에 open 또는 closed 저장
• 닫힘 상태에서는 왼쪽 사이드바를 숨기고 중앙/오른쪽 컬럼만 표시

공개 화면 색상

• 라이트/다크 모드는 CSS 변수로 관리
• 기본 배경, 패널, 라인, 텍스트, 보조 텍스트, 입력, 강조 버튼 색상을 분리
• 시스템 다크 모드는 prefers-color-scheme: dark 기준으로 우선 대응
• Thred 참고 화면처럼 사이드바와 본문은 같은 화면 안에서 구분되는 패널과 라인으로 표현

Post 페이지

• Main 좌우 패딩: 24px → 20px
• 공개 게시물 본문은 콘텐츠 타입별 컴포넌트로 분리해 추후 스타일 변경이 쉽도록 구성

Page 페이지

• About, Projects, Links, Contact, 서비스 소개 페이지 등 고정 콘텐츠에 사용
• 기본 게시물 목록에는 노출하지 않음
• 헤더와 사이드바를 사용하지 않고 본문 중심 전체 화면으로 표시
• 진입 경로는 추후 메뉴/링크 설정을 통해 연결

레이아웃 파일

layouts/
├── default.vue    # 메인/목록 화면
├── post.vue       # 게시물 화면
└── admin.vue      # 관리자 화면

---

컴포넌트 구조

사이트 컴포넌트

components/site/
├── SiteHeader.vue    # 상단 헤더
├── 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 카드
├── ProseHeaderCard.vue # Header 카드 (Simple/Wide/Full-width/Split)
└── ProseEmbed.vue      # Embeds (YouTube, Twitter)

---

데이터베이스 구조

환경 분리 원칙

• 로컬 개발 환경과 NAS 운영 환경은 서로 다른 DB를 사용
• 로컬 개발 서버는 개발 DB만 연결
• NAS 배포 환경은 운영 DB만 연결
• 운영 DB 접속 정보는 로컬 기본 .env에 기록하지 않음
• DB 관리 도구는 CloudBeaver 등을 사용할 수 있도록 접속 정보를 환경별로 분리

Posts (블로그 글)

필드	타입	설명
id	UUID	Primary Key
title	String	제목
slug	String	URL 슬러그
content	Text	마크다운 콘텐츠
excerpt	String	요약
featured_image	String	대표 이미지
status	Enum	published/draft/private
published_at	DateTime	발행일
created_at	DateTime	생성일
updated_at	DateTime	수정일

Pages (고정 페이지)

필드	타입	설명
id	UUID	Primary Key
title	String	제목
slug	String	URL 슬러그
content	Text	마크다운 콘텐츠
featured_image	String	대표 이미지
created_at	DateTime	생성일
updated_at	DateTime	수정일

Tags

필드	타입	설명
id	UUID	Primary Key
name	String	태그명
slug	String	URL 슬러그
description	String	설명

PostTags (다대다)

필드	타입	설명
post_id	UUID	FK → Posts
tag_id	UUID	FK → Tags

---

API 구조

현재 API는 Nuxt server/api 내부에 샘플 데이터 기반으로 구현되어 있다. DB 연결 후 같은 응답 구조를 유지하되 저장소만 교체한다.

백엔드 구성

• 별도 backend/ 앱을 두지 않고 Nuxt/Nitro 서버 기능을 사용
• 공개 API는 server/api에 작성
• 서버 공통 스키마와 샘플 데이터는 server/utils에 작성
• 초기 단계에서는 같은 앱 배포로 관리 비용을 낮춤
• 독립 API 서버가 필요해지는 시점에만 백엔드 분리를 재검토

공개 API (/api/)

• GET /api/posts - 게시물 목록
• GET /api/posts/:slug - 게시물 상세
• GET /api/pages - 고정 페이지 목록
• GET /api/pages/:slug - 고정 페이지 상세
• GET /api/tags - 태그 목록

관리자 API (/admin/api/)

• POST /admin/api/auth/login - 로그인
• GET /admin/api/posts - 글 목록
• POST /admin/api/posts - 글 작성
• PUT /admin/api/posts/:id - 글 수정
• DELETE /admin/api/posts/:id - 글 삭제
• POST /admin/api/posts/:id/publish - 글 발행
• GET /admin/api/tags - 태그 목록
• POST /admin/api/tags - 태그 생성
• DELETE /admin/api/tags/:id - 태그 삭제

---

미디어 관리

업로드 경로 규칙

/uploads/posts/YYYY/MM/filename.webp
/uploads/pages/YYYY/MM/filename.webp
/uploads/system/logo.png
/uploads/system/favicon.png

---

환경 변수 (.env)

공통 키

# Database
DATABASE_URL=
DATABASE_NAME=

# Auth
ADMIN_EMAIL=
ADMIN_PASSWORD=

# Upload
UPLOAD_DIR=/uploads
MAX_FILE_SIZE=10485760

# Site
NUXT_PUBLIC_SITE_URL=https://sori.studio
NUXT_PUBLIC_SITE_TITLE=sori.studio

# Server
APP_PORT=43118

환경 파일 기준

파일	용도	DB
.env.development	로컬 개발	개발 DB
.env.production	NAS 운영	운영 DB
.env.example	공유 예시	실제 접속 정보 없음

포트 기준

용도	포트
로컬 개발 서버	43117
NAS Docker 외부 포트	43118
컨테이너 내부 포트	3000

---

버전 관리

• 현재 버전: v0.0.4
• 첫 커밋 이후 변경사항을 커밋할 때마다 패치 버전 증가
• 메이저/마이너 버전은 구조 변경 또는 기능 묶음 단위로 결정