daiso 1.0.4 → 1.0.6

package/dist/services/daiso/tools/findInventoryByName.js

@@ -0,0 +1,222 @@
+/**
+ * 상품명 기반 재고 통합 조회 도구
+ *
+ * 상품명과 위치만 아는 사용자를 위해 상품 검색과 재고 조회를 한 번에 수행합니다.
+ */
+import * as z from 'zod';
+import { fetchProducts } from './searchProducts.js';
+import { fetchOnlineStock, fetchStoreInventory } from './checkInventory.js';
+import { fetchStores } from './findStores.js';
+function buildTextResponse(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+    };
+}
+function buildEmptySummary(query, storeQuery) {
+    return {
+        headline: `"${query}" 상품 후보를 찾지 못했습니다.`,
+        selectedProduct: '',
+        storeQuery: storeQuery || '미지정',
+        inventorySummary: '상품 후보가 없어 온라인/매장 재고 조회를 건너뛰었습니다.',
+        displayLocationHint: '상품 후보를 먼저 확인한 뒤 daiso_get_display_location을 사용할 수 있습니다.',
+    };
+}
+async function resolveInventoryLocation(args) {
+    if (typeof args.latitude === 'number' && typeof args.longitude === 'number') {
+        return {
+            latitude: args.latitude,
+            longitude: args.longitude,
+            source: 'input',
+        };
+    }
+    if (args.storeQuery.trim().length > 0) {
+        const stores = await fetchStores(args.storeQuery);
+        const firstStore = stores[0];
+        if (firstStore) {
+            return {
+                latitude: firstStore.lat,
+                longitude: firstStore.lng,
+                source: 'storeQuery',
+                storeName: firstStore.name,
+                storeAddress: firstStore.address,
+            };
+        }
+    }
+    return {
+        latitude: args.latitude ?? 37.5665,
+        longitude: args.longitude ?? 126.978,
+        source: 'default',
+    };
+}
+function buildInventorySummary(args) {
+    const storeScope = args.storeQuery || '기본 위치 주변';
+    return {
+        headline: `"${args.query}" 조회 결과, "${args.selectedProductName}" 상품을 기준으로 재고를 확인했습니다.`,
+        selectedProduct: args.selectedProductName,
+        storeQuery: args.storeQuery || '미지정',
+        inventorySummary: `${storeScope} 매장 ${args.totalStores}곳 중 ${args.inStockCount}곳에서 재고가 확인되었습니다. 온라인 재고는 ${args.onlineStock}개입니다.`,
+        displayLocationHint: '진열 위치가 필요하면 storeInventory.stores[].storeCode로 daiso_get_display_location을 호출하세요.',
+    };
+}
+function toSummary(product) {
+    return {
+        id: product.id,
+        name: product.name,
+        imageUrl: product.imageUrl,
+        brand: product.brand,
+        soldOut: product.soldOut,
+        isNew: product.isNew,
+    };
+}
+function normalizeProductName(value) {
+    return value.toLowerCase().replace(/\s+/g, '');
+}
+function scoreProductCandidate(query, candidate, index) {
+    const normalizedQuery = normalizeProductName(query);
+    const normalizedName = normalizeProductName(candidate.name);
+    const exactMatchScore = normalizedName === normalizedQuery ? 100 : 0;
+    const availabilityScore = candidate.soldOut ? 0 : 20;
+    const startsWithScore = normalizedName.startsWith(normalizedQuery) ? 10 : 0;
+    const containsScore = normalizedName.includes(normalizedQuery) ? 5 : 0;
+    return exactMatchScore + availabilityScore + startsWithScore + containsScore - index / 1000;
+}
+function selectProductCandidate(query, candidates) {
+    return (candidates
+        .map((candidate, index) => ({
+        candidate,
+        score: scoreProductCandidate(query, candidate, index),
+    }))
+        .sort((a, b) => b.score - a.score)[0]?.candidate ?? null);
+}
+async function findInventoryByName(args) {
+    const { query, storeQuery = '', latitude, longitude, page = 1, pageSize = 30, productLimit = 5, } = args;
+    if (!query || query.trim().length === 0) {
+        throw new Error('상품명(query)을 입력해주세요.');
+    }
+    const productResult = await fetchProducts(query, 1, productLimit);
+    const productCandidates = productResult.products.map(toSummary);
+    const selectedProduct = selectProductCandidate(query, productCandidates);
+    if (!selectedProduct) {
+        return buildTextResponse({
+            query,
+            storeQuery,
+            summary: buildEmptySummary(query, storeQuery),
+            productCandidates: [],
+            selectedProduct: null,
+            onlineStock: 0,
+            storeInventory: {
+                totalStores: 0,
+                inStockCount: 0,
+                outOfStockCount: 0,
+                page,
+                pageSize,
+                stores: [],
+            },
+            nextSteps: {
+                productSearchTool: 'daiso_search_products',
+                inventoryTool: 'daiso_check_inventory',
+                note: '상품 후보가 없어서 재고 조회를 진행하지 않았습니다.',
+            },
+        });
+    }
+    const resolvedLocation = await resolveInventoryLocation({
+        storeQuery,
+        latitude,
+        longitude,
+    });
+    const [onlineStock, storeResult] = await Promise.all([
+        fetchOnlineStock(selectedProduct.id),
+        fetchStoreInventory(selectedProduct.id, resolvedLocation.latitude, resolvedLocation.longitude, page, pageSize, storeQuery),
+    ]);
+    const stores = storeResult.stores;
+    const inStockCount = stores.filter((store) => store.quantity > 0).length;
+    const result = {
+        query,
+        storeQuery,
+        location: resolvedLocation,
+        summary: buildInventorySummary({
+            query,
+            storeQuery,
+            selectedProductName: selectedProduct.name,
+            onlineStock,
+            inStockCount,
+            totalStores: storeResult.totalCount,
+        }),
+        productCandidates,
+        selectedProduct,
+        onlineStock,
+        storeInventory: {
+            totalStores: storeResult.totalCount,
+            inStockCount,
+            outOfStockCount: stores.filter((store) => store.quantity === 0).length,
+            page,
+            pageSize,
+            stores,
+        },
+        nextSteps: {
+            productSearchTool: 'daiso_search_products',
+            inventoryTool: 'daiso_check_inventory',
+            displayLocationTool: 'daiso_get_display_location',
+            storeCodeSource: '진열 위치가 필요하면 storeInventory.stores[].storeCode를 사용하세요.',
+        },
+    };
+    return buildTextResponse(result);
+}
+const inventoryByNameOutputSchema = {
+    query: z.string().describe('사용자가 입력한 상품 검색어'),
+    storeQuery: z.string().describe('사용자가 입력한 위치 키워드'),
+    location: z
+        .object({
+        latitude: z.number(),
+        longitude: z.number(),
+        source: z.enum(['input', 'storeQuery', 'default']),
+        storeName: z.string().optional(),
+        storeAddress: z.string().optional(),
+    })
+        .optional()
+        .describe('재고 조회에 사용한 위치와 위치 해석 출처'),
+    summary: z
+        .object({
+        headline: z.string(),
+        selectedProduct: z.string(),
+        storeQuery: z.string(),
+        inventorySummary: z.string(),
+        displayLocationHint: z.string(),
+    })
+        .describe('사용자에게 바로 보여줄 요약'),
+    productCandidates: z.array(z.unknown()).describe('검색된 상품 후보 목록'),
+    selectedProduct: z.unknown().nullable().describe('재고 조회 기준으로 선택한 상품'),
+    onlineStock: z.number().describe('온라인 재고 수량'),
+    storeInventory: z
+        .object({
+        totalStores: z.number(),
+        inStockCount: z.number(),
+        outOfStockCount: z.number(),
+        page: z.number(),
+        pageSize: z.number(),
+        stores: z.array(z.unknown()),
+    })
+        .describe('매장별 재고 조회 결과'),
+    nextSteps: z.record(z.string(), z.unknown()).describe('후속 도구 호출 안내'),
+};
+export function createFindInventoryByNameTool() {
+    return {
+        name: 'daiso_find_inventory_by_name',
+        metadata: {
+            title: '상품명 기반 재고 통합 조회',
+            description: '상품명과 대강의 위치만 아는 사용자를 위해 제품 검색부터 재고 조회까지 한 번에 수행합니다. 결과의 storeInventory.stores[].storeCode는 진열 위치 조회에 사용할 수 있습니다.',
+            inputSchema: {
+                query: z.string().describe('검색할 상품명 또는 키워드'),
+                storeQuery: z.string().optional().describe('역명, 동네, 매장명 같은 대강의 위치'),
+                latitude: z.number().optional().describe('위도 (생략 시 서울 시청 37.5665)'),
+                longitude: z.number().optional().describe('경도 (생략 시 서울 시청 126.978)'),
+                page: z.number().optional().default(1).describe('재고 매장 페이지 번호 (기본값: 1)'),
+                pageSize: z.number().optional().default(30).describe('재고 매장 페이지 크기 (기본값: 30)'),
+                productLimit: z.number().optional().default(5).describe('상품 후보 수 (기본값: 5)'),
+            },
+            outputSchema: inventoryByNameOutputSchema,
+        },
+        handler: findInventoryByName,
+    };
+}

