@pylonts/dsl 1.0.1 → 1.0.3

package/dist/dictionary.d.ts

@@ -1,25 +1,13 @@
 import { SchemaBase } from './dsl';
-/** A vocabulary entry: name is written back from the dictionary key. */
+/** A vocabulary entry. */
 export interface DictionaryEntry extends SchemaBase {
+    /** Display label (Chinese) for the term. */
+    label?: string;
 }
-export interface DictionarySchema extends SchemaBase {
-    entries: Record<string, DictionaryEntry>;
-}
-/** Creates a phrase entry. name is filled in by defineDictionary. */
-export declare function definePhrase(extra?: Omit<DictionaryEntry, 'name'>): DictionaryEntry;
-/** Defines the entity phrase dictionary: standard words aligned with entities. */
-export declare function defineEntityDictionary(schema: {
-    description?: string;
-    entries: Record<string, DictionaryEntry>;
-}): DictionarySchema;
-/**
- * Defines a business phrase package (one file per industry): entries are the
- * top-level map keys, no wrapping container.
- */
-export declare function defineBusinessDictionary(entries: Record<string, DictionaryEntry>): DictionarySchema;
 /**
- * Merges business phrase packages (one file per industry) into a single flat
- * map. Package metadata (name/description) is dropped; duplicate keys across
- * packages throw.
+ * Explains a phrase — the returned entry IS the phrase. `name` is the phrase
+ * itself (column-name stem, e.g. mer / bd / amt), not a full entity name;
+ * label/description explain what it means. Convention: short phrase, not long
+ * name.
  */
-export declare function mergeBusinessDictionaries(packages: DictionarySchema[]): Record<string, DictionaryEntry>;
+export declare function definePhrase(extra: DictionaryEntry): DictionaryEntry;

package/dist/dictionary.js

@@ -1,45 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.definePhrase = definePhrase;
-exports.defineEntityDictionary = defineEntityDictionary;
-exports.defineBusinessDictionary = defineBusinessDictionary;
-exports.mergeBusinessDictionaries = mergeBusinessDictionaries;
-/** Creates a phrase entry. name is filled in by defineDictionary. */
-function definePhrase(extra = {}) {
-    return { name: '', ...extra };
-}
-function defineDictionary(schema) {
-    const dictionary = { ...schema };
-    for (const key of Object.keys(dictionary.entries)) {
-        dictionary.entries[key].name = key;
-    }
-    return dictionary;
-}
-/** Defines the entity phrase dictionary: standard words aligned with entities. */
-function defineEntityDictionary(schema) {
-    return defineDictionary({ name: 'entity', ...schema });
-}
-/**
- * Defines a business phrase package (one file per industry): entries are the
- * top-level map keys, no wrapping container.
- */
-function defineBusinessDictionary(entries) {
-    return defineDictionary({ name: 'business', entries });
-}
 /**
- * Merges business phrase packages (one file per industry) into a single flat
- * map. Package metadata (name/description) is dropped; duplicate keys across
- * packages throw.
+ * Explains a phrase — the returned entry IS the phrase. `name` is the phrase
+ * itself (column-name stem, e.g. mer / bd / amt), not a full entity name;
+ * label/description explain what it means. Convention: short phrase, not long
+ * name.
  */
