@pylonts/dsl 1.1.5 → 1.1.6

package/docs/dto.md

@@ -1,67 +1,74 @@
-# 定义 DTO（四种方向）
-
-DTO 描述接口出入参。方向决定可选性规则，由各方向工厂设置；**规则统一只在 `field.optional === undefined` 时生效**（作者已显式设置的跳过）：
-
-| 构建器 | 方向 | 可选性规则 |
-|---|---|---|
-| `buildInput` | input | 按 DB 列规则：主键 → 必填；可空（未写 `optional` 或 `optional: true`）/ 有默认 → 可选；`optional: false` 无默认 → 必填 |
-| `buildOutput` | output | 不设置（保持字段构建器/作者设置） |
-| `buildQuery` | query | 全部可选 |
-| `buildPk` | pk | 主键字段必填，其他字段可选 |
-
-## 从表提取字段
-
-```ts
-import { buildInput, buildQuery, dtoField, from } from '@pylonts/dsl';
-
-// 输入：新增订单
-buildInput('OrderAddRequest', { ...from(order, [order.columns.mer_id, order.columns.amount]) });
-
-// 输出：订单行
-buildOutput('OrderRow', from(order, [order.columns.id, order.columns.order_no]));
-
-// 查询：分页 + 过滤（query 字段恒为可选，.op() 声明比较操作符）
-buildQuery('OrderPageQuery', {
-  keyword: dtoField(stringField({ maxLength: 32 })).setOperator('like'),
-  ...from(order, [order.columns.mer_id]),
-});
-
-// 主键：按 id 取详情
-buildPk('OrderDetailRequest', from(order, [order.columns.id]));
-```
-
-`from(table, fields)` 提取表字段包装为 DTO 字段，字段实例与表共享，`name/schema` 保持指向表。**DTO 字段名转 camelCase**（`mer_id` → `merId`），与 DB 列名（snake_case）分离。`from()` 本身不做任何可选性推断——推断在各方向工厂。
-
-## 独立字段
-
-不来自表的内联字段直接用 `dtoField(...)` 包装任意字段构建器，可加 `pattern`、`optional`、`operator`、`default`。
-
-```ts
-dtoField(stringField({ maxLength: 32 })).setOperator('like')
-dtoField(intField()).setDefault(0)        // TypeBox default 注解
-```
-
-## 默认值
-
-- `setDefault(v)` 设 DTO 层默认值，渲染为 TypeBox `default:` 注解（`Type.String({ default: 'PENDING' })`、`Type.Enum(OrderStatus, { default: OrderStatus.PENDING })`）。
-- 枚举默认值必须是该枚举的成员值（value），渲染时解析为成员引用；非成员值直接报错。
-- 未显式设置时，fallback 到字段构建器的 `default`（DB 默认值，string），`from()` 提取的字段自动带出。
-
-## 继承基础 schema
-
-```ts
-buildQuery('OrderPageQuery', { ... })
-  .include({ from: '@pylonts/core', name: 'PageRequest' });   // 渲染 Type.Intersect([PageRequest, ...])
-```
-
-## 关键语义
-
-- **字段两层名**：`DtoField.name` 是接口字段名（DTO map key 反写）；`field.name` 是数据库列名（表反写）。
-- **可选性优先级**：DTO 层 `optional` 优先于字段层；query 方向所有字段强制可选。
-- **HTTP 传 string**：bigint / decimal / date / time 在接口层渲染为 `Type.String()`，保证精度与序列化语义。
-
-## 文件组织
-
-- `dto_schema/{module}/*.dto.ts`：DTO 源文件，一个文件可导出多个 DtoMessage；`module` = `project.config.ts` 的 `apps.name`，另加 `common/` 放跨 app 共享 DTO。
-- `pylonts gen dto` 按 module 逐个扫描：`dto_schema/{module}/*.dto.ts` → 生成 `dto/{module}/{Name}.dto.ts`。
+# 定义 DTO（四种方向）
+
+DTO 描述接口出入参。方向决定可选性规则，由各方向工厂设置；**规则统一只在 `field.optional === undefined` 时生效**（作者已显式设置的跳过）：
+
+| 构建器 | 方向 | 可选性规则 |
+|---|---|---|
+| `buildInput` | input | 按 DB 列规则：主键 → 必填；可空（未写 `optional` 或 `optional: true`）/ 有默认 → 可选；`optional: false` 无默认 → 必填 |
+| `buildOutput` | output | 不设置（保持字段构建器/作者设置） |
+| `buildQuery` | query | 全部可选 |
+| `buildPk` | pk | 主键字段必填，其他字段可选 |
+
+## 从字段集合投影
+
+`from(source, fields)` 接受两类字段集合源：**表**（`TableSchema`）或**第三方方法消息**（`ThirdMethodSchema`，见 [third-service.md](./third-service.md)），投影字段包装为 DTO 字段，字段实例与源共享，`name/schema` 保持指向源。
+
+```ts
+import { buildInput, buildQuery, dtoField, from } from '@pylonts/dsl';
+
+// 输入：新增订单
+buildInput('OrderAddRequest', { ...from(order, [order.columns.mer_id, order.columns.amount]) });
+
+// 输出：订单行
+buildOutput('OrderRow', from(order, [order.columns.id, order.columns.order_no]));
+
+// 查询：分页 + 过滤（query 字段恒为可选，.op() 声明比较操作符）
+buildQuery('OrderPageQuery', {
+  keyword: dtoField(stringField({ maxLength: 32 })).setOperator('like'),
+  ...from(order, [order.columns.mer_id]),
+});
+
+// 主键：按 id 取详情
+buildPk('OrderDetailRequest', from(order, [order.columns.id]));
+
+// 转发：透传第三方方法消息（wire-format 字段名保持协议原样，不转 camelCase）
+buildOutput('BalanceResult', from(queryBalance.results, [queryBalance.results.fields.balance]));
+```
+
+- **表源**：DTO 字段名转 camelCase（`mer_id` → `merId`），与 DB 列名（snake_case）分离。
+- **第三方方法源**：字段名即线格式协议名（`out_trade_no`、`appId`），保持不变。
+- `from()` 本身不做任何可选性推断——推断在各方向工厂，且按字段的 schema 判断：共享实体列按列规则推断（Rule A），wire 自有字段保留声明值。
+
+## 独立字段
+
+不来自表的内联字段直接用 `dtoField(...)` 包装任意字段构建器，可加 `pattern`、`optional`、`operator`、`default`。
+
+```ts
+dtoField(stringField({ maxLength: 32 })).setOperator('like')
+dtoField(intField()).setDefault(0)        // TypeBox default 注解
+```
+
+## 默认值
+
+- `setDefault(v)` 设 DTO 层默认值，渲染为 TypeBox `default:` 注解（`Type.String({ default: 'PENDING' })`、`Type.Enum(OrderStatus, { default: OrderStatus.PENDING })`）。
+- 枚举默认值必须是该枚举的成员值（value），渲染时解析为成员引用；非成员值直接报错。
+- 未显式设置时，fallback 到字段构建器的 `default`（DB 默认值，string），`from()` 提取的字段自动带出。
+
+## 继承基础 schema
+
+```ts
+buildQuery('OrderPageQuery', { ... })
+  .include({ from: '@pylonts/core', name: 'PageRequest' });   // 渲染 Type.Intersect([PageRequest, ...])
+```
+
+## 关键语义
+
+- **字段两层名**：`DtoField.name` 是接口字段名（DTO map key 反写）；`field.name` 是数据库列名（表反写）。
+- **可选性优先级**：DTO 层 `optional` 优先于字段层；query 方向所有字段强制可选。
+- **HTTP 传 string**：bigint / decimal / date / time 在接口层渲染为 `Type.String()`，保证精度与序列化语义。
+
+## 文件组织
+
+- `dto_schema/{module}/*.dto.ts`：DTO 源文件，一个文件可导出多个 DtoMessage；`module` = `project.config.ts` 的 `apps.name`，另加 `common/` 放跨 app 共享 DTO。
+- `pylonts gen dto` 按 module 逐个扫描：`dto_schema/{module}/*.dto.ts` → 生成 `dto/{module}/{Name}.dto.ts`。
 - 枚举字段引用 `enums/` 下生成的枚举源文件，DTO 文件通过 `../../enums/{JsName}.enum` 导入。