package/dist/services/daiso/tools/findStores.js

@@ -6,6 +6,7 @@
 import * as z from 'zod';
 import { DAISO_WEB_API, formatTime } from '../api.js';
 import { fetchDaisoHtml, fetchDaisoJson } from '../client.js';
+import { buildDaisoStoreKeywordVariants } from '../../../utils/daisoKeyword.js';
 /**
  * HTML에서 매장 정보 파싱
  */
@@ -75,13 +76,22 @@ function parseStoresFromHtml(html) {
  * 다이소 매장 검색 API 호출
  */
 export async function fetchStores(keyword, sido, gugun, dong) {
-    const url = new URL(DAISO_WEB_API.SHOP_SEARCH);
-    url.searchParams.set('name_address', keyword || '');
-    url.searchParams.set('sido', sido || '');
-    url.searchParams.set('gugun', gugun || '');
-    url.searchParams.set('dong', dong || '');
-    const html = await fetchDaisoHtml(url.toString());
-    return parseStoresFromHtml(html);
+    const searchKeywords = keyword && !sido && !gugun && !dong
+        ? buildDaisoStoreKeywordVariants(keyword)
+        : [keyword || ''];
+    for (const searchKeyword of searchKeywords) {
+        const url = new URL(DAISO_WEB_API.SHOP_SEARCH);
+        url.searchParams.set('name_address', searchKeyword);
+        url.searchParams.set('sido', sido || '');
+        url.searchParams.set('gugun', gugun || '');
+        url.searchParams.set('dong', dong || '');
+        const html = await fetchDaisoHtml(url.toString());
+        const stores = parseStoresFromHtml(html);
+        if (stores.length > 0) {
+            return stores;
+        }
+    }
+    return [];
 }
 /**
  * 시/도별 구/군 목록 조회

package/dist/services/daiso/tools/getDisplayLocation.js

@@ -0,0 +1,75 @@
+/**
+ * 진열 위치 조회 도구
+ *
+ * 다이소몰 API를 사용하여 매장 내 상품 진열 위치(구역/층)를 조회합니다.
+ */
+import * as z from 'zod';
+import { DAISOMALL_API } from '../api.js';
+import { fetchDaisoJsonWithAuth } from '../client.js';
+/**
+ * 매장 내 상품 진열 위치 조회
+ */
+export async function fetchDisplayLocation(productId, storeCode) {
+    const data = await fetchDaisoJsonWithAuth(DAISOMALL_API.DISPLAY_LOCATION, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ pdNo: productId, strCd: storeCode }),
+    });
+    if (!data.success) {
+        return {
+            productId,
+            storeCode,
+            hasLocation: false,
+            locations: [],
+            message: data.message ?? null,
+        };
+    }
+    const locations = Array.isArray(data.data)
+        ? data.data.map((item) => ({
+            zoneNo: String(item.zoneNo ?? ''),
+            stairNo: String(item.stairNo ?? ''),
+            storeErp: String(item.storeErp ?? storeCode),
+        }))
+        : [];
+    return {
+        productId,
+        storeCode,
+        hasLocation: locations.length > 0,
+        locations,
+    };
+}
+/**
+ * 진열 위치 조회 핸들러
+ */
+async function getDisplayLocation(args) {
+    const { productId, storeCode } = args;
+    if (!productId || productId.trim().length === 0) {
+        throw new Error('상품 ID(productId)를 입력해주세요.');
+    }
+    if (!storeCode || storeCode.trim().length === 0) {
+        throw new Error('매장 코드(storeCode)를 입력해주세요.');
+    }
+    const result = await fetchDisplayLocation(productId, storeCode);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+}
+/**
+ * 도구 등록 정보 생성
+ */
+export function createGetDisplayLocationTool() {
+    return {
+        name: 'daiso_get_display_location',
+        metadata: {
+            title: '진열 위치 조회',
+            description: '다이소 매장 내 상품의 진열 위치(구역/층)를 조회합니다. 상품 ID와 매장 코드가 필요합니다. storeCode를 모르면 먼저 daiso_check_inventory로 재고를 조회하고 storeInventory.stores[].storeCode를 사용하세요.',
+            inputSchema: {
+                productId: z.string().describe('상품 ID (daiso_search_products로 조회한 상품의 id)'),
+                storeCode: z
+                    .string()
+                    .describe('매장 코드. storeCode를 모르면 먼저 daiso_check_inventory 결과의 storeInventory.stores[].storeCode를 확인하세요.'),
+            },
+        },
+        handler: getDisplayLocation,
+    };
+}

