zenn/sori.studio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dd0a643d7320dd2bf3008d1296379a4d0c968d71
sori.studio/docs/spec.md

412 lines
17 KiB
Markdown
Raw Blame History

# sori.studio 기술 명세
## 프로젝트 개요
- **프로젝트명**: sori.studio
- **유형**: 커스텀 블로그/CMS
- **목표**: 개인 블로그 중심 운영, 기존 포털성 링크와 서비스 진입점은 블로그 내부 구조에 통합
- **참조**: Ghost(관리자 UX/글쓰기), Thred 테마(사용자 화면)
- **현재 상태**: Nuxt 3 초기 스캐폴딩과 PostgreSQL 저장소 계층 구성 완료
- **원격 저장소**: 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, 서비스 소개 페이지 등 고정 콘텐츠에 사용
- 기본 게시물 목록에는 노출하지 않음
- 헤더와 사이드바를 사용하지 않고 본문 중심 전체 화면으로 표시
- 진입 경로는 추후 메뉴/링크 설정을 통해 연결
### 공개 URL 구조
- `/posts` - 게시물 전체 목록
- `/post/:slug` - 개별 게시물 상세
- `/tags` - 태그 전체 목록
- `/tag/:slug` - 태그별 게시물 목록
- 기존 `/posts/:slug`, `/tags/:slug` 상세 경로는 새 단수형 상세 경로로 리다이렉트한다.
### 레이아웃 파일
```
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)
```
---
## 데이터베이스 구조
### 환경 분리 원칙
- 데이터베이스는 PostgreSQL을 기준으로 한다.
- 로컬 개발 환경과 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 nullable | 대표 이미지 |
| 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 nullable | 대표 이미지 |
| created_at | DateTime | 생성일 |
| updated_at | DateTime | 수정일 |
### Tags
| 필드 | 타입 | 설명 |
|------|------|------|
| id | UUID | Primary Key |
| name | String | 태그명 |
| slug | String | URL 슬러그 |
| description | String | 설명 |
| sort_order | Integer | 사용자 화면 표시 순서 |
| color | String | 태그 색상 코드 |
| created_at | DateTime | 생성일 |
| updated_at | DateTime | 수정일 |
### SiteSettings
| 필드 | 타입 | 설명 |
|------|------|------|
| id | Integer | 단일 설정 레코드 ID, 항상 1 |
| title | String | 사이트 이름 |
| description | String | 사이트 설명 |
| site_url | String | 사이트 기본 URL |
| logo_text | String | 텍스트 로고 |
| copyright_text | String | 저작권 문구 |
| updated_at | DateTime | 수정일 |
### NavigationItems
| 필드 | 타입 | 설명 |
|------|------|------|
| id | UUID | Primary Key |
| label | String | 메뉴 표시 이름 |
| url | String | 내부 경로 또는 외부 URL |
| location | Enum | primary/footer |
| sort_order | Integer | 표시 순서 |
| is_visible | Boolean | 공개 화면 표시 여부 |
| created_at | DateTime | 생성일 |
| updated_at | DateTime | 수정일 |
### MediaMetadata
| 필드 | 타입 | 설명 |
|------|------|------|
| url | String | 업로드 미디어 URL |
| category | String | 관리자 분류명 |
| created_at | DateTime | 생성일 |
| updated_at | DateTime | 수정일 |
### PostTags (다대다)
| 필드 | 타입 | 설명 |
|------|------|------|
| post_id | UUID | FK → Posts |
| tag_id | UUID | FK → Tags |
| created_at | DateTime | 생성일 |
---
## 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` - 게시물 목록
- `GET /api/posts/:slug` - 게시물 상세
- `GET /api/pages` - 고정 페이지 목록
- `GET /api/pages/:slug` - 고정 페이지 상세
- `GET /api/tags` - 태그 목록
- `GET /api/site-settings` - 공개 사이트 설정
- `GET /api/navigation` - 공개 네비게이션
### 관리자 API (`/admin/api/`)
- `POST /admin/api/auth/login` - 로그인
- `POST /admin/api/auth/logout` - 로그아웃
- `GET /admin/api/auth/me` - 현재 관리자 세션 조회
- `GET /admin/api/posts` - 글 목록
- `POST /admin/api/posts` - 글 작성
- `GET /admin/api/posts/:id` - 글 상세
- `PUT /admin/api/posts/:id` - 글 수정
- `DELETE /admin/api/posts/:id` - 글 삭제
- `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/media` - 업로드 미디어 목록
- `PUT /admin/api/media` - 업로드 미디어 파일명 변경
- `DELETE /admin/api/media` - 업로드 미디어 삭제
- `POST /admin/api/uploads` - 관리자 이미지 업로드
- `GET /admin/api/tags` - 태그 목록
- `POST /admin/api/tags` - 태그 생성
- `GET /admin/api/tags/:id` - 태그 상세
- `PUT /admin/api/tags/:id` - 태그 수정
- `DELETE /admin/api/tags/:id` - 태그 삭제
- `GET /admin/api/settings` - 사이트 설정 조회
- `PUT /admin/api/settings` - 사이트 설정 수정
- `GET /admin/api/navigation` - 네비게이션 항목 목록
- `PUT /admin/api/navigation` - 네비게이션 항목 일괄 저장
> 글 발행/초안/비공개 전환은 현재 `PUT /admin/api/posts/:id`의 `status` 값으로 처리한다.
> 태그 삭제 시 `post_tags` 연결도 데이터베이스 외래 키 규칙에 따라 함께 삭제된다.
> 태그 목록은 `sort_order ASC, name ASC` 기준으로 정렬한다.
> 태그 `color`는 `#RRGGBB` 형식이며 사용자 화면 태그 색상 표시와 배지 배경색에 사용한다.
### 관리자 글 편집
- 글 작성/수정 화면은 Ghost 스타일을 참고한 블록형 에디터를 사용한다.
- 저장 데이터는 기존 `content` 필드의 마크다운 문자열을 유지한다.
- `/` 입력 시 블록 선택 메뉴를 표시한다.
- `/` 명령 메뉴는 화면 하단 공간이 부족하면 현재 블록 위쪽으로 표시한다.
- `/` 명령 메뉴가 열린 상태에서 Enter를 누르면 현재 강조된 메뉴 항목을 적용한다.
- `/` 명령 메뉴가 열린 상태에서 위/아래 방향키로 강조 항목을 이동한다.
- 블록 메뉴는 문단, 제목 2, 제목 3, 이미지, 갤러리, 콜아웃, 토글, 임베드, 인용, 목록, 코드, 구분선을 제공한다.
- `#`, `##`, `###`, `>`, `-` 입력 후 공백을 누르면 현재 블록 타입을 즉시 변환한다.
- 한글 등 조합형 입력 중에는 단축 문법과 슬래시 메뉴 상태를 확정하지 않고 조합 종료 뒤 반영한다.
- 한글 등 조합형 입력 직후 Enter는 새 블록 생성으로 처리하지 않는다.
- 빈 문단에서 Enter를 누르면 다음 빈 문단 블록을 생성한다.
- 빈 블록 placeholder는 현재 활성 블록 또는 첫 빈 블록에만 표시한다.
- 에디터 마지막에는 클릭 가능한 빈 문단 블록을 항상 유지하며, 해당 블록이 비어 있으면 저장 콘텐츠에는 포함하지 않는다.
- 제목은 별도 라벨 영역이 아니라 에디터 상단의 큰 제목 입력으로 표시한다.
- 제목 입력에서 Enter를 누르면 본문 첫 블록으로 포커스를 이동한다.
- 새 글 작성처럼 본문이 비어 있는 경우에도 빈 문단 블록을 먼저 생성한다.
- 글 작성/수정 중인 입력값은 브라우저 `localStorage`에 자동 저장한다.
- 자동 저장 키는 `SORI_ADMIN_POST_AUTOSAVE:new` 또는 `SORI_ADMIN_POST_AUTOSAVE:{postId}` 형식을 사용한다.
- 자동 저장본이 있으면 작성 화면에서 복원 또는 삭제를 선택할 수 있다.
- 글 저장 성공 시 해당 자동 저장본은 삭제한다.
- 글 저장/수정/삭제 진행과 성공/실패 상태는 화면 우측 상단 토스트로 표시한다.
- 관리자 글 에디터의 실제 입력 텍스트 색상은 placeholder보다 진하게 표시한다.
- 관리자 작성 화면과 공개 본문은 같은 마크다운 렌더링 기준을 사용한다.
- 대표 이미지는 URL 직접 입력이 아니라 미디어 선택 또는 새 이미지 업로드로 설정한다.
- 대표 이미지가 설정되면 관리자 글 폼에 썸네일과 삭제/변경 액션을 표시한다.
- 이미지 블록은 관리자 업로드 API로 이미지를 업로드하고 `![alt](url){width=wide}` 형식으로 저장한다.
- 이미지/갤러리 삽입 시 파일명은 alt 값으로 자동 입력하지 않는다.
- 이미지 블록 alt 입력은 이미지 hover 또는 focus 상태에서만 표시한다.
- 이미지 블록 표시 옵션은 `regular`, `wide`, `full` 값을 사용하며 `regular`는 width 옵션을 생략한다.
- 갤러리 블록은 `:::gallery` fenced block 안에 이미지 마크다운 행을 여러 개 저장한다.
- 공개 갤러리는 한 줄에 2~3개 이미지 그리드로 표시하고 클릭 시 라이트박스로 크게 확인한다.
- 이미지와 갤러리 블록은 기존 업로드 미디어 선택 또는 새 이미지 업로드를 제공한다.
- 콜아웃 블록은 `:::callout` fenced block 안에 본문을 저장한다.
- 토글 블록은 `:::toggle 제목` fenced block 안에 펼침 본문을 저장한다.
- 임베드 블록은 `:::embed` fenced block 안에 URL을 저장한다.
- YouTube 임베드 URL은 공개 화면에서 iframe으로 렌더링하고, 그 외 URL은 외부 링크로 표시한다.
### 관리자 페이지 편집
- 고정 페이지 작성/수정 화면은 게시물과 같은 블록형 에디터를 사용한다.
- 고정 페이지는 제목, 슬러그, 본문, 대표 이미지만 저장한다.
- 고정 페이지는 게시물 목록과 태그 목록에 노출하지 않는다.
- 고정 페이지 공개 보기 경로는 `/pages/:slug`를 사용한다.
### 사이트 설정
- 사이트 설정은 `site_settings` 테이블의 단일 레코드로 관리한다.
- 관리자는 사이트 이름, 설명, 사이트 URL, 텍스트 로고, 저작권 문구를 수정할 수 있다.
- 공개 헤더와 오른쪽 사이드바는 공개 사이트 설정 API 값을 사용한다.
- DB 연결이 없는 환경에서는 환경 변수와 기본값 기반 설정을 사용한다.
### 메뉴/네비게이션
- 네비게이션은 `navigation_items` 테이블로 관리한다.
- 관리자는 메뉴 라벨, URL, 위치, 순서, 표시 여부를 수정할 수 있다.
- 공개 왼쪽 사이드바의 상단 메뉴는 `primary` 위치 항목을 사용한다.
- 공개 왼쪽 사이드바 하단 메뉴는 `footer` 위치 항목을 사용한다.
- URL은 `/`로 시작하는 내부 경로 또는 `http://`, `https://` 외부 URL을 허용한다.
### 관리자 인증
- 초기 관리자 인증은 `ADMIN_EMAIL`, `ADMIN_PASSWORD` 환경 변수를 사용
- 로그인 성공 시 httpOnly 세션 쿠키를 `/admin` 경로에 설정
- 관리자 페이지 접근은 `/admin/api/auth/me` 확인 후 허용
- 세션 토큰은 `ADMIN_PASSWORD` 기반 HMAC 서명으로 검증
---
## 미디어 관리
### 업로드 경로 규칙
```
/uploads/posts/YYYY/MM/filename.webp
/uploads/pages/YYYY/MM/filename.webp
/uploads/system/logo.png
/uploads/system/favicon.png
```
- 관리자 이미지 업로드 API는 `image/jpeg`, `image/png`, `image/webp`, `image/gif`만 허용한다.
- 업로드 파일 크기 제한은 `MAX_FILE_SIZE` 환경 변수를 따른다.
- 로컬 개발 업로드 파일은 `public/uploads/posts/YYYY/MM/` 아래 저장하고 `/uploads/posts/YYYY/MM/filename` URL로 제공한다.
- 관리자 미디어 화면은 고밀도 썸네일 갤러리, 검색, 파일명 변경, 개별 삭제를 제공한다.
- 관리자 미디어 화면은 카테고리 필터와 미디어별 카테고리 수정을 제공한다.
- 미디어 파일 경로, 사용 현황, 용량 등 세부 정보는 썸네일 클릭 시 열리는 상세 모달에서 표시한다.
- 미디어 카테고리는 파일 경로를 옮기지 않고 `media_metadata` 테이블에 URL별로 저장한다.
- 글쓰기 미디어 선택 창은 업로드 미디어 목록에서 이미지를 선택해 단일 이미지 또는 갤러리에 삽입한다.
- 미디어 사용 현황은 게시물/페이지의 대표 이미지와 본문 내 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=43119
# Auth
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=replace-with-random-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` | 로컬 개발, Git 제외 | 개발 DB |
| `.env.production` | NAS 운영, Git 제외 | 운영 DB |
| `.env.example` | 공유 예시, Git 포함 | 실제 접속 정보 없음 |
- `.env.example`에는 실제 이메일, 비밀번호, 토큰, 운영 서버 주소를 기록하지 않음
- `.env.development`와 `.env.production`의 DB 비밀번호와 관리자 비밀번호는 서로 다른 랜덤 값을 사용
- 로컬 개발 `DATABASE_URL`은 호스트 기준 `127.0.0.1:43119`를 사용
- NAS Docker 내부 `DATABASE_URL`은 서비스명 기준 `sori-studio-db:5432`를 사용
### 포트 기준
| 용도 | 포트 |
|------|------|
| 로컬 개발 서버 | 43117 |
| NAS Docker 외부 포트 | 43118 |
| 컨테이너 내부 포트 | 3000 |
| PostgreSQL 외부 포트 | 43119 |
---
## 버전 관리
- 현재 버전: v0.0.13
- 첫 커밋 이후 변경사항을 커밋할 때마다 패치 버전 증가
- 메이저/마이너 버전은 구조 변경 또는 기능 묶음 단위로 결정
Reference in New Issue View Git Blame Copy Permalink