관리자 이미지와 갤러리 블록 추가

docs/deploy.md

@@ -141,9 +141,18 @@ docker run -d -p 3000:3000 sori.studio:latest
 - 로컬 개발 Docker Compose 실행 시 `ENV_FILE=.env.development`와 `--env-file .env.development`를 함께 사용
 - 로컬 개발 DB 마이그레이션은 `npm run db:migrate:dev`로 실행
 
+## 업로드 파일
+
+- 관리자 글쓰기에서 업로드한 이미지는 `/uploads/posts/YYYY/MM/` URL로 제공한다.
+- 로컬 개발에서는 실제 파일이 `public/uploads/posts/YYYY/MM/` 아래 저장된다.
+- `public/uploads/`는 Git에 포함하지 않는다.
+- NAS 운영에서는 업로드 파일이 컨테이너 재생성으로 사라지지 않도록 별도 볼륨 연결을 확정해야 한다.
+- `MAX_FILE_SIZE` 환경 변수로 관리자 이미지 업로드 최대 크기를 제한한다.
+
 ## 사용자 액션 필요 항목
 
 - NAS SSH 접속 주소 확인.
 - NAS 프로젝트 루트 경로 확정.
 - 운영 DB 이름, 계정, 권한 확정.
+- 운영 업로드 볼륨 경로 확정.
 - 도메인 `sori.studio`의 NAS 연결 방식 확정.

docs/history.md

@@ -1,5 +1,13 @@
 # 의사결정 이력
 
+## 2026-05-01 v0.0.14
+
+### 이미지와 갤러리 블록 구현 범위 결정
+
+관리자 글쓰기의 이미지 기능은 기존 `content` 필드를 유지하면서 마크다운 확장 문법으로 저장한다. 단일 이미지는 기본 마크다운 이미지 문법에 `{width=wide}` 같은 너비 옵션만 붙이고, 갤러리는 `:::gallery` fenced block 안에 여러 이미지 행을 넣는다. 이렇게 하면 DB 구조를 바꾸지 않고 공개 렌더러와 관리자 에디터를 함께 확장할 수 있다.
+
+이번 단계에서는 게시물 작성 중 새 이미지를 업로드하고 글에 삽입하는 흐름을 먼저 구현한다. 워드프레스처럼 이미 업로드된 미디어를 선택하거나 파일명 변경, 개별 삭제, 카테고리 분류를 관리하는 기능은 별도 미디어 라이브러리 메뉴에서 다룬다. 글쓰기 화면이 이후 미디어 라이브러리를 호출할 수 있도록 업로드 API와 저장 URL 기준을 먼저 고정한다.
+
 ## 2026-05-01 v0.0.13
 
 ### 개발 서버 로그 요약 방식 결정

docs/map.md

@@ -27,7 +27,7 @@
 | 파일 | 화면 위치 |
 |------|-----------|
 | components/admin/AdminPostForm.vue | 관리자 글 작성/수정 폼 |
-| components/admin/AdminBlockEditor.vue | 관리자 글 블록형 에디터 |
+| components/admin/AdminBlockEditor.vue | 관리자 글 블록형 에디터, 이미지/갤러리 블록 |
 | components/admin/AdminTagForm.vue | 관리자 태그 생성/수정 폼 |
 
 ## 콘텐츠 컴포넌트
@@ -91,6 +91,7 @@
 | server/routes/admin/api/posts/[id].get.js | 관리자 게시물 상세 API |
 | server/routes/admin/api/posts/[id].put.js | 관리자 게시물 수정 API |
 | server/routes/admin/api/posts/[id].delete.js | 관리자 게시물 삭제 API |
+| server/routes/admin/api/uploads.post.js | 관리자 이미지 업로드 API |
 | server/routes/admin/api/tags.get.js | 관리자 태그 목록 API |
 | server/routes/admin/api/tags.post.js | 관리자 태그 생성 API |
 | server/routes/admin/api/tags/[id].get.js | 관리자 태그 상세 API |

docs/spec.md

@@ -188,6 +188,7 @@ components/content/
 - `GET /admin/api/posts/:id` - 글 상세
 - `PUT /admin/api/posts/:id` - 글 수정
 - `DELETE /admin/api/posts/:id` - 글 삭제
+- `POST /admin/api/uploads` - 관리자 이미지 업로드
 - `GET /admin/api/tags` - 태그 목록
 - `POST /admin/api/tags` - 태그 생성
 - `GET /admin/api/tags/:id` - 태그 상세
@@ -207,7 +208,7 @@ components/content/
 - `/` 명령 메뉴는 화면 하단 공간이 부족하면 현재 블록 위쪽으로 표시한다.
 - `/` 명령 메뉴가 열린 상태에서 Enter를 누르면 현재 강조된 메뉴 항목을 적용한다.
 - `/` 명령 메뉴가 열린 상태에서 위/아래 방향키로 강조 항목을 이동한다.
