vome-core 0.0.1

package/dist/src/routing/base.d.ts

@@ -0,0 +1,27 @@
+/** 业务码：1000 成功 */
+export declare const RES_CODE: {
+    readonly SUCCESS: 1000;
+    readonly ERROR: 1001;
+};
+export type ResCode = (typeof RES_CODE)[keyof typeof RES_CODE];
+export type ApiSuccess<T = unknown> = {
+    code: typeof RES_CODE.SUCCESS;
+    message: string;
+    data: T;
+};
+export type ApiFail = {
+    code: number;
+    message: string;
+};
+export type ApiResult<T = unknown> = ApiSuccess<T> | ApiFail;
+/**
+ * 控制器基类
+ *
+ * - `ok(data)` → `{ code: 1000, message: 'success', data }`
+ * - `fail(message, code?)` → `{ code, message }`
+ * - 成功响应内 Date / *Time|*Date|*At 自动格式化为 `YYYY-MM-DD HH:mm:ss`
+ */
+export declare class BaseController {
+    ok<T = unknown>(data?: T): ApiSuccess<T | null>;
+    fail(message?: string, code?: number): ApiFail;
+}

package/dist/src/routing/context.d.ts

@@ -0,0 +1,14 @@
+import type { ControllerSide } from '../../typings/routing/meta';
+import type { ControllerScanContext } from '../../typings/routing/scan-context';
+export type { ControllerScanContext };
+export declare function setControllerScanContext(next: ControllerScanContext | null): void;
+export declare function getControllerScanContext(): ControllerScanContext | null;
+/** modules/base/controller/admin/auth.ts → base */
+export declare function parseModuleFromPath(file: string): string;
+/**
+ * 未写 prefix 时由文件路径生成（相对 sidePrefix）
+ * modules/base/controller/admin/auth.ts → /base/auth
+ * modules/user/controller/app/rbac.ts → /user/rbac
+ */
+export declare function parseControllerAutoPrefix(file: string): string;
+export type { ControllerSide };

package/dist/src/routing/crud-summary.d.ts

@@ -0,0 +1,2 @@
+/** CRUD 接口 OpenAPI / EPS 备注 */
+export declare const CRUD_SUMMARY: Record<string, string>;

package/dist/src/routing/decorators.d.ts

@@ -0,0 +1,48 @@
+import 'reflect-metadata';
+import type { RouteMiddleware } from '../../typings/routing/crud';
+import type { ControllerOptions } from '../../typings/routing/meta';
+/**
+ * 注册控制器（自动进 IoC，无需 `@Provide`）。
+ *
+ * @param prefixOrOptions - `'/auth'` 显式前缀；省略则按规则：/{module}/{文件名}
+ */
+export declare function Controller(prefixOrOptions?: string | ControllerOptions): (target: new (...args: unknown[]) => unknown) => void;
+/**
+ * 单路由中间件（Elysia beforeHandle）
+ *
+ * @example
+ * ```ts
+ * @Use(rateLimit)
+ * @Post('/once')
+ * once() {}
+ * ```
+ */
+export declare function Use(...middleware: RouteMiddleware[]): (target: object, propertyKey: string | symbol) => void;
+/** 公开路由：admin 侧跳过鉴权宏 */
+export declare function Public(): (target: object, propertyKey: string | symbol) => void;
+/**
+ * 显式权限码（可选覆盖自动推导）；超管跳过。
+ * 业务侧优先在菜单配置权限码，一般无需使用。
+ */
+export declare function Perms(...codes: string[]): (target: object, propertyKey: string | symbol) => void;
+/** 跳过权限码校验（仍走登录，除非同时 @Public） */
+export declare function IgnorePerms(): (target: object, propertyKey: string | symbol) => void;
+export declare const Body: (schema?: unknown) => (target: object, propertyKey: string | symbol | undefined, parameterIndex: number) => void;
+export declare const Query: (schema?: unknown) => (target: object, propertyKey: string | symbol | undefined, parameterIndex: number) => void;
+export declare const Param: (schema?: unknown) => (target: object, propertyKey: string | symbol | undefined, parameterIndex: number) => void;
+/** @example `@Get('/perms', { summary: '当前权限' })` → 侧栏显示 `perms 当前权限` */
+export declare const Get: (path?: string, options?: {
+    summary?: string;
+}) => (target: object, propertyKey: string | symbol) => void;
+export declare const Post: (path?: string, options?: {
+    summary?: string;
+}) => (target: object, propertyKey: string | symbol) => void;
+export declare const Put: (path?: string, options?: {
+    summary?: string;
+}) => (target: object, propertyKey: string | symbol) => void;
+export declare const Delete: (path?: string, options?: {
+    summary?: string;
+}) => (target: object, propertyKey: string | symbol) => void;
+export declare const Patch: (path?: string, options?: {
+    summary?: string;
+}) => (target: object, propertyKey: string | symbol) => void;

