Feat/sw 70 - AI 북마크 분석 로직 고도화 및 API 에러 처리 표준화

frontend/src/components/dialogs/SaveLinkDialog.tsx

@@ -182,23 +182,24 @@ export function SaveLinkDialog() {
         // 태그: 이전 AI 추천 태그를 제거하고 새 추천 적용 (재분석 시 이전 상태 초기화)
         const prevAiTags = aiSuggestedTags;
         const baseTags = selectedTags.filter(tag => !prevAiTags.has(tag)); // 수동 선택 태그만 남김
-        const newTagNames = new Set<string>();
+        const aiTagNames = new Set<string>();
 
         if (result.suggestedTags?.length) {
           const tagsToSelect = [...baseTags];
           for (const tag of result.suggestedTags) {
             if (!tagsToSelect.includes(tag.tagName)) {
               tagsToSelect.push(tag.tagName);
             }
-            if (!tag.isExisting) {
-              newTagNames.add(tag.tagName);
+            // 이미 수동으로 선택된 태그가 아닌 경우에만 AI 추천 태그로 기록
+            if (!baseTags.includes(tag.tagName)) {
+              aiTagNames.add(tag.tagName);
             }
           }
           setSelectedTags(tagsToSelect);
         } else {
           setSelectedTags(baseTags);
         }
-        setAiSuggestedTags(newTagNames);
+        setAiSuggestedTags(aiTagNames);
 
         // 폴더: 이전 AI 추천 상태 초기화 후 새 추천 적용
         setPinnedFolderId(null);

frontend/src/components/providers/QueryProvider.tsx

@@ -2,6 +2,7 @@
 
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { useState } from 'react';
+import { ApiError, getApiErrorMessage } from '@/lib/api/fetchClient';
 
 export function QueryProvider({ children }: { children: React.ReactNode }) {
   const [queryClient] = useState(
@@ -13,14 +14,27 @@ export function QueryProvider({ children }: { children: React.ReactNode }) {
             retry: 1,             // 요청 실패 시 1회 재시도
           },
           mutations: {
-            onError: (error: any) => {
+            onError: (error: unknown) => {
               // 1. 보안을 위해 오직 '개발 환경(development)'에서만 상세한 에러 정보 출력
               if (process.env.NODE_ENV === 'development') {
-                console.error('[API Mutation Error]:', error);
+                if (error instanceof ApiError) {
+                  console.warn('[API Mutation Warning]:', {
+                    status: error.status,
+                    code: error.code,
+                    message: error.message,
+                  });
+                } else {
+                  console.error('[API Mutation Error]:', error);
+                }
               }
 
-              // 2. 사용자에게는 어떤 상황에서도 기술 정보 없이 일반적인 안내 문구만 제공
-              alert('요청 처리 중 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.');
+              // 2. 로그인 만료 에러(AUTH_EXPIRED)는 자동 리다이렉트되므로 alert를 띄우지 않음
+              if (error instanceof ApiError && error.code === 'AUTH_EXPIRED') {
+                return;
+              }
+
+              // 3. 그 외 백엔드가 내려준 사용자용 메시지가 있으면 안내한다.
+              alert(getApiErrorMessage(error));
             },
           },
         },

frontend/src/lib/api/fetchClient.ts

@@ -2,6 +2,34 @@ import type { ApiResponse } from '@/lib/types/apiResponse';
 import { buildBackendUrl } from '@/lib/config/backend';
 import { useAuthStore } from '@/lib/store/authStore';
 
+const DEFAULT_API_ERROR_MESSAGE = '요청 처리 중 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.';
+
+type ApiErrorParams = {
+  message: string;
+  status?: number;
+  code?: string;
+};
+
+export class ApiError extends Error {
+  readonly status?: number;
+  readonly code?: string;
+
+  constructor({ message, status, code }: ApiErrorParams) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export function getApiErrorMessage(error: unknown): string {
+  if (error instanceof ApiError && error.message) {
+    return error.message;
+  }
+
+  return DEFAULT_API_ERROR_MESSAGE;
+}
+
 // 여러 API 가 동시에 401 을 받아도 refresh 는 1회만 보내도록 Promise 를 공유한다.
 let refreshPromise: Promise<boolean> | null = null;
 
@@ -80,7 +108,11 @@ export async function fetchClient<T>(
     if (typeof window !== 'undefined') {
       window.location.href = '/login';
     }
-    throw new Error('인증이 만료되었습니다.');
+    throw new ApiError({
+      status: 401,
+      code: 'AUTH_EXPIRED',
+      message: '인증이 만료되었습니다.',
+    });
   }
 
   return parseResponse<T>(response);
@@ -91,14 +123,22 @@ async function parseResponse<T>(response: Response): Promise<T> {
   // 2xx 외 HTTP 오류 처리
   if (!response.ok) {
     const text = await response.text().catch(() => '');
-    let message = `HTTP ${response.status}`;
+    let message = DEFAULT_API_ERROR_MESSAGE;
+    let code: string | undefined;
     try {
       const parsed = JSON.parse(text) as ApiResponse<unknown>;
-      if (parsed.error?.message) message = parsed.error.message;
+      if (parsed.error?.message) {
+        message = parsed.error.message;
+        code = parsed.error.code;
+      }
     } catch {
-      if (text) message = text;
+      // ApiResponse 형식이 아닌 응답 본문은 사용자에게 그대로 노출하지 않는다.
     }
-    throw new Error(message);
+    throw new ApiError({
+      status: response.status,
+      code,
+      message,
+    });
   }
 
   // 204 No Content 또는 빈 응답
@@ -111,7 +151,11 @@ async function parseResponse<T>(response: Response): Promise<T> {
 
   // HTTP는 200이지만 비즈니스 로직 에러인 경우 (success: false)
   if (!json.success) {
-    throw new Error(json.error?.message ?? '알 수 없는 에러');
+    throw new ApiError({
+      status: response.status,
+      code: json.error?.code,
+      message: json.error?.message ?? DEFAULT_API_ERROR_MESSAGE,
+    });
   }
 
   return json.data;

src/main/java/com/web/SearchWeb/bookmark/dao/BookmarkDao.java

@@ -7,6 +7,7 @@
 import org.apache.ibatis.annotations.Param;
 
 import java.util.List;
+import java.util.Map;
 
 public interface BookmarkDao {
     //북마크 추가
@@ -62,4 +63,9 @@ public interface BookmarkDao {
 
     // 폴더 내 활성 북마크 존재 여부
     boolean existsActiveBookmarkInFolder(Long memberFolderId);
+
+    // 폴더별 컨텍스트 조회 (LLM 폴더 추천용 - LATERAL aggregation)
+    List<Map<String, Object>> selectFolderContexts(@Param("memberId") Long memberId,
+                                                   @Param("sampleLimit") int sampleLimit,
+                                                   @Param("tagLimit") int tagLimit);
 }

src/main/java/com/web/SearchWeb/bookmark/dao/MybatisBookmarkDao.java

@@ -9,6 +9,7 @@
 import org.springframework.stereotype.Repository;
 
 import java.util.List;
+import java.util.Map;
 
 @Repository
 public class MybatisBookmarkDao implements BookmarkDao {
@@ -169,4 +170,12 @@ public int insertBookmarkTags(Long bookmarkId, List<Long> tagIds) {
     public boolean existsActiveBookmarkInFolder(Long memberFolderId) {
         return mapper.existsActiveBookmarkInFolder(memberFolderId);
     }
+
+    /**
+     *  폴더별 컨텍스트 조회 (LLM 폴더 추천용 - LATERAL aggregation)
+     */
+    @Override
+    public List<Map<String, Object>> selectFolderContexts(Long memberId, int sampleLimit, int tagLimit) {
+        return mapper.selectFolderContexts(memberId, sampleLimit, tagLimit);
+    }
 }

src/main/java/com/web/SearchWeb/linkanalysis/domain/FolderContext.java

@@ -0,0 +1,131 @@
+package com.web.SearchWeb.linkanalysis.domain;
+
+import lombok.Builder;
+import lombok.Getter;
+import lombok.extern.slf4j.Slf4j;
+
+import java.sql.Array;
+import java.sql.SQLException;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 폴더 컨텍스트 도메인 객체 (LLM 폴더 추천용)
+ * - BookmarkDao.selectFolderContexts() 결과 행을 변환한 불변 DTO
+ * - 폴더당 북마크 수, 최근 저장일, 샘플 제목 목록, 자주 쓰인 태그(빈도) 목록을 포함
+ */
+@Slf4j
+@Getter
+@Builder
+public class FolderContext {
+
+    /** 폴더 ID */
+    private final Long memberFolderId;
+
+    /** 폴더명 */
+    private final String folderName;
+
+    /** 폴더 설명 (용도) */
+    private final String description;
+
+    /** 폴더 유형 ("CUSTOM" / "UNORGANIZED") */
+    private final String folderType;
+
+    /** 활성 북마크 개수 */
+    private final long bookmarkCount;
+
+    /** 최근 북마크 저장 일자 (UNORGANIZED 또는 빈 폴더는 null) */
+    private final LocalDate lastCreatedAt;
+
+    /** 샘플 북마크 제목 목록 (최신순 최대 sampleLimit개) */
+    @Builder.Default
+    private final List<String> sampleTitles = List.of();
+
+    /** 폴더 안의 저장 링크에서 자주 쓰인 태그(빈도) 목록. 예: AI(12) */
+    @Builder.Default
+    private final List<String> topTags = List.of();
+
+
+    /**
+     * MyBatis가 반환한 Map row 한 건을 FolderContext로 변환한다.
+     * - PostgreSQL ARRAY → java.sql.Array → List<String> 변환 처리
+     * - timestamp → LocalDate 변환 처리
+     */
+    public static FolderContext fromRow(Map<String, Object> row) {
+        return FolderContext.builder()
+                .memberFolderId(toLong(row.get("memberFolderId")))
+                .folderName(asString(row.get("folderName")))
+                .description(asString(row.get("description")))
+                .folderType(asString(row.get("folderType")))
+                .bookmarkCount(toLong(row.get("bookmarkCount")))
+                .lastCreatedAt(toLocalDate(row.get("lastCreatedAt")))
+                .sampleTitles(toStringList(row.get("sampleTitles")))
+                .topTags(toStringList(row.get("topTags")))
+                .build();
+    }
+
+
+    private static String asString(Object value) {
+        return value != null ? value.toString() : null;
+    }
+
+    private static long toLong(Object value) {
+        if (value == null) return 0L;
+        if (value instanceof Number n) return n.longValue();
+        try {
+            return Long.parseLong(value.toString());
+        } catch (NumberFormatException e) {
+            return 0L;
+        }
+    }
+
+    private static LocalDate toLocalDate(Object value) {
+        if (value == null) return null;
+        if (value instanceof LocalDate ld) return ld;
+        if (value instanceof LocalDateTime ldt) return ldt.toLocalDate();
+        if (value instanceof java.sql.Date sqlDate) return sqlDate.toLocalDate();
+        if (value instanceof java.sql.Timestamp ts) return ts.toLocalDateTime().toLocalDate();
+        if (value instanceof java.util.Date d) {
+            return new java.sql.Timestamp(d.getTime()).toLocalDateTime().toLocalDate();
+        }
+        return null;
+    }
+
+    @SuppressWarnings("unchecked")
+    private static List<String> toStringList(Object value) {
+        if (value == null) return List.of();
+        if (value instanceof List<?> list) {
+            List<String> out = new ArrayList<>(list.size());
+            for (Object o : list) {
+                if (o != null) out.add(o.toString());
+            }
+            return Collections.unmodifiableList(out);
+        }
+        if (value instanceof Object[] arr) {
+            List<String> out = new ArrayList<>(arr.length);
+            for (Object o : arr) {
+                if (o != null) out.add(o.toString());
+            }
+            return Collections.unmodifiableList(out);
+        }
+        if (value instanceof Array sqlArr) {
+            try {
+                Object inner = sqlArr.getArray();
+                if (inner instanceof Object[] objArr) {
+                    List<String> out = new ArrayList<>(objArr.length);
+                    for (Object o : objArr) {
+                        if (o != null) out.add(o.toString());
+                    }
+                    return Collections.unmodifiableList(out);
+                }
+            } catch (SQLException e) {
+                log.debug("[folder-context] failed to read sql array: {}", e.getMessage());
+            }
+        }
+        return List.of();
+    }
+}

src/main/java/com/web/SearchWeb/linkanalysis/domain/PageContent.java

@@ -29,9 +29,6 @@ public class PageContent {
     /** 전체 URL */
     private final String url;
 
-    /** 콘텐츠 유형 (JSON-LD @type 또는 og:type, 예: "Article", "Product") */
-    private final String contentType;
-
     /** 페이지 메타 키워드 (최대 10개) */
     @Builder.Default
     private final List<String> keywords = List.of();