@pylonts/dsl 1.0.6 → 1.1.2

package/dist/prototype.d.ts

@@ -1,4 +1,4 @@
-import { SchemaBase } from './dsl';
+import { SchemaBase } from './dsl.js';
 /** Display metadata for a prototype field. */
 export interface PrototypeFieldMeta {
     label: string;

package/dist/prototype.js

@@ -1,10 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.definePrototype = definePrototype;
 /**
  * Defines a page prototype. The field keys become the names referenced by
  * later DTO/table definitions; here they only carry label/description.
  */
-function definePrototype(name, schema) {
+export function definePrototype(name, schema) {
     return { name, ...schema };
 }

package/dist/provider.d.ts

@@ -0,0 +1,54 @@
+import type { ImportBase } from './import-base.js';
+import type { ImportableSchemaBase } from './dsl.js';
+import type { DtoField, DtoMessage, DtoArrayField, DtoObjectField } from './dto.js';
+import type { ActionSchema } from './action.js';
+import type { RefSchema } from './ref.js';
+import type { ConvertSchema } from './convert.js';
+/** Parameter data source for a call argument. */
+export type DataRef = {
+    type: 'route';
+    key: string;
+} | {
+    type: 'data';
+    key: string;
+} | {
+    type: 'value';
+    value: unknown;
+};
+/** Create a route-parameter reference. */
+export declare function route(key: string): DataRef;
+/** Create a page-data reference. */
+export declare function data(key: string): DataRef;
+export interface CallAction extends ActionSchema {
+    type: 'call';
+    func: ProviderSchema;
+    args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>;
+}
+export declare function call(func: ProviderSchema, args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>): CallAction;
+/** Provider function signature. The generated API client exposes one function
+ *  per endpoint; ProviderSchema gives that function a name and types. */
+export interface ProviderSchema extends ImportableSchemaBase {
+    isAsync: boolean;
+    /** Input DTO (buildInput / buildQuery / buildPk result). */
+    args: DtoMessage;
+    /** Output DTO (buildOutput result) or primitive. */
+    results: DtoMessage | number | boolean | string;
+}
+/** Define a provider function. */
+export declare function defineProvider(name: string, schema: {
+    isAsync: boolean;
+    args: DtoMessage;
+    results: DtoMessage | number | boolean | string;
+    description?: string;
+    importRef?: ImportBase;
+}): ProviderSchema;
+/** Assign a call's result to a page data field.
+ *  React: setState({ [field]: await ... }). Mini-program: this.setData({ [field]: ... }). */
+export interface SetDataAction extends ActionSchema {
+    type: 'setData';
+    call: CallAction;
+    field: DtoField;
+    /** Optional field-level transform before assignment. */
+    convert?: ConvertSchema;
+}
+export declare function setData(call: CallAction, field: DtoField, convert?: ConvertSchema): SetDataAction;

package/dist/provider.js

@@ -0,0 +1,18 @@
+/** Create a route-parameter reference. */
+export function route(key) {
+    return { type: 'route', key };
+}
+/** Create a page-data reference. */
+export function data(key) {
+    return { type: 'data', key };
+}
+export function call(func, args) {
+    return { name: func.name, type: 'call', func, args };
+}
+/** Define a provider function. */
+export function defineProvider(name, schema) {
+    return { name, ...schema };
+}
+export function setData(call, field, convert) {
+    return { name: 'setData', type: 'setData', call, field, convert };
+}

package/dist/ref.d.ts

@@ -0,0 +1,14 @@
+import type { CollectionSchemaBase } from './dsl.js';
+import type { DtoField } from './dto.js';
+/** A reference to a field within another schema. Carries a .schema back-reference
+ *  so the driver knows where the data comes from (route params, page data, etc.). */
+export interface RefSchema {
+    name: string;
+    /** Schema back-reference — tells driver the data source. */
+    schema: CollectionSchemaBase;
+    /** The referenced field instance. */
+    field: DtoField;
+}
+/** Create a reference to a field in a source schema.
+ *  Writes back field.schema to the source so the driver can trace origin. */
+export declare function defineRef(source: CollectionSchemaBase, field: DtoField): RefSchema;

package/dist/ref.js

@@ -0,0 +1,6 @@
+/** Create a reference to a field in a source schema.
+ *  Writes back field.schema to the source so the driver can trace origin. */
+export function defineRef(source, field) {
+    field.schema = source;
+    return { name: field.name, schema: source, field };
+}

package/dist/route.d.ts

@@ -0,0 +1,8 @@
+import type { CollectionSchemaBase } from './dsl.js';
+import type { DtoField } from './dto.js';
+/** Route params: data that arrives from the navigation URL / route. */
+export interface RouteDataSchema extends CollectionSchemaBase {
+    type: 'route';
+    fields: Record<string, DtoField>;
+}
+export declare function defineRouteData(name: string, fields: RouteDataSchema['fields']): RouteDataSchema;

package/dist/route.js

@@ -0,0 +1,3 @@
+export function defineRouteData(name, fields) {
+    return { name, type: 'route', fields };
+}

package/dist/typebox-driver.d.ts

@@ -1,7 +1,7 @@
-import { DtoMessage, ImportRef } from './dto';
-export type EnumResolver = (enumName: string) => ImportRef | undefined;
+import { DtoMessage, ImportBase } from './dto.js';
+export type EnumResolver = (enumName: string) => ImportBase | undefined;
 /** Collect all imports needed to render a DTO: include() bases + enum references. */
-export declare function collectDtoImports(schema: DtoMessage, resolver: EnumResolver | undefined, out: Map<string, ImportRef>): void;
+export declare function collectDtoImports(schema: DtoMessage, resolver: EnumResolver | undefined, out: Map<string, ImportBase>): void;
 /** Render one DTO export (const + type) — no file header, for file-level generation. */
 export declare function renderDtoExport(schema: DtoMessage, resolver: EnumResolver | undefined): string;
 /** Render the Static type export for a DTO. */

package/dist/typebox-driver.js

@@ -1,10 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.collectDtoImports = collectDtoImports;
-exports.renderDtoExport = renderDtoExport;
-exports.renderDtoTypeExport = renderDtoTypeExport;
-exports.renderDtoMessage = renderDtoMessage;
-const dto_1 = require("./dto");
 function renderString(s) {
     return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 }
@@ -83,31 +76,36 @@ function renderField(f, indent, resolver) {
     return f.isOptional() ? `Type.Optional(${base})` : base;
 }
 function renderValue(f, indent, resolver) {
-    if (f instanceof dto_1.DtoArrayField) {
-        const items = f.items();
+    if (f.field.type === 'array') {
+        const items = f.field.items;
         // Referenced DTO element — render by name (same-file export), not expanded.
-        if (items instanceof dto_1.DtoMessage)
+        if (isDtoMessage(items))
             return `Type.Array(${items.name})`;
         return `Type.Array(${renderField(items, indent + 1, resolver)})`;
     }
-    if (f instanceof dto_1.DtoObjectField) {
-        return renderObject(f.properties(), indent + 1, resolver);
+    if (f.field.type === 'object') {
+        return renderObject(f.field.properties, indent + 1, resolver);
     }
     // DtoField only wraps a database Field; array/object defs live in the subclasses.
-    // DTO-level default wins over the DB field default; the DB default (string)
-    // is used as a fallback so from() picks carry it into the API contract.
-    const defaultValue = f.default !== undefined ? f.default : f.field.default;
-    return renderBasic(f.field, f.pattern, defaultValue, resolver);
+    // Only DTO-level defaults (setDefault) are emitted as TypeBox default
+    // annotations; DB field defaults are not carried into the API contract.
+    return renderBasic(f.field, f.pattern, f.default, resolver);
+}
+/** Structural check — DtoMessage instances may come from a different module copy, so instanceof is unreliable. */
+function isDtoMessage(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    return v.type === 'dto';
 }
 function collectEnumImports(f, resolver, out) {
-    if (f instanceof dto_1.DtoArrayField) {
-        const items = f.items();
-        if (!(items instanceof dto_1.DtoMessage))
+    if (f.field.type === 'array') {
+        const items = f.field.items;
+        if (!isDtoMessage(items))
             collectEnumImports(items, resolver, out);
         return;
     }
-    if (f instanceof dto_1.DtoObjectField) {
-        for (const child of Object.values(f.properties()))
+    if (f.field.type === 'object') {
+        for (const child of Object.values(f.field.properties))
             collectEnumImports(child, resolver, out);
         return;
     }
@@ -119,14 +117,14 @@ function collectEnumImports(f, resolver, out) {
     }
 }
 /** Collect all imports needed to render a DTO: include() bases + enum references. */
-function collectDtoImports(schema, resolver, out) {
+export function collectDtoImports(schema, resolver, out) {
     for (const base of schema.bases ?? [])
         out.set(`${base.from}#${base.name}`, base);
     for (const f of Object.values(schema.fields))
         collectEnumImports(f, resolver, out);
 }
 /** Render one DTO export (const + type) — no file header, for file-level generation. */
-function renderDtoExport(schema, resolver) {
+export function renderDtoExport(schema, resolver) {
     const object = renderObject(schema.fields, 1, resolver);
     const bases = schema.bases ?? [];
     const body = bases.length > 0
@@ -135,10 +133,10 @@ function renderDtoExport(schema, resolver) {
     return `export const ${schema.name} = ${body};`;
 }
 /** Render the Static type export for a DTO. */
-function renderDtoTypeExport(name) {
+export function renderDtoTypeExport(name) {
     return `export type ${name} = Static<typeof ${name}>;`;
 }
-function renderDtoMessage(schema, options = {}) {
+export function renderDtoMessage(schema, options = {}) {
     const { resolver, source } = options;
     const imports = new Map();
     collectDtoImports(schema, resolver, imports);
@@ -146,7 +144,7 @@ function renderDtoMessage(schema, options = {}) {
         '// AUTO-GENERATED by typebox-driver — DO NOT EDIT',
         ...(source !== undefined ? [`// Source: ${source}`] : []),
         "import { Type, Static } from '@sinclair/typebox';",
-        ...[...imports.values()].map((r) => `import { ${r.name} } from '${r.from}';`),
+        ...[...imports.values()].map((r) => `import${r.type ? ' type' : ''} { ${r.name} } from '${r.from}';`),
     ];
     return [
         ...header,

package/dist/utils.d.ts

@@ -1,2 +1,4 @@
 /** snake_case → camelCase: mer_id → merId; names without underscores are unchanged */
 export declare function toCamelCase(name: string): string;
+/** snake_case → PascalCase: mer_id → MerId */
+export declare function toPascalCase(snake: string): string;

package/dist/utils.js

@@ -1,8 +1,9 @@
-"use strict";
 // ── naming conversions ──
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.toCamelCase = toCamelCase;
 /** snake_case → camelCase: mer_id → merId; names without underscores are unchanged */
-function toCamelCase(name) {
+export function toCamelCase(name) {
     return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
 }
+/** snake_case → PascalCase: mer_id → MerId */
+export function toPascalCase(snake) {
+    return snake.replace(/(^|_)([a-z])/g, (_m, _p, c) => c.toUpperCase());
+}

package/docs/curd.md

@@ -0,0 +1,111 @@
+# 管理端 CRUD 页面标准（CurdSchema）
+
+CurdSchema 是**管理端专用**（`FrontAppSchema.type === 'admin'`）的 CRUD 页面标准：绑定一张实体表 + 一个管理端 app，描述列表页与新增/编辑/详情动作页生成所需的全部页面语义。一条 CurdSchema = 列表页（+ 动作页）的生成规格。
+
+页面定义文件按实体组织：`{project}/pages/{entity}.curd.ts`（与 `schema/*.table.ts` 平级）。
+
+**CurdSchema 只依赖 table schema（`Field` 实例），不挂钩 DTO（`DtoMessage`）**——DTO 由生成器按标准从 `columns` 推导。
+
+## 定义
+
+```ts
+import { defineCurd } from '@pylonts/dsl';
+
+export const orderCurd = defineCurd('order-curd', {
+  description: '订单管理',
+  app: webAdmin,                    // 所属管理端（project.config.ts 的 FrontAppSchema 共享实例）
+  table: order,                     // 绑定实体表（共享实例）
+  title: '订单管理',
+  section: '订单管理',               // 必填：sidebar 分组名
+  actions: [defineAction('EXPORT', '导出订单')],   // 额外操作按钮
+  actionPages: {
+    add:    { mode: 'modal', columns: [order.columns.order_no, order.columns.mer_id] },
+    update: { mode: 'modal', columns: [order.columns.id, order.columns.order_no] },
+    detail: { mode: 'route',  columns: [order.columns.id, order.columns.order_no, order.columns.amount] },
+  },
+  list: {
+    columns: [order.columns.id, order.columns.order_no, merchant.columns.name],  // 可跨表
+    keyword: { columns: [order.columns.order_no] },  // 模糊搜索（本表字段）
+    orderBy: { column: order.columns.id, direction: 'desc' },
+    searchFields: [{ field: order.columns.mer_id }, { field: order.columns.order_no, op: 'like' }],
+    columnTitles: { order_no: '订单号', name: '商户名称' },   // Field.name → 文案
+  },
+});
+```
+
+## 字段
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `app` | `FrontAppSchema` | 所属管理端（共享实例，`type` 必须为 `'admin'`） |
+| `table` | `TableSchema` | 绑定实体表（共享实例） |
+| `title` | `string` | 列表页中文标题 |
+| `section` | `string` | **必填**：sidebar 分组名（`pylonts gen curd` 据此生成路由注册的 `section` 字段） |
+| `actions?` | `ActionSchema[]` | 页面额外可执行动作（标准 CRUD 之外，如导出、审核） |
+| `actionPages?` | `{ add? / update? / detail? }` | 动作页：`{ mode: 'modal' \| 'route'; columns: Field[] }` |
+| `list` | `CurdListConfig` | 列表页配置（必填） |
+
+### ActionPage
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `mode` | `'modal' \| 'route'` | 弹窗或独立路由 |
+| `columns` | `Field[]` | 该页面渲染的字段，**必填非空**——前端要显示的字段必须全部显式列出 |
+
+### CurdListConfig
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `columns` | `Field[]` | 列表列，**必填非空**——前端要显示的字段必须全部显式列出；可含跨表字段（见下） |
+| `keyword?` | `{ columns: Field[] }` | 模糊搜索，columns 必须是**本表字段实例** |
+| `orderBy` | `{ column: Field; direction: 'asc' \| 'desc' }` | 默认排序，**必填**，column 与 direction 都必填；column 必须是**本表字段实例** |
+| `searchFields?` | `{ field: Field; op?: Operator }[]` | 搜索条件字段，op 默认 `'eq'`，可选 `eq/gt/gte/lt/lte/like/ne` |
+| `columnTitles?` | `Record<string, string>` | 列标题覆盖：`Field.name` → 中文文案 |
+
+## 跨表字段
+
+`columns` / `searchFields` 里的 `Field` 实例可指向**本表或其他表**的列——列表列与搜索条件因此可以显示关联表字段（如订单列表显示商户名称）：
+
+```ts
+list: {
+  columns: [order.columns.id, order.columns.order_no, merchant.columns.name],  // 跨表：字段指向 merchant.name
+}
+```
+
+## 默认与校验
+
+- `list.columns` / `actionPages.*.columns` **必填非空**（不允许省略、不允许空数组）——前端显示什么必须显式定义
+- `list.orderBy` **必填**，`column` 与 `direction` 都必填（规格：默认主键 desc 由定义方显式写出）
+- 运行时校验（`defineCurd`，仿 `defineTable` 强校验风格）：
+  - `app.type` 必须为 `'admin'`，否则抛错
+  - 所有 `columns` 非空，否则抛错
+  - `list.keyword.columns` / `list.orderBy.column` 必须属于 `table`，否则抛错
+  - `list.columns` / `list.searchFields` 允许跨表，**不校验归属**
+- 生成时校验（curd 生成器，`DtoSchemaGen.add` / `update`）：
+  - 表配置 `autoIncrement` 或 `generator`（主键由服务端生成）时，`actionPages.add.columns` **不允许包含主键字段**，否则抛错——AddRequest 不携带服务端生成的主键
+  - `actionPages.update.columns` **必须包含主键字段**，否则抛错——UpdateRequest 靠主键定位记录
+
+## DTO 推导（生成器约定）
+
+DTO 由 curd 生成器从 `CurdSchema` 按标准命名推导，页面语义不持有 DTO 实例：
+
+| DTO | 命名 | 字段来源 |
+|---|---|---|
+| Row | `{Pascal}Row` | `list.columns` |
+| AddRequest | `{Pascal}AddRequest` | `actionPages.add.columns` |
+| UpdateRequest | `{Pascal}UpdateRequest` | `actionPages.update.columns` |
+| DetailRequest | `{Pascal}DetailRequest` | 主键 |
+| DetailResponse | `{Pascal}DetailResponse` | `actionPages.detail.columns` |
+
+## 与旧 PageConfig 的差异
+
+| PageConfig（旧方案，已废弃） | CurdSchema |
+|---|---|
+| `module: string` | 由 `app` 推导（后端模块 == app 1:1） |
+| `schema: 'bd'` 字符串 | `table: TableSchema` 实例（类型安全） |
+| `operations: { label, action }` | `actions: ActionSchema[]` |
+| `detail.mode` 单例 | `actionPages.detail.mode` |
+| `forms.add / forms.update` | `actionPages.add / actionPages.update` |
+| `keyword` / `orderBy` / `columnTitles` | `list.keyword` / `list.orderBy` / `list.columnTitles`（列改字段实例引用） |
+| `naming` | 去掉（DTO 命名是生成器约定，非页面语义） |
+| DTO 引用（`request` / `fields` / `DtoFields`） | 去掉（DTO 由生成器推导，页面只依赖 table） |

package/docs/dictionary.md

@@ -1,31 +1,42 @@
-# 短语词典 (Dictionary)
-
-词典是与团队达成共识的基础知识库：**某词代表什么**（语义/定义层面），不是物理形式。短语定了，字段命名、外键命名就都有依据——全项目只说同一种话。
-
-- 是基础知识库，很少变更。
-- **能引用就引用**：魔法字符串只在首次出现时使用，之后一律引用词典条目。
-
-## 规范位置：schema/_dictionary.ts
-
-**所有短语统一定义在 `schema/_dictionary.ts`**，一个文件一处定义；`*.table.ts` 从该文件 import 短语，禁止在表文件里内联定义短语。
-
-## 口径：definePhrase 解释短语，name 即短语
-
-`definePhrase` 返回的条目**就是短语本身**，不是"全名 + 缩写"两套——`name` 即短语词干（列名前缀），`label`/`description` 解释语义。**变量名与 name 一致**（小写）。短语要短（mer / bd / amt 三字母左右），**不要用长语**：引用商户实体的字段叫 `mer_id`，不叫 `merchant_id`。
-
-## 定义
-
-```ts
-// schema/_dictionary.ts
-import { definePhrase } from '@pylonts/dsl';
-
-const bd = definePhrase({ name: 'bd', label: 'BD推广员', description: '线下拓展商户、辅助入驻的推广人员' });
-const amt = definePhrase({ name: 'amt', label: '金额', description: '交易金额，单位分' });
-const mer = definePhrase({ name: 'mer', label: '商户', description: '入驻平台的商户' });
-```
-
-## 使用
-
-- **表链接实体**：`TableSchema.phrase` 引用实体条目，声明本表归属哪个实体（见 [table.md](./table.md) 的外键检查链）。关联表等多实体场景不需要。
-- 业务短语供字段命名/文档使用，跨团队对齐。
-- 未收录短语的实体保留全名作词干（不臆造缩写），评审时再裁决收录。
+# 短语词典 (Dictionary)
+
+词典是与团队达成共识的基础知识库：**某词代表什么**（语义/定义层面），不是物理形式。短语定了，字段命名、外键命名就都有依据——全项目只说同一种话。
+
+- 是基础知识库，很少变更。
+- **能引用就引用**：魔法字符串只在首次出现时使用，之后一律引用词典条目。
+
+## 规范位置：schema/_dictionary.ts
+
+**所有短语统一定义在 `schema/_dictionary.ts`**，一个文件一处定义；`*.table.ts` 从该文件 import 短语，禁止在表文件里内联定义短语。
+
+## 两种短语，两种命名规则
+
+短语分两类，参与不同的字段命名校验：
+
+| 类型 | 定义函数 | 含义 | 命名规则 | 例子 |
+|---|---|---|---|---|
+| `entity` | `defineEntityPhrase` | 实体缩写 | 字段名**首段**（实体领先） | `mer_id`、`bd_rate` |
+| `business` | `defineBusinessPhrase` | 实体的属性 | 字段名**末段**（属性收尾） | `bd_rate`、`acquiring_rate` |
+
+## 口径：name 即短语
+
+两个定义函数返回的条目**就是短语本身**，不是"全名 + 缩写"两套——`name` 即短语词干（列名前缀），`label`/`description` 解释语义。**变量名与 name 一致**（小写）。短语要短（mer / bd / amt 三字母左右），**不要用长语**：引用商户实体的字段叫 `mer_id`，不叫 `merchant_id`。
+
+## 定义
+
+```ts
+// schema/_dictionary.ts
+import { defineEntityPhrase, defineBusinessPhrase } from '@pylonts/dsl';
+
+const bd  = defineEntityPhrase({ name: 'bd',  label: 'BD推广员', description: '线下拓展商户、辅助入驻的推广人员' });
+const mer = defineEntityPhrase({ name: 'mer', label: '商户', description: '入驻平台的商户' });
+const amt = defineBusinessPhrase({ name: 'amt', label: '金额', description: '交易金额，单位分' });
+const rate = defineBusinessPhrase({ name: 'rate', label: '费率', description: '结算费率' });
+```
+
+## 使用
+
+- **表链接实体**：`TableSchema.phrase` 引用**实体短语**条目，声明本表归属哪个实体（见 [table.md](./table.md) 的外键检查链）。关联表等多实体场景不需要。
+- 业务短语供字段命名/文档使用，跨团队对齐。
+- 未收录短语的实体保留全名作词干（不臆造缩写），评审时再裁决收录。
+- 字段命名校验按类型区分：实体短语必须首段、业务短语必须末段（见 [field-check.md](../../lint/docs/field-check.md)）。

package/docs/driver.md

@@ -1,42 +1,42 @@
-# Driver 模式与产物生成
-
-DSL 定义元数据，driver 翻译成目标语言产物。产物与定义解耦，同一份定义可生成不同目标：
-
-| 定义 | Driver | 产物 | 消费方 |
-|---|---|---|---|
-| `TableSchema` | mysql-driver | `CREATE TABLE` | MySQL |
-| `EnumDef` | enum-driver | `export enum Xxx { … }` + `XXX_LABEL` | 业务代码 |
-| `DtoMessage` | typebox-driver | `Type.Object({…})` + `Static` 推导 | fastify v5 参数校验 |
-
-## 生成 SQL
-
-```ts
-import { buildCreateTableSql } from '@pylonts/dsl';
-
-buildCreateTableSql(order);   // "CREATE TABLE `order` (\n  ..."
-```
-
-默认不生成外键约束；需要时：
-
-```ts
-buildCreateTableSql(order, { generateForeignKeys: true });
-```
-
-## 生成枚举源码
-
-```ts
-import { renderEnum } from '@pylonts/dsl';
-
-renderEnum(AcquiringType);    // TS enum 源码
-```
-
-## 生成 TypeBox 源码
-
-```ts
-import { renderDtoMessage } from '@pylonts/dsl';
-
-renderDtoMessage(orderPageQuery, {
-  source: 'dto_schema/order/order.dsl.dto.ts',
-  resolver: (name) => ({ from: '@mall/enums/user', name }),   // 枚举引用解析
-});
-```
+# Driver 模式与产物生成
+
+DSL 定义元数据，driver 翻译成目标语言产物。产物与定义解耦，同一份定义可生成不同目标：
+
+| 定义 | Driver | 产物 | 消费方 |
+|---|---|---|---|
+| `TableSchema` | mysql-driver | `CREATE TABLE` | MySQL |
+| `EnumDef` | enum-driver | `export enum Xxx { … }` + `XXX_LABEL` | 业务代码 |
+| `DtoMessage` | typebox-driver | `Type.Object({…})` + `Static` 推导 | fastify v5 参数校验 |
+
+## 生成 SQL
+
+```ts
+import { buildCreateTableSql } from '@pylonts/dsl';
+
+buildCreateTableSql(order);   // "CREATE TABLE `order` (\n  ..."
+```
+
+默认不生成外键约束；需要时：
+
+```ts
+buildCreateTableSql(order, { generateForeignKeys: true });
+```
+
+## 生成枚举源码
+
+```ts
+import { renderEnum } from '@pylonts/dsl';
+
+renderEnum(AcquiringType);    // TS enum 源码
+```
+
+## 生成 TypeBox 源码
+
+```ts
+import { renderDtoMessage } from '@pylonts/dsl';
+
+renderDtoMessage(orderPageQuery, {
+  source: 'dto_schema/order/order.dto.ts',
+  resolver: (name) => ({ from: '@mall/enums/user', name }),   // 枚举引用解析
+});
+```

package/docs/dto.md

@@ -4,7 +4,7 @@ DTO 描述接口出入参。方向决定可选性规则，由各方向工厂设
 
 | 构建器 | 方向 | 可选性规则 |
 |---|---|---|
-| `buildInput` | input | 按 DB 列规则：可空 / 有默认 / 自增列 → 可选；NOT NULL 无默认 → 必填 |
+| `buildInput` | input | 按 DB 列规则：主键 → 必填；可空（未写 `optional` 或 `optional: true`）/ 有默认 → 可选；`optional: false` 无默认 → 必填 |
 | `buildOutput` | output | 不设置（保持字段构建器/作者设置） |
 | `buildQuery` | query | 全部可选 |
 | `buildPk` | pk | 主键字段必填，其他字段可选 |
@@ -15,19 +15,19 @@ DTO 描述接口出入参。方向决定可选性规则，由各方向工厂设
 import { buildInput, buildQuery, dtoField, from } from '@pylonts/dsl';
 
 // 输入：新增订单
-buildInput('OrderAddRequest', { ...from(order, [order.fields.mer_id, order.fields.amount]) });
+buildInput('OrderAddRequest', { ...from(order, [order.columns.mer_id, order.columns.amount]) });
 
 // 输出：订单行
-buildOutput('OrderRow', from(order, [order.fields.id, order.fields.order_no]));
+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.fields.mer_id]),
+  ...from(order, [order.columns.mer_id]),
 });
 
 // 主键：按 id 取详情
-buildPk('OrderDetailRequest', from(order, [order.fields.id]));
+buildPk('OrderDetailRequest', from(order, [order.columns.id]));
 ```
 
 `from(table, fields)` 提取表字段包装为 DTO 字段，字段实例与表共享，`name/schema` 保持指向表。**DTO 字段名转 camelCase**（`mer_id` → `merId`），与 DB 列名（snake_case）分离。`from()` 本身不做任何可选性推断——推断在各方向工厂。
@@ -63,5 +63,5 @@ buildQuery('OrderPageQuery', { ... })
 ## 文件组织
 
 - `dto_schema/{module}/*.dto.ts`：DTO 源文件，一个文件可导出多个 DtoMessage；`module` = `project.config.ts` 的 `apps.name`，另加 `common/` 放跨 app 共享 DTO。
-- `gen-cli dto` 按 module 逐个扫描：`dto_schema/{module}/*.dto.ts` → 生成 `dto/{module}/{Name}.dto.ts`。
+- `pylonts gen dto` 按 module 逐个扫描：`dto_schema/{module}/*.dto.ts` → 生成 `dto/{module}/{Name}.dto.ts`。
 - 枚举字段引用 `enums/` 下生成的枚举源文件，DTO 文件通过 `../../enums/{JsName}.enum` 导入。

package/docs/enum.md

@@ -1,24 +1,24 @@
-# 定义枚举（可跨表复用）
-
-枚举定义与字段分离：`defineEnum` 产生共享定义（纯值对象），`enumField` 引用它。同一枚举可被多张表 / 多个 DTO 复用，只生成一次。
-
-```ts
-import { defineEnum, enumField } from '@pylonts/dsl';
-
-// 共享定义（_common.ts 等公共文件）
-export const AcquiringType = defineEnum('AcquiringType', 'string', [
-  { symbol: 'WECHAT', value: 'wechat', label: '微信' },
-  { symbol: 'UNIONPAY', value: 'unionpay', label: '银联商务' },
-]);
-
-// 字段引用（每表独立实例）
-buildTable('merchant', { fields: { acquiring_type: enumField({ enum: AcquiringType }) }, ... });
-buildTable('order',    { fields: { acquiring_type: enumField({ enum: AcquiringType }) }, ... });
-```
-
-- 字段实例每表独立（列名、可选性随表），枚举定义全局共享。
-- 枚举由 enum-driver 生成独立文件；typebox-driver 只渲染 `Type.Enum(名称)` + import 引用，不内联。
-
-## 生成枚举源码
-
-见 [driver.md](./driver.md)。
+# 定义枚举（可跨表复用）
+
+枚举定义与字段分离：`defineEnum` 产生共享定义（纯值对象），`enumField` 引用它。同一枚举可被多张表 / 多个 DTO 复用，只生成一次。
+
+```ts
+import { defineEnum, enumField } from '@pylonts/dsl';
+
+// 共享定义（_common.ts 等公共文件）
+export const AcquiringType = defineEnum('AcquiringType', 'string', [
+  { symbol: 'WECHAT', value: 'wechat', label: '微信' },
+  { symbol: 'UNIONPAY', value: 'unionpay', label: '银联商务' },
+]);
+
+// 字段引用（每表独立实例）
+buildTable('merchant', { columns: { acquiring_type: enumField({ enum: AcquiringType }) }, ... });
+buildTable('order',    { columns: { acquiring_type: enumField({ enum: AcquiringType }) }, ... });
+```
+
+- 字段实例每表独立（列名、可选性随表），枚举定义全局共享。
+- 枚举由 enum-driver 生成独立文件；typebox-driver 只渲染 `Type.Enum(名称)` + import 引用，不内联。
+
+## 生成枚举源码
+
+见 [driver.md](./driver.md)。

package/docs/project.md

@@ -18,7 +18,7 @@ export const mall = defineProject('mall', {
 });
 ```
 
-- `FrontApp`：`name` / `description` / `type`（admin | wxmini）/ `dir`（相对仓库根目录的源码目录）。
-- `ProjectApi`：`name` / `description` / `dir` / `apps`（直接引用共享的 FrontApp 实例——一个 app 被多个 API 服务就定义一次、引用多次）/ `contextPath`（API 基础 URL 前缀，如 `/mall`，空串表示无前缀）。
+- `FrontAppSchema`：`name` / `description` / `type`（admin | wxmini）/ `dir`（相对仓库根目录的源码目录）。
+- `ProjectApiSchema`：`name` / `description` / `dir` / `apps`（直接引用共享的 FrontAppSchema 实例——一个 app 被多个 API 服务就定义一次、引用多次）/ `contextPath`（API 基础 URL 前缀，如 `/mall`，空串表示无前缀）。
 - **直接对象引用优先**：`api.apps` 与 `project.apps` 指向同一实例，不写字符串。
 - **contextPath 解析**：前端 app 的 API 前缀由服务它的 api 决定——`api.apps` 必须恰好包含该 app（零个或多个都报错），app 本身不声明 contextPath。