daiso 1.0.5 → 1.0.6

package/README.md

@@ -5,9 +5,17 @@
 <br>
 <br>
 
-# Daiso MCP Server
+# Daiso MCP 및 Skill
 
-다이소(제품/매장/재고), 롯데마트(매장/상품), GS25(매장/상품/재고), 세븐일레븐(상품/매장/재고/인기검색어/카탈로그), CU(매장/재고), 이마트24(매장/상품/재고), 올리브영(매장/재고), 메가박스(지점/영화/시간표/좌석), 롯데시네마(지점/영화/좌석), CGV(극장/영화/시간표) 조회 기능을 AI에 연결합니다.
+다이소(제품/매장/재고), 롯데마트(매장/상품), GS25(매장/상품/재고), 세븐일레븐(상품/매장/재고/인기검색어/카탈로그), CU(매장/재고), 이마트24(매장/상품/재고), 올리브영(매장/재고), 메가박스(지점/영화/시간표/좌석), 롯데시네마(지점/영화/좌석), CGV(극장/영화/시간표) 조회 기능을 MCP, CLI, Codex Skill로 AI에 연결합니다.
+
+<br>
+
+**MCP:** `https://mcp.aka.page` · **CLI:** `npx daiso` · **Skill:** `clawhub install daiso-cli`
+
+**ClawHub:** [clawhub.ai/hmmhmmhm/daiso-cli](https://clawhub.ai/hmmhmmhm/daiso-cli)
+
+한국 로컬 리테일과 영화관 조회를 MCP, CLI, Codex Skill로 연결하는 도구입니다.
 
 <br>
 
@@ -21,11 +29,11 @@
 **[실시간 서비스 상태 보기](https://aka-page.betteruptime.com/)**
 
 <!-- WORKERS_INVOCATIONS_CHART:START -->
-<h3>Cloudflare Workers 호출량 (2026-03-01 ~ 2026-05-16, 77일)</h3>
+<h3>Cloudflare Workers 호출량 (2026-03-01 ~ 2026-05-19, 80일)</h3>
 
-<img src="./assets/analytics/workers-invocations.png?v=2026-05-16T15:44:19.119Z" alt="Cloudflare Workers 호출량 그래프 (2026-03-01 ~ 2026-05-16)" width="100%">
+<img src="./assets/analytics/workers-invocations.png?v=2026-05-19T16:35:34.414Z" alt="Cloudflare Workers 호출량 그래프 (2026-03-01 ~ 2026-05-19)" width="100%">
 
-<sub>기준 워커: <code>daiso-mcp</code> · 마지막 갱신: 2026-05-17 00:44 KST</sub>
+<sub>기준 워커: <code>daiso-mcp</code> · 마지막 갱신: 2026-05-20 01:35 KST</sub>
 
 <!-- WORKERS_INVOCATIONS_CHART:END -->
 
@@ -216,6 +224,17 @@ npx daiso get /api/cgv/movies --playDate 20260307 --theaterCode 0056
 npx daiso products 수납박스 --json
 ```
 
+### Codex Skill
+
+이 저장소는 MCP 서버뿐 아니라 에이전트가 `npx daiso` CLI를 직접 고를 수 있게 하는 Codex Skill도 제공합니다.
+
+- ClawHub: `clawhub install daiso-cli`
+- 공개 페이지: `https://clawhub.ai/hmmhmmhm/daiso-cli`
+- 스킬 파일: `skills/daiso-cli/SKILL.md`
+- 명령 맵: `skills/daiso-cli/references/cli-command-map.md`
+- 기본 원칙: 쉘 실행이 가능한 환경에서는 CLI를 우선 사용하고, AI 앱 연결이 필요할 때는 MCP 서버 URL `https://mcp.aka.page`를 사용합니다.
+- 구조화 결과가 필요하면 스킬은 `npx daiso ... --json` 형태를 선택합니다.
+
 ### OpenAPI 스펙
 
 - OpenAI 챗봇 등록용 축약 스펙: `https://mcp.aka.page/openapi.json`
@@ -223,6 +242,14 @@ npx daiso products 수납박스 --json
 - 전체 개별 엔드포인트 스펙(JSON): `https://mcp.aka.page/openapi-full.json`
 - 전체 개별 엔드포인트 스펙(YAML): `https://mcp.aka.page/openapi-full.yaml`
 
+### MCP 표준 응답 모델
+
+MCP 도구 응답은 각 서비스의 원본 필드를 유지하면서, 클라이언트가 공통 UI를 만들 수 있도록 `standard` 필드를 함께 제공합니다.
+
+- `standard.products`: 상품/영화 목록을 `code`, `name`, `price`, `imageUrl`, `raw` 형태로 정규화합니다.
+- `standard.stores`: 매장 목록을 `code`, `name`, `address`, `distanceMeters`, `raw` 형태로 정규화합니다.
+- `standard.theaters`: 영화관 목록을 `code`, `name`, `address`, `distanceMeters`, `raw` 형태로 정규화합니다.
+
 ### 운영 헬스 체크
 
 공개 상태 페이지: **[Daiso MCP Status](https://aka-page.betteruptime.com/)**
@@ -231,16 +258,26 @@ npx daiso products 수납박스 --json
 
 ```bash
 curl -H "Authorization: Bearer $HEALTH_CHECK_SECRET" \
-  "https://mcp.aka.page/api/health/checks?check=lottemart.products&fresh=true&includeSamples=true"
+  "https://mcp.aka.page/api/health/checks?mode=full&fresh=true&includeSamples=true&timeoutMs=20000&slowThresholdMs=9000"
 ```
 
 주요 쿼리:
 
 - `service=gs25`: 특정 서비스만 확인
 - `check=lottemart.products`: 특정 체크만 확인
-- `mode=quick|deep`: 체크 모드 선택
+- `mode=quick|deep|full`: 체크 모드 선택
 - `fresh=true`: 60초 캐시 우회
 - `includeSamples=true`: 첫 결과 이름 샘플 포함
+- `timeoutMs=20000`: 체크별 요청 제한 시간
+- `slowThresholdMs=9000`: 지정 시간보다 느린 성공 응답을 degraded로 표시
+
+상태 기준:
+
+- `ok`: 필수 응답 구조와 최소 결과가 정상입니다.
+- `degraded`: 기능은 살아 있지만 빈 결과, 느린 응답, 응답 구조 변화 등 확인이 필요합니다.
+- `fail`: 외부 API 오류, 타임아웃, 인증 문제처럼 실제 장애로 봐야 합니다.
+
+Better Stack 같은 외부 모니터링에서는 `fail`을 장애 알림 기준으로 보고, `degraded`는 느린 외부 API나 응답 품질 저하를 추적하는 경고 신호로 봅니다.
 
 배포 전 로컬에서 CLI 모드까지 확인할 때는 아래 명령을 사용합니다.
 
@@ -315,6 +352,7 @@ daiso 인터랙티브 모드
 
 - [@thecats1105](https://github.com/thecats1105): 다이소 진열 위치 조회 도구(`daiso_get_display_location`) 구현 및 API/테스트 연동
 - [@betterthanhajin](https://github.com/betterthanhajin): CGV 서비스 프로바이더 구현(극장/영화/시간표 도구, 라우트·스펙·테스트 추가)
+- [@LLagoon3](https://github.com/LLagoon3): 다이소 매장 재고 조회 신규 인증 흐름 전환 및 관련 테스트 보강
 - [제로초님](https://youtube.com/shorts/ZgIqA1NCEp0?si=UW0pKsSpqmEi7lXG): 프로젝트 홍보 도움
 
 <br>

package/dist/api/configStatus.js

@@ -0,0 +1,19 @@
+function isConfigured(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+export function buildConfigStatus(bindings) {
+    return {
+        googleMapsApiKey: {
+            configured: isConfigured(bindings?.GOOGLE_MAPS_API_KEY),
+            usedBy: ['gs25', 'cu', 'lottemart', 'megabox', 'lottecinema', 'cgv'],
+        },
+        zyteApiKey: {
+            configured: isConfigured(bindings?.ZYTE_API_KEY),
+            usedBy: ['oliveyoung', 'lottemart', 'cgv'],
+        },
+        healthCheckSecret: {
+            configured: isConfigured(bindings?.HEALTH_CHECK_SECRET),
+            usedBy: ['health-checks'],
+        },
+    };
+}

package/dist/api/gs25Handlers.js

@@ -143,22 +143,33 @@ export async function handleGs25CheckInventory(c) {
     }
     try {
         if ((typeof latitude !== 'number' || typeof longitude !== 'number') && storeKeyword.trim().length > 0) {
-            const baseStores = await fetchGs25Stores({
-                serviceCode,
-            }, {
-                timeout: 20000,
+            const directGeocoded = await geocodeGs25Address(storeKeyword, {
+                timeout: 15000,
+                googleMapsApiKey: c.env?.GOOGLE_MAPS_API_KEY,
             });
-            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 (directGeocoded) {
+                latitude = directGeocoded.latitude;
+                longitude = directGeocoded.longitude;
+                geocodeUsed = true;
+            }
+            else {
+                const baseStores = await fetchGs25Stores({
+                    serviceCode,
+                }, {
+                    timeout: 20000,
                 });
-                if (geocoded) {
-                    latitude = geocoded.latitude;
-                    longitude = geocoded.longitude;
-                    geocodeUsed = true;
+                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;
+                    }
                 }
             }
         }

package/dist/api/handlers.js

@@ -8,6 +8,19 @@ import { enrichOliveyoungProductsWithNearbyStoreInventory, fetchOliveyoungProduc
 import { fetchCuStock, fetchCuStores, geocodeCuAddress } from '../services/cu/client.js';
 import { errorResponse, successResponse } from './response.js';
 export { handleCheckInventory, handleFindStores, handleGetDisplayLocation, handleGetProduct, handleSearchProducts, } from './daisoHandlers.js';
+function parseBooleanQuery(value, defaultValue = false) {
+    if (!value) {
+        return defaultValue;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true' || normalized === '1' || normalized === 'y') {
+        return true;
+    }
+    if (normalized === 'false' || normalized === '0' || normalized === 'n') {
+        return false;
+    }
+    return defaultValue;
+}
 /**
  * 올리브영 상품 검색 API 핸들러
  * GET /api/oliveyoung/products?keyword={검색어}
@@ -18,6 +31,8 @@ export async function handleOliveyoungSearchProducts(c) {
     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)를 입력해주세요.');
     }
@@ -30,6 +45,7 @@ export async function handleOliveyoungSearchProducts(c) {
             includeSoldOut,
         }, {
             apiKey: c.env?.ZYTE_API_KEY,
+            timeout: timeoutMs,
         });
         return successResponse(c, {
             keyword,
@@ -54,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,
@@ -62,6 +80,7 @@ export async function handleOliveyoungFindStores(c) {
             searchWords: keyword,
         }, {
             apiKey: c.env?.ZYTE_API_KEY,
+            timeout: timeoutMs,
         });
         return successResponse(c, {
             stores: result.stores.slice(0, limit),
@@ -86,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)를 입력해주세요.');
     }
@@ -98,6 +121,7 @@ export async function handleOliveyoungCheckInventory(c) {
                 searchWords: storeKeyword,
             }, {
                 apiKey: c.env.ZYTE_API_KEY,
+                timeout: timeoutMs,
             }),
             fetchOliveyoungProducts({
                 keyword,
@@ -107,15 +131,17 @@ 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, 5),
+            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, {
@@ -191,6 +217,7 @@ export async function handleCuCheckInventory(c) {
     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)를 입력해주세요.');
     }
@@ -207,9 +234,11 @@ export async function handleCuCheckInventory(c) {
         const hasInputLocation = typeof lat === 'number' && typeof lng === 'number';
         const resolvedLat = hasInputLocation ? lat : undefined;
         const resolvedLng = hasInputLocation ? lng : undefined;
-        let storeResult = null;
+        let storeResult = storeCheck
+            ? null
+            : { totalCount: 0, stores: [] };
         // 좌표 미입력 + 매장 키워드 입력 시, 키워드 기반 매장 검색 결과를 우선 사용합니다.
-        if (!hasInputLocation && storeKeyword.trim().length > 0) {
+        if (storeCheck && !hasInputLocation && storeKeyword.trim().length > 0) {
             const keywordStoreResult = await fetchCuStores({
                 searchWord: storeKeyword,
             }, {

package/dist/api/healthChecks.js

@@ -2,8 +2,10 @@
  * 개별 서비스 헬스 체크 실행기
  */
 const HEALTH_CHECK_CACHE_TTL_MS = 60_000;
-const DEFAULT_HEALTH_CHECK_TIMEOUT_MS = 3000;
-const MAX_HEALTH_CHECK_TIMEOUT_MS = 10_000;
+const DEFAULT_HEALTH_CHECK_TIMEOUT_MS = 7000;
+const MAX_HEALTH_CHECK_TIMEOUT_MS = 20_000;
+const DEFAULT_HEALTH_CHECK_CONCURRENCY = 6;
+const DEFAULT_HEALTH_CHECK_SLOW_THRESHOLD_MS = 0;
 const HEALTH_CHECKS = [
     {
         id: 'cli.contract',
@@ -19,6 +21,8 @@ const HEALTH_CHECKS = [
         target: 'products',
         mode: 'quick',
         path: '/api/daiso/products?q=%ED%85%8C%EC%9D%B4%ED%94%84&pageSize=1',
+        collectionKey: 'products',
+        requiredFields: ['id', 'name', 'productName', 'itemName', 'goodsName'],
     },
     {
         id: 'cu.stores',
@@ -26,6 +30,8 @@ const HEALTH_CHECKS = [
         target: 'stores',
         mode: 'quick',
         path: '/api/cu/stores?keyword=%EA%B0%95%EB%82%A8&limit=1',
+        collectionKey: 'stores',
+        requiredFields: ['storeCode', 'storeName', 'name'],
     },
     {
         id: 'emart24.products',
@@ -33,6 +39,8 @@ const HEALTH_CHECKS = [
         target: 'products',
         mode: 'quick',
         path: '/api/emart24/products?keyword=%EC%BB%A4%ED%94%BC&pageSize=1',
+        collectionKey: 'products',
+        requiredFields: ['pluCd', 'goodsName', 'itemName', 'name'],
     },
     {
         id: 'gs25.products',
@@ -40,6 +48,8 @@ const HEALTH_CHECKS = [
         target: 'products',
         mode: 'quick',
         path: '/api/gs25/products?keyword=%EC%BD%9C%EB%9D%BC&limit=1',
+        collectionKey: 'products',
+        requiredFields: ['itemCode', 'itemName', 'name'],
     },
     {
         id: 'gs25.stores',
@@ -47,6 +57,8 @@ const HEALTH_CHECKS = [
         target: 'stores',
         mode: 'quick',
         path: '/api/gs25/stores?keyword=%EA%B0%95%EB%82%A8&limit=1',
+        collectionKey: 'stores',
+        requiredFields: ['storeCode', 'storeName', 'name'],
     },
     {
         id: 'seveneleven.products',
@@ -54,20 +66,26 @@ const HEALTH_CHECKS = [
         target: 'products',
         mode: 'quick',
         path: '/api/seveneleven/products?query=%EC%BB%A4%ED%94%BC&size=1',
+        collectionKey: 'products',
+        requiredFields: ['itemCode', 'itemName', 'productNo', 'name'],
     },
     {
         id: 'lottemart.products',
         service: 'lottemart',
         target: 'products',
         mode: 'quick',
-        path: '/api/lottemart/products?keyword=%EC%BD%9C%EB%9D%BC&storeCode=2301&area=%EC%84%9C%EC%9A%B8&pageLimit=1',
+        path: '/api/lottemart/products?keyword=%EC%BD%9C%EB%9D%BC&storeCode=2301&area=%EC%84%9C%EC%9A%B8&pageLimit=1&source=zetta',
+        collectionKey: 'products',
+        requiredFields: ['productCode', 'name', 'productName'],
     },
     {
         id: 'oliveyoung.products',
         service: 'oliveyoung',
         target: 'products',
         mode: 'quick',
-        path: '/api/oliveyoung/products?keyword=%EC%84%A0%ED%81%AC%EB%A6%BC&size=1',
+        path: '/api/oliveyoung/products?keyword=%EB%A6%BD%EB%B0%A4&size=1',
+        collectionKey: 'products',
+        requiredFields: ['goodsNumber', 'goodsName', 'productNo', 'productName', 'name'],
     },
     {
         id: 'megabox.theaters',
@@ -75,6 +93,8 @@ const HEALTH_CHECKS = [
         target: 'theaters',
         mode: 'quick',
         path: '/api/megabox/theaters?keyword=%EA%B0%95%EB%82%A8&limit=1',
+        collectionKey: 'theaters',
+        requiredFields: ['theaterCode', 'theaterName', 'name'],
     },
     {
         id: 'lottecinema.theaters',
@@ -82,6 +102,8 @@ const HEALTH_CHECKS = [
         target: 'theaters',
         mode: 'quick',
         path: '/api/lottecinema/theaters?keyword=%EC%9E%A0%EC%8B%A4&limit=1',
+        collectionKey: 'theaters',
+        requiredFields: ['theaterCode', 'theaterName', 'name'],
     },
     {
         id: 'cgv.theaters',
@@ -89,6 +111,53 @@ const HEALTH_CHECKS = [
         target: 'theaters',
         mode: 'quick',
         path: '/api/cgv/theaters?keyword=%EA%B0%95%EB%82%A8&limit=1',
+        collectionKey: 'theaters',
+        requiredFields: ['theaterCode', 'theaterName', 'name'],
+    },
+    {
+        id: 'cu.inventory',
+        service: 'cu',
+        target: 'inventory',
+        mode: 'deep',
+        path: '/api/cu/inventory?keyword=%EC%BB%A4%ED%94%BC&size=1&storeLimit=0&storeCheck=false',
+        collectionKey: 'inventoryItems',
+        requiredFields: ['itemCode', 'itemName', 'name'],
+    },
+    {
+        id: 'emart24.inventory',
+        service: 'emart24',
+        target: 'inventory',
+        mode: 'deep',
+        path: '/api/emart24/inventory?keyword=%EC%BB%A4%ED%94%BC&storeKeyword=%EA%B0%95%EB%82%A8&limit=1',
+        collectionKey: 'inventoryItems',
+        requiredFields: ['pluCd', 'goodsName', 'itemName', 'name'],
+    },
+    {
+        id: 'gs25.inventory',
+        service: 'gs25',
+        target: 'inventory',
+        mode: 'deep',
+        path: '/api/gs25/inventory?keyword=%EC%BD%9C%EB%9D%BC&storeKeyword=%EA%B0%95%EB%82%A8&limit=1',
+        collectionKey: 'inventoryItems',
+        requiredFields: ['itemCode', 'itemName', 'name'],
+    },
+    {
+        id: 'seveneleven.inventory',
+        service: 'seveneleven',
+        target: 'inventory',
+        mode: 'deep',
+        path: '/api/seveneleven/inventory?keyword=%EC%BB%A4%ED%94%BC&storeKeyword=%EA%B0%95%EB%82%A8&size=1',
+        collectionKey: 'inventoryItems',
+        requiredFields: ['itemCode', 'itemName', 'productNo', 'name'],
+    },
+    {
+        id: 'oliveyoung.inventory',
+        service: 'oliveyoung',
+        target: 'inventory',
+        mode: 'deep',
+        path: '/api/oliveyoung/inventory?keyword=%EC%84%A0%ED%81%AC%EB%A6%BC&storeKeyword=%EB%AA%85%EB%8F%99&size=1&storeLimit=1&stockCheckLimit=0',
+        collectionKey: 'inventoryProducts',
+        requiredFields: ['goodsNumber', 'goodsName', 'productNo', 'productName', 'name'],
     },
 ];
 const healthCheckCache = new Map();
@@ -105,13 +174,15 @@ function createCacheKey(params) {
         params.check || '',
         params.mode,
         params.timeoutMs,
+        params.slowThresholdMs || 0,
+        params.cacheBust ? 'cache-bust' : 'cache',
         params.includeSamples ? 'samples' : 'no-samples',
     ].join('|');
 }
 function selectChecks(params) {
     const mode = params.mode || 'quick';
     return HEALTH_CHECKS.filter((check) => {
-        if (check.mode !== mode) {
+        if (mode !== 'full' && check.mode !== mode) {
             return false;
         }
         if (params.service && check.service !== params.service) {
@@ -123,6 +194,19 @@ function selectChecks(params) {
         return true;
     });
 }
+async function mapWithConcurrency(items, concurrency, mapper) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const workerCount = Math.min(Math.max(1, concurrency), items.length);
+    await Promise.all(Array.from({ length: workerCount }, async () => {
+        while (nextIndex < items.length) {
+            const currentIndex = nextIndex;
+            nextIndex += 1;
+            results[currentIndex] = await mapper(items[currentIndex]);
+        }
+    }));
+    return results;
+}
 function toCount(data) {
     if (!data || typeof data !== 'object') {
         return null;
@@ -137,6 +221,15 @@ function toCount(data) {
             return value.length;
         }
     }
+    if (record.inventory && typeof record.inventory === 'object') {
+        const inventory = record.inventory;
+        for (const key of ['products', 'items']) {
+            const value = inventory[key];
+            if (Array.isArray(value)) {
+                return value.length;
+            }
+        }
+    }
     return null;
 }
 function toFirstName(data) {
@@ -156,8 +249,67 @@ function toFirstName(data) {
             }
         }
     }
+    if (record.inventory && typeof record.inventory === 'object') {
+        const inventory = record.inventory;
+        for (const key of ['products', 'items']) {
+            const value = inventory[key];
+            if (!Array.isArray(value) || !value[0] || typeof value[0] !== 'object') {
+                continue;
+            }
+            const item = value[0];
+            for (const nameKey of ['productName', 'itemName', 'goodsName', 'name']) {
+                if (typeof item[nameKey] === 'string' && item[nameKey].trim().length > 0) {
+                    return item[nameKey].trim();
+                }
+            }
+        }
+    }
     return undefined;
 }
+function getCollectionItems(data, collectionKey) {
+    if (!data || typeof data !== 'object') {
+        return [];
+    }
+    const record = data;
+    if (collectionKey === 'inventoryProducts' || collectionKey === 'inventoryItems') {
+        const inventory = record.inventory;
+        if (!inventory || typeof inventory !== 'object') {
+            return [];
+        }
+        const key = collectionKey === 'inventoryProducts' ? 'products' : 'items';
+        const value = inventory[key];
+        return Array.isArray(value) ? value : [];
+    }
+    if (collectionKey && Array.isArray(record[collectionKey])) {
+        return record[collectionKey];
+    }
+    for (const key of ['products', 'stores', 'theaters', 'movies', 'showtimes']) {
+        /* c8 ignore next -- 현재 정의된 체크는 collectionKey를 명시한다. */
+        if (Array.isArray(record[key])) {
+            return record[key];
+        }
+    }
+    return [];
+}
+function hasRequiredRepresentativeFields(data, collectionKey, requiredFields = []) {
+    /* c8 ignore next -- 현재 정의된 API 체크는 requiredFields를 명시한다. */
+    if (requiredFields.length === 0) {
+        return true;
+    }
+    const items = getCollectionItems(data, collectionKey);
+    if (items.length === 0) {
+        return true;
+    }
+    const first = items[0];
+    if (!first || typeof first !== 'object' || Array.isArray(first)) {
+        return false;
+    }
+    const record = first;
+    return requiredFields.some((field) => {
+        const value = record[field];
+        return typeof value === 'string' ? value.trim().length > 0 : value !== undefined && value !== null;
+    });
+}
 function aggregateStatus(checks) {
     if (checks.length === 0) {
         return 'skipped';
@@ -170,9 +322,12 @@ function aggregateStatus(checks) {
     }
     return 'ok';
 }
-function buildCheckUrl(baseUrl, check, timeoutMs) {
+function buildCheckUrl(baseUrl, check, timeoutMs, cacheBustValue) {
     const url = new URL(check.path, baseUrl);
     url.searchParams.set('timeoutMs', String(timeoutMs));
+    if (typeof cacheBustValue === 'number') {
+        url.searchParams.set('_healthCheck', String(cacheBustValue));
+    }
     return url.toString();
 }
 const CLI_CONTRACT_PATHS = [
@@ -201,10 +356,11 @@ function isCliCompatibleEnvelope(path, body) {
 }
 async function runCliContractCheck(check, params) {
     const startedAt = params.now();
+    const cacheBustValue = params.cacheBust ? startedAt : undefined;
     for (const path of CLI_CONTRACT_PATHS) {
         const syntheticCheck = { ...check, path };
         try {
-            const response = await params.fetchImpl(buildCheckUrl(params.baseUrl, syntheticCheck, params.timeoutMs), {
+            const response = await params.fetchImpl(buildCheckUrl(params.baseUrl, syntheticCheck, params.timeoutMs, cacheBustValue), {
                 signal: AbortSignal.timeout(params.timeoutMs),
             });
             const body = (await response.json().catch(() => ({})));
@@ -246,8 +402,9 @@ async function runSingleCheck(check, params) {
     }
     const timeoutMs = params.timeoutMs;
     const startedAt = params.now();
+    const cacheBustValue = params.cacheBust ? startedAt : undefined;
     try {
-        const response = await params.fetchImpl(buildCheckUrl(params.baseUrl, check, timeoutMs), {
+        const response = await params.fetchImpl(buildCheckUrl(params.baseUrl, check, timeoutMs, cacheBustValue), {
             signal: AbortSignal.timeout(timeoutMs),
         });
         const body = (await response.json().catch(() => ({})));
@@ -264,8 +421,18 @@ async function runSingleCheck(check, params) {
             };
         }
         const count = typeof body.meta?.total === 'number' ? body.meta.total : toCount(body.data);
-        const status = count === 0 ? 'degraded' : 'ok';
+        const shapeOk = hasRequiredRepresentativeFields(body.data, check.collectionKey, check.requiredFields);
+        const slowThresholdMs = params.slowThresholdMs || DEFAULT_HEALTH_CHECK_SLOW_THRESHOLD_MS;
+        const slow = slowThresholdMs > 0 && durationMs > slowThresholdMs;
+        const status = count === 0 || !shapeOk || slow ? 'degraded' : 'ok';
         const first = params.includeSamples ? toFirstName(body.data) : undefined;
+        const message = slow
+            ? `slow response: ${durationMs}ms > ${slowThresholdMs}ms`
+            : !shapeOk && count !== 0
+                ? `response missing required fields: ${check.requiredFields.join(', ')}`
+                : count === null
+                    ? 'response ok'
+                    : `${count} item(s) returned`;
         return {
             id: check.id,
             service: check.service,
@@ -273,7 +440,7 @@ async function runSingleCheck(check, params) {
             status,
             durationMs,
             httpStatus: response.status,
-            message: count === null ? 'response ok' : `${count} item(s) returned`,
+            message,
             ...(first ? { sample: { first } } : {}),
         };
     }
@@ -293,7 +460,10 @@ export async function runHealthChecks(params) {
     const fetchImpl = params.fetchImpl || ((input, init) => globalThis.fetch(input, init));
     const mode = params.mode || 'quick';
     const timeoutMs = clampTimeout(params.timeoutMs ?? DEFAULT_HEALTH_CHECK_TIMEOUT_MS);
-    const cacheKey = createCacheKey({ ...params, mode, timeoutMs, baseUrl: params.baseUrl });
+    const slowThresholdMs = Number.isFinite(params.slowThresholdMs) && params.slowThresholdMs && params.slowThresholdMs > 0
+        ? Math.trunc(params.slowThresholdMs)
+        : DEFAULT_HEALTH_CHECK_SLOW_THRESHOLD_MS;
+    const cacheKey = createCacheKey({ ...params, mode, timeoutMs, slowThresholdMs, baseUrl: params.baseUrl });
     const cached = healthCheckCache.get(cacheKey);
     const startedAt = now();
     if (!params.fresh && cached && cached.expiresAt > startedAt) {
@@ -302,13 +472,15 @@ export async function runHealthChecks(params) {
             cached: true,
         };
     }
-    const checks = await Promise.all(selectChecks(params).map((check) => runSingleCheck(check, {
+    const checks = await mapWithConcurrency(selectChecks(params), DEFAULT_HEALTH_CHECK_CONCURRENCY, (check) => runSingleCheck(check, {
         baseUrl: params.baseUrl,
         fetchImpl,
         now,
         timeoutMs,
+        slowThresholdMs,
         includeSamples: params.includeSamples,
-    })));
+        cacheBust: params.cacheBust,
+    }));
     const summary = {
         status: aggregateStatus(checks),
         checkedAt: new Date(startedAt).toISOString(),