@pylonts/dsl 1.1.20 → 1.1.22

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/task.md

@@ -0,0 +1,81 @@
+# 任务 (Task)
+
+Task 是**定时任务（定时器）**的定义——**action 闭包的第二成员**（action = controller | task | third callback，无第四种）。
+
+```
+action = trigger =
+  ① controller       —— 前端/外部调用的 RPC 入口
+  ② task             —— 定时器（cron 驱动）：到期退款、结算、提现、报表、关单
+  ③ third callback   —— 外部系统主动回调
+```
+
+- **Task 只表示定时器**（cron 驱动）。异步/事件驱动的操作归 event 体系（EventObserver / EventNotifier，待设计），不属于 task。
+- Task 是**契约**（名字 + cron + 做什么），不声明状态变化——状态变化由 journey 步骤表达。
+- Task 实现（扫描逻辑、幂等）在实现层（如 pylon-flow step）。
+
+## 定义
+
+```ts
+// task_schema/auto-refund.task.ts
+export const AutoRefundTask = defineTask({
+  name: 'AutoRefundTask',
+  label: '到期自动退款',
+  cron: '0 3 * * *',
+  description: '扫描已锁定券码 + auto_refund + valid_to<now → 按订单发起全额退款',
+});
+```
+
+## 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `name` | string | ✅ | `XxTask`（PascalCase + `Task` 后缀） |
+| `label` | string | ✅ | 中文名 |
+| `cron` | string | ✅ | 定时表达式（系统怎么触发的契约，一处看全） |
+| `description` | string | 可选 | 做什么（叙述） |
+
+## 命名与存储规则
+
+| 约定 | 规则 | 例子 |
+|---|---|---|
+| `name` | PascalCase + `Task` 后缀 | `AutoRefundTask` |
+| 导出符号 | = name | `export const AutoRefundTask` |
+| 文件位置 | `task_schema/`（项目根，与 schema/ 并列） | `task_schema/auto-refund.task.ts` |
+| 文件名 | name 去 `Task` 后缀转 kebab + `.task.ts` | `auto-refund.task.ts` |
+| 一文件一 task | loader 机器校验（仿 loadDaos/loadEntities） | 多导出/零导出报错 |
+
+## 校验
+
+- 运行时（`defineTask`）：
+  - `name` 必须以 `Task` 结尾，否则抛错
+  - `cron` 必填（task 是定时器），否则抛错
+- 存储（`loadTasks`）：
+  - 唯一合法目录是 `task_schema/` 根（一级）
+  - **导出符号 == schema name**，否则抛错
+  - 文件名 = name 去 `Task` 后缀转 kebab + `.task.ts`，否则抛错
+  - 一文件一 task（多导出/零导出报错）
+
+## 作为 action 引用
+
+Task 与 controller、third callback 并列，是 action 闭包成员，被状态迁移与 journey 步骤引用：
+
+```ts
+// journey 步骤
+{ action: AutoRefundTask, host: api, text: '到期自动退款' }
+```
+
+lint 校验：`action` 引用必须是三类之一（controller | task | third callback）且引用存在。
+
+## 与 pylon-flow 的关系
+
+pylon-flow 的 step 函数是 task 的实现形态之一：
+
+```ts
+// flow/flows/settlement.flow.ts（api driver）
+export async function autoRefund(flow, deps) { ... }   // 实现 AutoRefundTask
+export default { autoRefund };
+```
+
+- **task schema = 契约**（名字/cron/做什么）
+- **pylon-flow step = 实现**（怎么跑）
+- 对账：task schema 的 name ↔ pylon-flow 的 step names——"定时任务已声明但没实现"可 lint

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.22",
   "description": "Schema definition DSL with drivers: MySQL DDL, TS enum, TypeBox schema codegen.",
   "type": "module",
   "main": "dist/index.js",

package/src/action.ts

