From efc7955415e5b9cc3e7055bdad68bd9496593b42 Mon Sep 17 00:00:00 2001 From: zenn Date: Wed, 29 Apr 2026 14:28:57 +0900 Subject: [PATCH] =?UTF-8?q?=EC=B4=88=EA=B8=B0=20=EB=AC=B8=EC=84=9C=20?= =?UTF-8?q?=EA=B8=B0=EC=A4=80=EC=A0=90=20=EC=A0=95=EB=A6=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 29 ++++++ AGENTS.md | 242 +++++++++++++++++++++++++++++++++++++++++++++ docs/changelog.md | 12 +++ docs/convention.md | 52 ++++++++++ docs/deploy.md | 110 +++++++++++++++++++++ docs/history.md | 21 ++++ docs/map.md | 63 ++++++++++++ docs/spec.md | 214 +++++++++++++++++++++++++++++++++++++++ docs/todo.md | 69 +++++++++++++ docs/update.md | 16 +++ 10 files changed, 828 insertions(+) create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 docs/changelog.md create mode 100644 docs/convention.md create mode 100644 docs/deploy.md create mode 100644 docs/history.md create mode 100644 docs/map.md create mode 100644 docs/spec.md create mode 100644 docs/todo.md create mode 100644 docs/update.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3dd4cd6 --- /dev/null +++ b/.gitignore @@ -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/ \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..183fc6f --- /dev/null +++ b/AGENTS.md @@ -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} 게시물 목록 + */ +``` + +--- + +## 검증 규칙 +- 가능한 범위에서 검증을 수행한다. +- 실패 케이스를 확인한다. +- 검증하지 못한 경우 명시한다. + +--- + +## 문서 업데이트 기준 +- 기능 변경 → docs/spec.md +- 버그 수정 → docs/update.md +- 이슈 발견 → docs/todo.md +- 구조 변경 → docs/history.md +- 화면 변경 → docs/map.md +- 배포 변경 → docs/deploy.md + +--- + +## 금지 사항 +- docs 업데이트 누락 +- 기존 스타일 무시 +- 대규모 리팩토링 +- 하드코딩 추가 +- 민감 정보 커밋 +- 검증 없이 완료 처리 + +--- + +## 의사결정 원칙 +1. 기존 패턴 우선 +2. 최소 수정 +3. 유지보수 용이성 +4. 구조 파악 용이성 + +--- + +## 작업 결과 보고 형식 +- 수정 내용 +- 변경 파일 +- 검증 내용 +- 문서 반영 여부 +- 남은 이슈 + +--- + +## 최종 체크리스트 +- docs 확인 여부 +- 코드 수정 완료 여부 +- 검증 수행 여부 +- 문서 반영 여부 +- 민감 정보 포함 여부 diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..69a115d --- /dev/null +++ b/docs/changelog.md @@ -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를 사용하도록 배포 기준 보강. + +공개 플랫폼에 공유할 주요 변경사항은 사용자가 요청한 시점에 별도 문장으로 정리한다. diff --git a/docs/convention.md b/docs/convention.md new file mode 100644 index 0000000..b8d7f11 --- /dev/null +++ b/docs/convention.md @@ -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 +
+``` + +## 주석 + +- JSDoc 형식 +- 한국어 작성 + +```javascript +/** + * 게시물 목록 조회 + * @param {Object} options - 조회 옵션 + * @param {number} options.page - 페이지 번호 + * @param {number} options.limit - 페이지당 개수 + * @returns {Promise} 게시물 목록 + */ +``` + +## 설정 + +- 경로/URL/키값: .env로 관리 +- 하드코딩 금지 +- 로컬 개발 설정과 NAS 운영 설정은 별도 환경 파일로 분리 +- 운영 DB 접속 정보는 개발용 `.env`에 기록하지 않음 diff --git a/docs/deploy.md b/docs/deploy.md new file mode 100644 index 0000000..b42702f --- /dev/null +++ b/docs/deploy.md @@ -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 연결 방식 확정. diff --git a/docs/history.md b/docs/history.md new file mode 100644 index 0000000..fb4c61f --- /dev/null +++ b/docs/history.md @@ -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 `으로 통일해 이후 커밋 이력을 한 계정 기준으로 유지한다. + +`note.md`는 원본 의도 반영이 끝난 뒤 삭제한다. 이후 프로젝트 기준 문서는 `AGENTS.md`와 `docs/` 아래 문서만 사용한다. diff --git a/docs/map.md b/docs/map.md new file mode 100644 index 0000000..377b2b6 --- /dev/null +++ b/docs/map.md @@ -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 | 고정 페이지 상세 | diff --git a/docs/spec.md b/docs/spec.md new file mode 100644 index 0000000..7592bfe --- /dev/null +++ b/docs/spec.md @@ -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 +- 첫 커밋 이후 변경사항을 커밋할 때마다 패치 버전 증가 +- 메이저/마이너 버전은 구조 변경 또는 기능 묶음 단위로 결정 diff --git a/docs/todo.md b/docs/todo.md new file mode 100644 index 0000000..90b97e0 --- /dev/null +++ b/docs/todo.md @@ -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 작성 diff --git a/docs/update.md b/docs/update.md new file mode 100644 index 0000000..f080d94 --- /dev/null +++ b/docs/update.md @@ -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 저장소 초기 기준점 설정 진행.