릴리스: v0.1.41 커스텀 아이템 승격 연결 수정

backend/index.js

@@ -24,7 +24,7 @@ const allowedOrigins = (process.env.CORS_ORIGINS || '')
 
 const FileStore = FileStoreFactory(session)
 
-;['uploads/avatars', 'uploads/games', 'uploads/custom', '.sessions'].forEach((relativePath) => {
+;['uploads/avatars', 'uploads/games', 'uploads/custom', 'uploads/tierlists', '.sessions'].forEach((relativePath) => {
   fs.mkdirSync(path.join(__dirname, relativePath), { recursive: true })
 })
 
@@ -53,6 +53,7 @@ app.use(
       retries: 0,
     }),
     secret: SESSION_SECRET,
+    proxy: TRUST_PROXY > 0,
     resave: false,
     saveUninitialized: false,
     cookie: {

backend/src/db.js

@@ -72,6 +72,7 @@ function mapTierListRow(row) {
     authorAvatarSrc: row.avatar_src || '',
     gameId: row.game_id,
     title: row.title,
+    thumbnailSrc: row.thumbnail_src || '',
     description: row.description || '',
     isPublic: !!row.is_public,
     groups: parseJson(row.groups_json, []),
@@ -195,6 +196,7 @@ async function ensureSchema() {
         author_id VARCHAR(64) NOT NULL,
         game_id VARCHAR(120) NOT NULL,
         title VARCHAR(120) NOT NULL,
+        thumbnail_src VARCHAR(255) NOT NULL DEFAULT '',
         description TEXT NOT NULL,
         is_public TINYINT(1) NOT NULL DEFAULT 0,
         groups_json LONGTEXT NOT NULL,
@@ -209,6 +211,11 @@ async function ensureSchema() {
       ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
     `)
 
+    const tierListThumbnailColumns = await query("SHOW COLUMNS FROM tierlists LIKE 'thumbnail_src'")
+    if (!tierListThumbnailColumns.length) {
+      await query("ALTER TABLE tierlists ADD COLUMN thumbnail_src VARCHAR(255) NOT NULL DEFAULT '' AFTER title")
+    }
+
     await query(
       `
         INSERT INTO games (id, name, thumbnail_src, created_at)
@@ -397,6 +404,12 @@ async function createGameItem({ id, gameId, src, label }) {
   return mapGameItemRow(rows[0])
 }
 
+async function updateGameItemLabel(itemId, label) {
+  await query('UPDATE game_items SET label = ? WHERE id = ?', [label, itemId])
+  const rows = await query('SELECT id, game_id, src, label, created_at FROM game_items WHERE id = ? LIMIT 1', [itemId])
+  return mapGameItemRow(rows[0])
+}
+
 async function deleteGameItem(itemId) {
   const gameItemRows = await query('SELECT game_id FROM game_items WHERE id = ? LIMIT 1', [itemId])
   const gameId = gameItemRows[0]?.game_id
@@ -459,6 +472,28 @@ async function createCustomItem({ id, ownerId, src, label }) {
   return { id, ownerId, src, label, origin: 'custom', createdAt }
 }
 
+async function findCustomItemById(id) {
+  const rows = await query(
+    `
+      SELECT id, owner_id, src, label, created_at
+      FROM custom_items
+      WHERE id = ?
+      LIMIT 1
+    `,
+    [id]
+  )
+
+  const row = rows[0]
+  if (!row) return null
+  return {
+    id: row.id,
+    ownerId: row.owner_id,
+    src: row.src,
+    label: row.label,
+    createdAt: Number(row.created_at),
+  }
+}
+
 async function getCustomItemUsageMap() {
   const rows = await query('SELECT groups_json, pool_json FROM tierlists')
   const usageMap = new Map()
@@ -588,6 +623,7 @@ async function listPublicTierLists(gameId) {
         t.id,
         t.game_id,
         t.title,
+        t.thumbnail_src,
         t.created_at,
         t.updated_at,
         t.author_id,
@@ -607,6 +643,7 @@ async function listPublicTierLists(gameId) {
     id: row.id,
     gameId: row.game_id,
     title: row.title,
+    thumbnailSrc: row.thumbnail_src || '',
     createdAt: Number(row.created_at),
     updatedAt: Number(row.updated_at),
     authorId: row.author_id,
@@ -623,6 +660,7 @@ async function listUserTierLists(userId) {
         t.id,
         t.game_id,
         t.title,
+        t.thumbnail_src,
         t.created_at,
         t.updated_at,
         t.is_public,
@@ -641,6 +679,7 @@ async function listUserTierLists(userId) {
     id: row.id,
     gameId: row.game_id,
     title: row.title,
+    thumbnailSrc: row.thumbnail_src || '',
     createdAt: Number(row.created_at),
     updatedAt: Number(row.updated_at),
     isPublic: !!row.is_public,
@@ -658,6 +697,7 @@ async function findTierListById(id) {
         t.author_id,
         t.game_id,
         t.title,
+        t.thumbnail_src,
         t.description,
         t.is_public,
         t.groups_json,
@@ -708,17 +748,17 @@ async function deleteCustomItems(ids) {
   await query(`DELETE FROM custom_items WHERE id IN (${placeholders})`, ids)
 }
 
-async function saveTierList({ id, authorId, gameId, title, description, isPublic, groups, pool }) {
+async function saveTierList({ id, authorId, gameId, title, thumbnailSrc = '', description, isPublic, groups, pool }) {
   const existing = id ? await findTierListById(id) : null
 
   if (existing) {
     await query(
       `
         UPDATE tierlists
-        SET title = ?, description = ?, is_public = ?, groups_json = ?, pool_json = ?, updated_at = ?
+        SET title = ?, thumbnail_src = ?, description = ?, is_public = ?, groups_json = ?, pool_json = ?, updated_at = ?
         WHERE id = ?
       `,
-      [title, description || '', isPublic ? 1 : 0, serializeJson(groups), serializeJson(pool), now(), existing.id]
+      [title, thumbnailSrc, description || '', isPublic ? 1 : 0, serializeJson(groups), serializeJson(pool), now(), existing.id]
     )
     return findTierListById(existing.id)
   }
@@ -727,11 +767,11 @@ async function saveTierList({ id, authorId, gameId, title, description, isPublic
   await query(
     `
       INSERT INTO tierlists (
-        id, author_id, game_id, title, description, is_public, groups_json, pool_json, created_at, updated_at
+        id, author_id, game_id, title, thumbnail_src, description, is_public, groups_json, pool_json, created_at, updated_at
       )
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `,
-    [id, authorId, gameId, title, description || '', isPublic ? 1 : 0, serializeJson(groups), serializeJson(pool), createdAt, createdAt]
+    [id, authorId, gameId, title, thumbnailSrc, description || '', isPublic ? 1 : 0, serializeJson(groups), serializeJson(pool), createdAt, createdAt]
   )
   return findTierListById(id)
 }
@@ -755,10 +795,12 @@ module.exports = {
   createGame,
   updateGameThumbnail,
   createGameItem,
+  updateGameItemLabel,
   deleteGameItem,
   deleteGame,
   updateGameDisplayOrder,
   createCustomItem,
+  findCustomItemById,
   listCustomItems,
   findUnusedCustomItems,
   listPublicTierLists,

backend/src/routes/admin.js

@@ -12,10 +12,12 @@ const {
   listGames,
   updateGameThumbnail,
   createGameItem,
+  updateGameItemLabel,
   deleteGameItem,
   deleteGame,
   updateGameDisplayOrder,
   listCustomItems,
+  findCustomItemById,
   findUnusedCustomItems,
   findCustomItemsByIds,
   deleteCustomItems,
@@ -34,6 +36,18 @@ function buildUploadFilename(file) {
   return `${Date.now()}-${nanoid()}${safeExt}`
 }
 
+function buildItemLabelFromFilename(file) {
+  const originalName = file?.originalname || ''
+  const base = path.basename(originalName, path.extname(originalName))
+  const normalized = base
+    .replace(/[_-]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 60)
+
+  return normalized || 'item'
+}
+
 const upload = multer({
   storage: multer.diskStorage({
     destination: (req, file, cb) => cb(null, path.join(__dirname, '..', '..', 'uploads', 'games')),
@@ -74,20 +88,27 @@ router.post('/games/:gameId/thumbnail', requireAdmin, upload.single('thumbnail')
   res.json({ game: updated })
 })
 
-router.post('/games/:gameId/images', requireAdmin, upload.single('image'), async (req, res) => {
-  if (!req.file) return res.status(400).json({ error: 'file_required' })
-  const schema = z.object({ label: z.string().min(1).max(60) })
-  const parsed = schema.safeParse(req.body)
-  if (!parsed.success) return res.status(400).json({ error: 'bad_request' })
+router.post('/games/:gameId/images', requireAdmin, upload.array('images', 50), async (req, res) => {
+  const files = Array.isArray(req.files) ? req.files : []
+  if (!files.length) return res.status(400).json({ error: 'file_required' })
   const game = await findGameById(req.params.gameId)
   if (!game) return res.status(404).json({ error: 'not_found' })
-  const item = await createGameItem({
-    id: nanoid(),
-    gameId: game.id,
-    src: `/uploads/games/${req.file.filename}`,
-    label: parsed.data.label,
-  })
-  res.json({ item })
+
+  const manualLabel = typeof req.body?.label === 'string' ? req.body.label.trim() : ''
+  if (manualLabel && manualLabel.length > 60) return res.status(400).json({ error: 'bad_request' })
+
+  const items = await Promise.all(
+    files.map((file, index) =>
+      createGameItem({
+        id: nanoid(),
+        gameId: game.id,
+        src: `/uploads/games/${file.filename}`,
+        label: index === 0 && manualLabel ? manualLabel : buildItemLabelFromFilename(file),
+      })
+    )
+  )
+
+  res.json({ item: items[0], items })
 })
 
 router.delete('/games/:gameId/items/:itemId', requireAdmin, async (req, res) => {
@@ -97,6 +118,19 @@ router.delete('/games/:gameId/items/:itemId', requireAdmin, async (req, res) =>
   res.json({ ok: true })
 })
 
+router.patch('/games/:gameId/items/:itemId', requireAdmin, async (req, res) => {
+  const schema = z.object({ label: z.string().trim().min(1).max(60) })
+  const parsed = schema.safeParse(req.body)
+  if (!parsed.success) return res.status(400).json({ error: 'bad_request' })
+
+  const game = await findGameById(req.params.gameId)
+  if (!game) return res.status(404).json({ error: 'not_found' })
+
+  const updated = await updateGameItemLabel(req.params.itemId, parsed.data.label)
+  if (!updated || updated.gameId !== game.id) return res.status(404).json({ error: 'not_found' })
+  res.json({ item: updated })
+})
+
 router.delete('/games/:gameId', requireAdmin, async (req, res) => {
   const game = await findGameById(req.params.gameId)
   if (!game) return res.status(404).json({ error: 'not_found' })
@@ -141,6 +175,23 @@ async function removeCustomItemFiles(items) {
   )
 }
 
+async function promoteCustomItemToGameItem({ customItem, gameId }) {
+  const originalName = path.basename(customItem.src || '')
+  const nextFilename = buildUploadFilename({ originalname: originalName })
+  const sourcePath = path.join(__dirname, '..', '..', customItem.src.replace(/^\//, ''))
+  const targetRelativePath = path.join('uploads', 'games', nextFilename)
+  const targetPath = path.join(__dirname, '..', '..', targetRelativePath)
+
+  await fs.copyFile(sourcePath, targetPath)
+
+  return createGameItem({
+    id: nanoid(),
+    gameId,
+    src: `/${targetRelativePath.replace(/\\/g, '/')}`,
+    label: customItem.label,
+  })
+}
+
 router.delete('/custom-items/:itemId', requireAdmin, async (req, res) => {
   const result = await listCustomItems({ page: 1, limit: 200, orphanOnly: false })
   const target = result.items.find((item) => item.id === req.params.itemId)
@@ -153,6 +204,23 @@ router.delete('/custom-items/:itemId', requireAdmin, async (req, res) => {
   res.json({ ok: true })
 })
 
+router.post('/custom-items/:itemId/promote', requireAdmin, async (req, res) => {
+  const schema = z.object({
+    gameId: z.string().min(1),
+  })
+  const parsed = schema.safeParse(req.body)
+  if (!parsed.success) return res.status(400).json({ error: 'bad_request' })
+
+  const game = await findGameById(parsed.data.gameId)
+  if (!game) return res.status(404).json({ error: 'game_not_found' })
+
+  const customItem = await findCustomItemById(req.params.itemId)
+  if (!customItem) return res.status(404).json({ error: 'not_found' })
+
+  const item = await promoteCustomItemToGameItem({ customItem, gameId: game.id })
+  res.json({ item })
+})
+
 router.delete('/custom-items', requireAdmin, async (req, res) => {
   const schema = z.object({
     q: z.string().trim().max(120).optional().default(''),

backend/src/routes/auth.js

@@ -44,7 +44,11 @@ router.post('/signup', async (req, res) => {
 
   req.session.userId = user.id
   req.session.isAdmin = !!user.isAdmin
-  res.json(user)
+  // 세션을 응답 전에 명시적으로 저장해 Set-Cookie가 확실히 내려오도록 보강
+  req.session.save((err) => {
+    if (err) return res.status(500).json({ error: 'session_save_failed' })
+    res.json(user)
+  })
 })
 
 router.post('/login', async (req, res) => {
@@ -60,13 +64,16 @@ router.post('/login', async (req, res) => {
 
   req.session.userId = user.id
   req.session.isAdmin = !!user.isAdmin
-  res.json({
-    id: user.id,
-    email: user.email,
-    nickname: user.nickname || '',
-    isAdmin: !!user.isAdmin,
-    avatarSrc: user.avatarSrc || '',
-    createdAt: user.createdAt,
+  req.session.save((err) => {
+    if (err) return res.status(500).json({ error: 'session_save_failed' })
+    res.json({
+      id: user.id,
+      email: user.email,
+      nickname: user.nickname || '',
+      isAdmin: !!user.isAdmin,
+      avatarSrc: user.avatarSrc || '',
+      createdAt: user.createdAt,
+    })
   })
 })
 

backend/src/routes/tierlists.js

@@ -52,10 +52,19 @@ const upload = multer({
   limits: { fileSize: 6 * 1024 * 1024 },
 })
 
+const thumbnailUpload = multer({
+  storage: multer.diskStorage({
+    destination: (req, file, cb) => cb(null, path.join(__dirname, '..', '..', 'uploads', 'tierlists')),
+    filename: (req, file, cb) => cb(null, buildUploadFilename(file)),
+  }),
+  limits: { fileSize: 6 * 1024 * 1024 },
+})
+
 const tierListUpsertSchema = z.object({
   id: z.string().optional(),
   gameId: z.string().min(1),
   title: z.string().min(1).max(120),
+  thumbnailSrc: z.string().max(255).optional().default(''),
   description: z.string().max(1000).optional().default(''),
   isPublic: z.boolean().default(false),
   groups: z.array(
@@ -121,6 +130,11 @@ router.post('/custom-items', requireAuth, upload.single('image'), async (req, re
   res.json({ item })
 })
 
+router.post('/thumbnail', requireAuth, thumbnailUpload.single('thumbnail'), async (req, res) => {
+  if (!req.file) return res.status(400).json({ error: 'file_required' })
+  res.json({ thumbnailSrc: `/uploads/tierlists/${req.file.filename}` })
+})
+
 router.post('/', requireAuth, async (req, res) => {
   const parsed = tierListUpsertSchema.safeParse(req.body)
   if (!parsed.success) return res.status(400).json({ error: 'bad_request' })
@@ -137,6 +151,7 @@ router.post('/', requireAuth, async (req, res) => {
       authorId: existing.authorId,
       gameId: existing.gameId,
       title: payload.title,
+      thumbnailSrc: payload.thumbnailSrc || '',
       description: payload.description || '',
       isPublic: !!payload.isPublic,
       groups: payload.groups,
@@ -150,6 +165,7 @@ router.post('/', requireAuth, async (req, res) => {
     authorId: req.session.userId,
     gameId: payload.gameId,
     title: payload.title,
+    thumbnailSrc: payload.thumbnailSrc || '',
     description: payload.description || '',
     isPublic: !!payload.isPublic,
     groups: payload.groups,

docker-compose.prod.yml

@@ -14,10 +14,11 @@ services:
     volumes:
       - tmaker_mariadb_data:/var/lib/mysql
     healthcheck:
-      test: ["CMD-SHELL", "mariadb-admin ping -h 127.0.0.1 -u$$MARIADB_USER -p$$MARIADB_PASSWORD --silent"]
+      test: ["CMD-SHELL", "mariadb-admin ping -h 127.0.0.1 -uroot -p$$MARIADB_ROOT_PASSWORD --silent"]
+      start_period: 150s
       interval: 10s
       timeout: 5s
-      retries: 10
+      retries: 20
 
   backend:
     build:
@@ -55,7 +56,7 @@ services:
     depends_on:
       - backend
     ports:
-      - "8080:80"
+      - "18080:80"
 
   phpmyadmin:
     image: phpmyadmin:5.2-apache
@@ -71,7 +72,7 @@ services:
       PMA_USER: ${MARIADB_USER}
       PMA_PASSWORD: ${MARIADB_PASSWORD}
     ports:
-      - "8081:80"
+      - "18081:80"
 
 volumes:
   tmaker_mariadb_data:

docs/history.md

@@ -1,5 +1,20 @@
 # 의사결정 이력
 
+## 2026-03-26 v0.1.41
+- 관리자 커스텀 아이템 승격은 버튼만 보이는 상태로 끝나면 안 되므로, 프런트 API와 백엔드 라우트가 실제로 함께 연결되어야 기능이 완결된다고 정리했다.
+
+## 2026-03-26 v0.1.40
+- 관리자 기본 아이템 이름 저장은 눌러도 변화가 없으면 혼란스러우므로, 실제 변경이 있을 때만 버튼이 활성화되는 편이 더 명확하다고 판단했다.
+- 사용자 커스텀 이미지는 관리자 검토 후 특정 게임의 기본 템플릿으로 복제해 가져올 수 있어야 운영 효율이 높아지므로, 게임 선택 기반 승격 흐름을 추가하기로 결정했다.
+
+## 2026-03-26 v0.1.39
+- 티어표 편집 헤더는 게임명 kicker보다 제목과 설명이 더 중요하므로, 좌측 입력 중심 구조로 재배치하고 썸네일은 우측 보조 카드로 분리하는 편이 더 자연스럽다고 판단했다.
+- 썸네일 조작 버튼은 모바일에서도 카드와 함께 유지되는 편이 흐름이 덜 끊기므로, 미리보기 아래 별도 줄로 떨어뜨리기보다 카드 내부의 짧은 액션 행으로 묶기로 결정했다.
+
+## 2026-03-26 v0.1.38
+- 관리자 기본 아이템은 업로드 시점에만 이름을 정할 수 있으면 운영 중 수정이 어려우므로, 목록에서 직접 이름을 바꾸고 저장할 수 있게 하기로 결정했다.
+- 게임별 티어표 목록도 식별성이 중요하므로, 사용자가 편집 시 별도 썸네일을 지정할 수 있게 하고 목록 카드에서는 게임 카드와 비슷한 상단 썸네일 구조를 사용하기로 결정했다.
+
 ## 2026-03-19
 - 초기 저장소는 빠른 구현을 위해 `lowdb(JSON 파일)`를 채택했다.
 - 인증은 JWT 대신 서버 세션(`express-session` + `session-file-store`)을 사용했다.
@@ -102,3 +117,38 @@
 ## 2026-03-26 v0.1.27
 - NAS 운영은 리버스 프록시 설정을 단순하게 유지하는 편이 좋으므로, 프런트 컨테이너 하나만 외부 공개하고 `/api`, `/uploads`는 내부 프록시로 넘기는 구조를 채택했다.
 - 운영은 로컬 개발 컴포즈와 분리된 전용 `docker-compose.prod.yml`을 두고, 환경변수는 `.env.production`으로 분리해 관리하기로 결정했다.
+
+## 2026-03-26 v0.1.28
+- UGREEN NAS에서 MariaDB 초기화가 길게 걸릴 수 있으므로, healthcheck는 앱 계정보다 `root` 기준 ping과 더 긴 유예 시간으로 두는 편이 안전하다고 판단했다.
+
+## 2026-03-26 v0.1.29
+- NAS에서 HTTPS를 종료한 뒤 내부 컨테이너끼리는 HTTP로 통신하는 구조에서는, 프런트 프록시가 백엔드에 원래 프로토콜을 정확히 전달하지 않으면 `secure` 세션 쿠키가 발급되지 않는다고 판단했다.
+- 따라서 운영 프런트 Nginx는 백엔드 프록시 요청에 `X-Forwarded-Proto: https`를 명시하고, Express 세션도 프록시 환경을 명시적으로 신뢰하도록 설정하기로 결정했다.
+
+## 2026-03-26 v0.1.30
+- 운영 프런트는 다른 origin 절대 URL보다 같은 origin 상대 `/api` 요청을 우선해야 세션 쿠키 저장이 안정적이라고 판단했다.
+
+## 2026-03-26 v0.1.31
+- 세션 기반 로그인 응답은 저장소 반영 타이밍 차이를 줄이기 위해 `req.session.save()`를 명시 호출하는 쪽이 운영 안정성에 유리하다고 판단했다.
+
+## 2026-03-26 v0.1.32
+- 인증 문제를 빠르게 확인하기 위해 일시적으로 세션 저장 성공/실패 로그를 남기고 원인을 좁혀가는 접근을 선택했다.
+
+## 2026-03-26 v0.1.33
+- 프록시 환경의 실제 판단 값을 보기 위해 `req.secure`, `req.protocol`, `x-forwarded-proto`를 직접 로그로 비교해 원인을 확인하기로 했다.
+
+## 2026-03-26 v0.1.34
+- 일부 NAS 환경에서 `favicon.svg` 정적 응답이 `403`으로 차단될 수 있으므로, 운영 안정성을 위해 별도 파일 요청이 필요 없는 인라인 데이터 URL 파비콘으로 전환하기로 결정했다.
+- 관리자 기본 아이템 등록은 단일 파일 업로드만으로는 운영 부담이 크므로, 다중 선택과 드래그 앤 드롭을 지원하고 라벨은 파일명으로 자동 생성하는 방향을 채택했다.
+
+## 2026-03-26 v0.1.35
+- NAS 운영 경로는 수동 파일 복사보다 Git clone 기반이 로컬 개발 흐름과 더 잘 맞고, 실수로 누락되는 파일을 줄일 수 있으므로 기본 배포 방식으로 권장하기로 결정했다.
+- 운영 환경 변수와 Docker 볼륨은 Git 저장소 바깥의 NAS 자산으로 유지하고, 코드는 `git pull`로만 반영하는 역할 분리를 명확히 하기로 했다.
+
+## 2026-03-26 v0.1.36
+- 브라우저 탭 제목은 개발용 기본 문자열보다 서비스 이름을 직접 보여주는 편이 맞다고 판단해 `Tier Maker`로 고정했다.
+- 무제목 티어표 기본값은 날짜형 임시 제목보다 사용자가 어떤 게임으로 작성했는지 즉시 알 수 있는 게임명 기준이 더 자연스럽다고 판단했다.
+
+## 2026-03-26 v0.1.37
+- 운영 포트 충돌을 피하기 위해 프로덕션 외부 포트는 `frontend=18080`, `phpMyAdmin=18081`로 고정하고, 리버스 프록시 문서도 그 기준으로 맞추기로 했다.
+- 인증 장애 원인을 찾기 위한 디버그 로그는 문제 해결 후 제거하고, 실제 운영에는 세션 저장 보강과 프록시 헤더 설정만 유지하는 편이 낫다고 판단했다.

docs/map.md

@@ -7,13 +7,13 @@
 
 ## `/games/:gameId`
 - 화면 파일: `frontend/src/views/GameHubView.vue`
-- 역할: 선택한 게임 정보 표시, 공개 티어표 목록 표시, 작성자 닉네임 노출, 새 티어표 작성 진입
+- 역할: 선택한 게임 정보 표시, 공개 티어표 목록 표시, 티어표별 상단 썸네일/작성자 표시, 새 티어표 작성 진입
 - 연동 API: `GET /api/games/:gameId`, `GET /api/tierlists/public`
 
 ## `/editor/:gameId/new`, `/editor/:gameId/:tierListId`
 - 화면 파일: `frontend/src/views/TierEditorView.vue`
-- 역할: 티어 그룹 편집, 티어 행 추가/삭제, 관리자 아이템/커스텀 아이템 다중 드래그 앤 드롭 업로드, 작성 권한 제어, 저장, 공개 여부 설정, PNG 다운로드
-- 연동 API: `GET /api/games/:gameId`, `GET /api/tierlists/:id`, `POST /api/tierlists/custom-items`, `POST /api/tierlists`
+- 역할: 티어 그룹 편집, 티어 행 추가/삭제, 관리자 아이템/커스텀 아이템 다중 드래그 앤 드롭 업로드, 티어표 썸네일 선택, 작성 권한 제어, 저장, 공개 여부 설정, PNG 다운로드
+- 연동 API: `GET /api/games/:gameId`, `GET /api/tierlists/:id`, `POST /api/tierlists/thumbnail`, `POST /api/tierlists/custom-items`, `POST /api/tierlists`
 
 ## `/login`
 - 화면 파일: `frontend/src/views/LoginView.vue`
@@ -22,13 +22,13 @@
 
 ## `/me`
 - 화면 파일: `frontend/src/views/MyTierListsView.vue`
-- 역할: 내 티어표 목록 조회, 편집 화면으로 이동, 작성자 본인 티어표 삭제
+- 역할: 내 티어표 목록 조회, 상단 썸네일 카드 표시, 편집 화면으로 이동, 작성자 본인 티어표 삭제
 - 연동 API: `GET /api/tierlists/me`, `DELETE /api/tierlists/:id`
 
 ## `/admin`
 - 화면 파일: `frontend/src/views/AdminView.vue`
-- 역할: `게임 관리 / 아이템 관리 / 회원 관리` 탭 분리, 선택된 게임의 썸네일/기본 아이템 관리, 사용자 커스텀 아이템 검색/페이지네이션/사용 횟수 확인/미사용 이미지 개별·일괄 삭제, 회원 비밀번호 초기화 포함 회원 관리, 파일 입력 초기화, 아이템 삭제, 게임 삭제
-- 연동 API: `POST /api/admin/games`, `POST /api/admin/games/:gameId/thumbnail`, `POST /api/admin/games/:gameId/images`, `GET /api/admin/custom-items`, `DELETE /api/admin/custom-items/:itemId`, `DELETE /api/admin/custom-items`, `GET /api/admin/users`, `PATCH /api/admin/users/:userId`, `PATCH /api/admin/users/:userId/password`, `DELETE /api/admin/users/:userId`, `DELETE /api/admin/games/:gameId/items/:itemId`, `DELETE /api/admin/games/:gameId`
+- 역할: `게임 관리 / 아이템 관리 / 회원 관리` 탭 분리, 선택된 게임의 썸네일 관리, 기본 아이템 다중 드래그 앤 드롭 업로드, 기본 아이템 이름 수정, 사용자 커스텀 아이템 검색/페이지네이션/사용 횟수 확인/미사용 이미지 개별·일괄 삭제, 사용자 커스텀 아이템의 기본 템플릿 승격, 회원 비밀번호 초기화 포함 회원 관리, 파일 입력 초기화, 아이템 삭제, 게임 삭제
+- 연동 API: `POST /api/admin/games`, `POST /api/admin/games/:gameId/thumbnail`, `POST /api/admin/games/:gameId/images`, `PATCH /api/admin/games/:gameId/items/:itemId`, `GET /api/admin/custom-items`, `POST /api/admin/custom-items/:itemId/promote`, `DELETE /api/admin/custom-items/:itemId`, `DELETE /api/admin/custom-items`, `GET /api/admin/users`, `PATCH /api/admin/users/:userId`, `PATCH /api/admin/users/:userId/password`, `DELETE /api/admin/users/:userId`, `DELETE /api/admin/games/:gameId/items/:itemId`, `DELETE /api/admin/games/:gameId`
 
 ## `/profile`
 - 화면 파일: `frontend/src/views/ProfileView.vue`

docs/spec.md

@@ -7,6 +7,8 @@
 - 세션 저장소: `session-file-store` 기반 파일 세션
 - 업로드 저장소: 로컬 파일 시스템(`backend/uploads/`)
 - 운영 배포: `frontend(Nginx 정적 서빙 + /api,/uploads 프록시) + backend + mariadb` Docker Compose 구조
+- NAS HTTPS 리버스 프록시 운영 시 프런트 Nginx는 백엔드로 `X-Forwarded-Proto: https`를 전달하고, Express 세션은 프록시 환경에서 `secure` 쿠키를 허용하도록 설정한다.
+- 프런트 파비콘은 운영 정적 파일 차단 영향을 줄이기 위해 `index.html`의 인라인 데이터 URL로 제공한다.
 
 ## 데이터 저장 구조
 - 메인 데이터베이스: MariaDB `tier_cursor` (기본값)
@@ -49,6 +51,7 @@
   - `authorId`: string
   - `gameId`: string
   - `title`: string
+  - `thumbnailSrc`: string
   - `description`: string
   - `isPublic`: boolean
   - `groups`: `{ id, name, itemIds[] }[]`
@@ -76,13 +79,17 @@
   - `GET /api/tierlists/me`
   - `GET /api/tierlists/:id`
   - `DELETE /api/tierlists/:id`
+  - `POST /api/tierlists/thumbnail`
   - `POST /api/tierlists/custom-items`
   - `POST /api/tierlists`
 - 관리자
   - `POST /api/admin/games`
   - `POST /api/admin/games/:gameId/thumbnail`
   - `POST /api/admin/games/:gameId/images`
+    - 여러 이미지를 한 번에 업로드할 수 있고, 별도 라벨이 없으면 파일명 기준으로 기본 아이템 이름을 만든다.
+  - `PATCH /api/admin/games/:gameId/items/:itemId`
   - `GET /api/admin/custom-items`
+  - `POST /api/admin/custom-items/:itemId/promote`
   - `DELETE /api/admin/custom-items/:itemId`
   - `DELETE /api/admin/custom-items`
   - `GET /api/admin/users`
@@ -94,11 +101,14 @@
 
 ## 관리자 화면 메모
 - 썸네일은 16:9 비율 미리보기 후 `썸네일 적용` 버튼으로 실제 반영한다.
-- 게임 기본 아이템 추가는 이름 입력, 파일 선택, 1:1 미리보기 확인 뒤 저장하는 흐름이다.
+- 게임 기본 아이템 추가는 드래그 앤 드롭 또는 다중 파일 선택으로 처리하고, 미리보기 카드에서 여러 장을 함께 확인할 수 있다.
+- 현재 기본 아이템 목록에서는 등록된 아이템 이름을 직접 수정하고 저장할 수 있다.
+- 기본 아이템 이름 저장 버튼은 값이 실제로 바뀐 경우에만 활성화된다.
 - 아이템 미리보기는 반응형 환경에서도 최대 `192px` 크기 안에서 표시한다.
 - 게임 전환 또는 업로드 성공 뒤에는 파일 입력값을 초기화해 같은 파일도 다시 선택할 수 있다.
 - 게임 관리 탭에서는 홈 화면 상단에 먼저 노출할 게임을 최대 50개까지 지정하고, 드래그 또는 위/아래 버튼으로 순서를 저장할 수 있다.
 - 사용자 업로드 커스텀 아이템은 관리자 화면의 아이템 관리 탭에서 검색, 페이지네이션, 다운로드할 수 있다.
+- 사용자 커스텀 아이템은 선택한 게임의 기본 템플릿으로 복제해 가져올 수 있다.
 - 커스텀 아이템은 사용 횟수(`usageCount`)를 표시하며, 미사용 항목만 필터링해 개별/일괄 삭제할 수 있다.
 - 관리자 화면에서는 회원 이메일/닉네임/권한 수정, 비밀번호 초기화, 계정 삭제가 가능하다.
 
@@ -108,8 +118,10 @@
 - 커스텀 이미지 추가는 다중 파일 선택과 드래그 앤 드롭을 모두 지원한다.
 - 티어 행은 기본 5단으로 시작하지만, 사용자가 직접 추가하거나 제거할 수 있다.
 - 신규 티어표의 공개 여부 기본값은 `ON`이며, 기존 티어표는 편집 화면과 `내 티어표` 목록에서 직접 삭제할 수 있다.
-- 제목이 비어 있는 상태로 저장하면 내부 제목은 `이름 없음 + 날짜` 형식으로 자동 생성한다.
+- 제목이 비어 있는 상태로 저장하면 내부 제목은 현재 게임명을 기본값으로 사용한다.
 - 제목 입력이 비어 있는 동안에는 무분별한 도배 방지를 위한 관리자 임의 삭제 가능성 안내 문구를 표시한다.
+- 티어표는 편집 화면에서 16:9 썸네일 이미지를 별도로 선택해 저장할 수 있고, 목록 카드에서는 그 이미지를 상단 대표 썸네일로 사용한다.
+- 편집 화면 상단 헤더는 좌측 제목/설명, 우측 썸네일 카드 구조를 사용하며 모바일에서는 한 열로 접힌다.
 - 티어표 편집기의 아이콘 기본 크기는 `80px`이며, 사용자가 `48 / 60 / 80 / 100 / 120` 단계로 즉시 조절할 수 있다.
 - 공개 티어표 목록과 `내 티어표` 목록은 제목 옆에 작성자 아바타와 표시명을 함께 보여준다.
 - 작성자 아바타 이미지가 없을 경우 목록 썸네일 fallback은 닉네임이 아니라 계정명 기준 첫 글자를 사용한다.
@@ -141,8 +153,9 @@
 
 ## 운영 배포 메모
 - 프로덕션 컴포즈 파일은 [docker-compose.prod.yml](/Users/bicute/Desktop/zenn.dev/tier-cursor/docker-compose.prod.yml)이다.
-- 외부 도메인 `tmaker.sori.studio`는 `frontend` 컨테이너의 `8080` 포트로 리버스 프록시하고, `/api`, `/uploads`, `/health`는 프런트 Nginx가 내부 `backend:5179`로 전달한다.
+- 외부 도메인 `tmaker.sori.studio`는 `frontend` 컨테이너의 `18080` 포트로 리버스 프록시하고, `/api`, `/uploads`, `/health`는 프런트 Nginx가 내부 `backend:5179`로 전달한다.
 - 운영 볼륨은 MariaDB 데이터, 업로드 파일, 세션 파일을 각각 분리해 유지한다.
+- MariaDB healthcheck는 NAS 첫 기동 지연을 고려해 `root` 기준 ping과 긴 `start_period/retries`를 사용한다.
 
 ## NAS 배포 메모
 - 현재 구조는 MariaDB/MySQL 계열이므로 NAS에 MariaDB를 올리면 phpMyAdmin 또는 Adminer로 직접 데이터 확인이 가능하다.

docs/todo.md

@@ -5,6 +5,9 @@
 - 회원 관리에서 아바타/작성 티어표 수/최근 활동 같은 보조 정보는 아직 표시하지 않는다.
 - 미사용 커스텀 이미지 일괄 삭제는 현재 "참조가 없는 항목" 기준이며, 보관 기간 정책 같은 운영 규칙은 아직 없다.
 - 업로드 이미지는 현재 원본 파일을 그대로 저장하므로, 운영 부담이 커지면 서버 저장 전 리사이즈/압축(예: 긴 변 제한, WebP 변환) 도입이 필요하다.
+- 관리자 기본 아이템 다중 업로드는 현재 파일명 기반 자동 라벨만 지원하므로, 필요하면 업로드 후 일괄 라벨 수정/정렬 UX를 추가 검토한다.
+- 티어표 썸네일은 현재 업로드/교체만 지원하므로, 필요하면 자동 썸네일 추출이나 업로드 이미지 크롭 UX를 추가 검토한다.
+- 사용자 커스텀 아이템 승격은 현재 수동 복제 방식이므로, 필요하면 중복 감지나 “비슷한 항목 추천” 같은 보조 UX를 검토한다.
 
 ## 배포 전 작업
 - NAS 실제 도메인 기준으로 `VITE_API_ORIGIN`, `CORS_ORIGINS`, `SESSION_SECRET`, `SESSION_COOKIE_SECURE`, `TRUST_PROXY` 값을 설정한다.

docs/ugreen-nas-deploy.md

@@ -17,6 +17,37 @@
 - NAS 작업 폴더에 현재 프로젝트를 그대로 업로드한다.
 - 기존 로컬 MariaDB 내용은 무시하고 새 운영 DB로 시작해도 된다.
 
+## 1-1. 권장 방식: Git clone 기반 운영
+- 수동 복사는 처음 1회에는 가능하지만, 이후부터는 로컬과 NAS가 쉽게 어긋난다.
+- 권장 방식은 NAS 작업 폴더를 Git 저장소로 두고, 로컬에서 작업 후 `push`, NAS에서는 `pull`만 하는 구조다.
+- 추천 흐름:
+  - 로컬: 개발 → 테스트 → 커밋 → `git push`
+  - NAS: `git pull` → `docker compose up -d --build`
+
+처음부터 Git으로 시작하려면 NAS에서:
+
+```bash
+cd /volume1/docker/projects/apps
+git clone https://git.sori.studio/zenn/tier-maker.git
+cd tier-maker
+cp .env.production.example .env.production
+```
+
+- 이미 같은 경로에 수동 복사본이 있다면, 가장 깔끔한 방법은 기존 폴더를 다른 이름으로 잠시 옮기고 새로 `clone`하는 것이다.
+- `.env.production`은 Git에 올리지 않고 NAS에만 유지한다.
+
+예시:
+
+```bash
+cd /volume1/docker/projects/apps
+mv tier-maker tier-maker-manual-backup
+git clone https://git.sori.studio/zenn/tier-maker.git
+cd tier-maker
+cp .env.production.example .env.production
+```
+
+- 이후 기존 수동 복사본의 `.env.production` 값을 새 clone 폴더의 `.env.production`에 그대로 옮기면 된다.
+
 ## 2. 환경변수 파일 준비
 - 루트에서 `.env.production.example`를 복사해 `.env.production`으로 만든다.
 - 최소 변경값:
@@ -46,18 +77,56 @@ docker compose --env-file .env.production -f docker-compose.prod.yml up -d --bui
 docker compose --env-file .env.production -f docker-compose.prod.yml --profile admin up -d --build
 ```
 
+- MariaDB 첫 초기화는 NAS 환경에서 2분 이상 걸릴 수 있다.
+- 현재 프로덕션 컴포즈는 이를 고려해 `start_period: 150s`, `retries: 20` healthcheck를 사용한다.
+- 로그상 DB가 정상 기동했는데도 `unhealthy`가 뜬 적이 있다면 최신 `docker-compose.prod.yml`로 다시 올리는 것이 좋다.
+
+## 3-1. 이후 업데이트 방식
+- Git clone 기반으로 전환한 뒤에는 파일을 하나씩 NAS에 덮어쓰지 않는다.
+- 로컬에서 커밋과 푸시가 끝난 뒤, NAS에서는 아래 두 줄이 기본 배포 절차다.
+
+```bash
+git pull origin main
+docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build
+```
+
+- Dockerfile, Nginx 설정, 프런트 소스, 백엔드 소스가 바뀐 경우에는 `--build`를 유지한다.
+- 단순 재시작만 필요할 때도 있지만, 운영에서는 실수 방지를 위해 `up -d --build`를 기본값으로 두는 편이 안전하다.
+
+## 3-2. 이번 v0.1.34까지 적용하는 예시
+- 이미 NAS 폴더가 Git clone 상태라면:
+
+```bash
+cd /volume1/docker/projects/apps/tier-maker
+git pull origin main
+sudo docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build
+```
+
+- 아직 수동 복사 폴더만 있다면:
+
+```bash
+cd /volume1/docker/projects/apps
+mv tier-maker tier-maker-manual-backup
+git clone https://git.sori.studio/zenn/tier-maker.git
+cd tier-maker
+cp .env.production.example .env.production
+# 여기서 기존 .env.production 값을 새 파일에 옮긴다.
+docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build
+```
+
 ## 4. NAS 리버스 프록시
 - 외부 도메인: `tmaker.sori.studio`
 - 내부 대상 프로토콜: `http`
 - 내부 대상 호스트: NAS IP 또는 `localhost`
-- 내부 대상 포트: `8080`
+- 내부 대상 포트: `18080`
 
-즉 NAS 리버스 프록시는 `frontend` 컨테이너의 `8080`만 바라보면 된다.
+즉 NAS 리버스 프록시는 `frontend` 컨테이너의 `18080`만 바라보면 된다.
 
 ## 5. HTTPS / 쿠키
 - 현재 프로덕션 컴포즈는 `SESSION_COOKIE_SECURE=true`를 사용한다.
 - 따라서 `tmaker.sori.studio`에는 HTTPS 인증서가 연결되어 있어야 한다.
-- NAS 리버스 프록시가 HTTPS 종료를 하고 내부는 `http://frontend:80` 또는 `localhost:8080`으로 전달하면 된다.
+- NAS 리버스 프록시가 HTTPS 종료를 하고 내부는 `http://frontend:80` 또는 `localhost:18080`으로 전달하면 된다.
+- 최신 프런트 Nginx 설정은 백엔드로 `X-Forwarded-Proto: https`를 넘기므로, 로그인 직후 세션이 바로 풀리는 경우에는 프런트 이미지를 다시 빌드해 최신 설정이 반영됐는지 먼저 확인한다.
 
 ## 6. 데이터 위치
 - MariaDB 데이터: Docker volume `tmaker_mariadb_data`
@@ -67,12 +136,25 @@ docker compose --env-file .env.production -f docker-compose.prod.yml --profile a
 ## 7. 점검 포인트
 - 메인 접속: `https://tmaker.sori.studio`
 - 헬스체크: `https://tmaker.sori.studio/health`
+- 로그인 후 새로고침 또는 `내 티어표` 진입 시 세션이 유지되는지 확인
 - 관리자 로그인 후:
   - 게임 생성
   - 썸네일 업로드
   - 티어표 저장
   - 이미지 다운로드
 
-## 8. 참고
+## 8. MariaDB가 unhealthy일 때
+- 로그에 `ready for connections`가 보이면 DB 자체는 정상일 가능성이 높다.
+- 이 경우는 대부분 healthcheck 시간이 짧아서 생기는 문제다.
+- 최신 컴포즈 파일 반영 후 아래 순서로 다시 시작한다:
+
+```bash
+docker compose --env-file .env.production -f docker-compose.prod.yml down -v
+docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build
+```
+
+## 9. 참고
 - 현재 업로드 이미지는 서버 저장 전에 리사이즈/압축하지 않는다.
 - 운영 중 원본 이미지가 많이 쌓이면 이후 `sharp` 기반 최적화 단계를 추가하는 것이 좋다.
+- 프런트/백엔드/Nginx 설정을 바꿨다면 NAS에서 `docker compose --env-file .env.production -f docker-compose.prod.yml up -d --build`로 이미지를 다시 빌드해 반영한다.
+- 운영 중 `.env.production`, 업로드 파일 볼륨, MariaDB 볼륨은 Git과 별개로 NAS 로컬 자산이므로 백업 정책을 따로 잡아야 한다.

docs/update.md

@@ -1,5 +1,57 @@
 # 업데이트 로그
 
+## 2026-03-26 v0.1.41
+- **커스텀 아이템 승격 연결 수정**: 관리자 아이템 관리의 `기본 템플릿에 추가` 버튼이 실제 API와 백엔드 승격 라우트로 연결되도록 누락된 프런트/백엔드 구현을 보완
+
+## 2026-03-26 v0.1.40
+- **기본 아이템 저장 UX 보강**: 관리자 게임 관리에서 아이템 이름이 실제로 바뀐 경우에만 `이름 저장` 버튼이 활성화되도록 조정하고, 저장 중 상태를 버튼에 표시
+- **커스텀 아이템 승격 추가**: 관리자 아이템 관리에서 사용자 커스텀 이미지를 선택한 게임의 기본 템플릿으로 복제해 가져올 수 있도록 API와 UI를 추가
+
+## 2026-03-26 v0.1.39
+- **에디터 헤더 재구성**: 티어표 편집 상단에서 게임명 kicker를 제거하고, 좌측 제목/설명 입력과 우측 썸네일 카드가 나란히 보이는 구조로 재정리
+- **썸네일 영역 UX 개선**: 썸네일 미리보기와 선택/제거 버튼을 하나의 카드 안에 묶고, 모바일에서도 버튼이 카드 아래로 무너지지 않도록 밀도 있게 조정
+
+## 2026-03-26 v0.1.38
+- **관리자 기본 아이템 이름 수정 추가**: 게임 관리 화면의 현재 기본 아이템 목록에서 이름을 직접 수정하고 저장할 수 있도록 API와 UI를 보강
+- **티어표 썸네일 추가**: 티어표 편집 화면에서 별도 썸네일 이미지를 선택해 저장할 수 있도록 업로드 흐름을 추가하고, 게임별 공개 티어표/내 티어표 목록은 게임 카드처럼 상단 썸네일 + 하단 제목/작성자 정보 카드 구조로 변경
+
+## 2026-03-26 v0.1.37
+- **운영 포트 설정 반영**: 프로덕션 컴포즈의 `frontend/phpMyAdmin` 외부 포트를 `18080/18081` 기준으로 유지하고, NAS 배포 문서와 기술 명세의 리버스 프록시 포트 안내도 동일하게 정리
+- **인증 라우트 정리**: NAS 로그인 문제를 확인하기 위해 넣었던 `auth` 디버그 로그를 제거하고, 실제 운영에 필요한 세션 저장 보강만 유지
+- **이력 문서 정렬**: `docs/history.md`를 날짜/버전 흐름에 맞게 다시 정리해 추적성을 높임
+
+## 2026-03-26 v0.1.36
+- **브라우저 탭 이름 변경**: 프런트 문서 제목을 `frontend`에서 `Tier Maker`로 변경
+- **무제목 티어표 기본값 조정**: 사용자가 제목을 입력하지 않으면 `이름 없음 + 날짜` 대신 현재 게임명을 기본 제목으로 사용하도록 변경하고, 관리자 임의 삭제 안내 문구는 유지
+
+## 2026-03-26 v0.1.35
+- **NAS Git 배포 절차 추가**: UGREEN NAS에서 수동 복사 대신 `git clone`과 `git pull` 기반으로 운영 배포를 관리하는 절차를 배포 가이드에 정리
+- **v0.1.34 반영 명령 정리**: 이미 수동 복사본이 있는 경우 새 clone으로 전환한 뒤 최신 이미지를 다시 빌드하는 순서를 문서화
+
+## 2026-03-26 v0.1.34
+- **파비콘 정적 요청 제거**: 운영 환경에서 `/favicon.svg`가 `403`으로 막히는 경우를 피하기 위해, 별도 파일 대신 `index.html` 인라인 데이터 URL 파비콘으로 전환
+- **관리자 기본 아이템 다중 업로드 추가**: 게임 관리 화면에서 기본 아이템을 여러 장 드래그 앤 드롭 또는 다중 파일 선택으로 한 번에 추가할 수 있도록 변경하고, 기본 라벨은 파일명 기준으로 자동 생성
+
+## 2026-03-26 v0.1.33
+- **[NAS] 요청 프로토콜 디버그**: `auth/login`/`auth/me`에서 `req.secure`, `req.protocol`, `x-forwarded-proto` 값을 로그로 출력해 프록시/HTTPS 판단 문제를 확인
+
+## 2026-03-26 v0.1.32
+- **[NAS] 인증 디버그 로그 추가**: `auth/login`에서 `req.session.save` 성공/실패와 `auth/me`에서 세션 존재 여부를 콘솔 로그로 남겨 세션 쿠키 발급 문제를 빠르게 진단
+
+## 2026-03-26 v0.1.31
+- **[NAS] 세션 쿠키 발급 강제**: 백엔드 인증 라우트에서 `req.session.save()`를 명시 호출해 응답 전에 세션을 저장하고 `Set-Cookie`가 확실히 내려오도록 보강
+
+## 2026-03-26 v0.1.30
+- **[NAS] /api 상대경로 호출**: 운영(`import.meta.env.PROD`)에서는 `http://localhost:...` 같은 다른 origin으로 API를 호출하지 않도록, `frontend/src/lib/runtime.js`에서 `/api` 호출을 상대경로로 고정해 세션 쿠키가 정상 저장되도록 수정
+
+## 2026-03-26 v0.1.29
+- **NAS 로그인 유지 수정**: 프런트 Nginx가 백엔드에 전달하는 `X-Forwarded-Proto`를 `https`로 고정하고 Express 세션의 프록시 인지를 명시해, NAS HTTPS 리버스 프록시 뒤에서도 `secure` 세션 쿠키가 정상 발급되도록 조정
+- **운영 템플릿 복구**: 실수로 빠질 수 있는 `.env.production.example`를 다시 포함하고, NAS 재배포 시 최신 프런트 이미지를 다시 빌드하도록 문서 보강
+
+## 2026-03-26 v0.1.28
+- **MariaDB healthcheck 완화**: UGREEN NAS 첫 초기화 시간이 길어도 `unhealthy`로 오판하지 않도록 프로덕션 컴포즈의 DB healthcheck를 `root` 기준과 더 긴 `start_period/retries`로 조정
+- **NAS 장애 대응 문서화**: `ready for connections` 이후에도 `unhealthy`가 뜨는 경우의 재기동 절차를 배포 가이드에 추가
+
 ## 2026-03-26 v0.1.27
 - **UGREEN NAS 배포 파일 추가**: `backend`, `frontend`용 Dockerfile과 프런트 Nginx 프록시 설정, 프로덕션 전용 `docker-compose.prod.yml` 추가
 - **운영 환경 예시 추가**: `.env.production.example`로 MariaDB/세션 시크릿 환경변수 템플릿 제공

frontend/index.html

@@ -2,9 +2,12 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link
+      rel="icon"
+      href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' rx='16' fill='%230b1220'/%3E%3Cpath d='M18 18h28v8H36v20h-8V26H18z' fill='%23f8fafc'/%3E%3C/svg%3E"
+    />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>frontend</title>
+    <title>Tier Maker</title>
   </head>
   <body>
     <div id="app"></div>

frontend/nginx.conf

@@ -15,7 +15,7 @@ server {
     proxy_set_header Host $host;
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-Proto https;
   }
 
   location /uploads/ {
@@ -24,7 +24,7 @@ server {
     proxy_set_header Host $host;
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-Proto https;
   }
 
   location /health {
@@ -33,6 +33,6 @@ server {
     proxy_set_header Host $host;
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-Proto https;
   }
 }

frontend/src/App.vue

@@ -58,7 +58,7 @@ async function logout() {
     <header class="app-header">
       <div class="brand" @click="$router.push('/')">
         <span class="brand__title">Tier Maker</span>
-        <span class="brand__sub">Vue</span>
+        <span class="brand__sub">by zenn</span>
       </div>
       <nav class="nav">
         <RouterLink to="/" class="nav__link">게임</RouterLink>

frontend/src/lib/api.js

@@ -33,10 +33,14 @@ export const api = {
   listGames: () => request('/api/games'),
   getGame: (gameId) => request(`/api/games/${encodeURIComponent(gameId)}`),
   updateAdminGameDisplayOrder: (payload) => request('/api/admin/games/display-order', { method: 'PATCH', body: payload }),
+  updateAdminGameItem: (gameId, itemId, payload) =>
+    request(`/api/admin/games/${encodeURIComponent(gameId)}/items/${encodeURIComponent(itemId)}`, { method: 'PATCH', body: payload }),
   listAdminCustomItems: ({ q = '', page = 1, limit = 50, orphanOnly = false } = {}) =>
     request(
       `/api/admin/custom-items?q=${encodeURIComponent(q)}&page=${encodeURIComponent(page)}&limit=${encodeURIComponent(limit)}&orphanOnly=${encodeURIComponent(orphanOnly)}`
     ),
+  promoteAdminCustomItem: (itemId, payload) =>
+    request(`/api/admin/custom-items/${encodeURIComponent(itemId)}/promote`, { method: 'POST', body: payload }),
   listAdminUsers: () => request('/api/admin/users'),
   updateAdminUser: (userId, payload) =>
     request(`/api/admin/users/${encodeURIComponent(userId)}`, { method: 'PATCH', body: payload }),
@@ -50,6 +54,23 @@ export const api = {
   getTierList: (id) => request(`/api/tierlists/${encodeURIComponent(id)}`),
   deleteTierList: (id) => request(`/api/tierlists/${encodeURIComponent(id)}`, { method: 'DELETE' }),
   saveTierList: (payload) => request('/api/tierlists', { method: 'POST', body: payload }),
+  uploadTierListThumbnail: async (file) => {
+    const fd = new FormData()
+    fd.append('thumbnail', file)
+    const res = await fetch(toApiUrl('/api/tierlists/thumbnail'), {
+      method: 'POST',
+      credentials: 'include',
+      body: fd,
+    })
+    const data = await res.json()
+    if (!res.ok) {
+      const err = new Error('request_failed')
+      err.status = res.status
+      err.data = data
+      throw err
+    }
+    return data
+  },
   deleteAdminCustomItem: (itemId) => request(`/api/admin/custom-items/${encodeURIComponent(itemId)}`, { method: 'DELETE' }),
   deleteAdminUnusedCustomItems: ({ q = '' } = {}) =>
     request(`/api/admin/custom-items?q=${encodeURIComponent(q)}`, { method: 'DELETE' }),

frontend/src/lib/runtime.js

@@ -3,7 +3,12 @@ const FALLBACK_API_ORIGIN = 'http://localhost:5179'
 export const API_ORIGIN = (import.meta.env.VITE_API_ORIGIN || FALLBACK_API_ORIGIN).replace(/\/+$/, '')
 
 export function toApiUrl(path = '') {
-  if (!path) return API_ORIGIN
+  const p = path.startsWith('/') ? path : `/${path}`
+
+  // 운영(Nginx 프록시)에서는 같은 도메인/프로토콜로 호출해야
+  // 세션 쿠키(`Set-Cookie`)가 브라우저에 정상 저장됩니다.
+  if (import.meta.env.PROD) return p
+
   if (/^https?:\/\//.test(path)) return path
-  return `${API_ORIGIN}${path.startsWith('/') ? path : `/${path}`}`
+  return `${API_ORIGIN}${p}`
 }

frontend/src/style.css

@@ -172,7 +172,7 @@ code {
 }
 
 #app {
-  width: 1126px;
+  /* width: 1126px; */
   max-width: 100%;
   margin: 0 auto;
   text-align: center;

frontend/src/views/AdminView.vue

@@ -22,6 +22,7 @@ const customItemPage = ref(1)
 const customItemLimit = ref(50)
 const customItemTotal = ref(0)
 const customItemOrphanOnly = ref(false)
+const customItemTargetGameId = ref('')
 
 const users = ref([])
 
@@ -31,10 +32,10 @@ const success = ref('')
 const newGameId = ref('')
 const newGameName = ref('')
 
-const uploadLabel = ref('')
-const uploadFile = ref(null)
+const uploadFiles = ref([])
 const thumbFile = ref(null)
-const itemPreviewUrl = ref('')
+const itemPreviewUrls = ref([])
+const isItemDragOver = ref(false)
 const thumbPreviewUrl = ref('')
 const itemFileInput = ref(null)
 const thumbFileInput = ref(null)
@@ -43,7 +44,7 @@ const featuredSortable = ref(null)
 
 const hasSelectedGame = computed(() => !!selectedGame.value?.game?.id)
 const canApplyThumbnail = computed(() => !!thumbFile.value && !!selectedGameId.value)
-const canAddItem = computed(() => !!uploadFile.value && !!selectedGameId.value)
+const canAddItem = computed(() => uploadFiles.value.length > 0 && !!selectedGameId.value)
 const customItemPageCount = computed(() => Math.max(1, Math.ceil(customItemTotal.value / customItemLimit.value)))
 const featuredGames = computed(() =>
   featuredGameIds.value
@@ -72,12 +73,18 @@ function resetMessages() {
 function setTab(tab) {
   resetMessages()
   activeTab.value = tab
+  if (tab === 'items' && !customItemTargetGameId.value && games.value.length) {
+    customItemTargetGameId.value = games.value[0].id
+  }
 }
 
 async function refreshGames() {
   try {
     const data = await api.listGames()
     games.value = data.games || []
+    if (!customItemTargetGameId.value && games.value.length) {
+      customItemTargetGameId.value = games.value[0].id
+    }
     featuredGameIds.value = games.value
       .filter((game) => game.displayRank != null)
       .sort((a, b) => a.displayRank - b.displayRank)
@@ -151,8 +158,7 @@ async function refreshUsers() {
 }
 
 function resetUploadState() {
-  uploadLabel.value = ''
-  uploadFile.value = null
+  uploadFiles.value = []
   thumbFile.value = null
   resetFileInput('item')
   resetFileInput('thumb')
@@ -171,9 +177,9 @@ function setGameMode(mode) {
 }
 
 function clearPreviewUrl(type) {
-  if (type === 'item' && itemPreviewUrl.value) {
-    URL.revokeObjectURL(itemPreviewUrl.value)
-    itemPreviewUrl.value = ''
+  if (type === 'item' && itemPreviewUrls.value.length) {
+    itemPreviewUrls.value.forEach((url) => URL.revokeObjectURL(url))
+    itemPreviewUrls.value = []
   }
   if (type === 'thumb' && thumbPreviewUrl.value) {
     URL.revokeObjectURL(thumbPreviewUrl.value)
@@ -197,7 +203,13 @@ async function loadGame() {
 
   try {
     const data = await api.getGame(selectedGameId.value)
-    selectedGame.value = data
+    selectedGame.value = {
+      ...data,
+      items: (data.items || []).map((item) => ({
+        ...item,
+        draftLabel: item.label,
+      })),
+    }
   } catch (e) {
     error.value = '게임 정보를 불러오지 못했어요.'
   }
@@ -232,9 +244,46 @@ function onThumb(event) {
 }
 
 function onFile(event) {
-  uploadFile.value = event.target.files && event.target.files[0] ? event.target.files[0] : null
+  handleItemFiles(event.target.files)
+}
+
+function handleItemFiles(fileList) {
+  const files = Array.from(fileList || []).filter((file) => (file.type || '').startsWith('image/'))
+  uploadFiles.value = files
   clearPreviewUrl('item')
-  if (uploadFile.value) itemPreviewUrl.value = URL.createObjectURL(uploadFile.value)
+  if (!files.length) return
+  itemPreviewUrls.value = files.map((file) => URL.createObjectURL(file))
+  resetFileInput('item')
+}
+
+function openItemFilePicker() {
+  itemFileInput.value?.click()
+}
+
+function clearItemFiles() {
+  uploadFiles.value = []
+  clearPreviewUrl('item')
+  resetFileInput('item')
+}
+
+function onItemDragEnter(event) {
+  event.preventDefault()
+  isItemDragOver.value = true
+}
+
+function onItemDragOver(event) {
+  event.preventDefault()
+  isItemDragOver.value = true
+}
+
+function onItemDragLeave(event) {
+  if (event.currentTarget === event.target) isItemDragOver.value = false
+}
+
+function onItemDrop(event) {
+  event.preventDefault()
+  isItemDragOver.value = false
+  handleItemFiles(event.dataTransfer?.files)
 }
 
 async function uploadThumbnail() {
@@ -267,15 +316,15 @@ async function uploadThumbnail() {
 
 async function uploadItem() {
   resetMessages()
-  if (!uploadFile.value || !selectedGameId.value) {
+  if (!uploadFiles.value.length || !selectedGameId.value) {
     error.value = '아이템 파일을 선택해주세요.'
     return
   }
 
   try {
     const fd = new FormData()
-    fd.append('label', uploadLabel.value || 'item')
-    fd.append('image', uploadFile.value)
+    uploadFiles.value.forEach((file) => fd.append('images', file))
+    const uploadCount = uploadFiles.value.length
     const res = await fetch(toApiUrl(`/api/admin/games/${encodeURIComponent(selectedGameId.value)}/images`), {
       method: 'POST',
       credentials: 'include',
@@ -285,7 +334,7 @@ async function uploadItem() {
 
     resetUploadState()
     await loadGame()
-    success.value = '게임 기본 아이템이 추가됐어요.'
+    success.value = `게임 기본 아이템 ${uploadCount}개 추가를 완료했어요.`
   } catch (e) {
     error.value = '아이템 추가 실패(관리자 권한/파일 크기 확인)'
   }
@@ -310,6 +359,29 @@ async function removeGameItem(itemId) {
   }
 }
 
+async function saveGameItemLabel(item) {
+  resetMessages()
+  if (!selectedGameId.value) return
+  const nextLabel = (item.draftLabel || '').trim()
+  if (!nextLabel) {
+    error.value = '아이템 이름을 입력해주세요.'
+    return
+  }
+  if (nextLabel === item.label) return
+
+  try {
+    item.isSavingLabel = true
+    const data = await api.updateAdminGameItem(selectedGameId.value, item.id, { label: nextLabel })
+    item.label = data.item.label
+    item.draftLabel = data.item.label
+    success.value = '기본 아이템 이름을 수정했어요.'
+  } catch (e) {
+    error.value = '기본 아이템 이름 수정에 실패했어요.'
+  } finally {
+    item.isSavingLabel = false
+  }
+}
+
 async function removeGame() {
   resetMessages()
   if (!selectedGameId.value || !selectedGame.value?.game) return
@@ -446,6 +518,26 @@ async function removeUnusedCustomItems() {
   }
 }
 
+async function promoteCustomItem(item) {
+  resetMessages()
+  if (!customItemTargetGameId.value) {
+    error.value = '가져올 게임을 먼저 선택해주세요.'
+    return
+  }
+
+  try {
+    item.isPromoting = true
+    await api.promoteAdminCustomItem(item.id, { gameId: customItemTargetGameId.value })
+    const targetGameName = games.value.find((game) => game.id === customItemTargetGameId.value)?.name || customItemTargetGameId.value
+    if (selectedGameId.value === customItemTargetGameId.value) await loadGame()
+    success.value = `"${item.label}" 아이템을 ${targetGameName} 기본 템플릿으로 추가했어요.`
+  } catch (e) {
+    error.value = '커스텀 아이템을 기본 템플릿으로 가져오지 못했어요.'
+  } finally {
+    item.isPromoting = false
+  }
+}
+
 const displayThumbnailUrl = computed(() => {
   if (thumbPreviewUrl.value) return thumbPreviewUrl.value
   if (selectedGame.value?.game?.thumbnailSrc) return toApiUrl(selectedGame.value.game.thumbnailSrc)
@@ -631,16 +723,36 @@ async function saveFeaturedOrder() {
                 <div class="section__title">기본 아이템 추가</div>
                 <div class="itemComposer">
                   <div class="itemComposer__form">
-                    <input v-model="uploadLabel" class="input input--compact" placeholder="아이템 이름" />
-                    <input ref="itemFileInput" type="file" accept="image/*" class="inputFile inputFile--tight" @change="onFile" />
-                    <button class="btn" :disabled="!canAddItem" @click="uploadItem">아이템 추가</button>
+                    <input ref="itemFileInput" type="file" accept="image/*" multiple class="srOnlyInput" @change="onFile" />
+                    <div
+                      class="dropZone"
+                      :class="{ 'dropZone--active': isItemDragOver }"
+                      @dragenter="onItemDragEnter"
+                      @dragover="onItemDragOver"
+                      @dragleave="onItemDragLeave"
+                      @drop="onItemDrop"
+                    >
+                      <div class="dropZone__title">이미지를 드래그해서 기본 아이템으로 추가</div>
+                      <div class="dropZone__desc">여러 파일을 한 번에 올릴 수 있고, 저장 라벨은 파일명으로 자동 생성됩니다.</div>
+                      <div class="dropZone__actions">
+                        <button class="btn btn--ghost btn--small" type="button" @click="openItemFilePicker">파일 선택</button>
+                        <button class="btn btn--danger btn--small" type="button" :disabled="!uploadFiles.length" @click="clearItemFiles">선택 비우기</button>
+                      </div>
+                    </div>
+                    <button class="btn" :disabled="!canAddItem" @click="uploadItem">
+                      아이템 {{ uploadFiles.length || 0 }}개 추가
+                    </button>
                   </div>
                   <div class="itemPreviewCard">
-                    <div class="itemPreviewFrame">
-                      <img v-if="itemPreviewUrl" class="itemPreviewImage" :src="itemPreviewUrl" alt="item preview" />
-                      <div v-else class="itemPreviewEmpty">이미지를 선택해주세요</div>
+                    <div v-if="itemPreviewUrls.length" class="itemPreviewGrid">
+                      <div v-for="(previewUrl, index) in itemPreviewUrls.slice(0, 6)" :key="previewUrl" class="itemPreviewFrame">
+                        <img class="itemPreviewImage" :src="previewUrl" :alt="uploadFiles[index]?.name || 'item preview'" />
+                      </div>
+                    </div>
+                    <div v-else class="itemPreviewEmpty">선택한 기본 아이템 미리보기가 여기에 표시됩니다.</div>
+                    <div class="thumbLabel thumbLabel--preview">
+                      {{ uploadFiles.length ? `선택된 파일 ${uploadFiles.length}개` : '아직 선택된 파일이 없어요.' }}
                     </div>
-                    <div class="thumbLabel thumbLabel--preview">{{ uploadLabel || '아이템 이름 미리보기' }}</div>
                   </div>
                 </div>
               </section>
@@ -652,8 +764,17 @@ async function saveFeaturedOrder() {
               <div v-else class="thumbGrid">
                 <div v-for="item in selectedGame.items" :key="item.id" class="thumbCard">
                   <img class="thumb thumb--game" :src="toApiUrl(item.src)" :alt="item.label" />
-                  <div class="thumbLabel">{{ item.label }}</div>
-                  <button class="btn btn--danger btn--small" @click="removeGameItem(item.id)">아이템 삭제</button>
+                  <input v-model="item.draftLabel" class="input input--labelEdit" placeholder="아이템 이름" />
+                  <div class="thumbCard__actions">
+                    <button
+                      class="btn btn--ghost btn--small"
+                      :disabled="item.isSavingLabel || !item.draftLabel?.trim() || item.draftLabel.trim() === item.label"
+                      @click="saveGameItemLabel(item)"
+                    >
+                      {{ item.isSavingLabel ? '저장중...' : '이름 저장' }}
+                    </button>
+                    <button class="btn btn--danger btn--small" @click="removeGameItem(item.id)">아이템 삭제</button>
+                  </div>
                 </div>
               </div>
             </div>
@@ -680,6 +801,10 @@ async function saveFeaturedOrder() {
             </div>
 
             <div class="toolbar toolbar--secondary">
+              <select v-model="customItemTargetGameId" class="select toolbar__select">
+                <option value="">가져올 게임 선택</option>
+                <option v-for="game in games" :key="game.id" :value="game.id">{{ game.name }}</option>
+              </select>
               <label class="checkRow checkRow--toolbar">
                 <input v-model="customItemOrphanOnly" type="checkbox" @change="toggleCustomItemOrphanOnly" />
                 <span>미사용 커스텀 이미지만 보기</span>
@@ -701,6 +826,9 @@ async function saveFeaturedOrder() {
                   <div class="customItemCard__meta">{{ fmt(item.createdAt) }}</div>
                   <div class="customItemCard__actions">
                     <a class="btn btn--small btn--ghost" :href="toApiUrl(item.src)" :download="item.label">이미지 다운로드</a>
+                    <button class="btn btn--small btn--ghost" :disabled="!customItemTargetGameId || item.isPromoting" @click="promoteCustomItem(item)">
+                      {{ item.isPromoting ? '추가중...' : '기본 템플릿에 추가' }}
+                    </button>
                     <button class="btn btn--small btn--danger" :disabled="item.usageCount > 0" @click="removeCustomItem(item)">개별 삭제</button>
                   </div>
                 </div>
@@ -955,7 +1083,7 @@ async function saveFeaturedOrder() {
   align-items: end;
 }
 .toolbar--secondary {
-  grid-template-columns: minmax(0, 1fr) auto;
+  grid-template-columns: auto minmax(0, 1fr) auto;
   align-items: center;
 }
 .toolbar__search,
@@ -991,6 +1119,9 @@ async function saveFeaturedOrder() {
 .input--compact {
   max-width: 320px;
 }
+.input--labelEdit {
+  margin-top: 10px;
+}
 .hint {
   margin-top: 10px;
   opacity: 0.78;
@@ -1006,6 +1137,17 @@ async function saveFeaturedOrder() {
 .inputFile--tight {
   margin-top: 0;
 }
+.srOnlyInput {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
 .btn {
   font-size: 12px;
   margin-top: 12px;
@@ -1090,20 +1232,53 @@ async function saveFeaturedOrder() {
   gap: 12px;
   align-items: start;
 }
+.dropZone {
+  padding: 18px;
+  border-radius: 16px;
+  border: 1px dashed rgba(255, 255, 255, 0.2);
+  background: rgba(255, 255, 255, 0.03);
+  transition:
+    border-color 0.16s ease,
+    background 0.16s ease,
+    transform 0.16s ease;
+}
+.dropZone--active {
+  border-color: rgba(96, 165, 250, 0.56);
+  background: rgba(96, 165, 250, 0.08);
+  transform: translateY(-1px);
+}
+.dropZone__title {
+  font-weight: 900;
+}
+.dropZone__desc {
+  margin-top: 8px;
+  font-size: 13px;
+  opacity: 0.74;
+  line-height: 1.5;
+}
+.dropZone__actions {
+  margin-top: 12px;
+  display: flex;
+  gap: 10px;
+  flex-wrap: wrap;
+}
 .itemPreviewCard {
   padding: 10px;
   border-radius: 14px;
   border: 1px solid rgba(255, 255, 255, 0.12);
   background: rgba(255, 255, 255, 0.04);
 }
+.itemPreviewGrid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 10px;
+}
 .itemPreviewFrame {
-  width: min(100%, 192px);
   aspect-ratio: 1 / 1;
   border-radius: 12px;
   overflow: hidden;
   border: 1px solid rgba(255, 255, 255, 0.12);
   background: rgba(0, 0, 0, 0.18);
-  margin: 0 auto;
 }
 .itemPreviewImage {
   width: 100%;
@@ -1111,12 +1286,13 @@ async function saveFeaturedOrder() {
   object-fit: cover;
 }
 .itemPreviewEmpty {
-  width: 100%;
-  height: 100%;
+  min-height: 192px;
   display: grid;
   place-items: center;
   color: rgba(255, 255, 255, 0.62);
   font-size: 13px;
+  text-align: center;
+  line-height: 1.5;
 }
 .thumbGrid {
   margin-top: 12px;
@@ -1150,6 +1326,11 @@ async function saveFeaturedOrder() {
   opacity: 0.9;
   word-break: break-word;
 }
+.thumbCard__actions {
+  margin-top: 10px;
+  display: grid;
+  gap: 8px;
+}
 .thumbLabel--preview {
   text-align: center;
 }
@@ -1188,7 +1369,7 @@ async function saveFeaturedOrder() {
 }
 .customItemCard__actions {
   display: grid;
-  grid-template-columns: repeat(2, minmax(0, 1fr));
+  grid-template-columns: repeat(3, minmax(0, 1fr));
   gap: 10px;
   margin-top: 4px;
 }
@@ -1281,8 +1462,11 @@ async function saveFeaturedOrder() {
   .itemComposer {
     grid-template-columns: 1fr;
   }
+  .toolbar--secondary {
+    grid-template-columns: 1fr;
+  }
   .itemPreviewCard {
-    max-width: 192px;
+    max-width: none;
   }
 }
 @media (max-width: 640px) {

frontend/src/views/GameHubView.vue

@@ -37,6 +37,10 @@ function avatarFallbackOf(tierList) {
   return (tierList.authorAccountName || 'u').trim().charAt(0).toUpperCase() || '?'
 }
 
+function tierListThumbnailUrl(tierList) {
+  return tierList.thumbnailSrc ? toApiUrl(tierList.thumbnailSrc) : ''
+}
+
 onMounted(async () => {
   try {
     const [gameRes, listRes] = await Promise.all([api.getGame(gameId.value), api.listPublicTierLists(gameId.value)])
@@ -78,6 +82,10 @@ function openTierList(id) {
     <div v-if="tierLists.length === 0" class="empty">아직 공개 티어표가 없어요.</div>
     <div v-else class="list">
       <button v-for="t in tierLists" :key="t.id" class="row" @click="openTierList(t.id)">
+        <div class="row__thumbWrap">
+          <img v-if="tierListThumbnailUrl(t)" class="row__thumb" :src="tierListThumbnailUrl(t)" :alt="t.title" />
+          <div v-else class="row__thumbPlaceholder"></div>
+        </div>
         <div class="row__head">
           <div class="row__title">{{ t.title }}</div>
           <div class="row__author">
@@ -153,7 +161,7 @@ function openTierList(id) {
 }
 .row {
   text-align: left;
-  padding: 14px;
+  padding: 0;
   border-radius: 16px;
   border: 1px solid rgba(255, 255, 255, 0.12);
   background: rgba(255, 255, 255, 0.04);
@@ -164,10 +172,28 @@ function openTierList(id) {
   gap: 10px;
   align-content: start;
   min-height: 168px;
+  overflow: hidden;
 }
 .row:hover {
   background: rgba(255, 255, 255, 0.05);
 }
+.row__thumbWrap {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  background: rgba(255, 255, 255, 0.03);
+}
+.row__thumb {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+.row__thumbPlaceholder {
+  width: 100%;
+  height: 100%;
+  background:
+    linear-gradient(135deg, rgba(255,255,255,0.06), rgba(255,255,255,0.02));
+}
 .row__title {
   font-weight: 800;
   min-width: 0;
@@ -175,6 +201,7 @@ function openTierList(id) {
   line-height: 1.35;
 }
 .row__head {
+  padding: 14px 14px 0;
   display: grid;
   gap: 12px;
   align-content: start;
@@ -202,6 +229,7 @@ function openTierList(id) {
   font-weight: 900;
 }
 .row__meta {
+  padding: 0 14px 14px;
   opacity: 0.78;
   font-size: 13px;
   margin-top: auto;

frontend/src/views/MyTierListsView.vue

@@ -30,6 +30,10 @@ function avatarFallbackOf(tierList) {
   return (tierList.authorAccountName || 'u').trim().charAt(0).toUpperCase() || '?'
 }
 
+function tierListThumbnailUrl(tierList) {
+  return tierList.thumbnailSrc ? toApiUrl(tierList.thumbnailSrc) : ''
+}
+
 onMounted(async () => {
   try {
     const data = await api.listMyTierLists()
@@ -68,6 +72,10 @@ async function removeList(t) {
       <div v-else class="list">
         <article v-for="t in myLists" :key="t.id" class="row">
           <button class="row__body" @click="openList(t)">
+            <div class="row__thumbWrap">
+              <img v-if="tierListThumbnailUrl(t)" class="row__thumb" :src="tierListThumbnailUrl(t)" :alt="t.title" />
+              <div v-else class="row__thumbPlaceholder"></div>
+            </div>
             <div class="row__head">
               <div class="row__title">{{ t.title }}</div>
               <div class="row__author">
@@ -125,18 +133,17 @@ async function removeList(t) {
 }
 .list {
   display: grid;
-  gap: 10px;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 14px;
 }
 .row {
-  display: flex;
+  display: grid;
   gap: 10px;
-  justify-content: space-between;
-  align-items: center;
-  padding: 12px 14px;
   border-radius: 14px;
   border: 1px solid rgba(255, 255, 255, 0.10);
   background: rgba(0, 0, 0, 0.16);
   color: rgba(255, 255, 255, 0.92);
+  overflow: hidden;
 }
 .row__body {
   flex: 1 1 auto;
@@ -147,12 +154,32 @@ async function removeList(t) {
   background: transparent;
   color: inherit;
   padding: 0;
+  display: grid;
+  gap: 10px;
+}
+.row__thumbWrap {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  background: rgba(255, 255, 255, 0.03);
+}
+.row__thumb {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+.row__thumbPlaceholder {
+  width: 100%;
+  height: 100%;
+  background:
+    linear-gradient(135deg, rgba(255,255,255,0.06), rgba(255,255,255,0.02));
 }
 .row__title {
   font-weight: 900;
   min-width: 0;
 }
 .row__head {
+  padding: 0 14px;
   display: flex;
   gap: 12px;
   align-items: center;
@@ -181,6 +208,7 @@ async function removeList(t) {
   font-weight: 900;
 }
 .row__meta {
+  padding: 0 14px;
   margin-top: 6px;
   opacity: 0.76;
   font-size: 13px;
@@ -188,5 +216,16 @@ async function removeList(t) {
 .link--danger {
   background: rgba(239, 68, 68, 0.14);
   border-color: rgba(239, 68, 68, 0.28);
+  margin: 0 14px 14px;
+}
+@media (max-width: 1100px) {
+  .list {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+@media (max-width: 720px) {
+  .list {
+    grid-template-columns: 1fr;
+  }
 }
 </style>

frontend/src/views/TierEditorView.vue

@@ -26,6 +26,9 @@ const pool = ref([])
 const itemsById = ref({})
 
 const title = ref('')
+const thumbnailSrc = ref('')
+const pendingThumbnailFile = ref(null)
+const thumbnailPreviewUrl = ref('')
 const description = ref('')
 const isPublic = ref(true)
 const error = ref('')
@@ -45,13 +48,14 @@ const groupListEl = ref(null)
 const poolEl = ref(null)
 const groupDropEls = ref({})
 const fileEl = ref(null)
+const thumbnailFileEl = ref(null)
 const groupSortable = ref(null)
 const poolSortable = ref(null)
 const dropSortables = ref([])
 
 const isNewTierList = computed(() => tierListId.value === 'new')
 const canEdit = computed(() => !!auth.user && (!ownerId.value || ownerId.value === auth.user.id))
-const iconSizeOptions = [48, 60, 80, 100, 120]
+const iconSizeOptions = [48, 64, 80, 96, 112]
 const hasCustomTitle = computed(() => !!(title.value || '').trim())
 const fallbackTimestamp = computed(() => (updatedAt.value ? updatedAt.value : Date.now()))
 const effectiveAuthorName = computed(() => {
@@ -65,8 +69,9 @@ const effectiveAuthorName = computed(() => {
 const effectiveTitle = computed(() => {
   const customTitle = (title.value || '').trim()
   if (customTitle) return customTitle
-  return `이름 없음 ${formatTitleDate(fallbackTimestamp.value)}`
+  return (gameName.value || gameId.value || 'Tier Maker').trim()
 })
+const displayThumbnailUrl = computed(() => thumbnailPreviewUrl.value || (thumbnailSrc.value ? resolveItemSrc({ src: thumbnailSrc.value }) : ''))
 const untitledWarning = computed(
   () =>
     canEdit.value &&
@@ -237,6 +242,31 @@ function openFile() {
   fileEl.value?.click()
 }
 
+function openThumbnailFile() {
+  if (!canEdit.value) return
+  thumbnailFileEl.value?.click()
+}
+
+function onThumbnailChange(event) {
+  const file = event.target.files?.[0]
+  if (thumbnailPreviewUrl.value) {
+    URL.revokeObjectURL(thumbnailPreviewUrl.value)
+    thumbnailPreviewUrl.value = ''
+  }
+  pendingThumbnailFile.value = file || null
+  if (file) thumbnailPreviewUrl.value = URL.createObjectURL(file)
+  event.target.value = ''
+}
+
+function clearThumbnail() {
+  if (thumbnailPreviewUrl.value) {
+    URL.revokeObjectURL(thumbnailPreviewUrl.value)
+    thumbnailPreviewUrl.value = ''
+  }
+  pendingThumbnailFile.value = null
+  thumbnailSrc.value = ''
+}
+
 function onFileChange(e) {
   const files = Array.from(e.target.files || [])
   if (!files.length) return
@@ -322,12 +352,25 @@ async function uploadPendingCustomItems() {
   }
 }
 
+async function uploadPendingThumbnail() {
+  if (!pendingThumbnailFile.value) return thumbnailSrc.value || ''
+  const data = await api.uploadTierListThumbnail(pendingThumbnailFile.value)
+  if (thumbnailPreviewUrl.value) {
+    URL.revokeObjectURL(thumbnailPreviewUrl.value)
+    thumbnailPreviewUrl.value = ''
+  }
+  pendingThumbnailFile.value = null
+  thumbnailSrc.value = data.thumbnailSrc || ''
+  return thumbnailSrc.value
+}
+
 function buildPayload(existingId) {
   const finalTitle = effectiveTitle.value
   return {
     id: existingId || undefined,
     gameId: gameId.value,
     title: finalTitle,
+    thumbnailSrc: thumbnailSrc.value || '',
     description: (description.value || '').trim(),
     isPublic: !!isPublic.value,
     groups: groups.value.map((g) => ({ id: g.id, name: g.name, itemIds: g.itemIds })),
@@ -340,6 +383,7 @@ async function save() {
   isSaving.value = true
   try {
     await uploadPendingCustomItems()
+    await uploadPendingThumbnail()
     const payload = buildPayload(tierListId.value && tierListId.value !== 'new' ? tierListId.value : null)
     const res = await api.saveTierList(payload)
     if (tierListId.value === 'new') history.replaceState({}, '', `/editor/${gameId.value}/${res.tierList.id}`)
@@ -405,6 +449,7 @@ onMounted(() => {
         const t = res.tierList
         ownerId.value = t.authorId
         title.value = t.title
+        thumbnailSrc.value = t.thumbnailSrc || ''
         description.value = t.description || ''
         isPublic.value = !!t.isPublic
         authorName.value = t.authorName || ''
@@ -430,29 +475,48 @@ onMounted(() => {
 })
 
 onUnmounted(() => {
+  if (thumbnailPreviewUrl.value) URL.revokeObjectURL(thumbnailPreviewUrl.value)
   destroySortables()
 })
 </script>
 
 <template>
   <section class="head">
-    <div class="head__meta">
-      <div class="kicker">{{ gameName || gameId }}</div>
-      <input v-model="title" class="titleInput" placeholder="티어표 이름을 입력하세요" :readonly="!canEdit" />
-      <div v-if="untitledWarning" class="titleNotice">{{ untitledWarning }}</div>
-      <input
-        v-model="description"
-        class="descInput"
-        placeholder="설명(선택): 이 티어표의 기준/룰"
-        :readonly="!canEdit"
-      />
-      <div class="hint">
-        <template v-if="canEdit">
-          그룹 이름/순서 변경과 아이템 드래그&드롭이 가능합니다. 저장하려면 <b>저장</b>을 누르세요.
-        </template>
-        <template v-else>
-          공개된 티어표를 보는 중입니다. 로그인한 작성자만 수정할 수 있어요.
-        </template>
+    <div class="heroCard">
+      <div class="heroCard__main">
+        <input v-model="title" class="titleInput" placeholder="티어표 이름을 입력하세요" :readonly="!canEdit" />
+        <div v-if="untitledWarning" class="titleNotice">{{ untitledWarning }}</div>
+        <input
+          v-model="description"
+          class="descInput"
+          placeholder="설명(선택): 이 티어표의 기준/룰"
+          :readonly="!canEdit"
+        />
+        <div class="hint">
+          <template v-if="canEdit">
+            그룹 이름/순서 변경과 아이템 드래그&드롭이 가능합니다. 저장하려면 <b>저장</b>을 누르세요.
+          </template>
+          <template v-else>
+            공개된 티어표를 보는 중입니다. 로그인한 작성자만 수정할 수 있어요.
+          </template>
+        </div>
+      </div>
+      <div class="heroCard__side">
+        <div class="thumbComposer">
+          <input ref="thumbnailFileEl" type="file" accept="image/*" class="hidden" @change="onThumbnailChange" />
+          <div class="thumbComposer__header">
+            <div class="thumbComposer__eyebrow">대표 썸네일</div>
+            <div class="thumbComposer__caption">목록 카드 상단에 표시됩니다.</div>
+          </div>
+          <div class="thumbComposer__preview">
+            <img v-if="displayThumbnailUrl" class="thumbComposer__image" :src="displayThumbnailUrl" alt="썸네일 미리보기" />
+            <div v-else class="thumbComposer__empty">썸네일 없음</div>
+          </div>
+          <div v-if="canEdit" class="thumbComposer__actions">
+            <button class="btn btn--ghost thumbComposer__button" @click="openThumbnailFile">썸네일 선택</button>
+            <button class="btn btn--danger thumbComposer__button" :disabled="!pendingThumbnailFile && !thumbnailSrc" @click="clearThumbnail">제거</button>
+          </div>
+        </div>
       </div>
     </div>
     <div class="actions">
@@ -573,30 +637,41 @@ onUnmounted(() => {
   gap: 14px;
   padding: 6px 2px 14px;
 }
-.head__meta {
+.heroCard {
   display: grid;
-  gap: 10px;
+  grid-template-columns: minmax(0, 1.5fr) minmax(280px, 360px);
+  gap: 18px;
+  align-items: stretch;
 }
-.kicker {
-  font-size: 12px;
-  opacity: 0.7;
+.heroCard__main,
+.heroCard__side {
+  min-width: 0;
+}
+.heroCard__main {
+  display: grid;
+  gap: 12px;
+}
+.heroCard__side {
+  display: flex;
 }
 .titleInput {
-  width: min(100%, 920px);
+  width: 100%;
   font-size: 22px;
   font-weight: 800;
   letter-spacing: -0.02em;
-  padding: 10px 12px;
-  border-radius: 14px;
+  padding: 14px 16px;
+  border-radius: 18px;
   border: 1px solid rgba(255, 255, 255, 0.12);
-  background: rgba(255, 255, 255, 0.04);
+  background: linear-gradient(180deg, rgba(255, 255, 255, 0.07), rgba(255, 255, 255, 0.04));
   color: rgba(255, 255, 255, 0.92);
   outline: none;
+  box-sizing: border-box;
 }
 .descInput {
-  width: min(100%, 920px);
-  padding: 10px 12px;
-  border-radius: 14px;
+  width: 100%;
+  min-height: 92px;
+  padding: 14px 16px;
+  border-radius: 18px;
   border: 1px solid rgba(255, 255, 255, 0.12);
   background: rgba(0, 0, 0, 0.18);
   color: rgba(255, 255, 255, 0.92);
@@ -606,11 +681,69 @@ onUnmounted(() => {
 .hint {
   opacity: 0.78;
   font-size: 13px;
+  line-height: 1.6;
+  padding: 0 2px;
 }
 .titleNotice {
   font-size: 13px;
   line-height: 1.5;
   color: rgba(251, 191, 36, 0.94);
+  padding: 0 2px;
+}
+.thumbComposer {
+  display: grid;
+  gap: 10px;
+  width: 100%;
+  padding: 16px;
+  border-radius: 22px;
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  background:
+    radial-gradient(circle at top right, rgba(96, 165, 250, 0.12), transparent 46%),
+    rgba(255, 255, 255, 0.04);
+  box-sizing: border-box;
+}
+.thumbComposer__header {
+  display: grid;
+  gap: 4px;
+}
+.thumbComposer__eyebrow {
+  font-size: 13px;
+  font-weight: 900;
+  letter-spacing: 0.02em;
+}
+.thumbComposer__caption {
+  font-size: 12px;
+  opacity: 0.68;
+}
+.thumbComposer__preview {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  border-radius: 18px;
+  overflow: hidden;
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  background: rgba(11, 18, 32, 0.78);
+}
+.thumbComposer__image {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+.thumbComposer__empty {
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  color: rgba(255, 255, 255, 0.62);
+  font-size: 13px;
+}
+.thumbComposer__actions {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 10px;
+}
+.thumbComposer__button {
+  width: 100%;
+  margin-top: 0;
 }
 .actions {
   display: flex;
@@ -687,7 +820,7 @@ onUnmounted(() => {
 }
 .btn--ghost {
   width: 100%;
-  margin-top: 10px;
+  margin-top: 0;
 }
 .layout {
   display: grid;
@@ -986,6 +1119,9 @@ onUnmounted(() => {
   border-radius: 14px;
 }
 @media (max-width: 980px) {
+  .heroCard {
+    grid-template-columns: 1fr;
+  }
   .layout {
     grid-template-columns: 1fr;
   }
@@ -1002,5 +1138,13 @@ onUnmounted(() => {
   .row {
     grid-template-columns: 150px 1fr;
   }
+  .thumbComposer {
+    padding: 14px;
+    border-radius: 18px;
+  }
+  .titleInput,
+  .descInput {
+    border-radius: 16px;
+  }
 }
 </style>