미디어 폴더 트리 관리 추가

docs/history.md

@@ -1,5 +1,13 @@
 # 의사결정 이력
 
+## 2026-05-02 v0.0.27
+
+### 미디어 폴더 트리 관리 방식 결정
+
+미디어 폴더는 워드프레스 플러그인형 폴더 UX처럼 왼쪽 트리에서 만들고 선택하지만, 실제 업로드 파일 경로는 이동하지 않는다. 이미 게시물과 페이지에 저장된 이미지 URL이 깨지는 일을 막기 위해 폴더 이동은 `media_metadata.category` 값을 경로 문자열로 갱신하는 방식으로 처리한다.
+
+빈 폴더도 남길 수 있어야 하므로 `media_folders` 테이블을 별도로 둔다. 다만 미디어 사용 여부와 공개 렌더링은 계속 URL 기준으로 판단하며, Ctrl/Command 및 Shift 복수 선택과 드래그 이동은 선택된 URL 목록의 메타데이터만 일괄 변경한다.
+
 ## 2026-05-02 v0.0.26
 
 ### 미디어 카테고리 저장 방식 결정

docs/map.md

@@ -63,7 +63,7 @@
 | pages/admin/pages/index.vue | 페이지 목록 |
 | pages/admin/pages/new.vue | 페이지 작성, 저장 토스트 |
 | pages/admin/pages/[id].vue | 페이지 수정, 저장/삭제 토스트 |
-| pages/admin/media/index.vue | 미디어 관리 |
+| pages/admin/media/index.vue | 미디어 관리, 폴더 트리, 복수 선택, 드래그 이동 |
 | pages/admin/navigation/index.vue | 메뉴/네비게이션 관리 |
 | pages/admin/tags/index.vue | 태그 관리 |
 | pages/admin/tags/new.vue | 태그 생성 |
@@ -108,8 +108,10 @@
 | server/routes/admin/api/pages/[id].put.js | 관리자 고정 페이지 수정 API |
 | server/routes/admin/api/pages/[id].delete.js | 관리자 고정 페이지 삭제 API |
 | server/routes/admin/api/media.get.js | 관리자 미디어 목록 API |
-| server/routes/admin/api/media.put.js | 관리자 미디어 파일명 변경 API |
+| server/routes/admin/api/media.put.js | 관리자 미디어 파일명 변경 및 단일/복수 폴더 변경 API |
 | server/routes/admin/api/media.delete.js | 관리자 미디어 삭제 API |
+| server/routes/admin/api/media-folders.get.js | 관리자 미디어 폴더 목록 API |
+| server/routes/admin/api/media-folders.post.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 |
@@ -130,7 +132,7 @@
 | server/utils/admin-tag-input.js | 관리자 태그 입력값 검증 스키마 |
 | server/utils/site-settings.js | 사이트 설정 기본값 유틸리티 |
 | server/utils/navigation-items.js | 네비게이션 기본값과 그룹 유틸리티 |
-| server/utils/media-library.js | 업로드 미디어 파일 관리 유틸리티 |
+| server/utils/media-library.js | 업로드 미디어 파일과 폴더 메타데이터 관리 유틸리티 |
 | server/repositories/postgres-client.js | PostgreSQL 클라이언트 |
 | server/repositories/content-repository.js | 콘텐츠 조회 저장소 |
 
@@ -144,6 +146,7 @@
 | db/migrations/004_add_site_settings.sql | 사이트 설정 테이블 추가 |
 | db/migrations/005_add_navigation_items.sql | 네비게이션 항목 테이블 추가 |
 | db/migrations/006_add_media_metadata.sql | 미디어 메타데이터 테이블 추가 |
+| db/migrations/007_add_media_folders.sql | 미디어 폴더 테이블 추가 |
 
 ## 설정/배포
 

docs/spec.md

@@ -184,7 +184,15 @@ components/content/
 | 필드 | 타입 | 설명 |
 |------|------|------|
 | url | String | 업로드 미디어 URL |
-| category | String | 관리자 분류명 |
+| category | String | 관리자 미디어 폴더 경로 |
+| created_at | DateTime | 생성일 |
+| updated_at | DateTime | 수정일 |
+
+### MediaFolders
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| path | String | 미디어 폴더 경로 |
 | created_at | DateTime | 생성일 |
 | updated_at | DateTime | 수정일 |
 
@@ -238,8 +246,10 @@ components/content/
 - `PUT /admin/api/pages/:id` - 고정 페이지 수정
 - `DELETE /admin/api/pages/:id` - 고정 페이지 삭제
 - `GET /admin/api/media` - 업로드 미디어 목록
-- `PUT /admin/api/media` - 업로드 미디어 파일명 변경
+- `PUT /admin/api/media` - 업로드 미디어 파일명 변경 또는 단일/복수 미디어 폴더 변경
 - `DELETE /admin/api/media` - 업로드 미디어 삭제
+- `GET /admin/api/media-folders` - 미디어 폴더 목록
+- `POST /admin/api/media-folders` - 미디어 폴더 생성
 - `POST /admin/api/uploads` - 관리자 이미지 업로드
 - `GET /admin/api/tags` - 태그 목록
 - `POST /admin/api/tags` - 태그 생성