package/dist/services/emart24/api.js

@@ -0,0 +1,11 @@
+/**
+ * 이마트24 API 엔드포인트 중앙 관리
+ */
+export const EMART24_API = {
+    WEB_BASE_URL: 'https://emart24.co.kr',
+    EVERSE_BASE_URL: 'https://everse.emart24.co.kr',
+    STORE_PATH: '/api1/store',
+    PRODUCT_SEARCH_PATH: '/stock/stock/search',
+    STOCK_SEARCH_STORE_PATH: '/api/stock/v2/stock-search/store',
+    STORE_DETAIL_PATH_PREFIX: '/api/stock/stock/store/',
+};

package/dist/services/emart24/client.js

@@ -0,0 +1,182 @@
+/**
+ * 이마트24 API 클라이언트
+ */
+import { fetchJson } from '../../utils/http.js';
+import { EMART24_API } from './api.js';
+const EMART24_JSON_HEADERS = {
+    Accept: 'application/json, text/javascript, */*; q=0.01',
+    'X-Requested-With': 'XMLHttpRequest',
+};
+const EMART24_FORM_HEADERS = {
+    'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8',
+    Accept: 'application/json, text/javascript, */*; q=0.01',
+    'X-Requested-With': 'XMLHttpRequest',
+};
+const EMART24_DEFAULT_FETCH_OPTIONS = {
+    retries: 1,
+    retryDelayMs: 250,
+};
+function buildKeywordVariants(keyword) {
+    const trimmed = keyword.trim();
+    if (trimmed.length === 0) {
+        return [''];
+    }
+    const tokens = trimmed.split(/\s+/).filter((token) => token.length > 0);
+    const variants = [
+        trimmed,
+        trimmed.replace(/\s+/g, ''),
+        ...tokens,
+        ...tokens.map((token) => token.replace(/역$/, '')),
+    ].filter((value) => value.length > 0);
+    return [...new Set(variants)];
+}
+function toNumber(value) {
+    if (typeof value === 'number') {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number.parseFloat(value);
+        return Number.isFinite(parsed) ? parsed : 0;
+    }
+    return 0;
+}
+function toBooleanFlag(value) {
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    const normalized = String(value || '').trim().toUpperCase();
+    return normalized === '1' || normalized === 'Y' || normalized === 'TRUE';
+}
+function toStore(item) {
+    return {
+        storeCode: item.CODE || '',
+        storeName: item.TITLE || '',
+        address: item.ADDRESS || '',
+        addressDetail: item.ADDRESS_DE || '',
+        phone: item.PHONE || '',
+        latitude: toNumber(item.LATITUDE),
+        longitude: toNumber(item.LONGITUDE),
+        openTime: item.START_HHMM || '',
+        closeTime: item.END_HHMM || '',
+        openDate: item.OPEN_DATE || '',
+        endDate: item.END_DATE || '',
+        service24h: toBooleanFlag(item.SVR_24),
+        distanceM: null,
+    };
+}
+function toProduct(item) {
+    return {
+        pluCd: item.pluCd || '',
+        goodsName: item.goodsNm || '',
+        originPrice: toNumber(item.originPrice),
+        viewPrice: toNumber(item.viewPrice),
+        category: item.categoryNm || '',
+        kind: item.kindNm || '',
+    };
+}
+export function calculateDistanceM(lat1, lng1, lat2, lng2) {
+    const toRad = (deg) => (deg * Math.PI) / 180;
+    const dLat = toRad(lat2 - lat1);
+    const dLng = toRad(lng2 - lng1);
+    const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+        Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLng / 2) * Math.sin(dLng / 2);
+    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    return Math.round(6371000 * c);
+}
+export async function fetchEmart24Stores(params = {}, options = {}) {
+    const { timeout = 15000 } = options;
+    const { keyword = '', area1 = '', area2 = '', page = 1, service24h = false } = params;
+    const keywordVariants = buildKeywordVariants(keyword);
+    let lastError;
+    for (let index = 0; index < keywordVariants.length; index += 1) {
+        const searchKeyword = keywordVariants[index];
+        const endpoint = new URL(EMART24_API.STORE_PATH, EMART24_API.WEB_BASE_URL);
+        endpoint.searchParams.set('page', String(page));
+        if (searchKeyword.length > 0) {
+            endpoint.searchParams.set('search', searchKeyword);
+        }
+        if (area1.trim().length > 0) {
+            endpoint.searchParams.set('AREA1', area1.trim());
+        }
+        if (area2.trim().length > 0) {
+            endpoint.searchParams.set('AREA2', area2.trim());
+        }
+        if (service24h) {
+            endpoint.searchParams.set('SVR_24', '1');
+        }
+        const body = await fetchJson(endpoint.toString(), {
+            ...EMART24_DEFAULT_FETCH_OPTIONS,
+            method: 'GET',
+            timeout,
+            headers: EMART24_JSON_HEADERS,
+        });
+        if (body.error === 0 || body.error === undefined) {
+            const stores = (body.data || []).map(toStore).filter((store) => store.storeCode.length > 0);
+            return {
+                totalCount: toNumber(body.count),
+                stores,
+                appliedKeyword: searchKeyword,
+            };
+        }
+        lastError = body.error;
+        const hasMoreVariants = index < keywordVariants.length - 1;
+        if (body.error !== 1 || !hasMoreVariants) {
+            break;
+        }
+    }
+    throw new Error(`이마트24 매장 조회 실패: error=${lastError}`);
+}
+export async function searchEmart24Products(params, options = {}) {
+    const { keyword, page = 1, pageSize = 10, sortType = 'SALE', saleProductYn = 'N', } = params;
+    const { timeout = 15000 } = options;
+    const form = new URLSearchParams();
+    form.set('currentPage', String(page));
+    form.set('pageCnt', String(pageSize));
+    form.set('sortType', sortType);
+    form.set('saleProductYn', saleProductYn);
+    form.set('searchWord', keyword.trim());
+    const body = await fetchJson(`${EMART24_API.EVERSE_BASE_URL}${EMART24_API.PRODUCT_SEARCH_PATH}`, {
+        ...EMART24_DEFAULT_FETCH_OPTIONS,
+        method: 'POST',
+        retryUnsafeMethods: true,
+        timeout,
+        headers: EMART24_FORM_HEADERS,
+        body: form.toString(),
+    });
+    const products = (body.productList || []).map(toProduct).filter((item) => item.pluCd.length > 0);
+    return {
+        totalCount: toNumber(body.totalCnt),
+        products,
+    };
+}
+export async function searchEmart24StockByStores(params, options = {}) {
+    const { timeout = 15000 } = options;
+    const { pluCd, bizNos } = params;
+    const filteredBizNos = bizNos.map((value) => value.trim()).filter((value) => value.length > 0);
+    if (filteredBizNos.length === 0) {
+        return {
+            storeGoodsInfo: {
+                pluCd,
+            },
+            storeGoodsQty: [],
+        };
+    }
+    const endpoint = new URL(EMART24_API.STOCK_SEARCH_STORE_PATH, EMART24_API.EVERSE_BASE_URL);
+    endpoint.searchParams.set('searchPluCode', pluCd);
+    endpoint.searchParams.set('bizNoArr', filteredBizNos.join(','));
+    return fetchJson(endpoint.toString(), {
+        ...EMART24_DEFAULT_FETCH_OPTIONS,
+        method: 'GET',
+        timeout,
+        headers: EMART24_JSON_HEADERS,
+    });
+}
+export async function fetchEmart24StoreDetail(bizNo, options = {}) {
+    const { timeout = 15000 } = options;
+    return fetchJson(`${EMART24_API.EVERSE_BASE_URL}${EMART24_API.STORE_DETAIL_PATH_PREFIX}${encodeURIComponent(bizNo)}`, {
+        ...EMART24_DEFAULT_FETCH_OPTIONS,
+        method: 'GET',
+        timeout,
+        headers: EMART24_JSON_HEADERS,
+    });
+}