package/docs/third-service.md

@@ -0,0 +1,122 @@
+# 定义第三方服务（ThirdServiceSchema）
+
+第三方服务适配器契约（如微信支付 tenpay、短信、文件存储）。`defineThirdService` 声明适配器类契约：构造函数配置 + 方法列表。
+
+```ts
+import { defineFieldRule, defineThirdService } from '@pylonts/dsl';
+import { wx } from '../project.config';
+
+const balance = intField({ optional: false, label: '余额（分）' });
+
+// Rule = name + two named ends. One rule per semantic (defining fenYuan twice throws).
+const fenYuan = defineFieldRule({
+  name: 'fenYuan',
+  ends: { fen: {}, yuan: {} },
+});
+
+export const wxPayService = defineThirdService({
+  schema: wx,
+  name: 'WxPayService',
+  description: '微信支付服务（tenpay APIv2）',
+  methods: [
+    {
+      name: 'queryBalance',
+      args: { name: 'QueryBalanceArgs', fields: { openid: user.columns.openid } },
+      results: {
+        name: 'QueryBalanceResult',
+        fields: {
+          balance,
+        },
+        refs: [
+          { field: balance, ref: order.columns.amount, convert: { rule: fenYuan, end: fenYuan.ends.fen } },
+        ],
+      },
+    },
+  ],
+});
+```
+
+## ThirdMethodSchema：方法的 args / results
+
+每个方法的 `args` / `results` 各是一个 `ThirdMethodSchema`——**字段集合容器**，与 `TableSchema.columns` 同构，但字段是线格式（wire-format）字段。结构上它是 `DtoMessage` 的字段集合对应物。
+
+| 属性 | 说明 |
+|------|------|
+| `name` | 消息名（如 `QueryBalanceResult`），生成产物的类型名 |
+| `fields` | 线格式字段 map，key 即协议字段名（`out_trade_no`、`appId` 原样保留） |
+| `refs` | 同事实变体链接（见下） |
+| `schema` | 反向指针，指向所属 method（构建器写入） |
+
+`defineThirdMethod` 写回自有字段的 `name/schema`（与 `defineTable` 同一惯例）。
+
+## 字段与本地实体的关系
+
+两个通道，按"同一事实"的表达方式选择：
+
+### 同一概念且类型一致 → 共享实例
+
+直接复用本地实体列实例，类型/语义/默认值自动跟随实体，DTO 投影继承全部语义（与 `from(table)` 完全同构）：
+
+```ts
+args: {
+  name: 'QueryBalanceArgs',
+  fields: {
+    openid: user.columns.openid,   // 共享实例，schema 仍指向 t_user
+  },
+},
+```
+
+前提是线格式字段名与实体列名一致（协议恰好也叫 `openid`）。名字不同时（协议叫 `userId` 而列叫 `user_id`），不共享实例，走 refs。
+
+### 同一概念但类型/格式不同（变体）→ 自有字段 + refs
+
+声明自有线格式类型，再挂一条 `refs` 链接指向实体列。规则先定义一次：
+
+```ts
+// 规则 = 名称 + 两端（具名 map）。同一语义全局只允许一条（重复定义抛错）。
+const fenYuan = defineFieldRule({
+  name: 'fenYuan',
+  ends: { fen: {}, yuan: {} },
+});
+
+const totalFee = intField({ optional: false, label: '金额（分）' });
+
+fields: {
+  total_fee: totalFee,
+},
+refs: [
+  {
+    field: totalFee,              // 本地定义（本消息的 wire 字段）
+    ref: order.columns.amount,    // 其他定义（表列或其他消息字段）
+    convert: { rule: fenYuan, end: fenYuan.ends.fen },
+  },
+],
+```
+
+- `field`：本消息的 wire 字段实例（构建器校验必须是本消息字段）
+- `ref`：其他 schema 的字段实例（表列或其他消息字段，构建器校验不得是本消息字段）
+- `convert`（可选）：绑定一条规则到这对字段——仅当两字段需要转化时声明，纯关联不需要
+  - `rule`：`FieldRuleSchema`——规则 = 名称 + 两端（如 `fenYuan` 的 `fen`/`yuan` 端）。加密/脱敏/换算统一为规则名维度，`defineFieldRule` 按名称查重，同一语义只声明一次
+  - `end`：`field` 所站的端——引用 `rule.ends.fen` / `rule.ends.yuan`（具名引用，无索引魔法；构建器按实例校验），`ref` 自动占另一端——不再重复声明 from/to
+  - 生成器将来为这对字段产出两个方向的函数（field 端→ref 端 与 ref 端→field 端）
+
+## 嵌套字段
+
+线格式字段支持递归嵌套，用 `arrayField` / `objectField`（Field 体系，非表列）：
+
+```ts
+fields: {
+  payer_info: objectField({
+    properties: {
+      openid: stringField({ optional: false, maxLength: 64 }),
+    },
+  }),
+  coupons: arrayField({ items: intField() }),
+},
+```
+
+表列不支持这两个类型（`buildCreateTableSql` 直接报错）。
+
+## DTO 转发
+
+DTO 通过 `from(thirdMethod, fields)` 投影第三方消息字段，构建转发引用（透传不复制）。线格式字段名保持协议原样，不做 camelCase。见 [dto.md](./dto.md#从字段集合投影)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonts/dsl",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Schema definition DSL with drivers: MySQL DDL, TS enum, TypeBox schema codegen.",
   "type": "module",
   "main": "src/index.ts",
@@ -24,6 +24,9 @@
   ],
   "author": "",
   "license": "MIT",