package/dist/src/routing/eps.d.ts

@@ -0,0 +1,16 @@
+import type { EpsApiItem, EpsColumn, EpsEntity, EpsModuleMap } from '../../typings/routing/eps';
+import { listControllers } from './metadata';
+export type { EpsApiItem, EpsColumn, EpsEntity, EpsModuleMap };
+/** 是否开启 EPS 下发（vome.eps === true） */
+export declare function isEpsEnabled(): boolean;
+/**
+ * EPS 接口元数据（按模块分组）
+ * - admin → GET /admin/base/open/eps
+ * - app → GET /app/base/open/eps
+ */
+export declare const Eps: {
+    controllers: typeof listControllers;
+    admin: () => EpsModuleMap;
+    app: () => EpsModuleMap;
+    enabled: typeof isEpsEnabled;
+};

package/dist/src/routing/index.d.ts

@@ -0,0 +1,8 @@
+export { Eps, isEpsEnabled } from './eps';
+export type { EpsApiItem, EpsColumn, EpsEntity, EpsModuleMap } from './eps';
+export { BaseController, RES_CODE } from './base';
+export type { ApiFail, ApiResult, ApiSuccess, ResCode } from './base';
+export { Controller, Get, Post, Put, Delete, Patch, Body, Query, Param, Public, Perms, IgnorePerms, Use, } from './decorators';
+export { listControllers, type ControllerMeta, type ControllerRouteMeta, type ControllerSide, type HttpMethod, type RouteParamMeta, type RouteParamSource, } from './metadata';
+export type { ControllerCrudOptions, CrudApi, CrudBeforeFn, InsertParamFn, QueryExtendFn, QueryExtendQb, QueryFieldRef, QueryJoin, QueryJoinType, QueryOp, QueryOpCtx, QueryWhereFn, QueryWhereResult, RouteMiddleware, } from '../../typings/routing/crud';
+export type { CrudRegistrar } from './register';

package/dist/src/routing/metadata.d.ts

