daiso 1.0.7 → 1.0.9

package/dist/core/registry.js

@@ -3,133 +3,8 @@
  *
  * 서비스 프로바이더를 등록하고 MCP 서버에 도구를 연결합니다.
  */
-import * as z from 'zod';
 import { getErrorMessage, toStandardErrorDiagnostics } from './errors.js';
-const DEFAULT_OUTPUT_SCHEMA = z.object({}).loose().describe('도구 실행 결과(JSON 객체)');
-function createFallbackOutputSchema(toolName) {
-    if (toolName.includes('search_products') ||
-        toolName.includes('searchProducts') ||
-        toolName.endsWith('_products')) {
-        return {
-            keyword: z.string().optional(),
-            query: z.string().optional(),
-            page: z.number().optional(),
-            pageSize: z.number().optional(),
-            totalCount: z.number().optional(),
-            count: z.number().optional(),
-            products: z.array(z.unknown()).optional(),
-            note: z.string().optional(),
-        };
-    }
-    if (toolName.includes('find_stores') ||
-        toolName.includes('nearby_stores') ||
-        toolName.includes('search_stores')) {
-        return {
-            keyword: z.string().optional(),
-            searchParams: z.unknown().optional(),
-            location: z.unknown().optional(),
-            totalCount: z.number().optional(),
-            filteredCount: z.number().optional(),
-            count: z.number().optional(),
-            stores: z.array(z.unknown()).optional(),
-        };
-    }
-    if (toolName.includes('places')) {
-        return {
-            provider: z.string().optional(),
-            searchMode: z.string().optional(),
-            query: z.string().optional(),
-            category: z.string().optional(),
-            location: z.string().optional(),
-            totalCount: z.number().optional(),
-            count: z.number().optional(),
-            places: z.array(z.unknown()).optional(),
-        };
-    }
-    if (toolName.includes('inventory')) {
-        return {
-            productId: z.string().optional(),
-            keyword: z.string().optional(),
-            itemCode: z.string().nullable().optional(),
-            location: z.unknown().optional(),
-            product: z.unknown().optional(),
-            onlineStock: z.number().optional(),
-            inventory: z.unknown().optional(),
-            storeInventory: z.unknown().optional(),
-        };
-    }
-    if (toolName.includes('display_location')) {
-        return {
-            productId: z.string().optional(),
-            storeCode: z.string().optional(),
-            displayLocation: z.unknown().optional(),
-            locations: z.array(z.unknown()).optional(),
-        };
-    }
-    if (toolName.includes('price_info')) {
-        return {
-            productId: z.string().optional(),
-            productName: z.string().optional(),
-            product: z.unknown().optional(),
-            price: z.number().optional(),
-        };
-    }
-    if (toolName.includes('theater')) {
-        return {
-            keyword: z.string().optional(),
-            location: z.unknown().optional(),
-            count: z.number().optional(),
-            theaters: z.array(z.unknown()).optional(),
-        };
-    }
-    if (toolName.includes('movie') || toolName.includes('now_showing')) {
-        return {
-            keyword: z.string().optional(),
-            playDate: z.string().optional(),
-            theaterCode: z.string().optional(),
-            count: z.number().optional(),
-            movies: z.array(z.unknown()).optional(),
-        };
-    }
-    if (toolName.includes('timetable') || toolName.includes('remaining_seats')) {
-        return {
-            playDate: z.string().optional(),
-            theaterCode: z.string().optional(),
-            movieCode: z.string().optional(),
-            count: z.number().optional(),
-            showtimes: z.array(z.unknown()).optional(),
-            seats: z.array(z.unknown()).optional(),
-        };
-    }
-    if (toolName.includes('popwords')) {
-        return {
-            label: z.string().optional(),
-            keywords: z.array(z.string()).optional(),
-            count: z.number().optional(),
-        };
-    }
-    if (toolName.includes('catalog')) {
-        return {
-            pages: z.array(z.unknown()).optional(),
-            issues: z.array(z.unknown()).optional(),
-            exhibitions: z.array(z.unknown()).optional(),
-            count: z.number().optional(),
-        };
-    }
-    return {};
-}
-function createToolOutputSchema(toolName, outputSchema) {
-    const schema = outputSchema || createFallbackOutputSchema(toolName);
-    if (Object.keys(schema).length === 0) {
-        return DEFAULT_OUTPUT_SCHEMA;
-    }
-    return z
-        .object({
-        ...schema,
-        standard: z.unknown().optional().describe('서비스 공통 상품/매장/영화관 정규화 결과'),
-    })
-        .loose();
-}
+import { createToolOutputSchema } from './outputSchema.js';
 function parseJsonText(text) {
     try {
         const parsed = JSON.parse(text);

package/dist/index.js

@@ -20,6 +20,9 @@ import { createEmart24Service } from './services/emart24/index.js';
 import { createGs25Service } from './services/gs25/index.js';
 import { createSevenElevenService } from './services/seveneleven/index.js';
 import { createPlacesService } from './services/places/index.js';
+import { createOpinetService } from './services/opinet/index.js';
+import { createCompareService } from './services/compare/index.js';
+import { createFeedbackService } from './services/feedback/index.js';
 import { createPromptResponse } from './pages/prompt.js';
 import { createFullOpenApiJsonResponse, createFullOpenApiYamlResponse, createOpenApiJsonResponse, createOpenApiYamlResponse, } from './pages/openapi.js';
 import { createPrivacyResponse } from './pages/privacy.js';
@@ -35,6 +38,9 @@ import { registerEmart24Routes } from './api/routes/emart24Routes.js';
 import { registerGs25Routes } from './api/routes/gs25Routes.js';
 import { registerSevenElevenRoutes } from './api/routes/sevenelevenRoutes.js';
 import { registerPlacesRoutes } from './api/routes/placesRoutes.js';
+import { registerOpinetRoutes } from './api/routes/opinetRoutes.js';
+import { registerCompareRoutes } from './api/routes/compareRoutes.js';
+import { registerFeedbackRoutes } from './api/routes/feedbackRoutes.js';
 import { registerHealthRoutes } from './api/routes/healthRoutes.js';
 import { buildConfigStatus } from './api/configStatus.js';
 // 서버 메타데이터
@@ -55,10 +61,19 @@ const createRegistry = (bindings) => {
             zyteApiKey: bindings?.ZYTE_API_KEY,
         }),
         createSevenElevenService,
+        createCompareService,
+        () => createFeedbackService({
+            supabaseUrl: bindings?.SUPABASE_URL,
+            supabaseServiceRoleKey: bindings?.SUPABASE_SERVICE_ROLE_KEY,
+        }),
         () => createPlacesService({
             naverClientId: bindings?.NAVER_CLIENT_ID,
             naverClientSecret: bindings?.NAVER_CLIENT_SECRET,
         }),
+        () => createOpinetService({
+            apiKey: bindings?.OPINET_API_KEY,
+            googleMapsApiKey: bindings?.GOOGLE_MAPS_API_KEY,
+        }),
         createCuService,
         createEmart24Service,
         () => createLotteMartService({
@@ -91,6 +106,53 @@ const createMcpServer = (bindings) => {
     registry.applyToServer(server);
     return server;
 };
+function buildRootInfo() {
+    const registry = createRegistry();
+    const services = registry.getServicesInfo();
+    const allTools = registry.getAllToolNames();
+    return {
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+        description: 'Multi-Service MCP Server for Cloudflare Workers',
+        endpoints: {
+            mcp: '/ 또는 /mcp (POST) - MCP 프로토콜 엔드포인트',
+            health: '/health (GET) - 헬스 체크',
+            healthChecks: '/api/health/checks (GET) - 서비스별 상세 헬스 체크',
+            openapi: '/openapi.json (GET) - OpenAI Actions용 축약 OpenAPI',
+            openapiFull: '/openapi-full.json (GET) - 전체 OpenAPI',
+            actionsQuery: '/api/actions/query (GET) - 기존 GET API 통합 facade',
+            compareProducts: '/api/compare/products (GET) - 키 없는 통합 상품 가격 후보 비교',
+            opinetAverage: '/api/opinet/average (GET) - 오피넷 전국 평균 유가',
+            opinetLowest: '/api/opinet/lowest (GET) - 오피넷 최저가 주유소',
+            developerRequests: '/api/feedback/requests (POST/GET) - 개발자 요청 제출',
+        },
+        services,
+        tools: allTools,
+        totalServices: services.length,
+        totalTools: allTools.length,
+    };
+}
+const ROOT_INFO_JSON = JSON.stringify(buildRootInfo());
+const ROOT_INFO_BODY = new TextEncoder().encode(ROOT_INFO_JSON);
+const ROOT_INFO_HEADERS = {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Content-Length': String(ROOT_INFO_BODY.byteLength),
+    'Access-Control-Allow-Origin': '*',
+    'Cache-Control': 'public, max-age=300, s-maxage=3600, stale-while-revalidate=86400',
+};
+function isRootInfoRequest(request) {
+    if (request.method !== 'GET' && request.method !== 'HEAD') {
+        return false;
+    }
+    const url = new URL(request.url);
+    return url.pathname === '/' && url.search === '';
+}
+function createRootInfoResponse(method) {
+    return new Response(method === 'HEAD' ? null : ROOT_INFO_BODY, {
+        status: 200,
+        headers: ROOT_INFO_HEADERS,
+    });
+}
 /**
  * initialize 요청 여부를 확인합니다.
  */
@@ -163,6 +225,24 @@ const handleMcpRequest = async (c) => {
         message: `세션이 없습니다. 먼저 POST /mcp initialize 요청 후 ${SESSION_HEADER} 헤더를 사용해주세요.`,
     }, 400);
 };
+const handleRootMcpRequest = async (c) => {
+    if (c.req.header(SESSION_HEADER) || c.req.method === 'DELETE') {
+        return handleMcpRequest(c);
+    }
+    const parsedBody = await c.req.raw
+        .clone()
+        .json()
+        .catch(() => undefined);
+    if (isInitializeRequest(parsedBody)) {
+        const { server, transport } = createSessionTransport(c.env);
+        await server.connect(transport);
+        return transport.handleRequest(c.req.raw, { parsedBody });
+    }
+    const transport = new WebStandardStreamableHTTPServerTransport();
+    const server = createMcpServer(c.env);
+    await server.connect(transport);
+    return transport.handleRequest(c.req.raw, { parsedBody });
+};
 // Hono 앱 생성
 const app = new Hono();
 // CORS 설정
@@ -181,34 +261,10 @@ app.use('*', cors({
 }));
 // 기본 정보 엔드포인트 (GET 요청만)
 app.get('/', (c) => {
-    const registry = createRegistry(c.env);
-    const services = registry.getServicesInfo();
-    const allTools = registry.getAllToolNames();
-    return c.json({
-        name: SERVER_NAME,
-        version: SERVER_VERSION,
-        description: 'Multi-Service MCP Server for Cloudflare Workers',
-        endpoints: {
-            mcp: '/ 또는 /mcp (POST) - MCP 프로토콜 엔드포인트',
-            health: '/health (GET) - 헬스 체크',
-            healthChecks: '/api/health/checks (GET) - 서비스별 상세 헬스 체크',
-            openapi: '/openapi.json (GET) - OpenAI Actions용 축약 OpenAPI',
-            openapiFull: '/openapi-full.json (GET) - 전체 OpenAPI',
-            actionsQuery: '/api/actions/query (GET) - 기존 GET API 통합 facade',
-        },
-        services,
-        tools: allTools,
-        totalServices: services.length,
-        totalTools: allTools.length,
-    });
-});
-// 루트 경로에서 MCP 요청 처리 (POST, DELETE, OPTIONS)
-app.on(['POST', 'DELETE', 'OPTIONS'], '/', async (c) => {
-    const transport = new WebStandardStreamableHTTPServerTransport();
-    const server = createMcpServer(c.env);
-    await server.connect(transport);
-    return transport.handleRequest(c.req.raw);
+    return c.body(ROOT_INFO_JSON, 200, ROOT_INFO_HEADERS);
 });
+// 루트 경로에서 MCP 요청 처리 (POST, DELETE)
+app.on(['POST', 'DELETE'], '/', handleRootMcpRequest);
 // 헬스 체크 엔드포인트
 app.get('/health', (c) => c.json({ status: 'ok', config: buildConfigStatus(c.env) }));
 registerHealthRoutes(app);
@@ -243,7 +299,10 @@ app.get('/privacy', (c) => {
 registerDaisoRoutes(app);
 registerGs25Routes(app);
 registerSevenElevenRoutes(app);
+registerCompareRoutes(app);
+registerFeedbackRoutes(app);
 registerPlacesRoutes(app);
+registerOpinetRoutes(app);
 registerCuRoutes(app);
 registerEmart24Routes(app);
 registerLotteMartRoutes(app);
@@ -274,4 +333,13 @@ app.get('/api/actions/query', async (c) => {
 });
 // MCP 엔드포인트
 app.all('/mcp', handleMcpRequest);
-export default app;
+const worker = {
+    fetch(request, env, executionCtx) {
+        if (isRootInfoRequest(request)) {
+            return createRootInfoResponse(request.method);
+        }
+        return app.fetch(request, env, executionCtx);
+    },
+    request: app.request.bind(app),
+};
+export default worker;

package/dist/pages/openapiFullSpec.js

@@ -11,6 +11,9 @@ import { OPENAPI_PATHS_LOTTECINEMA } from './openapiSpecPathsLottecinema.js';
 import { OPENAPI_PATHS_GS25 } from './openapiSpecPathsGs25.js';
 import { OPENAPI_PATHS_SEVENELEVEN } from './openapiSpecPathsSeveneleven.js';
 import { OPENAPI_PATHS_PLACES } from './openapiSpecPathsPlaces.js';
+import { OPENAPI_PATHS_OPINET } from './openapiSpecPathsOpinet.js';
+import { OPENAPI_PATHS_COMPARE } from './openapiSpecPathsCompare.js';
+import { OPENAPI_PATHS_FEEDBACK } from './openapiSpecPathsFeedback.js';
 import { OPENAPI_COMPONENTS } from './openapiSpecComponents.js';
 export function generateFullOpenApiSpec(baseUrl) {
     return {
@@ -26,11 +29,13 @@ export function generateFullOpenApiSpec(baseUrl) {
 - 🧭 **진열 위치 조회**: 매장 내 상품 구역/층 정보 조회
 - 🏪 **GS25 매장/상품/재고 조회**: GS25 매장 탐색, 상품 검색, 재고 조회
 - 7️⃣ **세븐일레븐 상품/매장/재고 조회**: 상품 검색, 매장 검색, 실재고 조회
+- 🧾 **통합 가격 후보 비교**: 새 외부 키 없이 상품 검색 결과를 묶어 가격 비교
 - 🏪 **CU 매장/재고 조회**: CU 매장 탐색 및 상품 재고 검색
 - 🎬 **메가박스 지점/영화 조회**: 주변 지점, 상영 목록, 잔여 좌석 조회
 - 🎞️ **롯데시네마 지점/영화 조회**: 주변 지점, 상영 목록, 잔여 좌석 조회
 - 🎥 **CGV 지점/영화 조회**: 극장 목록, 영화 목록, 시간표 조회
 - 🍽️ **주변 음식점/카페 검색**: 네이버 지역 검색 기반 장소 조회
+- ⛽ **오피넷 유가 정보**: 전국 평균 유가, 최저가 주유소, 반경 내 주유소 조회
 
 ## 사용 팁
 1. 한글 검색어는 URL 인코딩이 자동 처리됩니다
@@ -51,7 +56,10 @@ export function generateFullOpenApiSpec(baseUrl) {
             ...OPENAPI_PATHS_LOTTEMART,
             ...OPENAPI_PATHS_GS25,
             ...OPENAPI_PATHS_SEVENELEVEN,
+            ...OPENAPI_PATHS_COMPARE,
+            ...OPENAPI_PATHS_FEEDBACK,
             ...OPENAPI_PATHS_PLACES,
+            ...OPENAPI_PATHS_OPINET,
             ...OPENAPI_PATHS_MEGABOX,
             ...OPENAPI_PATHS_LOTTECINEMA,
             ...OPENAPI_PATHS_CGV,

package/dist/pages/openapiSpecActions.js

@@ -63,6 +63,76 @@ const ACTION_QUERY_PARAMETERS = [
         description: '주변 장소 카테고리(restaurant, cafe, food, dessert, all)',
         schema: { type: 'string' },
     },
+    {
+        name: 'services',
+        in: 'query',
+        required: false,
+        description: '통합 비교 서비스 목록(daiso,gs25,seveneleven,emart24)',
+        schema: { type: 'string' },
+    },
+    {
+        name: 'type',
+        in: 'query',
+        required: false,
+        description: '개발자 요청 유형(bug, improvement, feature, docs, other)',
+        schema: { type: 'string' },
+    },
+    {
+        name: 'severity',
+        in: 'query',
+        required: false,
+        description: '개발자 요청 영향도(low, medium, high, critical)',
+        schema: { type: 'string' },
+    },
+    {
+        name: 'title',
+        in: 'query',
+        required: false,
+        description: '개발자 요청 제목',
+        schema: { type: 'string' },
+    },
+    {
+        name: 'description',
+        in: 'query',
+        required: false,
+        description: '개발자 요청 상세 설명',
+        schema: { type: 'string' },
+    },
+    {
+        name: 'toolName',
+        in: 'query',
+        required: false,
+        description: '문제가 발생했거나 개선이 필요한 MCP 도구 이름',
+        schema: { type: 'string' },
+    },
+    {
+        name: 'reproduction',
+        in: 'query',
+        required: false,
+        description: '오류 재현 방법',
+        schema: { type: 'string' },
+    },
+    {
+        name: 'expected',
+        in: 'query',
+        required: false,
+        description: '기대 결과',
+        schema: { type: 'string' },
+    },
+    {
+        name: 'actual',
+        in: 'query',
+        required: false,
+        description: '실제 결과',
+        schema: { type: 'string' },
+    },
+    {
+        name: 'source',
+        in: 'query',
+        required: false,
+        description: '요청 출처(mcp, chatgpt, claude, cli, api, other)',
+        schema: { type: 'string' },
+    },
     {
         name: 'sido',
         in: 'query',

package/dist/pages/openapiSpecPathsCompare.js

@@ -0,0 +1,59 @@
+export const OPENAPI_PATHS_COMPARE = {
+    '/api/compare/products': {
+        get: {
+            operationId: 'compareProducts',
+            summary: '키 없는 통합 상품 가격 후보 비교',
+            description: '새 외부 키 없이 다이소, GS25, 세븐일레븐, 이마트24 상품 검색을 묶어 가격 후보를 비교합니다.',
+            parameters: [
+                {
+                    name: 'keyword',
+                    in: 'query',
+                    required: true,
+                    description: '비교할 상품 검색어',
+                    schema: { type: 'string' },
+                },
+                {
+                    name: 'services',
+                    in: 'query',
+                    required: false,
+                    description: '쉼표로 구분한 서비스 목록(daiso,gs25,seveneleven,emart24)',
+                    schema: { type: 'string' },
+                },
+                {
+                    name: 'limit',
+                    in: 'query',
+                    required: false,
+                    description: '서비스별 최대 결과 수',
+                    schema: { type: 'integer', default: 5, minimum: 1, maximum: 20 },
+                },
+            ],
+            responses: {
+                '200': {
+                    description: '통합 상품 가격 후보 비교 결과',
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                properties: {
+                                    success: { type: 'boolean' },
+                                    data: {
+                                        type: 'object',
+                                        properties: {
+                                            keyword: { type: 'string' },
+                                            serviceCount: { type: 'integer' },
+                                            resultCount: { type: 'integer' },
+                                            bestPrice: { type: ['object', 'null'] },
+                                            results: { type: 'array', items: { type: 'object' } },
+                                            errors: { type: 'array', items: { type: 'object' } },
+                                            note: { type: 'string' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};

package/dist/pages/openapiSpecPathsFeedback.js

@@ -0,0 +1,95 @@
+const REQUEST_PROPERTIES = {
+    type: {
+        type: 'string',
+        enum: ['bug', 'improvement', 'feature', 'docs', 'other'],
+        default: 'other',
+    },
+    severity: {
+        type: 'string',
+        enum: ['low', 'medium', 'high', 'critical'],
+        default: 'medium',
+    },
+    title: { type: 'string' },
+    description: { type: 'string' },
+    service: { type: 'string' },
+    toolName: { type: 'string' },
+    reproduction: { type: 'string' },
+    expected: { type: 'string' },
+    actual: { type: 'string' },
+    source: {
+        type: 'string',
+        enum: ['mcp', 'chatgpt', 'claude', 'cli', 'api', 'other'],
+    },
+};
+const RESPONSE_SCHEMA = {
+    type: 'object',
+    properties: {
+        success: { type: 'boolean' },
+        data: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                type: { type: 'string' },
+                severity: { type: 'string' },
+                title: { type: 'string' },
+                service: { type: 'string' },
+                toolName: { type: 'string' },
+                source: { type: 'string' },
+                status: { type: 'string' },
+                createdAt: { type: 'string' },
+            },
+        },
+    },
+};
+export const OPENAPI_PATHS_FEEDBACK = {
+    '/api/feedback/requests': {
+        post: {
+            operationId: 'submitDeveloperRequest',
+            summary: '개발자 요청 제출',
+            description: 'MCP 기능 오류, 개선 요청, 신규 기능 요청, 문서 문제를 개발자에게 전달하고 Supabase에 저장합니다.',
+            requestBody: {
+                required: true,
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            required: ['title', 'description'],
+                            properties: REQUEST_PROPERTIES,
+                        },
+                    },
+                },
+            },
+            responses: {
+                '200': {
+                    description: '개발자 요청 저장 결과',
+                    content: {
+                        'application/json': {
+                            schema: RESPONSE_SCHEMA,
+                        },
+                    },
+                },
+            },
+        },
+        get: {
+            operationId: 'submitDeveloperRequestViaQuery',
+            summary: '개발자 요청 제출(GET)',
+            description: 'OpenAI Actions facade 등 GET만 가능한 환경에서 개발자 요청을 제출합니다.',
+            parameters: Object.entries(REQUEST_PROPERTIES).map(([name, schema]) => ({
+                name,
+                in: 'query',
+                required: name === 'title' || name === 'description',
+                schema,
+            })),
+            responses: {
+                '200': {
+                    description: '개발자 요청 저장 결과',
+                    content: {
+                        'application/json': {
+                            schema: RESPONSE_SCHEMA,
+                        },
+                    },
+                },
+            },
+        },
+    },
+};

package/dist/pages/openapiSpecPathsOpinet.js

@@ -0,0 +1,81 @@
+/**
+ * OpenAPI 경로 정의 (오피넷)
+ */
+const fuelCodeSchema = {
+    type: 'string',
+    enum: ['B027', 'D047', 'B034', 'C004', 'K015'],
+    default: 'B027',
+};
+const successResponse = {
+    description: '조회 성공',
+    content: {
+        'application/json': {
+            schema: {
+                type: 'object',
+                properties: {
+                    success: { type: 'boolean' },
+                    data: { type: 'object' },
+                },
+            },
+        },
+    },
+};
+export const OPENAPI_PATHS_OPINET = {
+    '/api/opinet/average': {
+        get: {
+            operationId: 'opinetGetAveragePrices',
+            summary: '오피넷 전국 평균 유가',
+            description: '한국석유공사 오피넷 전국 평균 유가를 조회합니다.',
+            parameters: [],
+            responses: {
+                '200': successResponse,
+                '500': {
+                    description: '오피넷 키 누락 또는 API 호출 실패',
+                    content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
+                },
+            },
+        },
+    },
+    '/api/opinet/lowest': {
+        get: {
+            operationId: 'opinetGetLowestPriceStations',
+            summary: '오피넷 최저가 주유소',
+            description: '전국 또는 지역별 최저가 주유소를 유종별로 조회합니다.',
+            parameters: [
+                { name: 'fuelCode', in: 'query', required: false, description: '유종 코드', schema: fuelCodeSchema },
+                { name: 'areaCode', in: 'query', required: false, description: '오피넷 지역 코드', schema: { type: 'string' } },
+                { name: 'count', in: 'query', required: false, description: '결과 수(1~20)', schema: { type: 'integer', minimum: 1, maximum: 20, default: 10 } },
+            ],
+            responses: { '200': successResponse },
+        },
+    },
+    '/api/opinet/stations/around': {
+        get: {
+            operationId: 'opinetSearchStationsAround',
+            summary: '오피넷 반경 내 주유소',
+            description: 'KATEC x/y, WGS84 위경도, 또는 location 키워드 기준 반경 내 주유소를 조회합니다.',
+            parameters: [
+                { name: 'x', in: 'query', required: false, description: '기준 위치 X좌표(KATEC)', schema: { type: 'number' } },
+                { name: 'y', in: 'query', required: false, description: '기준 위치 Y좌표(KATEC)', schema: { type: 'number' } },
+                { name: 'lat', in: 'query', required: false, description: '위도(WGS84)', schema: { type: 'number' } },
+                { name: 'lng', in: 'query', required: false, description: '경도(WGS84)', schema: { type: 'number' } },
+                { name: 'location', in: 'query', required: false, description: '장소/주소 키워드. 예: 강남역', schema: { type: 'string' } },
+                { name: 'radiusMeters', in: 'query', required: false, description: '검색 반경 m(100~5000)', schema: { type: 'integer', minimum: 100, maximum: 5000, default: 3000 } },
+                { name: 'fuelCode', in: 'query', required: false, description: '유종 코드', schema: fuelCodeSchema },
+                { name: 'sort', in: 'query', required: false, description: '정렬 기준', schema: { type: 'string', enum: ['price', 'distance'], default: 'price' } },
+            ],
+            responses: { '200': successResponse },
+        },
+    },
+    '/api/opinet/station': {
+        get: {
+            operationId: 'opinetGetStationDetail',
+            summary: '오피넷 주유소 상세정보',
+            description: '오피넷 주유소 ID로 상세 정보, 부가시설, 유종별 가격을 조회합니다.',
+            parameters: [
+                { name: 'id', in: 'query', required: true, description: '오피넷 주유소 ID', schema: { type: 'string' } },
+            ],
+            responses: { '200': successResponse },
+        },
+    },
+};