@pylonts/dsl 1.1.13 → 1.1.15

package/dist/dto.d.ts

@@ -47,6 +47,8 @@ export declare class DtoField implements SchemaBase {
     operator?: Operator;
     /** TypeBox default annotation (API contract level); falls back to field.default (DB default) */
     default?: unknown;
+    /** Optional reference to another DtoField — this field reuses the referenced field's type/constraints */
+    ref?: DtoField;
     constructor(field: Field | DtoArrayFieldDef | DtoObjectFieldDef);
     setPattern(value: string): this;
     setDescription(value: string): this;
@@ -56,6 +58,8 @@ export declare class DtoField implements SchemaBase {
     setOptional(value: boolean): this;
     /** Set a default value — emitted as a TypeBox schema default annotation */
     setDefault(value: unknown): this;
+    /** Reference another DtoField — this field reuses the referenced field's type/constraints */
+    setRef(value: DtoField): this;
     /** 查询比较操作符（query 方向字段）。Rule B: 查询字段恒为可选 */
     setOperator(value: Operator): this;
     /** optional 优先于 field.optional */

package/dist/dto.js

@@ -14,6 +14,8 @@ export class DtoField {
     operator;
     /** TypeBox default annotation (API contract level); falls back to field.default (DB default) */
     default;
+    /** Optional reference to another DtoField — this field reuses the referenced field's type/constraints */
+    ref;
     constructor(field) {
         this.name = '';
         this.field = field;
@@ -42,6 +44,11 @@ export class DtoField {
         this.default = value;
         return this;
     }
+    /** Reference another DtoField — this field reuses the referenced field's type/constraints */
+    setRef(value) {
+        this.ref = value;
+        return this;
+    }
     /** 查询比较操作符（query 方向字段）。Rule B: 查询字段恒为可选 */
     setOperator(value) {
         this.operator = value;

package/docs/third-service.md

@@ -2,121 +2,151 @@
 
 第三方服务适配器契约（如微信支付 tenpay、短信、文件存储）。`defineThirdService` 声明适配器类契约：构造函数配置 + 方法列表。
 
+> 完整对接流程（前置准备 → 契约化 → gen third → 填充 client → 沙箱验证）见 [methodology/third-party-integration.md](../../docs/methodology/third-party-integration.md)。
+
+与两个相近概念区分：
+
+- `ServiceSchema`（service_schema/）——后端业务服务；
+- `ThirdApiSchema`（project.config.ts `thirdApis`）——项目拓扑：第三方系统的目录归属，如 `wx/`、`ble/`。
+
+`ThirdServiceSchema.schema` 引用 `ThirdApiSchema` 实例（拓扑引用）。第三方方法实现在外部系统，仅声明契约、不建模内部流程。
+
+## 定义
+
 ```ts
-import { defineFieldRule, defineThirdService } from '@pylonts/dsl';
+import { buildInput, buildOutput, CodeException, defineThirdService, dtoField, intField, IOException, stringField } 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: {} },
-});
+const totalFee = intField({ optional: false, label: '金额（分）' });
 
 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 } },
-        ],
-      },
+  methods: {
+    getPayParams: {
+      args: buildInput('PayParams', {
+        out_trade_no: dtoField(stringField({ maxLength: 32, optional: false, label: '订单号' })),
+        total_fee: dtoField(totalFee),
+        // Same fact and same type as the entity column — shared instance.
+        openid: dtoField(user.columns.openid),
+      }),
+      results: buildOutput('PayParamsResult', {
+        appId: dtoField(stringField({ optional: false, label: 'appId' })),
+        paySign: dtoField(stringField({ optional: false, label: '签名' })),
+      }),
+      throws: [CodeException, IOException],
+      description: '获取支付参数',
     },
-  ],
+  },
 });
 ```
 
-## ThirdMethodSchema：方法的 args / results
-
-每个方法的 `args` / `results` 各是一个 `ThirdMethodSchema`——**字段集合容器**，与 `TableSchema.columns` 同构，但字段是线格式（wire-format）字段。结构上它是 `DtoMessage` 的字段集合对应物。
+- `methods` 是 **map**：key 即方法名（构建器写回 `method.name`），value 为 `ThirdServiceMethodDef`。
+- 每个方法的 `args` / `results` 各是一个 `DtoMessage`，用 `buildInput` / `buildOutput` 构建。`buildInput` 构建 `args`（输入消息），`buildOutput` 构建 `results`（输出消息）——与业务 DTO 同一 POJO 聚合，字段以 `dtoField(field)` 包装，map key 即线格式（wire-format）字段名，**原样保留协议拼写**（`out_trade_no`、`appId`，不做 camelCase）。
+- `throws`（**必填**）：每个方法必须声明 **`CodeException` + `IOException`** 两个异常——`CodeException`（第三方返回的业务错误码）与 `IOException`（网络/超时/不可恢复故障）。两个异常都来自 `@pylonts/core`，**不能自定义、不能替换**（`pylonts gen third` 会校验，缺失即报错拒绝生成）。原因：第三方集成有两类必然失败——业务层失败（第三方返回错误码，需转译给调用方）与传输层失败（网络/超时，需按故障重试或上报），client 骨架的异常翻译依赖这两个契约。
+- `description`（可选）：服务或方法说明。
 
-| 属性 | 说明 |
-|------|------|
-| `name` | 消息名（如 `QueryBalanceResult`），生成产物的类型名 |
-| `fields` | 线格式字段 map，key 即协议字段名（`out_trade_no`、`appId` 原样保留） |
-| `refs` | 同事实变体链接（见下） |
-| `schema` | 反向指针，指向所属 method（构建器写入） |
-
-`defineThirdMethod` 写回自有字段的 `name/schema`（与 `defineTable` 同一惯例）。
-
-## 字段与本地实体的关系
-
-两个通道，按"同一事实"的表达方式选择：
+字段与本地实体列/其他消息字段的关系，两个通道，按"同一事实"的表达方式选择：
 
 ### 同一概念且类型一致 → 共享实例
 
-直接复用本地实体列实例，类型/语义/默认值自动跟随实体，DTO 投影继承全部语义（与 `from(table)` 完全同构）：
+直接复用本地实体列实例，类型/语义/默认值自动跟随实体，DTO 投影继承全部语义：
 
 ```ts
 args: {
-  name: 'QueryBalanceArgs',
+  name: 'PayParams',
   fields: {
-    openid: user.columns.openid,   // 共享实例，schema 仍指向 t_user
+    openid: dtoField(user.columns.openid),   // user 是 TableSchema 实例，此处复用其 openid 列的 Field 对象
   },
 },
 ```
 
-前提是线格式字段名与实体列名一致（协议恰好也叫 `openid`）。名字不同时（协议叫 `userId` 而列叫 `user_id`），不共享实例，走 refs。
+线格式字段名（map key）与列名无需一致——key 是协议拼写，value 是任意 Field 实例，两者解耦。协议叫 `userId`、列叫 `user_id` 照样共享：
 
-### 同一概念但类型/格式不同（变体）→ 自有字段 + refs
+```ts
+fields: {
+  userId: dtoField(user.columns.user_id),   // key 按协议拼写，value 复用列实例
+},
+```
 
-声明自有线格式类型，再挂一条 `refs` 链接指向实体列。规则先定义一次：
+> `user` 是 `schema/user.table.ts` 中 `export const user = defineTable('user', { ... })` 导出的 **TableSchema 实例**（`user.columns` 是它的列 map，`user.columns.openid` 是该表 `openid` 列的 Field 实例）。共享实例即把**同一个 Field 对象**放入消息字段，类型/语义/默认值全部跟随表定义。
 
-```ts
-// 规则 = 名称 + 两端（具名 map）。同一语义全局只允许一条（重复定义抛错）。
-const fenYuan = defineFieldRule({
-  name: 'fenYuan',
-  ends: { fen: {}, yuan: {} },
-});
+### 同一概念但类型/格式不同 → 自有字段
 
+声明自有线格式类型：
+
+```ts
 const totalFee = intField({ optional: false, label: '金额（分）' });
 
 fields: {
-  total_fee: totalFee,
+  total_fee: dtoField(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 端）
+wire 字段与本地字段之间的换算/映射（分↔元、加密、脱敏）由 convert 防腐层承载，`FieldRuleSchema` 换算规则为规划能力、尚未接入消息绑定。
 
 ## 嵌套字段
 
-线格式字段支持递归嵌套，用 `arrayField` / `objectField`（Field 体系，非表列）：
+线格式字段支持递归嵌套，用 `objectField` / `arrayField`（Field 体系，非表列）：
 
 ```ts
 fields: {
-  payer_info: objectField({
+  payer_info: dtoField(objectField({
     properties: {
       openid: stringField({ optional: false, maxLength: 64 }),
     },
-  }),
-  coupons: arrayField({ items: intField() }),
+  })),
+  coupons: dtoField(arrayField({ items: intField() })),
 },
 ```
 
-表列不支持这两个类型（`buildCreateTableSql` 直接报错）。
+表列不支持这两个类型（`buildCreateTableSql` 直接报错，定义期即拦截）。
+
+## 枚举与异常
+
+第三方消息字段可用 `enumField` 挂 `defineEnum` 枚举，两者与 `defineThirdService` 定义在同一源文件中（named export），供 `pylonts gen third` 生成枚举产物。
+
+异常不在此处定义——方法 `throws` 固定声明 `@pylonts/core` 的 `CodeException` + `IOException`（见上文「定义」一节），`pylonts gen third` 强校验。
+
+## 存储与生成
+
+- 声明：`third_schema/{thirdApi.name}/*.third-service.ts`——一文件一服务（named export），目录名 = project.config.ts 的 `thirdApis` 实例名。
+- 生成：`pylonts gen third`——对每个 thirdApi，扫描 `third_schema/{name}/`，按三步产出到 `third/{name}/`：
+  0. **throws 校验**（生成前置闸门）：每个方法必须声明 `CodeException` + `IOException`，缺失即报错列出违规方法，不写任何产物；
+  1. **枚举**：模块导出的 `defineEnum` 实例 → `third/{name}/enums/{JsName}.enum.ts`（复用 enum-driver 的 `renderEnum`，与表枚举同一渲染），一 jsName 一文件；
+  2. **DTO**：每方法 args/results 用 typebox-driver 渲染 TypeBox 消息 + Static 类型，**一源文件一生成文件**，输出 `third/{name}/{stem}.third-service.gen.ts`（覆盖写）；
+  3. **客户端骨架**：每服务渲染一个 class（构造配置接口 + 每方法 async 签名 + Not-implemented throw），输出 `third/{name}/{stem}.client.ts`——**已存在则跳过**（方法体是用户填充的），`--force` 覆盖。
+- DTO 的枚举字段 import 走**相对路径** `./enums/{JsName}.enum`（DTO 与 enums/ 同处 `third/{name}/` 下，`moduleResolution: bundler` 解析 `.enum.ts`），不依赖根 `enums/` 子包。
+- 生成物目录是子包：`third/` 目录带 `package.json`，`exports` 声明 `*.third-service.gen` 子路径，供 convert 产物 import。
+
+## 客户端骨架是生成的，方法体是手写的
 
-## DTO 转发
+`defineThirdService` 只描述**契约**（构造配置 + 方法列表）。`gen third` 生成的 `{name}.client.ts` 是一个**骨架**：导出 `{Service}Config` 接口（TODO 注释标注 transport 配置——baseUrl/凭据/密钥属外部实现，不在契约内）+ `{Service}` 类（constructor 空实现），每方法带完整签名（args/results 类型从同名 `.third-service.gen` import type）与 `throw new Error('Not implemented: ...')` stub（含 `// @gen:stub` 标记，与 gen-service 骨架同一套 marker 约定）。**签名/throws 注释由生成器保证与契约同步，方法体、构造配置、签名加密等外部交互由人工填充**——已存在文件默认跳过（避免覆盖人工实现），`--force` 才重写。
+
+## convert 防腐接线
+
+第三方消息（`args`/`results` 是 `DtoMessage`，天然满足 `ConvertSourceSchema`）可直接作为 convert 的**源或目标**，用于 wire 消息 ↔ 本地模型的防腐翻译。```ts
+// convert_schema/{api.name}/{app.name}/convert/wx-pay.convert.ts
+import { wxPayService } from '../../../third_schema/wx/wxpay.third-service';
+
+const getPayParams = wxPayService.methods.getPayParams;
+
+export const wxPayConvert = defineConvert({
+  name: 'WxPayConvert',
+  api,
+  app: admin,
+  methods: {
+    toPayParams: {
+      sources: [order],                 // 本地订单表 → wire 请求
+      target: getPayParams.args,
+    },
+    toLocalPayResult: {
+      sources: [getPayParams.results],  // wire 响应 → 本地 DTO
+      target: WxPayParamsResultDto,
+    },
+  },
+});
+```
 
-DTO 通过 `from(thirdMethod, fields)` 投影第三方消息字段，构建转发引用（透传不复制）。线格式字段名保持协议原样，不做 camelCase。见 [dto.md](./dto.md#从字段集合投影)。
+convert 文件绑定第三方服务身份时按 `{third-service}.convert.ts` 命名（上例 `wx-pay.convert.ts` 对应 `wxpay.third-service.ts` 的 `WxPayService`）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonts/dsl",
-  "version": "1.1.13",
+  "version": "1.1.15",
   "description": "Schema definition DSL with drivers: MySQL DDL, TS enum, TypeBox schema codegen.",
   "type": "module",
   "main": "dist/index.js",
@@ -41,7 +41,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@pylonts/core": "^1.1.2"
+    "@pylonts/core": "^1.1.3"
   },
   "devDependencies": {
     "typescript": "^7.0.2",

package/src/dto.ts

@@ -1,324 +1,332 @@
-import { BaseField, CollectionSchemaBase, Field, Operator, SchemaBase, walkContainer } from './dsl.js';
-import { TableSchema } from './db.js';
-import type { EntitySchema } from './entity.js';
-import type { ImportBase } from './import-base.js';
-import { toCamelCase } from '@pylonts/core';
-
-// Interface (DTO) field definitions.
-// Naming convention: all DTO types and builders use the Dto prefix.
-// A DtoField stores the database Field and the API-only extras separately.
-
-/** Re-export — Operator lives on the DSL level (see dsl.ts). */
-export type { Operator } from './dsl.js';
-
-/** Re-export — ImportBase lives on its own module (see import-base.ts). */
-export type { ImportBase } from './import-base.js';
-
-/** Re-export — MockDescriptor lives on its own module (see mock.ts). */
-export type { MockDescriptor } from './mock.js';
-
-/**
- * Reference to an existing TypeBox base schema by its import location.
- * Serializable metadata: the driver renders `import { name } from 'from'`
- * and `Type.Intersect([name, ...])` — the runtime schema is never loaded by the DSL.
- */
-export interface ImportRef extends ImportBase {
-  /**
-   * Generic type arguments for the base schema (e.g. PageResult(OrderRow)).
-   * Two forms, both local DTOs:
-   *   string     — the DTO export name
-   *   DtoMessage — the DTO instance itself; the driver resolves it to its name
-   */
-  args?: (string | DtoMessage)[];
-}
-
-export type DtoArrayFieldDef = BaseField & {
-  type: 'array';
-  jsType: 'array';
-  /** Element type: inline DtoField, or a reference to an existing DTO (rendered by name) */
-  items: DtoField | DtoMessage;
-};
-
-export type DtoObjectFieldDef = BaseField & {
-  type: 'object';
-  jsType: 'object';
-  properties: Record<string, DtoField>;
-};
-
-export class DtoField implements SchemaBase {
-  /** DTO 语义字段名（接口字段名），与 field.name（数据库列名）含义不同。
-   *  构造时未知，由 buildMessage 从 map key 反写。 */
-  name: string;
-  /** 字段描述 */
-  description?: string;
-  /** 所属容器（buildMessage / defineRouteData / definePageData 反写） */
-  schema?: CollectionSchemaBase;
-  field: Field | DtoArrayFieldDef | DtoObjectFieldDef;
-  pattern?: string;
-  optional?: boolean;
-  operator?: Operator;
-  /** TypeBox default annotation (API contract level); falls back to field.default (DB default) */
-  default?: unknown;
-
-  constructor(field: Field | DtoArrayFieldDef | DtoObjectFieldDef) {
-    this.name = '';
-    this.field = field;
-  }
-
-  setPattern(value: string): this {
-    this.pattern = value;
-    return this;
-  }
-
-  setDescription(value: string): this {
-    this.description = value;
-    return this;
-  }
-
-  getDescription(): string | undefined {
-    return this.description;
-  }
-
-  /** True when this field wraps a DB column (picked via from()); false for inline fields. */
-  isColumn(): boolean {
-    return this.field.schema?.type === 'table';
-  }
-
-  setOptional(value: boolean): this {
-    this.optional = value;
-    return this;
-  }
-
-  /** Set a default value — emitted as a TypeBox schema default annotation */
-  setDefault(value: unknown): this {
-    this.default = value;
-    return this;
-  }
-
-  /** 查询比较操作符（query 方向字段）。Rule B: 查询字段恒为可选 */
-  setOperator(value: Operator): this {
-    this.operator = value;
-    return this;
-  }
-
-  /** optional 优先于 field.optional */
-  isOptional(): boolean {
-    if (this.optional !== undefined) return this.optional;
-    return this.field.optional ?? false;
-  }
-}
-
-export class DtoArrayField extends DtoField {
-  declare field: DtoArrayFieldDef;
-
-  /** Element type: inline DtoField or a referenced DtoMessage (rendered by name). */
-  items(): DtoField | DtoMessage {
-    return this.field.items;
-  }
-}
-
-export class DtoObjectField extends DtoField {
-  declare field: DtoObjectFieldDef;
-
-  properties(): Record<string, DtoField> {
-    return this.field.properties;
-  }
-}
-
-export enum DtoDirection {
-  Input = 'input',
-  Output = 'output',
-  Query = 'query',
-  Pk = 'pk',
-}
-
-export class DtoMessage implements CollectionSchemaBase {
-  type = 'dto';
-  name: string;
-  description?: string;
-  /** 方向：输入或输出 */
-  direction: DtoDirection;
-  fields: Record<string, DtoField>;
-  /** TypeBox base schemas to intersect with at generation time (e.g. PageRequest) */
-  bases: ImportRef[] = [];
-
-  constructor(name: string, direction: DtoDirection, fields: Record<string, DtoField>, description?: string) {
-    this.name = name;
-    this.direction = direction;
-    this.fields = fields;
-    this.description = description;
-  }
-
-  /** 引用已存在的 TypeBox base schema，例如 include({ from: '@pylonts/core', name: 'PageRequest' }) */
-  include(...refs: ImportRef[]): this {
-    this.bases.push(...refs);
-    return this;
-  }
-}
-
-export function dtoField(field: Field | DtoArrayFieldDef | DtoObjectFieldDef): DtoField {
-  return new DtoField(field);
-}
-
-/** Structural check — DtoMessage instances may come from a different module copy, so instanceof is unreliable. */
-export function isDtoMessage(v: unknown): v is DtoMessage {
-  if (typeof v !== 'object' || v === null) return false;
-  return (v as Record<string, unknown>).type === 'dto';
-}
-
-/** Structural check — a DtoField wraps a Field in a .field property and has no .type of its own. */
-export function isDtoField(v: unknown): v is DtoField {
-  if (typeof v !== 'object' || v === null) return false;
-  return 'field' in v && !('type' in v);
-}
-
-export function dtoArrayField(def: { items: DtoField | DtoMessage } & Omit<BaseField, 'name'>): DtoArrayField {
-  // Items stay as-is: an inline DtoField is rendered inline, a DtoMessage is
-  // referenced by name (the driver renders Type.Array(<DtoName>)).
-  return new DtoArrayField({ name: '', type: 'array', jsType: 'array', ...def });
-}
-
-export function dtoObjectField(def: { properties: Record<string, DtoField> } & Omit<BaseField, 'name'>): DtoObjectField {
-  return new DtoObjectField({ name: '', type: 'object', jsType: 'object', ...def });
-}
-
-function buildMessage(name: string, direction: DtoDirection, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  const message = new DtoMessage(name, direction, fields, description);
-  // Write back the DTO field name from the map key (safe: DtoField instances
-  // are created per DTO, never shared).
-  for (const key of Object.keys(message.fields)) {
-    const df = message.fields[key];
-    if (!(df instanceof DtoField)) {
-      const got = df === null || df === undefined ? String(df) : `${(df as object).constructor.name ?? typeof df}`;
-      throw new Error(
-        `[dto] DTO "${name}" field "${key}" must be a DtoField (created with dtoField()/dtoArrayField()/dtoObjectField()), got ${got}. ` +
-        `Did you pass enumField(...) directly? Use dtoField(enumField({...})) instead.`
-      );
-    }
-    df.name = key;
-    df.schema = message;
-    // Custom (inline) fields are owned by this DTO: write back name + schema.
-    // Fields picked via from() share the database Field instance whose
-    // name/schema already point to the table — leave them untouched.
-    if (df.field.schema === undefined) {
-      df.field.name = key;
-      df.field.schema = message;
-    }
-    writeBackNested(df, message);
-  }
-  return message;
-}
-
-/** Write back name/schema on nested DTO fields (array items, object
- *  properties) — both plain-Field containers (objectField/arrayField) and
- *  DtoField containers (dtoObjectField/dtoArrayField). DtoMessage item
- *  references are skipped — they carry their own identity. */
-function writeBackNested(df: DtoField, message: DtoMessage): void {
-  const f = df.field;
-  if (f.type === 'array') {
-    const items = f.items;
-    if (isDtoMessage(items)) return;
-    if (isDtoField(items)) {
-      writeBackNested(items, message);
-      return;
-    }
-    walkContainer(items, writeBackLeaf(message));
-    return;
-  }
-  if (f.type === 'object') {
-    for (const [key, child] of Object.entries(f.properties)) {
-      if (isDtoField(child)) {
-        child.name = key;
-        child.schema = message;
-        if (child.field.schema === undefined) {
-          child.field.name = key;
-          child.field.schema = message;
-        }
-        writeBackNested(child, message);
-      } else {
-        writeBackLeaf(message)(child, key);
-      }
-    }
-  }
-}
-
-/** Name/schema write-back for a plain Field (own fields only — shared
- *  instances keep their original identity). */
-function writeBackLeaf(message: DtoMessage): (f: Field, key?: string) => void {
-  return (f, key) => {
-    if (key !== undefined && f.schema === undefined) {
-      f.name = key;
-      f.schema = message;
-    }
-  };
-}
-
-export function buildInput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  const message = buildMessage(name, DtoDirection.Input, fields, description);
-  // Rule A — set optionality from the DB column rule (skips fields the author
-  // already set): nullable / default → optional, else required.
-  // PK columns are always required.
-  for (const field of Object.values(message.fields)) {
-    if (field.optional !== undefined) continue;
-    const f = field.field as Field;
-    if (f.schema?.type !== 'table') continue;
-    const table = f.schema as TableSchema;
-    field.optional = table.isPk(f) ? false : f.optional !== false || f.default !== undefined;
-  }
-  return message;
-}
-
-export function buildOutput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  return buildMessage(name, DtoDirection.Output, fields, description);
-}
-
-export function buildQuery(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  const message = buildMessage(name, DtoDirection.Query, fields, description);
-  // Rule B: query/search fields are always optional.
-  for (const field of Object.values(message.fields)) field.optional = true;
-  return message;
-}
-
-export function buildPk(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  const message = buildMessage(name, DtoDirection.Pk, fields, description);
-  // Rule P: PK locator fields are required, other fields are optional.
-  for (const field of Object.values(message.fields)) {
-    if (field.optional !== undefined) continue;
-    const f = field.field as Field;
-    const table = f.schema?.type === 'table' ? (f.schema as TableSchema) : undefined;
-    field.optional = table !== undefined && table.isPk(f) ? false : true;
-  }
-  return message;
-}
-
-/** Field-collection source a DTO can project from: a DB table, another DTO
- *  message (protocol fields keep their names), or an entity (which may carry
- *  aggregate fields). */
-export type DtoFieldSource = TableSchema | DtoMessage | EntitySchema;
-
-function ownsField(source: DtoFieldSource, field: Field | DtoArrayFieldDef | DtoObjectFieldDef): boolean {
-  if (isDtoMessage(source)) {
-    return Object.values(source.fields).some((df) => df.field === field);
-  }
-  return Object.values(source.columns).some((c) => c === field);
-}
-
-/** Project fields from a field-collection source (table, DTO message or
- *  entity) and wrap them as DTO fields (aligned with dto.from). Shared Field
- *  instances keep their original identity — the projection references them. */
-export function from(
-  source: DtoFieldSource,
-  fields: (Field | DtoArrayFieldDef | DtoObjectFieldDef)[],
-): Record<string, DtoField> {
-  const out: Record<string, DtoField> = {};
-  for (const field of fields) {
-    if (!ownsField(source, field)) {
-      throw new Error(`dto.from(${source.name}): field ${field.name} does not belong to this ${isDtoMessage(source) ? 'dto' : source.type}`);
-    }
-    // DB columns map to camelCase interface names (mer_id → merId); aggregate
-    // field names are already camel and pass through; DTO message fields are
-    // protocol names themselves and stay untouched.
-    out[isDtoMessage(source) ? field.name : toCamelCase(field.name)] = dtoField(field);
-  }
-  return out;
+import { BaseField, CollectionSchemaBase, Field, Operator, SchemaBase, walkContainer } from './dsl.js';
+import { TableSchema } from './db.js';
+import type { EntitySchema } from './entity.js';
+import type { ImportBase } from './import-base.js';
+import { toCamelCase } from '@pylonts/core';
+
+// Interface (DTO) field definitions.
+// Naming convention: all DTO types and builders use the Dto prefix.
+// A DtoField stores the database Field and the API-only extras separately.
+
+/** Re-export — Operator lives on the DSL level (see dsl.ts). */
+export type { Operator } from './dsl.js';
+
+/** Re-export — ImportBase lives on its own module (see import-base.ts). */
+export type { ImportBase } from './import-base.js';
+
+/** Re-export — MockDescriptor lives on its own module (see mock.ts). */
+export type { MockDescriptor } from './mock.js';
+
+/**
+ * Reference to an existing TypeBox base schema by its import location.
+ * Serializable metadata: the driver renders `import { name } from 'from'`
+ * and `Type.Intersect([name, ...])` — the runtime schema is never loaded by the DSL.
+ */
+export interface ImportRef extends ImportBase {
+  /**
+   * Generic type arguments for the base schema (e.g. PageResult(OrderRow)).
+   * Two forms, both local DTOs:
+   *   string     — the DTO export name
+   *   DtoMessage — the DTO instance itself; the driver resolves it to its name
+   */
+  args?: (string | DtoMessage)[];
+}
+
+export type DtoArrayFieldDef = BaseField & {
+  type: 'array';
+  jsType: 'array';
+  /** Element type: inline DtoField, or a reference to an existing DTO (rendered by name) */
+  items: DtoField | DtoMessage;
+};
+
+export type DtoObjectFieldDef = BaseField & {
+  type: 'object';
+  jsType: 'object';
+  properties: Record<string, DtoField>;
+};
+
+export class DtoField implements SchemaBase {
+  /** DTO 语义字段名（接口字段名），与 field.name（数据库列名）含义不同。
+   *  构造时未知，由 buildMessage 从 map key 反写。 */
+  name: string;
+  /** 字段描述 */
+  description?: string;
+  /** 所属容器（buildMessage / defineRouteData / definePageData 反写） */
+  schema?: CollectionSchemaBase;
+  field: Field | DtoArrayFieldDef | DtoObjectFieldDef;
+  pattern?: string;
+  optional?: boolean;
+  operator?: Operator;
+  /** TypeBox default annotation (API contract level); falls back to field.default (DB default) */
+  default?: unknown;
+  /** Optional reference to another DtoField — this field reuses the referenced field's type/constraints */
+  ref?: DtoField;
+
+  constructor(field: Field | DtoArrayFieldDef | DtoObjectFieldDef) {
+    this.name = '';
+    this.field = field;
+  }
+
+  setPattern(value: string): this {
+    this.pattern = value;
+    return this;
+  }
+
+  setDescription(value: string): this {
+    this.description = value;
+    return this;
+  }
+
+  getDescription(): string | undefined {
+    return this.description;
+  }
+
+  /** True when this field wraps a DB column (picked via from()); false for inline fields. */
+  isColumn(): boolean {
+    return this.field.schema?.type === 'table';
+  }
+
+  setOptional(value: boolean): this {
+    this.optional = value;
+    return this;
+  }
+
+  /** Set a default value — emitted as a TypeBox schema default annotation */
+  setDefault(value: unknown): this {
+    this.default = value;
+    return this;
+  }
+
+  /** Reference another DtoField — this field reuses the referenced field's type/constraints */
+  setRef(value: DtoField): this {
+    this.ref = value;
+    return this;
+  }
+
+  /** 查询比较操作符（query 方向字段）。Rule B: 查询字段恒为可选 */
+  setOperator(value: Operator): this {
+    this.operator = value;
+    return this;
+  }
+
+  /** optional 优先于 field.optional */
+  isOptional(): boolean {
+    if (this.optional !== undefined) return this.optional;
+    return this.field.optional ?? false;
+  }
+}
+
+export class DtoArrayField extends DtoField {
+  declare field: DtoArrayFieldDef;
+
+  /** Element type: inline DtoField or a referenced DtoMessage (rendered by name). */
+  items(): DtoField | DtoMessage {
+    return this.field.items;
+  }
+}
+
+export class DtoObjectField extends DtoField {
+  declare field: DtoObjectFieldDef;
+
+  properties(): Record<string, DtoField> {
+    return this.field.properties;
+  }
+}
+
+export enum DtoDirection {
+  Input = 'input',
+  Output = 'output',
+  Query = 'query',
+  Pk = 'pk',
+}
+
+export class DtoMessage implements CollectionSchemaBase {
+  type = 'dto';
+  name: string;
+  description?: string;
+  /** 方向：输入或输出 */
+  direction: DtoDirection;
+  fields: Record<string, DtoField>;
+  /** TypeBox base schemas to intersect with at generation time (e.g. PageRequest) */
+  bases: ImportRef[] = [];
+
+  constructor(name: string, direction: DtoDirection, fields: Record<string, DtoField>, description?: string) {
+    this.name = name;
+    this.direction = direction;
+    this.fields = fields;
+    this.description = description;
+  }
+
+  /** 引用已存在的 TypeBox base schema，例如 include({ from: '@pylonts/core', name: 'PageRequest' }) */
+  include(...refs: ImportRef[]): this {
+    this.bases.push(...refs);
+    return this;
+  }
+}
+
+export function dtoField(field: Field | DtoArrayFieldDef | DtoObjectFieldDef): DtoField {
+  return new DtoField(field);
+}
+
+/** Structural check — DtoMessage instances may come from a different module copy, so instanceof is unreliable. */
+export function isDtoMessage(v: unknown): v is DtoMessage {
+  if (typeof v !== 'object' || v === null) return false;
+  return (v as Record<string, unknown>).type === 'dto';
+}
+
+/** Structural check — a DtoField wraps a Field in a .field property and has no .type of its own. */
+export function isDtoField(v: unknown): v is DtoField {
+  if (typeof v !== 'object' || v === null) return false;
+  return 'field' in v && !('type' in v);
+}
+
+export function dtoArrayField(def: { items: DtoField | DtoMessage } & Omit<BaseField, 'name'>): DtoArrayField {
+  // Items stay as-is: an inline DtoField is rendered inline, a DtoMessage is
+  // referenced by name (the driver renders Type.Array(<DtoName>)).
+  return new DtoArrayField({ name: '', type: 'array', jsType: 'array', ...def });
+}
+
+export function dtoObjectField(def: { properties: Record<string, DtoField> } & Omit<BaseField, 'name'>): DtoObjectField {
+  return new DtoObjectField({ name: '', type: 'object', jsType: 'object', ...def });
+}
+
+function buildMessage(name: string, direction: DtoDirection, fields: Record<string, DtoField>, description?: string): DtoMessage {
+  const message = new DtoMessage(name, direction, fields, description);
+  // Write back the DTO field name from the map key (safe: DtoField instances
+  // are created per DTO, never shared).
+  for (const key of Object.keys(message.fields)) {
+    const df = message.fields[key];
+    if (!(df instanceof DtoField)) {
+      const got = df === null || df === undefined ? String(df) : `${(df as object).constructor.name ?? typeof df}`;
+      throw new Error(
+        `[dto] DTO "${name}" field "${key}" must be a DtoField (created with dtoField()/dtoArrayField()/dtoObjectField()), got ${got}. ` +
+        `Did you pass enumField(...) directly? Use dtoField(enumField({...})) instead.`
+      );
+    }
+    df.name = key;
+    df.schema = message;
+    // Custom (inline) fields are owned by this DTO: write back name + schema.
+    // Fields picked via from() share the database Field instance whose
+    // name/schema already point to the table — leave them untouched.
+    if (df.field.schema === undefined) {
+      df.field.name = key;
+      df.field.schema = message;
+    }
+    writeBackNested(df, message);
+  }
+  return message;
+}
+
+/** Write back name/schema on nested DTO fields (array items, object
+ *  properties) — both plain-Field containers (objectField/arrayField) and
+ *  DtoField containers (dtoObjectField/dtoArrayField). DtoMessage item
+ *  references are skipped — they carry their own identity. */
+function writeBackNested(df: DtoField, message: DtoMessage): void {
+  const f = df.field;
+  if (f.type === 'array') {
+    const items = f.items;
+    if (isDtoMessage(items)) return;
+    if (isDtoField(items)) {
+      writeBackNested(items, message);
+      return;
+    }
+    walkContainer(items, writeBackLeaf(message));
+    return;
+  }
+  if (f.type === 'object') {
+    for (const [key, child] of Object.entries(f.properties)) {
+      if (isDtoField(child)) {
+        child.name = key;
+        child.schema = message;
+        if (child.field.schema === undefined) {
+          child.field.name = key;
+          child.field.schema = message;
+        }
+        writeBackNested(child, message);
+      } else {
+        writeBackLeaf(message)(child, key);
+      }
+    }
+  }
+}
+
+/** Name/schema write-back for a plain Field (own fields only — shared
+ *  instances keep their original identity). */
+function writeBackLeaf(message: DtoMessage): (f: Field, key?: string) => void {
+  return (f, key) => {
+    if (key !== undefined && f.schema === undefined) {
+      f.name = key;
+      f.schema = message;
+    }
+  };
+}
+
+export function buildInput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
+  const message = buildMessage(name, DtoDirection.Input, fields, description);
+  // Rule A — set optionality from the DB column rule (skips fields the author
+  // already set): nullable / default → optional, else required.
+  // PK columns are always required.
+  for (const field of Object.values(message.fields)) {
+    if (field.optional !== undefined) continue;
+    const f = field.field as Field;
+    if (f.schema?.type !== 'table') continue;
+    const table = f.schema as TableSchema;
+    field.optional = table.isPk(f) ? false : f.optional !== false || f.default !== undefined;
+  }
+  return message;
+}
+
+export function buildOutput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
+  return buildMessage(name, DtoDirection.Output, fields, description);
+}
+
+export function buildQuery(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
+  const message = buildMessage(name, DtoDirection.Query, fields, description);
+  // Rule B: query/search fields are always optional.
+  for (const field of Object.values(message.fields)) field.optional = true;
+  return message;
+}
+
+export function buildPk(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
+  const message = buildMessage(name, DtoDirection.Pk, fields, description);
+  // Rule P: PK locator fields are required, other fields are optional.
+  for (const field of Object.values(message.fields)) {
+    if (field.optional !== undefined) continue;
+    const f = field.field as Field;
+    const table = f.schema?.type === 'table' ? (f.schema as TableSchema) : undefined;
+    field.optional = table !== undefined && table.isPk(f) ? false : true;
+  }
+  return message;
+}
+
+/** Field-collection source a DTO can project from: a DB table, another DTO
+ *  message (protocol fields keep their names), or an entity (which may carry
+ *  aggregate fields). */
+export type DtoFieldSource = TableSchema | DtoMessage | EntitySchema;
+
+function ownsField(source: DtoFieldSource, field: Field | DtoArrayFieldDef | DtoObjectFieldDef): boolean {
+  if (isDtoMessage(source)) {
+    return Object.values(source.fields).some((df) => df.field === field);
+  }
+  return Object.values(source.columns).some((c) => c === field);
+}
+
+/** Project fields from a field-collection source (table, DTO message or
+ *  entity) and wrap them as DTO fields (aligned with dto.from). Shared Field
+ *  instances keep their original identity — the projection references them. */
+export function from(
+  source: DtoFieldSource,
+  fields: (Field | DtoArrayFieldDef | DtoObjectFieldDef)[],
+): Record<string, DtoField> {
+  const out: Record<string, DtoField> = {};
+  for (const field of fields) {
+    if (!ownsField(source, field)) {
+      throw new Error(`dto.from(${source.name}): field ${field.name} does not belong to this ${isDtoMessage(source) ? 'dto' : source.type}`);
+    }
+    // DB columns map to camelCase interface names (mer_id → merId); aggregate
+    // field names are already camel and pass through; DTO message fields are
+    // protocol names themselves and stay untouched.
+    out[isDtoMessage(source) ? field.name : toCamelCase(field.name)] = dtoField(field);
+  }
+  return out;
 }