@@ -0,0 +1,28 @@
+import 'reflect-metadata';
+import type { ControllerCrudOptions, RouteMiddleware } from '../../typings/routing/crud';
+import type { ControllerMeta, ControllerRouteMeta, ControllerSide, HttpMethod, RouteParamMeta, RouteParamSource } from '../../typings/routing/meta';
+export type { ControllerMeta, ControllerRouteMeta, ControllerSide, HttpMethod, RouteParamMeta, RouteParamSource, };
+export declare function registerController(meta: ControllerMeta): void;
+export declare function listControllers(side?: ControllerSide): ControllerMeta[];
+export declare function appendRouteParam(token: new (...args: unknown[]) => unknown, handler: string, param: RouteParamMeta): void;
+export declare function getRouteParams(token: new (...args: unknown[]) => unknown, handler: string): RouteParamMeta[];
+export declare function clearRouteParams(token: new (...args: unknown[]) => unknown): void;
+export declare function markRoutePublic(token: new (...args: unknown[]) => unknown, handler: string): void;
+export declare function isRoutePublic(token: new (...args: unknown[]) => unknown, handler: string): boolean;
+export declare function clearRoutePublic(token: new (...args: unknown[]) => unknown): void;
+export declare function appendRouteMiddleware(token: new (...args: unknown[]) => unknown, handler: string, middleware: RouteMiddleware[]): void;
+export declare function getRouteMiddleware(token: new (...args: unknown[]) => unknown, handler: string): RouteMiddleware[];
+export declare function clearRouteMiddleware(token: new (...args: unknown[]) => unknown): void;
+export declare function setRoutePerms(token: new (...args: unknown[]) => unknown, handler: string, perms: string[]): void;
+export declare function getRoutePerms(token: new (...args: unknown[]) => unknown, handler: string): string[] | undefined;
+export declare function clearRoutePerms(token: new (...args: unknown[]) => unknown): void;
+export declare function markRouteIgnorePerms(token: new (...args: unknown[]) => unknown, handler: string): void;
+export declare function isRouteIgnorePerms(token: new (...args: unknown[]) => unknown, handler: string): boolean;
+export declare function clearRouteIgnorePerms(token: new (...args: unknown[]) => unknown): void;
+export declare function schemaFromParams(params: RouteParamMeta[]): {
+    body?: unknown;
+    query?: unknown;
+    params?: unknown;
+} | undefined;
+/** @internal 供装饰器写入 CRUD 选项时使用 */
+export type { ControllerCrudOptions, RouteMiddleware };

package/dist/src/routing/openapi-tags.d.ts

@@ -0,0 +1,23 @@
+import { type ControllerSide } from './metadata';
+/**
+ * OpenAPI 操作 tag（全局唯一）
+ * 侧栏展示名靠 x-displayName = admin | app，勿用 `/`（Scalar 会显示成整串）
+ */
+export declare function openApiTag(module: string, side: ControllerSide): string;
+/**
+ * 侧栏结构：
+ *   base          ← x-tagGroups（一级：模块名）
+ *     admin       ← tag + x-displayName（二级）
+ *     app
+ */
+export declare function buildOpenApiTagDocs(): {
+    tags: {
+        name: string;
+        description: string;
+        'x-displayName': string;
+    }[];
+    tagGroups: {
+        name: string;
+        tags: string[];
+    }[];
+};

package/dist/src/routing/path-utils.d.ts

@@ -0,0 +1,5 @@
+/** 路由前缀 / 路径拼接（register / eps / decorators 共用） */
+export declare function normalizePrefix(prefix: string): string;
+export declare function joinPrefix(...parts: string[]): string;
+/** 从完整路由路径拆出相对 controller prefix 的子路径 */
+export declare function getRouteSubPath(routePath: string, controllerPrefix: string): string;

package/dist/src/routing/perm.d.ts

@@ -0,0 +1,18 @@
+import type { ControllerMeta, ControllerRouteMeta } from '../../typings/routing/meta';
+/**
+ * 由模块 + Controller prefix + action 推导权限码
+ * - /menu + module base → base:menu:add
+ * - /user-role + module user → user:role:add
+ * - /base/menu（自动前缀）→ base:menu:add
+ * - /user/user-role → user:role:add
+ */
+export declare function resolveRoutePerm(module: string, prefix: string, action: string): string;
+/** 路由子路径最后一段作为 action（/tree → tree） */
+export declare function actionFromSubPath(subPath: string): string;
+/**
+ * admin 非公开路由的有效权限码：
+ * 显式 @Perms → 用显式；否则按约定推导；Public / IgnorePerms → 无
+ */
+export declare function effectivePerms(route: Pick<ControllerRouteMeta, 'public' | 'ignorePerms' | 'perms'> & {
+    path?: string;
+}, meta: Pick<ControllerMeta, 'side' | 'module' | 'prefix'>, action?: string): string[] | undefined;

