@wordrhyme/auto-crud-server 0.7.0 → 0.9.0

package/README.md

@@ -75,27 +75,32 @@ export const tasks = pgTable("tasks", {
 // src/server/routers/tasks.ts
 import { createCrudRouter } from "@wordrhyme/auto-crud-server";
 import { tasks } from "@/db/schema";
+
+// 🚀 零配置！一行代码生成完整 CRUD 路由
+export const tasksRouter = createCrudRouter({
+  table: tasks,
+  // Schema 自动从 table 派生，排除 id, createdAt, updatedAt
+});
+```
+
+**或者，显式传入 Schema：**
+
+```typescript
+import { createCrudRouter } from "@wordrhyme/auto-crud-server";
+import { tasks } from "@/db/schema";
 import { createSelectSchema } from "drizzle-zod";
 
 // 从 Drizzle Schema 自动生成 Zod Schema
-const selectTaskSchema = createSelectSchema(tasks);
-
-// 创建输入 Schema
-const insertTaskSchema = selectTaskSchema.omit({
+const taskSchema = createSelectSchema(tasks).omit({
   id: true,
   createdAt: true,
   updatedAt: true,
 });
 
-const updateTaskSchema = insertTaskSchema.partial();
-
-// 🚀 一行代码生成完整 CRUD 路由
 export const tasksRouter = createCrudRouter({
   table: tasks,
-  selectSchema: selectTaskSchema,
-  insertSchema: insertTaskSchema,
-  updateSchema: updateTaskSchema,
-  idField: "id",  // 可选，默认为 "id"
+  schema: taskSchema,  // 主 Schema（用于 create/upsert）
+  // updateSchema 自动派生为 schema.partial()
 });
 ```
 
@@ -440,14 +445,57 @@ await trpc.tasks.list({
 
 ```typescript
 interface CrudRouterConfig<TTable, TSelect, TInsert, TUpdate> {
+  // ========== 必填 ==========
   table: TTable;                    // Drizzle 表定义
-  selectSchema: z.ZodType<TSelect>; // 查询返回 Schema
-  insertSchema: z.ZodType<TInsert>; // 创建输入 Schema
-  updateSchema: z.ZodType<TUpdate>; // 更新输入 Schema
+
+  // ========== Schema 配置（可选） ==========
+  schema?: z.ZodType<TInsert>;      // 主 Schema（用于 create/upsert）
+  updateSchema?: z.ZodType<TUpdate>;// 更新 Schema（覆盖自动派生）
+  selectSchema?: z.ZodType<TSelect>;// 查询返回 Schema
+
+  // ========== 其他配置 ==========
   idField?: string;                 // ID 字段名，默认 "id"
+  omitFields?: string[];            // 自动派生时排除的字段
+                                    // 默认 ["id", "createdAt", "updatedAt"]
 }
 ```
 
+#### Schema 派生规则
+
+| 配置 | 派生行为 |
+|-----|---------|
+| 无 `schema` | 从 `table` 自动派生，排除 `omitFields` |
+| 无 `updateSchema` | 从 `schema.partial().refine(nonEmpty)` 派生 |
+| 无 `selectSchema` | 若有 `schema` 则使用它，否则从 `table` 派生 |
+
+#### 使用示例
+
+```typescript
+// 1. 零配置 - 全部自动派生
+const tasksRouter = createCrudRouter({
+  table: tasks,
+});
+
+// 2. 传入 schema，updateSchema 自动派生
+const postsRouter = createCrudRouter({
+  table: posts,
+  schema: postSchema,
+});
+
+// 3. 传入 schema + 自定义 updateSchema
+const usersRouter = createCrudRouter({
+  table: users,
+  schema: userSchema,
+  updateSchema: customUpdateSchema,
+});
+
+// 4. 自定义排除字段
+const ordersRouter = createCrudRouter({
+  table: orders,
+  omitFields: ["id", "createdAt", "updatedAt", "internalCode"],
+});
+```
+
 #### 返回值
 
 ```typescript
@@ -459,95 +507,94 @@ interface CrudRouterConfig<TTable, TSelect, TInsert, TUpdate> {
   // 可 spread 的 procedures 对象（用于扩展自定义路由）
   procedures: {
     list: Procedure<ListInput, ListOutput>,
-    getById: Procedure<string, TSelect>,
+    get: Procedure<string, TSelect>,
     create: Procedure<TInsert, TSelect>,
     update: Procedure<{ id: string, data: TUpdate }, TSelect>,
     delete: Procedure<string, TSelect>,
     deleteMany: Procedure<string[], { deleted: number }>,
     updateMany: Procedure<{ ids: string[], data: TUpdate }, { updated: number }>,
+    upsert: Procedure<TInsert, { data: TSelect, isNew: boolean }>,
   }
 }
 ```
 
-#### 完整示例
+---
+
+## 🔐 权限控制
+
+### 使用 procedure 配置
 
 ```typescript
 import { createCrudRouter } from "@wordrhyme/auto-crud-server";
-import { users } from "@/db/schema";
-import { createSelectSchema } from "drizzle-zod";
-import { z } from "zod";
+import { protectedProcedure, adminProcedure, publicProcedure } from "../trpc";
 
-const selectUserSchema = createSelectSchema(users);
-
-const insertUserSchema = selectUserSchema.omit({
-  id: true,
-  createdAt: true,
-  updatedAt: true,
+export const tasksRouter = createCrudRouter({
+  table: tasks,
+  // 按操作指定不同的 procedure
+  procedure: {
+    list: publicProcedure,      // 公开读
+    get: publicProcedure,
+    create: protectedProcedure, // 需要登录
+    update: protectedProcedure,
+    delete: adminProcedure,     // 需要管理员
+    default: protectedProcedure,
+  },
 });
+```
 
-const updateUserSchema = insertUserSchema.partial();
+### 使用 guard（操作级守卫）
 
-export const usersRouter = createCrudRouter({
-  table: users,
-  selectSchema: selectUserSchema,
-  insertSchema: insertUserSchema,
-  updateSchema: updateUserSchema,
-  idField: "id",
+```typescript
+export const tasksRouter = createCrudRouter({
+  table: tasks,
+  guard: (ctx, operation) => {
+    // 删除操作需要管理员权限
+    if (operation === "delete") {
+      return ctx.user.role === "admin";
+    }
+    // 其他操作需要登录
+    return !!ctx.user;
+  },
 });
 ```
 
----
-
-## 🔐 权限控制
-
-### 使用 tRPC Middleware
+### 使用 scope（行级过滤 RLS）
 
 ```typescript
-import { initTRPC, TRPCError } from "@trpc/server";
-
-const t = initTRPC.context<Context>().create();
+import { eq } from "drizzle-orm";
 
-// 创建受保护的 procedure
-const protectedProcedure = t.procedure.use(async ({ ctx, next }) => {
-  if (!ctx.user) {
-    throw new TRPCError({ code: "UNAUTHORIZED" });
-  }
-  return next({ ctx: { ...ctx, user: ctx.user } });
+export const tasksRouter = createCrudRouter({
+  table: tasks,
+  // 自动注入到所有查询的 WHERE 子句
+  scope: (ctx, table, operation) => {
+    return eq(table.tenantId, ctx.user.tenantId);
+  },
 });
+```
+
+### 使用 authorize（资源级检查 ABAC）
 
-// 在 createCrudRouter 中使用
+```typescript
 export const tasksRouter = createCrudRouter({
   table: tasks,
-  selectSchema: selectTaskSchema,
-  insertSchema: insertTaskSchema,
-  updateSchema: updateTaskSchema,
-  // 注意：当前版本不支持直接传入 procedure
-  // 需要在路由层面添加权限控制
+  // 在 get/update/delete 时，预取资源后调用
+  authorize: (ctx, resource, operation) => {
+    return resource.ownerId === ctx.user.id;
+  },
 });
-
-// 包装路由添加权限
-export const protectedTasksRouter = {
-  list: protectedProcedure.query(async ({ input, ctx }) => {
-    return tasksRouter.list(input, ctx);
-  }),
-  // ... 其他路由
-};
 ```
 
-### 行级权限控制
+### 使用 inject（强制注入字段）
 
 ```typescript
-// 在 createContext 中添加用户信息
-export const createContext = async ({ req }: { req: Request }) => {
-  const user = await getUserFromRequest(req);
-  return { db, user };
-};
-
-// 在查询中添加过滤条件
-const result = await db
-  .select()
-  .from(tasks)
-  .where(eq(tasks.userId, ctx.user.id));  // 只查询当前用户的任务
+export const tasksRouter = createCrudRouter({
+  table: tasks,
+  // 写入时强制覆盖字段（防止伪造）
+  inject: (ctx, operation) => ({
+    tenantId: ctx.user.tenantId,
+    ...(operation === "create" ? { createdBy: ctx.user.id } : { updatedBy: ctx.user.id }),
+  }),
+});
 ```
 
 ---
@@ -566,9 +613,6 @@ import { z } from "zod";
 // 创建基础 CRUD
 const tasksCrud = createCrudRouter({
   table: tasks,
-  selectSchema: selectTaskSchema,
-  insertSchema: insertTaskSchema,
-  updateSchema: updateTaskSchema,
 });
 
 // 使用 .procedures spread 并添加自定义路由
@@ -604,9 +648,6 @@ export const tasksRouter = router({
 ```typescript
 const tasksCrud = createCrudRouter({
   table: tasks,
-  selectSchema: selectTaskSchema,
-  insertSchema: insertTaskSchema,
-  updateSchema: updateTaskSchema,
 });
 
 // 直接嵌套到 appRouter
@@ -619,7 +660,7 @@ export const appRouter = router({
 
 ```typescript
 // 覆盖 list 路由，添加自定义过滤逻辑
-const tasksCrud = createCrudRouter({ ... });
+const tasksCrud = createCrudRouter({ table: tasks });
 
 export const tasksRouter = router({
   ...tasksCrud.procedures,
@@ -655,8 +696,6 @@ import { createCrudRouter } from "@wordrhyme/auto-crud-server";
 
 const tasksRouter = createCrudRouter({
   table: tasks,
-  insertSchema: insertTaskSchema,
-  updateSchema: updateTaskSchema,
 
   // 中间件：完全控制操作流程
   middleware: {
@@ -711,8 +750,6 @@ import {
 
 const tasksRouter = createCrudRouter({
   table: tasks,
-  insertSchema: insertTaskSchema,
-  updateSchema: updateTaskSchema,
 
   middleware: {
     // 简单副作用：只在操作后执行
@@ -811,24 +848,53 @@ app.listen(3000);
 ```typescript
 export const usersRouter = createCrudRouter({
   table: users,
-  selectSchema: selectUserSchema,
-  insertSchema: insertUserSchema,
-  updateSchema: updateUserSchema,
   idField: "userId",  // 使用自定义 ID 字段
 });
 ```
 
-### 自定义过滤器配置
+### 自定义排除字段
 
 ```typescript
-// src/config/data-table.ts
-export const filterVariants = {
-  text: ["eq", "ne", "like", "notLike"],
-  number: ["eq", "ne", "gt", "gte", "lt", "lte", "between"],
-  select: ["eq", "ne", "in", "notIn"],
-  date: ["eq", "ne", "gt", "gte", "lt", "lte", "between"],
-  boolean: ["eq"],
-};
+export const ordersRouter = createCrudRouter({
+  table: orders,
+  // 自动派生 schema 时排除这些字段
+  omitFields: ["id", "createdAt", "updatedAt", "internalCode"],
+});
+```
+
+### 软删除
+
+```typescript
+export const tasksRouter = createCrudRouter({
+  table: tasks,
+  // 方式 1：使用默认列名 'deletedAt'
+  softDelete: true,
+
+  // 方式 2：指定列名
+  softDelete: "deletedAt",
+
+  // 方式 3：完整配置（用于布尔字段）
+  softDelete: { column: "isDeleted", value: () => true },
+});
+```
+
+### 批量操作限制
+
+```typescript
+export const tasksRouter = createCrudRouter({
+  table: tasks,
+  maxBatchSize: 50,  // 默认 100
+});
+```
+
+### 列白名单
+
+```typescript
+export const tasksRouter = createCrudRouter({
+  table: tasks,
+  filterableColumns: ["title", "status", "priority"],  // 只允许这些列过滤
+  sortableColumns: ["title", "createdAt", "priority"], // 只允许这些列排序
+});
 ```
 
 ---

package/dist/index.cjs

@@ -25,6 +25,8 @@ let zod = require("zod");
 zod = __toESM(zod);
 let drizzle_orm = require("drizzle-orm");
 drizzle_orm = __toESM(drizzle_orm);
+let drizzle_zod = require("drizzle-zod");
+drizzle_zod = __toESM(drizzle_zod);
 let __trpc_server = require("@trpc/server");
 __trpc_server = __toESM(__trpc_server);
 let superjson = require("superjson");
@@ -399,6 +401,26 @@ const dataTableConfig = {
 	joinOperators: ["and", "or"]
 };
 
+//#endregion
+//#region src/lib/schema-utils.ts
+/**
+* 检查是否为 ZodObject 类型
+* 兼容 Zod v3 和 v4
+*
+* 实现策略：检查 schema 是否具有 ZodObject 特有的 .shape 属性
+* 这种方式比检查内部 _def 属性更稳定，因为不依赖 Zod 的内部实现细节
+*/
+function isZodObject(schema) {
+	return schema !== null && typeof schema === "object" && "shape" in schema && typeof schema.shape === "object" && schema.shape !== null;
+}
+/**
+* 非空对象验证器
+* 用于 updateSchema 的 refine，防止空更新
+*/
+function nonEmpty(value) {
+	return Object.keys(value).length > 0;
+}
+
 //#endregion
 //#region src/routers/_factory.ts
 function resolveSoftDelete(option) {
@@ -485,20 +507,46 @@ const listInputSchema = zod.z.object({
 	filters: zod.z.array(filterItemSchema).optional(),
 	joinOperator: zod.z.enum(["and", "or"]).default("and")
 });
+const DEFAULT_OMIT_FIELDS = [
+	"id",
+	"createdAt",
+	"updatedAt"
+];
+/**
+* 解析并派生 Schema
+* - 优先使用显式传入的 Schema
+* - 否则从 Drizzle table 自动派生
+*/
+function resolveSchemas(config) {
+	const { table, omitFields = DEFAULT_OMIT_FIELDS } = config;
+	let schema;
+	if (config.schema) {
+		if (!isZodObject(config.schema)) throw new Error("[createCrudRouter] schema must be a ZodObject (not ZodEffects or other types). If you're using .refine() or .transform(), please remove them from schema.");
+		schema = config.schema;
+	} else {
+		const rawSchema = (0, drizzle_zod.createInsertSchema)(table);
+		if (!isZodObject(rawSchema)) throw new Error("[createCrudRouter] drizzle-zod returned non-ZodObject schema. This may be due to table refinements. Please provide schema explicitly.");
+		const omitConfig = Object.fromEntries(omitFields.map((f) => [f, true]));
+		schema = rawSchema.omit(omitConfig);
+	}
+	let selectSchema;
+	if (config.selectSchema) selectSchema = config.selectSchema;
+	else if (config.schema) selectSchema = schema;
+	else selectSchema = (0, drizzle_zod.createSelectSchema)(table);
+	const updateSchema = config.updateSchema ?? schema.partial().refine(nonEmpty, { message: "Update payload cannot be empty. At least one field is required." });
+	return {
+		selectSchema,
+		schema,
+		updateSchema
+	};
+}
 function validateColumn(columnId, allowedColumns) {
 	if (!allowedColumns || allowedColumns.length === 0) return true;
 	return allowedColumns.includes(columnId);
 }
-/**
-* 创建 CRUD Router
-*
-* @typeParam TContext - 上下文类型（包含 db）
-* @typeParam TSelect - 查询返回类型（从 selectSchema 或 insertSchema 推断）
-* @typeParam TInsert - 创建输入类型（从 insertSchema 推断）
-* @typeParam TUpdate - 更新输入类型（从 updateSchema 推断）
-*/
 function createCrudRouter(config) {
-	const { table, insertSchema, updateSchema, idField = "id", filterableColumns, sortableColumns, maxBatchSize = 100, softDelete: softDeleteOption, middleware = {} } = config;
+	const { table, idField = "id", filterableColumns, sortableColumns, maxBatchSize = 100, softDelete: softDeleteOption, middleware = {} } = config;
+	const { schema, updateSchema } = resolveSchemas(config);
 	const resolved = resolveConfig(config);
 	const softDelete = resolveSoftDelete(softDeleteOption);
 	const m = middleware;
@@ -596,7 +644,7 @@ function createCrudRouter(config) {
 			});
 			return doGet();
 		}),
-		create: resolved.procedureFactory("create").input(insertSchema).mutation(async ({ ctx, input }) => {
+		create: resolved.procedureFactory("create").input(schema).mutation(async ({ ctx, input }) => {
 			await withGuard(ctx, "create");
 			const doCreate = async (inputData) => {
 				const injectData = resolved.getInject(ctx, "create");
@@ -703,7 +751,7 @@ function createCrudRouter(config) {
 			});
 			return doUpdateMany(input.data);
 		}),
-		upsert: resolved.procedureFactory("upsert").input(insertSchema).mutation(async ({ ctx, input }) => {
+		upsert: resolved.procedureFactory("upsert").input(schema).mutation(async ({ ctx, input }) => {
 			await withGuard(ctx, "upsert");
 			const doUpsert = async (inputData) => {
 				const inputId = inputData[idField];

package/dist/index.d.cts

@@ -1,8 +1,8 @@
+import { z } from "zod";
+import { InferInsertModel, InferSelectModel, SQL } from "drizzle-orm";
+import { PgTable } from "drizzle-orm/pg-core";
 import * as _trpc_server2 from "@trpc/server";
 import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
-import { SQL } from "drizzle-orm";
-import { PgTable } from "drizzle-orm/pg-core";
-import { z } from "zod";
 
 //#region src/trpc.d.ts
 /**
@@ -23,6 +23,11 @@ declare const publicProcedure: _trpc_server2.TRPCProcedureBuilder<Context, objec
 //#region src/types/config.d.ts
 type CrudOperation = "list" | "get" | "create" | "update" | "delete" | "deleteMany" | "updateMany" | "upsert";
 type WriteOperation = "create" | "update";
+/**
+ * 表字段键类型提取
+ * 用于 omitFields 的强类型支持
+ */
+type TableColumnKeys<T extends PgTable> = keyof T["_"]["columns"];
 type AnyProcedure = any;
 interface SoftDeleteConfig {
   /** 软删除标记列名 */
@@ -270,13 +275,37 @@ type ProcedureConfig = AnyProcedure | ProcedureMap | ProcedureFactory;
  *   authorize: (ctx, resource) => resource.ownerId === ctx.user.id,
  * })
  */
-interface CrudRouterConfig<TContext = unknown, TSelect = unknown, TInsert = unknown, TUpdate = unknown> {
+interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown, TSelect = unknown, TInsert = unknown, TUpdate = unknown> {
   /** Drizzle 表定义 */
-  table: PgTable;
-  /** 创建输入 Schema */
-  insertSchema: z.ZodType<TInsert>;
-  /** 更新输入 Schema */
-  updateSchema: z.ZodType<TUpdate>;
+  table: TTable;
+  /**
+   * 主 Schema（用于 create/upsert 输入验证）
+   * - 如果不传，自动从 table 派生并排除 omitFields
+   * - updateSchema 默认为 schema.partial().refine(nonEmpty)
+   *
+   * @example
+   * // 自动派生
+   * createCrudRouter({ table: tasks })
+   *
+   * // 显式传入
+   * createCrudRouter({ table: tasks, schema: taskSchema })
+   */
+  schema?: z.ZodType<TInsert>;
+  /**
+   * 更新输入 Schema（可选）
+   * - 如果不传，自动从 schema.partial() 派生
+   * - 传入时覆盖自动派生
+   *
+   * @example
+   * createCrudRouter({
+   *   table: tasks,
+   *   schema: taskSchema,
+   *   updateSchema: customUpdateSchema,  // 覆盖自动派生
+   * })
+   */
+  updateSchema?: z.ZodType<TUpdate>;
+  /** 查询返回 Schema */
+  selectSchema?: z.ZodType<TSelect>;
   /**
    * Procedure 配置（统一字段）
    *
@@ -320,8 +349,11 @@ interface CrudRouterConfig<TContext = unknown, TSelect = unknown, TInsert = unkn
    * authorize: (ctx, resource, op) => resource.ownerId === ctx.user.id
    */
   authorize?: (ctx: TContext, resource: TSelect, operation: CrudOperation) => boolean | Promise<boolean>;
-  /** 查询返回 Schema */
-  selectSchema?: z.ZodType<TSelect>;
+  /**
+   * 要从 schema 排除的字段（自动派生时使用）
+   * @default ["id", "createdAt", "updatedAt"]
+   */
+  omitFields?: TableColumnKeys<TTable>[];
   /** ID 字段名，默认 "id" */
   idField?: string;
   /** 可过滤的列白名单 */
@@ -390,17 +422,33 @@ interface CrudProcedures<TSelect, TInsert, TUpdate> {
 }
 //#endregion
 //#region src/routers/_factory.d.ts
+/**
+ * createCrudRouter 返回类型
+ */
+type CrudRouterReturn<TSelect, TInsert, TUpdate> = ReturnType<typeof router> & {
+  procedures: CrudProcedures<TSelect, TInsert, TUpdate>;
+};
 /**
  * 创建 CRUD Router
  *
  * @typeParam TContext - 上下文类型（包含 db）
- * @typeParam TSelect - 查询返回类型（从 selectSchema 或 insertSchema 推断）
- * @typeParam TInsert - 创建输入类型（从 insertSchema 推断）
- * @typeParam TUpdate - 更新输入类型（从 updateSchema 推断）
+ * @typeParam TSelect - 查询返回类型
+ * @typeParam TInsert - 创建输入类型（从 schema 推断）
+ * @typeParam TUpdate - 更新输入类型（从 updateSchema 或 schema.partial() 推断）
  */
-declare function createCrudRouter<TContext = unknown, TSelect = unknown, TInsert = unknown, TUpdate = unknown>(config: CrudRouterConfig<TContext, TSelect, TInsert, TUpdate>): ReturnType<typeof router> & {
-  procedures: CrudProcedures<TSelect, TInsert, TUpdate>;
-};
+declare function createCrudRouter<TTable extends PgTable, TContext, TSelect, TInsert, TUpdate>(config: CrudRouterConfig<TTable, TContext, TSelect, TInsert, TUpdate> & {
+  schema: z.ZodType<TInsert>;
+  updateSchema: z.ZodType<TUpdate>;
+}): CrudRouterReturn<TSelect, TInsert, TUpdate>;
+declare function createCrudRouter<TTable extends PgTable, TContext = unknown>(config: Omit<CrudRouterConfig<TTable, TContext>, "schema" | "updateSchema"> & {
+  schema?: undefined;
+  updateSchema?: undefined;
+}): CrudRouterReturn<InferSelectModel<TTable>, InferInsertModel<TTable>, Partial<InferInsertModel<TTable>>>;
+declare function createCrudRouter<TTable extends PgTable, TContext, TInsert>(config: Omit<CrudRouterConfig<TTable, TContext, unknown, TInsert, unknown>, "updateSchema"> & {
+  schema: z.ZodType<TInsert>;
+  updateSchema?: undefined;
+}): CrudRouterReturn<unknown, TInsert, Partial<TInsert>>;
+declare function createCrudRouter<TTable extends PgTable, TContext = unknown, TSelect = unknown, TInsert = unknown, TUpdate = unknown>(config: CrudRouterConfig<TTable, TContext, TSelect, TInsert, TUpdate>): CrudRouterReturn<TSelect, TInsert, TUpdate>;
 //#endregion
 //#region src/lib/middleware-helpers.d.ts
 /**

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { z } from "zod";
-import { SQL } from "drizzle-orm";
+import { InferInsertModel, InferSelectModel, SQL } from "drizzle-orm";
 import * as _trpc_server2 from "@trpc/server";
 import superjson from "superjson";
-import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import { PgTable } from "drizzle-orm/pg-core";
+import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 
 //#region src/trpc.d.ts
 /**
@@ -24,6 +24,11 @@ declare const publicProcedure: _trpc_server2.TRPCProcedureBuilder<Context, objec
 //#region src/types/config.d.ts
 type CrudOperation = "list" | "get" | "create" | "update" | "delete" | "deleteMany" | "updateMany" | "upsert";
 type WriteOperation = "create" | "update";
+/**
+ * 表字段键类型提取
+ * 用于 omitFields 的强类型支持
+ */
+type TableColumnKeys<T extends PgTable> = keyof T["_"]["columns"];
 type AnyProcedure = any;
 interface SoftDeleteConfig {
   /** 软删除标记列名 */
@@ -271,13 +276,37 @@ type ProcedureConfig = AnyProcedure | ProcedureMap | ProcedureFactory;
  *   authorize: (ctx, resource) => resource.ownerId === ctx.user.id,
  * })
  */
-interface CrudRouterConfig<TContext = unknown, TSelect = unknown, TInsert = unknown, TUpdate = unknown> {
+interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown, TSelect = unknown, TInsert = unknown, TUpdate = unknown> {
   /** Drizzle 表定义 */
-  table: PgTable;
-  /** 创建输入 Schema */
-  insertSchema: z.ZodType<TInsert>;
-  /** 更新输入 Schema */
-  updateSchema: z.ZodType<TUpdate>;
+  table: TTable;
+  /**
+   * 主 Schema（用于 create/upsert 输入验证）
+   * - 如果不传，自动从 table 派生并排除 omitFields
+   * - updateSchema 默认为 schema.partial().refine(nonEmpty)
+   *
+   * @example
+   * // 自动派生
+   * createCrudRouter({ table: tasks })
+   *
+   * // 显式传入
+   * createCrudRouter({ table: tasks, schema: taskSchema })
+   */
+  schema?: z.ZodType<TInsert>;
+  /**
+   * 更新输入 Schema（可选）
+   * - 如果不传，自动从 schema.partial() 派生
+   * - 传入时覆盖自动派生
+   *
+   * @example
+   * createCrudRouter({
+   *   table: tasks,
+   *   schema: taskSchema,
+   *   updateSchema: customUpdateSchema,  // 覆盖自动派生
+   * })
+   */
+  updateSchema?: z.ZodType<TUpdate>;
+  /** 查询返回 Schema */
+  selectSchema?: z.ZodType<TSelect>;
   /**
    * Procedure 配置（统一字段）
    *
@@ -321,8 +350,11 @@ interface CrudRouterConfig<TContext = unknown, TSelect = unknown, TInsert = unkn
    * authorize: (ctx, resource, op) => resource.ownerId === ctx.user.id
    */
   authorize?: (ctx: TContext, resource: TSelect, operation: CrudOperation) => boolean | Promise<boolean>;
-  /** 查询返回 Schema */
-  selectSchema?: z.ZodType<TSelect>;
+  /**
+   * 要从 schema 排除的字段（自动派生时使用）
+   * @default ["id", "createdAt", "updatedAt"]
+   */
+  omitFields?: TableColumnKeys<TTable>[];
   /** ID 字段名，默认 "id" */
   idField?: string;
   /** 可过滤的列白名单 */
@@ -391,17 +423,33 @@ interface CrudProcedures<TSelect, TInsert, TUpdate> {
 }
 //#endregion
 //#region src/routers/_factory.d.ts
+/**
+ * createCrudRouter 返回类型
+ */
+type CrudRouterReturn<TSelect, TInsert, TUpdate> = ReturnType<typeof router> & {
+  procedures: CrudProcedures<TSelect, TInsert, TUpdate>;
+};
 /**
  * 创建 CRUD Router
  *
  * @typeParam TContext - 上下文类型（包含 db）
- * @typeParam TSelect - 查询返回类型（从 selectSchema 或 insertSchema 推断）
- * @typeParam TInsert - 创建输入类型（从 insertSchema 推断）
- * @typeParam TUpdate - 更新输入类型（从 updateSchema 推断）
+ * @typeParam TSelect - 查询返回类型
+ * @typeParam TInsert - 创建输入类型（从 schema 推断）
+ * @typeParam TUpdate - 更新输入类型（从 updateSchema 或 schema.partial() 推断）
  */
-declare function createCrudRouter<TContext = unknown, TSelect = unknown, TInsert = unknown, TUpdate = unknown>(config: CrudRouterConfig<TContext, TSelect, TInsert, TUpdate>): ReturnType<typeof router> & {
-  procedures: CrudProcedures<TSelect, TInsert, TUpdate>;
-};
+declare function createCrudRouter<TTable extends PgTable, TContext, TSelect, TInsert, TUpdate>(config: CrudRouterConfig<TTable, TContext, TSelect, TInsert, TUpdate> & {
+  schema: z.ZodType<TInsert>;
+  updateSchema: z.ZodType<TUpdate>;
+}): CrudRouterReturn<TSelect, TInsert, TUpdate>;
+declare function createCrudRouter<TTable extends PgTable, TContext = unknown>(config: Omit<CrudRouterConfig<TTable, TContext>, "schema" | "updateSchema"> & {
+  schema?: undefined;
+  updateSchema?: undefined;
+}): CrudRouterReturn<InferSelectModel<TTable>, InferInsertModel<TTable>, Partial<InferInsertModel<TTable>>>;
+declare function createCrudRouter<TTable extends PgTable, TContext, TInsert>(config: Omit<CrudRouterConfig<TTable, TContext, unknown, TInsert, unknown>, "updateSchema"> & {
+  schema: z.ZodType<TInsert>;
+  updateSchema?: undefined;
+}): CrudRouterReturn<unknown, TInsert, Partial<TInsert>>;
+declare function createCrudRouter<TTable extends PgTable, TContext = unknown, TSelect = unknown, TInsert = unknown, TUpdate = unknown>(config: CrudRouterConfig<TTable, TContext, TSelect, TInsert, TUpdate>): CrudRouterReturn<TSelect, TInsert, TUpdate>;
 //#endregion
 //#region src/lib/middleware-helpers.d.ts
 /**

package/dist/index.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { and, asc, desc, eq, gt, gte, ilike, inArray, isNull, lt, lte, ne, not, notIlike, notInArray, or, sql } from "drizzle-orm";
+import { createInsertSchema, createSelectSchema } from "drizzle-zod";
 import { TRPCError, initTRPC } from "@trpc/server";
 import superjson from "superjson";
 import { addDays, endOfDay, startOfDay } from "date-fns";
@@ -371,6 +372,26 @@ const dataTableConfig = {
 	joinOperators: ["and", "or"]
 };
 
+//#endregion
+//#region src/lib/schema-utils.ts
+/**
+* 检查是否为 ZodObject 类型
+* 兼容 Zod v3 和 v4
+*
+* 实现策略：检查 schema 是否具有 ZodObject 特有的 .shape 属性
+* 这种方式比检查内部 _def 属性更稳定，因为不依赖 Zod 的内部实现细节
+*/
+function isZodObject(schema) {
+	return schema !== null && typeof schema === "object" && "shape" in schema && typeof schema.shape === "object" && schema.shape !== null;
+}
+/**
+* 非空对象验证器
+* 用于 updateSchema 的 refine，防止空更新
+*/
+function nonEmpty(value) {
+	return Object.keys(value).length > 0;
+}
+
 //#endregion
 //#region src/routers/_factory.ts
 function resolveSoftDelete(option) {
@@ -457,20 +478,46 @@ const listInputSchema = z.object({
 	filters: z.array(filterItemSchema).optional(),
 	joinOperator: z.enum(["and", "or"]).default("and")
 });
+const DEFAULT_OMIT_FIELDS = [
+	"id",
+	"createdAt",
+	"updatedAt"
+];
+/**
+* 解析并派生 Schema
+* - 优先使用显式传入的 Schema
+* - 否则从 Drizzle table 自动派生
+*/
+function resolveSchemas(config) {
+	const { table, omitFields = DEFAULT_OMIT_FIELDS } = config;
+	let schema;
+	if (config.schema) {
+		if (!isZodObject(config.schema)) throw new Error("[createCrudRouter] schema must be a ZodObject (not ZodEffects or other types). If you're using .refine() or .transform(), please remove them from schema.");
+		schema = config.schema;
+	} else {
+		const rawSchema = createInsertSchema(table);
+		if (!isZodObject(rawSchema)) throw new Error("[createCrudRouter] drizzle-zod returned non-ZodObject schema. This may be due to table refinements. Please provide schema explicitly.");
+		const omitConfig = Object.fromEntries(omitFields.map((f) => [f, true]));
+		schema = rawSchema.omit(omitConfig);
+	}
+	let selectSchema;
+	if (config.selectSchema) selectSchema = config.selectSchema;
+	else if (config.schema) selectSchema = schema;
+	else selectSchema = createSelectSchema(table);
+	const updateSchema = config.updateSchema ?? schema.partial().refine(nonEmpty, { message: "Update payload cannot be empty. At least one field is required." });
+	return {
+		selectSchema,
+		schema,
+		updateSchema
+	};
+}
 function validateColumn(columnId, allowedColumns) {
 	if (!allowedColumns || allowedColumns.length === 0) return true;
 	return allowedColumns.includes(columnId);
 }
-/**
-* 创建 CRUD Router
-*
-* @typeParam TContext - 上下文类型（包含 db）
-* @typeParam TSelect - 查询返回类型（从 selectSchema 或 insertSchema 推断）
-* @typeParam TInsert - 创建输入类型（从 insertSchema 推断）
-* @typeParam TUpdate - 更新输入类型（从 updateSchema 推断）
-*/
 function createCrudRouter(config) {
-	const { table, insertSchema, updateSchema, idField = "id", filterableColumns, sortableColumns, maxBatchSize = 100, softDelete: softDeleteOption, middleware = {} } = config;
+	const { table, idField = "id", filterableColumns, sortableColumns, maxBatchSize = 100, softDelete: softDeleteOption, middleware = {} } = config;
+	const { schema, updateSchema } = resolveSchemas(config);
 	const resolved = resolveConfig(config);
 	const softDelete = resolveSoftDelete(softDeleteOption);
 	const m = middleware;
@@ -568,7 +615,7 @@ function createCrudRouter(config) {
 			});
 			return doGet();
 		}),
-		create: resolved.procedureFactory("create").input(insertSchema).mutation(async ({ ctx, input }) => {
+		create: resolved.procedureFactory("create").input(schema).mutation(async ({ ctx, input }) => {
 			await withGuard(ctx, "create");
 			const doCreate = async (inputData) => {
 				const injectData = resolved.getInject(ctx, "create");
@@ -675,7 +722,7 @@ function createCrudRouter(config) {
 			});
 			return doUpdateMany(input.data);
 		}),
-		upsert: resolved.procedureFactory("upsert").input(insertSchema).mutation(async ({ ctx, input }) => {
+		upsert: resolved.procedureFactory("upsert").input(schema).mutation(async ({ ctx, input }) => {
 			await withGuard(ctx, "upsert");
 			const doUpsert = async (inputData) => {
 				const inputId = inputData[idField];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wordrhyme/auto-crud-server",
   "type": "module",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "tRPC server utilities for auto-crud - automatic CRUD routers for Drizzle ORM",
   "author": "wordrhyme",
   "license": "MIT",
@@ -50,8 +50,8 @@
     "@internal/eslint-config": "0.3.0",
     "@internal/tsconfig": "0.1.0",
     "@internal/prettier-config": "0.0.1",
-    "@internal/vitest-config": "0.1.0",
-    "@internal/tsdown-config": "0.1.0"
+    "@internal/tsdown-config": "0.1.0",
+    "@internal/vitest-config": "0.1.0"
   },
   "prettier": "@internal/prettier-config",
   "scripts": {