-- 블록 메뉴는 문단, 제목 2, 제목 3, 인용, 목록, 코드, 구분선을 제공한다.
+- 블록 메뉴는 문단, 제목 2, 제목 3, 이미지, 갤러리, 인용, 목록, 코드, 구분선을 제공한다.
 - `#`, `##`, `###`, `>`, `-` 입력 후 공백을 누르면 현재 블록 타입을 즉시 변환한다.
 - 빈 문단에서 Enter를 누르면 다음 빈 문단 블록을 생성한다.
 - 빈 블록 placeholder는 현재 활성 블록 또는 첫 빈 블록에만 표시한다.
@@ -215,6 +216,11 @@ components/content/
 - 제목 입력에서 Enter를 누르면 본문 첫 블록으로 포커스를 이동한다.
 - 관리자 글 에디터의 실제 입력 텍스트 색상은 placeholder보다 진하게 표시한다.
 - 관리자 작성 화면과 공개 본문은 같은 마크다운 렌더링 기준을 사용한다.
+- 이미지 블록은 관리자 업로드 API로 이미지를 업로드하고 `![alt](url){width=wide}` 형식으로 저장한다.
+- 이미지 블록 표시 옵션은 `regular`, `wide`, `full` 값을 사용하며 `regular`는 width 옵션을 생략한다.
+- 갤러리 블록은 `:::gallery` fenced block 안에 이미지 마크다운 행을 여러 개 저장한다.
+- 공개 갤러리는 한 줄에 2~3개 이미지 그리드로 표시하고 클릭 시 라이트박스로 크게 확인한다.
+- 현재 글쓰기 화면은 새 이미지 업로드를 우선 지원하며, 기존 업로드 미디어 선택은 미디어 라이브러리 구현 시 추가한다.
 
 ### 관리자 인증
 
@@ -236,6 +242,11 @@ components/content/
 /uploads/system/favicon.png
 ```
 
+- 관리자 이미지 업로드 API는 `image/jpeg`, `image/png`, `image/webp`, `image/gif`만 허용한다.
+- 업로드 파일 크기 제한은 `MAX_FILE_SIZE` 환경 변수를 따른다.
+- 로컬 개발 업로드 파일은 `public/uploads/posts/YYYY/MM/` 아래 저장하고 `/uploads/posts/YYYY/MM/filename` URL로 제공한다.
+- 향후 미디어 라이브러리는 업로드 이미지 목록, 기존 미디어 선택, 파일명 변경, 개별 삭제, 카테고리 분류를 제공한다.
+
 ---
 
 ## 환경 변수 (.env)

docs/todo.md

@@ -4,7 +4,8 @@
 
 - [ ] 블록 에디터 브라우저 수동 QA: 빈 줄 Enter, `/` 메뉴 필터, 방향키, Enter 선택, 한글 조합 입력 확인
 - [ ] 블록 에디터 저장/수정 왕복 QA: 기존 글 수정 시 블록 파싱, 저장 후 다시 열기 확인
-- [ ] 이미지 업로드 블록 구현
+- [ ] 이미지/갤러리 블록 브라우저 수동 QA: 업로드, 너비 옵션, 저장 후 공개 렌더링, 갤러리 라이트박스 확인
+- [ ] 게시물 작성 시 기존 미디어 선택 또는 새 미디어 업로드 선택 흐름 추가
 - [ ] 콜아웃, 토글, 임베드 블록 추가
 - [ ] 글 작성 중 자동 저장
 
@@ -13,7 +14,7 @@
 - [ ] 페이지 관리 (CRUD)
 - [ ] 사이트 설정
 - [ ] 메뉴/네비게이션 관리
-- [ ] 미디어 라이브러리
+- [ ] 미디어 라이브러리: 업로드 이미지 목록, 검색, 선택, 파일명 변경, 개별 삭제, 카테고리 분류
 
 ## 3차 관리자 개발
 

docs/update.md

@@ -1,5 +1,17 @@
 # 업데이트 이력
 
+## v0.0.14
+
+- 관리자 블록 에디터에 단일 이미지 블록 추가.
+- 관리자 블록 에디터에 복수 이미지 갤러리 블록 추가.
+- 이미지 블록의 기본/와이드/풀사이즈 표시 옵션 추가.
+- 관리자 이미지 업로드 API 추가.
+- 공개 본문 렌더러에 이미지와 갤러리 렌더링 추가.
+- 공개 갤러리 이미지 클릭 시 라이트박스로 크게 보는 기능 추가.
+- 업로드 파일이 Git에 포함되지 않도록 `public/uploads/` 제외 처리.
+- 향후 미디어 라이브러리 관리 기능 범위 정리.
+- 패키지 버전을 0.0.14로 갱신.
+
 ## v0.0.13
 
 - 개발 서버 실행 로그를 프로젝트 전용 링크 요약 출력으로 정리.