package/dist/src/routing/register.d.ts

@@ -0,0 +1,7 @@
+import { type AnyElysia } from 'elysia';
+import type { CrudRegistrar, CrudRouteOptionsInput } from '../../typings/routing/register';
+export type { CrudRegistrar, CrudRouteOptionsInput };
+/** @internal 宿主注册 CRUD 实现 */
+export declare function setCrudRegistrar(fn: CrudRegistrar | undefined): void;
+/** 扫描元数据并注册 Elysia 路由（须在 bootstrapIoc 之后调用） */
+export declare function registerControllers(app: AnyElysia, vomeConfig: Record<string, unknown>): AnyElysia;

package/dist/src/server/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * vome-core/server — Bun + Elysia 服务端框架入口
+ *
+ * 导入时加载宿主 `src/config`；扫描 / IoC / 路由注册在 `App.start()` 中执行。
+ * 宿主须：`import 'reflect-metadata'`，并开启 `experimentalDecorators` + `emitDecoratorMetadata`。
+ */
+export { App, appendInjectMeta, BaseController, Body, CommException, Context, Controller, Delete, Eps, isEpsEnabled, Get, getEnv, Inject, Ioc, isCommException, listControllers, listProviders, Logger, Param, Patch, Post, Provide, Public, Perms, IgnorePerms, Put, Query, RES_CODE, scanFiles, ScopeEnum, Use, vome, VomeConfig, DbStore, baseColumns, BASE_COLUMN_COMMENTS, entitySchemas, columnComments, getColumnComments, syncColumnCommentsToPg, Repository, getRepository, InjectRepository, BaseService, q, attachCrudRoutes, isTenantEnabled, noTenant, normalizeHost, resolveTenantScope, tableHasDepartmentId, resolveDataScope, applyDataScopeWhere, applyRowScopes, noDataScope, BasePlugin, loadPluginClass, readPluginScript, pDataPath, pPluginPath, pModulesPath, pModulePath, ModuleRegistry, loadModuleHandlers, microApps, createModuleGateway, defineAuthMacro, } from '../core';
+export type { ApiFail, ApiResult, ApiSuccess, ClassToken, ContextData, ControllerCrudOptions, ControllerMeta, ControllerRouteMeta, ControllerSide, CrudApi, CrudBeforeFn, CrudRegistrar, CrudUpsertMode, CrudModifyType, CrudWriteOptions, CrudTrashQueryOptions, CrudDeleteOptions, PageQuery, PagePagination, PageResult, PluginManifest, PluginInfo, PluginPayload, PluginCheckResult, ModuleRouteDef, ModuleMenuDef, ModuleManifest, ModuleHandlerCtx, ModuleHandler, ModuleInstalled, EpsApiItem, EpsColumn, EpsEntity, EpsModuleMap, HttpMethod, InjectionToken, InjectMeta, InsertParamFn, ProvideOptions, ProviderToken, QueryExtendFn, QueryExtendQb, QueryFieldRef, QueryJoin, QueryJoinType, QueryOp, QueryOpCtx, QueryWhereFn, QueryWhereResult, ResCode, RouteMiddleware, RouteParamMeta, RouteParamSource, ScanOptions, } from '../core';
+/** 与 package.json version 同步 */
+export declare const version: string;

package/dist/src/shared/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 同构共享：前后端均可引用（无 Bun / Elysia / Vue 依赖）
+ */
+export { merge } from '../comm/merge';
+export { deepTree, flattenTree } from './tree';
+export type { Loose } from '../../typings/common';
+export type { PageQuery, PagePagination, PageResult } from '../../typings/comm/page';
+export { RES_CODE, type ResCode, type ApiSuccess, type ApiFail, type ApiResult, } from '../routing/base';

package/dist/src/shared/tree.d.ts

