@pylonts/dsl 1.1.20 → 1.1.21

package/docs/aggregate-implementation.md

@@ -0,0 +1,174 @@
+# 聚合 DSL 极简落盘记录
+
+> 日期：本次会话
+> 范围：`@pylonts/dsl` 聚合声明层
+> 目标：让“多对一 / 一对多”先落地，扩展表（一对一）只设计不实现。
+
+## 1. 背景
+
+聚合判断标准已收敛为：
+
+> 创建 / 保存 / 删除时，是否必须一起做？
+> - 是 → 聚合成员
+> - 否 → 不聚合（引用）
+
+本次落盘只实现最常用的“一对多”聚合成员：
+
+```ts
+defineAggregate({
+  root: order,
+  members: {
+    items: [orderItem],
+  },
+});
+```
+
+- 数组成员 `[orderItem]` = 一对多；
+- 非数组成员（扩展表 / 一对一）暂不落代码，保留设计。
+
+## 2. 本次落盘改了什么
+
+### 2.1 源码
+
+| 文件 | 改动 |
+|---|---|
+| `dsl/src/aggregate.ts` | 极简化 `defineAggregate` |
+| `dsl/src/repository.ts` | 注释同步为 `FK / extends` |
+
+`dsl/src/aggregate.ts` 关键变化：
+
+- 去掉 `name` 必填，聚合名自动取 `root.name`；
+- `members` 类型简化为：
+
+```ts
+Record<string, TableSchema | TableSchema[]>
+```
+
+- 删除 `via` / `one` 复杂配置；
+- 数组成员校验：
+  - 必须恰好包含一张表；
+  - 该表必须有且仅有一个外键指向 root 主键；
+  - 多个外键指向 root 时明确报错；
+- 非数组成员（扩展表）暂不支持，明确报错。
+
+### 2.2 测试
+
+| 文件 | 改动 |
+|---|---|
+| `dsl/test/aggregate.test.ts` | 改为新极简 API，并增加“非数组成员暂不支持”测试 |
+| `dsl/test/repository.test.ts` | 改为新极简 API |
+
+### 2.3 文档
+
+| 文件 | 改动 |
+|---|---|
+| `dsl/docs/aggregate.md` | 示例去掉 `name`，成员表达改为数组/扩展表，同步扩展表规则 |
+| `dsl/docs/table.md` | 新增“扩展表（extends）”设计说明，标注暂不落代码 |
+| `dsl/docs/aggregate-implementation.md` | 本文档 |
+
+## 3. 当前 API 形态
+
+```ts
+import { defineAggregate } from '@pylonts/dsl';
+
+const orderAggregate = defineAggregate({
+  root: order,
+  members: {
+    items: [orderItem],
+  },
+});
+```
+
+约束：
+
+- `root` 必须有主键；
+- `members` 的数组元素必须是普通表；
+- 数组元素必须有外键指向 `root` 的主键；
+- 如果有多条外键指向 root，必须收敛为一条，否则无法自动推导。
+
+## 4. 如何验证
+
+在仓库根目录或 `dsl/` 目录执行。
+
+### 4.1 运行 DSL 测试
+
+```bash
+# 方式一：workspace
+npm test --workspace @pylonts/dsl
+
+# 方式二：进入 dsl 目录
+cd dsl
+npm test
+```
+
+可只跑聚合相关测试：
+
+```bash
+cd dsl
+npx vitest run test/aggregate.test.ts test/repository.test.ts
+```
+
+预期结果：
+
+- `aggregate.test.ts` 全部通过；
+- `repository.test.ts` 全部通过；
+- 新增的“非数组成员暂不支持”用例通过。
+
+### 4.2 类型检查
+
+```bash
+npm run typecheck --workspace @pylonts/dsl
+```
+
+或：
+
+```bash
+cd dsl
+npm run typecheck
+```
+
+预期结果：无 TypeScript 错误。
+
+### 4.3 构建
+
+```bash
+npm run build --workspace @pylonts/dsl
+```
+
+或：
+
+```bash
+cd dsl
+npm run build
+```
+
+预期结果：`dist/` 正常生成。
+
+### 4.4 全量回归（如项目要求）
+
+在仓库根按项目现有脚本执行：
+
+```bash
+npm run lint all
+npm run typecheck
+```
+
+或按仓库实际脚本执行 `api tsc + lint all`。
+
+## 5. 验证重点
+
+1. 新的极简 `defineAggregate` 能正常声明聚合；
+2. 不再需要传 `name`；
+3. `members.items` 直接是 `[orderItem]`，不再有 `via` / `one`；
+4. 没有外键指向 root 时会报错；
+5. 非数组成员会报“扩展表未实现”；
+6. 旧测试已全部迁移到新 API。
+
+## 6. 暂未实现（保留设计）
+
+- 扩展表 `extends: root`：一对一成员；
+- 非数组成员：当前会抛错；
+- Repository 生成器：仍未实现；
+- flow 调用 repository：仍未实现。
+
+这些内容在 `dsl/docs/aggregate.md` 和 `dsl/docs/table.md` 中保留设计。

