zenn/sori.studio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

초기 문서 기준점 정리

Browse Source
This commit is contained in:
zenn
2026-04-29 14:28:57 +09:00
commit efc7955415
10 changed files with 828 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/changelog.md Normal file
View File

@@ -0,0 +1,12 @@
# 업데이트 요약
## v0.0.1
- sori.studio 개인 블로그/CMS 초기 방향 정리.
- Ghost 스타일 관리자와 Thred 스타일 공개 화면을 기준 참조로 확정.
- Nuxt SSR, JavaScript, JSDoc, Zod, Tailwind CSS 기반 개발 원칙 정리.
- Git 원격 저장소와 작성자 정보를 프로젝트 기준으로 명시.
- 로컬 개발 DB와 NAS 운영 DB를 분리하는 원칙 추가.
- NAS 배포 시 운영 환경 변수와 운영 DB를 사용하도록 배포 기준 보강.
공개 플랫폼에 공유할 주요 변경사항은 사용자가 요청한 시점에 별도 문장으로 정리한다.

52
docs/convention.md Normal file
View File

@@ -0,0 +1,52 @@
# 코딩 컨벤션
## 언어
- JavaScript (TypeScript 미사용)
- JSDoc으로 타입 명시
- Zod로 스키마 검증
## 문법
- 세미콜론 미사용
- const/let 사용 (var 미사용)
- 화살표 함수 우선
## 네이밍
- Vue 컴포넌트: PascalCase (SiteHeader.vue)
- 일반 파일/폴더: kebab-case
- Vue 컴포넌트 파일: PascalCase
- CSS 클래스: kebab-case
- 고유 클래스명 필수 (Tailwind 외)
## 스타일
- TailwindCSS 기본 사용
- 주요 요소: Tailwind + 고유 className 동시 적용
```html
<main class="site-main w-[720px]">
```
## 주석
- JSDoc 형식
- 한국어 작성
```javascript
/**
* 게시물 목록 조회
* @param {Object} options - 조회 옵션
* @param {number} options.page - 페이지 번호
* @param {number} options.limit - 페이지당 개수
* @returns {Promise<Post[]>} 게시물 목록
*/
```
## 설정
- 경로/URL/키값: .env로 관리
- 하드코딩 금지
- 로컬 개발 설정과 NAS 운영 설정은 별도 환경 파일로 분리
- 운영 DB 접속 정보는 개발용 `.env`에 기록하지 않음

110
docs/deploy.md Normal file
View File

@@ -0,0 +1,110 @@
# 배포 가이드
> 현재 프로젝트는 코드 스캐폴딩 전 상태다. 아래 내용은 Nuxt 앱 생성 후 적용할 기본 배포 방향이다.
## 빌드 유형
| 유형 | 명령어 | 용도 |
|------|--------|------|
| 개발 | `npm run dev` | 로컬 테스트, 개발 서버 |
| 프로덕션 | `npm run build` | NAS 배포, 운영 서버 |
---
## 로컬 개발
### 필수 조건
- Node.js 20+ 권장
- npm 9+
- 개발 DB
### 실행 단계
```bash
# 프로젝트 클론
git clone https://git.sori.studio/zenn/sori.studio.git
# 디렉토리 이동
cd sori.studio
# 의존성 설치
npm install
# 개발 환경 변수 설정
cp .env.example .env.development
# .env.development 파일에 개발 DB 연결 정보 입력
# 개발 서버 실행
npm run dev
```
### 확인 주소
- 개발 서버: http://localhost:3000
- 관리자: http://localhost:3000/admin
---
## UGREEN NAS Docker 배포
> Dockerfile과 docker-compose 설정은 아직 작성 전이다.
### SSH 접속
```bash
ssh [NAS_IP]
```
### 프로젝트 설치
```bash
# 프로젝트 디렉토리로 이동
cd /volume1/docker/sori.studio
# 프로젝트 클론
git clone https://git.sori.studio/zenn/sori.studio.git
# 디렉토리 이동
cd sori.studio
# 운영 환경 변수 설정
cp .env.example .env.production
# .env.production 파일에 운영 DB 연결 정보 입력
# Docker 빌드 및 실행
docker-compose up -d
```
### 프로덕션 빌드 (NAS에서)
```bash
# 프로덕션 빌드
npm run build
# 또는 Docker로 빌드
docker build -t sori.studio:latest .
docker run -d -p 3000:3000 sori.studio:latest
```
### 포트
- HTTP: 3000
- HTTPS: 3001 (SSL 설정 시)
---
## 데이터베이스
- 로컬 개발: `.env.development`의 `DATABASE_URL`
- NAS 운영: `.env.production`의 `DATABASE_URL`
- 개발 DB와 운영 DB는 반드시 별도 인스턴스 또는 별도 데이터베이스로 분리
- 운영 DB는 로컬 개발 서버에서 직접 연결하지 않음
- 관리 도구: CloudBeaver 등으로 추후 연결 가능하게 설계
## 사용자 액션 필요 항목
- NAS SSH 접속 주소 확인.
- NAS 프로젝트 루트 경로 확정.
- 운영 DB 이름, 계정, 권한 확정.
- 도메인 `sori.studio`의 NAS 연결 방식 확정.

