@longzai-intelligence-transport/http-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3136 @@
+import * as z from "zod";
+import { ZodError, ZodType } from "zod";
+import { CompactPaginatedResult, CursorPaginatedResult, CursorPaginationParams, CursorPaginationParamsSchema, OffsetPaginatedResult, OffsetPaginationParams, OffsetPaginationParamsSchema, PaginatedResult, PaginationParams, PaginationParamsSchema, calculateOffset, calculateTotalPages, createPaginatedResult, normalizePagination } from "@longzai-intelligence/pagination";
+import { Result } from "@longzai-intelligence/shared-kernel";
+import { AxiosRequestConfig, AxiosResponse } from "axios";
+import { Logger } from "@longzai-intelligence/logger-core";
+
+//#region src/contract/response.schema.d.ts
+/**
+ * API 响应数据类型
+ *
+ * 统一的 API 响应结构，支持服务端和客户端两种使用场景：
+ * - 服务端：包含 data/message/timestamp
+ * - 客户端：包含 data/error
+ *
+ * @typeParam T - 响应数据类型
+ */
+type ApiResponse<T = unknown> = {
+  /**
+   * 请求是否成功
+   */
+  success: boolean;
+  /**
+   * 响应数据，成功时存在
+   */
+  data?: T;
+  /**
+   * 响应消息，失败时存在
+   */
+  message?: string;
+  /**
+   * 错误信息，客户端错误响应时存在
+   */
+  error?: ApiError;
+  /**
+   * 响应时间戳，服务端生成
+   */
+  timestamp?: number;
+  /**
+   * 元数据，用于传递额外信息（如重试状态）
+   */
+  metadata?: Record<string, unknown>;
+};
+/**
+ * API 成功响应类型
+ *
+ * @typeParam T - 响应数据类型
+ */
+type ApiSuccessResponse<T> = ApiResponse<T> & ApiSuccessResponseData<T>;
+/**
+ * API 成功响应数据
+ *
+ * @typeParam T - 响应数据类型
+ */
+type ApiSuccessResponseData<T> = {
+  /**
+   * 请求是否成功
+   */
+  success: true;
+  /**
+   * 响应数据
+   */
+  data: T;
+};
+/**
+ * API 失败响应类型
+ *
+ * @typeParam T - 错误数据类型
+ */
+type ApiFailResponse<T = unknown> = ApiResponse<T> & ApiFailResponseData;
+/**
+ * API 失败响应数据
+ *
+ * @typeParam T - 错误数据类型
+ */
+type ApiFailResponseData = {
+  /**
+   * 请求是否成功
+   */
+  success: false;
+  /**
+   * 响应消息
+   */
+  message: string;
+};
+/**
+ * API 列表数据类型
+ *
+ * @typeParam T - 列表项类型
+ */
+type ApiListData<T> = {
+  /**
+   * 列表项数组
+   */
+  items: T[];
+  /**
+   * 总数
+   */
+  total: number;
+};
+/**
+ * API 分页列表数据类型
+ *
+ * 基于 @longzai-intelligence/pagination 的 PaginatedResult
+ * 适用于需要完整分页控制的场景（带跳页、总数显示）
+ *
+ * @typeParam T - 列表项类型
+ */
+type ApiPaginatedListData<T> = PaginatedResult<T>;
+/**
+ * API 紧凑分页列表数据类型
+ *
+ * 基于 @longzai-intelligence/pagination 的 CompactPaginatedResult
+ * 适用于不需要跳页的列表场景（如下拉加载更多）
+ *
+ * @typeParam T - 列表项类型
+ */
+type ApiCompactPaginatedListData<T> = CompactPaginatedResult<T>;
+/**
+ * 重新导出 @longzai-intelligence/pagination 的分页类型和工具函数
+ */
+/**
+ * API 错误 Schema
+ *
+ * 描述 API 错误响应的结构
+ */
+declare const ApiErrorSchema: z.ZodObject<{
+  code: z.ZodString;
+  message: z.ZodString;
+  details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * API 错误类型
+ */
+type ApiError = z.infer<typeof ApiErrorSchema>;
+/**
+ * API 响应 Schema 工厂
+ *
+ * 创建包含 success/data/message/error/timestamp 结构的 Zod Schema
+ *
+ * @typeParam T - 数据部分的 Zod Schema 类型
+ * @param dataSchema - 数据部分的 Zod Schema
+ * @returns API 响应 Zod Schema
+ */
+declare const ApiResponseSchema: <T extends z.ZodTypeAny>(dataSchema: T) => z.ZodObject<{
+  success: z.ZodBoolean;
+  data: z.ZodOptional<T>;
+  message: z.ZodOptional<z.ZodString>;
+  error: z.ZodOptional<z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>>;
+  timestamp: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * API 列表数据 Schema 工厂
+ *
+ * 创建包含 items/total 结构的 Zod Schema
+ *
+ * @typeParam T - 列表项的 Zod Schema 类型
+ * @param itemSchema - 列表项的 Zod Schema
+ * @returns 列表数据 Zod Schema
+ */
+declare const ApiListDataSchema: <T extends z.ZodTypeAny>(itemSchema: T) => z.ZodObject<{
+  items: z.ZodArray<T>;
+  total: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * API 分页列表数据 Schema 工厂
+ *
+ * 基于 @longzai-intelligence/pagination 的 createPaginatedResultSchema
+ *
+ * @typeParam T - 列表项 Schema 类型
+ * @param itemSchema - 列表项的 Zod Schema
+ * @returns 分页列表数据 Zod Schema
+ */
+declare const ApiPaginatedListDataSchema: <T extends z.ZodTypeAny>(itemSchema: T) => z.ZodObject<{
+  items: z.ZodArray<T>;
+  total: z.ZodNumber;
+  page: z.ZodNumber;
+  pageSize: z.ZodNumber;
+  totalPages: z.ZodNumber;
+  hasNextPage: z.ZodBoolean;
+  hasPreviousPage: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * API 紧凑分页列表数据 Schema 工厂
+ *
+ * 基于 @longzai-intelligence/pagination 的 createCompactPaginatedResultSchema
+ *
+ * @typeParam T - 列表项 Schema 类型
+ * @param itemSchema - 列表项的 Zod Schema
+ * @returns 紧凑分页列表数据 Zod Schema
+ */
+declare const ApiCompactPaginatedListDataSchema: <T extends z.ZodTypeAny>(itemSchema: T) => z.ZodObject<{
+  items: z.ZodArray<T>;
+  total: z.ZodNumber;
+  hasMore: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * 空响应 Schema
+ *
+ * 用于无返回数据的 API 响应
+ */
+declare const EmptyResponseSchema: z.ZodObject<{
+  success: z.ZodBoolean;
+  data: z.ZodOptional<z.ZodVoid>;
+  message: z.ZodOptional<z.ZodString>;
+  error: z.ZodOptional<z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>>;
+  timestamp: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * 空响应类型
+ */
+type EmptyResponse = ApiResponse<void>;
+//#endregion
+//#region src/contract/type-utils.types.d.ts
+/**
+ * 从对象类型中提取 data 字段的类型
+ *
+ * 如果对象有 data 字段，则返回 data 字段的类型（排除 undefined），否则返回原类型
+ *
+ * @example
+ *   type Result = ExtractData<{ data: string }>; // string
+ *
+ * @typeParam T - 对象类型
+ */
+type ExtractData<T> = T extends DataField<infer D> ? NonNullable<D> : T;
+/**
+ * 数据字段类型
+ *
+ * @typeParam D - data 字段的类型
+ */
+type DataField<D> = {
+  /**
+   * 可选的 data 字段
+   */
+  data?: D;
+} | {
+  /**
+   * 必选的 data 字段
+   */
+  data: D;
+};
+/**
+ * 从 ApiResponse 中解包数据类型
+ *
+ * @example
+ *   type Result = UnwrapApiResponse<ApiResponse<string>>; // string
+ *
+ * @typeParam T - ApiResponse 类型
+ */
+type UnwrapApiResponse<T> = T extends ApiResponse<infer D> ? D : T;
+/**
+ * 从 ApiListData 中解包数组项类型
+ *
+ * @example
+ *   type Result = UnwrapApiListData<ApiListData<string>>; // string[]
+ *
+ * @typeParam T - ApiListData 类型
+ */
+type UnwrapApiListData<T> = T extends ApiListData<infer I> ? I[] : T;
+/**
+ * 从 ApiPaginatedListData 中解包数组项类型
+ *
+ * @example
+ *   type Result = UnwrapApiPaginatedListData<ApiPaginatedListData<string>>; // string[]
+ *
+ * @typeParam T - ApiPaginatedListData 类型
+ */
+type UnwrapApiPaginatedListData<T> = T extends ApiPaginatedListData<infer I> ? I[] : T;
+/**
+ * 从可能为 null 或 undefined 的类型中提取非空类型
+ *
+ * @typeParam T - 输入类型
+ */
+type NonNullableData<T> = NonNullable<T>;
+/**
+ * 从数组类型中提取元素类型
+ *
+ * @example
+ *   type Result = ArrayElement<string[]>; // string
+ *
+ * @typeParam T - 数组类型
+ */
+type ArrayElement<T> = T extends (infer E)[] ? E : never;
+/**
+ * 从 Promise 类型中提取解析后的类型
+ *
+ * @typeParam T - Promise 类型
+ */
+type AwaitedData<T> = Awaited<T>;
+/**
+ * 从函数返回类型中提取类型
+ *
+ * @typeParam T - 函数类型
+ */
+type ReturnDataType<T extends (...args: unknown[]) => unknown> = ReturnType<T>;
+/**
+ * 深度部分类型
+ *
+ * 支持嵌套对象的部分更新
+ *
+ * @typeParam T - 对象类型
+ */
+type DeepPartial<T> = { [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P] };
+/**
+ * 深度必需类型
+ *
+ * 将所有嵌套的可选字段变为必需
+ *
+ * @typeParam T - 对象类型
+ */
+type DeepRequired<T> = { [P in keyof T]-?: T[P] extends object ? DeepRequired<T[P]> : T[P] };
+/**
+ * 深度只读类型
+ *
+ * 将所有嵌套的字段变为只读
+ *
+ * @typeParam T - 对象类型
+ */
+type DeepReadonly<T> = { readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P] };
+/**
+ * 从对象类型中选取特定值类型的键
+ *
+ * @example
+ *   type Result = PickByValue<{ a: string; b: number }, string>; // { a: string }
+ *
+ * @typeParam T - 对象类型
+ * @typeParam V - 值类型
+ */
+type PickByValue<T, V> = Pick<T, { [K in keyof T]: T[K] extends V ? K : never }[keyof T]>;
+/**
+ * 从对象类型中排除特定值类型的键
+ *
+ * @example
+ *   type Result = OmitByValue<{ a: string; b: number }, string>; // { b: number }
+ *
+ * @typeParam T - 对象类型
+ * @typeParam V - 值类型
+ */
+type OmitByValue<T, V> = Pick<T, { [K in keyof T]: T[K] extends V ? never : K }[keyof T]>;
+/**
+ * 将对象类型的键转换为联合类型
+ *
+ * @typeParam T - 对象类型
+ */
+type ObjectKeys<T extends object> = keyof T;
+/**
+ * 将对象类型的值转换为联合类型
+ *
+ * @typeParam T - 对象类型
+ */
+type ObjectValues<T extends object> = T[keyof T];
+/**
+ * 将两个对象类型合并
+ *
+ * 后者的属性会覆盖前者的同名属性
+ *
+ * @typeParam T - 第一个对象类型
+ * @typeParam U - 第二个对象类型
+ */
+type Merge<T, U> = Omit<T, keyof U> & U;
+/**
+ * 将对象类型的所有键变为可选
+ *
+ * @typeParam T - 对象类型
+ */
+type OptionalKeys<T> = { [K in keyof T]?: T[K] };
+/**
+ * 将对象类型的所有键变为必需
+ *
+ * @typeParam T - 对象类型
+ */
+type RequiredKeys<T> = { [K in keyof T]-?: T[K] };
+/**
+ * 从对象类型中提取可选键
+ *
+ * @example
+ *   type Result = OptionalKeyOf<{ a: string; b?: number }>; // 'b'
+ *
+ * @typeParam T - 对象类型
+ */
+type OptionalKeyOf<T extends object> = { [K in keyof T]-?: undefined extends T[K] ? K : never }[keyof T];
+/**
+ * 从对象类型中提取必需键
+ *
+ * @example
+ *   type Result = RequiredKeyOf<{ a: string; b?: number }>; // 'a'
+ *
+ * @typeParam T - 对象类型
+ */
+type RequiredKeyOf<T extends object> = { [K in keyof T]-?: undefined extends T[K] ? never : K }[keyof T];
+//#endregion
+//#region src/contract/request.types.d.ts
+/**
+ * HTTP 请求方法类型
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * 请求配置类型
+ *
+ * 每次请求的额外配置选项，如认证、自定义头、超时等
+ */
+type RequestConfig = {
+  /**
+   * 是否携带认证令牌
+   */
+  withAuth?: boolean;
+  /**
+   * 自定义请求头
+   */
+  headers?: Record<string, string>;
+  /**
+   * 请求超时时间（毫秒）
+   */
+  timeout?: number;
+  /**
+   * 中断信号
+   */
+  signal?: AbortSignal;
+  /**
+   * 是否携带 CSRF 令牌，与 RouteDefinition.csrf 配合使用
+   */
+  withCsrf?: boolean;
+};
+/**
+ * 路由定义类型
+ *
+ * 描述一个 API 路由的完整契约，包括方法、路径、参数、请求体和响应
+ *
+ * @typeParam TMethod - HTTP 方法类型
+ * @typeParam TPath - 路径模板字符串
+ * @typeParam TParams - 路径参数 Zod Schema
+ * @typeParam TQuery - 查询参数 Zod Schema
+ * @typeParam TBody - 请求体 Zod Schema
+ * @typeParam TResponse - 响应 Zod Schema
+ */
+type RouteDefinition<TMethod extends HttpMethod = HttpMethod, TPath extends string = string, TParams extends ZodType | undefined = ZodType | undefined, TQuery extends ZodType | undefined = ZodType | undefined, TBody extends ZodType | undefined = ZodType | undefined, TResponse extends ZodType = ZodType> = {
+  /**
+   * HTTP 方法
+   */
+  method: TMethod;
+  /**
+   * 路径模板，支持 :param 形式的路径参数
+   */
+  path: TPath;
+  /**
+   * 路径参数 Schema
+   */
+  params?: TParams;
+  /**
+   * 查询参数 Schema
+   */
+  query?: TQuery;
+  /**
+   * 请求体 Schema
+   */
+  body?: TBody;
+  /**
+   * 响应 Schema
+   */
+  response: TResponse;
+  /**
+   * 接口摘要描述
+   */
+  summary?: string;
+  /**
+   * 接口标签分组
+   */
+  tags?: string[];
+  /**
+   * 是否需要 CSRF 令牌保护，默认 false
+   */
+  csrf?: boolean;
+  /**
+   * 请求内容类型
+   *
+   * - 'json'：application/json（默认）
+   * - 'formData'：multipart/form-data，用于文件上传
+   */
+  contentType?: 'json' | 'formData';
+  /**
+   * 基础路径（NestJS 方法装饰器使用的相对路径）
+   *
+   * 由 defineRouteGroup.define 自动设置，值为原始子路径（不含分组前缀）。
+   * 未通过分组创建的路由不包含此字段。
+   */
+  basePath?: string;
+};
+/**
+ * 从路由定义中推断路径参数类型
+ *
+ * @example
+ *   type Params = InferRouteParams<typeof routes.detail>;
+ *   // { id: string }
+ *
+ * @typeParam T - 路由定义类型
+ */
+type InferRouteParams<T extends RouteDefinition> = T extends RouteDefinition<HttpMethod, string, infer P, ZodType | undefined, ZodType | undefined, ZodType> ? [P] extends [ZodType] ? P['_output'] : undefined : undefined;
+/**
+ * 从路由定义中推断查询参数类型
+ *
+ * @example
+ *   type Query = InferRouteQuery<typeof routes.list>;
+ *   // { page?: number; pageSize?: number }
+ *
+ * @typeParam T - 路由定义类型
+ */
+type InferRouteQuery<T extends RouteDefinition> = T extends RouteDefinition<HttpMethod, string, ZodType | undefined, infer Q, ZodType | undefined, ZodType> ? [Q] extends [ZodType] ? Q['_output'] : undefined : undefined;
+/**
+ * 从路由定义中推断请求体类型
+ *
+ * @example
+ *   type Body = InferRouteBody<typeof routes.create>;
+ *   // { name: string; price: number }
+ *
+ * @typeParam T - 路由定义类型
+ */
+type InferRouteBody<T extends RouteDefinition> = T extends RouteDefinition<HttpMethod, string, ZodType | undefined, ZodType | undefined, infer B, ZodType> ? [B] extends [ZodType] ? B['_output'] : undefined : undefined;
+/**
+ * 从路由定义中推断响应数据类型
+ *
+ * 自动解包 ApiResponse 和 PaginatedResponse
+ *
+ * @example
+ *   type Data = InferRouteResponse<typeof routes.detail>;
+ *   // User
+ *
+ * @typeParam T - 路由定义类型
+ */
+type InferRouteResponse<T extends RouteDefinition> = T extends RouteDefinition<HttpMethod, string, ZodType | undefined, ZodType | undefined, ZodType | undefined, infer R> ? [R] extends [ZodType] ? ExtractData<R['_output']> : never : never;
+/**
+ * 从路由定义中推断完整的响应类型
+ *
+ * 包含 ApiResponse 包装
+ *
+ * @example
+ *   type Response = InferRouteFullResponse<typeof routes.detail>;
+ *   // ApiResponse<User>
+ *
+ * @typeParam T - 路由定义类型
+ */
+type InferRouteFullResponse<T extends RouteDefinition> = T extends RouteDefinition<HttpMethod, string, ZodType | undefined, ZodType | undefined, ZodType | undefined, infer R> ? [R] extends [ZodType] ? ApiResponse<ExtractData<R['_output']>> : never : never;
+/**
+ * 从路由定义中推断分页响应的项类型
+ *
+ * @example
+ *   type Item = InferRouteItem<typeof routes.list>;
+ *   // User
+ *
+ * @typeParam T - 路由定义类型
+ */
+type InferRouteItem<T extends RouteDefinition> = InferRouteResponse<T> extends ApiListData<infer I> ? I : never;
+/**
+ * 从路由定义中推断控制器方法的返回值类型
+ *
+ * 包含 Promise + ApiResponse 包装，可直接用作控制器方法返回类型标注
+ *
+ * @example
+ *   type Return = InferRouteReturn<typeof routes.detail>;
+ *   // Promise<ApiResponse<User>>
+ *
+ * @typeParam T - 路由定义类型
+ */
+type InferRouteReturn<T extends RouteDefinition> = Promise<InferRouteFullResponse<T>>;
+//#endregion
+//#region src/interceptors/interceptor.types.d.ts
+/**
+ * 请求拦截器上下文
+ *
+ * 包含请求的所有信息，拦截器可修改并返回新的上下文
+ */
+type RequestInterceptorContext = {
+  /**
+   * 完整请求 URL
+   */
+  url: string;
+  /**
+   * HTTP 方法
+   */
+  method: HttpMethod;
+  /**
+   * 请求头
+   */
+  headers: Record<string, string>;
+  /**
+   * 路径参数
+   */
+  params?: Record<string, string | number>;
+  /**
+   * 查询参数
+   */
+  query?: Record<string, unknown>;
+  /**
+   * 请求体
+   */
+  body?: unknown;
+  /**
+   * 路由定义
+   */
+  route?: RouteDefinition;
+  /**
+   * 请求配置
+   */
+  config?: RequestConfig;
+  /**
+   * 元数据存储，用于拦截器间传递信息
+   */
+  metadata: Record<string, unknown>;
+};
+/**
+ * 响应拦截器上下文
+ *
+ * 包含响应的元信息，拦截器可访问但通常不修改
+ */
+type ResponseInterceptorContext = {
+  /**
+   * HTTP 状态码
+   */
+  status: number;
+  /**
+   * 响应头
+   */
+  headers: Record<string, string>;
+  /**
+   * 请求上下文（只读引用）
+   */
+  request: Readonly<RequestInterceptorContext>;
+};
+/**
+ * 请求拦截器接口
+ *
+ * 在请求发送前执行，可修改请求配置或添加元数据
+ */
+type RequestInterceptor = {
+  /**
+   * 请求处理函数
+   *
+   * @param context - 请求上下文
+   * @returns 修改后的请求上下文（同步或异步）
+   */
+  onRequest?(context: RequestInterceptorContext): RequestInterceptorContext | Promise<RequestInterceptorContext>;
+  /**
+   * 请求错误处理函数
+   *
+   * 当请求发送失败时调用，可用于错误转换或日志记录
+   *
+   * @param error - 原始错误
+   * @param context - 请求上下文
+   * @returns 转换后的错误或原始错误
+   */
+  onError?(error: unknown, context: RequestInterceptorContext): unknown;
+};
+/**
+ * 响应拦截器接口
+ *
+ * 在响应接收后执行，可修改响应数据或处理错误
+ */
+type ResponseInterceptor = {
+  /**
+   * 响应处理函数
+   *
+   * @param response - API 响应
+   * @param context - 响应上下文
+   * @returns 修改后的 API 响应（同步或异步）
+   */
+  onResponse?(response: ApiResponse, context: ResponseInterceptorContext): ApiResponse | Promise<ApiResponse>;
+  /**
+   * 响应错误处理函数
+   *
+   * 当响应处理失败时调用，可用于错误恢复或重试
+   *
+   * @param error - 原始错误
+   * @param context - 响应上下文
+   * @returns 转换后的错误、恢复的响应或原始错误
+   */
+  onError?(error: unknown, context: ResponseInterceptorContext): unknown | ApiResponse;
+};
+//#endregion
+//#region src/interceptors/executor.utils.d.ts
+/**
+ * HTTP 适配器接口
+ *
+ * 各运行时环境需实现此接口，拦截器执行器调用适配器执行实际 HTTP 请求
+ */
+type HttpAdapter$1 = {
+  /**
+   * 执行 HTTP 请求
+   *
+   * @param context - 请求上下文（已通过请求拦截器处理）
+   * @returns 包含状态码、响应头和响应数据的对象
+   */
+  execute(context: RequestInterceptorContext): Promise<AdapterResponse>;
+};
+/**
+ * 适配器响应类型
+ */
+type AdapterResponse = {
+  /**
+   * HTTP 状态码
+   */
+  status: number;
+  /**
+   * 响应头
+   */
+  headers: Record<string, string>;
+  /**
+   * 响应数据
+   */
+  data: unknown;
+};
+/**
+ * 拦截器执行器配置
+ */
+type InterceptorExecutorConfig = {
+  /**
+   * 请求拦截器列表
+   */
+  requestInterceptors: RequestInterceptor[];
+  /**
+   * 响应拦截器列表
+   */
+  responseInterceptors: ResponseInterceptor[];
+  /**
+   * 未授权回调
+   */
+  onUnauthorized?: OnUnauthorizedCallback;
+};
+/**
+ * 未授权回调函数类型
+ */
+type OnUnauthorizedCallback = () => void | Promise<void>;
+/**
+ * 创建拦截器执行器
+ *
+ * @param config - 执行器配置
+ * @param adapter - HTTP 适配器
+ * @returns 执行器实例
+ * @throws {@link Error} 当请求执行过程中发生错误时抛出
+ */
+declare function createInterceptorExecutor(config: InterceptorExecutorConfig, adapter: HttpAdapter$1): {
+  /**
+   * 执行完整请求流程
+   *
+   * @param context - 请求拦截器上下文
+   * @returns 最终 API 响应
+   */
+  execute: (context: RequestInterceptorContext) => Promise<ApiResponse>;
+  executeRequestInterceptors: (context: RequestInterceptorContext) => Promise<RequestInterceptorContext>;
+  executeResponseInterceptors: (response: ApiResponse, context: ResponseInterceptorContext) => Promise<ApiResponse>;
+  handleRequestError: (error: unknown, context: RequestInterceptorContext) => Promise<unknown>;
+  handleResponseError: (error: unknown, context: ResponseInterceptorContext) => Promise<unknown>;
+};
+/**
+ * 从 HttpClientConfig 创建拦截器执行器配置
+ *
+ * 将旧配置项转换为拦截器
+ *
+ * @param config - HTTP 客户端配置
+ * @returns 拦截器执行器配置
+ * @throws {@link Error} 当配置转换失败时抛出错误
+ */
+declare function createExecutorConfigFromClientConfig(config: HttpClientConfig): InterceptorExecutorConfig;
+//#endregion
+//#region src/interceptors/auth.interceptor.d.ts
+/**
+ * Auth 拦截器配置
+ */
+type AuthInterceptorConfig = {
+  /**
+   * 是否在请求头中携带认证，默认 true
+   * 可通过 RequestConfig.withAuth 覆盖
+   */
+  withAuth?: boolean;
+  /**
+   * Token 前缀，默认 'Bearer'
+   */
+  tokenPrefix?: string;
+  /**
+   * 请求头名称，默认 'Authorization'
+   */
+  headerName?: string;
+};
+/**
+ * 创建 Bearer Token 认证拦截器
+ *
+ * 自动从 TokenProvider 获取令牌并注入 Authorization 头
+ *
+ * @example
+ *   ```typescript
+ *   import {
+ *     createAuthTokenInterceptor,
+ *     createHttpClient,
+ *   } from '@longzai-intelligence-transport/http';
+ *
+ *   const tokenProvider = {
+ *     getToken: () => localStorage.getItem('token'),
+ *     setToken: (token) => localStorage.setItem('token', token),
+ *     removeToken: () => localStorage.removeItem('token'),
+ *   };
+ *
+ *   const client = createHttpClient({
+ *     baseUrl: 'https://api.example.com',
+ *     requestInterceptors: [createAuthTokenInterceptor(tokenProvider)],
+ *   });
+ *   ```;
+ *
+ * @param tokenProvider - 令牌提供者
+ * @param config - 配置选项
+ * @returns 请求拦截器
+ */
+declare function createAuthTokenInterceptor(tokenProvider: TokenProvider, config?: AuthInterceptorConfig): RequestInterceptor;
+//#endregion
+//#region src/interceptors/auth-strategy.interceptor.d.ts
+/**
+ * 创建多策略认证拦截器
+ *
+ * 根据 AuthStrategy 类型分发认证逻辑：
+ * - bearer: 注入 Authorization 头
+ * - cookie: 设置 withCredentials/credentials
+ * - custom: 调用 injector 函数
+ * - none: 不注入任何认证信息
+ *
+ * @example
+ *   ```typescript
+ *   import {
+ *     createAuthStrategyInterceptor,
+ *     createHttpClient,
+ *   } from '@longzai-intelligence-transport/http';
+ *
+ *   // Bearer Token 策略
+ *   const client = createHttpClient({
+ *     baseUrl: 'https://api.example.com',
+ *     requestInterceptors: [
+ *       createAuthStrategyInterceptor({
+ *         type: 'bearer',
+ *         tokenProvider: myTokenProvider,
+ *       }),
+ *     ],
+ *   });
+ *
+ *   // Cookie 策略
+ *   const cookieClient = createHttpClient({
+ *     baseUrl: 'https://api.example.com',
+ *     requestInterceptors: [
+ *       createAuthStrategyInterceptor({
+ *         type: 'cookie',
+ *         credentials: 'include',
+ *       }),
+ *     ],
+ *   });
+ *   ```;
+ *
+ * @param strategy - 认证策略
+ * @returns 请求拦截器
+ */
+declare function createAuthStrategyInterceptor(strategy: AuthStrategy): RequestInterceptor;
+/**
+ * 从 tokenProvider 创建 AuthStrategy
+ *
+ * @param tokenProvider - 令牌提供者
+ * @returns Bearer Token 认证策略
+ */
+declare function createBearerAuthStrategy(tokenProvider: TokenProvider): AuthStrategy;
+/**
+ * 创建 Cookie 认证策略
+ *
+ * @param credentials - 凭证模式
+ * @returns Cookie 认证策略
+ */
+declare function createCookieAuthStrategy(credentials?: 'include' | 'same-origin' | 'omit'): AuthStrategy;
+/**
+ * 创建自定义认证策略
+ *
+ * @param injector - 自定义注入器函数
+ * @returns 自定义认证策略
+ */
+declare function createCustomAuthStrategy(injector: CustomAuthInjector): AuthStrategy;
+/**
+ * 自定义认证注入器类型
+ */
+type CustomAuthInjector = (config: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * 创建无认证策略
+ *
+ * @returns 无认证策略
+ */
+declare function createNoneAuthStrategy(): AuthStrategy;
+//#endregion
+//#region src/interceptors/csrf.interceptor.d.ts
+/**
+ * CSRF 拦截器配置
+ */
+type CsrfInterceptorConfig = {
+  /**
+   * CSRF 请求头名称，默认 'X-CSRF-Token'
+   */
+  headerName?: string;
+  /**
+   * 是否对所有请求注入，默认 false（仅对 csrf: true 的路由注入）
+   */
+  injectAll?: boolean;
+  /**
+   * 令牌获取失败时的行为，默认 'warn'（输出警告）
+   */
+  onTokenError?: 'warn' | 'throw' | 'ignore';
+};
+/**
+ * 创建 CSRF 令牌拦截器
+ *
+ * 根据 RouteDefinition.csrf 标记自动注入 CSRF 令牌
+ *
+ * @example
+ *   ```typescript
+ *   import {
+ *     createCsrfInterceptor,
+ *     createHttpClient,
+ *     defineRoute,
+ *   } from '@longzai-intelligence-transport/http';
+ *
+ *   const csrfProvider = {
+ *     getToken: () => document.querySelector('meta[name="csrf-token"]')?.getAttribute('content'),
+ *   };
+ *
+ *   const client = createHttpClient({
+ *     baseUrl: 'https://api.example.com',
+ *     requestInterceptors: [createCsrfInterceptor(csrfProvider)],
+ *   });
+ *
+ *   // 定义需要 CSRF 保护的路由
+ *   const routes = {
+ *     create: defineRoute({
+ *       method: 'POST',
+ *       path: '/items',
+ *       csrf: true, // 标记需要 CSRF 保护
+ *       response: ItemSchema,
+ *     }),
+ *   };
+ *   ```;
+ *
+ * @param csrfProvider - CSRF 令牌提供者
+ * @param config - 配置选项
+ * @returns 请求拦截器
+ * @throws {@link Error} 当 onTokenError 设置为 'throw' 时，令牌获取失败会抛出错误
+ */
+declare function createCsrfInterceptor(csrfProvider: CsrfProvider, config?: CsrfInterceptorConfig): RequestInterceptor;
+//#endregion
+//#region src/interceptors/transform.interceptor.d.ts
+/**
+ * 响应转换器类型
+ */
+type ResponseTransformer$1 = (raw: unknown) => ApiResponse<unknown>;
+/**
+ * 创建响应转换拦截器
+ *
+ * 将非标准后端响应格式转换为 ApiResponse
+ *
+ * @example
+ *   ```typescript
+ *   import {
+ *     createResponseTransformerInterceptor,
+ *     createHttpClient,
+ *   } from '@longzai-intelligence-transport/http';
+ *
+ *   // 后端返回 { ok: true, result: { ... } } 格式
+ *   const client = createHttpClient({
+ *     baseUrl: 'https://api.example.com',
+ *     responseInterceptors: [
+ *       createResponseTransformerInterceptor((raw) => ({
+ *         success: (raw as any).ok,
+ *         data: (raw as any).result,
+ *         message: (raw as any).message,
+ *       })),
+ *     ],
+ *   });
+ *   ```;
+ *
+ * @param transformer - 响应转换函数
+ * @returns 响应拦截器
+ */
+declare function createResponseTransformerInterceptor(transformer: ResponseTransformer$1): ResponseInterceptor;
+//#endregion
+//#region src/interceptors/retry.interceptor.d.ts
+/**
+ * 重试配置
+ */
+type RetryConfig = {
+  /**
+   * 最大重试次数，默认 0（不重试）
+   */
+  maxRetries?: number;
+  /**
+   * 重试延迟（毫秒）或延迟计算函数
+   * 默认指数退避：baseDelay * 2^attempt
+   */
+  retryDelay?: number | ((attempt: number) => number);
+  /**
+   * 触发重试的 HTTP 状态码，默认 [408, 429, 500, 502, 503, 504]
+   */
+  retryOn?: number[];
+  /**
+   * 自定义重试条件
+   */
+  retryCondition?: (error: unknown, context: ResponseInterceptorContext) => boolean;
+  /**
+   * 基础延迟（毫秒），默认 1000
+   */
+  baseDelay?: number;
+};
+/**
+ * 默认触发重试的状态码
+ */
+declare const DEFAULT_RETRY_STATUS_CODES: number[];
+/**
+ * 创建重试拦截器
+ *
+ * 在请求失败时自动重试
+ *
+ * @example
+ *   ```typescript
+ *   import { createRetryInterceptor, createHttpClient } from '@longzai-intelligence-transport/http';
+ *
+ *   const client = createHttpClient({
+ *     baseUrl: 'https://api.example.com',
+ *     responseInterceptors: [
+ *       createRetryInterceptor({
+ *         maxRetries: 3,
+ *         baseDelay: 1000,
+ *         retryOn: [500, 502, 503, 504],
+ *       }),
+ *     ],
+ *   });
+ *   ```;
+ *
+ * @param config - 重试配置
+ * @returns 响应拦截器
+ */
+declare function createRetryInterceptor(config?: RetryConfig): ResponseInterceptor;
+/**
+ * 计算指数退避延迟
+ *
+ * @param attempt - 当前尝试次数
+ * @param baseDelay - 基础延迟（毫秒）
+ * @returns 延迟时间（毫秒）
+ */
+declare function exponentialBackoff(attempt: number, baseDelay?: number): number;
+//#endregion
+//#region src/interceptors/validation.interceptor.d.ts
+/**
+ * 验证拦截器配置
+ */
+type ValidationInterceptorConfig = {
+  /**
+   * 验证模式
+   * - true: 始终验证
+   * - 'development': 仅开发环境验证
+   * - false: 不验证
+   */
+  mode?: boolean | 'development';
+  /**
+   * 验证失败时的行为，默认 'warn'（输出警告）
+   */
+  onValidationError?: 'warn' | 'throw' | 'ignore';
+  /**
+   * 日志记录器实例
+   */
+  logger?: ValidationLogger;
+};
+/**
+ * 验证日志函数类型
+ */
+type ValidationLogger = Logger;
+/**
+ * 创建响应验证拦截器
+ *
+ * 在开发环境对响应数据进行运行时 Schema 验证
+ *
+ * @example
+ *   ```typescript
+ *   import {
+ *     createValidationInterceptor,
+ *     createHttpClient,
+ *   } from '@longzai-intelligence-transport/http';
+ *
+ *   const client = createHttpClient({
+ *     baseUrl: 'https://api.example.com',
+ *     responseInterceptors: [createValidationInterceptor({ mode: 'development' })],
+ *   });
+ *   ```;
+ *
+ * @param config - 配置选项
+ * @returns 响应拦截器
+ * @throws {@link Error} 当 onValidationError 为 'throw' 时，验证失败会抛出错误
+ */
+declare function createValidationInterceptor(config?: ValidationInterceptorConfig): ResponseInterceptor;
+//#endregion
+//#region src/interceptors/logging.interceptor.d.ts
+/**
+ * 日志拦截器配置
+ */
+type LoggingInterceptorConfig = {
+  /**
+   * 日志级别，默认 'info'
+   */
+  level?: 'debug' | 'info' | 'warn' | 'error';
+  /**
+   * 是否记录请求体，默认 false
+   */
+  logBody?: boolean;
+  /**
+   * 是否记录响应体，默认 false
+   */
+  logResponse?: boolean;
+  /**
+   * 自定义日志函数
+   */
+  logger?: (level: string, message: string, data?: unknown) => void;
+};
+/**
+ * 默认日志函数
+ *
+ * @param level - 日志级别
+ * @param message - 日志消息
+ * @param data - 日志数据
+ */
+declare function defaultLogger(level: string, message: string, data?: unknown): void;
+/**
+ * 创建日志请求拦截器
+ *
+ * @param config - 配置选项
+ * @returns 请求拦截器
+ */
+declare function createLoggingRequestInterceptor(config?: LoggingInterceptorConfig): RequestInterceptor;
+/**
+ * 创建日志响应拦截器
+ *
+ * @param config - 配置选项
+ * @returns 响应拦截器
+ */
+declare function createLoggingResponseInterceptor(config?: LoggingInterceptorConfig): ResponseInterceptor;
+/**
+ * 创建日志拦截器
+ *
+ * 返回请求拦截器和响应拦截器，用于记录请求和响应信息
+ *
+ * @example
+ *   ```typescript
+ *   import { createLoggingInterceptor, createHttpClient } from '@longzai-intelligence-transport/http';
+ *
+ *   const { request, response } = createLoggingInterceptor({ level: 'debug' });
+ *
+ *   const client = createHttpClient({
+ *     baseUrl: 'https://api.example.com',
+ *     requestInterceptors: [request],
+ *     responseInterceptors: [response],
+ *   });
+ *   ```;
+ *
+ * @param config - 配置选项
+ * @returns 包含请求拦截器和响应拦截器的对象
+ */
+declare function createLoggingInterceptor(config?: LoggingInterceptorConfig): LoggingInterceptorResult;
+/**
+ * 日志拦截器结果类型
+ */
+type LoggingInterceptorResult = {
+  /**
+   * 请求拦截器
+   */
+  request: RequestInterceptor;
+  /**
+   * 响应拦截器
+   */
+  response: ResponseInterceptor;
+};
+//#endregion
+//#region src/interceptors/legacy-converter.utils.d.ts
+/**
+ * 从旧配置创建请求拦截器
+ *
+ * @param config - HTTP 客户端配置
+ * @returns 请求拦截器列表
+ */
+declare function createRequestInterceptorsFromConfig(config: HttpClientConfig): RequestInterceptor[];
+/**
+ * 从配置创建响应拦截器
+ *
+ * 始终注入验证拦截器（除非 validation === false），
+ * 并追加用户自定义的响应拦截器
+ *
+ * @param config - HTTP 客户端配置
+ * @returns 响应拦截器列表
+ */
+declare function createResponseInterceptorsFromConfig(config: HttpClientConfig): ResponseInterceptor[];
+/**
+ * 检查配置是否使用旧模式
+ *
+ * @param config - HTTP 客户端配置
+ * @returns 是否使用旧模式
+ */
+declare function isLegacyConfig(config: HttpClientConfig): boolean;
+/**
+ * 输出 deprecation 警告
+ *
+ * @param config - HTTP 客户端配置
+ */
+declare function warnDeprecatedConfig(config: HttpClientConfig): void;
+//#endregion
+//#region src/contract/client.types.d.ts
+/**
+ * HTTP 客户端接口
+ *
+ * 定义统一的 HTTP 请求接口，各运行时适配器需实现此接口。
+ * 通过 request 方法基于路由定义实现类型安全的请求。
+ */
+type HttpClient = {
+  /**
+   * 发送类型安全的 HTTP 请求
+   *
+   * 基于路由定义自动推断参数和响应类型
+   *
+   * @typeParam TRoute - 路由定义类型
+   * @param options - 请求选项
+   * @returns API 响应
+   */
+  request<TRoute extends RouteDefinition>(options: {
+    /**
+     * 路由定义
+     */
+    route: TRoute;
+    /**
+     * 路径参数
+     */
+    params?: InferRouteParams<TRoute>;
+    /**
+     * 查询参数
+     */
+    query?: InferRouteQuery<TRoute>;
+    /**
+     * 请求体
+     */
+    body?: InferRouteBody<TRoute>;
+    /**
+     * 请求配置
+     */
+    config?: RequestConfig;
+  }): Promise<ApiResponse<InferRouteResponse<TRoute>>>;
+};
+/**
+ * 令牌提供者接口
+ *
+ * 定义认证令牌的获取、设置和移除操作。
+ * 仅 getToken 为必需方法，其余为可选。
+ */
+type TokenProvider = {
+  /**
+   * 获取当前认证令牌
+   */
+  getToken(): string | null | Promise<string | null>;
+  /**
+   * 设置认证令牌（可选）
+   */
+  setToken?(token: string): void | Promise<void>;
+  /**
+   * 移除认证令牌（可选）
+   */
+  removeToken?(): void | Promise<void>;
+  /**
+   * 获取刷新令牌（可选）
+   */
+  getRefreshToken?(): string | null | Promise<string | null>;
+  /**
+   * 设置刷新令牌（可选）
+   */
+  setRefreshToken?(token: string): void | Promise<void>;
+};
+/**
+ * 响应转换器类型
+ *
+ * 将非标准后端响应格式转换为 ApiResponse 格式。
+ * 当后端返回的响应格式与 ApiResponse 不同时，
+ * 可通过此转换器在客户端统一转换。
+ *
+ * @deprecated 使用 createResponseTransformerInterceptor 替代
+ * @param raw - 后端原始响应数据
+ * @returns 转换后的 API 响应
+ */
+type ResponseTransformer = (raw: unknown) => ApiResponse<unknown>;
+/**
+ * 认证策略类型
+ *
+ * 支持多种认证方式的联合类型，根据 type 字段区分策略：
+ * - bearer：Bearer Token 认证，使用 tokenProvider 获取令牌
+ * - cookie：Cookie/Session 认证，自动携带凭证
+ * - custom：自定义认证，通过 injector 注入认证信息
+ * - none：无认证，不注入任何认证信息
+ *
+ * @deprecated 使用 createAuthStrategyInterceptor 替代
+ */
+type AuthStrategy = {
+  /**
+   * Bearer Token 认证策略
+   */
+  type: 'bearer';
+  /**
+   * 令牌提供者实例
+   */
+  tokenProvider: TokenProvider;
+} | {
+  /**
+   * Cookie/Session 认证策略
+   */
+  type: 'cookie';
+  /**
+   * 请求凭证模式，默认 'include'
+   */
+  credentials?: 'include' | 'same-origin' | 'omit';
+} | {
+  /**
+   * 自定义认证策略
+   */
+  type: 'custom';
+  /**
+   * 自定义认证注入器，接收请求配置并返回修改后的配置
+   */
+  injector: (config: Record<string, unknown>) => Record<string, unknown>;
+} | {
+  /**
+   * 无认证策略
+   */
+  type: 'none';
+};
+/**
+ * CSRF 令牌提供者接口
+ *
+ * 定义 CSRF 令牌的获取操作，用于防止跨站请求伪造攻击
+ *
+ * @deprecated 使用 createCsrfInterceptor 替代
+ */
+type CsrfProvider = {
+  /**
+   * 获取 CSRF 令牌
+   */
+  getToken(): string | null | Promise<string | null>;
+};
+/**
+ * HTTP 客户端配置类型
+ *
+ * 创建 HTTP 客户端实例时所需的配置。
+ * 推荐使用拦截器模式进行扩展，旧配置项已标记为 deprecated。
+ */
+type HttpClientConfig = {
+  /**
+   * API 基础 URL
+   */
+  baseUrl: string;
+  /**
+   * 请求超时时间（毫秒）
+   */
+  timeout?: number;
+  /**
+   * 自定义请求头
+   */
+  headers?: Record<string, string>;
+  /**
+   * 请求拦截器列表
+   *
+   * 按注册顺序执行，用于在请求发送前修改请求配置
+   */
+  requestInterceptors?: RequestInterceptor[];
+  /**
+   * 响应拦截器列表
+   *
+   * 按注册顺序执行，用于在响应接收后修改响应数据
+   */
+  responseInterceptors?: ResponseInterceptor[];
+  /**
+   * 未授权回调
+   *
+   * 当收到 401 响应且所有拦截器都无法恢复时触发
+   */
+  onUnauthorized?: () => void | Promise<void>;
+  /**
+   * 令牌提供者实例
+   *
+   * @deprecated 使用 requestInterceptors + createAuthTokenInterceptor 替代
+   * 内部自动转换为 auth 拦截器
+   */
+  tokenProvider?: TokenProvider;
+  /**
+   * 认证策略
+   *
+   * @deprecated 使用 requestInterceptors + createAuthStrategyInterceptor 替代
+   * 内部自动转换为对应的 auth 拦截器
+   */
+  authStrategy?: AuthStrategy;
+  /**
+   * 响应转换器
+   *
+   * @deprecated 使用 responseInterceptors + createResponseTransformerInterceptor 替代
+   * 内部自动转换为响应拦截器
+   */
+  responseTransformer?: ResponseTransformer;
+  /**
+   * CSRF 令牌提供者
+   *
+   * @deprecated 使用 requestInterceptors + createCsrfInterceptor 替代
+   * 内部自动转换为 CSRF 拦截器
+   */
+  csrfProvider?: CsrfProvider;
+  /**
+   * CSRF 请求头名称
+   *
+   * @deprecated 在 createCsrfInterceptor 中配置
+   */
+  csrfHeaderName?: string;
+  /**
+   * 响应验证配置
+   *
+   * 启用后对响应数据执行 Zod Schema 验证（safeParse），
+   * 默认在开发环境以 warn 模式运行。
+   *
+   * - 传入配置对象自定义验证行为
+   * - 传入 false 显式禁用验证
+   * - 不传则使用默认值（开发环境 warn）
+   */
+  validation?: ValidationInterceptorConfig | false;
+};
+//#endregion
+//#region src/schemas/common.schema.d.ts
+/**
+ * ID 参数 Schema
+ *
+ * 用于需要单个 ID 的接口，如详情查询、删除等
+ */
+declare const IdParamsSchema: z.ZodObject<{
+  id: z.ZodString;
+}, z.core.$strip>;
+/**
+ * ID 参数类型
+ */
+type IdParams = z.infer<typeof IdParamsSchema>;
+/**
+ * 分页查询参数 Schema
+ *
+ * 基于 @longzai-intelligence/pagination 的 PaginationParamsSchema 扩展，
+ * 添加 z.coerce 支持 HTTP query string 自动类型转换，以及默认值和最大值限制
+ *
+ * 默认值与 @longzai-intelligence/pagination 的 PAGINATION_DEFAULTS 保持一致
+ */
+declare const PaginationQuerySchema: z.ZodObject<{
+  page: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+  pageSize: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+}, z.core.$strip>;
+/**
+ * 分页查询参数类型
+ */
+type PaginationQuery = z.infer<typeof PaginationQuerySchema>;
+/**
+ * HTTP 分页查询参数配置类型
+ *
+ * 用于 createHttpPaginationSchema 工厂函数的自定义配置，
+ * 支持不同后端使用不同的分页字段名
+ *
+ * 配置项与 @longzai-intelligence/pagination 的 createPaginationDefaults 对齐
+ */
+type HttpPaginationConfig = {
+  /**
+   * 每页条数字段名，默认 'pageSize'
+   */
+  pageSizeField?: string;
+  /**
+   * 默认页码，默认使用 PAGINATION_DEFAULTS.page
+   */
+  defaultPage?: number;
+  /**
+   * 默认每页条数，默认使用 PAGINATION_DEFAULTS.pageSize
+   */
+  defaultPageSize?: number;
+  /**
+   * 每页最大条数，默认使用 PAGINATION_DEFAULTS.maxPageSize
+   */
+  maxPageSize?: number;
+  /**
+   * 每页最小条数，默认使用 PAGINATION_DEFAULTS.minPageSize
+   */
+  minPageSize?: number;
+};
+/**
+ * 创建 HTTP 分页查询参数 Schema 的工厂函数
+ *
+ * 根据 @longzai-intelligence/pagination 的 createPaginationSchema 和 createPaginationDefaults，
+ * 添加 HTTP 传输层特有的 z.coerce 支持。
+ *
+ * @example
+ *   const schema = createHttpPaginationSchema();
+ *   // 生成 { page?: number, pageSize?: number } Schema，带 z.coerce 和默认值
+ *
+ * @example
+ *   const schema = createHttpPaginationSchema({ pageSizeField: 'limit' });
+ *   // 生成 { page?: number, limit?: number } Schema
+ *
+ * @param config - HTTP 分页查询参数配置，可选
+ * @returns 分页查询参数 Zod Schema
+ */
+declare function createHttpPaginationSchema(config?: HttpPaginationConfig): z.ZodObject<{
+  [x: string]: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+  page: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+}, z.core.$strip>;
+/**
+ * 过滤查询参数 Schema
+ *
+ * 用于列表接口的过滤和排序
+ * 排序参数使用 @longzai-intelligence/pagination 的 SortParamsSchema
+ */
+declare const FilterQuerySchema: z.ZodObject<{
+  filter: z.ZodOptional<z.ZodString>;
+  sortBy: z.ZodOptional<z.ZodString>;
+  sortOrder: z.ZodOptional<z.ZodEnum<{
+    asc: "asc";
+    desc: "desc";
+  }>>;
+}, z.core.$strip>;
+/**
+ * 过滤查询参数类型
+ */
+type FilterQuery = z.infer<typeof FilterQuerySchema>;
+/**
+ * 创建带排序字段约束的过滤查询参数 Schema
+ *
+ * @example
+ *   const schema = createFilterQuerySchema(['name', 'createdAt'] as const);
+ *   // sortBy 只能为 'name' | 'createdAt'
+ *
+ * @typeParam T - 排序字段元组类型
+ * @param sortFields - 允许排序的字段名称数组
+ * @returns 过滤查询参数 Zod Schema
+ */
+declare function createFilterQuerySchema<T extends [string, ...string[]]>(sortFields: T): z.ZodObject<{
+  filter: z.ZodOptional<z.ZodString>;
+  sortBy: z.ZodOptional<z.ZodEnum<{ [k_1 in T[number]]: k_1 } extends infer T_1 ? { [k in keyof T_1]: T_1[k] } : never>>;
+  sortOrder: z.ZodOptional<z.ZodEnum<{
+    asc: "asc";
+    desc: "desc";
+  }>>;
+}, z.core.$strip>;
+/**
+ * 日期范围查询参数 Schema
+ *
+ * 用于按日期范围筛选的接口
+ */
+declare const DateRangeQuerySchema: z.ZodObject<{
+  startDate: z.ZodOptional<z.ZodString>;
+  endDate: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * 日期范围查询参数类型
+ */
+type DateRangeQuery = z.infer<typeof DateRangeQuerySchema>;
+/**
+ * 搜索查询参数 Schema
+ *
+ * 用于关键词搜索的接口
+ */
+declare const SearchQuerySchema: z.ZodObject<{
+  keyword: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * 搜索查询参数类型
+ */
+type SearchQuery = z.infer<typeof SearchQuerySchema>;
+//#endregion
+//#region src/schemas/error.schema.d.ts
+/**
+ * 通用错误码定义
+ *
+ * 仅包含跨项目通用的错误码，业务特定错误码由各项目通过 createErrorCodeSchema 扩展
+ */
+declare const ErrorCodeSchema: z.ZodEnum<{
+  UNKNOWN: "UNKNOWN";
+  INVALID_PARAMETER: "INVALID_PARAMETER";
+  RESOURCE_NOT_FOUND: "RESOURCE_NOT_FOUND";
+  RESOURCE_ALREADY_EXISTS: "RESOURCE_ALREADY_EXISTS";
+  OPERATION_FAILED: "OPERATION_FAILED";
+  PERMISSION_DENIED: "PERMISSION_DENIED";
+  UNAUTHORIZED: "UNAUTHORIZED";
+  TOKEN_EXPIRED: "TOKEN_EXPIRED";
+  TOKEN_INVALID: "TOKEN_INVALID";
+  LOGIN_FAILED: "LOGIN_FAILED";
+  ACCOUNT_DISABLED: "ACCOUNT_DISABLED";
+  PASSWORD_INCORRECT: "PASSWORD_INCORRECT";
+  DATABASE_ERROR: "DATABASE_ERROR";
+  EXTERNAL_SERVICE_ERROR: "EXTERNAL_SERVICE_ERROR";
+  RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED";
+  DUPLICATE_REQUEST: "DUPLICATE_REQUEST";
+  VALIDATION_ERROR: "VALIDATION_ERROR";
+}>;
+/**
+ * 通用错误码类型
+ */
+type ErrorCode = z.infer<typeof ErrorCodeSchema>;
+/**
+ * 通用错误码对应的错误消息
+ */
+declare const ERROR_MESSAGES: Record<ErrorCode, string>;
+/**
+ * 获取错误码对应的错误消息
+ *
+ * @param code - 错误码
+ * @returns 错误消息字符串
+ */
+declare function getErrorMessage(code: ErrorCode): string;
+/**
+ * 通用错误码到 HTTP 状态码的映射
+ */
+declare const ERROR_HTTP_STATUS: Partial<Record<ErrorCode, number>>;
+/**
+ * 获取错误码对应的 HTTP 状态码
+ *
+ * @param code - 错误码
+ * @returns HTTP 状态码，默认 400
+ */
+declare function getHttpStatus(code: ErrorCode): number;
+/**
+ * 创建业务错误码 Schema 的工厂函数
+ *
+ * 在通用错误码基础上扩展项目特定的业务错误码
+ *
+ * @example
+ *   const KtvErrorCodeSchema = createErrorCodeSchema(
+ *     ['ORDER_NOT_FOUND', 'ROOM_NOT_AVAILABLE'] as const,
+ *     'KTV 错误码',
+ *   );
+ *
+ * @typeParam T - 业务错误码数组类型
+ * @param businessCodes - 业务特定的错误码数组
+ * @param description - Schema 描述
+ * @returns 包含通用和业务错误码的枚举定义
+ * @throws {@link Error} 当错误码合并失败时抛出错误
+ */
+declare function createErrorCodeSchema<T extends readonly string[]>(businessCodes: T, description?: string): z.ZodEnum<{ [k_1 in "UNKNOWN" | "INVALID_PARAMETER" | "RESOURCE_NOT_FOUND" | "RESOURCE_ALREADY_EXISTS" | "OPERATION_FAILED" | "PERMISSION_DENIED" | "UNAUTHORIZED" | "TOKEN_EXPIRED" | "TOKEN_INVALID" | "LOGIN_FAILED" | "ACCOUNT_DISABLED" | "PASSWORD_INCORRECT" | "DATABASE_ERROR" | "EXTERNAL_SERVICE_ERROR" | "RATE_LIMIT_EXCEEDED" | "DUPLICATE_REQUEST" | "VALIDATION_ERROR" | T[number]]: k_1 } extends infer T_1 ? { [k in keyof T_1]: T_1[k] } : never>;
+/**
+ * 错误码配置类型
+ *
+ * 用于 createErrorCodeSchema 配置业务错误码
+ *
+ * @typeParam T - 业务错误码数组类型
+ */
+type ErrorCodeConfig<T extends readonly string[]> = {
+  /**
+   * 业务特定的错误码数组
+   */
+  codes: T;
+  /**
+   * Schema 描述
+   */
+  description?: string;
+};
+/**
+ * API 错误响应 Schema
+ */
+declare const ApiErrorResponseSchema: z.ZodObject<{
+  code: z.ZodEnum<{
+    UNKNOWN: "UNKNOWN";
+    INVALID_PARAMETER: "INVALID_PARAMETER";
+    RESOURCE_NOT_FOUND: "RESOURCE_NOT_FOUND";
+    RESOURCE_ALREADY_EXISTS: "RESOURCE_ALREADY_EXISTS";
+    OPERATION_FAILED: "OPERATION_FAILED";
+    PERMISSION_DENIED: "PERMISSION_DENIED";
+    UNAUTHORIZED: "UNAUTHORIZED";
+    TOKEN_EXPIRED: "TOKEN_EXPIRED";
+    TOKEN_INVALID: "TOKEN_INVALID";
+    LOGIN_FAILED: "LOGIN_FAILED";
+    ACCOUNT_DISABLED: "ACCOUNT_DISABLED";
+    PASSWORD_INCORRECT: "PASSWORD_INCORRECT";
+    DATABASE_ERROR: "DATABASE_ERROR";
+    EXTERNAL_SERVICE_ERROR: "EXTERNAL_SERVICE_ERROR";
+    RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED";
+    DUPLICATE_REQUEST: "DUPLICATE_REQUEST";
+    VALIDATION_ERROR: "VALIDATION_ERROR";
+  }>;
+  message: z.ZodString;
+  data: z.ZodNullable<z.ZodUnknown>;
+}, z.core.$strip>;
+/**
+ * API 错误响应类型
+ */
+type ApiErrorResponse = z.infer<typeof ApiErrorResponseSchema>;
+//#endregion
+//#region src/routes/utils.d.ts
+/**
+ * 定义 API 路由
+ *
+ * 创建类型安全的路由定义，所有泛型参数从配置对象自动推断
+ *
+ * @example
+ *   const loginRoute = defineRoute({
+ *     method: 'POST',
+ *     path: '/v1/auth/login',
+ *     body: LoginBodySchema,
+ *     response: ApiResponseSchema(AuthResponseSchema),
+ *     summary: '用户登录',
+ *     tags: ['认证'],
+ *   });
+ *
+ * @typeParam TMethod - HTTP 方法类型
+ * @typeParam TPath - 路径模板字符串
+ * @typeParam TParams - 路径参数 Zod Schema
+ * @typeParam TQuery - 查询参数 Zod Schema
+ * @typeParam TBody - 请求体 Zod Schema
+ * @typeParam TResponse - 响应 Zod Schema
+ * @param config - 路由配置对象
+ * @returns 类型安全的路由定义
+ */
+/**
+ * 定义 API 路由配置类型
+ *
+ * 描述 defineRoute 函数的配置参数结构
+ *
+ * @typeParam TMethod - HTTP 方法类型
+ * @typeParam TPath - 路径模板字符串
+ * @typeParam TParams - 路径参数 Schema 类型
+ * @typeParam TQuery - 查询参数 Schema 类型
+ * @typeParam TBody - 请求体 Schema 类型
+ * @typeParam TResponse - 响应 Schema 类型
+ */
+type DefineRouteConfig<TMethod extends HttpMethod, TPath extends string, TParams extends ZodType | undefined, TQuery extends ZodType | undefined, TBody extends ZodType | undefined, TResponse extends ZodType> = {
+  /**
+   * HTTP 请求方法
+   */
+  method: TMethod;
+  /**
+   * API 路径模板
+   */
+  path: TPath;
+  /**
+   * 路径参数 Schema
+   */
+  params?: TParams;
+  /**
+   * 查询参数 Schema
+   */
+  query?: TQuery;
+  /**
+   * 请求体 Schema
+   */
+  body?: TBody;
+  /**
+   * 响应 Schema
+   */
+  response: TResponse;
+  /**
+   * 接口描述信息
+   */
+  summary?: string;
+  /**
+   * 接口标签
+   */
+  tags?: string[];
+};
+/**
+ * 定义 API 路由
+ *
+ * 创建类型安全的路由定义，所有泛型参数从配置对象自动推断
+ *
+ * @example
+ *   const loginRoute = defineRoute({
+ *     method: 'POST',
+ *     path: '/v1/auth/login',
+ *     body: LoginBodySchema,
+ *     response: ApiResponseSchema(AuthResponseSchema),
+ *     summary: '用户登录',
+ *     tags: ['认证'],
+ *   });
+ *
+ * @typeParam TMethod - HTTP 方法类型
+ * @typeParam TPath - 路径模板字符串
+ * @typeParam TParams - 路径参数 Schema 类型
+ * @typeParam TQuery - 查询参数 Schema 类型
+ * @typeParam TBody - 请求体 Schema 类型
+ * @typeParam TResponse - 响应 Schema 类型
+ * @param config - 路由配置对象
+ * @returns 类型安全的路由定义
+ * @throws {@link Error} 当路由定义创建失败时抛出错误
+ */
+declare function defineRoute<TMethod extends HttpMethod, TPath extends string, TParams extends ZodType | undefined, TQuery extends ZodType | undefined, TBody extends ZodType | undefined, TResponse extends ZodType>(config: DefineRouteConfig<TMethod, TPath, TParams, TQuery, TBody, TResponse>): RouteDefinition<TMethod, TPath, TParams, TQuery, TBody, TResponse>;
+/**
+ * 构建完整 URL 路径
+ *
+ * 将路径模板中的 :param 替换为实际值，并附加查询参数
+ *
+ * @example
+ *   buildPath('/v1/users/:id', { id: '123' }, { include: 'profile' });
+ *   // '/v1/users/123?include=profile'
+ *
+ * @param path - 路径模板，如 /v1/users/:id
+ * @param params - 路径参数键值对
+ * @param query - 查询参数键值对，undefined 值会被忽略
+ * @returns 完整的 URL 路径
+ */
+declare function buildPath(path: string, params?: Record<string, string | number>, query?: Record<string, string | number | boolean | undefined>): string;
+/**
+ * 构建查询字符串
+ *
+ * 将查询参数对象转换为 URL 查询字符串，undefined 值会被忽略
+ *
+ * @example
+ *   buildQuery({ page: 1, pageSize: 10 });
+ *   // '?page=1&pageSize=10'
+ *
+ * @param query - 查询参数键值对
+ * @returns 查询字符串，以 ? 开头；无参数时返回空字符串
+ */
+declare function buildQuery(query?: Record<string, string | number | boolean | undefined>): string;
+/**
+ * 拼接路径片段
+ *
+ * 将两个路径字符串拼接为一个完整路径，返回类型安全的模板字面量类型
+ *
+ * @typeParam T - 前缀路径类型
+ * @typeParam U - 子路径类型
+ * @param a - 前缀路径
+ * @param b - 子路径
+ * @returns 拼接后的完整路径
+ */
+declare function concatPath<T extends string, U extends string>(a: T, b: U): `${T}${U}`;
+//#endregion
+//#region src/routes/route-group.utils.d.ts
+/**
+ * API 版本号类型
+ *
+ * 支持标准版本格式：v1, v2, v3, ...
+ * 也支持自定义版本字符串
+ */
+type ApiVersion = `v${number}` | (string & {});
+/**
+ * 默认认证策略类型
+ *
+ * 支持三种内置策略和自定义字符串策略
+ */
+type DefaultAuthStrategy = 'public' | 'user' | 'admin' | (string & {});
+/**
+ * 计算带版本前缀的完整路径类型
+ *
+ * @typeParam TVersion - 版本号类型
+ * @typeParam TPrefix - 路径前缀类型
+ */
+type VersionedPrefix<TVersion extends ApiVersion | undefined, TPrefix extends string> = TVersion extends ApiVersion ? TPrefix extends `/${string}` ? `/${TVersion}${TPrefix}` : TPrefix extends '' ? `/${TVersion}` : `/${TVersion}/${TPrefix}` : TPrefix;
+/**
+ * 路由分组配置
+ *
+ * @typeParam TPrefix - 路径前缀类型
+ * @typeParam TVersion - API 版本号类型
+ * @typeParam TAuthStrategy - 认证策略类型
+ */
+type RouteGroupConfig<TPrefix extends string = '', TVersion extends ApiVersion | undefined = undefined, TAuthStrategy extends string = DefaultAuthStrategy> = {
+  /**
+   * 父路由分组（可选）
+   *
+   * 指定父分组时，当前分组会继承父分组的配置并追加路径
+   * - prefix 会追加到父分组的 prefix 后面
+   * - auth 和 tags 会继承父分组的值（如果未指定）
+   */
+  parent?: RouteGroup<string, ApiVersion | undefined, TAuthStrategy>;
+  /**
+   * 路径前缀（可选）
+   *
+   * 所有子路由的路径都会自动拼接此前缀
+   * 如果指定了 parent，此前缀会追加到父分组的 prefix 后面
+   * 如果指定了 version，版本前缀会自动添加到 prefix 前面
+   * 如果未指定，默认为空字符串
+   */
+  prefix?: TPrefix;
+  /**
+   * API 版本号
+   *
+   * 版本前缀会自动添加到 prefix 前面，格式为 /{version}
+   * 例如：version: 'v1', prefix: 'client' -> 实际前缀: /v1/client
+   * 例如：version: 'v1', prefix: '' -> 实际前缀: /v1
+   *
+   * 注意：如果指定了 parent，version 应该在父分组中指定，子分组会自动继承
+   */
+  version?: TVersion;
+  /**
+   * 认证策略
+   *
+   * 标识分组内路由的认证要求，可由适配器读取并应用相应的中间件
+   * 如果指定了 parent 且未设置此字段，会继承父分组的 auth
+   */
+  auth?: TAuthStrategy;
+  /**
+   * API 标签（用于 Swagger 分组和 TypedController）
+   *
+   * TypedController 装饰器会使用这些标签设置 @ApiTags()
+   * 子路由会继承这些标签，并可追加自己的标签
+   * 如果指定了 parent 且未设置此字段，会继承父分组的 tags
+   */
+  tags?: string[];
+  /**
+   * 路由定义集合（可选）
+   *
+   * 提供 routes 时，defineRouteGroup 返回 RouteGroup & { routes }，
+   * 可直接用于 TypedController 和 TypedRoute。
+   * 不提供 routes 时，返回纯 RouteGroup，可用于 defineRoute 拆分定义。
+   *
+   * 接受两种输入：
+   * - 内联原始配置对象（简单场景，少量路由）
+   * - group.defineRoute() 的返回值（复杂场景，拆分定义）
+   */
+  routes?: Record<string, RouteDefineConfig | ProcessedRoute<RouteDefinition>>;
+};
+/**
+ * 路由分组
+ *
+ * 提供路由分组功能，子路由自动继承分组的配置
+ *
+ * @typeParam TPrefix - 路径前缀类型
+ * @typeParam TVersion - API 版本号类型
+ * @typeParam TAuthStrategy - 认证策略类型
+ */
+type RouteGroup<TPrefix extends string = string, TVersion extends ApiVersion | undefined = undefined, TAuthStrategy extends string = DefaultAuthStrategy> = {
+  /**
+   * 完整路径前缀（包含版本）
+   *
+   * 如果指定了 version，格式为 /{version}/{prefix}
+   * 如果未指定 version，则为原始 prefix
+   */
+  readonly prefix: VersionedPrefix<TVersion, TPrefix>;
+  /**
+   * API 版本号
+   */
+  readonly version?: TVersion;
+  /**
+   * 认证策略
+   *
+   * 标识分组内路由的认证要求
+   */
+  readonly auth?: TAuthStrategy;
+  /**
+   * API 标签（用于 Swagger 分组和 TypedController）
+   *
+   * 用于接口分组和文档生成
+   */
+  readonly tags?: string[];
+  /**
+   * 定义单条路由
+   *
+   * 语法糖，用于需要单独引用某条路由或拆分复杂路由定义的场景。
+   * 子路由的路径会自动拼接分组前缀，并继承分组的认证策略和标签。
+   *
+   * @typeParam TMethod - HTTP 方法类型
+   * @typeParam TPath - 路径模板字符串
+   * @typeParam TParams - 路径参数 Zod Schema
+   * @typeParam TQuery - 查询参数 Zod Schema
+   * @typeParam TBody - 请求体 Zod Schema
+   * @typeParam TResponse - 响应 Zod Schema
+   * @param config - 路由配置对象
+   * @returns 类型安全的路由定义，路径已拼接前缀
+   */
+  defineRoute: <TMethod extends HttpMethod = HttpMethod, TPath extends string = string, TParams extends ZodType | undefined = undefined, TQuery extends ZodType | undefined = undefined, TBody extends ZodType | undefined = undefined, TResponse extends ZodType = ZodType>(config: RouteDefineConfig<TMethod, TPath, TParams, TQuery, TBody, TResponse>) => RouteDefinition<TMethod, `${VersionedPrefix<TVersion, TPrefix>}${TPath}`, TParams, TQuery, TBody, TResponse> & {
+    /**
+     * 认证策略
+     */
+    auth?: TAuthStrategy;
+  };
+};
+/**
+ * 路由定义配置（用于分组内定义）
+ *
+ * @typeParam TMethod - HTTP 方法类型
+ * @typeParam TPath - 路径模板字符串
+ * @typeParam TParams - 路径参数 Schema 类型
+ * @typeParam TQuery - 查询参数 Schema 类型
+ * @typeParam TBody - 请求体 Schema 类型
+ * @typeParam TResponse - 响应 Schema 类型
+ */
+type RouteDefineConfig<TMethod extends HttpMethod = HttpMethod, TPath extends string = string, TParams extends ZodType | undefined = ZodType | undefined, TQuery extends ZodType | undefined = ZodType | undefined, TBody extends ZodType | undefined = ZodType | undefined, TResponse extends ZodType = ZodType> = {
+  /**
+   * HTTP 方法
+   */
+  method: TMethod;
+  /**
+   * 路径模板，会自动拼接分组前缀
+   */
+  path: TPath;
+  /**
+   * 路径参数 Schema
+   */
+  params?: TParams;
+  /**
+   * 查询参数 Schema
+   */
+  query?: TQuery;
+  /**
+   * 请求体 Schema
+   */
+  body?: TBody;
+  /**
+   * 响应 Schema
+   */
+  response: TResponse;
+  /**
+   * 接口摘要描述
+   */
+  summary?: string;
+  /**
+   * 接口标签，会与分组标签合并
+   */
+  tags?: string[];
+  /**
+   * 是否需要 CSRF 令牌保护
+   */
+  csrf?: boolean;
+  /**
+   * 请求内容类型
+   */
+  contentType?: 'json' | 'formData';
+  /**
+   * 覆盖分组的认证策略
+   *
+   * 用于覆盖父路由分组的认证设置
+   */
+  auth?: string;
+};
+/**
+ * 路由定义结果类型
+ *
+ * defineRoute 返回的类型，包含完整的路由定义和可选的 auth 属性
+ *
+ * @typeParam TMethod - HTTP 方法类型
+ * @typeParam TVersion - API 版本号类型
+ * @typeParam TPrefix - 路径前缀类型
+ * @typeParam TPath - 路径模板字符串
+ * @typeParam TParams - 路径参数 Schema 类型
+ * @typeParam TQuery - 查询参数 Schema 类型
+ * @typeParam TBody - 请求体 Schema 类型
+ * @typeParam TResponse - 响应 Schema 类型
+ */
+type RouteDefineResult<TMethod extends HttpMethod, TVersion extends ApiVersion | undefined, TPrefix extends string, TPath extends string, TParams extends ZodType | undefined, TQuery extends ZodType | undefined, TBody extends ZodType | undefined, TResponse extends ZodType> = RouteDefinition<TMethod, `${VersionedPrefix<TVersion, TPrefix>}${TPath}`, TParams, TQuery, TBody, TResponse> & {
+  /**
+   * 认证策略
+   */
+  auth?: string;
+};
+/**
+ * 已处理的路由类型
+ *
+ * defineRoute 方法返回的路由类型，或 defineRouteGroup 内部处理后的路由类型
+ *
+ * @typeParam T - 路由定义类型，保留 method 字面量和 Schema 类型信息
+ */
+type ProcessedRoute<T extends RouteDefinition = RouteDefinition> = T & {
+  /**
+   * 认证策略
+   */
+  auth?: string;
+  /**
+   * 基础路径（NestJS 方法装饰器使用的相对路径）
+   */
+  basePath?: string;
+  /**
+   * 接口摘要描述
+   */
+  summary?: string;
+  /**
+   * 接口标签分组
+   */
+  tags?: string[];
+  /**
+   * 是否需要 CSRF 令牌保护
+   */
+  csrf?: boolean;
+  /**
+   * 请求内容类型
+   */
+  contentType?: 'json' | 'formData';
+};
+/**
+ * 从路由配置中提取 RouteDefinition 类型（保留具体类型信息）
+ *
+ * 通过直接检查输入类型的字段来推断类型，
+ * 避免了 RouteDefineConfig 泛型默认值导致的类型丢失问题。
+ * 使用 params?/query?/body? 推断来保留具体的 Zod Schema 类型，
+ * 当字段不存在时推断为 undefined。
+ *
+ * @typeParam T - 路由配置值类型
+ */
+type InferRouteDefinitionFromValue<T> = T extends {
+  /**
+   * HTTP 方法
+   */
+  method: infer M extends HttpMethod;
+  /**
+   * 请求路径
+   */
+  path: string;
+  /**
+   * 响应 Schema
+   */
+  response: infer R extends ZodType;
+  /**
+   * 路径参数 Schema
+   */
+  params?: infer PA;
+  /**
+   * 查询参数 Schema
+   */
+  query?: infer Q;
+  /**
+   * 请求体 Schema
+   */
+  body?: infer B;
+} ? RouteDefinition<M, string, [PA] extends [ZodType] ? PA : undefined, [Q] extends [ZodType] ? Q : undefined, [B] extends [ZodType] ? B : undefined, R> & {
+  /**
+   * 接口摘要描述
+   */
+  summary?: string;
+  /**
+   * 接口标签分组
+   */
+  tags?: string[];
+  /**
+   * 是否需要 CSRF 令牌保护
+   */
+  csrf?: boolean;
+  /**
+   * 请求内容类型
+   */
+  contentType?: 'json' | 'formData';
+} : RouteDefinition;
+/**
+ * 处理路由集合类型
+ *
+ * 从输入的路由定义集合中提取每个路由的具体类型信息，
+ * 保留 method 字面量类型和 Schema 类型信息
+ *
+ * @typeParam TRoutes - 路由定义集合类型
+ */
+type ProcessRoutes<TRoutes extends Record<string, RouteDefineConfig | ProcessedRoute<RouteDefinition>>> = { [K in keyof TRoutes]: ProcessedRoute<InferRouteDefinitionFromValue<TRoutes[K]>> };
+/**
+ * 定义路由分组（含 routes，保留具体键类型）
+ *
+ * 创建路由分组并附加路由定义，返回结果可直接用于 TypedController 和 TypedRoute。
+ * routes 字段同时接受内联原始配置和 group.defineRoute() 的返回值。
+ *
+ * 重载顺序说明：此重载必须排在无 routes 重载之前。
+ * 因为 RouteGroupConfig 中 routes 是可选字段，若宽泛重载在前，
+ * TypeScript 会优先匹配宽泛签名，导致带 routes 的调用丢失 routes 类型信息。
+ *
+ * @typeParam TPrefix - 路径前缀类型
+ * @typeParam TVersion - API 版本号类型
+ * @typeParam TAuthStrategy - 认证策略类型
+ * @typeParam TRoutes - 路由定义集合类型，保留具体键名用于类型推断
+ * @param config - 分组配置（含 routes）
+ * @returns 路由分组对象（含 routes 属性）
+ */
+declare function defineRouteGroup<TPrefix extends string = '', TVersion extends ApiVersion | undefined = undefined, TAuthStrategy extends string = DefaultAuthStrategy, TRoutes extends Record<string, RouteDefineConfig | ProcessedRoute<RouteDefinition>> = Record<string, RouteDefineConfig | ProcessedRoute<RouteDefinition>>>(config: RouteGroupConfig<TPrefix, TVersion, TAuthStrategy> & {
+  /**
+   * 路由定义集合
+   */
+  routes: TRoutes;
+}): RouteGroup<TPrefix, TVersion, TAuthStrategy> & {
+  /**
+   * 路由定义集合（只读，保留具体键类型和 method 字面量类型）
+   */
+  readonly routes: Readonly<ProcessRoutes<TRoutes>>;
+};
+/**
+ * 定义路由分组（无 routes，用于 defineRoute 拆分定义的中间分组）
+ *
+ * @typeParam TPrefix - 路径前缀类型
+ * @typeParam TVersion - API 版本号类型
+ * @typeParam TAuthStrategy - 认证策略类型
+ * @param config - 分组配置（不含 routes）
+ * @returns 路由分组对象（提供 defineRoute 语法糖）
+ */
+declare function defineRouteGroup<TPrefix extends string = '', TVersion extends ApiVersion | undefined = undefined, TAuthStrategy extends string = DefaultAuthStrategy>(config: RouteGroupConfig<TPrefix, TVersion, TAuthStrategy>): RouteGroup<TPrefix, TVersion, TAuthStrategy>;
+//#endregion
+//#region src/factory/create-api-functions.factory.d.ts
+/**
+ * 创建 GET 请求函数类型
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type CreateGetFunction<TRoute extends RouteDefinition> = InferRouteParams<TRoute> extends undefined ? InferRouteQuery<TRoute> extends undefined ? () => Promise<ApiResponse<InferRouteResponse<TRoute>>> : (query?: InferRouteQuery<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>> : InferRouteQuery<TRoute> extends undefined ? (params: InferRouteParams<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>> : (params: InferRouteParams<TRoute>, query?: InferRouteQuery<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>>;
+/**
+ * 创建 POST 请求函数类型
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type CreatePostFunction<TRoute extends RouteDefinition> = InferRouteParams<TRoute> extends undefined ? InferRouteBody<TRoute> extends undefined ? InferRouteQuery<TRoute> extends undefined ? () => Promise<ApiResponse<InferRouteResponse<TRoute>>> : (query?: InferRouteQuery<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>> : InferRouteQuery<TRoute> extends undefined ? (body: InferRouteBody<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>> : (body: InferRouteBody<TRoute>, query?: InferRouteQuery<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>> : InferRouteBody<TRoute> extends undefined ? InferRouteQuery<TRoute> extends undefined ? (params: InferRouteParams<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>> : (params: InferRouteParams<TRoute>, query?: InferRouteQuery<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>> : InferRouteQuery<TRoute> extends undefined ? (params: InferRouteParams<TRoute>, body: InferRouteBody<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>> : (params: InferRouteParams<TRoute>, body: InferRouteBody<TRoute>, query?: InferRouteQuery<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>>;
+/**
+ * 创建 PUT/PATCH 请求函数类型
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type CreateUpdateFunction<TRoute extends RouteDefinition> = InferRouteParams<TRoute> extends undefined ? InferRouteBody<TRoute> extends undefined ? InferRouteQuery<TRoute> extends undefined ? () => Promise<ApiResponse<InferRouteResponse<TRoute>>> : (query?: InferRouteQuery<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>> : InferRouteQuery<TRoute> extends undefined ? (body: InferRouteBody<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>> : (body: InferRouteBody<TRoute>, query?: InferRouteQuery<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>> : InferRouteBody<TRoute> extends undefined ? InferRouteQuery<TRoute> extends undefined ? (params: InferRouteParams<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>> : (params: InferRouteParams<TRoute>, query?: InferRouteQuery<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>> : InferRouteQuery<TRoute> extends undefined ? (params: InferRouteParams<TRoute>, body: InferRouteBody<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>> : (params: InferRouteParams<TRoute>, body: InferRouteBody<TRoute>, query?: InferRouteQuery<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>>;
+/**
+ * 创建 DELETE 请求函数类型
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type CreateDeleteFunction<TRoute extends RouteDefinition> = InferRouteParams<TRoute> extends undefined ? InferRouteQuery<TRoute> extends undefined ? () => Promise<ApiResponse<InferRouteResponse<TRoute>>> : (query?: InferRouteQuery<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>> : InferRouteQuery<TRoute> extends undefined ? (params: InferRouteParams<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>> : (params: InferRouteParams<TRoute>, query?: InferRouteQuery<TRoute>) => Promise<ApiResponse<InferRouteResponse<TRoute>>>;
+/**
+ * HTTP 方法类型
+ */
+type MethodType = {
+  /**
+   * HTTP 方法
+   */
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+};
+/**
+ * 根据路由定义创建对应的 API 函数类型
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type CreateApiFunction<TRoute extends RouteDefinition> = TRoute extends MethodType ? CreateMethodFunction<TRoute> : () => Promise<ApiResponse<InferRouteResponse<TRoute>>>;
+/**
+ * 根据 HTTP 方法创建对应的函数类型
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type CreateMethodFunction<TRoute extends RouteDefinition> = TRoute extends {
+  /**
+   * HTTP 方法
+   */
+  method: 'GET';
+} ? CreateGetFunction<TRoute> : TRoute extends {
+  /**
+   * HTTP 方法
+   */
+  method: 'POST';
+} ? CreatePostFunction<TRoute> : TRoute extends {
+  /**
+   * HTTP 方法
+   */
+  method: 'PUT';
+} ? CreateUpdateFunction<TRoute> : TRoute extends {
+  /**
+   * HTTP 方法
+   */
+  method: 'PATCH';
+} ? CreateUpdateFunction<TRoute> : TRoute extends {
+  /**
+   * HTTP 方法
+   */
+  method: 'DELETE';
+} ? CreateDeleteFunction<TRoute> : never;
+/**
+ * 从路由定义对象创建 API 函数对象类型
+ *
+ * @typeParam TRoutes - 路由定义集合类型
+ */
+type ApiFunctions<TRoutes extends Record<string, RouteDefinition>> = { [K in keyof TRoutes]: CreateApiFunction<TRoutes[K]> };
+/**
+ * API 客户端工厂函数类型
+ *
+ * 接收路由定义集合，返回对应的 API 函数对象
+ *
+ * @typeParam TRoutes - 路由定义集合类型
+ */
+type CreateApiFromRoutes = <TRoutes extends Record<string, RouteDefinition>>(routes: TRoutes) => ApiFunctions<TRoutes>;
+/**
+ * API 客户端工厂
+ *
+ * 先绑定 HTTP 客户端，返回只需要路由定义的 createApi 函数。
+ * 避免每次调用都传递 client 参数，符合"一次配置，到处使用"的理念。
+ *
+ * @example
+ *   ```typescript
+ *   // 一次绑定 client
+ *   const createApi = createApiClientFactory(httpClient);
+ *
+ *   // 后续只需传 routes
+ *   const activityApi = createApi(activityRoutes.routes);
+ *   const categoryApi = createApi(categoryRoutes.routes);
+ *
+ *   // 使用 -- 全链路强类型
+ *   const response = await activityApi.list({ page: 1 });
+ *   ```;
+ *
+ * @param client - HTTP 客户端实例
+ * @returns 只需要 routes 参数的 createApi 函数
+ */
+declare function createApiClientFactory(client: HttpClient): CreateApiFromRoutes;
+//#endregion
+//#region src/utils/api-response.util.d.ts
+/**
+ * API 响应工具类
+ *
+ * 提供统一的响应构建方法，确保所有响应结构一致
+ */
+declare const ApiResponseUtil: {
+  /**
+   * 构建成功响应
+   *
+   * @typeParam T - 响应数据类型
+   * @param data - 响应数据
+   * @param message - 响应消息
+   * @returns 成功响应对象
+   */
+  success<T>(data: T, message?: string): ApiSuccessResponse<T>;
+  /**
+   * 构建仅包含数据的成功响应
+   *
+   * @typeParam T - 响应数据类型
+   * @param data - 响应数据
+   * @returns 成功响应对象
+   */
+  data<T>(data: T): ApiSuccessResponse<T>;
+  /**
+   * 构建仅包含消息的成功响应
+   *
+   * @param message - 响应消息
+   * @returns 成功响应对象
+   */
+  message(message: string): ApiSuccessResponse<undefined>;
+  /**
+   * 构建失败响应
+   *
+   * @typeParam T - 响应数据类型
+   * @param message - 错误消息
+   * @param data - 可选的响应数据
+   * @returns 失败响应对象
+   */
+  fail<T>(message: string, data?: T): ApiFailResponse<T>;
+  /**
+   * 构建空成功响应
+   *
+   * @typeParam T - 响应数据类型
+   * @returns 空成功响应对象
+   */
+  empty<T>(): ApiSuccessResponse<T | undefined>;
+};
+/**
+ * API 列表数据工具类
+ *
+ * 用于构建 ApiResponse.data 字段的列表数据
+ */
+declare const ApiListDataUtil: {
+  /**
+   * 构建空列表数据
+   *
+   * @typeParam T - 列表项数据类型
+   * @returns 空列表数据对象
+   */
+  empty<T>(): ApiListData<T>;
+  /**
+   * 从数组构建列表数据（自动计算总数）
+   *
+   * @typeParam T - 列表项数据类型
+   * @param items - 数据项数组
+   * @returns 列表数据对象
+   */
+  from<T>(items: T[]): ApiListData<T>;
+  /**
+   * 从数组和总数构建列表数据
+   *
+   * @typeParam T - 列表项数据类型
+   * @param items - 数据项数组
+   * @param total - 总记录数
+   * @returns 列表数据对象
+   */
+  withTotal<T>(items: T[], total: number): ApiListData<T>;
+  /**
+   * 构建完整分页列表数据
+   *
+   * 委托给 @longzai-intelligence/pagination 的 createPaginatedResult
+   *
+   * @typeParam T - 列表项数据类型
+   * @param items - 数据项数组
+   * @param total - 总记录数
+   * @param page - 当前页码
+   * @param pageSize - 每页数量
+   * @returns 分页列表数据对象
+   */
+  paginated<T>(items: T[], total: number, page: number, pageSize: number): ApiPaginatedListData<T>;
+};
+//#endregion
+//#region src/utils/form-data.util.d.ts
+/**
+ * FormData 转换配置
+ */
+type FormDataConvertConfig = {
+  /**
+   * 文件字段名列表
+   *
+   * 指定哪些字段应该作为文件处理
+   */
+  fileFields?: string[];
+  /**
+   * 数组处理方式
+   *
+   * - 'indices'：使用索引（field[0], field[1]）
+   * - 'brackets'：使用括号（field[], field[]）
+   * - 'repeat'：重复字段名（field, field）
+   */
+  arrayFormat?: 'indices' | 'brackets' | 'repeat';
+};
+/**
+ * 判断是否为文件对象
+ *
+ * @param value - 待判断的值
+ * @returns 是否为文件对象
+ */
+declare function isFile(value: unknown): value is File;
+/**
+ * 判断是否为 Blob 对象
+ *
+ * @param value - 待判断的值
+ * @returns 是否为 Blob 对象
+ */
+declare function isBlob(value: unknown): value is Blob;
+/**
+ * 将对象转换为 FormData
+ *
+ * @example
+ *   ```typescript
+ *   import { objectToFormData } from '@longzai-intelligence-transport/http';
+ *
+ *   const formData = objectToFormData(
+ *     {
+ *       name: 'Test',
+ *       file: new File(['content'], 'test.txt'),
+ *     },
+ *     {
+ *       fileFields: ['file'],
+ *     },
+ *   );
+ *   ```;
+ *
+ * @param obj - 要转换的对象
+ * @param config - 转换配置
+ * @returns FormData 实例
+ */
+declare function objectToFormData(obj: Record<string, unknown>, config?: FormDataConvertConfig): FormData;
+/**
+ * 判断路由是否需要 FormData
+ *
+ * @param contentType - 内容类型
+ * @returns 是否需要 FormData
+ */
+declare function isFormDataContentType(contentType?: 'json' | 'formData'): boolean;
+//#endregion
+//#region src/utils/route-response-builder.util.d.ts
+/**
+ * 路由响应构建器
+ *
+ * 提供类型安全的响应构建方法，响应数据类型从 RouteDefinition 自动推断
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type RouteResponseBuilder<TRoute extends RouteDefinition> = {
+  /**
+   * 构建成功响应
+   *
+   * @param data - 响应数据，类型从 RouteDefinition 自动推断
+   * @returns 成功响应对象
+   */
+  success: (data: InferRouteResponse<TRoute>) => ApiResponse<InferRouteResponse<TRoute>>;
+  /**
+   * 构建带消息的成功响应
+   *
+   * @param data - 响应数据
+   * @param message - 响应消息
+   * @returns 成功响应对象
+   */
+  successWithMessage: (data: InferRouteResponse<TRoute>, message: string) => ApiResponse<InferRouteResponse<TRoute>>;
+  /**
+   * 构建失败响应
+   *
+   * @param message - 错误消息
+   * @param error - 可选的错误详情
+   * @returns 失败响应对象
+   */
+  fail: (message: string, error?: ApiError) => ApiResponse<never>;
+  /**
+   * 构建空响应
+   *
+   * @returns 空成功响应对象
+   */
+  empty: () => ApiResponse<InferRouteResponse<TRoute>>;
+};
+/**
+ * 从路由定义创建类型安全的服务端响应构建器
+ *
+ * 响应数据类型从 RouteDefinition 自动推断，确保服务端返回的数据类型与路由定义一致
+ *
+ * @example
+ *   ```typescript
+ *   import { createRouteResponseBuilder, defineRoute, z } from '@longzai-intelligence-transport/http';
+ *
+ *   const userRoute = defineRoute({
+ *     method: 'GET',
+ *     path: '/users/:id',
+ *     params: z.object({ id: z.string() }),
+ *     response: z.object({ id: z.string(), name: z.string() }),
+ *   });
+ *
+ *   const builder = createRouteResponseBuilder(userRoute);
+ *
+ *   // 类型安全：data 必须符合 { id: string, name: string }
+ *   const response = builder.success({ id: '123', name: 'John' });
+ *
+ *   // 编译错误：缺少 name 字段
+ *   // builder.success({ id: '123' });
+ *   ```;
+ *
+ * @typeParam TRoute - 路由定义类型
+ * @param route - 路由定义
+ * @returns 类型安全的响应构建器
+ */
+declare function createRouteResponseBuilder<TRoute extends RouteDefinition>(route: TRoute): RouteResponseBuilder<TRoute>;
+/**
+ * 类型安全的成功响应函数类型
+ *
+ * @typeParam R - 路由定义类型
+ */
+type TypedResponseFunction<R extends RouteDefinition> = (data: InferRouteResponse<R>) => ApiResponse<InferRouteResponse<R>>;
+/**
+ * 类型安全的空响应函数类型
+ */
+type TypedEmptyFunction = () => ApiResponse<void>;
+/**
+ * 创建类型安全的成功响应函数
+ *
+ * 工厂模式: 创建时绑定路由定义，返回的函数只接受 data 参数。
+ * data 的类型由路由 response Schema 推导，编译期检查数据结构一致性。
+ *
+ * @example
+ *   ```typescript
+ *   const typedResponse = createTypedResponse(userListRoute);
+ *   return typedResponse({ items: [...], pagination: {...} });
+ *   ```;
+ *
+ * @typeParam R - 路由定义类型
+ * @param _route - 路由定义（创建时绑定，用于类型推断）
+ * @returns 响应函数，接受 data 参数，返回 ApiResponse
+ */
+declare function createTypedResponse<R extends RouteDefinition>(_route: R): TypedResponseFunction<R>;
+/**
+ * 创建类型安全的空响应函数
+ *
+ * 工厂模式: 创建时绑定路由定义，返回无参函数。
+ *
+ * @example
+ *   ```typescript
+ *   const typedEmpty = createTypedEmpty(userDeleteRoute);
+ *   return typedEmpty();
+ *   ```;
+ *
+ * @typeParam R - 路由定义类型
+ * @param _route - 路由定义（创建时绑定，用于类型推断）
+ * @returns 无参函数，返回空 ApiResponse
+ */
+declare function createTypedEmpty<R extends RouteDefinition>(_route: R): TypedEmptyFunction;
+//#endregion
+//#region src/utils/unwrap-result.util.d.ts
+/**
+ * 将 Result 显式转换为 ApiResponse
+ *
+ * 用于控制器层，将领域层的 Result 类型解包为传输层的 ApiResponse。
+ * Success 时提取 value 包装为标准响应，Failure 时抛出错误由异常过滤器处理。
+ *
+ * @typeParam T - Result 中成功值的类型
+ * @typeParam E - Result 中错误类型
+ * @param result - 服务层返回的 Result 实例
+ * @returns 标准化的 API 响应
+ * @throws {@link Error} Result 为 Failure 时抛出 error，由 HttpExceptionFilter 处理
+ */
+declare function unwrapResult<T, E>(result: Result<T, E>): ApiResponse<T>;
+//#endregion
+//#region src/utils/type-guards.util.d.ts
+/**
+ * 类型守卫工具
+ *
+ * 提供通用的类型守卫函数，用于替代 as 类型断言。
+ * 遵循项目规范：使用类型守卫或 Zod 进行类型收窄。
+ */
+/**
+ * 检查值是否为普通对象（非数组、非 null）
+ *
+ * @param value - 待检查的值
+ * @returns 是否为普通对象
+ */
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * 检查值是否为指定类型（通用类型守卫）
+ *
+ * 用于工厂模式中无法通过 Zod 验证的泛型类型收窄。
+ * 运行时仅检查值是否存在且不为 undefined，实际类型安全性由 TypeScript 泛型保证。
+ *
+ * @typeParam T - 目标类型
+ * @param value - 待检查的值
+ * @returns 是否为指定类型
+ */
+declare function isType<T>(value: unknown): value is T;
+//#endregion
+//#region src/client/create-http-client.utils.d.ts
+/**
+ * 创建 HTTP 客户端
+ *
+ * 创建配置好的 HTTP 客户端实例，提供统一的 REST 风格请求/响应处理。
+ * 返回的客户端提供类型安全的 request 方法。
+ *
+ * 支持拦截器模式进行扩展。
+ *
+ * @example
+ *   ```typescript
+ *   import {
+ *     createHttpClient,
+ *     createAuthTokenInterceptor,
+ *     createLoggingInterceptor,
+ *   } from '@longzai-intelligence-transport/http';
+ *
+ *   const loggingInterceptor = createLoggingInterceptor({ level: 'debug' });
+ *
+ *   const client = createHttpClient({
+ *     baseUrl: 'https://api.example.com',
+ *     requestInterceptors: [loggingInterceptor.request, createAuthTokenInterceptor(tokenProvider)],
+ *     responseInterceptors: [loggingInterceptor.response],
+ *   });
+ *
+ *   // 使用类型安全的 request 方法
+ *   const response = await client.request({ route: userRoutes.list });
+ *   ```;
+ *
+ * @param config - 客户端配置
+ * @returns HTTP 客户端实例
+ */
+declare function createHttpClient(config: HttpClientConfig): HttpClient;
+//#endregion
+//#region src/client/index.d.ts
+/**
+ * 设置 HTTP 客户端配置
+ *
+ * 供 orval 生成的客户端使用，配置 axios 实例的基础 URL、超时和认证
+ *
+ * @param config - 客户端配置
+ */
+declare function setHttpClientConfig(config: HttpClientConfig): void;
+/**
+ * 创建 orval 使用的 axios 实例
+ *
+ * 供 orval 生成的客户端调用，根据 setHttpClientConfig 配置创建 axios 实例
+ *
+ * @typeParam T - 响应数据类型
+ * @param config - Axios 请求配置
+ * @returns Axios 响应对象
+ */
+declare function createAxiosInstance<T>(config: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+//#endregion
+//#region src/adapters/adapter.types.d.ts
+/**
+ * HTTP 适配器接口
+ *
+ * 各运行时环境需实现此接口，拦截器执行器调用适配器执行实际 HTTP 请求
+ */
+type HttpAdapter = {
+  /**
+   * 执行 HTTP 请求
+   *
+   * @param context - 请求上下文（已通过请求拦截器处理）
+   * @returns 原始响应数据
+   */
+  execute(context: RequestInterceptorContext): Promise<{
+    /**
+     * HTTP 状态码
+     */
+    status: number;
+    /**
+     * 响应头
+     */
+    headers: Record<string, string>;
+    /**
+     * 响应数据
+     */
+    data: unknown;
+  }>;
+  /**
+   * 取消请求
+   *
+   * @param requestId - 请求标识
+   */
+  abort?(requestId: string): void;
+};
+/**
+ * Axios 适配器配置
+ */
+type AxiosAdapterConfig = {
+  /**
+   * 请求超时时间（毫秒）
+   */
+  timeout?: number;
+};
+/**
+ * Taro 适配器配置
+ */
+type TaroAdapterConfig = {
+  /**
+   * 请求超时时间（毫秒）
+   */
+  timeout?: number;
+};
+//#endregion
+//#region src/adapters/axios.adapter.d.ts
+/**
+ * 创建 Axios 适配器
+ *
+ * @param config - 适配器配置
+ * @returns HTTP 适配器实例
+ */
+declare function createAxiosAdapter(config?: AxiosAdapterConfig): HttpAdapter;
+//#endregion
+//#region src/mock/index.d.ts
+/**
+ * Mock 请求类型
+ *
+ * 描述一个模拟请求的配置
+ */
+type MockRequest = {
+  /**
+   * HTTP 方法
+   */
+  method?: string;
+  /**
+   * 路径模式（支持通配符）
+   */
+  path?: string;
+  /**
+   * 匹配条件函数
+   */
+  match?: (route: RouteDefinition, params?: unknown, query?: unknown, body?: unknown) => boolean;
+  /**
+   * 响应数据或响应生成函数
+   */
+  response: ApiResponse<unknown> | ((context: MockRequestContext) => ApiResponse<unknown>);
+  /**
+   * 响应延迟（毫秒）
+   */
+  delay?: number;
+};
+/**
+ * Mock 请求上下文
+ *
+ * 描述模拟请求执行时的上下文信息
+ */
+type MockRequestContext = {
+  /**
+   * 路由定义
+   */
+  route: RouteDefinition;
+  /**
+   * 路径参数
+   */
+  params?: unknown;
+  /**
+   * 查询参数
+   */
+  query?: unknown;
+  /**
+   * 请求体
+   */
+  body?: unknown;
+};
+/**
+ * 路由模拟请求选项类型
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type RouteMockRequestOptions<TRoute extends RouteDefinition> = {
+  /**
+   * 路由定义
+   */
+  route: TRoute;
+  /**
+   * 路径参数
+   */
+  params?: unknown;
+  /**
+   * 查询参数
+   */
+  query?: unknown;
+  /**
+   * 请求体
+   */
+  body?: unknown;
+};
+/**
+ * 创建模拟 HTTP 客户端
+ *
+ * @example
+ *   ```typescript
+ *   import { createMockHttpClient } from '@longzai-intelligence-transport/http';
+ *
+ *   const mockClient = createMockHttpClient({
+ *     success: true,
+ *     data: { id: 1, name: 'Test' },
+ *   });
+ *   ```;
+ *
+ * @typeParam T - 响应数据类型
+ * @param mockResponse - 模拟响应数据
+ * @returns 模拟的 HttpClient 实例
+ * @throws {@link Error} 当模拟响应类型不匹配时抛出错误
+ */
+declare function createMockHttpClient<T>(mockResponse: ApiResponse<T>): HttpClient;
+/**
+ * 创建可配置的模拟 HTTP 客户端
+ *
+ * @example
+ *   ```typescript
+ *   import { createConfigurableMockHttpClient } from '@longzai-intelligence-transport/http';
+ *
+ *   const responses = new Map([
+ *     ['GET:/users', { success: true, data: [{ id: 1, name: 'User 1' }] }],
+ *     ['POST:/users', { success: true, data: { id: 2, name: 'New User' } }],
+ *   ]);
+ *
+ *   const mockClient = createConfigurableMockHttpClient(responses);
+ *   ```;
+ *
+ * @param responses - 响应映射表，按路径和方法匹配
+ * @returns 模拟的 HttpClient 实例
+ * @throws {@link Error} 当模拟响应类型不匹配或创建失败时抛出错误
+ */
+declare function createConfigurableMockHttpClient(responses: Map<string, ApiResponse<unknown>>): HttpClient;
+/**
+ * 创建延迟响应的模拟 HTTP 客户端
+ *
+ * @example
+ *   ```typescript
+ *   import { createDelayedMockHttpClient } from '@longzai-intelligence-transport/http';
+ *
+ *   // 模拟 500ms 延迟
+ *   const mockClient = createDelayedMockHttpClient({ success: true, data: { id: 1 } }, 500);
+ *   ```;
+ *
+ * @typeParam T - 响应数据类型
+ * @param mockResponse - 模拟响应数据
+ * @param delay - 延迟时间（毫秒）
+ * @returns 模拟的 HttpClient 实例
+ * @throws {@link Error} 当模拟响应类型不匹配时抛出错误
+ */
+declare function createDelayedMockHttpClient<T>(mockResponse: ApiResponse<T>, delay: number): HttpClient;
+/**
+ * 创建错误响应的模拟 HTTP 客户端
+ *
+ * @example
+ *   ```typescript
+ *   import { createErrorMockHttpClient } from '@longzai-intelligence-transport/http';
+ *
+ *   const mockClient = createErrorMockHttpClient(new Error('Network error'));
+ *   ```;
+ *
+ * @param error - 要抛出的错误
+ * @returns 模拟的 HttpClient 实例
+ * @throws {@link Error} 总是抛出传入的错误
+ */
+declare function createErrorMockHttpClient(error: Error): HttpClient;
+/**
+ * 创建基于路由定义的 Mock 客户端
+ *
+ * @example
+ *   ```typescript
+ *   import { createRouteMock, defineRoute, z } from '@longzai-intelligence-transport/http';
+ *
+ *   const mockClient = createRouteMock([
+ *     {
+ *       path: '/users',
+ *       method: 'GET',
+ *       response: { success: true, data: [{ id: 1, name: 'User' }] },
+ *     },
+ *     {
+ *       match: (route) => route.method === 'POST' && route.path === '/users',
+ *       response: { success: true, data: { id: 2 } },
+ *       delay: 100,
+ *     },
+ *   ]);
+ *   ```;
+ *
+ * @param mocks - Mock 配置数组
+ * @returns 模拟的 HttpClient 实例
+ * @throws {@link Error} 当模拟响应类型不匹配或创建失败时抛出错误
+ */
+declare function createRouteMock(mocks: MockRequest[]): HttpClient;
+//#endregion
+//#region src/validation/index.d.ts
+/**
+ * 验证错误详情项
+ *
+ * 描述单个字段的验证错误
+ */
+type ValidationErrorDetail = {
+  /**
+   * 字段路径
+   */
+  path: string;
+  /**
+   * 错误消息
+   */
+  message: string;
+  /**
+   * 实际接收到的值
+   */
+  received: unknown;
+  /**
+   * 期望的类型或约束
+   */
+  expected: string;
+};
+/**
+ * 验证错误类型
+ *
+ * 包含验证失败的详细信息
+ */
+type ValidationError = {
+  /**
+   * 错误码
+   */
+  code: 'VALIDATION_ERROR';
+  /**
+   * 错误消息
+   */
+  message: string;
+  /**
+   * 字段级错误详情
+   */
+  details: ValidationErrorDetail[];
+};
+/**
+ * 验证结果类型
+ *
+ * 包含验证成功后的解析数据或验证失败的错误信息
+ *
+ * @typeParam TRoute - 路由定义类型
+ */
+type ValidationResult<TRoute extends RouteDefinition> = {
+  /**
+   * 验证是否成功
+   */
+  success: boolean;
+  /**
+   * 解析后的路径参数，验证成功时存在
+   */
+  params?: InferRouteParams<TRoute>;
+  /**
+   * 解析后的查询参数，验证成功时存在
+   */
+  query?: InferRouteQuery<TRoute>;
+  /**
+   * 解析后的请求体，验证成功时存在
+   */
+  body?: InferRouteBody<TRoute>;
+  /**
+   * 验证错误，验证失败时存在
+   */
+  error?: ValidationError;
+};
+/**
+ * 待验证的请求数据
+ */
+type RequestDataToValidate = {
+  /**
+   * 路径参数
+   */
+  params?: Record<string, string>;
+  /**
+   * 查询参数
+   */
+  query?: Record<string, string | string[]>;
+  /**
+   * 请求体
+   */
+  body?: unknown;
+};
+/**
+ * 从 ZodError 中提取验证错误详情
+ *
+ * @param zodError - Zod 验证错误
+ * @param prefix - 字段路径前缀
+ * @returns 验证错误详情数组
+ */
+declare function extractErrorDetails(zodError: ZodError, prefix?: string): ValidationErrorDetail[];
+/**
+ * Schema 验证成功结果
+ *
+ * @typeParam T - 解析后的数据类型
+ */
+type SchemaValidationSuccess<T> = {
+  /**
+   * 验证成功标记
+   */
+  success: true;
+  /**
+   * 解析后的数据
+   */
+  data: T;
+};
+/**
+ * Schema 验证失败结果
+ */
+type SchemaValidationFailure = {
+  /**
+   * 验证失败标记
+   */
+  success: false;
+  /**
+   * 验证错误详情列表
+   */
+  details: ValidationErrorDetail[];
+};
+/**
+ * Schema 验证结果
+ *
+ * @typeParam T - 解析后的数据类型
+ */
+type SchemaValidationResult<T> = SchemaValidationSuccess<T> | SchemaValidationFailure;
+/**
+ * 验证请求
+ *
+ * 从 RouteDefinition 中提取 Schema 并验证请求的 params / query / body
+ *
+ * @example
+ *   ```typescript
+ *   import { validateRequest, defineRoute, z } from '@longzai-intelligence-transport/http';
+ *
+ *   const userRoute = defineRoute({
+ *     method: 'POST',
+ *     path: '/users/:id',
+ *     params: z.object({ id: z.string().uuid() }),
+ *     query: z.object({ include: z.enum(['profile', 'settings']).optional() }),
+ *     body: z.object({ name: z.string(), email: z.string().email() }),
+ *     response: z.object({ id: z.string(), name: z.string() }),
+ *   });
+ *
+ *   const result = validateRequest(userRoute, {
+ *     params: { id: 'invalid-uuid' },
+ *     body: { name: 'Test', email: 'invalid-email' },
+ *   });
+ *
+ *   if (!result.success) {
+ *     console.log(result.error.details);
+ *     // [{ path: 'params.id', message: '...', ... }, { path: 'body.email', message: '...', ... }]
+ *   }
+ *   ```;
+ *
+ * @typeParam TRoute - 路由定义类型
+ * @param route - 路由定义
+ * @param request - 待验证的请求数据
+ * @returns 验证结果
+ * @throws {@link Error} 当验证结果创建失败时抛出错误
+ */
+declare function validateRequest<TRoute extends RouteDefinition>(route: TRoute, request: RequestDataToValidate): ValidationResult<TRoute>;
+/**
+ * 从 Zod 验证错误创建结构化 API 错误响应
+ *
+ * @example
+ *   ```typescript
+ *   import { createValidationErrorResponse } from '@longzai-intelligence-transport/http';
+ *   import * as z from 'zod';
+ *
+ *   const schema = z.object({ name: z.string() });
+ *   const result = schema.safeParse({ name: 123 });
+ *
+ *   if (!result.success) {
+ *     const response = createValidationErrorResponse(result.error);
+ *     // { success: false, error: { code: 'VALIDATION_ERROR', message: '参数验证失败', details: [...] } }
+ *   }
+ *   ```;
+ *
+ * @param zodError - Zod 验证错误
+ * @param message - 自定义错误消息，默认为"参数验证失败"
+ * @returns 符合 ApiResponse 格式的错误响应
+ */
+declare function createValidationErrorResponse(zodError: ZodError, message?: string): ApiResponse<never>;
+/**
+ * 从 ValidationError 创建 API 错误响应
+ *
+ * @param validationError - 验证错误
+ * @returns 符合 ApiResponse 格式的错误响应
+ */
+declare function createValidationErrorResponseFromError(validationError: ValidationError): ApiResponse<never>;
+//#endregion
+//#region src/types.d.ts
+/**
+ * 路由处理器类型
+ *
+ * 描述服务端路由的处理函数签名
+ *
+ * @typeParam T - 路由定义类型
+ */
+type RouteHandler<T extends RouteDefinition> = (context: {
+  /**
+   * 路径参数
+   */
+  params?: InferRouteParams<T>;
+  /**
+   * 查询参数
+   */
+  query?: InferRouteQuery<T>;
+  /**
+   * 请求体
+   */
+  body?: InferRouteBody<T>;
+  /**
+   * 请求头
+   */
+  headers?: Record<string, string>;
+}) => Promise<InferRouteResponse<T>>;
+/**
+ * 路由配置类型
+ *
+ * 将路由定义与处理器绑定
+ *
+ * @typeParam T - 路由定义类型
+ */
+type RouteConfig<T extends RouteDefinition> = {
+  /**
+   * 路由定义
+   */
+  route: T;
+  /**
+   * 路由处理器
+   */
+  handler: RouteHandler<T>;
+};
+//#endregion
+export { type ApiCompactPaginatedListData, ApiCompactPaginatedListDataSchema, type ApiError, type ApiErrorResponse, ApiErrorResponseSchema, ApiErrorSchema, type ApiFailResponse, type ApiFunctions, type ApiListData, ApiListDataSchema, ApiListDataUtil, type ApiPaginatedListData, ApiPaginatedListDataSchema, type ApiResponse, ApiResponseSchema, ApiResponseUtil, type ApiSuccessResponse, type ApiVersion, type ArrayElement, type AuthInterceptorConfig, type AuthStrategy, type AwaitedData, type AxiosAdapterConfig, type CreateApiFunction, type CreateDeleteFunction, type CreateGetFunction, type CreatePostFunction, type CreateUpdateFunction, type CsrfInterceptorConfig, type CsrfProvider, type CursorPaginatedResult, type CursorPaginationParams, CursorPaginationParamsSchema, DEFAULT_RETRY_STATUS_CODES, type DateRangeQuery, DateRangeQuerySchema, type DeepPartial, type DeepReadonly, type DeepRequired, ERROR_HTTP_STATUS, ERROR_MESSAGES, type EmptyResponse, EmptyResponseSchema, ErrorCode, type ErrorCodeConfig, ErrorCodeSchema, type ExtractData, type FilterQuery, FilterQuerySchema, type FormDataConvertConfig, type HttpAdapter, type HttpClient, type HttpClientConfig, type HttpMethod, type HttpPaginationConfig, type IdParams, IdParamsSchema, type InferRouteBody, type InferRouteFullResponse, type InferRouteItem, type InferRouteParams, type InferRouteQuery, type InferRouteResponse, type InferRouteReturn, type InterceptorExecutorConfig, type LoggingInterceptorConfig, type Merge, type MockRequest, type MockRequestContext, type NonNullableData, type ObjectKeys, type ObjectValues, type OffsetPaginatedResult, type OffsetPaginationParams, OffsetPaginationParamsSchema, type OmitByValue, type OptionalKeyOf, type OptionalKeys, type PaginatedResult, type PaginationParams, PaginationParamsSchema, type PaginationQuery, PaginationQuerySchema, type PickByValue, type RequestConfig, type RequestDataToValidate, type RequestInterceptor, type RequestInterceptorContext, type RequiredKeyOf, type RequiredKeys, type ResponseInterceptor, type ResponseInterceptorContext, type ResponseTransformer, type RetryConfig, type ReturnDataType, type RouteConfig, type RouteDefineConfig, type RouteDefineResult, type RouteDefinition, type RouteGroup, type RouteGroupConfig, type RouteHandler, type RouteMockRequestOptions, type RouteResponseBuilder, type SchemaValidationFailure, type SchemaValidationResult, type SchemaValidationSuccess, type SearchQuery, SearchQuerySchema, type TaroAdapterConfig, type TokenProvider, type UnwrapApiListData, type UnwrapApiPaginatedListData, type UnwrapApiResponse, type ValidationError, type ValidationErrorDetail, type ValidationInterceptorConfig, type ValidationResult, type VersionedPrefix, buildPath, buildQuery, calculateOffset, calculateTotalPages, concatPath, createApiClientFactory, createAuthStrategyInterceptor, createAuthTokenInterceptor, createAxiosAdapter, createAxiosInstance, createBearerAuthStrategy, createConfigurableMockHttpClient, createCookieAuthStrategy, createCsrfInterceptor, createCustomAuthStrategy, createDelayedMockHttpClient, createErrorCodeSchema, createErrorMockHttpClient, createExecutorConfigFromClientConfig, createFilterQuerySchema, createHttpClient, createHttpPaginationSchema, createInterceptorExecutor, createLoggingInterceptor, createLoggingRequestInterceptor, createLoggingResponseInterceptor, createMockHttpClient, createNoneAuthStrategy, createPaginatedResult, createRequestInterceptorsFromConfig, createResponseInterceptorsFromConfig, createResponseTransformerInterceptor, createRetryInterceptor, createRouteMock, createRouteResponseBuilder, createTypedEmpty, createTypedResponse, createValidationErrorResponse, createValidationErrorResponseFromError, createValidationInterceptor, defaultLogger, defineRoute, defineRouteGroup, exponentialBackoff, extractErrorDetails, getErrorMessage, getHttpStatus, isBlob, isFile, isFormDataContentType, isLegacyConfig, isRecord, isType, normalizePagination, objectToFormData, setHttpClientConfig, unwrapResult, validateRequest, warnDeprecatedConfig };