package/dist/services/emart24/index.js

@@ -0,0 +1,22 @@
+/**
+ * 이마트24 서비스 프로바이더
+ */
+import { createFindNearbyStoresTool } from './tools/findNearbyStores.js';
+import { createSearchProductsTool } from './tools/searchProducts.js';
+import { createCheckInventoryTool } from './tools/checkInventory.js';
+const EMART24_METADATA = {
+    id: 'emart24',
+    name: '이마트24',
+    version: '1.0.0',
+    description: '이마트24 매장 탐색, 상품 검색, 매장별 재고 조회 서비스',
+};
+class Emart24Service {
+    metadata = EMART24_METADATA;
+    getTools() {
+        return [createFindNearbyStoresTool(), createSearchProductsTool(), createCheckInventoryTool()];
+    }
+}
+export function createEmart24Service() {
+    return new Emart24Service();
+}
+export * from './types.js';

package/dist/services/emart24/inventoryLookup.js

@@ -0,0 +1,134 @@
+/**
+ * 이마트24 재고 조회 공통 로직
+ */
+import { calculateDistanceM, fetchEmart24StoreDetail, fetchEmart24Stores, searchEmart24Products, searchEmart24StockByStores, } from './client.js';
+async function resolvePluCd(pluCd, keyword, productPage, productPageSize, timeoutMs) {
+    const normalizedPluCd = (pluCd || '').trim();
+    if (normalizedPluCd.length > 0) {
+        return {
+            pluCd: normalizedPluCd,
+            products: [],
+        };
+    }
+    if (keyword.trim().length === 0) {
+        throw new Error('pluCd 또는 keyword 중 하나는 반드시 입력해주세요.');
+    }
+    const productResult = await searchEmart24Products({
+        keyword,
+        page: productPage,
+        pageSize: productPageSize,
+    }, {
+        timeout: timeoutMs,
+    });
+    const firstProduct = productResult.products.find((item) => item.pluCd.trim().length > 0);
+    if (!firstProduct) {
+        throw new Error('상품 검색 결과에서 PLU 코드를 찾을 수 없습니다.');
+    }
+    return {
+        pluCd: firstProduct.pluCd,
+        products: productResult.products,
+    };
+}
+function sortStoresByDistance(stores, latitude, longitude) {
+    return [...stores]
+        .map((store) => {
+        if (typeof latitude !== 'number' ||
+            typeof longitude !== 'number' ||
+            store.latitude === 0 ||
+            store.longitude === 0) {
+            return {
+                store,
+                sortDistance: Number.MAX_SAFE_INTEGER,
+            };
+        }
+        const distanceM = calculateDistanceM(latitude, longitude, store.latitude, store.longitude);
+        return {
+            store: {
+                ...store,
+                distanceM,
+            },
+            sortDistance: distanceM,
+        };
+    })
+        .sort((a, b) => a.sortDistance - b.sortDistance)
+        .map((entry) => entry.store);
+}
+export async function lookupEmart24Inventory(args) {
+    const { pluCd, keyword = '', latitude, longitude, storeKeyword = '', area1 = '', area2 = '', service24h = false, productPage = 1, productPageSize = 10, storeLimit = 10, timeoutMs = 15000, bizNos = [], includeRequestedStoresWithoutQty = false, } = args;
+    const resolved = await resolvePluCd(pluCd, keyword, productPage, productPageSize, timeoutMs);
+    const normalizedBizNos = [...new Set(bizNos.map((value) => value.trim()).filter((value) => value.length > 0))];
+    let nearbyStores = [];
+    let nearbyTotalCount = normalizedBizNos.length;
+    let appliedStoreKeyword = storeKeyword;
+    if (normalizedBizNos.length === 0) {
+        const nearbyStoreResult = await fetchEmart24Stores({
+            keyword: storeKeyword,
+            area1,
+            area2,
+            service24h,
+            page: 1,
+        }, {
+            timeout: timeoutMs,
+        });
+        appliedStoreKeyword = nearbyStoreResult.appliedKeyword;
+        nearbyTotalCount = nearbyStoreResult.totalCount;
+        nearbyStores = sortStoresByDistance(nearbyStoreResult.stores, latitude, longitude).slice(0, storeLimit);
+    }
+    const requestedBizNos = normalizedBizNos.length > 0 ? normalizedBizNos : nearbyStores.map((store) => store.storeCode);
+    const stockResult = await searchEmart24StockByStores({
+        pluCd: resolved.pluCd,
+        bizNos: requestedBizNos,
+    }, {
+        timeout: timeoutMs,
+    });
+    const qtyByBizNo = new Map((stockResult.storeGoodsQty || []).map((item) => [
+        String(item.BIZNO || '').trim(),
+        Number.parseInt(String(item.BIZQTY || 0), 10) || 0,
+    ]));
+    const inventoryBizNos = includeRequestedStoresWithoutQty && requestedBizNos.length > 0
+        ? requestedBizNos
+        : (stockResult.storeGoodsQty || [])
+            .map((item) => String(item.BIZNO || '').trim())
+            .filter((value) => value.length > 0);
+    const detailResults = await Promise.allSettled(inventoryBizNos.map((bizNo) => fetchEmart24StoreDetail(bizNo, { timeout: timeoutMs })));
+    const nearbyStoreByCode = new Map(nearbyStores.map((store) => [store.storeCode, store]));
+    const stores = inventoryBizNos.map((bizNo, index) => {
+        const detail = detailResults[index];
+        const detailInfo = detail.status === 'fulfilled' ? detail.value.storeInfo : undefined;
+        const nearby = nearbyStoreByCode.get(bizNo);
+        return {
+            bizNo,
+            bizQty: qtyByBizNo.get(bizNo) ?? 0,
+            storeName: detailInfo?.storeNm || nearby?.storeName || '',
+            address: detailInfo?.storeAddr || nearby?.address || '',
+            phone: detailInfo?.tel || nearby?.phone || '',
+            distanceM: nearby?.distanceM ?? null,
+        };
+    });
+    return {
+        keyword,
+        pluCd: resolved.pluCd,
+        productCandidates: resolved.products,
+        location: typeof latitude === 'number' && typeof longitude === 'number'
+            ? { latitude, longitude }
+            : null,
+        storeFilters: {
+            storeKeyword,
+            appliedStoreKeyword,
+            area1,
+            area2,
+            service24h,
+            storeLimit,
+            directBizNos: normalizedBizNos,
+        },
+        nearbyStores: {
+            totalCount: nearbyTotalCount,
+            stores: nearbyStores,
+        },
+        inventory: {
+            goodsInfo: stockResult.storeGoodsInfo || null,
+            count: stores.length,
+            stores,
+        },
+    };
+}