21
docs/history.md Normal file
View File

@@ -0,0 +1,21 @@
# 의사결정 이력
## 2026-04-29 v0.0.1
### 초기 제품 방향 결정
sori.studio는 개인 블로그를 중심으로 운영하되, 기존 포털 역할은 블로그 내부 링크와 고정 페이지로 흡수한다. 글이 계속 쌓이는 공간이 핵심이므로 공개 화면은 읽기 경험과 콘텐츠 확장성을 우선한다.
관리자 화면은 Ghost의 검증된 글쓰기 흐름과 마크다운 기반 위지윅 방식을 기준으로 삼는다. 개인용 프로젝트라서 관리자 기능은 과도한 추상화보다 단순한 유지보수성을 우선한다.
공개 화면은 Thred 테마의 3단 레이아웃과 콘텐츠 카드 스타일을 참고한다. 헤더, 좌우 사이드바, 중앙 본문 폭을 먼저 고정해 전체 화면 구조를 빠르게 파악할 수 있게 한다.
기술 스택은 Nuxt SSR, JavaScript, JSDoc, Zod, Tailwind CSS를 기본값으로 결정했다. SEO가 필요한 공개 페이지는 서버 렌더링을 우선하고, TypeScript는 초기 복잡도를 낮추기 위해 사용하지 않는다.
Posts와 Pages는 분리한다. Posts는 목록과 태그에 노출되는 블로그 글이고, Pages는 고정 페이지와 포털성 링크 정리에 사용한다.
로컬 개발 환경과 NAS 운영 환경은 서로 다른 데이터베이스를 사용한다. 개인 블로그라도 운영 데이터가 글과 미디어의 원본이 되므로, 로컬 개발 과정에서 운영 DB를 직접 연결하지 않는 것을 기본 원칙으로 정했다.
원격 저장소는 `https://git.sori.studio/zenn/sori.studio.git`을 사용한다. Git 작성자 정보는 `zenn <zenn.message@gmail.com>`으로 통일해 이후 커밋 이력을 한 계정 기준으로 유지한다.
`note.md`는 원본 의도 반영이 끝난 뒤 삭제한다. 이후 프로젝트 기준 문서는 `AGENTS.md`와 `docs/` 아래 문서만 사용한다.

63
docs/map.md Normal file
View File

@@ -0,0 +1,63 @@
# 파일-화면 매핑
> 현재 문서는 구현 예정 파일 기준 매핑이다. 실제 파일이 생성되면 경로와 화면 연결을 즉시 갱신한다.
## 레이아웃
| 파일 | 화면 |
|------|------|
| layouts/default.vue | 메인, 목록, 태그 페이지 |
| layouts/post.vue | 개별 게시물 |
| layouts/admin.vue | 관리자 전체 |
| layouts/page.vue | 고정 페이지 전체 화면 |
## 사이트 컴포넌트
| 파일 | 화면 위치 |
|------|-----------|
| components/site/SiteHeader.vue | 모든 공개 페이지 상단 |
| components/site/LeftSidebar.vue | 메인 화면 왼쪽 |
| components/site/RightSidebar.vue | 메인 화면 오른쪽 |
| components/site/MainColumn.vue | 메인 화면 중앙 |
| components/site/PostCard.vue | 목록의 게시물 카드 |
| components/site/TagHeader.vue | 태그 페이지 헤더 |
## 콘텐츠 컴포넌트
| 파일 | 화면 위치 |
|------|-----------|
| components/content/ContentRenderer.vue | 게시물/페이지 본문 |
| components/content/ProseHeading.vue | h1~h6 제목 |
| components/content/ProseImage.vue | 본문 내 이미지 |
| components/content/ProseList.vue | 목록 |
| components/content/ProseBlockquote.vue | 인용구 |
| components/content/ProseButton.vue | 버튼 |
| components/content/ProseCallout.vue | Callout 카드 |
| components/content/ProseToggle.vue | Toggle 카드 |
| components/content/ProseVideo.vue | 비디오 |
| components/content/ProseAudio.vue | 오디오 |
| components/content/ProseFile.vue | 파일 |
| components/content/ProseProduct.vue | 상품 카드 |
| components/content/ProseHeaderCard.vue | 헤더 카드 |
| components/content/ProseEmbed.vue | YouTube, Twitter 임베드 |
## 관리자 페이지
| 파일 | 화면 |
|------|------|
| pages/admin/index.vue | 대시보드 |
| pages/admin/posts/index.vue | 글 목록 |
| pages/admin/posts/new.vue | 글 작성 |
| pages/admin/posts/[id].vue | 글 수정 |
| pages/admin/pages/index.vue | 페이지 목록 |
| pages/admin/tags/index.vue | 태그 관리 |
| pages/admin/settings/index.vue | 사이트 설정 |
## 공개 페이지
| 파일 | 화면 |
|------|------|
| pages/index.vue | 홈 |
| pages/posts/[slug].vue | 블로그 글 상세 |
| pages/tags/[slug].vue | 태그별 글 목록 |
| pages/pages/[slug].vue | 고정 페이지 상세 |