-function mergeBusinessDictionaries(packages) {
-    const merged = {};
-    for (const pkg of packages) {
-        for (const key of Object.keys(pkg.entries)) {
-            if (merged[key]) {
-                throw new Error(`business phrase ${key} is defined in multiple packages`);
-            }
-            merged[key] = pkg.entries[key];
-        }
-    }
-    return merged;
+function definePhrase(extra) {
+    return extra;
 }

package/dist/dsl.d.ts

@@ -128,6 +128,8 @@ export declare function defineTable(name: string, schema: {
     primaryKey?: Field | Field[];
     indexes?: Index[];
     foreignKeys?: Record<string, ForeignKey>;
+    /** 引用的实体短语（词典条目） */
+    phrase?: DictionaryEntry;
     fields: Record<string, Field>;
 }): TableSchema;
 export {};

package/dist/flow.d.ts

@@ -0,0 +1,28 @@
+import { SchemaBase } from './dsl';
+export interface FlowNode extends SchemaBase {
+    /** Optional sub-flow. When present, entering this node runs the sub-flow;
+     *  after the sub-flow reaches any terminal node, the outer flow continues
+     *  via this node's outgoing edges. Sub-flows nest recursively. */
+    flow?: FlowSchema;
+}
+export interface FlowEdge extends SchemaBase {
+    /** Trigger condition; undefined = default path (success/normal). */
+    when?: string;
+    start: FlowNode;
+    end: FlowNode;
+}
+export interface FlowSchema extends SchemaBase {
+    /** Entry node. */
+    start: FlowNode;
+    /** All nodes, collected from edges (deduplicated by object identity). */
+    nodes: FlowNode[];
+    /** Independent edges; a node may be start of many edges, so cycles are expressible. */
+    edges: FlowEdge[];
+}
+export declare function node(name: string, flow?: FlowSchema, description?: string): FlowNode;
+export declare function edge(start: FlowNode, end: FlowNode, when?: string, description?: string): FlowEdge;
+export declare function defineFlow(name: string, schema: {
+    start: FlowNode;
+    edges: FlowEdge[];
+    description?: string;
+}): FlowSchema;

package/dist/flow.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.node = node;
+exports.edge = edge;
+exports.defineFlow = defineFlow;
+function node(name, flow, description) {
+    return { name, flow, description };
+}
+function edge(start, end, when, description) {
+    // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
+    return { name: `${start.name}->${end.name}`, start, end, when, description };
+}
+function defineFlow(name, schema) {
+    const seen = new Set();
+    const nodes = [];
+    for (const e of schema.edges) {
+        for (const n of [e.start, e.end]) {
+            if (!seen.has(n)) {
+                seen.add(n);
+                nodes.push(n);
+            }
+        }
+    }
+    if (!seen.has(schema.start)) {
+        seen.add(schema.start);
+        nodes.push(schema.start);
+    }
+    const flow = { name, description: schema.description, start: schema.start, nodes, edges: schema.edges };
+    validate(flow);
+    return flow;
+}
+// Nodes that never appear as an edge start are terminals. Reverse BFS from all
+// terminals marks every node that can reach a terminal; unmarked nodes sit on
+// a path that never ends (e.g. a cycle without an exit) — reject them at
+// definition time.
+function validate(schema) {
+    const starts = new Set();
+    for (const e of schema.edges)
+        starts.add(e.start);
+    const reverse = new Map();
+    for (const n of schema.nodes)
+        reverse.set(n, []);
+    for (const e of schema.edges) {
+        reverse.get(e.end).push(e.start);
+    }
+    const reached = new Set();
+    const queue = [];
+    for (const n of schema.nodes) {
+        if (!starts.has(n)) {
+            reached.add(n);
+            queue.push(n);
+        }
+    }
+    while (queue.length > 0) {
+        const cur = queue.shift();
+        for (const prev of reverse.get(cur)) {
+            if (!reached.has(prev)) {
+                reached.add(prev);
+                queue.push(prev);
+            }
+        }
+    }
+    for (const n of schema.nodes) {
+        if (!reached.has(n)) {
+            throw new Error(`flow ${schema.name}: node "${n.name}" cannot reach a terminal`);
+        }
+    }
+}

package/dist/index.d.ts

@@ -6,3 +6,9 @@ export * from './dictionary';
 export * from './mysql-driver';
 export * from './enum-driver';
 export * from './typebox-driver';
+export * from './pattern';
+export * from './patterns/retry';
+export * from './flow';
+export * from './page';
+export * from './page-flow';
+export * from './mermaid-driver';

package/dist/index.js

@@ -22,3 +22,9 @@ __exportStar(require("./dictionary"), exports);
 __exportStar(require("./mysql-driver"), exports);
 __exportStar(require("./enum-driver"), exports);
 __exportStar(require("./typebox-driver"), exports);
+__exportStar(require("./pattern"), exports);
+__exportStar(require("./patterns/retry"), exports);
+__exportStar(require("./flow"), exports);
+__exportStar(require("./page"), exports);
+__exportStar(require("./page-flow"), exports);
+__exportStar(require("./mermaid-driver"), exports);

package/dist/mermaid-driver.d.ts

@@ -0,0 +1,4 @@
+import { FlowSchema } from './flow';
+import { PageFlow } from './page-flow';
+export declare function renderFlowMermaid(schema: FlowSchema): string;
+export declare function renderPageFlowMermaid(schema: PageFlow): string;

package/dist/mermaid-driver.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderFlowMermaid = renderFlowMermaid;
+exports.renderPageFlowMermaid = renderPageFlowMermaid;
+// Mermaid driver: converts a FlowSchema into a Mermaid flowchart (TD).
+// Node ids are hierarchical (n0, n0_0, n0_0_0, ...) so nested sub-flows stay
+// globally unique. A node with a sub-flow renders as a subgraph block whose
+// internals are rendered recursively. ok edges render as -->, conditional
+// edges render as -->|"WHEN"|.
+function escapeLabel(s) {
+    return s.replace(/"/g, '\\"').replace(/\n/g, '<br/>');
+}
+function renderFlowMermaid(schema) {
+    const lines = ['flowchart TD'];
+    const ids = new Map();
+    renderFlow(schema, 'n', lines, ids);
+    lines.push('');
+    lines.push('    classDef start fill:#e6f4ea,stroke:#333,stroke-width:1px;');
+    lines.push(`    class ${ids.get(schema.start)} start;`);
+    return lines.join('\n');
+}
+function renderFlow(schema, prefix, lines, ids) {
+    schema.nodes.forEach((n, i) => ids.set(n, `${prefix}${i}`));
+    for (const n of schema.nodes) {
+        const id = ids.get(n);
+        if (n.flow) {
+            lines.push(`    subgraph ${id}["${escapeLabel(n.name)}"]`);
+            renderFlow(n.flow, `${id}_`, lines, ids);
+            lines.push('    end');
+        }
+        else {
+            lines.push(`    ${id}["${escapeLabel(n.name)}"]`);
+        }
+    }
+    for (const e of schema.edges) {
+        lines.push(renderEdge(e, ids));
+    }
+}
+function renderEdge(e, ids) {
+    const label = e.when ? `|"${escapeLabel(e.when)}"|` : '';
+    return `    ${ids.get(e.start)} -->${label} ${ids.get(e.end)}`;
+}
+// Page-driven flow renderer: groups pages by their app into swimlane
+// subgraphs, then renders edges across the whole flow.
+function renderPageFlowMermaid(schema) {
+    const lines = ['flowchart TD'];
+    const ids = new Map();
+    const byApp = new Map();
+    for (const p of schema.pages) {
+        const list = byApp.get(p.app.name) ?? [];
+        list.push(p);
+        byApp.set(p.app.name, list);
+    }
+    let appIdx = 0;
+    for (const [appName, pages] of byApp) {
+        lines.push(`    subgraph app${appIdx}["${escapeLabel(appName)}"]`);
+        pages.forEach((p, i) => ids.set(p, `app${appIdx}_p${i}`));
+        for (const p of pages) {
+            lines.push(`    ${ids.get(p)}["${escapeLabel(p.name)}"]`);
+        }
+        appIdx++;
+        lines.push('    end');
+    }
+    for (const e of schema.edges) {
+        const label = e.when ? `|"${escapeLabel(e.when.name)}"|` : '';
+        lines.push(`    ${ids.get(e.start)} -->${label} ${ids.get(e.end)}`);
+    }
+    lines.push('');
+    lines.push('    classDef start fill:#e6f4ea,stroke:#333,stroke-width:1px;');
+    lines.push(`    class ${ids.get(schema.start)} start;`);
+    return lines.join('\n');
+}

package/dist/page-flow.d.ts

@@ -0,0 +1,21 @@
+import { SchemaBase } from './dsl';
+import { ActionSchema, Page } from './page';
+export interface PageEdge extends SchemaBase {
+    /** Trigger action; undefined = default path (success/normal). */
+    when?: ActionSchema;
+    start: Page;
+    end: Page;
+}
+export interface PageFlow extends SchemaBase {
+    /** Entry page. */
+    start: Page;
+    /** All pages, collected from edges (deduplicated by object identity). */
+    pages: Page[];
+    edges: PageEdge[];
+}
+export declare function pageEdge(start: Page, end: Page, when?: ActionSchema, description?: string): PageEdge;
+export declare function definePageFlow(name: string, schema: {
+    start: Page;
+    edges: PageEdge[];
+    description?: string;
+}): PageFlow;

package/dist/page-flow.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pageEdge = pageEdge;
+exports.definePageFlow = definePageFlow;
+function pageEdge(start, end, when, description) {
+    // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
+    return { name: `${start.name}->${end.name}`, start, end, when, description };
+}
+function definePageFlow(name, schema) {
+    const seen = new Set();
+    const pages = [];
+    for (const e of schema.edges) {
+        for (const p of [e.start, e.end]) {
+            if (!seen.has(p)) {
+                seen.add(p);
+                pages.push(p);
+            }
+        }
+    }
+    if (!seen.has(schema.start)) {
+        seen.add(schema.start);
+        pages.push(schema.start);
+    }
+    return { name, description: schema.description, start: schema.start, pages, edges: schema.edges };
+}

package/dist/page.d.ts

@@ -0,0 +1,26 @@
+import { SchemaBase } from './dsl';
+import { FrontApp } from './project';
+/** 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. */
+export interface PageSchema extends SchemaBase {
+    /** The frontend app this page belongs to (shared instance from project.config). */
+    app: FrontApp;
+    /** Actions a user can perform on this page (e.g. submit, approve, reject). */
+    actions: ActionSchema[];
+}
+/** 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;
+    description?: string;
+    app: FrontApp;
+    actions: ActionSchema[];
+}): PageSchema;
+/** 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 {
+    /** The frontend app this page belongs to (shared instance from project.config). */
+    app: FrontApp;
+}
+export declare function page(app: FrontApp, name: string, description?: string): Page;

package/dist/page.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineAction = defineAction;
+exports.definePage = definePage;
+exports.page = page;
+function defineAction(name, description) {
+    return { name, description };
+}
+function definePage(schema) {
+    return { ...schema };
+}
+function page(app, name, description) {
+    return { name, app, description };
+}

package/dist/pattern.d.ts

@@ -0,0 +1,15 @@
+export interface PatternParamDef {
+    type: 'int' | 'string';
+    min?: number;
+    default?: number | string;
+}
+export interface PatternDef {
+    name: string;
+    params: Record<string, PatternParamDef>;
+}
+export interface PatternRef {
+    ref: string;
+    args: Record<string, unknown>;
+}
+export declare function definePattern(def: PatternDef): PatternDef;
+export declare function ref(name: string, args: Record<string, unknown>): PatternRef;

package/dist/pattern.js

@@ -0,0 +1,13 @@
+"use strict";
+// Pattern core: minimal definitions to bootstrap the Flow × Pattern DSL.
+// A Pattern is a reusable solution ("how to guarantee success") declared as
+// pure data. Concrete usage fills its params and action injection points.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.definePattern = definePattern;
+exports.ref = ref;
+function definePattern(def) {
+    return def;
+}
+function ref(name, args) {
+    return { ref: name, args };
+}

package/dist/patterns/retry.d.ts

@@ -0,0 +1,16 @@
+import { PatternDef } from '../pattern';
+export declare const retryPattern: PatternDef;
+export interface RetryAction {
+    /** Function to call, e.g. 'queryOrderList' */
+    call: string;
+    /** Type name of the single argument passed through, e.g. 'OrderQueryParams' */
+    params?: string;
+}
+export interface RetryRefArgs {
+    max?: number;
+    backoffMs?: number;
+    action: RetryAction;
+    /** Generated function name; defaults to '<call>WithRetry' */
+    fnName?: string;
+}
+export declare function renderRetry(args: RetryRefArgs): string;

package/dist/patterns/retry.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retryPattern = void 0;
+exports.renderRetry = renderRetry;
+// Retry pattern: blind mechanical retry for read-only operations.
+// Valid because a read-only action is idempotent by nature: clicking a query
+// button any number of times never changes the result, so retrying the same
+// call is always safe. No idempotency key, no query-and-resume, no compensate.
+exports.retryPattern = {
+    name: 'retry',
+    params: {
+        max: { type: 'int', min: 1, default: 3 },
+        backoffMs: { type: 'int', min: 0, default: 0 },
+    },
+};
+function renderRetry(args) {
+    if (args.max !== undefined && args.max < 1)
+        throw new Error('retry: max must be >= 1');
+    if (!args.action.call)
+        throw new Error('retry: action.call is required');
+    const max = args.max ?? 3;
+    const backoffMs = args.backoffMs ?? 0;
+    const call = args.action.call;
+    const paramType = args.action.params ?? 'unknown';
+    const fnName = args.fnName ?? `${call}WithRetry`;
+    const retryLine = backoffMs > 0 ? `      await sleep(${backoffMs});` : '';
+    return [
+        `export async function ${fnName}(params: ${paramType}) {`,
+        `  for (let attempt = 1; ; attempt++) {`,
+        `    try {`,
+        `      return await ${call}(params);`,
+        `    } catch (err) {`,
+        `      if (attempt >= ${max}) throw err;`,
+        retryLine,
+        `    }`,
+        `  }`,
+        `}`,
+        '',
+    ].join('\n');
+}

package/dist/project.d.ts

@@ -13,10 +13,20 @@ export interface ProjectApi extends SchemaBase {
     dir: string;
     /** Frontends this API serves. Direct instance references (see defineProject). */
     apps: FrontApp[];
+    /** API base URL prefix shared by all apps it serves, e.g. '/mall'. '' = no prefix. */
+    contextPath?: string;
+}
+/** A third-party system (e.g. wechat pay, unionpay). Owns its own
+ *  implementation dir and contract (controller_types), just like an API,
+ *  but is not part of this repo's served surface. */
+export interface ThirdApi extends SchemaBase {
+    /** Source directory relative to project root, e.g. 'wechat/'. */
+    dir: string;
 }
 export interface ProjectSchema extends SchemaBase {
     apps: FrontApp[];
     apis: ProjectApi[];
+    thirdApis: ThirdApi[];
 }
 /**
  * Defines the project topology. FrontApp instances are shared value objects:
@@ -27,4 +37,5 @@ export declare function defineProject(name: string, schema: {
     description?: string;
     apps: FrontApp[];
     apis: ProjectApi[];
+    thirdApis?: ThirdApi[];
 }): ProjectSchema;

package/dist/project.js

@@ -7,5 +7,5 @@ exports.defineProject = defineProject;
  * by multiple APIs is defined once and referenced many times.
  */
 function defineProject(name, schema) {
-    return { name, ...schema };
+    return { name, ...schema, thirdApis: schema.thirdApis ?? [] };
 }

package/docs/dictionary.md

@@ -0,0 +1,31 @@
+# 短语词典 (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) 的外键检查链）。关联表等多实体场景不需要。
+- 业务短语供字段命名/文档使用，跨团队对齐。
+- 未收录短语的实体保留全名作词干（不臆造缩写），评审时再裁决收录。

package/docs/driver.md

@@ -0,0 +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 }),   // 枚举引用解析
+});
+```

package/docs/dto.md

@@ -0,0 +1,60 @@
+# 定义 DTO（四种方向）
+
+DTO 描述接口出入参。方向决定语义与可选性规则：
+
+| 构建器 | 方向 | 用途 |
+|---|---|---|
+| `buildInput` | input | 新增/修改请求体 |
+| `buildOutput` | output | 响应体 |
+| `buildQuery` | query | 分页 + 过滤查询（字段恒为可选） |
+| `buildPk` | pk | 按主键取详情 |
+
+## 从表提取字段
+
+```ts
+import { buildInput, buildQuery, dtoField, from } from '@pylonts/dsl';
+
+// 输入：新增订单
+buildInput('OrderAddRequest', { ...from(order, [order.fields.mer_id, order.fields.amount]) });
+
+// 输出：订单行
+buildOutput('OrderRow', from(order, [order.fields.id, order.fields.order_no]));
+
+// 查询：分页 + 过滤（query 字段恒为可选，.op() 声明比较操作符）
+buildQuery('OrderPageQuery', {
+  keyword: dtoField(stringField({ maxLength: 32 })).op('like'),
+  ...from(order, [order.fields.mer_id]),
+});
+
+// 主键：按 id 取详情
+buildPk('OrderDetailRequest', from(order, [order.fields.id]));
+```
+
+`from(table, fields)` 提取表字段包装为 DTO 字段，字段实例与表共享，`name/schema` 保持指向表。
+
+## 独立字段
+
+不来自表的内联字段直接用 `dtoField(...)` 包装任意字段构建器，可加 `pattern`、`optional`、`operator`。
+
+```ts
+dtoField(stringField({ maxLength: 32 })).op('like')
+```
+
+## 继承基础 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`。
+- 枚举字段引用 `enums/` 下生成的枚举源文件，DTO 文件通过 `../../enums/{JsName}.enum` 导入。