@@ -0,0 +1,18 @@
+/** 扁平列表 → 树（parentId） */
+export declare function deepTree<T extends {
+    id?: number | string;
+    parentId?: number | string | null;
+    children?: T[];
+    orderNum?: number;
+}>(list: T[], sort?: 'asc' | 'desc'): T[];
+/** 树 → 扁平（带 depth / hasChildren），按 expanded 展开 */
+export declare function flattenTree<T extends {
+    id: number | string;
+    children?: T[];
+}>(nodes: T[], expanded: Set<string | number>, depth?: number, out?: Array<T & {
+    depth: number;
+    hasChildren: boolean;
+}>): Array<T & {
+    depth: number;
+    hasChildren: boolean;
+}>;

package/dist/typings/comm/crud.d.ts

@@ -0,0 +1,24 @@
+/** save：有 id 则更新；insert：只插入 */
+export type CrudUpsertMode = 'save' | 'insert';
+/** modifyBefore / modifyAfter 操作类型 */
+export type CrudModifyType = 'add' | 'update' | 'delete';
+/** add() 可选覆盖 */
+export type CrudWriteOptions = {
+    upsert?: CrudUpsertMode;
+};
+/** 查询回收站范围 */
+export type CrudTrashQueryOptions = {
+    withTrashed?: boolean;
+    onlyTrashed?: boolean;
+    softDelete?: boolean;
+};
+/** 删除选项 */
+export type CrudDeleteOptions = {
+    force?: boolean;
+    softDelete?: boolean;
+};
+/** vome.crud 运行时配置 */
+export type CrudConfig = {
+    upsert?: CrudUpsertMode;
+    softDelete?: boolean;
+};

package/dist/typings/comm/page.d.ts

@@ -0,0 +1,16 @@
+/** 分页参数 */
+export type PageQuery = {
+    /** 页码，从 1 开始，默认 1 */
+    page?: number;
+    /** 每页条数，默认 20 */
+    size?: number;
+};
+export type PagePagination = {
+    page: number;
+    size: number;
+    total: number;
+};
+export type PageResult<T = unknown> = {
+    list: T[];
+    pagination: PagePagination;
+};

package/dist/typings/comm/scan.d.ts

@@ -0,0 +1,6 @@
+export type ScanOptions = {
+    /** 宿主项目根目录，默认 process.cwd() */
+    cwd?: string;
+    /** 扩展名过滤，默认 .ts / .tsx */
+    ext?: RegExp;
+};

package/dist/typings/common.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 宽松对象类型：在固定字段基础上允许追加任意属性
+ */
+export type Loose<T extends object> = T & {
+    [key: string]: any;
+};

package/dist/typings/context/data.d.ts

@@ -0,0 +1,10 @@
+/** ALS 存储的请求上下文数据 */
+export interface ContextData {
+    requestId: string;
+    method: string;
+    path: string;
+    /** 客户端 IP（优先代理头，无则空串） */
+    ip: string;
+    startTime: number;
+    [key: string]: unknown;
+}

package/dist/typings/ext/module.d.ts

@@ -0,0 +1,45 @@
+export type ModuleRouteDef = {
+    method: string;
+    path: string;
+    handler: string;
+    perms?: string;
+    summary?: string;
+};
+export type ModuleMenuDef = {
+    name: string;
+    router?: string;
+    perms?: string;
+    type?: number;
+    icon?: string;
+    orderNum?: number;
+    appKey?: string;
+    isShow?: boolean;
+};
+export type ModuleManifest = {
+    name: string;
+    key: string;
+    version: string;
+    description?: string;
+    hook?: string;
+    config?: Record<string, unknown>;
+    singleton?: boolean;
+    author?: string;
+    logo?: string;
+    readme?: string;
+    routes?: ModuleRouteDef[];
+    menus?: ModuleMenuDef[];
+};
+export type ModuleHandlerCtx = {
+    body: unknown;
+    query: Record<string, string>;
+    params: Record<string, string>;
+    headers: Headers;
+    adminId?: number | string;
+};
+export type ModuleHandler = (ctx: ModuleHandlerCtx) => unknown | Promise<unknown>;
+export type ModuleInstalled = ModuleManifest & {
+    path: string;
+    hasServer: boolean;
+    hasWeb: boolean;
+    hasHook: boolean;
+};

