@route-forge/vue 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,7 @@
 # @route-forge/vue
 
-Route Forge 的 Vue 3 集成:插件 + composable(`useForgeApi` / `useForgeLevel` / `useForgeRoute` / `useForgeByPrefix`)。
+Route Forge 的 Vue 3 集成：插件 + composable（`useForge` / `useForgeApi` / `useForgeLevel` /
+`useForgeRoute` / `useForgeByPrefix`）。
 
 ## 安装
 
@@ -23,12 +24,80 @@ app.use(createRouteForgePlugin({
 app.mount('#app')
 ```
 
-```vue
-<script setup lang="ts">
-import { useForgeRoute } from '@route-forge/vue'
+## useForge — 核心 composable
+
+`useForge()` 返回一个可直接调用的 forge 实例，是 `forge.api()` 的快捷方式。支持可选传入 `level` 绑定层级：
+
+```ts
+import { useForge } from '@route-forge/vue'
+
+// 不绑定层级 — 直接调用需要传 level
+const forge = useForge()
+forge('admin', 'users.show', { user: 1 })        // = forge.api('admin', 'users.show', ...)
+forge.api('admin', 'users.show', { user: 1 })     // 显式调用
+
+// 绑定层级 — 直接调用和 api/route/url 均无需传 level
+const forge = useForge('admin')
+forge('users.show', { user: 1 })                  // 自动带 admin
+forge.api('users.show', { user: 1 })              // 同上
+forge.route('users.show', { user: 1 })            // 生成 URL，自动带 admin
+forge.url('users.show', { user: 1 })              // route() 语义别名
+
+// 通用方法（无论是否绑定 level 均可用）
+forge.load('admin')                               // 加载层级
+forge.isLoaded('admin')                           // 检查缓存
+forge.invalidate('admin')                         // 失效缓存
+forge.interceptors.request.use(...)               // 拦截器管理
+```
+
+### 参数智能解析
+
+`api()` 的参数支持智能消解：路径参数平铺传入，`query`/`body`/`headers` 为固定 key。当路径参数名与固定
+key 冲突时，`string|number` 值自动识别为路径参数，对象值按原定义处理。也可通过 `params`
+显式指定路径参数（优先级最高）：
+
+```ts
+// 冲突消解：query 为 string → 路径参数
+forge.api('search.show', { query: 'keyword' })
 
+// 显式 params：同时需要路径参数和 query string
+forge.api('search.show', {
+  params: { query: 'keyword' },
+  query: { page: 1 },
+})
+```
+
+## 其他 composable
+
+```ts
+import {
+  useForgeApi,
+  useForgeLevel,
+  useForgeRoute,
+  useForgeByPrefix,
+} from '@route-forge/vue'
+
+// useForgeApi — 带 loading/error 状态的 API 调用
+const { call, pending, error } = useForgeApi()
+const { data } = await call('admin', 'users.show', { user: 1 })
+
+// useForgeLevel — 挂载时自动加载层级
+const { loaded, error } = useForgeLevel('admin')
+
+// useForgeRoute — 响应式 URL 生成（用于 <a href> 等）
 const url = useForgeRoute('public', 'login.show')
-</script>
+
+// useForgeByPrefix — 层级 + 名字前缀封装
+const { api, route } = useForgeByPrefix('admin', 'users')
+await api('show', { user: 1 })   // = forge.api('admin', 'users.show', { user: 1 })
+```
+
+## 模板内使用
+
+```vue
+<template>
+  <a :href="$forge.route('public', 'login.show')">登录</a>
+</template>
 ```
 
 ## 文档

package/dist/index.cjs

@@ -3,6 +3,25 @@
 var vue = require('vue');
 var core = require('@route-forge/core');
 
+// src/plugin.ts
+async function resolveRouteName(forge, level, prefix, suffix, separator = ".") {
+  if (!suffix) return prefix;
+  const joined = `${prefix}${separator}${suffix}`;
+  if (!suffix.startsWith(`${prefix}${separator}`)) return joined;
+  await forge.load(level);
+  if (forge.hasRoute(level, joined)) return joined;
+  if (forge.hasRoute(level, suffix)) return suffix;
+  throw new core.UnknownRouteError(joined, level);
+}
+function resolveRouteNameSync(forge, level, prefix, suffix, separator = ".") {
+  if (!suffix) return prefix;
+  const joined = `${prefix}${separator}${suffix}`;
+  if (!suffix.startsWith(`${prefix}${separator}`)) return joined;
+  if (forge.hasRoute(level, joined)) return joined;
+  if (forge.hasRoute(level, suffix)) return suffix;
+  throw new core.UnknownRouteError(joined, level);
+}
+
 // src/plugin.ts
 var FORGE_INJECTION_KEY = /* @__PURE__ */ Symbol("route-forge");
 function createRouteForgePlugin(options) {
@@ -16,24 +35,65 @@ function createRouteForgePlugin(options) {
     }
   };
 }
-function useForge() {
+function useForge(level, prefix) {
   const forge = vue.inject(FORGE_INJECTION_KEY);
   if (!forge) {
     throw new Error(
       "[route-forge/vue] useForge() must be used inside an app with createRouteForgePlugin() installed"
     );
   }
-  return forge;
+  if (level !== void 0) {
+    const callable2 = prefix ? async (name, params) => forge.api(level, await resolveRouteName(forge, level, prefix, name), params) : (name, params) => forge.api(level, name, params);
+    defineImmutableProps(callable2, {
+      level,
+      prefix,
+      api: prefix ? async (name, params) => forge.api(level, await resolveRouteName(forge, level, prefix, name), params) : (name, params) => forge.api(level, name, params),
+      route: prefix ? (name, params) => forge.route(level, resolveRouteNameSync(forge, level, prefix, name), params) : (name, params) => forge.route(level, name, params),
+      url: prefix ? (name, params) => forge.route(level, resolveRouteNameSync(forge, level, prefix, name), params) : (name, params) => forge.route(level, name, params),
+      load: forge.load.bind(forge),
+      invalidate: forge.invalidate.bind(forge),
+      isLoaded: forge.isLoaded.bind(forge),
+      hasRoute: forge.hasRoute.bind(forge),
+      getRoutes: forge.getRoutes.bind(forge),
+      interceptors: forge.interceptors
+    });
+    return callable2;
+  }
+  const callable = (lvl, name, params) => forge.api(lvl, name, params);
+  defineImmutableProps(callable, {
+    api: forge.api.bind(forge),
+    route: forge.route.bind(forge),
+    url: forge.url.bind(forge),
+    load: forge.load.bind(forge),
+    invalidate: forge.invalidate.bind(forge),
+    isLoaded: forge.isLoaded.bind(forge),
+    hasRoute: forge.hasRoute.bind(forge),
+    getRoutes: forge.getRoutes.bind(forge),
+    interceptors: forge.interceptors
+  });
+  return callable;
 }
-function useForgeApi() {
-  const forge = useForge();
+function defineImmutableProps(target, props) {
+  for (const key of Object.keys(props)) {
+    const val = props[key];
+    Object.defineProperty(target, key, {
+      value: val !== null && typeof val === "object" ? Object.freeze(val) : val,
+      writable: false,
+      enumerable: false,
+      configurable: false
+    });
+  }
+  return target;
+}
+function useForgeApi(level, prefix) {
+  const forge = level !== void 0 ? useForge(level, prefix) : useForge();
   const pending = vue.ref(false);
   const error = vue.ref(null);
-  async function call(level, name, params) {
+  async function call(...args) {
     pending.value = true;
     error.value = null;
     try {
-      const data = await forge.api(level, name, params);
+      const data = await forge.api(...args);
       return { data, error: null };
     } catch (e) {
       error.value = e;
@@ -71,10 +131,11 @@ function useForgeRoute(level, name, params) {
 // src/composables/useForgeByPrefix.ts
 function useForgeByPrefix(level, prefix, separator = ".") {
   const forge = useForge();
-  const join = (suffix) => suffix ? `${prefix}${separator}${suffix}` : prefix;
   return {
-    api: (suffix, params) => forge.api(level, join(suffix), params),
-    route: (suffix, params) => forge.route(level, join(suffix), params)
+    api: (suffix, params) => resolveRouteName(forge, level, prefix, suffix, separator).then(
+      (name) => forge.api(level, name, params)
+    ),
+    route: (suffix, params) => forge.route(level, resolveRouteNameSync(forge, level, prefix, suffix, separator), params)
   };
 }
 

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/plugin.ts","../src/composables/useForgeApi.ts","../src/composables/useForgeLevel.ts","../src/composables/useForgeRoute.ts","../src/composables/useForgeByPrefix.ts"],"names":["createRouteForge","inject","ref","onMounted","computed"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Vue 3 插件入口\n * @see .docs/SPEC.md §4.1.7\n *\n * 提供：\n *   - 全局属性 $forge（route() 工具）\n *   - inject symbol 注入 RouteForge 实例供 composable 使用\n */\n\nimport type { App, InjectionKey, Plugin } from 'vue';\nimport { inject, reactive, readonly } from 'vue';\nimport { createRouteForge, type RouteForge, type RouteForgeOptions } from '@route-forge/core';\n\nexport const FORGE_INJECTION_KEY: InjectionKey<RouteForge> = Symbol('route-forge');\n\nexport interface RouteForgePluginOptions extends RouteForgeOptions {}\n\nexport function createRouteForgePlugin(options: RouteForgePluginOptions): Plugin<[]> {\n  const forge = createRouteForge(options);\n\n  return {\n    install(app: App) {\n      app.provide(FORGE_INJECTION_KEY, forge);\n      app.config.globalProperties.$forge = {\n        route: (level: string, name: string, params?: Record<string, unknown>) =>\n          forge.route(level, name, params),\n      };\n    },\n  };\n}\n\nexport function useForge(): RouteForge {\n  const forge = inject(FORGE_INJECTION_KEY);\n  if (!forge) {\n    throw new Error(\n      '[route-forge/vue] useForge() must be used inside an app with createRouteForgePlugin() installed',\n    );\n  }\n  return forge;\n}\n\nexport { readonly, reactive };\n","/**\n * useForgeApi：包装 forge.api()，自动管理 loading/error 状态\n * @see .docs/SPEC.md §4.1.7\n */\n\nimport { ref } from 'vue';\nimport { useForge } from '../plugin.js';\nimport type { ApiCallParams } from '@route-forge/core';\n\nexport interface UseForgeApiReturn {\n  pending: ReturnType<typeof ref<boolean>>;\n  error: ReturnType<typeof ref<unknown>>;\n  call: (level: string, name: string, params?: ApiCallParams) => Promise<{\n    data: unknown;\n    error: unknown;\n  }>;\n}\n\nexport function useForgeApi(): UseForgeApiReturn {\n  const forge = useForge();\n  const pending = ref(false);\n  const error = ref<unknown>(null);\n\n  async function call(level: string, name: string, params?: ApiCallParams) {\n    pending.value = true;\n    error.value = null;\n    try {\n      const data = await forge.api(level, name, params);\n      return { data, error: null };\n    } catch (e) {\n      error.value = e;\n      return { data: undefined, error: e };\n    } finally {\n      pending.value = false;\n    }\n  }\n\n  return { pending, error, call };\n}\n","/**\n * useForgeLevel：声明组件依赖某层级，挂载时自动 forge.load(level)，销毁时不主动失效\n * @see .docs/SPEC.md §4.1.7\n */\n\nimport { onMounted, ref } from 'vue';\nimport { useForge } from '../plugin.js';\n\nexport interface UseForgeLevelReturn {\n  loaded: ReturnType<typeof ref<boolean>>;\n  error: ReturnType<typeof ref<unknown>>;\n}\n\nexport function useForgeLevel(level: string): UseForgeLevelReturn {\n  const forge = useForge();\n  const loaded = ref(false);\n  const error = ref<unknown>(null);\n\n  onMounted(async () => {\n    try {\n      await forge.load(level);\n      loaded.value = true;\n    } catch (e) {\n      error.value = e;\n    }\n  });\n\n  return { loaded, error };\n}\n","/**\n * useForgeRoute：仅生成 URL，不发请求（用于 <a href>、外部跳转等）\n * @see .docs/SPEC.md §4.1.7\n */\n\nimport { computed, type ComputedRef } from 'vue';\nimport { useForge } from '../plugin.js';\n\nexport function useForgeRoute(\n  level: string | (() => string),\n  name: string | (() => string),\n  params?: () => Record<string, unknown>,\n): ComputedRef<string> {\n  const forge = useForge();\n  return computed(() => {\n    const lvl = typeof level === 'function' ? level() : level;\n    const n = typeof name === 'function' ? name() : name;\n    const p = params ? params() : undefined;\n    return forge.route(lvl, n, p);\n  });\n}\n","/**\n * useForgeByPrefix：带层级 + 名字前缀的封装，方便后续减少名称传入\n * @see .docs/SPEC.md §4.1.7\n *\n * 示例：\n *   const { api } = useForgeByPrefix('admin', 'users');\n *   await api('show', { user: 1 });   // 等价于 forge.api('admin', 'users.show', { user: 1 })\n */\n\nimport { useForge } from '../plugin.js';\nimport type { ApiCallParams } from '@route-forge/core';\n\nexport interface UseForgeByPrefixReturn {\n  api: (suffix: string, params?: ApiCallParams) => Promise<unknown>;\n  route: (suffix: string, params?: Record<string, unknown>) => string;\n}\n\nexport function useForgeByPrefix(level: string, prefix: string, separator = '.'): UseForgeByPrefixReturn {\n  const forge = useForge();\n\n  const join = (suffix: string) => (suffix ? `${prefix}${separator}${suffix}` : prefix);\n\n  return {\n    api: (suffix, params) => forge.api(level, join(suffix), params),\n    route: (suffix, params) => forge.route(level, join(suffix), params),\n  };\n}\n"]}
+{"version":3,"sources":["../src/utils/resolveRouteName.ts","../src/plugin.ts","../src/composables/useForgeApi.ts","../src/composables/useForgeLevel.ts","../src/composables/useForgeRoute.ts","../src/composables/useForgeByPrefix.ts"],"names":["UnknownRouteError","createRouteForge","inject","callable","ref","onMounted","computed"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * 智能路由名前缀解析\n *\n * 当前缀与后缀拼接产生歧义时（后缀本身已以前缀开头），\n * 通过查询已加载路由表来判定正确名称：\n *   - 优先尝试 prefix + sep + suffix（完整拼接）\n *   - 若不存在则回退到 suffix（视为已含前缀）\n *   - 均不存在则抛 UnknownRouteError\n *\n * @see .docs/SPEC.md §4.1.7\n */\n\nimport { UnknownRouteError } from '@route-forge/core';\n\n/**\n * 路由名解析所需的最小 forge 接口。\n * 仅依赖 load() 和 hasRoute()，不依赖拦截器等完整能力。\n * 兼容 RouteForge、BoundForgeTyped、ForgeInstanceTyped 等所有形态。\n */\ninterface RouteResolver {\n  load(level: string | string[]): Promise<void>;\n\n  hasRoute(level: string, name: string): boolean;\n}\n\n/**\n * 异步版本：先确保层级已加载，再做歧义消解。\n * 适用于 api() 调用路径。\n */\nexport async function resolveRouteName(\n  forge: RouteResolver,\n  level: string,\n  prefix: string,\n  suffix: string,\n  separator = '.',\n): Promise<string> {\n  // 后缀为空 → 直接返回前缀\n  if (!suffix) return prefix;\n\n  const joined = `${prefix}${separator}${suffix}`;\n\n  // 后缀不以前缀开头 → 无歧义，直接拼接\n  if (!suffix.startsWith(`${prefix}${separator}`)) return joined;\n\n  // 歧义场景：先确保层级已加载\n  await forge.load(level);\n\n  // 优先尝试完整拼接\n  if (forge.hasRoute(level, joined)) return joined;\n  // 回退到后缀本身（视为已含前缀）\n  if (forge.hasRoute(level, suffix)) return suffix;\n\n  // 均不存在 → 报错\n  throw new UnknownRouteError(joined, level);\n}\n\n/**\n * 同步版本：基于已加载缓存做歧义消解。\n * 适用于 route() / url() 调用路径（要求层级已加载）。\n */\nexport function resolveRouteNameSync(\n  forge: RouteResolver,\n  level: string,\n  prefix: string,\n  suffix: string,\n  separator = '.',\n): string {\n  if (!suffix) return prefix;\n\n  const joined = `${prefix}${separator}${suffix}`;\n  if (!suffix.startsWith(`${prefix}${separator}`)) return joined;\n\n  // 歧义场景：基于已加载缓存判定\n  if (forge.hasRoute(level, joined)) return joined;\n  if (forge.hasRoute(level, suffix)) return suffix;\n\n  throw new UnknownRouteError(joined, level);\n}\n","/**\n * Vue 3 插件入口\n * @see .docs/SPEC.md §4.1.7\n *\n * 提供：\n *   - 全局属性 $forge（route() 工具）\n *   - inject symbol 注入 RouteForge 实例供 composable 使用\n *   - useForge() / useForge(level) / useForge(level, prefix) 返回统一方法的 forge 实例\n *     • 不传 level：forge(level, name, params?) 直接调用\n *     • 传 level：forge(name, params?) 直接调用，自动绑定层级\n *     • 传 level + prefix：forge(suffix, params?) 自动拼接 prefix\n *\n * 类型推断：\n *   当 ForgeRouteMap 通过 codegen 或 module augmentation 定义时，\n *   level / name / params 均自动推断，IDE 提供补全提示。\n */\n\nimport type { App, InjectionKey, Plugin } from 'vue';\nimport { inject, reactive, readonly } from 'vue';\nimport {\n  type ApiCallParams,\n  createRouteForge,\n  type ForgeApiParams,\n  type ForgeApiResponse,\n  type ForgeRouteName,\n  type InterceptorHandler,\n  type RequestConfig,\n  type ResponseData,\n  type RouteForge,\n  type RouteForgeOptions,\n  type RouteMeta,\n} from '@route-forge/core';\nimport { resolveRouteName, resolveRouteNameSync } from './utils/resolveRouteName.js';\n\nexport const FORGE_INJECTION_KEY: InjectionKey<RouteForge> = Symbol('route-forge');\n\nexport interface RouteForgePluginOptions extends RouteForgeOptions {}\n\n/** 只读拦截器管理器：仅暴露查询方法，隐藏 use/eject/clear */\ninterface ReadOnlyInterceptorManager<TIn, TOut = TIn> {\n  readonly size: number;\n\n  forEach(fn: (handler: InterceptorHandler<TIn, TOut>) => void): void;\n}\n\n/**\n * 共享方法集（level 已绑定时的方法签名）\n * .api() / .route() / .url() — name 和 params 根据 ForgeRouteMap 自动推断\n * .load() / .invalidate() / .isLoaded() / .interceptors\n */\nexport interface BoundForgeMethods<L extends string = string> {\n  interceptors: {\n    request: ReadOnlyInterceptorManager<RequestConfig>;\n    response: ReadOnlyInterceptorManager<ResponseData>;\n  };\n\n  api(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<ForgeApiResponse<L, ForgeRouteName<L>>>;\n\n  route(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): string;\n\n  url(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): string;\n\n  load(level: string | string[]): Promise<void>;\n\n  invalidate(level?: string): void;\n\n  isLoaded(level?: string): boolean;\n\n  hasRoute(level: string, name: string): boolean;\n\n  /** 获取指定层级下全部路由元信息（深拷贝，修改不影响内部缓存） */\n  getRoutes(level: string): Record<string, RouteMeta>;\n}\n\n/** 已绑定 level — 直接调用无需 level，api/route/url 的 name 自动限定到该层级 */\nexport interface BoundForgeTyped<L extends string> extends BoundForgeMethods<L> {\n  (name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<ForgeApiResponse<L, ForgeRouteName<L>>>;\n  /** 当前绑定的 level 值 */\n  readonly level: L;\n  /** 路由名前缀（仅在 useForge(level, prefix) 传入 prefix 时存在） */\n  readonly prefix?: string;\n}\n\n/** 未绑定 level — 直接调用需要传 level */\nexport interface ForgeInstanceTyped extends Omit<BoundForgeMethods<string>, 'api' | 'route' | 'url' | 'hasRoute' | 'getRoutes'> {\n  (level: string, name: string, params?: ApiCallParams): Promise<unknown>;\n  api(level: string, name: string, params?: ApiCallParams): Promise<unknown>;\n  route(level: string, name: string, params?: Record<string, unknown>): string;\n  url(level: string, name: string, params?: Record<string, unknown>): string;\n\n  hasRoute(level: string, name: string): boolean;\n\n  /** 获取全部层级路由（深拷贝）；传 level 时仅返回该层级 */\n  getRoutes(): Record<string, Record<string, RouteMeta>>;\n  getRoutes(level: string): Record<string, RouteMeta>;\n}\n\nexport function createRouteForgePlugin(options: RouteForgePluginOptions): Plugin<[]> {\n  const forge = createRouteForge(options);\n\n  return {\n    install(app: App) {\n      app.provide(FORGE_INJECTION_KEY, forge);\n      app.config.globalProperties.$forge = {\n        route: (level: string, name: string, params?: Record<string, unknown>) =>\n          forge.route(level, name, params),\n      };\n    },\n  };\n}\n\n/**\n * 获取 forge 实例。\n *\n * @example\n * // 不绑定层级\n * const forge = useForge()\n * forge('admin', 'users.show', { user: 1 })\n * forge.api('admin', 'users.show')\n *\n * @example\n * // 绑定层级 — 直接调用和 api/route/url 均无需传 level\n * const forge = useForge('admin')\n * forge.level                    // → 'admin'\n * forge('users.show', { user: 1 })\n * forge.api('users.show')\n *\n * @example\n * // 绑定层级 + 前缀 — 路由名自动拼接\n * const forge = useForge('admin', 'users')\n * forge.level                    // → 'admin'\n * forge.prefix                   // → 'users'\n * forge('show', { user: 1 })           // → forge.api('admin', 'users.show', ...)\n * forge.api('index')                   // → forge.api('admin', 'users.index')\n * forge.route('show', { user: 1 })     // → forge.route('admin', 'users.show', ...)\n */\nexport function useForge<L extends string>(level: L, prefix: string): BoundForgeTyped<L>;\nexport function useForge<L extends string>(level: L): BoundForgeTyped<L>;\nexport function useForge(): ForgeInstanceTyped;\nexport function useForge(level?: string, prefix?: string): ForgeInstanceTyped | BoundForgeTyped<string> {\n  const forge = inject(FORGE_INJECTION_KEY);\n  if (!forge) {\n    throw new Error(\n      '[route-forge/vue] useForge() must be used inside an app with createRouteForgePlugin() installed',\n    );\n  }\n\n  if (level !== undefined) {\n    const callable = prefix\n      ? async (name: string, params?: ApiCallParams) =>\n        forge.api(level, await resolveRouteName(forge, level, prefix, name), params)\n      : (name: string, params?: ApiCallParams) =>\n        forge.api(level, name, params);\n    defineImmutableProps(callable, {\n      level,\n      prefix,\n      api: prefix\n        ? async (name: string, params?: ApiCallParams) =>\n          forge.api(level, await resolveRouteName(forge, level, prefix, name), params)\n        : (name: string, params?: ApiCallParams) => forge.api(level, name, params),\n      route: prefix\n        ? (name: string, params?: Record<string, unknown>) =>\n          forge.route(level, resolveRouteNameSync(forge, level, prefix, name), params)\n        : (name: string, params?: Record<string, unknown>) => forge.route(level, name, params),\n      url: prefix\n        ? (name: string, params?: Record<string, unknown>) =>\n          forge.route(level, resolveRouteNameSync(forge, level, prefix, name), params)\n        : (name: string, params?: Record<string, unknown>) => forge.route(level, name, params),\n      load: forge.load.bind(forge),\n      invalidate: forge.invalidate.bind(forge),\n      isLoaded: forge.isLoaded.bind(forge),\n      hasRoute: forge.hasRoute.bind(forge),\n      getRoutes: forge.getRoutes.bind(forge),\n      interceptors: forge.interceptors,\n    });\n    return callable as unknown as BoundForgeTyped<string>;\n  }\n\n  const callable = (lvl: string, name: string, params?: ApiCallParams) =>\n    forge.api(lvl, name, params);\n  defineImmutableProps(callable, {\n    api: forge.api.bind(forge),\n    route: forge.route.bind(forge),\n    url: forge.url.bind(forge),\n    load: forge.load.bind(forge),\n    invalidate: forge.invalidate.bind(forge),\n    isLoaded: forge.isLoaded.bind(forge),\n    hasRoute: forge.hasRoute.bind(forge),\n    getRoutes: forge.getRoutes.bind(forge),\n    interceptors: forge.interceptors,\n  });\n  return callable as ForgeInstanceTyped;\n}\n\nexport { readonly, reactive };\n\n/**\n * 以不可变、不可枚举、不可重配置的方式将属性挂载到目标对象上。\n * 相比 Object.assign 更安全——外部无法通过遍历/删除/重写篡改这些方法。\n * 对象类型的值会浅冻结（Object.freeze），防止内部键被增删改。\n */\nfunction defineImmutableProps<T extends object>(target: T, props: Record<string, unknown>): T {\n  for (const key of Object.keys(props)) {\n    const val = props[key];\n    Object.defineProperty(target, key, {\n      value: val !== null && typeof val === 'object' ? Object.freeze(val) : val,\n      writable: false,\n      enumerable: false,\n      configurable: false,\n    });\n  }\n  return target;\n}\n","/**\n * useForgeApi：包装 forge.api()，自动管理 loading/error 状态\n * @see .docs/SPEC.md §4.1.7\n *\n * 支持：\n *   - useForgeApi()             — call(level, name, params)\n *   - useForgeApi(level)        — call(name, params)，自动绑定层级\n *   - useForgeApi(level, prefix) — call(suffix, params)，自动绑定层级 + 拼接前缀\n *\n * 类型推断：\n *   当 ForgeRouteMap 通过 codegen 或 module augmentation 定义时，\n *   level / name / params 均自动推断，IDE 提供补全提示。\n */\n\nimport { ref } from 'vue';\nimport { useForge } from '../plugin.js';\nimport type {\n  ApiCallParams,\n  ForgeApiParams,\n  ForgeApiResponse,\n  ForgeRouteName,\n} from '@route-forge/core';\n\n/** call 函数签名 — 未绑定 level，需要显式传入 */\nexport interface UseForgeApiCall {\n  (level: string, name: string, params?: ApiCallParams): Promise<{\n    data: unknown;\n    error: unknown;\n  }>;\n}\n\n/** call 函数签名 — 已绑定 level，无需再传 */\nexport interface UseForgeApiBoundCall<L extends string> {\n  (name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<{\n    data: ForgeApiResponse<L, ForgeRouteName<L>>;\n    error: unknown;\n  }>;\n}\n\nexport interface UseForgeApiReturn {\n  pending: ReturnType<typeof ref<boolean>>;\n  error: ReturnType<typeof ref<unknown>>;\n  call: UseForgeApiCall;\n}\n\nexport interface UseForgeApiBoundReturn<L extends string> {\n  pending: ReturnType<typeof ref<boolean>>;\n  error: ReturnType<typeof ref<unknown>>;\n  call: UseForgeApiBoundCall<L>;\n}\n\n/** 不绑定层级 — call 需要传 level */\nexport function useForgeApi(): UseForgeApiReturn;\n/** 绑定层级 — call 无需传 level */\nexport function useForgeApi<L extends string>(level: L): UseForgeApiBoundReturn<L>;\n/** 绑定层级 + 前缀 — call 无需传 level，路由名自动拼接 prefix */\nexport function useForgeApi<L extends string>(level: L, prefix: string): UseForgeApiBoundReturn<L>;\nexport function useForgeApi(level?: string, prefix?: string): UseForgeApiReturn | UseForgeApiBoundReturn<string> {\n  const forge = level !== undefined ? useForge(level, prefix as string) : useForge();\n  const pending = ref(false);\n  const error = ref<unknown>(null);\n\n  async function call(...args: unknown[]): Promise<{ data: unknown; error: unknown }> {\n    pending.value = true;\n    error.value = null;\n    try {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      const data = await (forge as any).api(...args);\n      return { data, error: null };\n    } catch (e) {\n      error.value = e;\n      return { data: undefined, error: e };\n    } finally {\n      pending.value = false;\n    }\n  }\n\n  return { pending, error, call: call as any };\n}\n","/**\n * useForgeLevel：声明组件依赖某层级，挂载时自动 forge.load(level)，销毁时不主动失效\n * @see .docs/SPEC.md §4.1.7\n */\n\nimport { onMounted, ref } from 'vue';\nimport { useForge } from '../plugin.js';\n\nexport interface UseForgeLevelReturn {\n  loaded: ReturnType<typeof ref<boolean>>;\n  error: ReturnType<typeof ref<unknown>>;\n}\n\nexport function useForgeLevel(level: string): UseForgeLevelReturn {\n  const forge = useForge();\n  const loaded = ref(false);\n  const error = ref<unknown>(null);\n\n  onMounted(async () => {\n    try {\n      await forge.load(level);\n      loaded.value = true;\n    } catch (e) {\n      error.value = e;\n    }\n  });\n\n  return { loaded, error };\n}\n","/**\n * useForgeRoute：仅生成 URL，不发请求（用于 <a href>、外部跳转等）\n * @see .docs/SPEC.md §4.1.7\n */\n\nimport { computed, type ComputedRef } from 'vue';\nimport { useForge } from '../plugin.js';\n\nexport function useForgeRoute(\n  level: string | (() => string),\n  name: string | (() => string),\n  params?: () => Record<string, unknown>,\n): ComputedRef<string> {\n  const forge = useForge();\n  return computed(() => {\n    const lvl = typeof level === 'function' ? level() : level;\n    const n = typeof name === 'function' ? name() : name;\n    const p = params ? params() : undefined;\n    return forge.route(lvl, n, p);\n  });\n}\n","/**\n * useForgeByPrefix：带层级 + 名字前缀的封装，方便后续减少名称传入\n * @see .docs/SPEC.md §4.1.7\n *\n * 智能前缀解析：\n *   - 传入后缀不以前缀开头 → 自动拼接 prefix.suffix\n *   - 传入后缀已以前缀开头（歧义） → 优先尝试完整拼接，\n *     若不存在则视为已含前缀直接使用，均不存在则报错\n *\n * 示例（prefix = 'test'）：\n *   api('1')        → test.1\n *   api('test1.1')  → test.test1.1\n *   api('test.1')   → 歧义：优先 test.test.1，回退 test.1\n */\n\nimport { useForge } from '../plugin.js';\nimport { resolveRouteName, resolveRouteNameSync } from '../utils/resolveRouteName.js';\nimport type { ApiCallParams } from '@route-forge/core';\n\nexport interface UseForgeByPrefixReturn {\n  api: (suffix: string, params?: ApiCallParams) => Promise<unknown>;\n  route: (suffix: string, params?: Record<string, unknown>) => string;\n}\n\nexport function useForgeByPrefix(level: string, prefix: string, separator = '.'): UseForgeByPrefixReturn {\n  const forge = useForge();\n\n  return {\n    api: (suffix, params) =>\n      resolveRouteName(forge, level, prefix, suffix, separator).then(\n        (name) => forge.api(level, name, params),\n      ),\n    route: (suffix, params) =>\n      forge.route(level, resolveRouteNameSync(forge, level, prefix, suffix, separator), params),\n  };\n}\n"]}

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { InjectionKey, Plugin, ref, ComputedRef } from 'vue';
-import { RouteForge, RouteForgeOptions, ApiCallParams } from '@route-forge/core';
+import { InterceptorHandler, RequestConfig, ResponseData, ForgeRouteName, ForgeApiParams, ForgeApiResponse, RouteMeta, RouteForge, ApiCallParams, RouteForgeOptions } from '@route-forge/core';
 
 /**
  * Vue 3 插件入口
@@ -8,28 +8,137 @@ import { RouteForge, RouteForgeOptions, ApiCallParams } from '@route-forge/core'
  * 提供：
  *   - 全局属性 $forge（route() 工具）
  *   - inject symbol 注入 RouteForge 实例供 composable 使用
+ *   - useForge() / useForge(level) / useForge(level, prefix) 返回统一方法的 forge 实例
+ *     • 不传 level：forge(level, name, params?) 直接调用
+ *     • 传 level：forge(name, params?) 直接调用，自动绑定层级
+ *     • 传 level + prefix：forge(suffix, params?) 自动拼接 prefix
+ *
+ * 类型推断：
+ *   当 ForgeRouteMap 通过 codegen 或 module augmentation 定义时，
+ *   level / name / params 均自动推断，IDE 提供补全提示。
  */
 
 declare const FORGE_INJECTION_KEY: InjectionKey<RouteForge>;
 interface RouteForgePluginOptions extends RouteForgeOptions {
 }
+/** 只读拦截器管理器：仅暴露查询方法，隐藏 use/eject/clear */
+interface ReadOnlyInterceptorManager<TIn, TOut = TIn> {
+    readonly size: number;
+    forEach(fn: (handler: InterceptorHandler<TIn, TOut>) => void): void;
+}
+/**
+ * 共享方法集（level 已绑定时的方法签名）
+ * .api() / .route() / .url() — name 和 params 根据 ForgeRouteMap 自动推断
+ * .load() / .invalidate() / .isLoaded() / .interceptors
+ */
+interface BoundForgeMethods<L extends string = string> {
+    interceptors: {
+        request: ReadOnlyInterceptorManager<RequestConfig>;
+        response: ReadOnlyInterceptorManager<ResponseData>;
+    };
+    api(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<ForgeApiResponse<L, ForgeRouteName<L>>>;
+    route(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): string;
+    url(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): string;
+    load(level: string | string[]): Promise<void>;
+    invalidate(level?: string): void;
+    isLoaded(level?: string): boolean;
+    hasRoute(level: string, name: string): boolean;
+    /** 获取指定层级下全部路由元信息（深拷贝，修改不影响内部缓存） */
+    getRoutes(level: string): Record<string, RouteMeta>;
+}
+/** 已绑定 level — 直接调用无需 level，api/route/url 的 name 自动限定到该层级 */
+interface BoundForgeTyped<L extends string> extends BoundForgeMethods<L> {
+    (name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<ForgeApiResponse<L, ForgeRouteName<L>>>;
+    /** 当前绑定的 level 值 */
+    readonly level: L;
+    /** 路由名前缀（仅在 useForge(level, prefix) 传入 prefix 时存在） */
+    readonly prefix?: string;
+}
+/** 未绑定 level — 直接调用需要传 level */
+interface ForgeInstanceTyped extends Omit<BoundForgeMethods<string>, 'api' | 'route' | 'url' | 'hasRoute' | 'getRoutes'> {
+    (level: string, name: string, params?: ApiCallParams): Promise<unknown>;
+    api(level: string, name: string, params?: ApiCallParams): Promise<unknown>;
+    route(level: string, name: string, params?: Record<string, unknown>): string;
+    url(level: string, name: string, params?: Record<string, unknown>): string;
+    hasRoute(level: string, name: string): boolean;
+    /** 获取全部层级路由（深拷贝）；传 level 时仅返回该层级 */
+    getRoutes(): Record<string, Record<string, RouteMeta>>;
+    getRoutes(level: string): Record<string, RouteMeta>;
+}
 declare function createRouteForgePlugin(options: RouteForgePluginOptions): Plugin<[]>;
-declare function useForge(): RouteForge;
+/**
+ * 获取 forge 实例。
+ *
+ * @example
+ * // 不绑定层级
+ * const forge = useForge()
+ * forge('admin', 'users.show', { user: 1 })
+ * forge.api('admin', 'users.show')
+ *
+ * @example
+ * // 绑定层级 — 直接调用和 api/route/url 均无需传 level
+ * const forge = useForge('admin')
+ * forge.level                    // → 'admin'
+ * forge('users.show', { user: 1 })
+ * forge.api('users.show')
+ *
+ * @example
+ * // 绑定层级 + 前缀 — 路由名自动拼接
+ * const forge = useForge('admin', 'users')
+ * forge.level                    // → 'admin'
+ * forge.prefix                   // → 'users'
+ * forge('show', { user: 1 })           // → forge.api('admin', 'users.show', ...)
+ * forge.api('index')                   // → forge.api('admin', 'users.index')
+ * forge.route('show', { user: 1 })     // → forge.route('admin', 'users.show', ...)
+ */
+declare function useForge<L extends string>(level: L, prefix: string): BoundForgeTyped<L>;
+declare function useForge<L extends string>(level: L): BoundForgeTyped<L>;
+declare function useForge(): ForgeInstanceTyped;
 
 /**
  * useForgeApi：包装 forge.api()，自动管理 loading/error 状态
  * @see .docs/SPEC.md §4.1.7
+ *
+ * 支持：
+ *   - useForgeApi()             — call(level, name, params)
+ *   - useForgeApi(level)        — call(name, params)，自动绑定层级
+ *   - useForgeApi(level, prefix) — call(suffix, params)，自动绑定层级 + 拼接前缀
+ *
+ * 类型推断：
+ *   当 ForgeRouteMap 通过 codegen 或 module augmentation 定义时，
+ *   level / name / params 均自动推断，IDE 提供补全提示。
  */
 
-interface UseForgeApiReturn {
-    pending: ReturnType<typeof ref<boolean>>;
-    error: ReturnType<typeof ref<unknown>>;
-    call: (level: string, name: string, params?: ApiCallParams) => Promise<{
+/** call 函数签名 — 未绑定 level，需要显式传入 */
+interface UseForgeApiCall {
+    (level: string, name: string, params?: ApiCallParams): Promise<{
         data: unknown;
         error: unknown;
     }>;
 }
+/** call 函数签名 — 已绑定 level，无需再传 */
+interface UseForgeApiBoundCall<L extends string> {
+    (name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<{
+        data: ForgeApiResponse<L, ForgeRouteName<L>>;
+        error: unknown;
+    }>;
+}
+interface UseForgeApiReturn {
+    pending: ReturnType<typeof ref<boolean>>;
+    error: ReturnType<typeof ref<unknown>>;
+    call: UseForgeApiCall;
+}
+interface UseForgeApiBoundReturn<L extends string> {
+    pending: ReturnType<typeof ref<boolean>>;
+    error: ReturnType<typeof ref<unknown>>;
+    call: UseForgeApiBoundCall<L>;
+}
+/** 不绑定层级 — call 需要传 level */
 declare function useForgeApi(): UseForgeApiReturn;
+/** 绑定层级 — call 无需传 level */
+declare function useForgeApi<L extends string>(level: L): UseForgeApiBoundReturn<L>;
+/** 绑定层级 + 前缀 — call 无需传 level，路由名自动拼接 prefix */
+declare function useForgeApi<L extends string>(level: L, prefix: string): UseForgeApiBoundReturn<L>;
 
 /**
  * useForgeLevel：声明组件依赖某层级，挂载时自动 forge.load(level)，销毁时不主动失效
@@ -53,9 +162,15 @@ declare function useForgeRoute(level: string | (() => string), name: string | ((
  * useForgeByPrefix：带层级 + 名字前缀的封装，方便后续减少名称传入
  * @see .docs/SPEC.md §4.1.7
  *
- * 示例：
- *   const { api } = useForgeByPrefix('admin', 'users');
- *   await api('show', { user: 1 });   // 等价于 forge.api('admin', 'users.show', { user: 1 })
+ * 智能前缀解析：
+ *   - 传入后缀不以前缀开头 → 自动拼接 prefix.suffix
+ *   - 传入后缀已以前缀开头（歧义） → 优先尝试完整拼接，
+ *     若不存在则视为已含前缀直接使用，均不存在则报错
+ *
+ * 示例（prefix = 'test'）：
+ *   api('1')        → test.1
+ *   api('test1.1')  → test.test1.1
+ *   api('test.1')   → 歧义：优先 test.test.1，回退 test.1
  */
 
 interface UseForgeByPrefixReturn {
@@ -64,4 +179,4 @@ interface UseForgeByPrefixReturn {
 }
 declare function useForgeByPrefix(level: string, prefix: string, separator?: string): UseForgeByPrefixReturn;
 
-export { FORGE_INJECTION_KEY, type RouteForgePluginOptions, type UseForgeApiReturn, type UseForgeByPrefixReturn, type UseForgeLevelReturn, createRouteForgePlugin, useForge, useForgeApi, useForgeByPrefix, useForgeLevel, useForgeRoute };
+export { type BoundForgeMethods, type BoundForgeTyped, FORGE_INJECTION_KEY, type ForgeInstanceTyped, type RouteForgePluginOptions, type UseForgeApiBoundCall, type UseForgeApiBoundReturn, type UseForgeApiCall, type UseForgeApiReturn, type UseForgeByPrefixReturn, type UseForgeLevelReturn, createRouteForgePlugin, useForge, useForgeApi, useForgeByPrefix, useForgeLevel, useForgeRoute };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { InjectionKey, Plugin, ref, ComputedRef } from 'vue';
-import { RouteForge, RouteForgeOptions, ApiCallParams } from '@route-forge/core';
+import { InterceptorHandler, RequestConfig, ResponseData, ForgeRouteName, ForgeApiParams, ForgeApiResponse, RouteMeta, RouteForge, ApiCallParams, RouteForgeOptions } from '@route-forge/core';
 
 /**
  * Vue 3 插件入口
@@ -8,28 +8,137 @@ import { RouteForge, RouteForgeOptions, ApiCallParams } from '@route-forge/core'
  * 提供：
  *   - 全局属性 $forge（route() 工具）
  *   - inject symbol 注入 RouteForge 实例供 composable 使用
+ *   - useForge() / useForge(level) / useForge(level, prefix) 返回统一方法的 forge 实例
+ *     • 不传 level：forge(level, name, params?) 直接调用
+ *     • 传 level：forge(name, params?) 直接调用，自动绑定层级
+ *     • 传 level + prefix：forge(suffix, params?) 自动拼接 prefix
+ *
+ * 类型推断：
+ *   当 ForgeRouteMap 通过 codegen 或 module augmentation 定义时，
+ *   level / name / params 均自动推断，IDE 提供补全提示。
  */
 
 declare const FORGE_INJECTION_KEY: InjectionKey<RouteForge>;
 interface RouteForgePluginOptions extends RouteForgeOptions {
 }
+/** 只读拦截器管理器：仅暴露查询方法，隐藏 use/eject/clear */
+interface ReadOnlyInterceptorManager<TIn, TOut = TIn> {
+    readonly size: number;
+    forEach(fn: (handler: InterceptorHandler<TIn, TOut>) => void): void;
+}
+/**
+ * 共享方法集（level 已绑定时的方法签名）
+ * .api() / .route() / .url() — name 和 params 根据 ForgeRouteMap 自动推断
+ * .load() / .invalidate() / .isLoaded() / .interceptors
+ */
+interface BoundForgeMethods<L extends string = string> {
+    interceptors: {
+        request: ReadOnlyInterceptorManager<RequestConfig>;
+        response: ReadOnlyInterceptorManager<ResponseData>;
+    };
+    api(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<ForgeApiResponse<L, ForgeRouteName<L>>>;
+    route(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): string;
+    url(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): string;
+    load(level: string | string[]): Promise<void>;
+    invalidate(level?: string): void;
+    isLoaded(level?: string): boolean;
+    hasRoute(level: string, name: string): boolean;
+    /** 获取指定层级下全部路由元信息（深拷贝，修改不影响内部缓存） */
+    getRoutes(level: string): Record<string, RouteMeta>;
+}
+/** 已绑定 level — 直接调用无需 level，api/route/url 的 name 自动限定到该层级 */
+interface BoundForgeTyped<L extends string> extends BoundForgeMethods<L> {
+    (name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<ForgeApiResponse<L, ForgeRouteName<L>>>;
+    /** 当前绑定的 level 值 */
+    readonly level: L;
+    /** 路由名前缀（仅在 useForge(level, prefix) 传入 prefix 时存在） */
+    readonly prefix?: string;
+}
+/** 未绑定 level — 直接调用需要传 level */
+interface ForgeInstanceTyped extends Omit<BoundForgeMethods<string>, 'api' | 'route' | 'url' | 'hasRoute' | 'getRoutes'> {
+    (level: string, name: string, params?: ApiCallParams): Promise<unknown>;
+    api(level: string, name: string, params?: ApiCallParams): Promise<unknown>;
+    route(level: string, name: string, params?: Record<string, unknown>): string;
+    url(level: string, name: string, params?: Record<string, unknown>): string;
+    hasRoute(level: string, name: string): boolean;
+    /** 获取全部层级路由（深拷贝）；传 level 时仅返回该层级 */
+    getRoutes(): Record<string, Record<string, RouteMeta>>;
+    getRoutes(level: string): Record<string, RouteMeta>;
+}
 declare function createRouteForgePlugin(options: RouteForgePluginOptions): Plugin<[]>;
-declare function useForge(): RouteForge;
+/**
+ * 获取 forge 实例。
+ *
+ * @example
+ * // 不绑定层级
+ * const forge = useForge()
+ * forge('admin', 'users.show', { user: 1 })
+ * forge.api('admin', 'users.show')
+ *
+ * @example
+ * // 绑定层级 — 直接调用和 api/route/url 均无需传 level
+ * const forge = useForge('admin')
+ * forge.level                    // → 'admin'
+ * forge('users.show', { user: 1 })
+ * forge.api('users.show')
+ *
+ * @example
+ * // 绑定层级 + 前缀 — 路由名自动拼接
+ * const forge = useForge('admin', 'users')
+ * forge.level                    // → 'admin'
+ * forge.prefix                   // → 'users'
+ * forge('show', { user: 1 })           // → forge.api('admin', 'users.show', ...)
+ * forge.api('index')                   // → forge.api('admin', 'users.index')
+ * forge.route('show', { user: 1 })     // → forge.route('admin', 'users.show', ...)
+ */
+declare function useForge<L extends string>(level: L, prefix: string): BoundForgeTyped<L>;
+declare function useForge<L extends string>(level: L): BoundForgeTyped<L>;
+declare function useForge(): ForgeInstanceTyped;
 
 /**
  * useForgeApi：包装 forge.api()，自动管理 loading/error 状态
  * @see .docs/SPEC.md §4.1.7
+ *
+ * 支持：
+ *   - useForgeApi()             — call(level, name, params)
+ *   - useForgeApi(level)        — call(name, params)，自动绑定层级
+ *   - useForgeApi(level, prefix) — call(suffix, params)，自动绑定层级 + 拼接前缀
+ *
+ * 类型推断：
+ *   当 ForgeRouteMap 通过 codegen 或 module augmentation 定义时，
+ *   level / name / params 均自动推断，IDE 提供补全提示。
  */
 
-interface UseForgeApiReturn {
-    pending: ReturnType<typeof ref<boolean>>;
-    error: ReturnType<typeof ref<unknown>>;
-    call: (level: string, name: string, params?: ApiCallParams) => Promise<{
+/** call 函数签名 — 未绑定 level，需要显式传入 */
+interface UseForgeApiCall {
+    (level: string, name: string, params?: ApiCallParams): Promise<{
         data: unknown;
         error: unknown;
     }>;
 }
+/** call 函数签名 — 已绑定 level，无需再传 */
+interface UseForgeApiBoundCall<L extends string> {
+    (name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<{
+        data: ForgeApiResponse<L, ForgeRouteName<L>>;
+        error: unknown;
+    }>;
+}
+interface UseForgeApiReturn {
+    pending: ReturnType<typeof ref<boolean>>;
+    error: ReturnType<typeof ref<unknown>>;
+    call: UseForgeApiCall;
+}
+interface UseForgeApiBoundReturn<L extends string> {
+    pending: ReturnType<typeof ref<boolean>>;
+    error: ReturnType<typeof ref<unknown>>;
+    call: UseForgeApiBoundCall<L>;
+}
+/** 不绑定层级 — call 需要传 level */
 declare function useForgeApi(): UseForgeApiReturn;
+/** 绑定层级 — call 无需传 level */
+declare function useForgeApi<L extends string>(level: L): UseForgeApiBoundReturn<L>;
+/** 绑定层级 + 前缀 — call 无需传 level，路由名自动拼接 prefix */
+declare function useForgeApi<L extends string>(level: L, prefix: string): UseForgeApiBoundReturn<L>;
 
 /**
  * useForgeLevel：声明组件依赖某层级，挂载时自动 forge.load(level)，销毁时不主动失效
@@ -53,9 +162,15 @@ declare function useForgeRoute(level: string | (() => string), name: string | ((
  * useForgeByPrefix：带层级 + 名字前缀的封装，方便后续减少名称传入
  * @see .docs/SPEC.md §4.1.7
  *
- * 示例：
- *   const { api } = useForgeByPrefix('admin', 'users');
- *   await api('show', { user: 1 });   // 等价于 forge.api('admin', 'users.show', { user: 1 })
+ * 智能前缀解析：
+ *   - 传入后缀不以前缀开头 → 自动拼接 prefix.suffix
+ *   - 传入后缀已以前缀开头（歧义） → 优先尝试完整拼接，
+ *     若不存在则视为已含前缀直接使用，均不存在则报错
+ *
+ * 示例（prefix = 'test'）：
+ *   api('1')        → test.1
+ *   api('test1.1')  → test.test1.1
+ *   api('test.1')   → 歧义：优先 test.test.1，回退 test.1
  */
 
 interface UseForgeByPrefixReturn {
@@ -64,4 +179,4 @@ interface UseForgeByPrefixReturn {
 }
 declare function useForgeByPrefix(level: string, prefix: string, separator?: string): UseForgeByPrefixReturn;
 
-export { FORGE_INJECTION_KEY, type RouteForgePluginOptions, type UseForgeApiReturn, type UseForgeByPrefixReturn, type UseForgeLevelReturn, createRouteForgePlugin, useForge, useForgeApi, useForgeByPrefix, useForgeLevel, useForgeRoute };
+export { type BoundForgeMethods, type BoundForgeTyped, FORGE_INJECTION_KEY, type ForgeInstanceTyped, type RouteForgePluginOptions, type UseForgeApiBoundCall, type UseForgeApiBoundReturn, type UseForgeApiCall, type UseForgeApiReturn, type UseForgeByPrefixReturn, type UseForgeLevelReturn, createRouteForgePlugin, useForge, useForgeApi, useForgeByPrefix, useForgeLevel, useForgeRoute };

package/dist/index.js

@@ -1,5 +1,24 @@
 import { inject, ref, onMounted, computed } from 'vue';
-import { createRouteForge } from '@route-forge/core';
+import { createRouteForge, UnknownRouteError } from '@route-forge/core';
+
+// src/plugin.ts
+async function resolveRouteName(forge, level, prefix, suffix, separator = ".") {
+  if (!suffix) return prefix;
+  const joined = `${prefix}${separator}${suffix}`;
+  if (!suffix.startsWith(`${prefix}${separator}`)) return joined;
+  await forge.load(level);
+  if (forge.hasRoute(level, joined)) return joined;
+  if (forge.hasRoute(level, suffix)) return suffix;
+  throw new UnknownRouteError(joined, level);
+}
+function resolveRouteNameSync(forge, level, prefix, suffix, separator = ".") {
+  if (!suffix) return prefix;
+  const joined = `${prefix}${separator}${suffix}`;
+  if (!suffix.startsWith(`${prefix}${separator}`)) return joined;
+  if (forge.hasRoute(level, joined)) return joined;
+  if (forge.hasRoute(level, suffix)) return suffix;
+  throw new UnknownRouteError(joined, level);
+}
 
 // src/plugin.ts
 var FORGE_INJECTION_KEY = /* @__PURE__ */ Symbol("route-forge");
@@ -14,24 +33,65 @@ function createRouteForgePlugin(options) {
     }
   };
 }
-function useForge() {
+function useForge(level, prefix) {
   const forge = inject(FORGE_INJECTION_KEY);
   if (!forge) {
     throw new Error(
       "[route-forge/vue] useForge() must be used inside an app with createRouteForgePlugin() installed"
     );
   }
-  return forge;
+  if (level !== void 0) {
+    const callable2 = prefix ? async (name, params) => forge.api(level, await resolveRouteName(forge, level, prefix, name), params) : (name, params) => forge.api(level, name, params);
+    defineImmutableProps(callable2, {
+      level,
+      prefix,
+      api: prefix ? async (name, params) => forge.api(level, await resolveRouteName(forge, level, prefix, name), params) : (name, params) => forge.api(level, name, params),
+      route: prefix ? (name, params) => forge.route(level, resolveRouteNameSync(forge, level, prefix, name), params) : (name, params) => forge.route(level, name, params),
+      url: prefix ? (name, params) => forge.route(level, resolveRouteNameSync(forge, level, prefix, name), params) : (name, params) => forge.route(level, name, params),
+      load: forge.load.bind(forge),
+      invalidate: forge.invalidate.bind(forge),
+      isLoaded: forge.isLoaded.bind(forge),
+      hasRoute: forge.hasRoute.bind(forge),
+      getRoutes: forge.getRoutes.bind(forge),
+      interceptors: forge.interceptors
+    });
+    return callable2;
+  }
+  const callable = (lvl, name, params) => forge.api(lvl, name, params);
+  defineImmutableProps(callable, {
+    api: forge.api.bind(forge),
+    route: forge.route.bind(forge),
+    url: forge.url.bind(forge),
+    load: forge.load.bind(forge),
+    invalidate: forge.invalidate.bind(forge),
+    isLoaded: forge.isLoaded.bind(forge),
+    hasRoute: forge.hasRoute.bind(forge),
+    getRoutes: forge.getRoutes.bind(forge),
+    interceptors: forge.interceptors
+  });
+  return callable;
 }
-function useForgeApi() {
-  const forge = useForge();
+function defineImmutableProps(target, props) {
+  for (const key of Object.keys(props)) {
+    const val = props[key];
+    Object.defineProperty(target, key, {
+      value: val !== null && typeof val === "object" ? Object.freeze(val) : val,
+      writable: false,
+      enumerable: false,
+      configurable: false
+    });
+  }
+  return target;
+}
+function useForgeApi(level, prefix) {
+  const forge = level !== void 0 ? useForge(level, prefix) : useForge();
   const pending = ref(false);
   const error = ref(null);
-  async function call(level, name, params) {
+  async function call(...args) {
     pending.value = true;
     error.value = null;
     try {
-      const data = await forge.api(level, name, params);
+      const data = await forge.api(...args);
       return { data, error: null };
     } catch (e) {
       error.value = e;
@@ -69,10 +129,11 @@ function useForgeRoute(level, name, params) {
 // src/composables/useForgeByPrefix.ts
 function useForgeByPrefix(level, prefix, separator = ".") {
   const forge = useForge();
-  const join = (suffix) => suffix ? `${prefix}${separator}${suffix}` : prefix;
   return {
-    api: (suffix, params) => forge.api(level, join(suffix), params),
-    route: (suffix, params) => forge.route(level, join(suffix), params)
+    api: (suffix, params) => resolveRouteName(forge, level, prefix, suffix, separator).then(
+      (name) => forge.api(level, name, params)
+    ),
+    route: (suffix, params) => forge.route(level, resolveRouteNameSync(forge, level, prefix, suffix, separator), params)
   };
 }
 

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/plugin.ts","../src/composables/useForgeApi.ts","../src/composables/useForgeLevel.ts","../src/composables/useForgeRoute.ts","../src/composables/useForgeByPrefix.ts"],"names":["ref"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Vue 3 插件入口\n * @see .docs/SPEC.md §4.1.7\n *\n * 提供：\n *   - 全局属性 $forge（route() 工具）\n *   - inject symbol 注入 RouteForge 实例供 composable 使用\n */\n\nimport type { App, InjectionKey, Plugin } from 'vue';\nimport { inject, reactive, readonly } from 'vue';\nimport { createRouteForge, type RouteForge, type RouteForgeOptions } from '@route-forge/core';\n\nexport const FORGE_INJECTION_KEY: InjectionKey<RouteForge> = Symbol('route-forge');\n\nexport interface RouteForgePluginOptions extends RouteForgeOptions {}\n\nexport function createRouteForgePlugin(options: RouteForgePluginOptions): Plugin<[]> {\n  const forge = createRouteForge(options);\n\n  return {\n    install(app: App) {\n      app.provide(FORGE_INJECTION_KEY, forge);\n      app.config.globalProperties.$forge = {\n        route: (level: string, name: string, params?: Record<string, unknown>) =>\n          forge.route(level, name, params),\n      };\n    },\n  };\n}\n\nexport function useForge(): RouteForge {\n  const forge = inject(FORGE_INJECTION_KEY);\n  if (!forge) {\n    throw new Error(\n      '[route-forge/vue] useForge() must be used inside an app with createRouteForgePlugin() installed',\n    );\n  }\n  return forge;\n}\n\nexport { readonly, reactive };\n","/**\n * useForgeApi：包装 forge.api()，自动管理 loading/error 状态\n * @see .docs/SPEC.md §4.1.7\n */\n\nimport { ref } from 'vue';\nimport { useForge } from '../plugin.js';\nimport type { ApiCallParams } from '@route-forge/core';\n\nexport interface UseForgeApiReturn {\n  pending: ReturnType<typeof ref<boolean>>;\n  error: ReturnType<typeof ref<unknown>>;\n  call: (level: string, name: string, params?: ApiCallParams) => Promise<{\n    data: unknown;\n    error: unknown;\n  }>;\n}\n\nexport function useForgeApi(): UseForgeApiReturn {\n  const forge = useForge();\n  const pending = ref(false);\n  const error = ref<unknown>(null);\n\n  async function call(level: string, name: string, params?: ApiCallParams) {\n    pending.value = true;\n    error.value = null;\n    try {\n      const data = await forge.api(level, name, params);\n      return { data, error: null };\n    } catch (e) {\n      error.value = e;\n      return { data: undefined, error: e };\n    } finally {\n      pending.value = false;\n    }\n  }\n\n  return { pending, error, call };\n}\n","/**\n * useForgeLevel：声明组件依赖某层级，挂载时自动 forge.load(level)，销毁时不主动失效\n * @see .docs/SPEC.md §4.1.7\n */\n\nimport { onMounted, ref } from 'vue';\nimport { useForge } from '../plugin.js';\n\nexport interface UseForgeLevelReturn {\n  loaded: ReturnType<typeof ref<boolean>>;\n  error: ReturnType<typeof ref<unknown>>;\n}\n\nexport function useForgeLevel(level: string): UseForgeLevelReturn {\n  const forge = useForge();\n  const loaded = ref(false);\n  const error = ref<unknown>(null);\n\n  onMounted(async () => {\n    try {\n      await forge.load(level);\n      loaded.value = true;\n    } catch (e) {\n      error.value = e;\n    }\n  });\n\n  return { loaded, error };\n}\n","/**\n * useForgeRoute：仅生成 URL，不发请求（用于 <a href>、外部跳转等）\n * @see .docs/SPEC.md §4.1.7\n */\n\nimport { computed, type ComputedRef } from 'vue';\nimport { useForge } from '../plugin.js';\n\nexport function useForgeRoute(\n  level: string | (() => string),\n  name: string | (() => string),\n  params?: () => Record<string, unknown>,\n): ComputedRef<string> {\n  const forge = useForge();\n  return computed(() => {\n    const lvl = typeof level === 'function' ? level() : level;\n    const n = typeof name === 'function' ? name() : name;\n    const p = params ? params() : undefined;\n    return forge.route(lvl, n, p);\n  });\n}\n","/**\n * useForgeByPrefix：带层级 + 名字前缀的封装，方便后续减少名称传入\n * @see .docs/SPEC.md §4.1.7\n *\n * 示例：\n *   const { api } = useForgeByPrefix('admin', 'users');\n *   await api('show', { user: 1 });   // 等价于 forge.api('admin', 'users.show', { user: 1 })\n */\n\nimport { useForge } from '../plugin.js';\nimport type { ApiCallParams } from '@route-forge/core';\n\nexport interface UseForgeByPrefixReturn {\n  api: (suffix: string, params?: ApiCallParams) => Promise<unknown>;\n  route: (suffix: string, params?: Record<string, unknown>) => string;\n}\n\nexport function useForgeByPrefix(level: string, prefix: string, separator = '.'): UseForgeByPrefixReturn {\n  const forge = useForge();\n\n  const join = (suffix: string) => (suffix ? `${prefix}${separator}${suffix}` : prefix);\n\n  return {\n    api: (suffix, params) => forge.api(level, join(suffix), params),\n    route: (suffix, params) => forge.route(level, join(suffix), params),\n  };\n}\n"]}
+{"version":3,"sources":["../src/utils/resolveRouteName.ts","../src/plugin.ts","../src/composables/useForgeApi.ts","../src/composables/useForgeLevel.ts","../src/composables/useForgeRoute.ts","../src/composables/useForgeByPrefix.ts"],"names":["callable","ref"],"mappings":";;;;AA6BA,eAAsB,iBACpB,KAAA,EACA,KAAA,EACA,MAAA,EACA,MAAA,EACA,YAAY,GAAA,EACK;AAEjB,EAAA,IAAI,CAAC,QAAQ,OAAO,MAAA;AAEpB,EAAA,MAAM,SAAS,CAAA,EAAG,MAAM,CAAA,EAAG,SAAS,GAAG,MAAM,CAAA,CAAA;AAG7C,EAAA,IAAI,CAAC,OAAO,UAAA,CAAW,CAAA,EAAG,MAAM,CAAA,EAAG,SAAS,CAAA,CAAE,CAAA,EAAG,OAAO,MAAA;AAGxD,EAAA,MAAM,KAAA,CAAM,KAAK,KAAK,CAAA;AAGtB,EAAA,IAAI,KAAA,CAAM,QAAA,CAAS,KAAA,EAAO,MAAM,GAAG,OAAO,MAAA;AAE1C,EAAA,IAAI,KAAA,CAAM,QAAA,CAAS,KAAA,EAAO,MAAM,GAAG,OAAO,MAAA;AAG1C,EAAA,MAAM,IAAI,iBAAA,CAAkB,MAAA,EAAQ,KAAK,CAAA;AAC3C;AAMO,SAAS,qBACd,KAAA,EACA,KAAA,EACA,MAAA,EACA,MAAA,EACA,YAAY,GAAA,EACJ;AACR,EAAA,IAAI,CAAC,QAAQ,OAAO,MAAA;AAEpB,EAAA,MAAM,SAAS,CAAA,EAAG,MAAM,CAAA,EAAG,SAAS,GAAG,MAAM,CAAA,CAAA;AAC7C,EAAA,IAAI,CAAC,OAAO,UAAA,CAAW,CAAA,EAAG,MAAM,CAAA,EAAG,SAAS,CAAA,CAAE,CAAA,EAAG,OAAO,MAAA;AAGxD,EAAA,IAAI,KAAA,CAAM,QAAA,CAAS,KAAA,EAAO,MAAM,GAAG,OAAO,MAAA;AAC1C,EAAA,IAAI,KAAA,CAAM,QAAA,CAAS,KAAA,EAAO,MAAM,GAAG,OAAO,MAAA;AAE1C,EAAA,MAAM,IAAI,iBAAA,CAAkB,MAAA,EAAQ,KAAK,CAAA;AAC3C;;;AC3CO,IAAM,mBAAA,0BAAuD,aAAa;AA+D1E,SAAS,uBAAuB,OAAA,EAA8C;AACnF,EAAA,MAAM,KAAA,GAAQ,iBAAiB,OAAO,CAAA;AAEtC,EAAA,OAAO;AAAA,IACL,QAAQ,GAAA,EAAU;AAChB,MAAA,GAAA,CAAI,OAAA,CAAQ,qBAAqB,KAAK,CAAA;AACtC,MAAA,GAAA,CAAI,MAAA,CAAO,iBAAiB,MAAA,GAAS;AAAA,QACnC,KAAA,EAAO,CAAC,KAAA,EAAe,IAAA,EAAc,WACnC,KAAA,CAAM,KAAA,CAAM,KAAA,EAAO,IAAA,EAAM,MAAM;AAAA,OACnC;AAAA,IACF;AAAA,GACF;AACF;AA8BO,SAAS,QAAA,CAAS,OAAgB,MAAA,EAA+D;AACtG,EAAA,MAAM,KAAA,GAAQ,OAAO,mBAAmB,CAAA;AACxC,EAAA,IAAI,CAAC,KAAA,EAAO;AACV,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AAEA,EAAA,IAAI,UAAU,MAAA,EAAW;AACvB,IAAA,MAAMA,SAAAA,GAAW,MAAA,GACb,OAAO,IAAA,EAAc,MAAA,KACrB,MAAM,GAAA,CAAI,KAAA,EAAO,MAAM,gBAAA,CAAiB,KAAA,EAAO,KAAA,EAAO,QAAQ,IAAI,CAAA,EAAG,MAAM,CAAA,GAC3E,CAAC,IAAA,EAAc,WACf,KAAA,CAAM,GAAA,CAAI,KAAA,EAAO,IAAA,EAAM,MAAM,CAAA;AACjC,IAAA,oBAAA,CAAqBA,SAAAA,EAAU;AAAA,MAC7B,KAAA;AAAA,MACA,MAAA;AAAA,MACA,GAAA,EAAK,MAAA,GACD,OAAO,IAAA,EAAc,MAAA,KACrB,MAAM,GAAA,CAAI,KAAA,EAAO,MAAM,gBAAA,CAAiB,KAAA,EAAO,KAAA,EAAO,QAAQ,IAAI,CAAA,EAAG,MAAM,CAAA,GAC3E,CAAC,IAAA,EAAc,WAA2B,KAAA,CAAM,GAAA,CAAI,KAAA,EAAO,IAAA,EAAM,MAAM,CAAA;AAAA,MAC3E,KAAA,EAAO,SACH,CAAC,IAAA,EAAc,WACf,KAAA,CAAM,KAAA,CAAM,KAAA,EAAO,oBAAA,CAAqB,KAAA,EAAO,KAAA,EAAO,QAAQ,IAAI,CAAA,EAAG,MAAM,CAAA,GAC3E,CAAC,IAAA,EAAc,WAAqC,KAAA,CAAM,KAAA,CAAM,KAAA,EAAO,IAAA,EAAM,MAAM,CAAA;AAAA,MACvF,GAAA,EAAK,SACD,CAAC,IAAA,EAAc,WACf,KAAA,CAAM,KAAA,CAAM,KAAA,EAAO,oBAAA,CAAqB,KAAA,EAAO,KAAA,EAAO,QAAQ,IAAI,CAAA,EAAG,MAAM,CAAA,GAC3E,CAAC,IAAA,EAAc,WAAqC,KAAA,CAAM,KAAA,CAAM,KAAA,EAAO,IAAA,EAAM,MAAM,CAAA;AAAA,MACvF,IAAA,EAAM,KAAA,CAAM,IAAA,CAAK,IAAA,CAAK,KAAK,CAAA;AAAA,MAC3B,UAAA,EAAY,KAAA,CAAM,UAAA,CAAW,IAAA,CAAK,KAAK,CAAA;AAAA,MACvC,QAAA,EAAU,KAAA,CAAM,QAAA,CAAS,IAAA,CAAK,KAAK,CAAA;AAAA,MACnC,QAAA,EAAU,KAAA,CAAM,QAAA,CAAS,IAAA,CAAK,KAAK,CAAA;AAAA,MACnC,SAAA,EAAW,KAAA,CAAM,SAAA,CAAU,IAAA,CAAK,KAAK,CAAA;AAAA,MACrC,cAAc,KAAA,CAAM;AAAA,KACrB,CAAA;AACD,IAAA,OAAOA,SAAAA;AAAA,EACT;AAEA,EAAA,MAAM,QAAA,GAAW,CAAC,GAAA,EAAa,IAAA,EAAc,WAC3C,KAAA,CAAM,GAAA,CAAI,GAAA,EAAK,IAAA,EAAM,MAAM,CAAA;AAC7B,EAAA,oBAAA,CAAqB,QAAA,EAAU;AAAA,IAC7B,GAAA,EAAK,KAAA,CAAM,GAAA,CAAI,IAAA,CAAK,KAAK,CAAA;AAAA,IACzB,KAAA,EAAO,KAAA,CAAM,KAAA,CAAM,IAAA,CAAK,KAAK,CAAA;AAAA,IAC7B,GAAA,EAAK,KAAA,CAAM,GAAA,CAAI,IAAA,CAAK,KAAK,CAAA;AAAA,IACzB,IAAA,EAAM,KAAA,CAAM,IAAA,CAAK,IAAA,CAAK,KAAK,CAAA;AAAA,IAC3B,UAAA,EAAY,KAAA,CAAM,UAAA,CAAW,IAAA,CAAK,KAAK,CAAA;AAAA,IACvC,QAAA,EAAU,KAAA,CAAM,QAAA,CAAS,IAAA,CAAK,KAAK,CAAA;AAAA,IACnC,QAAA,EAAU,KAAA,CAAM,QAAA,CAAS,IAAA,CAAK,KAAK,CAAA;AAAA,IACnC,SAAA,EAAW,KAAA,CAAM,SAAA,CAAU,IAAA,CAAK,KAAK,CAAA;AAAA,IACrC,cAAc,KAAA,CAAM;AAAA,GACrB,CAAA;AACD,EAAA,OAAO,QAAA;AACT;AASA,SAAS,oBAAA,CAAuC,QAAW,KAAA,EAAmC;AAC5F,EAAA,KAAA,MAAW,GAAA,IAAO,MAAA,CAAO,IAAA,CAAK,KAAK,CAAA,EAAG;AACpC,IAAA,MAAM,GAAA,GAAM,MAAM,GAAG,CAAA;AACrB,IAAA,MAAA,CAAO,cAAA,CAAe,QAAQ,GAAA,EAAK;AAAA,MACjC,KAAA,EAAO,QAAQ,IAAA,IAAQ,OAAO,QAAQ,QAAA,GAAW,MAAA,CAAO,MAAA,CAAO,GAAG,CAAA,GAAI,GAAA;AAAA,MACtE,QAAA,EAAU,KAAA;AAAA,MACV,UAAA,EAAY,KAAA;AAAA,MACZ,YAAA,EAAc;AAAA,KACf,CAAA;AAAA,EACH;AACA,EAAA,OAAO,MAAA;AACT;AC3JO,SAAS,WAAA,CAAY,OAAgB,MAAA,EAAqE;AAC/G,EAAA,MAAM,QAAQ,KAAA,KAAU,MAAA,GAAY,SAAS,KAAA,EAAO,MAAgB,IAAI,QAAA,EAAS;AACjF,EAAA,MAAM,OAAA,GAAU,IAAI,KAAK,CAAA;AACzB,EAAA,MAAM,KAAA,GAAQ,IAAa,IAAI,CAAA;AAE/B,EAAA,eAAe,QAAQ,IAAA,EAA6D;AAClF,IAAA,OAAA,CAAQ,KAAA,GAAQ,IAAA;AAChB,IAAA,KAAA,CAAM,KAAA,GAAQ,IAAA;AACd,IAAA,IAAI;AAEF,MAAA,MAAM,IAAA,GAAO,MAAO,KAAA,CAAc,GAAA,CAAI,GAAG,IAAI,CAAA;AAC7C,MAAA,OAAO,EAAE,IAAA,EAAM,KAAA,EAAO,IAAA,EAAK;AAAA,IAC7B,SAAS,CAAA,EAAG;AACV,MAAA,KAAA,CAAM,KAAA,GAAQ,CAAA;AACd,MAAA,OAAO,EAAE,IAAA,EAAM,MAAA,EAAW,KAAA,EAAO,CAAA,EAAE;AAAA,IACrC,CAAA,SAAE;AACA,MAAA,OAAA,CAAQ,KAAA,GAAQ,KAAA;AAAA,IAClB;AAAA,EACF;AAEA,EAAA,OAAO,EAAE,OAAA,EAAS,KAAA,EAAO,IAAA,EAAkB;AAC7C;ACjEO,SAAS,cAAc,KAAA,EAAoC;AAChE,EAAA,MAAM,QAAQ,QAAA,EAAS;AACvB,EAAA,MAAM,MAAA,GAASC,IAAI,KAAK,CAAA;AACxB,EAAA,MAAM,KAAA,GAAQA,IAAa,IAAI,CAAA;AAE/B,EAAA,SAAA,CAAU,YAAY;AACpB,IAAA,IAAI;AACF,MAAA,MAAM,KAAA,CAAM,KAAK,KAAK,CAAA;AACtB,MAAA,MAAA,CAAO,KAAA,GAAQ,IAAA;AAAA,IACjB,SAAS,CAAA,EAAG;AACV,MAAA,KAAA,CAAM,KAAA,GAAQ,CAAA;AAAA,IAChB;AAAA,EACF,CAAC,CAAA;AAED,EAAA,OAAO,EAAE,QAAQ,KAAA,EAAM;AACzB;ACpBO,SAAS,aAAA,CACd,KAAA,EACA,IAAA,EACA,MAAA,EACqB;AACrB,EAAA,MAAM,QAAQ,QAAA,EAAS;AACvB,EAAA,OAAO,SAAS,MAAM;AACpB,IAAA,MAAM,GAAA,GAAM,OAAO,KAAA,KAAU,UAAA,GAAa,OAAM,GAAI,KAAA;AACpD,IAAA,MAAM,CAAA,GAAI,OAAO,IAAA,KAAS,UAAA,GAAa,MAAK,GAAI,IAAA;AAChD,IAAA,MAAM,CAAA,GAAI,MAAA,GAAS,MAAA,EAAO,GAAI,MAAA;AAC9B,IAAA,OAAO,KAAA,CAAM,KAAA,CAAM,GAAA,EAAK,CAAA,EAAG,CAAC,CAAA;AAAA,EAC9B,CAAC,CAAA;AACH;;;ACIO,SAAS,gBAAA,CAAiB,KAAA,EAAe,MAAA,EAAgB,SAAA,GAAY,GAAA,EAA6B;AACvG,EAAA,MAAM,QAAQ,QAAA,EAAS;AAEvB,EAAA,OAAO;AAAA,IACL,GAAA,EAAK,CAAC,MAAA,EAAQ,MAAA,KACZ,gBAAA,CAAiB,OAAO,KAAA,EAAO,MAAA,EAAQ,MAAA,EAAQ,SAAS,CAAA,CAAE,IAAA;AAAA,MACxD,CAAC,IAAA,KAAS,KAAA,CAAM,GAAA,CAAI,KAAA,EAAO,MAAM,MAAM;AAAA,KACzC;AAAA,IACF,KAAA,EAAO,CAAC,MAAA,EAAQ,MAAA,KACd,MAAM,KAAA,CAAM,KAAA,EAAO,oBAAA,CAAqB,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,MAAA,EAAQ,SAAS,GAAG,MAAM;AAAA,GAC5F;AACF","file":"index.js","sourcesContent":["/**\n * 智能路由名前缀解析\n *\n * 当前缀与后缀拼接产生歧义时（后缀本身已以前缀开头），\n * 通过查询已加载路由表来判定正确名称：\n *   - 优先尝试 prefix + sep + suffix（完整拼接）\n *   - 若不存在则回退到 suffix（视为已含前缀）\n *   - 均不存在则抛 UnknownRouteError\n *\n * @see .docs/SPEC.md §4.1.7\n */\n\nimport { UnknownRouteError } from '@route-forge/core';\n\n/**\n * 路由名解析所需的最小 forge 接口。\n * 仅依赖 load() 和 hasRoute()，不依赖拦截器等完整能力。\n * 兼容 RouteForge、BoundForgeTyped、ForgeInstanceTyped 等所有形态。\n */\ninterface RouteResolver {\n  load(level: string | string[]): Promise<void>;\n\n  hasRoute(level: string, name: string): boolean;\n}\n\n/**\n * 异步版本：先确保层级已加载，再做歧义消解。\n * 适用于 api() 调用路径。\n */\nexport async function resolveRouteName(\n  forge: RouteResolver,\n  level: string,\n  prefix: string,\n  suffix: string,\n  separator = '.',\n): Promise<string> {\n  // 后缀为空 → 直接返回前缀\n  if (!suffix) return prefix;\n\n  const joined = `${prefix}${separator}${suffix}`;\n\n  // 后缀不以前缀开头 → 无歧义，直接拼接\n  if (!suffix.startsWith(`${prefix}${separator}`)) return joined;\n\n  // 歧义场景：先确保层级已加载\n  await forge.load(level);\n\n  // 优先尝试完整拼接\n  if (forge.hasRoute(level, joined)) return joined;\n  // 回退到后缀本身（视为已含前缀）\n  if (forge.hasRoute(level, suffix)) return suffix;\n\n  // 均不存在 → 报错\n  throw new UnknownRouteError(joined, level);\n}\n\n/**\n * 同步版本：基于已加载缓存做歧义消解。\n * 适用于 route() / url() 调用路径（要求层级已加载）。\n */\nexport function resolveRouteNameSync(\n  forge: RouteResolver,\n  level: string,\n  prefix: string,\n  suffix: string,\n  separator = '.',\n): string {\n  if (!suffix) return prefix;\n\n  const joined = `${prefix}${separator}${suffix}`;\n  if (!suffix.startsWith(`${prefix}${separator}`)) return joined;\n\n  // 歧义场景：基于已加载缓存判定\n  if (forge.hasRoute(level, joined)) return joined;\n  if (forge.hasRoute(level, suffix)) return suffix;\n\n  throw new UnknownRouteError(joined, level);\n}\n","/**\n * Vue 3 插件入口\n * @see .docs/SPEC.md §4.1.7\n *\n * 提供：\n *   - 全局属性 $forge（route() 工具）\n *   - inject symbol 注入 RouteForge 实例供 composable 使用\n *   - useForge() / useForge(level) / useForge(level, prefix) 返回统一方法的 forge 实例\n *     • 不传 level：forge(level, name, params?) 直接调用\n *     • 传 level：forge(name, params?) 直接调用，自动绑定层级\n *     • 传 level + prefix：forge(suffix, params?) 自动拼接 prefix\n *\n * 类型推断：\n *   当 ForgeRouteMap 通过 codegen 或 module augmentation 定义时，\n *   level / name / params 均自动推断，IDE 提供补全提示。\n */\n\nimport type { App, InjectionKey, Plugin } from 'vue';\nimport { inject, reactive, readonly } from 'vue';\nimport {\n  type ApiCallParams,\n  createRouteForge,\n  type ForgeApiParams,\n  type ForgeApiResponse,\n  type ForgeRouteName,\n  type InterceptorHandler,\n  type RequestConfig,\n  type ResponseData,\n  type RouteForge,\n  type RouteForgeOptions,\n  type RouteMeta,\n} from '@route-forge/core';\nimport { resolveRouteName, resolveRouteNameSync } from './utils/resolveRouteName.js';\n\nexport const FORGE_INJECTION_KEY: InjectionKey<RouteForge> = Symbol('route-forge');\n\nexport interface RouteForgePluginOptions extends RouteForgeOptions {}\n\n/** 只读拦截器管理器：仅暴露查询方法，隐藏 use/eject/clear */\ninterface ReadOnlyInterceptorManager<TIn, TOut = TIn> {\n  readonly size: number;\n\n  forEach(fn: (handler: InterceptorHandler<TIn, TOut>) => void): void;\n}\n\n/**\n * 共享方法集（level 已绑定时的方法签名）\n * .api() / .route() / .url() — name 和 params 根据 ForgeRouteMap 自动推断\n * .load() / .invalidate() / .isLoaded() / .interceptors\n */\nexport interface BoundForgeMethods<L extends string = string> {\n  interceptors: {\n    request: ReadOnlyInterceptorManager<RequestConfig>;\n    response: ReadOnlyInterceptorManager<ResponseData>;\n  };\n\n  api(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<ForgeApiResponse<L, ForgeRouteName<L>>>;\n\n  route(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): string;\n\n  url(name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): string;\n\n  load(level: string | string[]): Promise<void>;\n\n  invalidate(level?: string): void;\n\n  isLoaded(level?: string): boolean;\n\n  hasRoute(level: string, name: string): boolean;\n\n  /** 获取指定层级下全部路由元信息（深拷贝，修改不影响内部缓存） */\n  getRoutes(level: string): Record<string, RouteMeta>;\n}\n\n/** 已绑定 level — 直接调用无需 level，api/route/url 的 name 自动限定到该层级 */\nexport interface BoundForgeTyped<L extends string> extends BoundForgeMethods<L> {\n  (name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<ForgeApiResponse<L, ForgeRouteName<L>>>;\n  /** 当前绑定的 level 值 */\n  readonly level: L;\n  /** 路由名前缀（仅在 useForge(level, prefix) 传入 prefix 时存在） */\n  readonly prefix?: string;\n}\n\n/** 未绑定 level — 直接调用需要传 level */\nexport interface ForgeInstanceTyped extends Omit<BoundForgeMethods<string>, 'api' | 'route' | 'url' | 'hasRoute' | 'getRoutes'> {\n  (level: string, name: string, params?: ApiCallParams): Promise<unknown>;\n  api(level: string, name: string, params?: ApiCallParams): Promise<unknown>;\n  route(level: string, name: string, params?: Record<string, unknown>): string;\n  url(level: string, name: string, params?: Record<string, unknown>): string;\n\n  hasRoute(level: string, name: string): boolean;\n\n  /** 获取全部层级路由（深拷贝）；传 level 时仅返回该层级 */\n  getRoutes(): Record<string, Record<string, RouteMeta>>;\n  getRoutes(level: string): Record<string, RouteMeta>;\n}\n\nexport function createRouteForgePlugin(options: RouteForgePluginOptions): Plugin<[]> {\n  const forge = createRouteForge(options);\n\n  return {\n    install(app: App) {\n      app.provide(FORGE_INJECTION_KEY, forge);\n      app.config.globalProperties.$forge = {\n        route: (level: string, name: string, params?: Record<string, unknown>) =>\n          forge.route(level, name, params),\n      };\n    },\n  };\n}\n\n/**\n * 获取 forge 实例。\n *\n * @example\n * // 不绑定层级\n * const forge = useForge()\n * forge('admin', 'users.show', { user: 1 })\n * forge.api('admin', 'users.show')\n *\n * @example\n * // 绑定层级 — 直接调用和 api/route/url 均无需传 level\n * const forge = useForge('admin')\n * forge.level                    // → 'admin'\n * forge('users.show', { user: 1 })\n * forge.api('users.show')\n *\n * @example\n * // 绑定层级 + 前缀 — 路由名自动拼接\n * const forge = useForge('admin', 'users')\n * forge.level                    // → 'admin'\n * forge.prefix                   // → 'users'\n * forge('show', { user: 1 })           // → forge.api('admin', 'users.show', ...)\n * forge.api('index')                   // → forge.api('admin', 'users.index')\n * forge.route('show', { user: 1 })     // → forge.route('admin', 'users.show', ...)\n */\nexport function useForge<L extends string>(level: L, prefix: string): BoundForgeTyped<L>;\nexport function useForge<L extends string>(level: L): BoundForgeTyped<L>;\nexport function useForge(): ForgeInstanceTyped;\nexport function useForge(level?: string, prefix?: string): ForgeInstanceTyped | BoundForgeTyped<string> {\n  const forge = inject(FORGE_INJECTION_KEY);\n  if (!forge) {\n    throw new Error(\n      '[route-forge/vue] useForge() must be used inside an app with createRouteForgePlugin() installed',\n    );\n  }\n\n  if (level !== undefined) {\n    const callable = prefix\n      ? async (name: string, params?: ApiCallParams) =>\n        forge.api(level, await resolveRouteName(forge, level, prefix, name), params)\n      : (name: string, params?: ApiCallParams) =>\n        forge.api(level, name, params);\n    defineImmutableProps(callable, {\n      level,\n      prefix,\n      api: prefix\n        ? async (name: string, params?: ApiCallParams) =>\n          forge.api(level, await resolveRouteName(forge, level, prefix, name), params)\n        : (name: string, params?: ApiCallParams) => forge.api(level, name, params),\n      route: prefix\n        ? (name: string, params?: Record<string, unknown>) =>\n          forge.route(level, resolveRouteNameSync(forge, level, prefix, name), params)\n        : (name: string, params?: Record<string, unknown>) => forge.route(level, name, params),\n      url: prefix\n        ? (name: string, params?: Record<string, unknown>) =>\n          forge.route(level, resolveRouteNameSync(forge, level, prefix, name), params)\n        : (name: string, params?: Record<string, unknown>) => forge.route(level, name, params),\n      load: forge.load.bind(forge),\n      invalidate: forge.invalidate.bind(forge),\n      isLoaded: forge.isLoaded.bind(forge),\n      hasRoute: forge.hasRoute.bind(forge),\n      getRoutes: forge.getRoutes.bind(forge),\n      interceptors: forge.interceptors,\n    });\n    return callable as unknown as BoundForgeTyped<string>;\n  }\n\n  const callable = (lvl: string, name: string, params?: ApiCallParams) =>\n    forge.api(lvl, name, params);\n  defineImmutableProps(callable, {\n    api: forge.api.bind(forge),\n    route: forge.route.bind(forge),\n    url: forge.url.bind(forge),\n    load: forge.load.bind(forge),\n    invalidate: forge.invalidate.bind(forge),\n    isLoaded: forge.isLoaded.bind(forge),\n    hasRoute: forge.hasRoute.bind(forge),\n    getRoutes: forge.getRoutes.bind(forge),\n    interceptors: forge.interceptors,\n  });\n  return callable as ForgeInstanceTyped;\n}\n\nexport { readonly, reactive };\n\n/**\n * 以不可变、不可枚举、不可重配置的方式将属性挂载到目标对象上。\n * 相比 Object.assign 更安全——外部无法通过遍历/删除/重写篡改这些方法。\n * 对象类型的值会浅冻结（Object.freeze），防止内部键被增删改。\n */\nfunction defineImmutableProps<T extends object>(target: T, props: Record<string, unknown>): T {\n  for (const key of Object.keys(props)) {\n    const val = props[key];\n    Object.defineProperty(target, key, {\n      value: val !== null && typeof val === 'object' ? Object.freeze(val) : val,\n      writable: false,\n      enumerable: false,\n      configurable: false,\n    });\n  }\n  return target;\n}\n","/**\n * useForgeApi：包装 forge.api()，自动管理 loading/error 状态\n * @see .docs/SPEC.md §4.1.7\n *\n * 支持：\n *   - useForgeApi()             — call(level, name, params)\n *   - useForgeApi(level)        — call(name, params)，自动绑定层级\n *   - useForgeApi(level, prefix) — call(suffix, params)，自动绑定层级 + 拼接前缀\n *\n * 类型推断：\n *   当 ForgeRouteMap 通过 codegen 或 module augmentation 定义时，\n *   level / name / params 均自动推断，IDE 提供补全提示。\n */\n\nimport { ref } from 'vue';\nimport { useForge } from '../plugin.js';\nimport type {\n  ApiCallParams,\n  ForgeApiParams,\n  ForgeApiResponse,\n  ForgeRouteName,\n} from '@route-forge/core';\n\n/** call 函数签名 — 未绑定 level，需要显式传入 */\nexport interface UseForgeApiCall {\n  (level: string, name: string, params?: ApiCallParams): Promise<{\n    data: unknown;\n    error: unknown;\n  }>;\n}\n\n/** call 函数签名 — 已绑定 level，无需再传 */\nexport interface UseForgeApiBoundCall<L extends string> {\n  (name: ForgeRouteName<L>, params?: ForgeApiParams<L, ForgeRouteName<L>>): Promise<{\n    data: ForgeApiResponse<L, ForgeRouteName<L>>;\n    error: unknown;\n  }>;\n}\n\nexport interface UseForgeApiReturn {\n  pending: ReturnType<typeof ref<boolean>>;\n  error: ReturnType<typeof ref<unknown>>;\n  call: UseForgeApiCall;\n}\n\nexport interface UseForgeApiBoundReturn<L extends string> {\n  pending: ReturnType<typeof ref<boolean>>;\n  error: ReturnType<typeof ref<unknown>>;\n  call: UseForgeApiBoundCall<L>;\n}\n\n/** 不绑定层级 — call 需要传 level */\nexport function useForgeApi(): UseForgeApiReturn;\n/** 绑定层级 — call 无需传 level */\nexport function useForgeApi<L extends string>(level: L): UseForgeApiBoundReturn<L>;\n/** 绑定层级 + 前缀 — call 无需传 level，路由名自动拼接 prefix */\nexport function useForgeApi<L extends string>(level: L, prefix: string): UseForgeApiBoundReturn<L>;\nexport function useForgeApi(level?: string, prefix?: string): UseForgeApiReturn | UseForgeApiBoundReturn<string> {\n  const forge = level !== undefined ? useForge(level, prefix as string) : useForge();\n  const pending = ref(false);\n  const error = ref<unknown>(null);\n\n  async function call(...args: unknown[]): Promise<{ data: unknown; error: unknown }> {\n    pending.value = true;\n    error.value = null;\n    try {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      const data = await (forge as any).api(...args);\n      return { data, error: null };\n    } catch (e) {\n      error.value = e;\n      return { data: undefined, error: e };\n    } finally {\n      pending.value = false;\n    }\n  }\n\n  return { pending, error, call: call as any };\n}\n","/**\n * useForgeLevel：声明组件依赖某层级，挂载时自动 forge.load(level)，销毁时不主动失效\n * @see .docs/SPEC.md §4.1.7\n */\n\nimport { onMounted, ref } from 'vue';\nimport { useForge } from '../plugin.js';\n\nexport interface UseForgeLevelReturn {\n  loaded: ReturnType<typeof ref<boolean>>;\n  error: ReturnType<typeof ref<unknown>>;\n}\n\nexport function useForgeLevel(level: string): UseForgeLevelReturn {\n  const forge = useForge();\n  const loaded = ref(false);\n  const error = ref<unknown>(null);\n\n  onMounted(async () => {\n    try {\n      await forge.load(level);\n      loaded.value = true;\n    } catch (e) {\n      error.value = e;\n    }\n  });\n\n  return { loaded, error };\n}\n","/**\n * useForgeRoute：仅生成 URL，不发请求（用于 <a href>、外部跳转等）\n * @see .docs/SPEC.md §4.1.7\n */\n\nimport { computed, type ComputedRef } from 'vue';\nimport { useForge } from '../plugin.js';\n\nexport function useForgeRoute(\n  level: string | (() => string),\n  name: string | (() => string),\n  params?: () => Record<string, unknown>,\n): ComputedRef<string> {\n  const forge = useForge();\n  return computed(() => {\n    const lvl = typeof level === 'function' ? level() : level;\n    const n = typeof name === 'function' ? name() : name;\n    const p = params ? params() : undefined;\n    return forge.route(lvl, n, p);\n  });\n}\n","/**\n * useForgeByPrefix：带层级 + 名字前缀的封装，方便后续减少名称传入\n * @see .docs/SPEC.md §4.1.7\n *\n * 智能前缀解析：\n *   - 传入后缀不以前缀开头 → 自动拼接 prefix.suffix\n *   - 传入后缀已以前缀开头（歧义） → 优先尝试完整拼接，\n *     若不存在则视为已含前缀直接使用，均不存在则报错\n *\n * 示例（prefix = 'test'）：\n *   api('1')        → test.1\n *   api('test1.1')  → test.test1.1\n *   api('test.1')   → 歧义：优先 test.test.1，回退 test.1\n */\n\nimport { useForge } from '../plugin.js';\nimport { resolveRouteName, resolveRouteNameSync } from '../utils/resolveRouteName.js';\nimport type { ApiCallParams } from '@route-forge/core';\n\nexport interface UseForgeByPrefixReturn {\n  api: (suffix: string, params?: ApiCallParams) => Promise<unknown>;\n  route: (suffix: string, params?: Record<string, unknown>) => string;\n}\n\nexport function useForgeByPrefix(level: string, prefix: string, separator = '.'): UseForgeByPrefixReturn {\n  const forge = useForge();\n\n  return {\n    api: (suffix, params) =>\n      resolveRouteName(forge, level, prefix, suffix, separator).then(\n        (name) => forge.api(level, name, params),\n      ),\n    route: (suffix, params) =>\n      forge.route(level, resolveRouteNameSync(forge, level, prefix, suffix, separator), params),\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@route-forge/vue",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Route Forge 的 Vue 3 集成：插件 + composable（useForgeApi/useForgeLevel/useForgeRoute/useForgeByPrefix）",
   "license": "MIT",
   "author": "阿杰很厉害 <506907958@qq.com>",
@@ -40,7 +40,7 @@
     "vue": "^3.4.0"
   },
   "dependencies": {
-    "@route-forge/core": "0.2.0"
+    "@route-forge/core": "0.3.0"
   },
   "publishConfig": {
     "access": "public"