@pylonts/dsl 1.1.1 → 1.1.3

package/dist/page.d.ts

@@ -1,26 +1,48 @@
 import { SchemaBase } from './dsl.js';
 import { FrontAppSchema } from './project.js';
-/** Standalone page definition. A page is a shared value object: it lists
- *  the actions a user can perform, and belongs to exactly one frontend app. */
+import type { PageDef } from './page-def.js';
+import type { RouteDataSchema } from './route.js';
+export declare function getRegisteredPages(): ReadonlySet<PageSchema>;
+export declare function clearRegisteredPages(): void;
+/** Standalone page definition. A page is a shared value object: it belongs to
+ *  exactly one frontend app. Actions live in the page skeleton (PageDef.actions),
+ *  not on the page itself — the page only carries what the flow/topology needs. */
 export interface PageSchema extends SchemaBase {
+    /** Short display name for topology diagrams. */
+    label: string;
     /** The frontend app this page belongs to (shared instance from project.config). */
     app: FrontAppSchema;
-    /** Actions a user can perform on this page (e.g. submit, approve, reject). */
-    actions: ActionSchema[];
+    /** Full page skeleton definition (optional). */
+    pageDef?: PageDef;
+    /** Route params this page expects (e.g. detail page expects productId). */
+    params?: RouteDataSchema;
 }
-/** An action a user can perform on a page (e.g. submit, approve, reject). */
-export interface ActionSchema extends SchemaBase {
-}
-export declare function defineAction(name: string, description?: string): ActionSchema;
 export declare function definePage(schema: {
     name: string;
+    label: string;
     description?: string;
     app: FrontAppSchema;
-    actions: ActionSchema[];
+    pageDef?: PageDef;
+    params?: RouteDataSchema;
 }): PageSchema;
+/** Page with bottom tab navigation. tabs collects the child pages reachable via tab switch. */
+export interface TabPageSchema extends PageSchema {
+    tabs: PageSchema[];
+}
+export declare function defineTabPage(schema: {
+    name: string;
+    label: string;
+    description?: string;
+    app: FrontAppSchema;
+    tabs: PageSchema[];
+    pageDef?: PageDef;
+    params?: RouteDataSchema;
+}): TabPageSchema;
 /** A page node in a page-driven flow: every node is a page, and a page belongs to an app. */
 export interface Page extends SchemaBase {
+    /** Short display name for topology diagrams. */
+    label?: string;
     /** The frontend app this page belongs to (shared instance from project.config). */
     app: FrontAppSchema;
 }
-export declare function page(app: FrontAppSchema, name: string, description?: string): Page;
+export declare function page(app: FrontAppSchema, name: string, description?: string, label?: string): Page;

package/dist/page.js

