게시물 Import 호환성 보강 v1.5.28

2026-06-02 10:30:11 +09:00
parent ef1a9d9032
commit 9d91355c81
11 changed files with 117 additions and 19 deletions
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -1,5 +1,10 @@
 # 업데이트 요약

+## v1.5.28
+
+- 게시물 Import가 Obsidian식 YAML 블록 배열 태그를 읽을 수 있게 했다.
+- Import 중 ZIP 내부 자산 누락이 있으면 완료 결과에 경고로 표시한다.
+
 ## v1.5.27

 - 게시물 Export ZIP을 관리자 설정에서 다시 Import할 수 있게 했다.
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -1,6 +1,6 @@
 # 배포 가이드

-> 로컬 기준 v1.5.27에서 `npm run lint`, `npm run build` 검증을 통과했다. NAS 실제 컨테이너 기동과 도메인/프록시 접속 검증은 운영 배포 단계에서 진행한다.
+> 로컬 기준 v1.5.28에서 `npm run lint`, `npm run build` 검증을 통과했다. NAS 실제 컨테이너 기동과 도메인/프록시 접속 검증은 운영 배포 단계에서 진행한다.

 ## 빌드 유형

--- a/docs/history.md
+++ b/docs/history.md
@@ -1,5 +1,9 @@
 # 의사결정 이력

+## 2026-06-02 v1.5.28 — Import는 부분 누락을 경고로 남긴다
+
+Export ZIP을 Obsidian에서 열고 편집한 뒤 다시 Import할 수 있어야 하므로, 태그 frontmatter는 inline 배열뿐 아니라 Obsidian이 흔히 쓰는 블록 배열도 읽는다. 또한 일부 이미지나 파일이 ZIP에서 누락된 경우 전체 Import를 막으면 나머지 게시물 복구까지 실패하므로, 게시물 생성은 계속 진행하고 누락 자산은 관리자 화면 경고로 확인하게 한다.
+
 ## 2026-06-02 v1.5.27 — Import 1차는 덮어쓰기보다 안전한 추가 가져오기

 Export ZIP은 백업 복구와 다른 환경으로의 이관에 모두 쓰일 수 있다. 같은 슬러그가 이미 있는 운영 DB에서 Import가 기존 글을 바로 덮어쓰면 복구보다 손상 위험이 커지므로, 1차 Import는 모든 게시물을 새 글로 추가하고 슬러그 충돌 시 `-2`, `-3` 접미사를 붙이는 정책으로 둔다. ZIP 내부 자산은 원래 URL을 믿지 않고 새 업로드 저장소로 다시 복사해 본문 경로를 새 `/uploads/...` URL로 재매핑한다.
--- a/docs/map.md
+++ b/docs/map.md
@@ -140,7 +140,7 @@
 | pages/admin/tags/index.vue | 태그 관리(메인 태그 드래그 정렬 자동 저장·more vert 메뉴, 일반 태그 배지 more vert 메뉴·검색/정렬, 태그 추가 버튼), 액션 피드백 토스트 |
 | pages/admin/tags/new.vue | 태그 생성 |
 | pages/admin/tags/[id].vue | 태그 수정 |
