sori.studio/docs/spec.md

sori.studio 기술 명세

프로젝트 개요

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

---

화면 구조

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

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

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 (/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
SITE_URL=https://sori.studio
SITE_TITLE=sori.studio

환경 파일 기준

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

---

버전 관리

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