mock-fried 1.0.1 → 1.0.3

package/README.md

@@ -160,8 +160,9 @@ const schema = await $api.getSchema()
 | Endpoint | Method | Description |
 |----------|--------|-------------|
 | `/mock/__schema` | GET | API 스키마 메타데이터 |
-| `/mock/**` | * | OpenAPI Mock 핸들러 |
+| `/mock/__reset` | POST | 캐시 초기화 |
 | `/mock/rpc/:service/:method` | POST | RPC Mock 핸들러 |
+| `/mock/**` | * | OpenAPI Mock 핸들러 |
 
 ## Development
 

package/dist/module.d.mts

@@ -50,12 +50,6 @@ interface MockCursorConfig {
      */
     includeSortInfo?: boolean;
 }
-/**
- * 응답 포맷 타입
- * - 'auto': 기존 동작 유지 (스키마 기반 자동)
- * - 'standardized': 표준화된 응답 형식
- */
-type MockResponseFormat = 'auto' | 'standardized';
 /**
  * Mock Module Options
  * nuxt.config.ts에서 mock 키로 설정
@@ -92,11 +86,6 @@ interface MockModuleOptions {
      * Cursor 설정
      */
     cursor?: MockCursorConfig;
-    /**
-     * 응답 포맷
-     * @default 'auto'
-     */
-    responseFormat?: MockResponseFormat;
 }
 /**
  * OpenAPI 클라이언트 패키지 설정

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=3.0.0"
   },
-  "version": "1.0.1",
+  "version": "1.0.3",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -113,8 +113,7 @@ const module$1 = defineNuxtModule({
       clientPackageConfig,
       protoPath,
       pagination: options.pagination,
-      cursor: options.cursor,
-      responseFormat: options.responseFormat ?? "auto"
+      cursor: options.cursor
     };
     nuxt.options.runtimeConfig.public.mock = {
       enable: options.enable,
@@ -126,6 +125,12 @@ const module$1 = defineNuxtModule({
       handler: resolver.resolve("./runtime/server/handlers/schema")
     });
     logger.info(`Schema handler registered at GET ${prefix}/__schema`);
+    addServerHandler({
+      route: `${prefix}/__reset`,
+      method: "post",
+      handler: resolver.resolve("./runtime/server/handlers/reset")
+    });
+    logger.info(`Reset handler registered at POST ${prefix}/__reset`);
     if (protoPath) {
       addServerHandler({
         route: `${prefix}/rpc/:service/:method`,

package/dist/runtime/plugin.js

@@ -17,9 +17,16 @@ export default defineNuxtPlugin(() => {
     };
     if (options?.body && fetchOptions.method !== "GET") {
       fetchOptions.body = JSON.stringify(options.body);
+      fetchOptions.headers = {
+        "Content-Type": "application/json",
+        ...fetchOptions.headers
+      };
     }
     if (options?.headers) {
-      fetchOptions.headers = options.headers;
+      fetchOptions.headers = {
+        ...fetchOptions.headers,
+        ...options.headers
+      };
     }
     let finalUrl = url;
     if (options?.params) {

package/dist/runtime/server/handlers/openapi.d.ts

@@ -1,2 +1,6 @@
+/**
+ * OpenAPI 관련 캐시 초기화
+ */
+export declare function clearOpenApiCache(): void;
 declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<any>>;
 export default _default;

package/dist/runtime/server/handlers/openapi.js

@@ -1,4 +1,4 @@
-import { defineEventHandler, getQuery, readBody, createError, getRequestURL } from "h3";
+import { defineEventHandler, getQuery, readBody, createError } from "h3";
 import { useRuntimeConfig } from "#imports";
 import { readFileSync } from "node:fs";
 import yaml from "js-yaml";
@@ -78,6 +78,15 @@ let cachedClientPath = null;
 let mockGenerator = null;
 let cursorPaginationManager = null;
 let pagePaginationManager = null;