-| pages/admin/settings/index.vue | 사이트 설정 Ghost형 전체 화면, **POST 설정**(`showPostUpdatedAt` 토글·읽기 모드 비활성 톤), 블로그 제목·설명·기타(로고·URL·저작권), **메인 화면**(라이트·다크 커버 이미지·오버레이 텍스트), **어나운스 바**(사용 토글·맞춤 설정·배경색·읽기 모드 비활성 톤), **스팸 필터**(가입 금지 닉네임), 타임존, 게시물 Import/Export 기본 액션 버튼, 펼침형 Export 전체·연도·월·직접 날짜 범위 작업 요청·목표 ZIP 용량·ZIP당 최대 게시물 수, 접힌 Import 안내 패널, 최근 작업·진행도·준비 완료 분할 파일 다운로드·브라우저 순차 일괄 다운로드·실패 작업 재시도·실패 상세 오류·작업 삭제, 진행 중 요청 버튼 잠금 |
+| pages/admin/settings/index.vue | 사이트 설정 Ghost형 전체 화면, **POST 설정**(`showPostUpdatedAt` 토글·읽기 모드 비활성 톤), 블로그 제목·설명·기타(로고·URL·저작권), **메인 화면**(라이트·다크 커버 이미지·오버레이 텍스트), **어나운스 바**(사용 토글·맞춤 설정·배경색·읽기 모드 비활성 톤), **스팸 필터**(가입 금지 닉네임), 타임존, 게시물 Import/Export 기본 액션 버튼, 펼침형 Export 전체·연도·월·직접 날짜 범위 작업 요청·목표 ZIP 용량·ZIP당 최대 게시물 수, 펼침형 Import ZIP 업로드·완료 요약·누락 자산 경고 표시, 최근 작업·진행도·준비 완료 분할 파일 다운로드·브라우저 순차 일괄 다운로드·실패 작업 재시도·실패 상세 오류·작업 삭제, 진행 중 요청 버튼 잠금 |
 | lib/signup-blocked-usernames.js | 가입 금지 닉네임 정리·매칭·안내 문구 |
 | pages/admin/members/index.vue | 관리자 멤버 목록(Ghost형 테이블, 글 목록과 같은 테두리형 검색, 조건 필터, 멤버 추가 버튼, 닉네임+이메일, 등급+비활성 상태, 가입일+최근 활동, IP, 댓글 수) |
 | pages/admin/members/new.vue | 관리자 멤버 추가(썸네일 URL, 이름, 이메일, 레이블, 관리자 노트) |
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -522,7 +522,7 @@ components/content/
 - `DELETE /admin/api/posts/export-jobs/:jobId` - 완료·실패한 게시물 Export 작업과 생성 ZIP 파일 삭제
 - `POST /admin/api/posts/export-jobs/:jobId/retry` - 실패한 게시물 Export 작업을 준비 완료 파일은 유지한 채 나머지 분할 파일부터 재시도
 - `GET /admin/api/posts/export-jobs/:fileId/download` - 준비 완료된 게시물 Export 분할 ZIP 파일 다운로드
- `POST /admin/api/posts/import` - Export ZIP 파일 Import. multipart `file` 필드의 ZIP을 읽어 Markdown frontmatter를 게시물로 생성하고, ZIP 내부 `images/`·`files/` 자산을 새 업로드 URL로 재매핑한다.
+- `POST /admin/api/posts/import` - Export ZIP 파일 Import. multipart `file` 필드의 ZIP을 읽어 Markdown frontmatter를 게시물로 생성하고, ZIP 내부 `images/`·`files/` 자산을 새 업로드 URL로 재매핑한다. 응답은 `importedCount`, `assetCount`, `warningCount`, `warnings`, `posts`를 반환한다.
 - `GET /admin/api/pages` - 고정 페이지 목록
 - `POST /admin/api/pages` - 고정 페이지 작성
 - `GET /admin/api/pages/:id` - 고정 페이지 상세