package/docs/aggregate.md

@@ -24,17 +24,54 @@
 | 应用服务编排 | service_schema + flow ✅ | 已具备 |
 | 防腐层 | ThirdServiceSchema 只隔离 | 缺模型映射 |
 
-## 2. 扩展一：AggregateSchema（核心）
+## 2. 什么情况下需要聚合？
+
+**核心判断标准**：
+
+> 创建 / 保存 / 删除时，是否必须一起做？
+> - 是 → 聚合（成员）
+> - 否 → 不聚合（引用）
+
+### 2.1 成员 vs 引用
+
+| 维度 | 聚合成员 | 聚合间引用 |
+|------|---------|-----------|
+| 生命周期 | 与根同生共死 | 独立生命周期 |
+| 创建 | 随根一起创建 | 不随根创建 |
+| 保存 | 随根一起保存 | 不随根保存 |
+| 删除 | 随根级联删除 | 不随根删除 |
+| 关联 | 成员表 FK 指向根 / 扩展表 extends 根 | 本表 FK 指向其他聚合根 |
+| 示例 | order_item / order_address 快照 | order.user_id / order.address_id |
+
+### 2.2 案例：地址可复用 vs 地址快照
+
+**场景**：一个订单对应一个地址，但地址可以被多个订单复用。
+
+- 如果地址可复用 → 不是聚合成员，是引用：
+  - 创建订单不会创建地址；
+  - 删除订单不会删除地址；
+  - 多个订单可以指向同一个地址；
+  - 建模为 `references: { address: 'AddressAggregate' }`，外键不需要 unique。
+
+- 如果地址是下单时的快照（copy）→ 是聚合成员：
+  - 下单时复制一份地址到订单；
+  - 之后修改地址簿不影响已下单订单；
+  - 删除订单时该快照一起删除；
+  - 建模为 `members: { address: orderAddress }`；
+  - 此时 `orderAddress` 应为**扩展表**（`extends: order`），主键与根主键同义、类型一致，天然保证一对一。
+
+**lint 规则**：声明为一对一成员时，成员表必须是扩展表（`extends` 指向根），主键与根主键同义且类型一致；否则它要么是一对多，要么应改为 references。
+
+## 3. 扩展一：AggregateSchema（核心）
 
 **作用**：显式声明"哪些表属于同一个聚合、谁是聚合根、成员如何挂载、跨成员不变式、聚合间引用规则"。这是把"多表一致性从约定变约束"的落点。
 
 ```ts
 defineAggregate({
-  name: 'Order',
   root: ordersTable,                        // 聚合根表
-  members: {                                // 成员表（"包含几个 table schema" 的声明）
-    items:   { table: orderItemsTable,  via: 'order_no' },   // 1:N，外键挂根
-    address: { table: orderAddressTable, via: 'order_no', one: true },  // 1:1
+  members: {                                // 成员表：数组=一对多，非数组=一对一
+    items:   [orderItemsTable],             // 1:N，外键自动推导
+    address: orderAddressTable,             // 1:1，扩展表
   },
   invariants: [                             // 跨成员表不变式，挂聚合上，可被生成代码消费
     { name: 'total = sum(items.price * items.qty)',
@@ -47,8 +84,8 @@ defineAggregate({
 | 声明项 | 含义 | 缺了会怎样 |
 |--------|------|-----------|
 | `root` | 谁是聚合根 | 分不清一致性入口 |
-| `members` | 包含哪几个 table schema | "包含"只是列表，无结构 |
-| `members[i].via` | 成员表靠哪个外键挂根 | 工具无法推导 join / 级联关系 |
+| `members` | 包含哪几个 table schema；数组=普通表=1:N，非数组=扩展表=1:1 | 无法推导成员关系 |
+| 成员外键 | 由 TableSchema.foreignKeys / extends 自动推导 | 工具无法推导 join / 级联关系 |
 | `invariants` | 跨成员一致性规则 | "总额=Σ明细"又回到 flow 里手工写 |
 | `references` | 聚合间只按 ID 引用 | 无法 lint 跨聚合直接持表引用 |
 
@@ -60,7 +97,7 @@ defineAggregate({
 
 **多表映射三种模式**（聚合↔表）：A 单表=单聚合（1:1，几乎透明）；B 一聚合=多表（1:N，最常见，Order 案例）；C 多聚合共享表（N:1，DDD 不推荐）。
 
-## 3. 扩展二：RepositorySchema（可推导，也可显式声明）
+## 4. 扩展二：RepositorySchema（可推导，也可显式声明）
 
 **作用**：聚合粒度的存储入口，把"哪些表一起查、怎么拼成聚合"的知识从 service flow 下沉到仓储。调用方只面对领域概念（Order），不面对表。
 
@@ -76,7 +113,7 @@ defineRepository({
 
 **聚合内 join 下沉、聚合间禁止 join**：
 
-- 聚合内：加载整个 Order（根 + 明细 + 地址）由 Repository 内部完成，调用方一行，join 知识声明在 `members[].via`；
+- 聚合内：加载整个 Order（根 + 明细 + 地址）由 Repository 内部完成，调用方一行，join 知识由成员表 `foreignKeys` / `extends` 自动推导；
 - 聚合间：只按 ID 引用，跨聚合 join 是 DDD 禁止的；展示商品名这类信息走读模型 / 查询服务（CQRS 的 Q 侧），或应用服务分步查 + 内存组装。
 
 **分层对照**：
@@ -87,7 +124,7 @@ defineRepository({
 | Repository | **聚合** | orders + order_items 一个事务 | **本扩展** |
 | DAO | **表** | 单表一条 SQL | dao_schema ✅ |
 
-## 4. 扩展三：引入支持 DDD 的 TS 库（选型，待决策）
+## 5. 扩展三：引入支持 DDD 的 TS 库（选型，待决策）
 
 dsl 是**声明期**（`defineAggregate` 声明结构），引入的库是**运行期**（代码跑起来时持久化/发事件）。两者互补，不冲突——声明可翻译为运行期库的配置。
 
@@ -101,9 +138,9 @@ dsl 是**声明期**（`defineAggregate` 声明结构），引入的库是**运
 
 **建议**：运行时持久化参考/选用 **MikroORM**（聚合持久化设计最完整）；领域事件参考 **Remesh**。dsl 的 `AggregateSchema` 声明层本身无现成开源，属本项目的增量设计空间。
 
-## 5. 落地步骤（待办，未开工）
+## 6. 落地步骤（待办，未开工）
 
-1. `AggregateSchema` 类型 + `defineAggregate` + 定义期校验（root 必须在其表内、via 外键存在、成员表不能是其他聚合的 root 等）；
+1. `AggregateSchema` 类型 + `defineAggregate` + 定义期校验（root 必须在其表内、成员表必须有外键指向 root 或 extends root、成员表不能是其他聚合的 root 等）；
 2. `RepositorySchema` 类型 + `defineRepository`（或从 aggregate 自动推导生成）；
 3. `gen` 生成 Repository 代码：加载/保存/删除三套骨架 + 同事务包装（`@Trans()` 从声明推导）；
 4. `lint` 聚合边界检查：聚合外禁止直接改成员表、聚合间禁止跨表引用；

package/docs/dto.md

@@ -1,107 +1,131 @@
-# 定义 DTO（四种方向）
-
-DTO 描述接口出入参。方向决定可选性规则，由各方向工厂设置；**规则统一只在 `field.optional === undefined` 时生效**（作者已显式设置的跳过）：
-
-| 构建器 | 方向 | 可选性规则 |
-|---|---|---|
-| `buildInput` | input | 按 DB 列规则：主键 → 必填；可空（未写 `optional` 或 `optional: true`）/ 有默认 → 可选；`optional: false` 无默认 → 必填 |
-| `buildOutput` | output | 不设置（保持字段构建器/作者设置） |
-| `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';
-
-// 输入：新增订单
-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]));
-
-// 转发：透传第三方方法消息（wire-format 字段名保持协议原样，不转 camelCase）
-buildOutput('BalanceResult', from(queryBalance.results, [queryBalance.results.fields.balance]));
-```
-
-- **表源**：DTO 字段名转 camelCase（`mer_id` → `merId`），与 DB 列名（snake_case）分离。
-- **第三方方法源**：字段名即线格式协议名（`out_trade_no`、`appId`），保持不变。
-- `from()` 本身不做任何可选性推断——推断在各方向工厂，且按字段的 schema 判断：共享实体列按列规则推断（Rule A），wire 自有字段保留声明值。
-
-## 独立字段
-
-不来自表的内联字段直接用 `dtoField(...)` 包装任意字段构建器，可加 `pattern`、`optional`、`operator`、`default`。
-
-```ts
-dtoField(stringField({ maxLength: 32 })).setOperator('like')
-dtoField(intField()).setDefault(0)        // TypeBox default 注解
-```
-
-## 字段引用规格（Reference Spec）
-
-`DtoField` 通过 `setRef(other)` 或共享字段实例引用其他字段，表达"本字段来源于 X"。**引用不是任意的**——只有业务契约 DTO（controller/service 消费的 `dto_schema/{app}` 或 `dto_schema/common` DTO）的字段可以作为引用方，且只能引用三类被引用方：
-
-| # | 引用 | 语法 | 语义 |
-|---|---|---|---|
-| 1 | **field 引用** | `dtoField(table.columns.x)`（共享实例）或 `setRef` 指向包装表列的 DtoField | 与数据库字段同义（来源：库） |
-| 2 | **token 引用** | `fromToken(token, [...])` 或 `setRef(token 字段)` | 字段来源于登录身份（服务端注入） |
-| 3 | **third 引用** | `setRef(third 消息字段)` | 字段来源于第三方消息（参数或结果） |
-
-**方向约束**：
-
-- 引用方：业务契约 DTO 的字段；
-- 被引用方：token 字段 / third 消息字段 / 表列 field——**业务 DTO 之间不能互相引用**（convert 的 sources/target 各自独立，映射由搬运生成推导，不靠 DTO 互 ref）；
-- third 字段、token 字段不可反向引用业务 DTO；
-- ref 链无环（渲染期强校验，循环引用报错）。
-
-**对 convert 自动搬运的意义**：同源判定 = ref 链终端 / 共享 field 实例，且只有规格内合法引用构成可推导搬运——业务 DTO ← third（防腐翻译，`setRef(thirdField)` = "本字段从 third 参数/结果来"）、业务 DTO ← entity（共享表列实例）都是可自动生成搬运的映射；越界引用是声明错误。
-
-> entity 列是裸 `Field` 实例：DTO 字段 `dtoField(order.columns.x)` 与 entity 列共享同一实例即构成 field 引用。
-
-### token 引用的注入与 readOnly
-
-`fromToken(token, fields)` 是 token 引用的标准入口：每个投影字段 `setRef(token 字段)`（复用类型/约束）+ 标记 `injectFrom`（服务端注入）。typebox 生成物中注入字段渲染为 **`Type.Optional(...)` + `readOnly: true` 注解**（JSON Schema annotation）——服务器字段，客户端不得上送：
-
-```ts
-id: Type.Optional(Type.Integer({ readOnly: true })),
-```
-
-同时生成非枚举 `__inject` 适配器，fastify RPC 层在进 controller 前执行 `body.k = token.k` 从登录身份填充——**客户端即使上送也会被覆盖**（上送无效）。三层闭环：声明 readOnly（不可上送语义）+ Optional（可不传）+ 运行时覆盖（上送无效）。
-
-注意：**只有 `fromToken()` 自动设置 `injectFrom`**；手写 `setRef(token 字段)` 只表达引用关系，不触发注入渲染（如需注入须显式标记或改走 fromToken）。
-
-## 默认值
-
-- `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`。
+# 定义 DTO（四种方向）
+
+DTO 描述接口出入参。方向决定可选性规则，由各方向工厂设置；**规则统一只在 `field.optional === undefined` 时生效**（作者已显式设置的跳过）：
+
+| 构建器 | 方向 | 可选性规则 |
+|---|---|---|
+| `buildInput` | input | 按 DB 列规则：主键 → 必填；可空（未写 `optional` 或 `optional: true`）/ 有默认 → 可选；`optional: false` 无默认 → 必填 |
+| `buildOutput` | output | 不设置（保持字段构建器/作者设置） |
+| `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';
+
+// 输入：新增订单
+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]));
+
+// 转发：透传第三方方法消息（wire-format 字段名保持协议原样，不转 camelCase）
+buildOutput('BalanceResult', from(queryBalance.results, [queryBalance.results.fields.balance]));
+```
+
+- **表源**：DTO 字段名转 camelCase（`mer_id` → `merId`），与 DB 列名（snake_case）分离。
+- **第三方方法源**：字段名即线格式协议名（`out_trade_no`、`appId`），保持不变。
+- `from()` 本身不做任何可选性推断——推断在各方向工厂，且按字段的 schema 判断：共享实体列按列规则推断（Rule A），wire 自有字段保留声明值。
+
+## 独立字段
+
+不来自表的内联字段直接用 `dtoField(...)` 包装任意字段构建器，可加 `pattern`、`optional`、`operator`、`default`。
+
+```ts
+dtoField(stringField({ maxLength: 32 })).setOperator('like')
+dtoField(intField()).setDefault(0)        // TypeBox default 注解
+```
+
+## 容器字段：禁止内联嵌套（构建期校验）
+
+**DTO 不内联**——嵌套结构必须命名引用，构建期（`buildInput/buildOutput/buildQuery/buildPk` 及 `defineUtils` args）机器校验：
+
+| 形态 | 允许 | 禁止 |
+|---|---|---|
+| 数组字段 `dtoArrayField` | `items: 命名 DTO`（`items: orderItemDto` → `OrderItemDto[]`）或 `items: 标量字段`（`string[]`） | `items: dtoObjectField(...)` 内联对象元素、`items: dtoArrayField(...)` 内联数组元素 |
+| 对象字段 | 裸 `objectField(...)`（wire 格式嵌套，渲染内联 `Type.Object({...})`） | `dtoObjectField(...)`、`dtoField(dtoObjectField(...))`——DtoField 类容器必须命名引用（数组元素），或改用裸 `objectField` |
+
+**理由**：DtoField 类容器（`dtoObjectField` / `dtoArrayField`）内联时无法跨 DTO 复用，生成类型要么靠字符串拼接（`Array<{...}>`），要么塌缩（`any[]`）——命名引用让结构有单一事实来源（DTO 定义处）且生成精确类型。裸 `objectField` / `arrayField` 属于 wire 格式嵌套（随消息直接内联渲染），不在禁用范围。校验错误示例：
+
+```
+[dto] "OrderSubmitRequest" field "items": inline container elements are not allowed — array items must be a named DTO or a scalar field
+```
+
+```ts
+// ✗ 内联对象元素
+items: dtoArrayField({ items: dtoObjectField({ properties: { skuId: ..., qty: ... } }) })
+
+// ✓ 命名 DTO 引用（OrderItemDto 单独 buildOutput 声明）
+export const OrderItemDto = buildOutput('OrderItemDto', { skuId: ..., qty: ... });
+items: dtoArrayField({ items: OrderItemDto })
+```
+
+## 字段引用规格（Reference Spec）
+
+`DtoField` 通过 `setRef(other)` 或共享字段实例引用其他字段，表达"本字段来源于 X"。**引用不是任意的**——只有业务契约 DTO（controller/service 消费的 `dto_schema/{app}` 或 `dto_schema/common` DTO）的字段可以作为引用方，且只能引用三类被引用方：
+
+| # | 引用 | 语法 | 语义 |
+|---|---|---|---|
+| 1 | **field 引用** | `dtoField(table.columns.x)`（共享实例）或 `setRef` 指向包装表列的 DtoField | 与数据库字段同义（来源：库） |
+| 2 | **token 引用** | `fromToken(token, [...])` 或 `setRef(token 字段)` | 字段来源于登录身份（服务端注入） |
+| 3 | **third 引用** | `setRef(third 消息字段)` | 字段来源于第三方消息（参数或结果） |
+
+**方向约束**：
+
+- 引用方：业务契约 DTO 的字段；
+- 被引用方：token 字段 / third 消息字段 / 表列 field——**业务 DTO 之间不能互相引用**（convert 的 sources/target 各自独立，映射由搬运生成推导，不靠 DTO 互 ref）；
+- third 字段、token 字段不可反向引用业务 DTO；
+- ref 链无环（渲染期强校验，循环引用报错）。
+
+**对 convert 自动搬运的意义**：同源判定 = ref 链终端 / 共享 field 实例，且只有规格内合法引用构成可推导搬运——业务 DTO ← third（防腐翻译，`setRef(thirdField)` = "本字段从 third 参数/结果来"）、业务 DTO ← entity（共享表列实例）都是可自动生成搬运的映射；越界引用是声明错误。
+
+> entity 列是裸 `Field` 实例：DTO 字段 `dtoField(order.columns.x)` 与 entity 列共享同一实例即构成 field 引用。
+
+### token 引用的注入与 readOnly
+
+`fromToken(token, fields)` 是 token 引用的标准入口：每个投影字段 `setRef(token 字段)`（复用类型/约束）+ 标记 `injectFrom`（服务端注入）。typebox 生成物中注入字段渲染为 **`Type.Optional(...)` + `readOnly: true` 注解**（JSON Schema annotation）——服务器字段，客户端不得上送：
+
+```ts
+id: Type.Optional(Type.Integer({ readOnly: true })),
+```
+
+同时生成非枚举 `__inject` 适配器，fastify RPC 层在进 controller 前执行 `body.k = token.k` 从登录身份填充——**客户端即使上送也会被覆盖**（上送无效）。三层闭环：声明 readOnly（不可上送语义）+ Optional（可不传）+ 运行时覆盖（上送无效）。
+
+注意：**只有 `fromToken()` 自动设置 `injectFrom`**；手写 `setRef(token 字段)` 只表达引用关系，不触发注入渲染（如需注入须显式标记或改走 fromToken）。
+
+## 默认值
+
+- `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