@@ -1,52 +1,87 @@
-import { SchemaBase } from './dsl.js';
-import type { DtoField, DtoMessage, DtoArrayField, DtoObjectField } from './dto.js';
-import type { RefSchema } from './ref.js';
-import type { ControllerMethodSchema } from './controller.js';
-
-/** An action a user can perform on a page (e.g. submit, approve, reject).
- *  Subclasses use `type` as the discriminator. */
-export interface ActionSchema extends SchemaBase {
-  type: string;
-}
-
-export function defineAction(name: string, description?: string): ActionSchema {
-  return { name, description, type: 'gesture' };
-}
-
-/** Parameter data source for a call argument. */
-export type DataRef =
-  | { type: 'route'; key: string }
-  | { type: 'data';  key: string }
-  | { type: 'value'; value: unknown };
-
-/** Create a route-parameter reference. */
-export function route(key: string): DataRef {
-  return { type: 'route', key };
-}
-
-/** Create a page-data reference. */
-export function data(key: string): DataRef {
-  return { type: 'data', key };
-}
-
-export interface CallAction extends ActionSchema {
-  type: 'call';
-  func: ControllerMethodSchema;
-  args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>;
-}
-
-export function call(func: ControllerMethodSchema, args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>): CallAction {
-  return { name: func.name, type: 'call', func, args };
-}
-
-/** Assign a call's result to a page data field.
- *  React: setState({ [field]: await ... }). Mini-program: this.setData({ [field]: ... }). */
-export interface SetDataAction extends ActionSchema {
-  type: 'setData';
-  call: CallAction;
-  field: DtoField;
-}
-
-export function setData(call: CallAction, field: DtoField): SetDataAction {
-  return { name: 'setData', type: 'setData', call, field };
-}
+import { SchemaBase } from './dsl.js';
+import type { ControllerMethodSchema } from './controller.js';
+import type { ThirdServiceMethodSchema, ThirdCallbackSchema } from './third-service.js';
+import type { TaskSchema } from './task.js';
+import type { TableSchema } from './db.js';
+import type { PageSchema } from './page.js';
+
+// Cross-domain actions: what happens along a business line (journey).
+// Distinguished from PageActionSchema (what a user can do ON a page):
+// an Action is one beat of a journey — a page visit, an API call, a
+// third-party invocation, a database write, or a task trigger.
+//
+// Every action is `type + properties + data`: the type picks the property
+// set (page for page visits, method for controller/third, table for db,
+// task for task triggers), and `data` is the input of that beat. No further
+// classification — page/controller/third/db/task are all actions, only their
+// properties differ.
+
+/** A beat of a journey: type + properties + input data. */
+export interface ActionSchema extends SchemaBase {
+  type: 'page' | 'controller' | 'third' | 'db' | 'task';
+  /** Input data of this beat (blueprint: names first, refined to refs later). */
+  data?: Record<string, unknown>;
+}
+
+/** Visit a page — `data` present means fill/submit a form, absent means pure view. */
+export interface PageAction extends ActionSchema {
+  type: 'page';
+  /** Target page (PageFlow node). */
+  page: PageSchema;
+  /** Page url/path (e.g. '/bd/apply'). */
+  url: string;
+}
+
+/** Call a backend controller method. */
+export interface ControllerAction extends ActionSchema {
+  type: 'controller';
+  /** The controller method invoked (shared instance). */
+  method: ControllerMethodSchema;
+}
+
+/** Invoke a third-party service method or receive its callback. */
+export interface ThirdAction extends ActionSchema {
+  type: 'third';
+  /** The third-party method invoked (outbound). */
+  method?: ThirdServiceMethodSchema;
+  /** The third-party callback received (inbound) — mutually exclusive with method. */
+  callback?: ThirdCallbackSchema;
+  /** Wait for the async callback (inbound) before the journey continues. */
+  async?: boolean;
+}
+
+/** Write to a database table. */
+export interface DbAction extends ActionSchema {
+  type: 'db';
+  /** The table written (shared instance). */
+  table: TableSchema;
+  /** Write operation: insert | update | delete. */
+  op: 'insert' | 'update' | 'delete';
+}
+
+/** Trigger a system task (scheduled or async). */
+export interface TaskAction extends ActionSchema {
+  type: 'task';
+  /** The task triggered (shared instance). */
+  task: TaskSchema;
+}
+
+/** Builder for a journey action. */
+export const action = {
+  page(options: { page: PageSchema; url: string; data?: Record<string, unknown>; description?: string }): PageAction {
+    return { name: options.page.name, type: 'page', page: options.page, url: options.url, data: options.data, description: options.description };
+  },
+  controller(options: { method: ControllerMethodSchema; data?: Record<string, unknown>; description?: string }): ControllerAction {
+    return { name: options.method.name, type: 'controller', method: options.method, data: options.data, description: options.description };
+  },
+  third(options: { method?: ThirdServiceMethodSchema; callback?: ThirdCallbackSchema; data?: Record<string, unknown>; async?: boolean; description?: string }): ThirdAction {
+    const name = options.method?.name ?? options.callback?.name ?? 'third';
+    return { name, type: 'third', method: options.method, callback: options.callback, data: options.data, async: options.async, description: options.description };
+  },
+  db(options: { table: TableSchema; op: 'insert' | 'update' | 'delete'; data?: Record<string, unknown>; description?: string }): DbAction {
+    return { name: options.table.name, type: 'db', table: options.table, op: options.op, data: options.data, description: options.description };
+  },
+  task(options: { task: TaskSchema; data?: Record<string, unknown>; description?: string }): TaskAction {
+    return { name: options.task.name, type: 'task', task: options.task, data: options.data, description: options.description };
+  },
+};