@pylonts/dsl 1.1.4 → 1.1.6

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 分组名（`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 命名是生成器约定，非页面语义） |
+# 管理端 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

@@ -9,7 +9,9 @@ DTO 描述接口出入参。方向决定可选性规则，由各方向工厂设
 | `buildQuery` | query | 全部可选 |
 | `buildPk` | pk | 主键字段必填，其他字段可选 |
 
-## 从表提取字段
+## 从字段集合投影
+
+`from(source, fields)` 接受两类字段集合源：**表**（`TableSchema`）或**第三方方法消息**（`ThirdMethodSchema`，见 [third-service.md](./third-service.md)），投影字段包装为 DTO 字段，字段实例与源共享，`name/schema` 保持指向源。
 
 ```ts
 import { buildInput, buildQuery, dtoField, from } from '@pylonts/dsl';
@@ -28,9 +30,14 @@ buildQuery('OrderPageQuery', {
 
 // 主键：按 id 取详情
 buildPk('OrderDetailRequest', from(order, [order.columns.id]));
+
+// 转发：透传第三方方法消息（wire-format 字段名保持协议原样，不转 camelCase）
+buildOutput('BalanceResult', from(queryBalance.results, [queryBalance.results.fields.balance]));
 ```
 
-`from(table, fields)` 提取表字段包装为 DTO 字段，字段实例与表共享，`name/schema` 保持指向表。**DTO 字段名转 camelCase**（`mer_id` → `merId`），与 DB 列名（snake_case）分离。`from()` 本身不做任何可选性推断——推断在各方向工厂。
+- **表源**：DTO 字段名转 camelCase（`mer_id` → `merId`），与 DB 列名（snake_case）分离。
+- **第三方方法源**：字段名即线格式协议名（`out_trade_no`、`appId`），保持不变。
+- `from()` 本身不做任何可选性推断——推断在各方向工厂，且按字段的 schema 判断：共享实体列按列规则推断（Rule A），wire 自有字段保留声明值。
 
 ## 独立字段
 

package/docs/table.md

@@ -1,136 +1,136 @@
-# 定义表 (TableSchema)
-
-## 字段类型
-
-| 构建器 | 类型 | jsType | MySQL 列 | 备注 |
-|---|---|---|---|---|
-| `stringField` | string | string | VARCHAR | 必填 `maxLength` |
-| `textField` | text | string | TEXT | |
-| `intField` | integer | number | INT | |
-| `bigintField` | bigint | string | BIGINT | 传输层走 string 保精度 |
-| `decimalField` | decimal | string | DECIMAL | 必填 `precision` / `scale`，传输层走 string 避免浮点误差 |
-| `booleanField` | boolean | boolean | TINYINT(1) | |
-| `dateField` | date | Date | DATE | |
-| `timeField` | time | string | TIME | |
-| `datetimeField` | datetime | Date | DATETIME | |
-| `enumField` | enum | string / number | VARCHAR(20) / TINYINT | 引用共享枚举定义，见 [enum.md](./enum.md) |
-| `jsonField` | json | object | JSON | |
-
-通用扩展属性（构建器参数）：`label`（中文标签）、`description`、`optional`、`readOnly`、`default`。
-
-**`optional` 默认语义（MySQL 惯例）**：不写 `optional` 或写 `optional: true` → 列可空，DDL 不渲染 `NOT NULL`；写 `optional: false` → 列必填（`NOT NULL`）。业务上必填的列必须显式声明。
-
-## 定义表
-
-```ts
-import { bigintField, defineTable, decimalField, stringField } from '@pylonts/dsl';
-
-const id = bigintField({ readOnly: true, label: '主键' });
-
-export const order = defineTable('order', {
-  description: '订单',
-  autoIncrement: id,
-  columns: {
-    id,
-    order_no: stringField({ label: '订单号', maxLength: 32, optional: false }),
-    amount: decimalField({ precision: 18, scale: 2, label: '金额', optional: false }),
-  },
-  primaryKey: id,
-});
-```
-
-- 字段名从 map key 反写，`columns` 里的 key 就是列名。
-- 字段实例不可跨表复用（复用同一字段实例会抛错），枚举除外。
-
-## 主键生成策略
-
-`autoIncrement` 与 `generator` 互斥，二者选一：
-
-| 属性 | 含义 | 例子 |
-|---|---|---|
-| `autoIncrement` | 引用自增主键字段，数据库负责生成值（MySQL `AUTO_INCREMENT`）。设了该属性的字段在 DTO 中自动标记为 optional（写入时不需要传） | `autoIncrement: id` |
-| `generator` | 主键由业务侧生成（非数据库自增），告诉下游工具用哪个 ID 生成器 | `generator: 'snowflake'` |
-
-```ts
-// 数据库自增主键
-export const t1 = defineTable('t1', {
-  autoIncrement: id,
-  columns: { id: bigintField({ readOnly: true, label: '主键' }) },
-  primaryKey: id,
-});
-
-// 业务生成主键（snowflake）
-export const t2 = defineTable('t2', {
-  generator: 'snowflake',
-  columns: { id: bigintField({ readOnly: true, label: '主键' }) },
-  primaryKey: id,
-});
-```
-
-## 索引
-
-```ts
-indexes: [
-  { name: 'uk_uuid', columns: c_uuid, unique: true },
-  { columns: [c_enum, c_date] },   // 名字缺省时 = 字段名 join '_'
-],
-```
-
-## 外键与短语检查链
-
-短语统一定义在 `schema/_dictionary.ts`（见 [dictionary.md](./dictionary.md)），表文件从那里 import：
-
-```ts
-// schema/_dictionary.ts
-import { defineEntityPhrase } from '@pylonts/dsl';
-
-export const bd = defineEntityPhrase({ name: 'bd', label: 'BD推广员', description: '线下拓展商户的推广人员' });
-```
-
-```ts
-// schema/bd.table.ts
-import { bigintField, defineTable } from '@pylonts/dsl';
-import { bd as bdPhrase } from './_dictionary';
-
-const bdId = bigintField({ readOnly: true, label: 'BD ID' });
-
-export const bd = defineTable('bd', {
-  description: 'BD',
-  phrase: bdPhrase,       // 链接词典条目：本表归属的实体
-  columns: { id: bdId },
-  primaryKey: bdId,
-});
-```
-
-```ts
-// schema/audit.table.ts
-import { bigintField, defineTable } from '@pylonts/dsl';
-import { bd } from './bd.table';
-
-const auditBdId = bigintField({ label: 'BD' });
-
-export const audit = defineTable('audit', {
-  description: '审核',
-  columns: {
-    bd_id: auditBdId,    // 列名必须 = 短语 + '_' + 被引用字段名
-  },
-  foreignKeys: {
-    fk_audit_bd: { columns: auditBdId, references: bd.columns.id },
-  },
-});
-```
-
-**规则（defineTable 时强制检查）**：外键字段名必须等于 `被引用表.phrase.name + "_" + 被引用字段名`。即引用 `bd.id` 的字段必须叫 `bd_id`——`bd` 来自词典（权威短语），`id` 是 `bd` 表主键。
-
-**短语口径**：`defineEntityPhrase`（实体短语）解释的**就是短语本身**——`name` 即短语词干（如 `mer`），不是实体全名。引用 `merchant` 实体的字段用短语 `mer`（`mer_id`），**不用长语**（`merchant_id`）。短语要短（mer / bd / amt 三字母左右），语义由 `label`/`description` 解释。`TableSchema.phrase` 只接受实体短语（`defineEntityPhrase` 产物）；业务短语（`defineBusinessPhrase`）用于字段命名后缀校验，见 [field-check.md](../../lint/docs/field-check.md)。
-
-- 被引用表未定义 `phrase` → 抛错（检查链要求每个被引用表都有短语）。
-- 命名不匹配 → 抛错并提示期望名，例如：
-  `foreign key bad: field must be named bd_id (phrase bd + id), got merchant_id`
-- 关联表不需要 `phrase`。
-
-> **外键是逻辑作用**：`foreignKeys` 用于定义期命名强校验与关系表达，**DDL 默认不渲染物理 FOREIGN KEY 约束**（`pylonts gen sql init` 不传 `generateForeignKeys`）。数据完整性由 Service/DAO 层保证；如需物理约束，调用 `buildCreateTableSql(schema, { generateForeignKeys: true })`。
-
-## 生成 SQL
-
+# 定义表 (TableSchema)
+
+## 字段类型
+
+| 构建器 | 类型 | jsType | MySQL 列 | 备注 |
+|---|---|---|---|---|
+| `stringField` | string | string | VARCHAR | 必填 `maxLength` |
+| `textField` | text | string | TEXT | |
+| `intField` | integer | number | INT | |
+| `bigintField` | bigint | string | BIGINT | 传输层走 string 保精度 |
+| `decimalField` | decimal | string | DECIMAL | 必填 `precision` / `scale`，传输层走 string 避免浮点误差 |
+| `booleanField` | boolean | boolean | TINYINT(1) | |
+| `dateField` | date | Date | DATE | |
+| `timeField` | time | string | TIME | |
+| `datetimeField` | datetime | Date | DATETIME | |
+| `enumField` | enum | string / number | VARCHAR(20) / TINYINT | 引用共享枚举定义，见 [enum.md](./enum.md) |
+| `jsonField` | json | object | JSON | |
+
+通用扩展属性（构建器参数）：`label`（中文标签）、`description`、`optional`、`readOnly`、`default`。
+
+**`optional` 默认语义（MySQL 惯例）**：不写 `optional` 或写 `optional: true` → 列可空，DDL 不渲染 `NOT NULL`；写 `optional: false` → 列必填（`NOT NULL`）。业务上必填的列必须显式声明。
+
+## 定义表
+
+```ts
+import { bigintField, defineTable, decimalField, stringField } from '@pylonts/dsl';
+
+const id = bigintField({ readOnly: true, label: '主键' });
+
+export const order = defineTable('order', {
+  description: '订单',
+  autoIncrement: id,
+  columns: {
+    id,
+    order_no: stringField({ label: '订单号', maxLength: 32, optional: false }),
+    amount: decimalField({ precision: 18, scale: 2, label: '金额', optional: false }),
+  },
+  primaryKey: id,
+});
+```
+
+- 字段名从 map key 反写，`columns` 里的 key 就是列名。
+- 字段实例不可跨表复用（复用同一字段实例会抛错），枚举除外。
+
+## 主键生成策略
+
+`autoIncrement` 与 `generator` 互斥，二者选一：
+
+| 属性 | 含义 | 例子 |
+|---|---|---|
+| `autoIncrement` | 引用自增主键字段，数据库负责生成值（MySQL `AUTO_INCREMENT`）。设了该属性的字段在 DTO 中自动标记为 optional（写入时不需要传） | `autoIncrement: id` |
+| `generator` | 主键由业务侧生成（非数据库自增），告诉下游工具用哪个 ID 生成器 | `generator: 'snowflake'` |
+
+```ts
+// 数据库自增主键
+export const t1 = defineTable('t1', {
+  autoIncrement: id,
+  columns: { id: bigintField({ readOnly: true, label: '主键' }) },
+  primaryKey: id,
+});
+
+// 业务生成主键（snowflake）
+export const t2 = defineTable('t2', {
+  generator: 'snowflake',
+  columns: { id: bigintField({ readOnly: true, label: '主键' }) },
+  primaryKey: id,
+});
+```
+
+## 索引
+
+```ts
+indexes: [
+  { name: 'uk_uuid', columns: c_uuid, unique: true },
+  { columns: [c_enum, c_date] },   // 名字缺省时 = 字段名 join '_'
+],
+```
+
+## 外键与短语检查链
+
+短语统一定义在 `schema/_dictionary.ts`（见 [dictionary.md](./dictionary.md)），表文件从那里 import：
+
+```ts
+// schema/_dictionary.ts
+import { defineEntityPhrase } from '@pylonts/dsl';
+
+export const bd = defineEntityPhrase({ name: 'bd', label: 'BD推广员', description: '线下拓展商户的推广人员' });
+```
+
+```ts
+// schema/bd.table.ts
+import { bigintField, defineTable } from '@pylonts/dsl';
+import { bd as bdPhrase } from './_dictionary';
+
+const bdId = bigintField({ readOnly: true, label: 'BD ID' });
+
+export const bd = defineTable('bd', {
+  description: 'BD',
+  phrase: bdPhrase,       // 链接词典条目：本表归属的实体
+  columns: { id: bdId },
+  primaryKey: bdId,
+});
+```
+
+```ts
+// schema/audit.table.ts
+import { bigintField, defineTable } from '@pylonts/dsl';
+import { bd } from './bd.table';
+
+const auditBdId = bigintField({ label: 'BD' });
+
+export const audit = defineTable('audit', {
+  description: '审核',
+  columns: {
+    bd_id: auditBdId,    // 列名必须 = 短语 + '_' + 被引用字段名
+  },
+  foreignKeys: {
+    fk_audit_bd: { columns: auditBdId, references: bd.columns.id },
+  },
+});
+```
+
+**规则（defineTable 时强制检查）**：外键字段名必须等于 `被引用表.phrase.name + "_" + 被引用字段名`。即引用 `bd.id` 的字段必须叫 `bd_id`——`bd` 来自词典（权威短语），`id` 是 `bd` 表主键。
+
+**短语口径**：`defineEntityPhrase`（实体短语）解释的**就是短语本身**——`name` 即短语词干（如 `mer`），不是实体全名。引用 `merchant` 实体的字段用短语 `mer`（`mer_id`），**不用长语**（`merchant_id`）。短语要短（mer / bd / amt 三字母左右），语义由 `label`/`description` 解释。`TableSchema.phrase` 只接受实体短语（`defineEntityPhrase` 产物）；业务短语（`defineBusinessPhrase`）用于字段命名后缀校验，见 [field-check.md](../../lint/docs/field-check.md)。
+
+- 被引用表未定义 `phrase` → 抛错（检查链要求每个被引用表都有短语）。
+- 命名不匹配 → 抛错并提示期望名，例如：
+  `foreign key bad: field must be named bd_id (phrase bd + id), got merchant_id`
+- 关联表不需要 `phrase`。
+
+> **外键是逻辑作用**：`foreignKeys` 用于定义期命名强校验与关系表达，**DDL 默认不渲染物理 FOREIGN KEY 约束**（`pylonts gen sql init` 不传 `generateForeignKeys`）。数据完整性由 Service/DAO 层保证；如需物理约束，调用 `buildCreateTableSql(schema, { generateForeignKeys: true })`。
+
+## 生成 SQL
+
 见 [driver.md](./driver.md)。

package/docs/third-service.md

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