package/dist/typings/ext/plugin.d.ts

@@ -0,0 +1,40 @@
+export type PluginManifest = {
+    name: string;
+    key: string;
+    hook?: string;
+    singleton?: boolean;
+    version: string;
+    description?: string;
+    author?: string;
+    logo?: string;
+    readme?: string;
+    config?: Record<string, unknown>;
+};
+export type PluginInfo = PluginManifest & {
+    config?: Record<string, unknown>;
+};
+export type PluginPayload = {
+    content: {
+        type: 'comm' | 'module';
+        data: string;
+    };
+    tsContent: {
+        type: 'ts';
+        data: string;
+    };
+};
+export type PluginCheckResult = {
+    type: 0 | 1 | 2 | 3;
+    message: string;
+};
+export type PluginServices = {
+    cache?: {
+        get: (key: string) => Promise<unknown>;
+        set: (key: string, value: unknown) => Promise<unknown>;
+        del: (key: string) => Promise<unknown>;
+    };
+    pluginService?: {
+        getInstance: (key: string) => Promise<unknown>;
+        invoke: (key: string, method: string, ...params: unknown[]) => Promise<unknown>;
+    };
+};

package/dist/typings/ioc/metadata.d.ts

@@ -0,0 +1,31 @@
+/** IoC 作用域 */
+export type ScopeValue = 'singleton' | 'request' | 'prototype';
+/** 可 new 的 Provider 类 */
+export type ClassToken<T = unknown> = abstract new (...args: any[]) => T;
+/**
+ * 注入标识：类 / 字符串 id / symbol
+ * 字符串 id 用于跨模块按名注入
+ */
+export type InjectionToken<T = unknown> = ClassToken<T> | string | symbol;
+/** @deprecated 使用 {@link ClassToken} */
+export type ProviderToken<T = unknown> = ClassToken<T>;
+export type InjectMeta = {
+    propertyKey: string | symbol;
+    /** 依赖标识；与 resolve 二选一 */
+    token?: InjectionToken;
+    /** 自定义解析（如 Repository） */
+    resolve?: () => unknown;
+};
+export type ProviderMeta = {
+    /** 注册键（类或自定义 id） */
+    token: InjectionToken;
+    /** 实际用来 new 的类 */
+    useClass: ClassToken;
+    scope: ScopeValue;
+};
+export type ProvideOptions = {
+    /** 自定义标识，可用 `@Inject('id')` / `Ioc.get('id')` */
+    id?: string | symbol;
+    /** 作用域，默认 singleton */
+    scope?: ScopeValue;
+};

package/dist/typings/logger/config.d.ts

@@ -0,0 +1,6 @@
+export type LoggingConfig = {
+    level?: string;
+    transport?: 'console' | 'file';
+    dir?: string;
+    maxDays?: number;
+};

package/dist/typings/routing/crud.d.ts