+  "dependencies": {
+    "@pylonts/core": "file:../pylon"
+  },
   "devDependencies": {
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"

package/src/controller.ts

@@ -0,0 +1,40 @@
+import { SchemaBase } from './dsl.js';
+import { FrontAppSchema } from './project.js';
+import type { EndpointSchema } from './endpoint.js';
+
+/** A backend RPC controller. Strong constraints:
+ *  - a backend module maps 1:1 to a frontend app (they are peers);
+ *  - a controller serves exactly one frontend app — no cross-module calls. */
+export interface ControllerSchema extends SchemaBase {
+  type: 'controller';
+  /** The frontend app this controller serves (shared instance from project.config). */
+  app: FrontAppSchema;
+  /** RPC methods exposed by this controller. */
+  methods: ControllerMethodSchema[];
+}
+
+export function defineController(options: {
+  name: string;
+  app: FrontAppSchema;
+  /** Method declarations: type/schema are injected by this builder. */
+  methods: Array<Omit<ControllerMethodSchema, 'type' | 'schema'>>;
+  description?: string;
+}): ControllerSchema {
+  const schema: ControllerSchema = {
+    type: 'controller',
+    name: options.name,
+    description: options.description,
+    app: options.app,
+    methods: [],
+  };
+  schema.methods = options.methods.map((method) => ({ type: 'method', schema, ...method }));
+  return schema;
+}
+
+/** An RPC method exposed by a controller. */
+export interface ControllerMethodSchema extends SchemaBase {
+  type: 'method';
+  schema: ControllerSchema;
+  /** Shared API signature — same instance the page-side provider references. */
+  signature: EndpointSchema;
+}

package/src/convert.ts

@@ -1,16 +1,43 @@
-import type { SchemaBase } from './dsl.js';
-import type { FrontAppSchema } from './project.js';
-
-/** Declares post-call result → page data field mapping.
- *  Driver generates per-item transform (e.g. .map()) before setData. */
-export interface ConvertSchema extends SchemaBase {
-  type: 'convert';
-  /** The frontend app this convert belongs to (shared instance from project.config). */
-  app: FrontAppSchema;
-  /** { targetField: sourceField } — renames or copies fields from call result. */
-  fields: Record<string, string>;
-}
-
-export function defineConvert(name: string, app: FrontAppSchema, fields: Record<string, string>): ConvertSchema {
-  return { name, type: 'convert', app, fields };
+import type { SchemaBase } from './dsl.js';
+import type { DtoMessage } from './dto.js';
+import type { TableSchema } from './db.js';
+import type { ThirdMethodSchema } from './third-service.js';
+import type { FrontAppSchema } from './project.js';
+
+// Schema-collection integration: multiple source collections combine into
+// one target collection (e.g. two entity tables into one dto, or entity
+// columns plus a dto into one third-party wire message).
+
+/** A source/target collection of a convert — dto, entity or third-party message. */
+export type ConvertSourceSchema = DtoMessage | TableSchema | ThirdMethodSchema;
+
+/** Declares a multi-source → single-target schema integration. */
+export interface ConvertSchema extends SchemaBase {
+  type: 'convert';
+  /** The app (module) this convert belongs to — its artifact lands in modules/{app}/convert/. */
+  app: FrontAppSchema;
+  /** Source schemas — one or more, mixed dimensions. */
+  sources: ConvertSourceSchema[];
+  /** Target schema — the single integrated collection. */
+  target: ConvertSourceSchema;
+}
+
+export function defineConvert(options: {
+  name: string;
+  app: FrontAppSchema;
+  sources: ConvertSourceSchema[];
+  target: ConvertSourceSchema;
+  description?: string;
+}): ConvertSchema {
+  if (options.sources.length === 0) {
+    throw new Error(`convert '${options.name}': sources must not be empty`);
+  }
+  return {
+    type: 'convert',
+    name: options.name,
+    description: options.description,
+    app: options.app,
+    sources: options.sources,
+    target: options.target,
+  };
 }

package/src/curd.ts

@@ -1,94 +1,99 @@
-import { SchemaBase, Field, Operator } from './dsl.js';
-import { TableSchema } from './db.js';
-import { FrontAppSchema } from './project.js';
-import { ActionSchema } from './action.js';
-
-// Admin-only CRUD page standard: binds one entity table to a frontend admin
-// app, describing everything needed to generate the list page plus optional
-// add/update/detail pages. Field-level columns are plain Field instances
-// (table fields, cross-table refs allowed) — DTOs are derived by the generator,
-// the schema itself never references DtoMessage.
-
-/** Mode of an action page: modal dialog or standalone route. */
-export type ActionPageMode = 'modal' | 'route';
-
-/** One CRUD action page (add / update / detail). */
-export interface ActionPage {
-  mode: ActionPageMode;
-  /** For add/update: when true, render as modal on list page; when false/undefined, render as standalone route page. */
-  modal?: boolean;
-  /** Fields rendered on this page. Required, non-empty — every field the
-   *  frontend shows must be listed explicitly. */
-  columns: Field[];
-}
-
-/** List page configuration. */
-export interface CurdListConfig {
-  /** List columns; required, non-empty. Every field the list shows must be
-   *  listed explicitly. May include cross-table fields via foreign refs. */
-  columns: Field[];
-  /** Fuzzy keyword search on this table's columns. */
-  keyword?: { columns: Field[] };
-  /** Default sort. Required — column and direction are both mandatory. */
-  orderBy: { column: Field; direction: 'asc' | 'desc' };
-  /** Search condition fields; op defaults to 'eq'. */
-  searchFields?: { field: Field; op?: Operator }[];
-  /** Column header text overrides: Field.name → header text. */
-  columnTitles?: Record<string, string>;
-}
-
-/** Admin-only CRUD page standard: binds one entity table to a frontend
- *  admin app. Drives generation of the list page plus optional
- *  add/update/detail pages. */
-export interface CurdSchema extends SchemaBase {
-  /** The admin frontend app this CRUD belongs to (shared instance, type must be 'admin'). */
-  app: FrontAppSchema;
-  /** The bound entity table (shared instance). */
-  table: TableSchema;
-  /** List page Chinese title. */
-  title: string;
-  /** Sidebar menu section (group) this CRUD page belongs to. */
-  section: string;
-  /** Extra user actions on this page (beyond the standard CRUD). */
-  actions?: ActionSchema[];
-  /** Add/update/detail action pages. */
-  actionPages?: {
-    add?: ActionPage;
-    update?: ActionPage;
-    detail?: ActionPage;
-  };
-  list: CurdListConfig;
-}
-
-function assertColumns(curd: CurdSchema, pageName: string, columns: Field[]): void {
-  if (columns.length === 0) {
-    throw new Error(`curd ${curd.name}: ${pageName}.columns must be non-empty`);
-  }
-}
-
-function assertFieldsOwnTable(curd: CurdSchema, label: string, fields: Field[]): void {
-  for (const f of fields) {
-    if (f.schema !== curd.table) {
-      throw new Error(`curd ${curd.name}: ${label} field ${f.name} does not belong to table ${curd.table.name}`);
-    }
-  }
-}
-
-/** Defines an admin CRUD page standard. Runtime-validates admin app binding,
- *  non-empty columns and table field ownership (same style as defineTable). */
-export function defineCurd(name: string, schema: Omit<CurdSchema, 'name'>): CurdSchema {
-  const curd: CurdSchema = { name, ...schema };
-  if (curd.app.type !== 'admin') {
-    throw new Error(`curd ${name}: app ${curd.app.name} must be type 'admin' (got '${curd.app.type}')`);
-  }
-  if (!curd.section) {
-    throw new Error(`curd ${name}: section is required (sidebar menu group, e.g. '商户管理')`);
-  }
-  assertColumns(curd, 'list', curd.list.columns);
-  for (const [pageName, page] of Object.entries(curd.actionPages ?? {})) {
-    if (page) assertColumns(curd, `actionPages.${pageName}`, page.columns);
-  }
-  assertFieldsOwnTable(curd, 'keyword', curd.list.keyword?.columns ?? []);
-  assertFieldsOwnTable(curd, 'orderBy', [curd.list.orderBy.column]);
-  return curd;
+import { SchemaBase, Field, Operator } from './dsl.js';
+import { TableSchema } from './db.js';
+import { FrontAppSchema } from './project.js';
+import { ActionSchema } from './action.js';
+import { toKebabCase } from '@pylonts/core';
+
+// Admin-only CRUD page standard: binds one entity table to a frontend admin
+// app, describing everything needed to generate the list page plus optional
+// add/update/detail pages. Field-level columns are plain Field instances
+// (table fields, cross-table refs allowed) — DTOs are derived by the generator,
+// the schema itself never references DtoMessage.
+
+/** Mode of an action page: modal dialog or standalone route. */
+export type ActionPageMode = 'modal' | 'route';
+
+/** One CRUD action page (add / update / detail). */
+export interface ActionPage {
+  mode: ActionPageMode;
+  /** Fields rendered on this page. Required, non-empty — every field the
+   *  frontend shows must be listed explicitly. */
+  columns: Field[];
+}
+
+/** List page configuration. */
+export interface CurdListConfig {
+  /** List columns; required, non-empty. Every field the list shows must be
+   *  listed explicitly. May include cross-table fields via foreign refs. */
+  columns: Field[];
+  /** Fuzzy keyword search on this table's columns. */
+  keyword?: { columns: Field[] };
+  /** Default sort. Required — column and direction are both mandatory. */
+  orderBy: { column: Field; direction: 'asc' | 'desc' };
+  /** Search condition fields; op defaults to 'eq'. */
+  searchFields?: { field: Field; op?: Operator }[];
+  /** Column header text overrides: Field.name → header text. */
+  columnTitles?: Record<string, string>;
+}
+
+/** Admin-only CRUD page standard: binds one entity table to a frontend
+ *  admin app. Drives generation of the list page plus optional
+ *  add/update/detail pages. */
+export interface CurdSchema extends SchemaBase {
+  /** The admin frontend app this CRUD belongs to (shared instance, type must be 'admin'). */
+  app: FrontAppSchema;
+  /** The bound entity table (shared instance). */
+  table: TableSchema;
+  /** List page Chinese title. */
+  title: string;
+  /** Sidebar menu section (group) this CRUD page belongs to. */
+  section: string;
+  /** Extra user actions on this page (beyond the standard CRUD). */
+  actions?: ActionSchema[];
+  /** Add/update/detail action pages. */
+  actionPages?: {
+    add?: ActionPage;
+    update?: ActionPage;
+    detail?: ActionPage;
+  };
+  list: CurdListConfig;
+}
+
+function assertColumns(curd: CurdSchema, pageName: string, columns: Field[]): void {
+  if (columns.length === 0) {
+    throw new Error(`curd ${curd.name}: ${pageName}.columns must be non-empty`);
+  }
+}
+
+function assertFieldsOwnTable(curd: CurdSchema, label: string, fields: Field[]): void {
+  for (const f of fields) {
+    if (f.schema !== curd.table) {
+      throw new Error(`curd ${curd.name}: ${label} field ${f.name} does not belong to table ${curd.table.name}`);
+    }
+  }
+}
+
+/** Defines an admin CRUD page standard. Runtime-validates admin app binding,
+ *  non-empty columns and table field ownership (same style as defineTable). */
+export function defineCurd(name: string, schema: Omit<CurdSchema, 'name'>): CurdSchema {
+  const curd: CurdSchema = { name, ...schema };
+  if (curd.app.type !== 'admin') {
+    throw new Error(`curd ${name}: app ${curd.app.name} must be type 'admin' (got '${curd.app.type}')`);
+  }
+  // The name is the admin route path — it must be the kebab-case table name
+  // so paths cannot drift from the table they serve.
+  const expectedName = toKebabCase(curd.table.name);
+  if (name !== expectedName) {
+    throw new Error(`curd name must be '${expectedName}' (kebab-case of table '${curd.table.name}'); got '${name}'`);
+  }
+  if (!curd.section) {
+    throw new Error(`curd ${name}: section is required (sidebar menu group, e.g. '商户管理')`);
+  }
+  assertColumns(curd, 'list', curd.list.columns);
+  for (const [pageName, page] of Object.entries(curd.actionPages ?? {})) {
+    if (page) assertColumns(curd, `actionPages.${pageName}`, page.columns);
+  }
+  assertFieldsOwnTable(curd, 'keyword', curd.list.keyword?.columns ?? []);
+  assertFieldsOwnTable(curd, 'orderBy', [curd.list.orderBy.column]);
+  return curd;
 }