@@ -1,9 +1,24 @@
-export function defineAction(name, description) {
-    return { name, description };
+// Page definitions: standalone page schemas and the page node type used by
+// page-driven flows. Kept separate from page-flow.ts (the flow graph itself).
+// Module-level registry: every definePage/defineTabPage call registers its
+// result so definePageFlow can check that no page is left out.
+const _pageRegistry = new Set();
+export function getRegisteredPages() {
+    return _pageRegistry;
+}
+export function clearRegisteredPages() {
+    _pageRegistry.clear();
 }
 export function definePage(schema) {
-    return { ...schema };
+    const p = { ...schema };
+    _pageRegistry.add(p);
+    return p;
+}
+export function defineTabPage(schema) {
+    const p = { ...schema };
+    _pageRegistry.add(p);
+    return p;
 }
-export function page(app, name, description) {
-    return { name, app, description };
+export function page(app, name, description, label) {
+    return { name, label, app, description };
 }

package/dist/popup.d.ts

@@ -0,0 +1,18 @@
+import type { ActionSchema } from './action.js';
+import type { RefSchema } from './ref.js';
+/** Display a toast notification. React: toast/message UI. Mini-program: wx.showToast. */
+export interface ToastAction extends ActionSchema {
+    type: 'toast';
+    message: string | RefSchema;
+    icon?: 'success' | 'error' | 'loading' | 'none';
+}
+/** Display an alert dialog. React: modal. Mini-program: wx.showModal. */
+export interface AlertAction extends ActionSchema {
+    type: 'alert';
+    title: string | RefSchema;
+    content: string | RefSchema;
+}
+export declare const popup: {
+    toast(message: string | RefSchema, icon?: 'success' | 'error' | 'loading' | 'none'): ToastAction;
+    alert(title: string | RefSchema, content: string | RefSchema): AlertAction;
+};

package/dist/popup.js

@@ -0,0 +1,8 @@
+export const popup = {
+    toast(message, icon) {
+        return { name: 'toast', type: 'toast', message, icon };
+    },
+    alert(title, content) {
+        return { name: 'alert', type: 'alert', title, content };
+    },
+};

package/dist/project.d.ts

@@ -1,4 +1,5 @@
 import { SchemaBase } from './dsl.js';
+import type { TableSchema } from './db.js';
 /** Frontend form factor. Closed enum, extend when new form factors appear. */
 export type FrontType = 'admin' | 'wxmini';
 /** A frontend application (e.g. admin console, wechat mini program). */
@@ -6,6 +7,12 @@ export interface FrontAppSchema extends SchemaBase {
     type: FrontType;
     /** Source directory relative to project root, e.g. 'web-admin/'. */
     dir: string;
+    /**
+     * Tenant table for this app. When set, all tables with a foreign key
+     * pointing to this table get automatic tenant scoping: the tenant PK
+     * value is injected from `user.id` into all curd operations.
+     */
+    tenant?: TableSchema;
 }
 /** A backend API service. apps references shared FrontAppSchema instances. */
 export interface ProjectApiSchema extends SchemaBase {

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/docs/curd.md

@@ -1,111 +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 分组名（`gen-cli 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 命名是生成器约定，非页面语义） |
+# 管理端 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/dto.md

@@ -1,67 +1,67 @@
-# 定义 DTO（四种方向）
-
-DTO 描述接口出入参。方向决定可选性规则，由各方向工厂设置；**规则统一只在 `field.optional === undefined` 时生效**（作者已显式设置的跳过）：
-
-| 构建器 | 方向 | 可选性规则 |
-|---|---|---|
-| `buildInput` | input | 按 DB 列规则：主键 → 必填；可空 / 有默认 → 可选；其余 → 必填 |
-| `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。
-- `gen-cli 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 | 主键字段必填，其他字段可选 |
+
+## 从表提取字段
+
+```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`。
 - 枚举字段引用 `enums/` 下生成的枚举源文件，DTO 文件通过 `../../enums/{JsName}.enum` 导入。

package/docs/table.md

@@ -18,6 +18,8 @@
 
 通用扩展属性（构建器参数）：`label`（中文标签）、`description`、`optional`、`readOnly`、`default`。
 
+**`optional` 默认语义（MySQL 惯例）**：不写 `optional` 或写 `optional: true` → 列可空，DDL 不渲染 `NOT NULL`；写 `optional: false` → 列必填（`NOT NULL`）。业务上必填的列必须显式声明。
+
 ## 定义表
 
 ```ts
@@ -31,7 +33,7 @@ export const order = defineTable('order', {
   columns: {
     id,
     order_no: stringField({ label: '订单号', maxLength: 32, optional: false }),
-    amount: decimalField({ precision: 18, scale: 2, label: '金额' }),
+    amount: decimalField({ precision: 18, scale: 2, label: '金额', optional: false }),
   },
   primaryKey: id,
 });
@@ -127,7 +129,7 @@ export const audit = defineTable('audit', {
   `foreign key bad: field must be named bd_id (phrase bd + id), got merchant_id`
 - 关联表不需要 `phrase`。
 
-> **外键是逻辑作用**：`foreignKeys` 用于定义期命名强校验与关系表达，**DDL 默认不渲染物理 FOREIGN KEY 约束**（`gen-cli sql init` 不传 `generateForeignKeys`）。数据完整性由 Service/DAO 层保证；如需物理约束，调用 `buildCreateTableSql(schema, { generateForeignKeys: true })`。
+> **外键是逻辑作用**：`foreignKeys` 用于定义期命名强校验与关系表达，**DDL 默认不渲染物理 FOREIGN KEY 约束**（`pylonts gen sql init` 不传 `generateForeignKeys`）。数据完整性由 Service/DAO 层保证；如需物理约束，调用 `buildCreateTableSql(schema, { generateForeignKeys: true })`。
 
 ## 生成 SQL
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonts/dsl",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Schema definition DSL with drivers: MySQL DDL, TS enum, TypeBox schema codegen.",
   "type": "module",
   "main": "src/index.ts",