@@ -0,0 +1,99 @@
+import type { ClassToken } from '../ioc/metadata';
+/** 快速 CRUD 接口名（含回收站） */
+export type CrudApi = 'add' | 'delete' | 'update' | 'info' | 'list' | 'page' | 'restore';
+/** 字段引用：表字段名，或带字典 / 前端行为的对象 */
+export type QueryFieldRef = string | {
+    column: string;
+    /** 请求体参数名，默认与 column 相同 */
+    requestParam?: string;
+    /** 筛选项展示名；缺省用实体 columnComments / EPS comment */
+    label?: string;
+    /** 业务字典 type.key；筛选项用其拉 options */
+    dict?: string;
+    /** 有 dict 时默认 true（下拉多选）；false 为单选 */
+    multiple?: boolean;
+    /** true：后端仍按本字段筛选，admin 不自动构建筛控件 */
+    none?: boolean;
+};
+/** 区间筛选精度 / 数字类型（告诉 admin 用什么控件） */
+export type FieldRangeType = 'int' | 'float' | 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second';
+/** 价格 / 时间等区间；min/max 为请求体参数名 */
+export type QueryFieldRange = {
+    column: string;
+    min: string;
+    max: string;
+    type: FieldRangeType;
+    /** true：后端支持区间，admin 不自动出控件 */
+    none?: boolean;
+};
+/** join 类型 */
+export type QueryJoinType = 'join' | 'leftJoin' | 'innerJoin';
+/**
+ * Join 配置（宿主解释为 Drizzle pgTable）
+ * `on(main)` 返回 SQL 条件，main 为主表
+ */
+export type QueryJoin = {
+    table: unknown;
+    type?: QueryJoinType;
+    on: (main: any) => unknown;
+};
+/** where / extend 上下文 */
+export type QueryOpCtx = {
+    body: Record<string, unknown>;
+    request: Request;
+};
+/** where 返回：单条 SQL，或列表（undefined/false/null 自动丢弃） */
+export type QueryWhereResult = unknown | Array<unknown | undefined | false | null>;
+export type QueryWhereFn = (ctx: QueryOpCtx) => QueryWhereResult | Promise<QueryWhereResult>;
+/** extend 可改的查询句柄 */
+export type QueryExtendQb = {
+    andWhere: (condition: unknown) => void;
+    orderBy: (...orders: unknown[]) => void;
+};
+export type QueryExtendFn = (qb: QueryExtendQb, ctx: QueryOpCtx) => void | Promise<void>;
+/** page / list 查询配置 */
+export type QueryOp = {
+    keyWordLikeFields?: string[];
+    fieldEq?: QueryFieldRef[];
+    fieldLike?: QueryFieldRef[];
+    /** PG 数组列包含查询（body 单值或数组）；admin 筛选用输入框 */
+    fieldArray?: QueryFieldRef[];
+    /** 数字 / 时间区间（与 fieldEq 等并存，勿再在 where 里拆参） */
+    fieldRange?: QueryFieldRange[];
+    addOrderBy?: Record<string, 'asc' | 'desc'>;
+    /** Drizzle select 对象；有 join 时建议显式配置 */
+    select?: unknown;
+    join?: QueryJoin[];
+    where?: QueryWhereFn;
+    extend?: QueryExtendFn;
+};
+export type InsertParamFn = (ctx: {
+    body?: unknown;
+    request?: Request;
+}) => Record<string, unknown> | Promise<Record<string, unknown>>;
+/** 写操作前钩子（add / update / delete / restore） */
+export type CrudBeforeFn = (ctx: {
+    body: Record<string, unknown>;
+    request: Request;
+    api: string;
+}) => void | Promise<void>;
+/** 控制器 / 路由中间件（Elysia onBeforeHandle） */
+export type RouteMiddleware = (ctx: Record<string, unknown>) => unknown | Promise<unknown>;
+/**
+ * @Controller 快速 CRUD 选项（Drizzle 适配）
+ */
+export type ControllerCrudOptions = {
+    api?: CrudApi[];
+    /** Drizzle pgTable，宿主挂载 Repository */
+    entity?: unknown;
+    /** 业务 Service 类（须 @Provide，建议 extends BaseService） */
+    service?: ClassToken;
+    /** 把 Service 方法挂成 POST /methodName */
+    serviceApis?: string[];
+    /** 写操作前改 body（add/update/delete/restore） */
+    before?: CrudBeforeFn;
+    pageQueryOp?: QueryOp;
+    listQueryOp?: QueryOp;
+    insertParam?: InsertParamFn;
+    infoIgnoreProperty?: string[];
+};