@@ -340,10 +350,12 @@ components/content/
 - 관리자 이미지 업로드 API는 `image/jpeg`, `image/png`, `image/webp`, `image/gif`만 허용한다.
 - 업로드 파일 크기 제한은 `MAX_FILE_SIZE` 환경 변수를 따른다.
 - 로컬 개발 업로드 파일은 `public/uploads/posts/YYYY/MM/` 아래 저장하고 `/uploads/posts/YYYY/MM/filename` URL로 제공한다.
-- 관리자 미디어 화면은 고밀도 썸네일 갤러리, 검색, 파일명 변경, 개별 삭제를 제공한다.
-- 관리자 미디어 화면은 카테고리 필터와 미디어별 카테고리 수정을 제공한다.
-- 미디어 파일 경로, 사용 현황, 용량 등 세부 정보는 썸네일 클릭 시 열리는 상세 모달에서 표시한다.
-- 미디어 카테고리는 파일 경로를 옮기지 않고 `media_metadata` 테이블에 URL별로 저장한다.
+- 관리자 미디어 화면은 왼쪽 폴더 트리와 오른쪽 고밀도 썸네일 갤러리, 검색, 파일명 변경, 개별 삭제를 제공한다.
+- 관리자는 폴더 트리에서 새 폴더와 하위 폴더를 만들 수 있다.
+- 미디어는 Ctrl/Command 클릭으로 복수 선택하고 Shift 클릭으로 범위 선택할 수 있다.
+- 선택한 미디어를 폴더로 드래그하면 해당 미디어들의 폴더 경로가 일괄 변경된다.
+- 미디어 파일 경로, 사용 현황, 용량 등 세부 정보는 썸네일 더블 클릭 시 열리는 상세 모달에서 표시한다.
+- 미디어 폴더는 실제 파일 경로를 옮기지 않고 `media_metadata` 테이블에 URL별 경로 메타데이터로 저장한다.
 - 글쓰기 미디어 선택 창은 업로드 미디어 목록에서 이미지를 선택해 단일 이미지 또는 갤러리에 삽입한다.
 - 미디어 사용 현황은 게시물/페이지의 대표 이미지와 본문 내 URL을 기준으로 표시한다.
 - 사용 중인 미디어는 저장된 콘텐츠 URL이 깨지지 않도록 파일명 변경과 삭제를 차단한다.

docs/todo.md

@@ -10,15 +10,13 @@
 - [ ] 대표 이미지 브라우저 수동 QA: 기존 미디어 선택, 새 업로드, 썸네일 표시, 삭제/변경 확인
 - [ ] 미디어 라이브러리 상세 모달 수동 QA: 검색, 사용 현황, 파일명 변경, 삭제 잠금 확인
 - [ ] 콜아웃, 토글, 임베드 블록 브라우저 수동 QA: `/` 메뉴 선택, 저장/수정 왕복, 공개 렌더링 확인
-- [ ] 글 작성 중 자동 저장 브라우저 수동 QA: 새 글/수정 글 복원, 저장 성공 후 삭제, 빈 글 자동 저장 삭제 확인
-- [ ] 저장 토스트 브라우저 수동 QA: 새 글 저장 후 이동, 수정 저장, 저장 실패, 삭제 실패 상태 확인
 
 ## 2차 관리자 개발
 
 - [ ] 페이지 관리 브라우저 수동 QA: 생성, 수정, 삭제, 공개 보기 확인
 - [ ] 사이트 설정 브라우저 수동 QA: 저장, 공개 헤더/사이드바 반영, 잘못된 URL 실패 확인
 - [ ] 메뉴/네비게이션 브라우저 수동 QA: 항목 추가, 삭제, 숨김, 정렬, 공개 사이드바 반영 확인
-- [ ] 미디어 라이브러리 카테고리 브라우저 수동 QA: 카테고리 저장, 필터, 파일명 변경 후 유지 확인
+- [ ] 미디어 라이브러리 폴더 브라우저 수동 QA: 폴더 생성, 하위 폴더 표시, Ctrl/Command 복수 선택, Shift 범위 선택, 드래그 일괄 이동, 상세 모달 폴더 변경 확인
 - [ ] 미디어 라이브러리 프로필/사이트 설정 이미지 사용처 추적
 
 ## 3차 관리자 개발

docs/update.md

@@ -1,5 +1,15 @@
 # 업데이트 이력
 
+## v0.0.27
+
+- 미디어 폴더 테이블 추가.
+- 관리자 미디어 폴더 목록/생성 API 추가.
+- 관리자 미디어 화면을 왼쪽 폴더 트리와 오른쪽 썸네일 갤러리 구조로 수정.
+- 미디어 Ctrl/Command 클릭 및 Shift 클릭 복수 선택 기능 추가.
+- 선택 미디어를 폴더로 드래그해 일괄 이동하는 기능 추가.
+- 미디어 폴더 이동은 실제 파일 경로가 아닌 메타데이터 경로를 갱신하도록 유지.
+- 패키지 버전을 0.0.27로 갱신.
+
 ## v0.0.26
 
 - 미디어 메타데이터 테이블 추가.