@@ -698,7 +698,7 @@ components/content/
 ### 사이트 설정

 - 관리자 사이트 설정 UI는 `/admin/settings`에서 제공한다. Ghost Admin과 유사하게 **전체 화면**으로 표시하며, 좌측 내비와 우측 본문을 **한 덩어리로 중앙 정렬**(`max-w` 래퍼, 본문 카드 영역은 약 760px 상한)하고, 페이지 배경은 밝은 회색·본문 열은 흰색으로 구분한다. 우측 본문을 스크롤하면 현재 보이는 구역에 맞춰 좌측 메뉴 활성 배경을 갱신한다. **우측 상단 고정** 닫기 버튼과 `Escape` 키로 설정 화면을 닫으며, 브라우저 히스토리가 있으면 `뒤로 가기`, 없으면 `/admin`으로 이동한다. 타임존은 메뉴·안내 카드만 제공한다. 게시물 Import/Export 기본 화면은 `Export 요청`·`Import 하기` 액션 버튼과 최근 작업 목록을 중심으로 표시한다. Export 상세 설정은 `Export 요청` 버튼을 눌렀을 때만 펼쳐지며, 전체·특정년·특정월·직접 지정 범위 Export 요청, 목표 ZIP 용량과 ZIP당 최대 게시물 수 지정을 제공한다. Import 상세는 `Import 하기` 버튼을 눌렀을 때 안내 패널로 펼쳐진다. 최근 작업 목록은 진행도, 준비 완료 분할 파일 다운로드, 브라우저 순차 일괄 다운로드, 실패 작업 재시도, 실패 상세 오류, 완료·실패 작업 삭제를 표시하며 대기 중·생성 중 작업이 있으면 새 Export 요청 버튼을 비활성화한다. **스팸 필터**는 가입 금지 닉네임을 저장한다. **블로그 제목·설명** 카드는 기본적으로 사이트 이름·설명을 읽기 전용으로 보여 주고, `편집`을 눌렀을 때만 입력 필드·미리보기·저장/취소가 나타난다. 제목·설명 편집 중 `Escape`는 설정 닫기 대신 편집 취소로 동작한다. **POST 설정**·**어나운스 바**는 읽기 모드에서도 토글 UI를 비활성화 상태로 보여 주며, 켜짐 상태도 조작 가능한 활성 스위치처럼 보이지 않도록 낮은 대비와 `cursor-not-allowed`를 사용한다.
- 게시물 Import/Export 1차 포맷은 Obsidian 호환 백업 번들을 기준으로 한다. Export는 게시물마다 별도 폴더를 만들고, 폴더 안에 `제목.md` 메인 파일과 `images/`, `files/` 같은 자산 폴더를 함께 둔다. 본문은 기존 Markdown을 최대한 유지하되 `/uploads/...`로 연결된 내부 이미지·파일은 번들 안의 로컬 파일로 복사하고, Markdown 참조는 `./images/...` 또는 `./files/...` 같은 상대 경로로 재작성한다. 제목·슬러그·상태·발행일·요약·대표 이미지·SEO·태그는 YAML frontmatter에 저장한다. Import는 같은 구조의 ZIP을 읽어 frontmatter를 게시물 메타데이터로 복원하고, 로컬 자산은 `/uploads/posts/YYYY/MM/`에 새 파일로 저장한 뒤 본문 경로를 새 `/uploads/...` URL로 다시 매핑한다. 같은 슬러그가 이미 있으면 기존 글을 덮어쓰지 않고 `slug-2`, `slug-3`처럼 새 슬러그로 가져온다. 1회 Import는 최대 1000개 Markdown 게시물까지 처리한다.
+- 게시물 Import/Export 1차 포맷은 Obsidian 호환 백업 번들을 기준으로 한다. Export는 게시물마다 별도 폴더를 만들고, 폴더 안에 `제목.md` 메인 파일과 `images/`, `files/` 같은 자산 폴더를 함께 둔다. 본문은 기존 Markdown을 최대한 유지하되 `/uploads/...`로 연결된 내부 이미지·파일은 번들 안의 로컬 파일로 복사하고, Markdown 참조는 `./images/...` 또는 `./files/...` 같은 상대 경로로 재작성한다. 제목·슬러그·상태·발행일·요약·대표 이미지·SEO·태그는 YAML frontmatter에 저장한다. Import는 같은 구조의 ZIP을 읽어 frontmatter를 게시물 메타데이터로 복원하고, 로컬 자산은 `/uploads/posts/YYYY/MM/`에 새 파일로 저장한 뒤 본문 경로를 새 `/uploads/...` URL로 다시 매핑한다. 태그는 inline 배열(`tags: ["a"]`)과 Obsidian식 블록 배열(`tags:\n- a`)을 모두 읽는다. 같은 슬러그가 이미 있으면 기존 글을 덮어쓰지 않고 `slug-2`, `slug-3`처럼 새 슬러그로 가져온다. ZIP 안에서 자산을 찾지 못한 경우 Import는 계속 진행하되 응답 경고로 누락 경로를 알려 준다. 1회 Import는 최대 1000개 Markdown 게시물까지 처리한다.
 - 대용량 게시물 Export는 즉시 응답 다운로드가 아니라 백그라운드 작업으로 처리한다. 관리자가 Export를 요청하면 서버는 작업 레코드를 만들고, 게시물을 목표 zip 용량 기준으로 나누어 여러 zip 파일을 순차 생성한다. 계획 단계에서는 본문 문자열 바이트와 내부 `/uploads` 자산 파일 크기를 합산해 `max_file_size_bytes`를 넘기기 전에 새 분할 파일을 만들며, `chunk_size`는 한 ZIP에 들어갈 게시물 수의 안전 상한으로만 사용한다. 현재 구현은 요청 시 `post_export_jobs` 작업과 `post_export_files` 분할 파일 계획을 생성하고, 서버 프로세스 안에서 대기 작업을 순차 실행해 `processed_count`, `current_part_index`, `progress_message`, `started_at`을 갱신한다. Export 대상은 전체 또는 `COALESCE(published_at, created_at)` 기준 특정년·특정월·직접 지정 날짜 범위로 제한할 수 있다. 설정 화면은 대기 중·생성 중 작업이 있을 때 5초 간격으로 작업 목록을 새로고침한다. 파일명은 기본적으로 `사이트명_범위_시작번호-끝번호.zip` 형식을 사용한다(예: `sori.studio_2026-05_1-100.zip`). 각 zip에는 해당 범위 게시물 폴더와 자산 폴더가 들어가며, 준비 완료된 분할 파일은 관리자 다운로드 API로 받을 수 있다. 준비 완료 파일은 일괄 다운로드 버튼으로 브라우저에서 순차 다운로드할 수 있다. 실패 작업은 이미 준비된 파일을 유지하고 실패·대기 파일만 다시 생성하도록 재시도할 수 있으며, 실패 상세 로그는 작업 카드에서 확인한다. Resend 환경 변수가 설정되어 있으면 모든 분할 파일 생성 완료 후 요청 관리자 이메일로 알림을 보낸다. 완료·실패한 작업은 관리자가 즉시 삭제할 수 있고, 삭제 시 DB 레코드와 생성 ZIP 파일을 함께 정리한다. 서버 용량 보호를 위해 export 산출물 보존 기간은 최대 100일로 제한하며, 만료된 완료·실패 작업은 목록 조회나 새 요청 시 생성 ZIP 파일과 함께 자동 정리된다.
 - 사이트 설정은 `site_settings` 테이블의 단일 레코드로 관리한다.
 - 관리자는 사이트 이름, 설명, 사이트 URL, 로고 이미지, 저작권 문구를 수정할 수 있다.