package/dist/typings/routing/eps.d.ts

@@ -0,0 +1,53 @@
+import type { QueryFieldRange, QueryFieldRef } from './crud';
+import type { ControllerSide } from './meta';
+/** EPS：单条 API */
+export type EpsApiItem = {
+    method: string;
+    path: string;
+    summary: string;
+    dts: Record<string, unknown>;
+    tag: string;
+    prefix: string;
+    ignoreToken: boolean;
+    /** 强化：登录但免权限码 */
+    ignorePerms: boolean;
+    /** 强化：推导/显式权限码 */
+    perms: string[];
+};
+/** EPS：字段列 */
+export type EpsColumn = {
+    propertyName: string;
+    type: string;
+    length?: string;
+    comment?: string;
+    nullable?: boolean;
+    defaultValue?: unknown;
+    source?: string;
+    dict?: string | string[];
+};
+/** EPS：单个控制器/实体描述 */
+export type EpsEntity = {
+    module: string;
+    /** 强化：admin | app */
+    side: ControllerSide;
+    prefix: string;
+    name?: string;
+    info: {
+        type: {
+            name: string;
+            description: string;
+        };
+    };
+    api: EpsApiItem[];
+    columns: EpsColumn[];
+    pageQueryOp: {
+        keyWordLikeFields: string[];
+        fieldEq: Array<string | QueryFieldRef>;
+        fieldLike: Array<string | QueryFieldRef>;
+        fieldArray: Array<string | QueryFieldRef>;
+        fieldRange: QueryFieldRange[];
+    };
+    pageColumns: EpsColumn[];
+};
+/** EPS：按模块分组 */
+export type EpsModuleMap = Record<string, EpsEntity[]>;

package/dist/typings/routing/meta.d.ts

@@ -0,0 +1,56 @@
+import type { ControllerCrudOptions, RouteMiddleware } from './crud';
+export type ControllerSide = 'admin' | 'app';
+/** @Controller() 装饰器选项 */
+export type ControllerOptions = {
+    /** 路由前缀，如 `/auth`；也可用字符串参数简写 */
+    prefix?: string;
+    side?: ControllerSide;
+    module?: string;
+    /** EPS / OpenAPI 描述 */
+    description?: string;
+    /** 控制器级中间件 */
+    middleware?: RouteMiddleware | RouteMiddleware[];
+} & ControllerCrudOptions;
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+export type RouteParamSource = 'body' | 'query' | 'params';
+/** handler 参数装饰器元数据（@Body / @Query / @Param） */
+export type RouteParamMeta = {
+    index: number;
+    source: RouteParamSource;
+    schema?: unknown;
+};
+/** 路由元数据 */
+export type ControllerRouteMeta = {
+    method: HttpMethod;
+    path: string;
+    handler: string;
+    body?: unknown;
+    query?: unknown;
+    routeParams?: unknown;
+    params?: RouteParamMeta[];
+    public?: boolean;
+    summary?: string;
+    /** 单路由中间件 */
+    middleware?: RouteMiddleware[];
+    /** 权限码（任一即可）；未设且非 IgnorePerms 时由路由自动推导 */
+    perms?: string[];
+    /** 跳过权限码校验（仍可要求登录） */
+    ignorePerms?: boolean;
+    /** 框架自动 CRUD 路由 */
+    autoCrud?: boolean;
+};
+/** 控制器元数据 */
+export type ControllerMeta = {
+    token: new (...args: unknown[]) => unknown;
+    module: string;
+    side: ControllerSide;
+    prefix: string;
+    /** OpenAPI / EPS 描述 */
+    description?: string;
+    file?: string;
+    routes: ControllerRouteMeta[];
+    /** 控制器级中间件（该 plugin 下全部路由） */
+    middleware?: RouteMiddleware[];
+    /** 快速 CRUD 配置 */
+    crud?: ControllerCrudOptions;
+};