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

29
.gitignore vendored Normal file
View File

@@ -0,0 +1,29 @@
# Dependencies
node_modules/
# Build output
.output/
.nuxt/
dist/
# Environment
.env
.env.*
!.env.example
# IDE
.idea/
.vscode/
*.swp
*.swo
# OS
.DS_Store
Thumbs.db
# Logs
*.log
npm-debug.log*
# Test
coverage/

242
AGENTS.md Normal file
View File

@@ -0,0 +1,242 @@
# AGENTS.md
## 목적
이 파일은 이 프로젝트에서 작업하는 AI 에이전트(Codex 등)가 반드시 따라야 하는 공통 작업 규칙을 정의한다.
모든 작업은 본 문서의 지침을 우선 적용한다.
---
## 기본 응답 및 문서 원칙
- 모든 대화, 설명, 보고, 문서 작성은 반드시 한국어로 한다.
- 코드 내 주석은 반드시 JSDoc 형식으로 작성한다.
- 사용자가 별도 형식을 요구하지 않는 한, 답변은 짧고 명확하게 작성한다.
- AI가 사용자에게 보여주는 문서, 보고, 작업 요약에는 이모지를 가급적 사용하지 않는다.
- 추측성 답변을 하지 않는다. 불확실한 내용은 반드시 불확실하다고 명시한다.
- 작업 완료를 선언하기 전에 실제 수정 파일과 문서 반영 여부를 다시 확인한다.
---
## 프로젝트 기본 전제
- 기본 스타일링은 Tailwind CSS를 사용한다.
- 사이트 전역 기본 폰트는 반드시 `Pretendard`를 기준으로 유지한다.
- 사람이 구조를 빠르게 파악할 수 있도록 의미 있는 고유 클래스명을 반드시 함께 부여한다.
- Nuxt SSR 기반으로 SEO 대응한다.
- JavaScript + JSDoc + Zod를 사용한다 (TypeScript 미사용).
- 세미콜론은 사용하지 않는다.
- 로컬 개발 DB와 NAS 운영 DB는 반드시 분리한다.
- 운영 설정, 경로, URL, 키값은 반드시 환경 변수로 관리한다.
---
## 작업 수행 절차 (필수)
모든 작업은 아래 순서를 반드시 따른다.
1. docs/ 내 관련 문서를 먼저 읽는다.
2. 작업 대상과 관련된 실제 코드 파일을 확인한다.
3. 기존 구현 방식과 패턴을 파악한다.
4. 작업 범위를 최소화하여 수정한다.
5. 필요한 경우 검증을 수행한다.
6. 작업 완료 후 문서를 즉시 갱신한다.
7. 변경 누락이 없는지 다시 확인한 뒤 결과를 정리한다.
이 순서를 생략하거나 임의로 바꾸지 않는다.
---
## 문서 선참조 규칙
새로운 코드를 작성하거나 기존 코드를 수정하기 전, 반드시 아래 문서를 우선 참조한다.
- docs/update.md
- docs/todo.md
- docs/spec.md
- docs/convention.md
- docs/history.md
- docs/map.md
- docs/deploy.md
- docs/changelog.md
문서와 실제 코드가 충돌할 경우:
1. 실제 코드를 기준으로 현재 상태를 확인한다.
2. 필요한 수정을 진행한다.
3. 관련 문서를 최신 상태로 맞춘다.
---
## 문서 자동 관리 규칙
모든 작업 수행 후, AI는 관련 내용을 아래 문서에 즉시 반영해야 한다.
### 작업 이력
- 파일: docs/update.md
- 수행한 작업 내용을 짧고 간략한 항목형으로 기록한다.
- 서술형 문장 대신 `~추가.`, `~수정.`, `~정리.`, `~진행.` 형식을 우선 사용한다.
- 같은 날 여러 번 수정하더라도 누적 관리한다.
- 버전 변경 작업은 버전을 명확히 기록한다.
- 날짜 기준이 아니라 버전 기준 섹션으로 구분한다.
- 가장 최신 버전 섹션이 항상 문서 상단에 오도록 유지한다.
### 할 일 및 이슈
- 파일: docs/todo.md
- 아직 해결되지 않은 문제를 기록한다.
- 다음 작업자가 바로 이어서 할 수 있도록 구체적으로 작성한다.
- 이미 구현된 항목은 즉시 삭제한다.
- 더 이상 필요 없는 항목도 즉시 삭제한다.
- 단순 누적이 아닌 현재 기준으로 유효한 작업만 유지한다.
### 기술 명세
- 파일: docs/spec.md
- API, 화면 동작, 데이터 구조 변경 시 반영한다.
- 외부 인터페이스가 바뀌면 반드시 갱신한다.
### 코딩 컨벤션
- 파일: docs/convention.md
- 반복적으로 적용되는 규칙만 기록한다.
### 의사결정 이력
- 파일: docs/history.md
- 구조 변경 및 중요한 기술 선택을 기록한다.
- 반드시 이유를 함께 남긴다.
- `docs/history.md`는 서술형 기록을 허용한다.
- 가장 최신 항목이 항상 문서 상단에 오도록 유지한다.
- 항목 제목에는 날짜와 버전을 함께 표시한다.
### 파일-화면 매핑
- 파일: docs/map.md
- 파일과 URL, 기능 연결 관계를 기록한다.
### 배포 가이드
- 파일: docs/deploy.md
### 공개 변경 요약
- 파일: docs/changelog.md
- 외부 공유용 변경 요약이 필요할 때만 간결하게 정리한다.
---
## Git 및 버전 관리 규칙
- Git 작성자 정보는 프로젝트 기준 계정으로 통일한다.
- Git 작성자 이름은 `zenn`, 이메일은 `zenn.message@gmail.com`을 사용한다.
- 원격 저장소는 `https://git.sori.studio/zenn/sori.studio.git`을 사용한다.
- 커밋 메시지는 반드시 한국어로 작성한다.
- 버전 변경 시 docs/update.md 먼저 반영한다.
- 작업이 끝나 변경사항을 커밋할 때마다 버전을 증가시킨다.
- 버전은 `v0.0.1`, `v0.0.2`처럼 `v` 접두사를 포함해 순차 증가시킨다.
- 원격 저장소에 푸시하기 전 민감 정보 포함 여부를 반드시 확인한다.
민감 정보 예시:
- 실명
- 개인 이메일
- 비밀키 / 토큰
- 로컬 경로
- 내부 서버 주소
---
## 코드 작성 규칙
### 공통
- 기존 코드 스타일을 우선 따른다.
- 불필요한 리팩토링을 하지 않는다.
- 요청받지 않은 대규모 구조 변경을 하지 않는다.
- 작은 수정으로 해결 가능한 문제를 전면 재구성하지 않는다.
### Vue / Nuxt
- layouts/default.vue, post.vue, admin.vue 사용
- components/site/: SiteHeader, LeftSidebar, RightSidebar, MainColumn, PostCard, TagHeader
- components/content/: ContentRenderer, ProseHeading, ProseImage, ProseList, ProseBlockquote, ProseButton, ProseCallout, ProseToggle, ProseVideo, ProseAudio, ProseFile, ProseProduct, ProseHeaderCard, ProseEmbed
- SSR이 필요한 공개 페이지는 Nuxt 서버 렌더링 우선
- 관리자 페이지는 기능보다 유지보수성과 단순성 우선
### 상태 관리
- 기존 상태 관리 방식을 따른다.
- 동일 데이터를 중복 관리하지 않는다.
- posts와 pages는 별도 관리 (목록 노출 여부 다름)
- pages는 헤더와 사이드바 없이 본문 중심 전체 화면으로 표시한다.
### API / 데이터 처리
- 기존 API 호출 패턴을 따른다.
- 응답 구조 변경 시 docs/spec.md를 반드시 갱신한다.
- 하드코딩된 값 사용을 금지한다.
- 개발 환경과 운영 환경의 데이터베이스 연결 문자열을 혼용하지 않는다.
- 운영 DB는 로컬 개발 서버에서 직접 사용하지 않는다.
### 스타일
- Tailwind CSS를 기본으로 사용한다.
- 임시 이름 사용을 금지한다.
---
## 네이밍 규칙
- 의미가 드러나는 이름을 사용한다.
- 축약어 남용을 금지한다.
- 임시 이름 사용을 금지한다.
---
## 주석 규칙
- JSDoc 형식으로 작성한다.
- 함수/클래스 앞에는 반드시 문서화 주석을 작성한다.
- 한국어로 작성한다.
```javascript
/**
* 게시물 목록 조회
* @param {Object} options - 조회 옵션
* @param {number} options.page - 페이지 번호
* @param {number} options.limit - 페이지당 개수
* @returns {Promise<Post[]>} 게시물 목록
*/
```
---
## 검증 규칙
- 가능한 범위에서 검증을 수행한다.
- 실패 케이스를 확인한다.
- 검증하지 못한 경우 명시한다.
---
## 문서 업데이트 기준
- 기능 변경 → docs/spec.md
- 버그 수정 → docs/update.md
- 이슈 발견 → docs/todo.md
- 구조 변경 → docs/history.md
- 화면 변경 → docs/map.md
- 배포 변경 → docs/deploy.md
---
## 금지 사항
- docs 업데이트 누락
- 기존 스타일 무시
- 대규모 리팩토링
- 하드코딩 추가
- 민감 정보 커밋
- 검증 없이 완료 처리
---
## 의사결정 원칙
1. 기존 패턴 우선
2. 최소 수정
3. 유지보수 용이성
4. 구조 파악 용이성
---
## 작업 결과 보고 형식
- 수정 내용
- 변경 파일
- 검증 내용
- 문서 반영 여부
- 남은 이슈
---
## 최종 체크리스트
- docs 확인 여부
- 코드 수정 완료 여부
- 검증 수행 여부
- 문서 반영 여부
- 민감 정보 포함 여부

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 저장소 초기 기준점 설정 진행.