태그 헤더 이미지 설정 추가

server/repositories/content-repository.js

@@ -94,6 +94,9 @@ const mapTagRow = (row) => ({
   name: row.name,
   slug: row.slug,
   description: row.description,
+  headerImageUrl: row.header_image_url || '',
+  headerTitle: row.header_title || '',
+  headerText: row.header_text || '',
   sortOrder: row.sort_order,
   color: row.color,
   tagType: row.tag_type || 'managed',
@@ -743,6 +746,9 @@ export const listTags = async ({ tagType, searchQuery = '', limit } = {}) => {
   if (!sql) {
     const sampleTags = getSampleTags().map((tag) => ({
       ...tag,
+      headerImageUrl: tag.headerImageUrl || '',
+      headerTitle: tag.headerTitle || '',
+      headerText: tag.headerText || '',
       tagType: 'managed',
       postCount: 0,
       lastUsedAt: null,
@@ -1327,8 +1333,8 @@ export const createAdminTag = async (input) => {
   }
 
   const rows = await sql`
-    INSERT INTO tags (name, slug, description, sort_order, color, tag_type)
-    VALUES (${input.name}, ${input.slug}, ${input.description}, ${input.sortOrder}, ${input.color}, ${input.tagType})
+    INSERT INTO tags (name, slug, description, header_image_url, header_title, header_text, sort_order, color, tag_type)
+    VALUES (${input.name}, ${input.slug}, ${input.description}, ${input.headerImageUrl}, ${input.headerTitle}, ${input.headerText}, ${input.sortOrder}, ${input.color}, ${input.tagType})
     RETURNING *
   `
 
@@ -1354,6 +1360,9 @@ export const updateAdminTag = async (id, input) => {
       name = ${input.name},
       slug = ${input.slug},
       description = ${input.description},
+      header_image_url = ${input.headerImageUrl},
+      header_title = ${input.headerTitle},
+      header_text = ${input.headerText},
       sort_order = ${input.sortOrder},
       color = ${input.color},
       tag_type = ${input.tagType},

server/routes/admin/api/tags/cover.post.js

@@ -0,0 +1,88 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { createError, readMultipartFormData } from 'h3'
+import sharp from 'sharp'
+import { requireAdminSession } from '../../../../utils/admin-auth'
+import { upsertMediaMetadataCategory } from '../../../../utils/media-library'
+
+const allowedImageTypes = new Set(['image/jpeg', 'image/png', 'image/webp'])
+const tagCoverWidth = 720
+
+/**
+ * 시스템 자산 파일명 접미사
+ * @returns {string} 파일명 접미사
+ */
+const createSystemAssetSuffix = () => {
+  const now = new Date()
+  const year = now.getFullYear()
+  const month = String(now.getMonth() + 1).padStart(2, '0')
+
+  return `${year}${month}-${Math.random().toString(36).slice(2, 8)}`
+}
+
+/**
+ * 태그 헤더 커버 이미지 업로드 API
+ * @param {import('h3').H3Event} event - 요청 이벤트
+ * @returns {Promise<{ headerImageUrl: string }>} 업로드된 이미지 URL
+ */
+export default defineEventHandler(async (event) => {
+  requireAdminSession(event)
+
+  const config = useRuntimeConfig()
+  const maxFileSize = Number(config.maxFileSize || 10485760)
+  const formData = await readMultipartFormData(event)
+  const file = (formData || []).find((part) => part.name === 'file' && part.filename)
+
+  if (!file) {
+    throw createError({
+      statusCode: 400,
+      message: '업로드할 태그 헤더 이미지가 없습니다.'
+    })
+  }
+
+  if (!allowedImageTypes.has(file.type)) {
+    throw createError({
+      statusCode: 400,
+      message: 'JPG, PNG, WebP 이미지만 태그 헤더로 사용할 수 있습니다.'
+    })
+  }
+
+  if (file.data.length > maxFileSize) {
+    throw createError({
+      statusCode: 413,
+      message: '업로드 가능한 파일 크기를 초과했습니다.'
+    })
+  }
+
+  const metadata = await sharp(file.data).metadata()
+  if (!metadata.width || !metadata.height) {
+    throw createError({
+      statusCode: 400,
+      message: '이미지 메타데이터를 읽을 수 없습니다.'
+    })
+  }
+
+  const uploadBaseUrl = String(config.uploadDir || '/uploads').replace(/\/+$/g, '') || '/uploads'
+  const publicBasePath = uploadBaseUrl.replace(/^\/+/, '')
+  const directoryPath = join(process.cwd(), 'public', publicBasePath, 'system')
+  const assetSuffix = createSystemAssetSuffix()
+  const coverFileName = `tag-cover-${assetSuffix}.webp`
+  const coverPath = join(directoryPath, coverFileName)
+  const headerImageUrl = `${uploadBaseUrl}/system/${coverFileName}`
+
+  await mkdir(directoryPath, { recursive: true })
+
+  const coverBuffer = await sharp(file.data)
+    .rotate()
+    .resize({
+      width: tagCoverWidth,
+      withoutEnlargement: true
+    })
+    .webp({ quality: 88 })
+    .toBuffer()
+
+  await writeFile(coverPath, coverBuffer)
+  await upsertMediaMetadataCategory(headerImageUrl, '시스템')
+
+  return { headerImageUrl }
+})

server/utils/admin-tag-input.js

@@ -4,6 +4,9 @@ export const adminTagInputSchema = z.object({
   name: z.string().trim().min(1),
   slug: z.string().trim().min(1).regex(/^[a-z0-9가-힣]+(?:-[a-z0-9가-힣]+)*$/),
   description: z.string().default(''),
+  headerImageUrl: z.string().trim().max(500).optional().default(''),
+  headerTitle: z.string().trim().max(120).optional().default(''),
+  headerText: z.string().trim().max(280).optional().default(''),
   sortOrder: z.number().int().min(0).default(0),
   color: z.string().trim().regex(/^#[0-9a-fA-F]{6}$/).default('#15171a'),
   tagType: z.enum(['managed', 'general']).default('managed')

server/utils/media-library.js

@@ -1,7 +1,7 @@
 import { readdir, rename, rm, stat } from 'node:fs/promises'
 import { basename, dirname, extname, join, relative } from 'node:path'
 import { createError } from 'h3'
-import { getSiteSettings, listAdminPosts, listPages } from '../repositories/content-repository'
+import { getSiteSettings, listAdminPosts, listAdminTags, listPages } from '../repositories/content-repository'
 import { getPostgresClient } from '../repositories/postgres-client'
 import {
   getPostThumbnailUrl,
@@ -506,17 +506,40 @@ const getMediaUsage = (url, posts, pages) => {
   return [...postUsages, ...pageUsages]
 }
 
+/**
+ * 태그 헤더 이미지 사용처 조회
+ * @param {string} url - 미디어 URL
+ * @param {Array<Object>} tags - 태그 목록
+ * @returns {Array<Object>} 사용처 목록
+ */
+const getTagMediaUsage = (url, tags) => tags
+  .filter((tag) => tag.headerImageUrl === url)
+  .map((tag) => ({
+    type: 'tag',
+    typeLabel: '태그',
+    id: tag.id,
+    title: tag.name,
+    slug: tag.slug,
+    adminUrl: `/admin/tags/${tag.id}`,
+    publicUrl: `/tag/${tag.slug}`,
+    status: tag.tagType,
+    location: 'headerImageUrl',
+    label: '태그 헤더 이미지'
+  }))
+
 /**
  * 미디어 URL이 실제 사용처에서 쓰이는지 조회한다.
  * @param {string} url - 미디어 URL
  * @param {Array<Object>} posts - 게시물 목록
  * @param {Array<Object>} pages - 페이지 목록
  * @param {Object} siteSettings - 사이트 설정
+ * @param {Array<Object>} tags - 태그 목록
  * @returns {Array<Object>} 사용처 목록
  */
-const getDirectMediaUsage = (url, posts, pages, siteSettings) => [
+const getDirectMediaUsage = (url, posts, pages, siteSettings, tags = []) => [
   ...getMediaUsage(url, posts, pages),
-  ...getSiteSettingsMediaUsage(url, siteSettings)
+  ...getSiteSettingsMediaUsage(url, siteSettings),
+  ...getTagMediaUsage(url, tags)
 ]
 
 /**
@@ -673,10 +696,11 @@ const getSiteSettingsMediaUsage = (url, siteSettings) => {
 export const listMediaItems = async () => {
   const items = await readMediaDirectory(uploadRoot)
   const metadataMap = await getMediaMetadataMap()
-  const [posts, pages, siteSettings] = await Promise.all([
+  const [posts, pages, siteSettings, tags] = await Promise.all([
     listAdminPosts(),
     listPages(),
-    getSiteSettings()
+    getSiteSettings(),
+    listAdminTags()
   ])
   const avatarOwnerByUrl = await getAvatarOwnersByUrls(items.map((item) => item.url))
   const itemUrlSet = new Set(items.map((item) => item.url))
@@ -685,7 +709,7 @@ export const listMediaItems = async () => {
     const rawCategory = metadataMap[item.url]?.category ?? item.category
     const category = normalizeStoredDisplayCategory(item.url, rawCategory)
     const avatarOwner = avatarOwnerByUrl.get(item.url) || null
-    const directUsage = getDirectMediaUsage(item.url, posts, pages, siteSettings)
+    const directUsage = getDirectMediaUsage(item.url, posts, pages, siteSettings, tags)
     const thumbnailUsage = getPostThumbnailMediaUsage(item.url, thumbnailOwnerByUrl, posts, pages, siteSettings)
     const originalUrl = thumbnailOwnerByUrl.get(item.url) || ''
 
@@ -818,13 +842,14 @@ export const updateMediaCategories = async (urls, category) => {
  * @returns {Promise<void>}
  */
 export const deleteMediaItem = async (url) => {
-  const [posts, pages, siteSettings] = await Promise.all([
+  const [posts, pages, siteSettings, tags] = await Promise.all([
     listAdminPosts(),
     listPages(),
-    getSiteSettings()
+    getSiteSettings(),
+    listAdminTags()
   ])
   const usage = [
-    ...getDirectMediaUsage(url, posts, pages, siteSettings),
+    ...getDirectMediaUsage(url, posts, pages, siteSettings, tags),
     ...getPostThumbnailMediaUsage(url, buildPostThumbnailOwnerMap(await readMediaDirectory(uploadRoot)), posts, pages, siteSettings)
   ]
 
@@ -860,13 +885,14 @@ export const renameMediaItem = async (url, name) => {
     })
   }
 
-  const [posts, pages, siteSettings] = await Promise.all([
+  const [posts, pages, siteSettings, tags] = await Promise.all([
     listAdminPosts(),
     listPages(),
-    getSiteSettings()
+    getSiteSettings(),
+    listAdminTags()
   ])
   const usage = [
-    ...getDirectMediaUsage(url, posts, pages, siteSettings),
+    ...getDirectMediaUsage(url, posts, pages, siteSettings, tags),
     ...getPostThumbnailMediaUsage(url, buildPostThumbnailOwnerMap(await readMediaDirectory(uploadRoot)), posts, pages, siteSettings)
   ]