+export function clearOpenApiCache() {
+  apiInstance = null;
+  cachedSpecPath = null;
+  cachedClientPackage = null;
+  cachedClientPath = null;
+  mockGenerator = null;
+  cursorPaginationManager = null;
+  pagePaginationManager = null;
+}
 function getClientPackageData(packagePath, config, paginationConfig, cursorConfig) {
   if (cachedClientPackage && cachedClientPath === packagePath && mockGenerator && cursorPaginationManager && pagePaginationManager) {
     return {
@@ -127,7 +136,7 @@ function findMatchingEndpoint(endpoints, path, method) {
   }
   return null;
 }
-function handleClientPackageRequest(pkg, generator, cursorManager, pageManager, path, method, query, _responseFormat = "auto") {
+function handleClientPackageRequest(pkg, generator, cursorManager, pageManager, path, method, query) {
   const match = findMatchingEndpoint(pkg.endpoints, path, method);
   if (!match) {
     return {
@@ -281,9 +290,8 @@ function handleClientPackageRequest(pkg, generator, cursorManager, pageManager,
 export default defineEventHandler(async (event) => {
   const config = useRuntimeConfig(event);
   const mockConfig = config.mock;
-  const requestUrl = getRequestURL(event);
   const prefix = mockConfig?.prefix || "/mock";
-  let path = requestUrl.pathname;
+  let path = event.path;
   if (path.startsWith(prefix)) {
     path = path.substring(prefix.length) || "/";
   }
@@ -310,8 +318,7 @@ export default defineEventHandler(async (event) => {
       pageManager,
       path,
       event.method,
-      query,
-      mockConfig.responseFormat ?? "auto"
+      query
     );
     if (result.statusCode) {
       event.node.res.statusCode = result.statusCode;

package/dist/runtime/server/handlers/reset.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 캐시 초기화 핸들러
+ * POST {prefix}/__reset
+ *
+ * 모든 캐시를 초기화하여 설정 변경사항을 즉시 반영할 수 있게 합니다.
+ * 개발 환경에서 핫리로드 후 캐시 문제 해결에 유용합니다.
+ *
+ * POST를 사용하는 이유: GET은 브라우저/CDN 프리페치로 의도치 않게 호출될 수 있음
+ */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, {
+    success: boolean;
+    message: string;
+    timestamp: string;
+}>;
+export default _default;

package/dist/runtime/server/handlers/reset.js

@@ -0,0 +1,18 @@
+import { defineEventHandler } from "h3";
+import { clearOpenApiCache } from "./openapi.js";
+import { clearProtoCache } from "./rpc.js";
+import { clearSchemaCache } from "./schema.js";
+import { clearClientPackageCache } from "../utils/client-parser.js";
+import { resetSnapshotStore } from "../utils/mock/pagination/index.js";
+export default defineEventHandler(() => {
+  clearOpenApiCache();
+  clearProtoCache();
+  clearSchemaCache();
+  clearClientPackageCache();
+  resetSnapshotStore();
+  return {
+    success: true,
+    message: "All caches have been reset",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+});

package/dist/runtime/server/handlers/rpc.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Proto 캐시 초기화
+ */
+export declare function clearProtoCache(): void;
 declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<{
     success: boolean;
     service: string;

package/dist/runtime/server/handlers/rpc.js

@@ -3,7 +3,7 @@ import { useRuntimeConfig } from "#imports";
 import * as protoLoader from "@grpc/proto-loader";
 import * as grpc from "@grpc/grpc-js";
 import { readdirSync, statSync } from "node:fs";
-import { join, extname } from "pathe";
+import { join, extname, dirname } from "pathe";
 import { generateMockMessage, deriveSeedFromRequest } from "../utils/mock/index.js";
 let protoCache = null;
 let cachedProtoPath = null;
@@ -47,13 +47,15 @@ async function loadProto(protoPath) {
   if (protoFiles.length === 0) {
     throw new Error(`No .proto files found in ${protoPath}`);
   }
+  const stat = statSync(protoPath);
+  const includeDir = stat.isFile() ? dirname(protoPath) : protoPath;
   const packageDefinition = await protoLoader.load(protoFiles, {
     keepCase: true,
     longs: String,
     enums: String,
     defaults: true,
     oneofs: true,
-    includeDirs: [protoPath]
+    includeDirs: [includeDir]
   });
   const grpcObject = grpc.loadPackageDefinition(packageDefinition);
   const services = /* @__PURE__ */ new Map();
@@ -66,6 +68,10 @@ async function loadProto(protoPath) {
   cachedProtoPath = protoPath;
   return protoCache;
 }
+export function clearProtoCache() {
+  protoCache = null;
+  cachedProtoPath = null;
+}
 function getResponseTypeInfo(methodDef) {
   const responseType = methodDef.responseType;
   if (responseType?.type) {

package/dist/runtime/server/handlers/schema.d.ts

@@ -1,4 +1,8 @@
 import type { ApiSchema } from '../../../types.js';
+/**
+ * 스키마 캐시 초기화
+ */
+export declare function clearSchemaCache(): void;
 /**
  * 스키마 핸들러
  * GET /mock/__schema

package/dist/runtime/server/handlers/schema.js

@@ -1,7 +1,92 @@
 import { defineEventHandler, createError } from "h3";
 import { useRuntimeConfig } from "#imports";
+import { consola } from "consola";
+import { createRequire } from "node:module";
 import { readFileSync, existsSync } from "node:fs";
+import yaml from "js-yaml";
+import { getClientPackage } from "../utils/client-parser.js";
+const logger = consola.withTag("mock-fried");
+const _require = createRequire(import.meta.url);
+function convertEndpointToPathItem(endpoint) {
+  const parameters = [
+    ...(endpoint.pathParams || []).map((p) => ({
+      name: p.name,
+      in: "path",
+      required: p.required,
+      schema: { type: p.type }
+    })),
+    ...(endpoint.queryParams || []).map((p) => ({
+      name: p.name,
+      in: "query",
+      required: p.required,
+      schema: { type: p.type }
+    }))
+  ];
+  return {
+    path: endpoint.path,
+    method: endpoint.method,
+    operationId: endpoint.operationId,
+    summary: endpoint.summary,
+    tags: endpoint.apiClassName ? [endpoint.apiClassName] : void 0,
+    parameters: parameters.length > 0 ? parameters : void 0,
+    requestBody: endpoint.requestBodyType ? {
+      content: {
+        "application/json": {
+          schema: { $ref: `#/components/schemas/${endpoint.requestBodyType}` }
+        }
+      }
+    } : void 0,
+    responses: {
+      200: {
+        description: "Success",
+        content: endpoint.responseType ? {
+          "application/json": {
+            schema: { $ref: `#/components/schemas/${endpoint.responseType}` }
+          }
+        } : void 0
+      }
+    }
+  };
+}
+function parseClientPackageSchema(config) {
+  try {
+    const packagePath = _require.resolve(`${config.package}/package.json`);
+    const packageRoot = packagePath.replace("/package.json", "").replace("\\package.json", "");
+    const clientPackage = getClientPackage(packageRoot, config);
+    const apiGroups = /* @__PURE__ */ new Map();
+    for (const endpoint of clientPackage.endpoints) {
+      const apiName = endpoint.apiClassName || "default";
+      if (!apiGroups.has(apiName)) {
+        apiGroups.set(apiName, []);
+      }
+      apiGroups.get(apiName).push(endpoint);
+    }
+    const pathItems = clientPackage.endpoints.map(convertEndpointToPathItem);
+    return {
+      info: {
+        title: clientPackage.info.title || clientPackage.info.name || "Unknown API",
+        version: clientPackage.info.version || "1.0.0",
+        description: `Generated from ${config.package}`
+      },
+      paths: pathItems,
+      // 추가 메타데이터: 모델 수, API 클래스 목록
+      _meta: {
+        source: "client-package",
+        package: config.package,
+        apiClasses: Array.from(apiGroups.keys()),
+        modelCount: clientPackage.models.size,
+        endpointCount: clientPackage.endpoints.length
+      }
+    };
+  } catch (error) {
+    logger.error("Failed to parse client package:", error);
+    return void 0;
+  }
+}
 let cachedSchema = null;
+export function clearSchemaCache() {
+  cachedSchema = null;
+}
 function parseOpenApiSpec(specPath) {
   if (!existsSync(specPath)) {
     return void 0;
@@ -10,7 +95,6 @@ function parseOpenApiSpec(specPath) {
     const content = readFileSync(specPath, "utf-8");
     let spec;
     if (specPath.endsWith(".yaml") || specPath.endsWith(".yml")) {
-      const yaml = require("js-yaml");
       spec = yaml.load(content);
     } else {
       spec = JSON.parse(content);
@@ -18,15 +102,28 @@ function parseOpenApiSpec(specPath) {
     const info = spec.info || {};
     const paths = spec.paths || {};
     const pathItems = [];
-    for (const [path, methods] of Object.entries(paths)) {
-      for (const [method, operation] of Object.entries(methods)) {
+    for (const [path, pathItem] of Object.entries(paths)) {
+      const pathLevelParams = [];
+      if (Array.isArray(pathItem.parameters)) {
+        for (const param of pathItem.parameters) {
+          const p = param;
+          pathLevelParams.push({
+            name: p.name,
+            in: p.in,
+            required: p.required,
+            description: p.description,
+            schema: p.schema
+          });
+        }
+      }
+      for (const [method, operation] of Object.entries(pathItem)) {
         if (["get", "post", "put", "delete", "patch"].includes(method.toLowerCase())) {
           const op = operation;
-          const parameters = [];
+          const operationParams = [];
           if (Array.isArray(op.parameters)) {
             for (const param of op.parameters) {
               const p = param;
-              parameters.push({
+              operationParams.push({
                 name: p.name,
                 in: p.in,
                 required: p.required,
@@ -35,6 +132,17 @@ function parseOpenApiSpec(specPath) {
               });
             }
           }
+          const mergedParams = [...pathLevelParams];
+          for (const opParam of operationParams) {
+            const existingIndex = mergedParams.findIndex(
+              (p) => p.name === opParam.name && p.in === opParam.in
+            );
+            if (existingIndex >= 0) {
+              mergedParams[existingIndex] = opParam;
+            } else {
+              mergedParams.push(opParam);
+            }
+          }
           pathItems.push({
             path,
             method: method.toUpperCase(),
@@ -42,7 +150,7 @@ function parseOpenApiSpec(specPath) {
             summary: op.summary,
             description: op.description,
             tags: op.tags,
-            parameters: parameters.length > 0 ? parameters : void 0,
+            parameters: mergedParams.length > 0 ? mergedParams : void 0,
             requestBody: op.requestBody,
             responses: op.responses
           });
@@ -57,7 +165,8 @@ function parseOpenApiSpec(specPath) {
       },
       paths: pathItems
     };
-  } catch {
+  } catch (error) {
+    logger.error("Failed to parse OpenAPI spec:", specPath, error);
     return void 0;
   }
 }
@@ -112,7 +221,8 @@ async function parseProtoSpec(protoPath) {
       package: packageName,
       services
     };
-  } catch {
+  } catch (error) {
+    logger.error("Failed to parse Proto spec:", protoPath, error);
     return void 0;
   }
 }
@@ -167,7 +277,36 @@ export default defineEventHandler(async () => {
     return cachedSchema;
   }
   const schema = {};
-  if (mockConfig.openapiPath) {
+  if (mockConfig.clientPackageConfig?.package) {
+    const openapi = parseClientPackageSchema(mockConfig.clientPackageConfig);
+    if (openapi) {
+      schema.openapi = openapi;
+    }
+  } else if (mockConfig.clientPackagePath) {
+    const clientPkg = getClientPackage(mockConfig.clientPackagePath);
+    const apiGroups = /* @__PURE__ */ new Map();
+    for (const endpoint of clientPkg.endpoints) {
+      const apiName = endpoint.apiClassName || "default";
+      if (!apiGroups.has(apiName)) {
+        apiGroups.set(apiName, []);
+      }
+    }
+    const pathItems = clientPkg.endpoints.map(convertEndpointToPathItem);
+    schema.openapi = {
+      info: {
+        title: clientPkg.info.title || clientPkg.info.name || "Unknown API",
+        version: clientPkg.info.version || "1.0.0",
+        description: `Generated from client package`
+      },
+      paths: pathItems,
+      _meta: {
+        source: "client-package",
+        apiClasses: Array.from(apiGroups.keys()),
+        modelCount: clientPkg.models.size,
+        endpointCount: clientPkg.endpoints.length
+      }
+    };
+  } else if (mockConfig.openapiPath) {
     const openapi = parseOpenApiSpec(mockConfig.openapiPath);
     if (openapi) {
       schema.openapi = openapi;

package/dist/runtime/server/utils/mock/client-generator.d.ts

@@ -14,6 +14,7 @@ export declare function inferValueByFieldName(fieldName: string, rng: SeededRand
 export declare function generateValueByType(type: string, fieldName: string, rng: SeededRandom, index?: number, idConfig?: MockIdConfig): unknown;
 /**
  * 필드명에서 타입을 추측하여 적절한 값 생성
+ * (unknown/any/object 타입인 경우 사용)
  */
 export declare function inferTypeFromFieldName(fieldName: string, rng: SeededRandom, index: number, idConfig?: MockIdConfig): unknown;
 /**
@@ -46,23 +47,32 @@ export declare class SchemaMockGenerator {
      * 모델 스키마 기반 단일 객체 생성
      */
     generateOne(modelName: string, seed?: string | number, index?: number): Record<string, unknown>;
+    /**
+     * 내부 구현: 순환 참조 감지를 위한 재귀 생성
+     */
+    private generateOneInternal;
     /**
      * ID 부여된 단일 객체 생성 (Pagination용)
      * 주어진 ID를 모델의 ID 필드에 설정하여 cursor와 응답 ID가 일치하도록 함
+     * @param modelName 모델명
+     * @param itemId 아이템 ID (string 또는 number)
+     * @param seed 생성 seed
+     * @param index 인덱스
      */
-    generateOneWithId(modelName: string, itemId: string, seed?: string | number, index?: number): Record<string, unknown>;
+    generateOneWithId(modelName: string, itemId: string | number, seed?: string | number, index?: number): Record<string, unknown>;
     /**
      * 모델의 ID 필드명 찾기 (MockIdConfig 기반)
+     * public으로 변경하여 CursorPaginationManager에서 사용 가능
      */
-    private findIdFieldName;
+    findIdFieldName(modelName: string): string | null;
     /**
      * 필드의 출력 키 가져오기 (jsonKey 또는 name)
      */
     private getOutputKey;
     /**
-     * 필드 값 생성
+     * 필드 값 생성 (순환 참조 감지 포함)
      */
-    private generateField;
+    private generateFieldInternal;
     /**
      * 리스트 데이터 생성 (캐시 지원 - Pagination)
      * @deprecated Use pagination/page-manager.ts instead for enhanced pagination

package/dist/runtime/server/utils/mock/client-generator.js

@@ -33,22 +33,43 @@ export function inferValueByFieldName(fieldName, rng, index = 0, idConfig = DEFA
   if (name.includes("title") || name.includes("subject") || name.includes("headline")) {
     return `\uC0D8\uD50C ${fieldName} #${rng.nextInt(1, 100)}`;
   }
-  if (name.includes("status")) {
-    return rng.pick(["ACTIVE", "INACTIVE", "PENDING", "COMPLETED"]);
+  if (name.includes("status") || name.includes("state") || name.includes("stage")) {
+    return rng.pick(["ACTIVE", "INACTIVE", "PENDING", "COMPLETED", "APPROVED", "REJECTED"]);
+  }
+  if (name.includes("yearmonth") || name.includes("month") && !name.includes("months")) {
+    const year = 2024 + rng.nextInt(0, 1);
+    const month = rng.nextInt(1, 12);
+    return year * 100 + month;
+  }
+  if (name.includes("note") || name.includes("memo") || name.includes("remark") || name.includes("comment") || name.includes("message")) {
+    return `${fieldName} \uB0B4\uC6A9\uC785\uB2C8\uB2E4. #${rng.nextInt(1, 100)}`;
   }
-  if (name.includes("count") || name.includes("quantity") || name.includes("amount") || name.includes("num")) {
+  if (name.includes("count") || name.includes("quantity") || name.includes("num")) {
     return rng.nextInt(0, 100);
   }
-  if (name.includes("price") || name.includes("cost") || name.includes("fee") || name.includes("amount")) {
+  if (name.includes("rate") || name.includes("ratio") || name.includes("percent")) {
+    return `${rng.nextInt(1, 100)}`;
+  }
+  if (name.includes("amount") || name.includes("price") || name.includes("cost") || name.includes("fee") || name.includes("commission")) {
     return rng.nextInt(1e3, 1e5);
   }
   if (name === "page") return 1;
   if (name === "limit" || name === "size" || name === "pagesize") return 20;
   if (name === "total" || name === "totalcount" || name === "totalitems") return rng.nextInt(50, 500);
   if (name === "totalpages") return rng.nextInt(3, 25);
+  if (name.includes("sequence") || name.includes("order") || name.includes("priority") || name.includes("rank") || name === "sort") {
+    return rng.nextInt(1, 100);
+  }
   if (name.startsWith("is") || name.startsWith("has") || name.startsWith("can") || name.startsWith("should") || name.startsWith("will")) {
     return rng.next() > 0.5;
   }
+  if (name === "result" || name === "success" || name.includes("enabled") || name.includes("valid") || name.includes("complete")) {
+    return rng.next() > 0.5;
+  }
+  if (name.includes("owner") || name.includes("manager") || name.includes("author") || name.includes("writer") || name.includes("creator")) {
+    const names = ["\uAE40\uCCA0\uC218", "\uC774\uC601\uD76C", "\uBC15\uBBFC\uC218", "John", "Jane"];
+    return rng.pick(names);
+  }
   if (name.includes("address") || name.includes("street")) {
     return `\uC11C\uC6B8\uC2DC \uAC15\uB0A8\uAD6C \uD14C\uD5E4\uB780\uB85C ${rng.nextInt(1, 500)}\uBC88\uAE38`;
   }
@@ -61,18 +82,42 @@ export function inferValueByFieldName(fieldName, rng, index = 0, idConfig = DEFA
   if (name.includes("zipcode") || name.includes("postal")) {
     return `${rng.nextInt(1e4, 99999)}`;
   }
+  if (name.includes("bizreg") || name.includes("regno")) {
+    return `${rng.nextInt(100, 999)}-${rng.nextInt(10, 99)}-${rng.nextInt(1e4, 99999)}`;
+  }
   if (name.includes("code")) {
     return `CODE-${rng.nextInt(1e3, 9999)}`;
   }
   if (name.includes("type") || name.includes("category")) {
     return rng.pick(["TYPE_A", "TYPE_B", "TYPE_C"]);
   }
+  if (name.includes("tag") || name.includes("label")) {
+    return rng.pick(["\uD0DC\uADF81", "\uD0DC\uADF82", "\uD0DC\uADF83", "Tag A", "Tag B"]);
+  }
+  if (name.includes("scale") || name.includes("level") || name.includes("grade") || name.includes("tier")) {
+    return rng.pick(["SMALL", "MEDIUM", "LARGE", "LEVEL_1", "LEVEL_2", "LEVEL_3"]);
+  }
+  if (name.includes("days") || name.includes("months") || name.includes("weeks") || name.includes("years")) {
+    return rng.nextInt(1, 30);
+  }
+  if (name.includes("day") && !name.includes("days")) {
+    return rng.nextInt(1, 28);
+  }
+  if (name.includes("reason") || name.includes("cause")) {
+    return rng.pick(["\uC0AC\uC6A9\uC790 \uC694\uCCAD", "\uC2DC\uC2A4\uD15C \uCC98\uB9AC", "\uAE30\uAC04 \uB9CC\uB8CC", "\uC815\uCC45 \uBCC0\uACBD"]);
+  }
+  if (name.includes("password") || name.includes("pwd")) {
+    return "********";
+  }
   if (name.includes("version")) {
     return `${rng.nextInt(1, 10)}.${rng.nextInt(0, 9)}.${rng.nextInt(0, 99)}`;
   }
   if (name.includes("token") || name.includes("key") || name.includes("secret")) {
     return rng.uuid();
   }
+  if (name.includes("file") || name.includes("attachment") || name.includes("document")) {
+    return `https://storage.example.com/files/${rng.hashId(12)}.pdf`;
+  }
   return null;
 }
 export function generateValueByType(type, fieldName, rng, index = 0, idConfig = DEFAULT_ID_CONFIG) {
@@ -103,23 +148,49 @@ export function inferTypeFromFieldName(fieldName, rng, index, idConfig = DEFAULT
   if (isIdField(fieldName, idConfig)) {
     return generateIdValue(fieldName, index, rng.hashId(16), idConfig);
   }
-  if (name.includes("count") || name.includes("num") || name.includes("amount") || name.includes("size") || name.includes("total") || name.includes("views") || name.includes("likes") || name.includes("price") || name.includes("age") || name.includes("quantity") || name.includes("index") || name.includes("order")) {
+  if (name.includes("yearmonth")) {
+    const year = 2024 + rng.nextInt(0, 1);
+    const month = rng.nextInt(1, 12);
+    return year * 100 + month;
+  }
+  if (name.includes("count") || name.includes("num") || name.includes("amount") || name.includes("size") || name.includes("total") || name.includes("views") || name.includes("likes") || name.includes("price") || name.includes("age") || name.includes("quantity") || name.includes("index") || name.includes("order") || name.includes("sequence") || name.includes("priority") || name.includes("rank") || name.includes("fee") || name.includes("commission")) {
     return rng.nextInt(0, 1e3);
   }
-  if (name.startsWith("is") || name.startsWith("has") || name.startsWith("can") || name.startsWith("should") || name.startsWith("will") || name.includes("enabled") || name.includes("active") || name.includes("visible") || name.includes("valid")) {
+  if (name.includes("rate") || name.includes("ratio") || name.includes("percent")) {
+    return `${rng.nextInt(1, 100)}`;
+  }
+  if (name.startsWith("is") || name.startsWith("has") || name.startsWith("can") || name.startsWith("should") || name.startsWith("will") || name.includes("enabled") || name.includes("active") || name.includes("visible") || name.includes("valid") || name === "result" || name === "success" || name.includes("complete")) {
     return rng.next() > 0.5;
   }
-  if (name.includes("date") || name.endsWith("at") || name.includes("time") || name.includes("created") || name.includes("updated") || name.includes("modified")) {
+  if (name.includes("date") || name.endsWith("at") || name.includes("time") || name.includes("created") || name.includes("updated") || name.includes("modified") || name.includes("deadline")) {
     const now = Date.now();
     const offset = rng.nextInt(-365, 30) * 24 * 60 * 60 * 1e3;
     return new Date(now + offset).toISOString();
   }
+  if (name.includes("days") || name.includes("months") || name.includes("weeks") || name.includes("years")) {
+    return rng.nextInt(1, 30);
+  }
+  if (name.includes("day") && !name.includes("days")) {
+    return rng.nextInt(1, 28);
+  }
   if (name.includes("url") || name.includes("link") || name.includes("href")) {
     return `https://example.com/${fieldName}/${rng.nextInt(1, 1e3)}`;
   }
   if (name.includes("image") || name.includes("thumbnail") || name.includes("avatar") || name.includes("photo") || name.includes("picture")) {
     return `https://picsum.photos/seed/${rng.nextInt(1, 1e3)}/200/200`;
   }
+  if (name.includes("file") || name.includes("attachment") || name.includes("document")) {
+    return `https://storage.example.com/files/${rng.hashId(12)}.pdf`;
+  }
+  if (name.includes("status") || name.includes("state") || name.includes("stage")) {
+    return rng.pick(["ACTIVE", "INACTIVE", "PENDING", "COMPLETED"]);
+  }
+  if (name.includes("scale") || name.includes("level") || name.includes("grade") || name.includes("tier")) {
+    return rng.pick(["SMALL", "MEDIUM", "LARGE"]);
+  }
+  if (name.includes("reason") || name.includes("cause")) {
+    return rng.pick(["\uC0AC\uC6A9\uC790 \uC694\uCCAD", "\uC2DC\uC2A4\uD15C \uCC98\uB9AC", "\uAE30\uAC04 \uB9CC\uB8CC"]);
+  }
   return `mock-${fieldName}-${rng.nextInt(1, 1e3)}`;
 }
 export function extractDataModelName(responseType, models) {
@@ -168,6 +239,7 @@ export function extractDataModelName(responseType, models) {
   }
   return { modelName: responseType, isList: false };
 }
+const MAX_RECURSION_DEPTH = 5;
 export class SchemaMockGenerator {
   models;
   dataStore = /* @__PURE__ */ new Map();
@@ -180,18 +252,32 @@ export class SchemaMockGenerator {
    * 모델 스키마 기반 단일 객체 생성
    */
   generateOne(modelName, seed, index = 0) {
+    return this.generateOneInternal(modelName, seed, index, /* @__PURE__ */ new Set(), 0);
+  }
+  /**
+   * 내부 구현: 순환 참조 감지를 위한 재귀 생성
+   */
+  generateOneInternal(modelName, seed, index, visitedModels, depth) {
     const schema = this.models.get(modelName);
     if (!schema) {
       return {};
     }
+    if (visitedModels.has(modelName) && depth > 1) {
+      return {};
+    }
+    if (depth >= MAX_RECURSION_DEPTH) {
+      return {};
+    }
     if (schema.enumValues && schema.enumValues.length > 0) {
       const rng2 = new SeededRandom(seed ?? modelName);
       return { value: rng2.pick(schema.enumValues) };
     }
+    const newVisited = new Set(visitedModels);
+    newVisited.add(modelName);
     const rng = new SeededRandom(seed ?? `${modelName}-${index}`);
     const result = {};
     for (const field of schema.fields) {
-      const value = this.generateField(field, rng, index);
+      const value = this.generateFieldInternal(field, rng, index, newVisited, depth);
       if (value !== void 0) {
         const outputKey = field.jsonKey || field.name;
         result[outputKey] = value;
@@ -202,6 +288,10 @@ export class SchemaMockGenerator {
   /**
    * ID 부여된 단일 객체 생성 (Pagination용)
    * 주어진 ID를 모델의 ID 필드에 설정하여 cursor와 응답 ID가 일치하도록 함
+   * @param modelName 모델명
+   * @param itemId 아이템 ID (string 또는 number)
+   * @param seed 생성 seed
+   * @param index 인덱스
    */
   generateOneWithId(modelName, itemId, seed, index = 0) {
     const item = this.generateOne(modelName, seed ?? `${modelName}-${itemId}`, index);
@@ -218,6 +308,7 @@ export class SchemaMockGenerator {
   }
   /**
    * 모델의 ID 필드명 찾기 (MockIdConfig 기반)
+   * public으로 변경하여 CursorPaginationManager에서 사용 가능
    */
   findIdFieldName(modelName) {
     const schema = this.models.get(modelName);
@@ -239,9 +330,9 @@ export class SchemaMockGenerator {
     return field?.jsonKey || fieldName;
   }
   /**
-   * 필드 값 생성
+   * 필드 값 생성 (순환 참조 감지 포함)
    */
-  generateField(field, rng, index) {
+  generateFieldInternal(field, rng, index, visitedModels, depth) {
     if (!field.required && rng.next() > 0.7) {
       return void 0;
     }
@@ -251,14 +342,17 @@ export class SchemaMockGenerator {
         const value = rng.pick(refSchema.enumValues);
         return field.isArray ? [value] : value;
       }
+      if (visitedModels.has(field.refType)) {
+        return field.isArray ? [] : {};
+      }
       if (field.isArray) {
         const count = rng.nextInt(1, 3);
         return Array.from(
           { length: count },
-          (_, i) => this.generateOne(field.refType, `${field.refType}-${index}-${i}`, i)
+          (_, i) => this.generateOneInternal(field.refType, `${field.refType}-${index}-${i}`, i, visitedModels, depth + 1)
         );
       }
-      return this.generateOne(field.refType, `${field.refType}-${index}`, index);
+      return this.generateOneInternal(field.refType, `${field.refType}-${index}`, index, visitedModels, depth + 1);
     }
     if (field.isArray) {
       const count = rng.nextInt(1, 5);

package/dist/runtime/server/utils/mock/pagination/cursor-manager.d.ts

@@ -14,6 +14,7 @@ export declare function encodeCursor(payload: CursorPayload): string;
  * - base64url 인코딩된 CursorPayload JSON
  * - Legacy base64 인코딩된 인덱스 번호
  * - Raw UUID/ID 문자열 (직접 ID로 사용)
+ * - Raw 숫자 (numeric ID 직접 사용)
  */
 export declare function decodeCursor(cursor: string): CursorPayload | null;
 /**

package/dist/runtime/server/utils/mock/pagination/cursor-manager.js

@@ -8,7 +8,7 @@ export function decodeCursor(cursor) {
   try {
     const json = Buffer.from(cursor, "base64url").toString("utf-8");
     const parsed = JSON.parse(json);
-    if (parsed && typeof parsed.lastId === "string" && parsed.direction) {
+    if (parsed && (typeof parsed.lastId === "string" || typeof parsed.lastId === "number") && parsed.direction) {
       return parsed;
     }
   } catch {
@@ -25,6 +25,14 @@ export function decodeCursor(cursor) {
     }
   } catch {
   }
+  const numericId = Number(cursor);
+  if (!Number.isNaN(numericId) && cursor === String(numericId)) {
+    return {
+      lastId: numericId,
+      direction: "forward",
+      timestamp: Date.now()
+    };
+  }
   if (cursor && cursor.length >= 8 && !cursor.includes(" ")) {
     return {
       lastId: cursor,
@@ -61,16 +69,17 @@ export class CursorPaginationManager {
       cache = true,
       ttl
     } = options;
+    const idFieldName = this.generator.findIdFieldName(modelName) ?? "id";
     let snapshot;
     if (snapshotId) {
       const existing = this.snapshotStore.getById(snapshotId);
       if (existing) {
         snapshot = existing;
       } else {
-        snapshot = this.snapshotStore.getOrCreate(modelName, seed, total, { cache, ttl });
+        snapshot = this.snapshotStore.getOrCreate(modelName, seed, total, { cache, ttl, idFieldName });
       }
     } else {
-      snapshot = this.snapshotStore.getOrCreate(modelName, seed, total, { cache, ttl });
+      snapshot = this.snapshotStore.getOrCreate(modelName, seed, total, { cache, ttl, idFieldName });
     }
     let startIndex = 0;
     let cursorPayload = null;
@@ -79,15 +88,15 @@ export class CursorPaginationManager {
       if (cursorPayload) {
         if (isCursorExpired(cursorPayload, this.cursorConfig)) {
           startIndex = 0;
-        } else if (cursorPayload.lastId.startsWith("legacy-")) {
+        } else if (typeof cursorPayload.lastId === "string" && cursorPayload.lastId.startsWith("legacy-")) {
           startIndex = Number.parseInt(cursorPayload.lastId.replace("legacy-", ""), 10);
         } else {
-          const anchorIndex = snapshot.itemIds.findIndex((id) => id === cursorPayload.lastId);
+          const targetId = String(cursorPayload.lastId);
+          const anchorIndex = snapshot.itemIds.findIndex((id) => String(id) === targetId);
           if (anchorIndex !== -1) {
             startIndex = cursorPayload.direction === "forward" ? anchorIndex + 1 : Math.max(0, anchorIndex - limit);
           } else {
-            const elapsedRatio = Math.min(1, (cursorPayload.timestamp - snapshot.createdAt) / (snapshot.expiresAt || Date.now() - snapshot.createdAt));
-            startIndex = Math.floor(elapsedRatio * snapshot.total);
+            startIndex = 0;
           }
         }
       }
@@ -109,7 +118,7 @@ export class CursorPaginationManager {
         direction: "forward",
         snapshotId: snapshot.id,
         timestamp: Date.now(),
-        sortField: this.cursorConfig.includeSortInfo ? "id" : void 0,
+        sortField: this.cursorConfig.includeSortInfo ? snapshot.idFieldName : void 0,
         sortOrder: this.cursorConfig.includeSortInfo ? "asc" : void 0
       });
     }
@@ -119,7 +128,7 @@ export class CursorPaginationManager {
         direction: "backward",
         snapshotId: snapshot.id,
         timestamp: Date.now(),
-        sortField: this.cursorConfig.includeSortInfo ? "id" : void 0,
+        sortField: this.cursorConfig.includeSortInfo ? snapshot.idFieldName : void 0,
         sortOrder: this.cursorConfig.includeSortInfo ? "asc" : void 0
       });
     }

package/dist/runtime/server/utils/mock/pagination/page-manager.js

@@ -22,16 +22,17 @@ export class PagePaginationManager {
       cache = this.config.cache,
       ttl = this.config.cacheTTL
     } = options;
+    const idFieldName = this.generator.findIdFieldName(modelName) ?? "id";
     let snapshot;
     if (snapshotId) {
       const existing = this.snapshotStore.getById(snapshotId);
       if (existing) {
         snapshot = existing;
       } else {
-        snapshot = this.snapshotStore.getOrCreate(modelName, seed, total, { cache, ttl });
+        snapshot = this.snapshotStore.getOrCreate(modelName, seed, total, { cache, ttl, idFieldName });
       }
     } else {
-      snapshot = this.snapshotStore.getOrCreate(modelName, seed, total, { cache, ttl });
+      snapshot = this.snapshotStore.getOrCreate(modelName, seed, total, { cache, ttl, idFieldName });
     }
     const startIndex = (page - 1) * limit;
     const endIndex = Math.min(startIndex + limit, snapshot.total);
@@ -66,16 +67,17 @@ export class PagePaginationManager {
       cache = this.config.cache,
       ttl = this.config.cacheTTL
     } = options;
+    const idFieldName = this.generator.findIdFieldName(modelName) ?? "id";
     let snapshot;
     if (snapshotId) {
       const existing = this.snapshotStore.getById(snapshotId);
       if (existing) {
         snapshot = existing;
       } else {
-        snapshot = this.snapshotStore.getOrCreate(modelName, seed, total, { cache, ttl });
+        snapshot = this.snapshotStore.getOrCreate(modelName, seed, total, { cache, ttl, idFieldName });
       }
     } else {
-      snapshot = this.snapshotStore.getOrCreate(modelName, seed, total, { cache, ttl });
+      snapshot = this.snapshotStore.getOrCreate(modelName, seed, total, { cache, ttl, idFieldName });
     }
     const endIndex = Math.min(offset + limit, snapshot.total);
     const pageItemIds = snapshot.itemIds.slice(offset, endIndex);

package/dist/runtime/server/utils/mock/pagination/snapshot-store.d.ts

@@ -20,14 +20,26 @@ export declare class SnapshotStore {
     /**
      * 아이템 ID 목록 생성 (MockIdConfig 기반)
      * 실제 응답에서 사용될 ID와 동일한 값을 생성
+     * @param total 총 아이템 수
+     * @param seed 생성 seed
+     * @param modelName 모델명
+     * @param idFieldName ID 필드명 (모델의 실제 ID 필드)
      */
     private generateItemIds;
     /**
      * 스냅샷 가져오기 또는 생성
+     * @param modelName 모델명
+     * @param seed 생성 seed
+     * @param total 총 아이템 수
+     * @param options 옵션
+     * @param options.ttl 캐시 TTL (ms)
+     * @param options.cache 캐싱 활성화 여부
+     * @param options.idFieldName ID 필드명 (모델의 실제 ID 필드)
      */
     getOrCreate(modelName: string, seed: string, total: number, options?: {
         ttl?: number;
         cache?: boolean;
+        idFieldName?: string;
     }): PaginationSnapshot;
     /**
      * 스냅샷 ID로 조회

package/dist/runtime/server/utils/mock/pagination/snapshot-store.js

@@ -21,19 +21,30 @@ export class SnapshotStore {
   /**
    * 아이템 ID 목록 생성 (MockIdConfig 기반)
    * 실제 응답에서 사용될 ID와 동일한 값을 생성
+   * @param total 총 아이템 수
+   * @param seed 생성 seed
+   * @param modelName 모델명
+   * @param idFieldName ID 필드명 (모델의 실제 ID 필드)
    */
-  generateItemIds(total, seed, modelName) {
+  generateItemIds(total, seed, modelName, idFieldName) {
     return Array.from({ length: total }, (_, i) => {
-      const id = generateIdValue("id", i, `${seed}-${modelName}-${i}`, this.idConfig);
-      return String(id);
+      return generateIdValue(idFieldName, i, `${seed}-${modelName}-${i}`, this.idConfig);
     });
   }
   /**
    * 스냅샷 가져오기 또는 생성
+   * @param modelName 모델명
+   * @param seed 생성 seed
+   * @param total 총 아이템 수
+   * @param options 옵션
+   * @param options.ttl 캐시 TTL (ms)
+   * @param options.cache 캐싱 활성화 여부
+   * @param options.idFieldName ID 필드명 (모델의 실제 ID 필드)
    */
   getOrCreate(modelName, seed, total, options) {
     const key = this.getKey(modelName, seed);
     const shouldCache = options?.cache ?? this.config.cache;
+    const idFieldName = options?.idFieldName ?? "id";
     const existing = this.snapshots.get(key);
     if (existing && !this.isExpired(existing)) {
       existing.accessedAt = Date.now();
@@ -46,7 +57,8 @@ export class SnapshotStore {
       modelName,
       seed,
       total,
-      itemIds: this.generateItemIds(total, seed, modelName),
+      itemIds: this.generateItemIds(total, seed, modelName, idFieldName),
+      idFieldName,
       createdAt: now,
       expiresAt: shouldCache ? now + ttl : void 0,
       accessedAt: now

package/dist/runtime/server/utils/mock/pagination/types.d.ts

@@ -5,8 +5,8 @@
  * Cursor 페이로드 - 연결성 있는 cursor 데이터
  */
 export interface CursorPayload {
-    /** 마지막 아이템 ID (anchor) */
-    lastId: string;
+    /** 마지막 아이템 ID (anchor) - string 또는 number 타입 지원 */
+    lastId: string | number;
     /** 방향: forward (다음) | backward (이전) */
     direction: 'forward' | 'backward';
     /** 스냅샷 ID (옵션) */
@@ -30,8 +30,10 @@ export interface PaginationSnapshot {
     seed: string;
     /** 총 아이템 수 */
     total: number;
-    /** 아이템 ID 목록 (순서 보장) */
-    itemIds: string[];
+    /** 아이템 ID 목록 (순서 보장) - string 또는 number 타입 지원 */
+    itemIds: (string | number)[];
+    /** ID 필드명 (모델의 실제 ID 필드) */
+    idFieldName: string;
     /** 생성 시간 */
     createdAt: number;
     /** 만료 시간 (옵션) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mock-fried",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Nuxt3 Mock API Module - OpenAPI & Protobuf RPC Mock Server",
   "repository": {
     "type": "git",
@@ -57,6 +57,7 @@
     "@grpc/grpc-js": "^1.12.0",
     "@grpc/proto-loader": "^0.7.13",
     "@nuxt/kit": "^4.2.2",
+    "consola": "^3.4.2",
     "js-yaml": "^4.1.0",
     "openapi-backend": "^5.10.6",
     "pathe": "^2.0.2"