daiso 1.0.4 → 1.0.6

package/dist/api/gs25Handlers.js

@@ -0,0 +1,267 @@
+/**
+ * GS25 GET API 핸들러
+ */
+/* c8 ignore start */
+import { errorResponse, successResponse } from './response.js';
+import { attachDistanceToGs25Stores, fetchGs25SearchProducts, fetchGs25Stores, filterGs25StoresByKeyword, geocodeGs25Address, selectGs25StoresForKeyword, sortGs25Stores, } from '../services/gs25/client.js';
+const GS25_FALLBACK_STORE_LOOKUP_ITEM_CODE = '8801117752804';
+/**
+ * GS25 매장 검색 API 핸들러
+ * GET /api/gs25/stores?keyword={키워드}&lat={위도}&lng={경도}
+ */
+export async function handleGs25FindStores(c) {
+    const keyword = c.req.query('keyword') || '';
+    const serviceCode = c.req.query('serviceCode') || '01';
+    const limit = parseInt(c.req.query('limit') || '20', 10);
+    const rawLat = c.req.query('lat');
+    const rawLng = c.req.query('lng');
+    const parsedLat = rawLat ? parseFloat(rawLat) : undefined;
+    const parsedLng = rawLng ? parseFloat(rawLng) : undefined;
+    let latitude = typeof parsedLat === 'number' && Number.isFinite(parsedLat) ? parsedLat : undefined;
+    let longitude = typeof parsedLng === 'number' && Number.isFinite(parsedLng) ? parsedLng : undefined;
+    let geocodeUsed = false;
+    try {
+        if ((typeof latitude !== 'number' || typeof longitude !== 'number') && keyword.trim().length > 0) {
+            const geocoded = await geocodeGs25Address(keyword, {
+                timeout: 15000,
+                googleMapsApiKey: c.env?.GOOGLE_MAPS_API_KEY,
+            });
+            if (geocoded) {
+                latitude = geocoded.latitude;
+                longitude = geocoded.longitude;
+                geocodeUsed = true;
+            }
+        }
+        let storeResult = await fetchGs25Stores({
+            serviceCode,
+            latitude,
+            longitude,
+        }, {
+            timeout: 20000,
+        });
+        let fallbackUsed = false;
+        if (storeResult.stores.length === 0 && typeof latitude === 'number' && typeof longitude === 'number') {
+            try {
+                const fallbackResult = await fetchGs25Stores({
+                    serviceCode,
+                    itemCode: GS25_FALLBACK_STORE_LOOKUP_ITEM_CODE,
+                    realTimeStockYn: 'Y',
+                    latitude,
+                    longitude,
+                    useCache: false,
+                }, {
+                    timeout: 20000,
+                });
+                if (fallbackResult.stores.length > 0) {
+                    storeResult = fallbackResult;
+                    fallbackUsed = true;
+                }
+            }
+            catch {
+                fallbackUsed = false;
+            }
+        }
+        const selected = selectGs25StoresForKeyword(storeResult.stores, keyword, {
+            relaxWhenEmpty: typeof latitude === 'number' && typeof longitude === 'number',
+        });
+        const withDistance = attachDistanceToGs25Stores(selected.stores, latitude, longitude);
+        const stores = sortGs25Stores(withDistance).slice(0, limit);
+        return successResponse(c, {
+            serviceCode,
+            keyword,
+            geocodeUsed,
+            location: typeof latitude === 'number' && typeof longitude === 'number'
+                ? { latitude, longitude }
+                : null,
+            cacheHit: storeResult.cacheHit,
+            filterRelaxed: selected.filterRelaxed,
+            fallbackUsed,
+            stores,
+        }, {
+            total: selected.stores.length,
+            pageSize: limit,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
+        return errorResponse(c, 'GS25_STORE_SEARCH_FAILED', message, 500);
+    }
+}
+/**
+ * GS25 상품 검색 API 핸들러
+ * GET /api/gs25/products?keyword={검색어}
+ */
+export async function handleGs25SearchProducts(c) {
+    const keyword = c.req.query('keyword') || '';
+    const limit = parseInt(c.req.query('limit') || '20', 10);
+    if (keyword.trim().length === 0) {
+        return errorResponse(c, 'MISSING_QUERY', '검색어(keyword)를 입력해주세요.');
+    }
+    try {
+        const products = await fetchGs25SearchProducts(keyword, { timeout: 20000 });
+        const limitedProducts = products.slice(0, limit);
+        return successResponse(c, {
+            keyword,
+            count: limitedProducts.length,
+            products: limitedProducts.map((p) => ({
+                itemCode: p.itemCode,
+                itemName: p.itemName,
+                shortItemName: p.shortItemName,
+                imageUrl: p.imageUrl,
+                rating: p.rating,
+                stockCheckEnabled: p.stockCheckEnabled,
+            })),
+        }, {
+            total: limitedProducts.length,
+            pageSize: limit,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
+        return errorResponse(c, 'GS25_PRODUCT_SEARCH_FAILED', message, 500);
+    }
+}
+/**
+ * GS25 재고 조회 API 핸들러
+ * GET /api/gs25/inventory?keyword={검색어}&storeKeyword={매장키워드}&lat={위도}&lng={경도}
+ */
+export async function handleGs25CheckInventory(c) {
+    const keyword = c.req.query('keyword') || '';
+    const itemCode = c.req.query('itemCode') || '';
+    const storeKeyword = c.req.query('storeKeyword') || '';
+    const serviceCode = c.req.query('serviceCode') || '01';
+    const storeLimit = parseInt(c.req.query('storeLimit') || '20', 10);
+    const rawLat = c.req.query('lat');
+    const rawLng = c.req.query('lng');
+    const parsedLat = rawLat ? parseFloat(rawLat) : undefined;
+    const parsedLng = rawLng ? parseFloat(rawLng) : undefined;
+    let latitude = typeof parsedLat === 'number' && Number.isFinite(parsedLat) ? parsedLat : undefined;
+    let longitude = typeof parsedLng === 'number' && Number.isFinite(parsedLng) ? parsedLng : undefined;
+    let geocodeUsed = false;
+    if (keyword.trim().length === 0 && itemCode.trim().length === 0) {
+        return errorResponse(c, 'MISSING_QUERY', '검색어(keyword) 또는 상품 코드(itemCode)를 입력해주세요.');
+    }
+    try {
+        if ((typeof latitude !== 'number' || typeof longitude !== 'number') && storeKeyword.trim().length > 0) {
+            const directGeocoded = await geocodeGs25Address(storeKeyword, {
+                timeout: 15000,
+                googleMapsApiKey: c.env?.GOOGLE_MAPS_API_KEY,
+            });
+            if (directGeocoded) {
+                latitude = directGeocoded.latitude;
+                longitude = directGeocoded.longitude;
+                geocodeUsed = true;
+            }
+            else {
+                const baseStores = await fetchGs25Stores({
+                    serviceCode,
+                }, {
+                    timeout: 20000,
+                });
+                const firstAddress = filterGs25StoresByKeyword(baseStores.stores, storeKeyword).find((store) => store.address.trim().length > 0)
+                    ?.address || '';
+                if (firstAddress.length > 0) {
+                    const geocoded = await geocodeGs25Address(firstAddress, {
+                        timeout: 15000,
+                        googleMapsApiKey: c.env?.GOOGLE_MAPS_API_KEY,
+                    });
+                    if (geocoded) {
+                        latitude = geocoded.latitude;
+                        longitude = geocoded.longitude;
+                        geocodeUsed = true;
+                    }
+                }
+            }
+        }
+        // 1단계: totalSearch API로 키워드 → itemCode 변환
+        let firstProduct;
+        let stockResult;
+        let itemCodeUsed = itemCode.trim().length > 0;
+        let resolvedItemCode = itemCode.trim().length > 0 ? itemCode.trim() : null;
+        if (resolvedItemCode) {
+            stockResult = await fetchGs25Stores({
+                serviceCode,
+                itemCode: resolvedItemCode,
+                realTimeStockYn: 'Y',
+                latitude,
+                longitude,
+                useCache: false,
+            }, {
+                timeout: 20000,
+            });
+        }
+        else {
+            const searchProducts = await fetchGs25SearchProducts(keyword, { timeout: 20000 });
+            firstProduct = searchProducts.find((p) => p.itemCode.length > 0);
+            if (firstProduct) {
+                resolvedItemCode = firstProduct.itemCode;
+                itemCodeUsed = true;
+                stockResult = await fetchGs25Stores({
+                    serviceCode,
+                    itemCode: resolvedItemCode,
+                    realTimeStockYn: 'Y',
+                    latitude,
+                    longitude,
+                    useCache: false,
+                }, {
+                    timeout: 20000,
+                });
+            }
+            else {
+                stockResult = await fetchGs25Stores({
+                    serviceCode,
+                    keyword,
+                    realTimeStockYn: 'Y',
+                    latitude,
+                    longitude,
+                    useCache: false,
+                }, {
+                    timeout: 20000,
+                });
+            }
+        }
+        const selected = selectGs25StoresForKeyword(stockResult.stores, storeKeyword, {
+            relaxWhenEmpty: typeof latitude === 'number' && typeof longitude === 'number',
+        });
+        const filtered = selected.stores;
+        const withDistance = attachDistanceToGs25Stores(filtered, latitude, longitude);
+        const stores = sortGs25Stores(withDistance).slice(0, storeLimit);
+        // 상품 정보: searchProducts에서 먼저 가져오고, 없으면 stores에서
+        const productName = firstProduct?.itemName || firstProduct?.shortItemName ||
+            filtered.find((item) => item.searchItemName.length > 0)?.searchItemName || null;
+        const productPrice = filtered.find((item) => item.searchItemSellPrice !== null)?.searchItemSellPrice ?? null;
+        const inStockStoreCount = filtered.filter((item) => item.realStockQuantity > 0).length;
+        const totalStockQuantity = filtered.reduce((sum, item) => sum + Math.max(item.realStockQuantity, 0), 0);
+        return successResponse(c, {
+            serviceCode,
+            keyword,
+            itemCodeUsed,
+            itemCode: resolvedItemCode,
+            storeKeyword,
+            geocodeUsed,
+            filterRelaxed: selected.filterRelaxed,
+            location: typeof latitude === 'number' && typeof longitude === 'number'
+                ? { latitude, longitude }
+                : null,
+            product: {
+                name: productName,
+                sellPrice: productPrice,
+                imageUrl: firstProduct?.imageUrl || null,
+                rating: firstProduct?.rating || null,
+            },
+            inventory: {
+                totalStoreCount: stockResult.totalCount,
+                matchedStoreCount: filtered.length,
+                inStockStoreCount,
+                totalStockQuantity,
+                count: stores.length,
+                stores,
+            },
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
+        return errorResponse(c, 'GS25_INVENTORY_CHECK_FAILED', message, 500);
+    }
+}
+/* c8 ignore stop */

package/dist/api/handlers.js

@@ -4,122 +4,60 @@
  * MCP 미지원 서비스를 위한 GET 기반 API 핸들러입니다.
  * 기존 도구의 핵심 함수들을 재사용합니다.
  */
-import { fetchProducts } from '../services/daiso/tools/searchProducts.js';
-import { fetchStores } from '../services/daiso/tools/findStores.js';
-import { fetchOnlineStock, fetchStoreInventory, } from '../services/daiso/tools/checkInventory.js';
-import { fetchProductById } from '../services/daiso/tools/getPriceInfo.js';
-import { getImageUrl } from '../services/daiso/api.js';
-import { fetchOliveyoungProducts, fetchOliveyoungStores, } from '../services/oliveyoung/client.js';
+import { enrichOliveyoungProductsWithNearbyStoreInventory, fetchOliveyoungProducts, fetchOliveyoungStores, } from '../services/oliveyoung/client.js';
+import { fetchCuStock, fetchCuStores, geocodeCuAddress } from '../services/cu/client.js';
 import { errorResponse, successResponse } from './response.js';
-/**
- * 제품 검색 API 핸들러
- * GET /api/daiso/products?q={검색어}&page={페이지}&pageSize={개수}
- */
-export async function handleSearchProducts(c) {
-    const query = c.req.query('q');
-    const page = parseInt(c.req.query('page') || '1');
-    const pageSize = parseInt(c.req.query('pageSize') || '30');
-    if (!query || query.trim().length === 0) {
-        return errorResponse(c, 'MISSING_QUERY', '검색어(q)를 입력해주세요.');
-    }
-    try {
-        const { products, totalCount } = await fetchProducts(query, page, pageSize);
-        return successResponse(c, { products }, { total: totalCount, page, pageSize });
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
-        return errorResponse(c, 'SEARCH_FAILED', message, 500);
-    }
-}
-/**
- * 제품 상세 정보 API 핸들러
- * GET /api/daiso/products/:id
- */
-export async function handleGetProduct(c) {
-    const productId = c.req.param('id');
-    if (!productId) {
-        return errorResponse(c, 'MISSING_ID', '제품 ID가 필요합니다.');
+export { handleCheckInventory, handleFindStores, handleGetDisplayLocation, handleGetProduct, handleSearchProducts, } from './daisoHandlers.js';
+function parseBooleanQuery(value, defaultValue = false) {
+    if (!value) {
+        return defaultValue;
     }
-    try {
-        const product = await fetchProductById(productId);
-        if (!product) {
-            return errorResponse(c, 'NOT_FOUND', '제품을 찾을 수 없습니다.', 404);
-        }
-        const result = {
-            id: product.PD_NO,
-            name: product.PDNM || product.EXH_PD_NM,
-            price: parseInt(product.PD_PRC) || 0,
-            currency: 'KRW',
-            imageUrl: getImageUrl(product.ATCH_FILE_URL),
-            brand: product.BRND_NM || undefined,
-            soldOut: product.SOLD_OUT_YN === 'Y',
-            isNew: product.NEW_PD_YN === 'Y',
-        };
-        return successResponse(c, result);
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true' || normalized === '1' || normalized === 'y') {
+        return true;
     }
-    catch (error) {
-        const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
-        return errorResponse(c, 'FETCH_FAILED', message, 500);
+    if (normalized === 'false' || normalized === '0' || normalized === 'n') {
+        return false;
     }
+    return defaultValue;
 }
 /**
- * 매장 검색 API 핸들러
- * GET /api/daiso/stores?keyword={키워드}&sido={시도}&gugun={구군}&dong={동}&limit={개수}
+ * 올리브영 상품 검색 API 핸들러
+ * GET /api/oliveyoung/products?keyword={검색어}
  */
-export async function handleFindStores(c) {
-    const keyword = c.req.query('keyword');
-    const sido = c.req.query('sido');
-    const gugun = c.req.query('gugun');
-    const dong = c.req.query('dong');
-    const limit = parseInt(c.req.query('limit') || '50');
-    if (!keyword && !sido) {
-        return errorResponse(c, 'MISSING_PARAMS', '검색어(keyword) 또는 지역(sido)을 입력해주세요.');
-    }
-    try {
-        const stores = await fetchStores(keyword, sido, gugun, dong);
-        const limitedStores = stores.slice(0, limit);
-        return successResponse(c, { stores: limitedStores }, { total: stores.length });
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
-        return errorResponse(c, 'SEARCH_FAILED', message, 500);
-    }
-}
-/**
- * 재고 확인 API 핸들러
- * GET /api/daiso/inventory?productId={제품ID}&lat={위도}&lng={경도}&keyword={매장검색어}
- */
-export async function handleCheckInventory(c) {
-    const productId = c.req.query('productId');
-    const lat = parseFloat(c.req.query('lat') || '37.5665');
-    const lng = parseFloat(c.req.query('lng') || '126.978');
+export async function handleOliveyoungSearchProducts(c) {
     const keyword = c.req.query('keyword') || '';
     const page = parseInt(c.req.query('page') || '1');
-    const pageSize = parseInt(c.req.query('pageSize') || '30');
-    if (!productId) {
-        return errorResponse(c, 'MISSING_PRODUCT_ID', '제품 ID(productId)를 입력해주세요.');
+    const size = parseInt(c.req.query('size') || '20');
+    const sort = c.req.query('sort') || '01';
+    const includeSoldOut = c.req.query('includeSoldOut') === 'true';
+    const parsedTimeoutMs = parseInt(c.req.query('timeoutMs') || '15000', 10);
+    const timeoutMs = Number.isFinite(parsedTimeoutMs) && parsedTimeoutMs > 0 ? parsedTimeoutMs : 15000;
+    if (keyword.trim().length === 0) {
+        return errorResponse(c, 'MISSING_QUERY', '검색어(keyword)를 입력해주세요.');
     }
     try {
-        const [onlineStock, storeResult] = await Promise.all([
-            fetchOnlineStock(productId),
-            fetchStoreInventory(productId, lat, lng, page, pageSize, keyword),
-        ]);
-        const inStockStores = storeResult.stores.filter((s) => s.quantity > 0);
-        const result = {
-            productId,
-            location: { latitude: lat, longitude: lng },
-            onlineStock,
-            storeInventory: {
-                totalStores: storeResult.totalCount,
-                inStockCount: inStockStores.length,
-                stores: storeResult.stores,
-            },
-        };
-        return successResponse(c, result, { total: storeResult.totalCount, page, pageSize });
+        const result = await fetchOliveyoungProducts({
+            keyword,
+            page,
+            size,
+            sort,
+            includeSoldOut,
+        }, {
+            apiKey: c.env?.ZYTE_API_KEY,
+            timeout: timeoutMs,
+        });
+        return successResponse(c, {
+            keyword,
+            totalCount: result.totalCount,
+            nextPage: result.nextPage,
+            count: result.products.length,
+            products: result.products,
+        }, { total: result.totalCount, page, pageSize: size });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
-        return errorResponse(c, 'INVENTORY_CHECK_FAILED', message, 500);
+        return errorResponse(c, 'OLIVEYOUNG_PRODUCT_SEARCH_FAILED', message, 500);
     }
 }
 /**
@@ -132,6 +70,8 @@ export async function handleOliveyoungFindStores(c) {
     const lng = parseFloat(c.req.query('lng') || '126.978');
     const pageIdx = parseInt(c.req.query('pageIdx') || '1');
     const limit = parseInt(c.req.query('limit') || '20');
+    const parsedTimeoutMs = parseInt(c.req.query('timeoutMs') || '15000', 10);
+    const timeoutMs = Number.isFinite(parsedTimeoutMs) && parsedTimeoutMs > 0 ? parsedTimeoutMs : 15000;
     try {
         const result = await fetchOliveyoungStores({
             latitude: lat,
@@ -139,7 +79,8 @@ export async function handleOliveyoungFindStores(c) {
             pageIdx,
             searchWords: keyword,
         }, {
-            apiKey: c.env.ZYTE_API_KEY,
+            apiKey: c.env?.ZYTE_API_KEY,
+            timeout: timeoutMs,
         });
         return successResponse(c, {
             stores: result.stores.slice(0, limit),
@@ -164,6 +105,10 @@ export async function handleOliveyoungCheckInventory(c) {
     const sort = c.req.query('sort') || '01';
     const includeSoldOut = c.req.query('includeSoldOut') === 'true';
     const storeLimit = parseInt(c.req.query('storeLimit') || '10');
+    const parsedTimeoutMs = parseInt(c.req.query('timeoutMs') || '15000', 10);
+    const timeoutMs = Number.isFinite(parsedTimeoutMs) && parsedTimeoutMs > 0 ? parsedTimeoutMs : 15000;
+    const parsedStockCheckLimit = parseInt(c.req.query('stockCheckLimit') || '5', 10);
+    const stockCheckLimit = Number.isFinite(parsedStockCheckLimit) && parsedStockCheckLimit >= 0 ? parsedStockCheckLimit : 5;
     if (!keyword || keyword.trim().length === 0) {
         return errorResponse(c, 'MISSING_QUERY', '검색어(keyword)를 입력해주세요.');
     }
@@ -176,6 +121,7 @@ export async function handleOliveyoungCheckInventory(c) {
                 searchWords: storeKeyword,
             }, {
                 apiKey: c.env.ZYTE_API_KEY,
+                timeout: timeoutMs,
             }),
             fetchOliveyoungProducts({
                 keyword,
@@ -185,8 +131,19 @@ export async function handleOliveyoungCheckInventory(c) {
                 includeSoldOut,
             }, {
                 apiKey: c.env.ZYTE_API_KEY,
+                timeout: timeoutMs,
             }),
         ]);
+        const enrichedInventory = await enrichOliveyoungProductsWithNearbyStoreInventory(productResult.products, {
+            latitude: lat,
+            longitude: lng,
+            storeKeyword,
+            maxProducts: Math.min(productResult.products.length, stockCheckLimit),
+        }, {
+            apiKey: c.env.ZYTE_API_KEY,
+            timeout: timeoutMs,
+        });
+        const inStockCount = enrichedInventory.products.filter((product) => product.inStock).length;
         return successResponse(c, {
             keyword,
             location: { latitude: lat, longitude: lng },
@@ -197,7 +154,11 @@ export async function handleOliveyoungCheckInventory(c) {
             inventory: {
                 totalCount: productResult.totalCount,
                 nextPage: productResult.nextPage,
-                products: productResult.products,
+                stockCheckedCount: enrichedInventory.checkedCount,
+                stockUncheckedCount: Math.max(0, productResult.products.length - enrichedInventory.checkedCount),
+                inStockCount,
+                outOfStockCount: enrichedInventory.products.length - inStockCount,
+                products: enrichedInventory.products,
             },
         }, { total: productResult.totalCount, page, pageSize: size });
     }
@@ -206,3 +167,147 @@ export async function handleOliveyoungCheckInventory(c) {
         return errorResponse(c, 'OLIVEYOUNG_INVENTORY_CHECK_FAILED', message, 500);
     }
 }
+/**
+ * CU 매장 검색 API 핸들러
+ * GET /api/cu/stores?keyword={키워드}&lat={위도}&lng={경도}
+ */
+export async function handleCuFindStores(c) {
+    const keyword = c.req.query('keyword') || '';
+    const rawLat = c.req.query('lat');
+    const rawLng = c.req.query('lng');
+    const limit = parseInt(c.req.query('limit') || '20');
+    const parsedLat = rawLat ? parseFloat(rawLat) : undefined;
+    const parsedLng = rawLng ? parseFloat(rawLng) : undefined;
+    const lat = typeof parsedLat === 'number' && Number.isFinite(parsedLat) ? parsedLat : undefined;
+    const lng = typeof parsedLng === 'number' && Number.isFinite(parsedLng) ? parsedLng : undefined;
+    try {
+        const result = await fetchCuStores({
+            latitude: lat,
+            longitude: lng,
+            searchWord: keyword,
+        }, {
+            timeout: 15000,
+            apiKey: c.env.ZYTE_API_KEY,
+        });
+        return successResponse(c, {
+            location: typeof lat === 'number' && typeof lng === 'number' ? { latitude: lat, longitude: lng } : null,
+            keyword,
+            stores: result.stores.slice(0, limit),
+        }, { total: result.totalCount, pageSize: limit });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
+        return errorResponse(c, 'CU_STORE_SEARCH_FAILED', message, 500);
+    }
+}
+/**
+ * CU 재고 검색 API 핸들러
+ * GET /api/cu/inventory?keyword={검색어}&lat={위도}&lng={경도}
+ */
+export async function handleCuCheckInventory(c) {
+    const keyword = c.req.query('keyword');
+    const storeKeyword = c.req.query('storeKeyword') || '';
+    const rawLat = c.req.query('lat');
+    const rawLng = c.req.query('lng');
+    const parsedLat = rawLat ? parseFloat(rawLat) : undefined;
+    const parsedLng = rawLng ? parseFloat(rawLng) : undefined;
+    const lat = typeof parsedLat === 'number' && Number.isFinite(parsedLat) ? parsedLat : undefined;
+    const lng = typeof parsedLng === 'number' && Number.isFinite(parsedLng) ? parsedLng : undefined;
+    const size = parseInt(c.req.query('size') || '20');
+    const offset = parseInt(c.req.query('offset') || '0');
+    const searchSort = c.req.query('searchSort') || 'recom';
+    const storeLimit = parseInt(c.req.query('storeLimit') || '10');
+    const storeCheck = parseBooleanQuery(c.req.query('storeCheck'), true);
+    if (!keyword || keyword.trim().length === 0) {
+        return errorResponse(c, 'MISSING_QUERY', '검색어(keyword)를 입력해주세요.');
+    }
+    try {
+        const stockResult = await fetchCuStock({
+            keyword,
+            limit: size,
+            offset,
+            searchSort,
+        }, {
+            timeout: 15000,
+        });
+        const firstStockItem = stockResult.items.find((item) => item.itemCode.trim().length > 0) || null;
+        const hasInputLocation = typeof lat === 'number' && typeof lng === 'number';
+        const resolvedLat = hasInputLocation ? lat : undefined;
+        const resolvedLng = hasInputLocation ? lng : undefined;
+        let storeResult = storeCheck
+            ? null
+            : { totalCount: 0, stores: [] };
+        // 좌표 미입력 + 매장 키워드 입력 시, 키워드 기반 매장 검색 결과를 우선 사용합니다.
+        if (storeCheck && !hasInputLocation && storeKeyword.trim().length > 0) {
+            const keywordStoreResult = await fetchCuStores({
+                searchWord: storeKeyword,
+            }, {
+                timeout: 15000,
+                apiKey: c.env?.ZYTE_API_KEY,
+            });
+            const firstAddress = keywordStoreResult.stores.find((store) => store.address.trim().length > 0)?.address || '';
+            if (firstAddress.length > 0) {
+                const geocoded = await geocodeCuAddress(firstAddress, {
+                    timeout: 15000,
+                    googleMapsApiKey: c.env?.GOOGLE_MAPS_API_KEY,
+                });
+                if (geocoded) {
+                    const hasStockSeed = !!firstStockItem?.itemCode;
+                    storeResult = await fetchCuStores({
+                        latitude: geocoded.latitude,
+                        longitude: geocoded.longitude,
+                        searchWord: storeKeyword,
+                        itemCd: firstStockItem?.itemCode || '',
+                        onItemNo: firstStockItem?.onItemNo || '',
+                        jipCd: firstStockItem?.itemCode || '',
+                        isRecommend: hasStockSeed ? 'Y' : '',
+                        recommendId: hasStockSeed ? 'stock' : '',
+                        pageType: hasStockSeed ? 'search_improve stock_sch_improve' : 'search_improve',
+                    }, {
+                        timeout: 15000,
+                        apiKey: c.env?.ZYTE_API_KEY,
+                    });
+                }
+            }
+            storeResult ||= keywordStoreResult;
+        }
+        if (!storeResult) {
+            const hasStockSeed = !!firstStockItem?.itemCode;
+            storeResult = await fetchCuStores({
+                latitude: resolvedLat,
+                longitude: resolvedLng,
+                searchWord: storeKeyword,
+                itemCd: firstStockItem?.itemCode || '',
+                onItemNo: firstStockItem?.onItemNo || '',
+                jipCd: firstStockItem?.itemCode || '',
+                isRecommend: hasStockSeed ? 'Y' : '',
+                recommendId: hasStockSeed ? 'stock' : '',
+                pageType: hasStockSeed ? 'search_improve stock_sch_improve' : 'search_improve',
+            }, {
+                timeout: 15000,
+                apiKey: c.env?.ZYTE_API_KEY,
+            });
+        }
+        return successResponse(c, {
+            keyword,
+            location: typeof resolvedLat === 'number' && typeof resolvedLng === 'number'
+                ? { latitude: resolvedLat, longitude: resolvedLng }
+                : null,
+            nearbyStores: {
+                totalCount: storeResult.totalCount,
+                stockItemCode: firstStockItem?.itemCode || null,
+                stockItemName: firstStockItem?.itemName || null,
+                stores: storeResult.stores.slice(0, storeLimit),
+            },
+            inventory: {
+                totalCount: stockResult.totalCount,
+                spellModifyYn: stockResult.spellModifyYn,
+                items: stockResult.items,
+            },
+        }, { total: stockResult.totalCount, page: Math.floor(offset / Math.max(size, 1)) + 1, pageSize: size });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
+        return errorResponse(c, 'CU_INVENTORY_CHECK_FAILED', message, 500);
+    }
+}