@@ -131,6 +131,47 @@ export const audit = defineTable('audit', {
 
 > **外键是逻辑作用**：`foreignKeys` 用于定义期命名强校验与关系表达，**DDL 默认不渲染物理 FOREIGN KEY 约束**（`pylonts gen sql init` 不传 `generateForeignKeys`）。数据完整性由 Service/DAO 层保证；如需物理约束，调用 `buildCreateTableSql(schema, { generateForeignKeys: true })`。
 
+## 扩展表（extends）
+
+扩展表表示“本表是某张根表的延伸”：主键与根表主键同义、类型一致，生命周期跟随根表（创建 / 保存 / 删除一起做）。除这两条外，扩展表与普通表完全一样，可以有索引、外键、被其他表引用等。
+
+### 定义
+
+```ts
+// order 根表
+export const order = defineTable('order', {
+  ...
+  primaryKey: id,
+});
+
+// order_address 是 order 的扩展表
+const addressId = stringField({ maxLength: 32 }); // 与 order.id 同类型
+
+export const orderAddress = defineTable('order_address', {
+  extends: order,          // 声明本表是 order 的扩展
+  primaryKey: addressId,   // 主键与根主键同义
+  columns: {
+    id: addressId,
+    receiver_name: stringField({ label: '收货人', maxLength: 32, optional: false }),
+    ...
+  },
+});
+```
+
+### 规则
+
+- 扩展表的主键与根表主键同义，类型必须一致；
+- 根表不能是扩展表；
+- 扩展表不能再 `extends`（禁止链式延伸）；
+- 一个根表可以有多个扩展表；
+- 除主键和生命周期外，扩展表与普通表完全一样：可以有普通外键、索引、枚举等，也可被其他表引用；
+- 扩展表不需要像普通外键那样命名 `{phrase}_{field}`，也不需要显式声明 `foreignKeys` 来表达与根的关系，`extends` 本身就是关系。
+
+### 与聚合的关系
+
+- `members: { items: [orderItem] }`：数组 → 普通表 → 一对多；
+- `members: { address: orderAddress }`：非数组 → 扩展表 → 一对一。
+
 ## 生成 SQL
 
 见 [driver.md](./driver.md)。

package/docs/utils.md

@@ -46,7 +46,8 @@ export default {
 
 - **args**：`Record<string, DtoField>`——用 `dtoField(...)` 包装。可包装**表列**（`dtoField(order.columns.status)`，领域规则引用表字段的标准方式）或内联字段（`dtoField(stringField(...))`）。包装层反写不污染共享表列实例（与 `buildMessage` 同规则：仅内联字段写回底层）。
 - **result**：`Field | undefined`——输出是全新值（boolean 判断、decimal 计算、string 派生文案），**不是共享表列**；省略 = void 方法（防御 guard 通过时无返回值）。
-- **失败语义**：规则失败直接 `throw`（配合 flow 的 `BusinessException`/`CodeException` 通道），**不返回错误码结构**。
+- **throws**：`ExceptionSchema[] | undefined`——方法可抛的异常清单，**防御 guard 的失败契约**。flow 里 `invoke` 防御 guard 时，其 throws 自动进入流程逃逸集——调用方 service 方法的 throws 必须包含它（或 TRY 捕获）。谓词（can/is/has）不抛，无需声明。
+- **失败语义**：规则失败直接 `throw`（配合 `throws` 声明的 `BusinessException`/`CodeException` 通道），**不返回错误码结构**。
 
 ## 文件与存储约定
 
@@ -65,11 +66,11 @@ export default {
 
 从纯函数视角，方法的出口只有两种：**返回值**或**抛异常**。因此领域规则方法恰好三类：
 
-| 分类 | 命名 | 本质 | result | 失败语义 | 典型示例 |
-|---|---|---|---|---|---|
-| **1 防御 guard** | `assertXX` / `validateXX` / `ensureXX` | 条件抛错（前置校验） | `void` | **失败必抛错**，通过无返回值 | `assertCancelable`——已完成/已取消订单 throw |
-| **2 判断** | `canXX` / `isXX` / `hasXX` | 返回判定值（谓词） | `boolean` / 枚举 | 返回 false/枚举值，不抛 | `canCancel`、`isExpired`——供 flow `IF(...)` 条件位 |
-| **3 计算** | `calcXX` / `formatXX` / 动词 | 派生值计算 | 标量（金额/数量/文案） | 一般不抛（入参合法前提） | `calcTotal`——金额计算 |
+| 分类 | 命名 | 本质 | result | throws | 失败语义 | 典型示例 |
+|---|---|---|---|---|---|---|
+| **1 防御 guard** | `assertXX` / `validateXX` / `ensureXX` | 条件抛错（前置校验） | `void` | **必填**（失败契约） | **失败必抛错**，通过无返回值 | `assertCancelable`——已完成/已取消订单 throw `BusinessException` |
+| **2 判断** | `canXX` / `isXX` / `hasXX` | 返回判定值（谓词） | `boolean` | 无 | 返回 false，不抛 | `canCancel`、`isExpired`——供 flow `IF(...)` 条件位 |
+| **3 计算** | `calcXX` / `formatXX` / 动词 | 派生值计算 | 标量（金额/数量/文案） | 一般不声明 | 一般不抛（入参合法前提） | `calcTotal`——金额计算 |
 
 ### 为什么这就是全集
 
@@ -77,12 +78,18 @@ export default {
 - **防御 guard = 判断 + 抛错**：guard 内部必然先判断再 throw，是"判断"失败分支的显式化；通过时没有调用方需要的值，所以返回 `void`。
 - **void 方法只能是防御 guard**：纯函数无副作用，不返回也不抛 = 什么都没做——void 方法若默认通过、特殊状态才抛，就是 guard 的语义。
 
-### 命名与返回的一致性（可机器校验）
+### 命名与返回的一致性（机器校验，已落地）
 
-- `assert/validate/ensure` 前缀 → **必须 void**（guard：通过无值、失败抛错）；
-- `can/is/has` 前缀 → **必须 boolean 或枚举**（判断谓词）；
+- `assert/validate/ensure` 前缀 → **必须 void + 必须声明 throws**（guard：通过无值、失败抛契约异常）；
+- `can/is/has` 前缀 → **必须 boolean**（判断谓词，进 flow `IF` 条件位）；
 - 计算类 → 标量 result。
-- 命名与 result 形态不匹配（如 `canXX` 返回 void）即声明错误——lint 可按此机器校验。
+
+**双重校验**：
+
+1. **声明侧**（`pylonts lint utils`）：命名与 result 形态不匹配（如 `canXX` 返回 void、`assertXX` 返回 boolean）即违规报错；防御 guard 缺 throws 声明（失败契约缺失）同样违规。
+2. **使用侧**（flow 编译期，`defineFlow` 校验）：条件位谓词必须声明 boolean result——`IF(invoke(xxUtils.canCancel, ...))` 通过；`IF(invoke(xxUtils.assertCancelable, ...))`（void 守卫）和标量方法进 IF 直接报错，提示"守卫应 invoke 而非 IF"。
+
+**逃逸集联动**：`invoke` 防御 guard 时，guard 的 throws 自动并入流程逃逸集（与 dao/third 的 throws 同规则）——调用方 service 方法契约因此必须声明该异常（或 TRY 捕获），守卫的失败成为可验证的契约，而不是隐式冒泡。
 
 ## 建议（best practices）
 
@@ -93,7 +100,7 @@ export default {
 5. **纯函数、无 I/O**：utils 不做数据库/网络访问；需要 I/O 的规则属于 service。
 6. **表列引用用 `dtoField(table.columns.x)` 包装**：包装层反写安全，共享列实例永不被动；参数名可以与列名不同（如 `state` 包装 `status` 列）。
 7. **result 选型与命名一致**：防御 guard → **`void`** + `assert/validate/ensure` 前缀（抛错即语义）；判断 → `booleanField()`（或枚举）+ `can/is/has` 前缀（供 flow 谓词位）；计算 → `decimalField`/`intField`/`stringField` 标量。
-8. **flow 集成**：判断类可直接作 `IF(cond)` 条件位谓词（多入参靠 invoke 多槽位）；防御 guard 通过 `invoke` 在流程前置位调用。
+8. **flow 集成**：判断类可直接作 `IF(cond)` 条件位谓词（多入参靠 invoke 多槽位），`gen service --flow` 渲染为 `OrderUtils.canCancel(body.status)`；防御 guard 通过 `invoke` 在流程前置位调用，渲染为 `OrderUtils.assertCancelable(body.status);`（void、内部 throw）。**计算类绑定标量槽**：flow 声明 `slots: { total: decimalField(...) }`，`invoke(calcTotal, args, slots.total)` 渲染 `const total: string = OrderUtils.calcTotal(body.unitPrice);`，标量槽可直接进守卫比较（`IF(gt(slots.total, 100))` → `if (Number(total) > 100)`）或作后续调用的标量参数（jsType 匹配直传）。
 
 ## 生成与合并
 
@@ -101,4 +108,4 @@ export default {
 
 ## 校验
 
-`pylonts lint utils`：存储位置 + 绑定共享实例 + 文件名机器校验（`lint all` 已包含）。
+`pylonts lint utils`：存储位置 + 绑定共享实例 + 文件名 + **命名↔result 一致性**（assert/validate/ensure → void，can/is/has → boolean）机器校验（`lint all` 已包含）。使用侧谓词 boolean 校验在 flow 编译期（`defineFlow`）执行。

package/package.json

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