214
docs/spec.md Normal file
View File

@@ -0,0 +1,214 @@
# 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)
### 공통 키
```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
- 첫 커밋 이후 변경사항을 커밋할 때마다 패치 버전 증가
- 메이저/마이너 버전은 구조 변경 또는 기능 묶음 단위로 결정

69
docs/todo.md Normal file
View File

@@ -0,0 +1,69 @@
# sori.studio 할 일
## 1차 관리자 개발
- [ ] 로그인 기능 구현
- [ ] 글 목록 조회
- [ ] 글 작성/수정 (마크다운 에디터)
- [ ] 글 발행/비공개 전환
- [ ] 태그 관리 (생성/수정/삭제)
- [ ] 이미지 업로드
## 2차 관리자 개발
- [ ] 페이지 관리 (CRUD)
- [ ] 사이트 설정
- [ ] 메뉴/네비게이션 관리
- [ ] 미디어 라이브러리
## 3차 관리자 개발
- [ ] 예약 발행
- [ ] 초안 자동 저장
- [ ] SEO 설정
- [ ] OG 이미지 설정
- [ ] 글 미리보기
## 프론트엔드 개발
- [ ] SiteHeader.vue 구현 (57px 높이)
- [ ] LeftSidebar.vue 구현 (287px, 패딩 12px 12px 12px 0)
- [ ] RightSidebar.vue 구현 (287px, 패딩 20px 0 20px 20px)
- [ ] MainColumn.vue 구현 (720px)
- [ ] PostCard.vue 구현
- [ ] TagHeader.vue 구현
## 콘텐츠 스타일 구현
- [ ] ProseHeading (h1~h6)
- [ ] ProseList (Ordered/Unordered)
- [ ] ProseBlockquote
- [ ] ProseImage (Regular/Wide/Full-width)
- [ ] ProseButton (Left-aligned/Centered)
- [ ] ProseCallout
- [ ] ProseToggle
- [ ] ProseVideo
- [ ] ProseAudio
- [ ] ProseFile
- [ ] ProseProduct
- [ ] ProseHeaderCard (Simple/Wide/Full-width/Split)
- [ ] ProseEmbed (YouTube, Twitter)
## 데이터베이스
- [ ] Posts 테이블 설계
- [ ] Pages 테이블 설계
- [ ] Tags 테이블 설계
- [ ] PostTags 테이블 설계
- [ ] 로컬 개발 DB 연결 설정 작성
- [ ] NAS 운영 DB 연결 설정 작성
- [ ] 개발 DB와 운영 DB 분리 검증 절차 작성
- [ ] CloudBeaver 등 DB 관리 도구 연결 방식 결정
## 배포
- [ ] UGREEN NAS Docker 배포 가이드 작성
- [ ] 로컬 개발 환경 가이드 작성
- [ ] Dockerfile 작성
- [ ] docker-compose.yml 작성
- [ ] .env.example 작성

16
docs/update.md Normal file
View File

@@ -0,0 +1,16 @@
# 업데이트 이력
## v0.0.1
- sori.studio 개인 블로그/CMS 방향 정리.
- note.md 원본 기획 기준 문서 재점검.
- Ghost 스타일 관리자와 Thred 스타일 공개 화면 기준 명세 정리.
- Nuxt SSR, JavaScript, JSDoc, Zod, Tailwind CSS 기본 전제 정리.
- Git 원격 저장소와 작성자 기준 문서화.
- 로컬 개발 DB와 NAS 운영 DB 분리 원칙 추가.
- 공개 레이아웃, 콘텐츠 컴포넌트, 관리자 화면 계획 정리.
- pages 전체 화면 표시 기준 정리.
- 배포 가이드에 clone, 개발/운영 환경 변수, NAS 운영 DB 기준 추가.
- 초기 할 일, 배포 초안, 파일-화면 매핑 문서 정리.
- note.md 삭제 정리.
- Git 저장소 초기 기준점 설정 진행.