--- a/docs/update.md
+++ b/docs/update.md
@@ -1,5 +1,11 @@
 # 업데이트 이력

+## v1.5.28
+
+- 게시물 Import: Obsidian에서 흔히 쓰는 YAML 블록 배열(`tags:\n- tag`) 형태를 읽을 수 있도록 frontmatter 파서 보강.
+- 게시물 Import: ZIP 내부에서 찾지 못한 자산을 조용히 무시하지 않고 Import 결과 경고로 반환하도록 수정.
+- 관리자 사이트 설정: Import 완료 후 누락 자산 등 경고 목록을 표시하도록 수정.
+
 ## v1.5.27

 - 게시물 Import: Export ZIP을 업로드해 Markdown frontmatter 기반 게시물로 복원하는 관리자 API 추가.
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
  "name": "sori.studio",
-  "version": "1.5.27",
+  "version": "1.5.28",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sori.studio",
-      "version": "1.5.27",
+      "version": "1.5.28",
      "hasInstallScript": true,
      "dependencies": {
        "@nuxtjs/tailwindcss": "^6.14.0",
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "sori.studio",
-  "version": "1.5.27",
+  "version": "1.5.28",
  "private": true,
  "type": "module",
  "imports": {
--- a/pages/admin/settings/index.vue
+++ b/pages/admin/settings/index.vue
@@ -2326,6 +2326,22 @@ onBeforeUnmount(() => {
                >
                  게시물 {{ postImportResult.importedCount }}개, 자산 {{ postImportResult.assetCount }}개를 가져왔습니다.
                </div>
+                <div
+                  v-if="postImportResult?.warningCount"
+                  class="rounded-md bg-[#fff8e8] px-3 py-2 text-sm text-[#8a5a00] ring-1 ring-inset ring-[#f0d28a]"
+                >
+                  <p class="font-semibold">
+                    경고 {{ postImportResult.warningCount }}개가 있습니다.
+                  </p>
+                  <ul class="mt-2 grid gap-1 text-xs leading-relaxed">
+                    <li
+                      v-for="warning in postImportResult.warnings"
+                      :key="warning"
+                    >
+                      {{ warning }}
+                    </li>
+                  </ul>
+                </div>
              </div>
            </div>

--- a/server/repositories/post-import-repository.js
+++ b/server/repositories/post-import-repository.js
@@ -146,6 +146,55 @@ const parseYamlValue = (value) => {
  return unquoteYamlString(trimmed)
 }

+/**
+ * Markdown frontmatter 줄을 키와 값으로 나눈다.
+ * @param {string} line - frontmatter 한 줄
+ * @returns {{ key: string, value: string } | null} 키와 값
+ */
+const parseFrontmatterLine = (line) => {
+  const match = String(line || '').match(/^([A-Za-z0-9_-]+):\s*(.*)$/)
+
+  if (!match) {
+    return null
+  }
+
+  return {
+    key: match[1].trim(),
+    value: match[2]
+  }
+}
+
+/**
+ * YAML 블록 배열 값을 수집한다.
+ * @param {Array<string>} lines - frontmatter 줄 목록
+ * @param {number} startIndex - 시작 인덱스
+ * @returns {{ values: Array<string>, nextIndex: number }} 수집 결과
+ */
+const collectYamlBlockArray = (lines, startIndex) => {
+  const values = []
+  let index = startIndex
+
+  while (index < lines.length) {
+    const line = lines[index]
+    const itemMatch = String(line || '').match(/^\s*-\s*(.*)$/)
+
+    if (!itemMatch) {
+      break
+    }
+
+    const value = unquoteYamlString(itemMatch[1])
+    if (value) {
+      values.push(value)
+    }
+    index += 1
+  }
+
+  return {
+    values,
+    nextIndex: index
+  }
+}
+
 /**
 * Markdown frontmatter와 본문을 분리한다.
 * @param {string} markdown - Markdown 문서
@@ -173,19 +222,26 @@ const parseMarkdownDocument = (markdown) => {
  const frontmatterText = normalized.slice(4, endIndex)
  const content = normalized.slice(endIndex + 4).replace(/^\n/, '')
  const frontmatter = {}
+  const lines = frontmatterText.split('\n')

-  for (const line of frontmatterText.split('\n')) {
-    const separatorIndex = line.indexOf(':')
-    if (separatorIndex < 0) {
+  for (let index = 0; index < lines.length; index += 1) {
+    const parsedLine = parseFrontmatterLine(lines[index])
+
+    if (!parsedLine) {
      continue
    }

-    const key = line.slice(0, separatorIndex).trim()
-    const value = line.slice(separatorIndex + 1)
+    const { key, value } = parsedLine
+    const trimmedValue = String(value || '').trim()

-    if (key) {
-      frontmatter[key] = parseYamlValue(value)
+    if (!trimmedValue && lines[index + 1]?.match(/^\s*-\s*/)) {
+      const blockArray = collectYamlBlockArray(lines, index + 1)
+      frontmatter[key] = blockArray.values
+      index = blockArray.nextIndex - 1
+      continue
    }
+
+    frontmatter[key] = parseYamlValue(value)
  }

  return {
@@ -271,7 +327,7 @@ const pickUniqueDiskFileName = async (directoryPath, originalName) => {
 * @param {Map<string, Buffer>} input.entryMap - ZIP 엔트리 맵
 * @param {string} input.postFolder - 게시물 폴더
 * @param {Set<string>} input.assetPaths - 자산 경로 목록
- * @returns {Promise<Map<string, string>>} 원본 경로별 새 URL
+ * @returns {Promise<{ replacements: Map<string, string>, missingAssets: Array<string> }>} 저장 결과
 */
 const saveImportAssets = async ({ entryMap, postFolder, assetPaths }) => {
  const now = new Date()
@@ -279,6 +335,7 @@ const saveImportAssets = async ({ entryMap, postFolder, assetPaths }) => {
  const month = String(now.getMonth() + 1).padStart(2, '0')
  const directoryPath = join(process.cwd(), 'public', 'uploads', 'posts', year, month)
  const replacements = new Map()
+  const missingAssets = []

  await mkdir(directoryPath, { recursive: true })

@@ -287,6 +344,7 @@ const saveImportAssets = async ({ entryMap, postFolder, assetPaths }) => {
    const data = entryMap.get(entryPath)

    if (!data) {
+      missingAssets.push(assetPath)
      continue
    }

@@ -301,7 +359,10 @@ const saveImportAssets = async ({ entryMap, postFolder, assetPaths }) => {
    replacements.set(`./${assetPath.replace(/^\.\//, '')}`, publicUrl)
  }

-  return replacements
+  return {
+    replacements,
+    missingAssets
+  }
 }

 /**
@@ -464,7 +525,7 @@ const collectMarkdownPosts = (entries) => entries
 /**
 * Export ZIP을 게시물로 가져온다.
 * @param {{ zipBuffer: Buffer, authorId: string }} input - Import 입력
- * @returns {Promise<{ importedCount: number, assetCount: number, posts: Array<Object> }>} Import 결과
+ * @returns {Promise<{ importedCount: number, assetCount: number, warningCount: number, warnings: Array<string>, posts: Array<Object> }>} Import 결과
 */
 export const importPostsFromExportZip = async ({ zipBuffer, authorId }) => {
  const entries = readZipBufferEntries(zipBuffer)
@@ -481,17 +542,21 @@ export const importPostsFromExportZip = async ({ zipBuffer, authorId }) => {

  const reservedSlugs = new Set()
  const importedPosts = []
+  const warnings = []
  let importedAssetCount = 0

  for (const markdownPost of markdownPosts) {
    const { frontmatter, content, postFolder } = markdownPost
    const assetPaths = collectImportAssetPaths({ frontmatter, content })
-    const replacements = await saveImportAssets({
+    const { replacements, missingAssets } = await saveImportAssets({
      entryMap,
      postFolder,
      assetPaths
    })
    importedAssetCount += replacements.size ? new Set(replacements.values()).size : 0
+    missingAssets.forEach((assetPath) => {
+      warnings.push(`${markdownPost.path}: ZIP 내부 자산을 찾지 못했습니다. (${assetPath})`)
+    })

    const title = String(frontmatter.title || basename(markdownPost.path).replace(MARKDOWN_EXTENSION_PATTERN, '') || 'Imported Post').trim()
    const slug = await createUniquePostSlug(frontmatter.slug || title, reservedSlugs)
@@ -525,6 +590,8 @@ export const importPostsFromExportZip = async ({ zipBuffer, authorId }) => {
  return {
    importedCount: importedPosts.length,
    assetCount: importedAssetCount,
+    warningCount: warnings.length,
+    warnings: warnings.slice(0, 20),
    posts: importedPosts.map((post) => ({
      id: post.id,
      title: post.title,
--- a/server/routes/admin/api/posts/import.post.js
+++ b/server/routes/admin/api/posts/import.post.js
@@ -7,7 +7,7 @@ const MAX_IMPORT_ZIP_BYTES = 300 * 1024 * 1024
 /**
 * 관리자 게시물 Import API
 * @param {import('h3').H3Event} event - 요청 이벤트
- * @returns {Promise<{ importedCount: number, assetCount: number, posts: Array<Object> }>} Import 결과
+ * @returns {Promise<{ importedCount: number, assetCount: number, warningCount: number, warnings: Array<string>, posts: Array<Object> }>} Import 결과
 */
 export default defineEventHandler(async (event) => {
  const adminSession = requireAdminSession(event)