234 lines
6.3 KiB
Markdown
234 lines
6.3 KiB
Markdown
# sori.studio 기술 명세
|
|
|
|
## 프로젝트 개요
|
|
|
|
- **프로젝트명**: sori.studio
|
|
- **유형**: 커스텀 블로그/CMS
|
|
- **목표**: 개인 블로그 중심 운영, 기존 포털성 링크와 서비스 진입점은 블로그 내부 구조에 통합
|
|
- **참조**: Ghost(관리자 UX/글쓰기), Thred 테마(사용자 화면)
|
|
- **현재 상태**: Nuxt 3 초기 스캐폴딩 완료
|
|
- **원격 저장소**: 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는 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)
|
|
|
|
### 공통 키
|
|
|
|
```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.2
|
|
- 첫 커밋 이후 변경사항을 커밋할 때마다 패치 버전 증가
|
|
- 메이저/마이너 버전은 구조 변경 또는 기능 묶음 단위로 결정
|