98 lines
9.0 KiB
Markdown
98 lines
9.0 KiB
Markdown
# 의사결정 이력
|
|
|
|
## 2026-05-01 v0.0.7
|
|
|
|
### 관리자 글 작성/수정 구조 결정
|
|
|
|
관리자 글 작성과 수정은 `AdminPostForm` 단일 컴포넌트를 공유한다. 현재 단계에서는 별도 위지윅 편집기를 도입하지 않고 마크다운 textarea 입력을 먼저 저장 가능한 형태로 연결한다. 글 관리의 핵심 흐름인 생성, 수정, 상태 변경을 먼저 검증한 뒤 미리보기, 자동 저장, 이미지 업로드를 분리해 확장하기 위해서다.
|
|
|
|
발행/초안/비공개 전환은 별도 publish API가 아니라 게시물 수정 API의 `status` 값으로 처리한다. 초기 관리자에서는 버튼과 API를 늘리기보다 저장 모델을 단순하게 유지하고, 추후 목록에서 빠른 발행 전환이 필요해질 때 별도 액션 API를 추가한다.
|
|
|
|
### 관리자 태그 관리 방식 결정
|
|
|
|
태그 관리는 목록 화면에서 생성/수정 입력을 인라인으로 열지 않고 생성/수정 전용 페이지로 분리한다. 태그에 표시 순서와 색상 코드가 추가되면서 입력 항목이 늘었고, 목록 행 안에서 수정 폼을 열면 테이블 레이아웃이 흔들리기 때문이다.
|
|
|
|
태그 삭제 시 게시물 자체는 삭제하지 않고 `post_tags` 연결만 외래 키 규칙으로 정리한다. 태그는 분류 메타데이터이고 게시물 본문 데이터와 생명주기가 다르기 때문이다.
|
|
|
|
태그의 `sort_order`는 공개 화면 카테고리 정렬 기준으로 사용하고, `color`는 태그 옆 색상 바와 이후 태그 배지 배경색에 사용할 수 있도록 `#RRGGBB` 문자열로 저장한다.
|
|
|
|
### 초기 관리자 인증 방식 결정
|
|
|
|
관리자 기능 1차 구현은 별도 사용자 테이블을 만들지 않고 `ADMIN_EMAIL`, `ADMIN_PASSWORD` 환경 변수로 시작한다. 개인 블로그/CMS 초기 단계에서는 운영 계정 수가 하나이고, 데이터 모델을 먼저 늘리기보다 글 관리 흐름을 빠르게 검증하는 편이 유지보수에 유리하다.
|
|
|
|
로그인 성공 시 `/admin` 경로에만 적용되는 httpOnly 세션 쿠키를 설정한다. 세션 토큰은 `ADMIN_PASSWORD` 기반 HMAC 서명으로 검증해 쿠키 위조를 막고, 운영 단계에서 사용자 테이블이나 더 강한 인증 방식이 필요해지는 시점에 확장한다.
|
|
|
|
### 로컬 개발 컨테이너 실행 환경 결정
|
|
|
|
새 개발 환경에서 Docker Desktop 없이 터미널 중심으로 PostgreSQL 개발 DB를 실행하기 위해 Homebrew, Docker CLI, Docker Compose, Colima 조합을 사용한다. 이 방식은 Docker daemon을 Colima가 담당하고, 프로젝트는 기존 `docker-compose.yml`을 그대로 활용할 수 있어 NAS Docker 배포 구조와 로컬 개발 구조를 크게 벌리지 않는다.
|
|
|
|
로컬 개발 DB는 `.env.development`만 사용하고, Docker Compose 실행 시 `ENV_FILE=.env.development`와 `--env-file .env.development`를 함께 넘긴다. 이렇게 하면 Git에 포함되지 않는 로컬 비밀번호를 사용하면서도 운영 기본값인 `.env.production` 기준은 유지할 수 있다.
|
|
|
|
개발 DB 마이그레이션은 `npm run db:migrate:dev`로 실행한다. Docker entrypoint는 새 볼륨 생성 시에만 SQL을 자동 실행하므로, 이미 생성된 개발 DB에도 반복 적용할 수 있는 별도 실행 명령을 둔다.
|
|
|
|
## 2026-04-29 v0.0.6
|
|
|
|
### 환경 변수 파일 보안 기준 정리
|
|
|
|
`.env.example`은 Git에 포함되는 공유 템플릿이므로 실제 개인 이메일, 관리자 비밀번호, DB 비밀번호를 기록하지 않는다. 공유 파일에는 placeholder만 두고, 실제 값은 Git에서 제외되는 `.env.development`와 `.env.production`에서만 관리한다.
|
|
|
|
로컬 개발 환경은 `127.0.0.1:43119`로 개발 DB에 연결하고, NAS Docker 운영 환경은 `sori-studio-db:5432`로 운영 DB에 연결한다. 개발 DB와 운영 DB는 비밀번호도 분리해 한쪽 값이 노출되더라도 다른 환경으로 전파되지 않게 한다.
|
|
|
|
이미 원격 저장소에 올라간 비밀번호가 실제 사용 값이었다면 Git 이력에서 지워도 안전하다고 볼 수 없으므로, 해당 값은 폐기하고 새 랜덤 값으로 교체하는 것을 전제로 한다.
|
|
|
|
## 2026-04-29 v0.0.5
|
|
|
|
### PostgreSQL 기반 데이터 계층 결정
|
|
|
|
DB 관리 도구로 CloudBeaver를 고려하고 NAS Docker 배포를 전제로 하기 때문에 초기 데이터베이스는 PostgreSQL로 잡는다. SQLite보다 운영/개발 분리, 외부 관리 도구 연결, 향후 확장에 유리하다.
|
|
|
|
Nuxt 서버 API는 바로 DB에 강결합하지 않고 `server/repositories`를 통해 콘텐츠를 조회한다. `DATABASE_URL`이 설정된 환경에서는 PostgreSQL을 사용하고, 설정되지 않은 환경에서는 샘플 데이터를 사용해 화면과 API 개발을 계속할 수 있게 했다.
|
|
|
|
Docker Compose에는 앱과 PostgreSQL 서비스를 함께 두되, 실제 운영 비밀번호와 연결 문자열은 `.env.production`에서 관리한다. DB 외부 포트는 기존 사용 포트와 겹치지 않도록 `43119`를 사용한다.
|
|
|
|
## 2026-04-29 v0.0.4
|
|
|
|
### 메뉴 토글 구현 방식 결정
|
|
|
|
원본 Ghost 테마는 Alpine 스타일의 `@click`, `:class`, `:aria-expanded` 바인딩으로 좌측 메뉴 상태를 제어한다. 이 프로젝트는 Nuxt/Vue 기반이므로 Alpine을 추가하지 않고 Vue 상태와 composable로 같은 기능을 구현한다.
|
|
|
|
메뉴 상태는 `useMenuState`에서 공유하고, 브라우저 `localStorage`의 `MENU_STATE`에 저장한다. 이렇게 하면 헤더 버튼, 공개 레이아웃, 게시물 레이아웃이 같은 상태를 사용하면서도 별도 프론트엔드 상태 라이브러리나 Alpine 의존성을 추가하지 않아도 된다.
|
|
|
|
## 2026-04-29 v0.0.3
|
|
|
|
### 공개 화면 테마와 패널 구조 보정
|
|
|
|
참고 화면 기준으로 공개 화면은 단순한 흰색 페이지가 아니라 헤더 아래 좌측 사이드바, 중앙 본문, 우측 사이드바가 각각 전체 화면 높이를 차지하는 패널 구조로 정했다. 사이드바 콘텐츠가 적어도 패널 자체는 `calc(100vh - 57px)` 높이를 유지한다.
|
|
|
|
색상은 초반부터 라이트/다크 모드 기준을 잡기 위해 CSS 변수로 관리한다. 기본 배경, 패널, 라인, 텍스트, 보조 텍스트, 입력, 강조 버튼 색상을 분리해 이후 디자인 조정 시 Tailwind 클래스 전체를 갈아엎지 않도록 했다.
|
|
|
|
## 2026-04-29 v0.0.2
|
|
|
|
### Nuxt 통합 백엔드 구조 결정
|
|
|
|
초기 세팅은 별도 백엔드 앱을 만들지 않고 Nuxt/Nitro의 `server/api`를 사용한다. 개인 블로그와 CMS를 한 서버에서 배포하면 로컬 개발, NAS 운영, 환경 변수 관리가 단순해진다. DB 연결과 API 라우팅은 Nuxt 서버 영역에서 시작하고, 추후 독립 배포나 워커가 필요해질 때 백엔드 분리를 재검토한다.
|
|
|
|
Nuxt 3, Tailwind CSS, Zod를 실제 의존성으로 추가하고 공개 화면, 관리자 화면, 콘텐츠 컴포넌트의 초기 골격을 만들었다. 현재 API는 샘플 데이터 기반이며 다음 단계에서 개발 DB로 교체한다.
|
|
|
|
기본 포트와 사용 중인 포트 충돌을 피하기 위해 로컬 개발 서버는 `43117`, NAS Docker 외부 포트는 `43118`을 사용한다. 컨테이너 내부 포트는 Nuxt 기본 실행 흐름에 맞춰 `3000`으로 유지한다.
|
|
|
|
## 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/` 아래 문서만 사용한다.
|