@pylonts/dsl 1.1.11 → 1.1.13

package/docs/dao-generation.md

@@ -1,478 +1,478 @@
-# DAO 生成标准化规划（dao_schema v2）
-
-> 状态：**规划中（未实现）**
-> 关联代码：`dsl/src/dao.ts`（DaoSchema 六方法）、`dsl/src/entity.ts`（EntitySchema 单表列）、`dsl/src/project.ts`（app.schema.tenant）、`gen/src/gen-dao.ts`（dao_schema 生成器）、`curd/src/dao.ts` + `curd/src/dao_utils.ts`（curd 直产 DAO 实现）、`dsl/src/flow.ts`（FlowMethodRef 含 DaoMethodSchema）
-> 背景：curd 的 DAO 与 dao_schema 的 DAO 是两套独立生成逻辑（仅 filter 模块文件共享 `renderFilterFile`），本次规划把 DAO 生成收敛到 dao_schema 单一标准。
-
-## 1. 目标与原则
-
-**目标**：DAO 实现只有一个生成入口（`gen dao`）。curd 不再直接产出 DAO 代码，改为产出 `dao_schema` + `entity_schema` 声明，由统一生成器展开实现。任何 DAO 查询语义（精确列、多表 join、租户）都先落到 dao_schema 声明能力，再进生成器。
-
-**原则**：
-
-1. 声明完整：一个 dao 方法声明包含生成所需的一切（列、join、租户、分页），产物无需手工填充；
-2. 机器可校验：精确列是否单表（写方法）、跨表源是否有 FK（读方法）、租户注入是否一致——全部 lint 可查；
-3. 写读分界：写方法（insert/update）列必须单表（写不能 join）；读方法（find/get/aggregate）可多表；
-4. 生成约定集中：join 推导、租户注入、FK label 别名规则只在 gen 一处，curd 声明不携带重复逻辑。
-
-## 2. 现状差距（curd 产物语义 → dao_schema 表达力）
-
-| curd DAO 方法 | curd 产物语义 | dao_schema 现状 | 差距 |
-|---|---|---|---|
-| `page`/`list`/`query` | 精确 select 列 + FK label 别名 + 跨表列别名 + leftJoin + tenant WHERE + filter | `find`：`select *`、`EntitySchema` 单表列 | 精确列、多表行类型、别名、租户 |
-| `detail` | 跨表列 + FK label + leftJoin + PK + tenant WHERE | `get`：单表 `select *` | 多表、精确列、租户 |
-| `get` | own-table 精确列 + PK + tenant | `get` | 精确列、租户 |
-| `insert` | 全行插入（generator 补 PK） | `insert` | ✅ 语义一致（generator 已实现） |
-| `update` | `where({pk, tenantFk}).update(setCols)` | `update`：`where({pk}) + where filter` | 租户 WHERE |
-| （无 delete） | — | `delete`：`where({pk})` | 租户 WHERE |
-| 分页 | 自写 `clone().clearSelect().count()` + offset/limit | `paginate()`（@pylonts/dao） | 收敛到 `paginate()` |
-
-**落地现状（2026-08-16 合并决策）**：`EntitySchema` 与 `RowSchema` 已合并为一个 schema——`EntitySchema` 承载数据库字段集合，**来源（单表/跨表）不是 schema 的责任**，由消费位置决定（写方法 args = 单表，读方法 results = 可跨表）。文件规则：一个文件对应一张表（主表），文件内可声明多个 entity，entity 名字可以 Row 化（如 `OrderListRow`），全部走 `defineEntity`。
-
-**flow 耦合**：`FlowMethodRef` 含 `DaoMethodSchema`——service flow 的 invoke 可直接引用 dao 方法，dao 方法签名（参数形状）是 flow 契约的一部分。签名变化（如新增 tenant 参数）必须同步 flow invoke 的渲染与校验。
-
-## 3. 核心概念改造
-
-### 3.1 行类型模型：EntitySchema（结果行）
-
-`find.results` / `get.results` 与写方法 args 统一使用 `EntitySchema`——精确列 + 跨表列，**无显式 alias 声明**：
-
-```ts
-/** A row object: a set of database columns. Columns may come from one table
- *  (write args) or span tables through the main table's foreign keys (read
- *  results) — where the columns come from is the responsibility of the
- *  consuming position. */
-export interface EntitySchema extends SchemaBase {
-  type: 'entity';
-  api: ProjectApiSchema;
-  app: FrontAppSchema;
-  columns: Field[];   // 任意表列（单表 = 写方法 args；多表 = 读方法 results）
-}
-```
-
-**alias 完全推导（隐式，map 计数）**：
-
-- 单表查询（delete/insert/update 的 args、单表 get/find）：列名天然唯一，**无 alias**，SELECT/接口都用裸列名；
-- 多表查询（find/get 的结果列跨表）：收集所有参与表的列名，map 计数——
-  - 列名**唯一**（只在一张表出现）→ 沿用裸列名；
-  - 列名**重复**（≥2 张表有同名列）→ 重名列必须带 alias；主表列优先保留裸名，跨表列 alias 按词典短语命名；
-- 规则完全机器可判（列名集合 + 计数），lint 可校验产物一致性——**EntitySchema 无 alias 声明字段**。
-
-**alias 命名公式（表短语 + 列名）**：
-
-```
-alias = {table.phrase?.name ?? table.name} + '_' + {column.name}
-```
-
-- 表侧：用表的实体短语（`TableSchema.phrase`，词典 EntityPhrase 条目，如 `mer`/`shop`）；关联表等多实体场景无短语 → 用表名；
-- 列侧：**直接用列名**——字段命名本身就是短语命名（词典约定，如 amount → `amt`、rate → `rate`），列名即短语形式，无需再挂短语引用或解析词典；
-- curd 生成的外部引用列别名即此规则：`merchant`（phrase `mer`）的 `name` 列被 `order` 的查询引用 → `mer_name`。
-
-```ts
-// 多表 find：merchant.name 与 shop.name 重名 → 跨表列 alias（表短语 + 列名）
-select('merchant.id', 'merchant.name', 'shop.name as shop_name')
-// 不重名场景：shop.address 唯一 → 裸名
-select('merchant.id', 'shop.address')
-```
-
-**单表硬约束落在使用位置**：写方法的 args（insert/update）在 `defineDao` 校验期强制单表列；读方法 results 可跨表（外部引用列需 FK 可达）——insert/update 的行类型语义不变。
-
-**enum 列的类型渲染**：EntitySchema 渲染的 TS interface 中，enum 列必须用枚举 JS 名（`status: MerchantStatus`）+ 类型 import，**不得**用 `Field.jsType`（enum 的 jsType 是 `'string' | 'number'`，会丢失枚举类型）——复用 filter 产物的 `enumImportOf` 机制。**现状差距**：gen-dao 的 `renderRowInterface` 用 `c.jsType`，enum 列退化为 string/number；curd 的 entity 生成器用 jsName + import，是正确的。v2 必须对齐后者。
-
-### 3.1.1 聚合字段 AggregateField（aggregate 查询的输出列）
-
-聚合查询（`aggregate` 机制）的 results 实体中，列分两类：**普通列 = GROUP BY 维度**（一行一组），**聚合字段 = 计算输出列**。聚合字段由 `aggField(name, expr)` 构建，与普通列同处 `columns`，定义在实体文件（`{table}.entity.ts`）——dao 方法 `results` 只引用实体，从不在 dao 文件内联聚合字段：
-
-```ts
-import { aggField, Compute } from '@pylonts/dsl';
-
-// entity_schema/{api}/{app}/entity/order.entity.ts
-export const orderStatusStats = defineEntity({
-  name: 'OrderStatusStats',
-  api, app,
-  columns: [
-    order.columns.status,                        // GROUP BY 维度（普通列）
-    aggField('total', Compute.count()),          // count → jsType: 'number'
-    aggField('sumAmt', Compute.sum(order.columns.amount)), // sum(decimal) → jsType: 'string'
-  ],
-});
-```
-
-- `AggregateField` 是 `Field` 联合成员（`type: 'aggregate'`），实体可像任何列一样携带它；构造器 `aggField(name, expr)`，表达式 `Compute.count()` / `Compute.sum(field)` / `Compute.avg(field)`；
-- **`jsType` 两态**，由表达式推导：`count()` 与整数列的 `sum/avg` → `'number'`；`decimal`/`bigint`/`rate` 列的 `sum/avg` → `'string'`（精度串，JS number 丢精度）；
-- 驱动规则（mysql2 `supportBigNumbers` 开启）：COUNT/SUM/AVG 一律以 string 返回，生成物按 `jsType` 决定是否 `Number()` 转换（`'number'` → 转，`'string'` → 原样）；
-- DTO 可用 `from(entity, ...)` 投影聚合字段：`jsType === 'number'` 渲染 `Type.Number()`，否则 `Type.String()`。
-
-### 3.2 外部引用列（多表列）+ curd 层的 label 展开
-
-**dao 层无 label 概念**：EntitySchema.columns 可包含**任何表的列**——属于其他表的列 = 外部引用列（external reference）。外部引用列的 join 关系由 **FK 推导**：**FK 就是 join 条件**——main table 的某个 FK 指向该列所属表，渲染 `table.column as alias` + LEFT JOIN（join 条件 = FK 的 columns/references）。alias 公式（3.1）对多表列统一生效。
-
-**引用表可能有 label，也可能没有**——外部引用列机制不依赖 label：`merchant.name`、`merchant.id`、`merchant.created_at` 作为外部引用列，机制完全相同（FK 推导 join → alias）。label 只是 **curd 层在选择"FK 引用表上展示哪一列"时的默认来源**（有 label 用 label，无 label 用 PK），dao 生成器完全不感知 label。
-
-```ts
-// curd list.columns = [..., order.mer_id]（FK 列，mer_id 的 FK 就是 order↔merchant 的 join 条件）
-// → curd 生成的 dao_schema 声明（隐式展开，选择 merchant 的 label 列作外部引用列）：
-results.columns = [..., order.mer_id, merchant.name /* 外部引用列：FK(order.mer_id→merchant.id) 推导 join */]
-// → gen-dao 渲染（无 label 概念，纯外部引用机制）：
-select('order.mer_id', 'merchant.name as mer_name')
-  .leftJoin('merchant', 'merchant.id', 'order.mer_id')
-```
-
-"隐式展开"的隐式发生在 **curd → dao_schema 生成环节**（待决策 7 已决策），不在 gen-dao 环节——gen-dao 拿到什么列渲染什么列，声明与产物一一对应。
-
-### 3.3 join 推导统一（gen 单一函数）
-
-规则（两边现状已一致，收敛即可）：main table 通过自己的 `foreignKeys` 指向跨表 source；结果列、filter 条件、FK label 展开（3.2）涉及的跨表 source 集合 = LEFT JOIN 集合；只支持一层 join（main 直接 FK，多层不做）。现有 `renderFilterJoins` 泛化为 `renderJoins(mainTable, sources)`，find/get 的结果列与 filter 条件合并计算 sources。
-
-### 3.4 租户自动注入
-
-`app.schema.tenant` 语义已在 dsl 定义（"所有指向此表的 FK 的表自动获得租户作用域"），生成器实现：
-
-| 方法 | 注入规则 |
-|------|---------|
-| `find`/`get`/`aggregate` | tenant FK 成为**强制方法参数**（camelCase）+ 无条件 WHERE |
-| `update`/`delete` | tenant FK 进 WHERE（args 内或独立参数，待决策） |
-| `insert` | 待决策（3.5） |
-
-dao_schema **不新增声明**：tenant 从 `dao.api`/`dao.app` 的 `app.schema.tenant` + `dao.table` 的 FK 机器推导（有 tenant 表且表有 FK 才注入；无 FK = 无租户，报错还是跳过待决策）。
-
-### 3.5 insert 的租户列
-
-curd 现状 insert 无 tenant 处理（examples 未启用 tenant，路径未跑过）。两条路（待决策）：
-
-- **A 声明保证**：add 行类型（EntitySchema）必须包含 tenant 列，insert 全行插入即可（零生成器改动，声明期 lint 校验 add 实体含 tenant 列）；
-- **B 生成器注入**：insert 方法签名加 tenant 参数，生成器 `insert({ ...row, tenant_col: tenantId })`（调用方无感知，但行类型与 DB 行不一致）。
-
-### 3.6 值表达式 ValueExpr（update 表达式 set + 条件右值）
-
-**背景**：乐观锁（`version = version + 1`）、扣库存（`stock = stock - ? WHERE stock >= ?`）、列间比较（`stock > locked`）要求 set 值与条件右值是表达式，不能只是直接赋值/同名参数。受控算子列表（`{col, op:'+', value}`）封闭不可扩展，否决；SQL 字符串泄漏 SQL 不可 lint，否决。**采用声明式递归 AST——节点类型可扩展**。
-
-```ts
-// 值表达式：列引用 / 字面量 / 方法参数 / 二元运算（递归）
-export type ValueExpr =
-  | { kind: 'col';   field: Field }                             // 列引用（当前行该列）
-  | { kind: 'lit';   value: string | number }                   // 字面量
-  | { kind: 'param'; name: string }                             // 方法参数（进方法签名）
-  | { kind: 'bin';   op: 'add' | 'sub' | 'mul' | 'div'; left: ValueExpr; right: ValueExpr };
-
-// update 扩展：col = expr（与 args 的直接赋值列互斥，lint 校验不重叠）
-interface UpdateSchema { args: EntitySchema; set?: SetExpr[]; where?: FilterSchema }
-interface SetExpr { col: Field; expr: ValueExpr }
-
-// 条件右值：缺省 = 现状同名参数语义（零破坏）；显式 = 表达式（列间比较/常量/运算）
-interface FilterCondition { field: Field; op?: Operator; right?: ValueExpr; optional?: boolean }
-
-// 便利函数：incr(col, by) / decr(col, by)（by = ValueExpr）
-```
-
-**需求覆盖矩阵**：
-
-| 场景 | 声明 | 生成 SQL |
-|---|---|---|
-| 乐观锁 | **一等公民（3.7）**：`TableSchema.version` 声明后，update 自动合成——无需手写 set | `SET ..., version = version + 1 WHERE id = ? AND version = ?`（affected=0 即冲突，重试/报错为调用方语义） |
-| 扣库存（防超卖） | `set: [{ col: stock, expr: bin('sub', col(stock), param('qty')) }]` + `where`（stock gte） | `SET stock = stock - ? WHERE id = ? AND stock >= ?` |
-| 扣款 | 同上（balance - param('amt')） | `SET balance = balance - ? WHERE balance >= ?` |
-| 列间运算 | `bin('sub', col(stock), col(locked))` | `SET stock = stock - locked` |
-| 状态机 CAS | args 直接赋值 + `where`（现状已支持） | `SET state = 'refund' WHERE id = ? AND state = 'success'` |
-
-**机器校验（lint）**：列引用属于 `dao.table` 或 args 实体；param 名唯一且进签名；lit 类型与列类型相容；bin 左右类型相容。
-
-**安全**：AST → SQL 全受控（列名来自 Field、op 封闭、值走 knex 绑定参数），无注入面。
-
-**扩展性**：未来加节点 = 加 kind（如 `{ kind: 'fn', name: 'greatest', args: ValueExpr[] }`、一元取负），不动已有结构、不改存量声明——AST 的价值所在。
-
-### 3.7 乐观锁一等公民（TableSchema.version）
-
-乐观锁是表级属性（版本列属于表，不随方法变化），声明收敛到 `TableSchema.version`，update 自动合成版本自增 + 版本条件——不要求每个方法手写 `incr(version, lit(1))`。
-
-```ts
-defineTable({
-  name: 'order',
-  columns: { ..., version: { type: 'integer' } },
-  version: order.columns.version,   // 乐观锁版本列（列引用）
-});
-```
-
-**语义**：
-
-| 机制 | 行为 |
-|---|---|
-| `TableSchema.version?: Field` | 指向本表一个整数列；定义期校验：属于本表 + 类型为 integer/number |
-| update（有 version 的表） | args 实体**必须含 version 列**（lint）；生成器从 row 提取 version 进 WHERE，set 自动合成 `version = version + 1`，其余列直接赋值——签名不变 `update(row)`，返回 affected rows，0 = 冲突（重试/报错为调用方语义） |
-| insert | 照旧——version 初始值（0/1）由调用方在行数据里给，生成器不注入 |
-| delete / get / find | 不受影响（乐观锁 delete 如需要，另议） |
-| 与 `set?: SetExpr[]` 的关系 | 互斥——version 列由一等公民机制管理，set 表达式不得再引用 version 列（lint） |
-
-**与 tenant 形态一致**：row 里的 version 列与 row 里的 tenant FK 列同构——都是"行内列既进 WHERE 又不在 set"（destructure 后进 where），签名都只有一个 row。三种隐式列（pk / tenant FK / version）的 WHERE 提取是同一生成器函数。
-
-**价值**：乐观锁零声明成本（表声明一次，所有 update 自动生效）、不可遗漏（lint 强制 args 含 version 列）、调用方直接受影响行数判断冲突。
-
-## 4. dao_schema v2 方法形态
-
-```ts
-// find — 精确列 + 多表 + 分页 + filter
-find: {
-  type: 'find',
-  args?: FilterSchema,          // 查询条件（现状不变）
-  results: EntitySchema,           // SELECT 列 + 行类型（可跨表）
-  mode?: 'page' | 'limit',      // 分页（现状不变）
-  orderBy?: OrderBySchema | OrderBySchema[],
-},
-// 扩展点（7.2 验证倒逼）：
-//   results: EntitySchema | Field —— Field = 单列投影（valueList：List<值>）
-//   Operator + 'in' / 'null' / 'notNull'（IN 条件 / NULL 条件）
-//   join 类型 left/inner 声明位（filter 跨表条件 inner join 过滤主表）
-
-// get — 机制语义：按精确键取单行（任意列组合，不限于 PK；复合 PK / getByXX 均合法）
-get: {
-  type: 'get',
-  args: Field | Field[],        // 单字段或 AND 精确匹配的多字段（复合 PK）
-  where?: FilterSchema,         // 附加条件（AND 到键上）："PK + 状态条件"取单行 / 乐观锁读取
-  results: EntitySchema,           // 可多表
-},
-
-// insert — 精确列（现状语义已对，不变）
-insert: { type: 'insert', args: EntitySchema },
-
-// update — 精确 set 列 + PK + tenant（+where filter 现状不变）
-update: { type: 'update', args: EntitySchema, where?: FilterSchema },
-// 表达式能力（3.6 ValueExpr 模型）：set?: SetExpr[]（col = expr）、FilterCondition.right?: ValueExpr
-
-// delete — 按精确键删除（复合 PK 支持）
-delete: { type: 'delete', args: Field | Field[] },
-
-// aggregate — filter + tenant + filter 跨表 join（现状 + tenant）
-aggregate: { type: 'aggregate', args?: FilterSchema, results: EntitySchema },
-```
-
-**方法名与机制 type 正交**：dao_schema 是**低级机制**——`type` 只表达"怎么查"（按 PK 取单行 / 条件列表 / 写 / 删 / 聚合），六种机制封闭，不再随业务新增；方法名（methods map 的 key）是**业务语义**，自由命名，生成器原样保留。同一个机制可以有多个业务方法，每个方法有各自的 args/results：
-
-```ts
-defineDao({
-  name: 'MerchantDao',
-  table: merchantTable,
-  methods: {
-    get:    { type: 'get', args: pk,     results: merchantGetRow },    // curd get：单表精确列
-    detail: { type: 'get', args: pk,     results: merchantDetailRow },  // curd detail：多表 + label
-    getByOrderNo: { type: 'get', args: orderNoField, results: merchantGetRow },  // 任意列精确取单行
-    getByCombo: { type: 'get', args: [orderNoField, merIdField], results: merchantGetRow },  // 多字段 AND（复合 PK 同理）
-    page:   { type: 'find', mode: 'page', ... },   // curd page
-    list:   { type: 'find', ... },                 // curd list
-    query:  { type: 'find', ... },                 // curd keyword query
-  },
-});
-```
-
-因此 dao 语义**不需要**为业务延伸出新 type（如 `getDetail`）——延伸发生在方法名与键组合层面：`get` 的 args 是"精确键"（任意列或列组合），`getByXX`、复合 PK 都是合法声明。curd 生成 dao_schema 时业务方法名原样保留（`page`/`list`/`query`/`get`/`detail`），service/controller 对 `dao.page(...)`、`dao.detail(...)` 的引用签名不变。
-
-**curd 方法 → dao_schema 映射**：
-
-| curd 业务方法 | 机制 type | 差异 |
-|---|---|---|
-| `page` | `find` + `mode: 'page'` | `table.paginated === true` 时 curd 生成 page；映射规则：paginated → `mode: 'page'`（方法名 page），非 paginated → 无 mode（方法名 list） |
-| `list` | `find` | — |
-| `query`（keyword） | `find`（同一 filter） | 无分页参数；keyword 存在才生成 |
-| `get` | `get`（单表 EntitySchema） | — |
-| `detail` | `get`（多表 EntitySchema） | 单表 vs 多表只是 EntitySchema 内容差异 |
-| `insert` / `update` | `insert` / `update` | — |
-| （无 delete） | `delete` 机制保留并补租户 | — |
-
-**对齐检查：v2 能力 ≥ curd 现状（逐项）**：
-
-| curd 现状能力 | v2 覆盖 | 说明 |
-|---|---|---|
-| 精确 select 列 | ✅ 3.1 EntitySchema | — |
-| FK label 自动展开 | ✅ 3.2 | 展开声明方式待决策 7 |
-| 跨表列 + leftJoin 推导 | ✅ 3.3 | 结果列 + filter + label 合并 sources |
-| tenant 强制参数 + WHERE | ✅ 3.4 | — |
-| filter 柯里化 + keyword 端点 | ✅（现状共享 `renderFilterFile`） | — |
-| 分页 | ✅ 收敛到 `paginate()` | curd 自写 count 与 `paginate()` 等价（clone + clearSelect） |
-| 单列 orderBy | ✅ `find.orderBy` | 且支持多列 |
-| generator 表 insert 补 PK | ✅ 现状 gen-dao 已实现 | — |
-| 枚举列类型 | ✅ 3.1 enum 渲染 | **gen-dao 现状有 bug**（jsType 退化），v2 修复 |
-| 类导出形态 | ✅ 一致 | `export default class` + `export const xxxDao = new XxxDao()` 两边相同 |
-
-**行为差异点（统一后变化，消费方需同步）**：
-
-1. **get 的 miss 返回**：curd 现状 `Promise<Row | undefined>`，gen-dao 现状 `Promise<Row | null>`——v2 统一 `| null`，curd 的 service/controller 生成器的 undefined 判断改为 null 判断；
-2. **PagedRows import 来源**：curd 从 `@pylonts/core`，gen-dao 从 `@pylonts/dao`——统一 `@pylonts/dao`；
-3. **select 列 qualified**：curd detail 全 table-qualified（`merchant.id`），page 单表裸列——v2 规则：单表裸列、多表重名列 alias（3.1），多表唯一列 qualified 裸名。
-
-**新增校验**（defineDao/loadDaos）：
-
-| 校验 | 规则 |
-|------|------|
-| 写方法单表 | insert/update 的 args 列必须全部来自 `dao.table` |
-| 键列属于主表 | get/delete 的 args 字段必须属于 `dao.table`（跨表键不走 get/delete） |
-| 读方法 FK | find/get 结果列的跨表 source 必须有 main-table FK 指向，否则报错 |
-| 租户一致性 | app 有 tenant 且 table 有 FK → 方法必须能注入（机器推导，无声明可错） |
-
-## 5. 产物形态（gen-dao 输出样例）
-
-```ts
-// {api}/src/modules/{app}/dao/MerchantDao.ts
-import { knex, paginate, type PagedRows } from '@pylonts/dao';
-import { merchantListFilter, type MerchantListFilterArgs } from '../filter/MerchantListFilter';
-
-export interface MerchantListRow {           // EntitySchema.columns 渲染
-  id: string;
-  name: string;
-  status: MerchantStatus;
-  shop_name: string;                          // FK label 别名（推导）
-}
-
-export default class MerchantDao {
-  // 业务名 page，机制 find + mode page
-  async page(page: number, pageSize: number, filter: MerchantListFilterArgs, shopId: string): Promise<PagedRows<MerchantListRow>> {
-    return paginate<MerchantListRow>(
-      merchantListFilter(filter)(knex('merchant')
-        .leftJoin('shop', 'shop.id', 'merchant.shop_id'))   // renderJoins（结果列 + filter 条件合并）
-        .select('merchant.id', 'merchant.name', 'merchant.status', 'shop.name as shop_name')
-        .where('merchant.shop_id', '=', shopId),            // tenant 无条件 WHERE
-      page, pageSize,
-    );
-  }
-
-  // 业务名 get，机制 get（单表 EntitySchema）
-  async get(id: string, shopId: string): Promise<MerchantGetRow | null> {
-    return knex('merchant')
-      .select('merchant.id', 'merchant.name')
-      .where({ id })
-      .where('merchant.shop_id', '=', shopId)
-      .first();
-  }
-
-  // 业务名 detail，机制 get（多表 EntitySchema）——同一机制的第二业务方法
-  async detail(id: string, shopId: string): Promise<MerchantListRow | null> {
-    return knex('merchant')
-      .leftJoin('shop', 'shop.id', 'merchant.shop_id')
-      .select('merchant.id', 'merchant.name', 'shop.name as shop_name')
-      .where({ id })
-      .where('merchant.shop_id', '=', shopId)
-      .first();
-  }
-
-  // update + tenant
-  async update(row: MerchantUpdateRow, shopId: string): Promise<number> {
-    const { id, shop_id, ...data } = row;
-    return knex('merchant').where({ id }).where('shop_id', '=', shopId).update(data);
-  }
-}
-```
-
-## 6. 消费方连锁影响
-
-| 消费方 | 影响 |
-|--------|------|
-| curd service/controller/page 生成器 | 行类型 import 从 `../entities/{Pascal}Entity` 改为 DAO 文件导出（或统一 entities 目录，待决策）；方法签名变化（tenant 参数） |
-| curd entity 生成器 | 退役：`entities/{Pascal}Entity.ts` 的 ListRow/AddRow/UpdateRow 改为产出 `entity_schema/{api}/{app}/entity/{table}.entity.ts` 声明（文件名=表名的机器规则正好容纳） |
-| curd dao/dao_utils | `createSqlBuilder`/`buildJoins`/`renderPageResult`（自写 count 分页）全部退役，产物语义移入 gen-dao |
-| flow（`FlowMethodRef` 含 DaoMethodSchema） | dao 方法签名变（tenant 参数）→ flow invoke 的 args 槽位渲染与 service 绑定校验同步 |
-| lint dao / entity-check | 新增写方法单表、读方法 FK、别名唯一、租户一致性检查 |
-
-## 7. 分阶段落地
-
-| 阶段 | 内容 | 产出 |
-|------|------|------|
-| 1 | dsl：`EntitySchema`（`columns: Field[]`，alias 隐式推导）、find/get 的 results 升级、get/delete args 放宽为 `Field \| Field[]`（任意键组合/复合 PK）+ get `where?: FilterSchema`、`ValueExpr` 表达式模型（3.6，update set + 条件右值）、`TableSchema.version` 乐观锁一等公民（3.7）、写方法单表/读方法 FK 校验、tenant 语义文档化 | `dsl/src/db.ts`、`dsl/src/dao.ts`、`dsl/src/entity.ts`（或新 row.ts）、`dsl/src/filter.ts`、`dsl/src/expr.ts`（或并入 dao.ts）+ 测试 |
-| 2 | gen：`renderJoins` 泛化、alias 推导（map 计数重名列 + `{表短语 ?? 表名}_{列名}` 公式）、gen-dao 按 v2 升级（精确列 select、get 多表、tenant 注入、分页统一 paginate）+ 测试 | `gen/src/gen-dao.ts`、`gen/src/filter-render.ts` |
-| 3 | curd：dao/entity 生成器改为产出 dao_schema + entity_schema 声明；service/controller/page import 改向；自写 count/join 代码退役 | `curd/src/dao.ts`、`curd/src/entity.ts` 等 |
-| 4 | flow invoke 同步 + lint dao 新规则 + examples 全量回归 | cli lint、examples |
-
-**阶段 2 之后、阶段 3 之前存在过渡期**：gen-dao 已升级，curd 仍直产实现（旧语义）——filter 模块文件继续幂等共享，不冲突。阶段 3 完成即两条路径合一。
-
-## 7.1 复杂项目验证（思维实验：cca-pay trans）
-
-用真实支付项目 `cca-back-server/cca-pay-parent/cca-pay` 的核心业务（zoom `dao.ar` ActiveRecord 形态）对照 v2 能力：
-
-| cca-pay 现状（zoom AR） | dao_schema v2 表达 | 覆盖 |
-|---|---|---|
-| `dao.ar(Pay.class).insert(pay)` | `insert`（args 精确列） | ✅ |
-| `.filter("state\|chId\|chTime\|errMsg\|errCode").update(pay)`（列白名单 update） | `update` args 精确列 | ✅ |
-| `.where("state", success).filter("state").update(pay)`（乐观锁条件更新，判影响行数） | `update` + `where?: FilterSchema` | ✅ |
-| `.get(id)` / `.where("id", id).get()` | `get` 单键 | ✅ |
-| `.where("devId", devId).where("devSeq", devSeq).get()`（组合键） | `get` args `Field[]`（v2 放宽） | ✅ |
-| `.where("state", success).get(id)`（PK + 状态条件取单行） | `get` + `where?: FilterSchema`（本次补充） | ✅ |
-| `.where(...).count() > 0`（contains） | `aggregate` count 或 `find` + limit 1 | ✅ |
-| `fill()` 可选条件分页 + 日期范围（GTE/LTE） | `find` + filter（optional 条件 + `op: 'gte'/'lte'`） | ✅ |
-| `orderBy("id", DESC)` + `.page(...)` | `find.orderBy` + `mode: 'page'` | ✅ |
-| `PayStatistics`（count(\*) + sum(amt) 聚合投影） | `aggregate` + `Compute.count/sum` | ✅ |
-| 同一查询多投影（Pay 全行 / 子集 / 统计） | 多个方法共享同一 filter，EntitySchema 各异 | ✅ |
-| 一表多实体（Pay / PayForRefund / PayStatistics 同表 t_pay） | 多 EntitySchema/EntitySchema 绑定同表 | ✅ |
-| enum 存 ordinal（int） | enum `valueType: 'integer'` | ✅ |
-| `@ColumnIgnore`（exception 不落库） | 列不进 EntitySchema 即可 | ✅ |
-| ID 生成器（时间 + 序号 snowflake 变体） | `table.generator` + `@pylonts/id-gen` registry | ✅ |
-| `@Trans` / `@EventNotifier` | `@pylonts/dao` `@Trans` / `@pylonts/event` | ✅ |
-| `dao.ar(Pay.class, table)`（表名运行时参数） | dao 绑定固定 table | ❌ 待决策 8（当前全传 baseTable，防御性预留） |
-| `@LockKey`（分布式锁）/ `@CacheKey`（缓存） | 无 | ❌ 非 dao 范围（service 层能力，flow 建模时会遇到） |
-
-**结论**：trans 核心业务的 DAO 形态 16/18 可表达；两个缺口——动态表名（当前无真实分表需求，待决策 8）与分布式锁/缓存（dao 生成范围之外）。乐观锁更新与"PK+条件取单行"促使本次补充 `get.where?: FilterSchema`。
-
-## 7.2 复杂项目验证（思维实验：v-pay 虚拟卡支付）
-
-`v-pay-impl`（zoom AR 形态，比 trans 更重：批量、IN、NULL、聚合粒度 DAO）：
-
-| v-pay 现状（zoom AR） | dao_schema v2 表达 | 覆盖 |
-|---|---|---|
-| `whereIn("bsUsrId", ids)` / `whereIn("id", cardIds)`（IN 条件，高频） | ❌ Operator 无 `in` | **缺口 1：Operator + `'in'`** |
-| `whereNull("nextSendTime")`（NULL 条件） | ❌ 无条件位 | **缺口 2：Operator + `'null'/'notNull'`** |
-| `valueList("id", Integer.class)`（单列投影 List） | ❌ find.results 只有 EntitySchema | **缺口 3：results 支持单 Field（单列列表）** |
-| `@Batch` 批量 update（filter + List）/ 批量 insert（`ar.insert(list)`） | ❌ 单行方法 | **待决策 10（批量机制）** |
-| `filter(...).ignoreNull(false).update`（null 跳过/动态部分更新） | ❌ set 列静态声明 | **待决策 11（update null 语义）** |
-| INNER JOIN 实体（`builder(VOp.class).join(INNER, "v_usr_op", ...)`） | ❌ join 推导全 LEFT | **待决策 12（join 类型 left/inner 声明）** |
-| 聚合粒度 DAO（VOpDaoImpl 一个类管 v_op + v_usr_op + v_op_detail 三表） | ⚠️ dao_schema 一 dao 一表 | **边界确认：多表编排 = service + 未来 Repository，dao_schema 不收编** |
-| `getByBsIdAndIds`（eq + in 组合） | 缺口 1 补上后 ✅ | — |
-| 插入冲突重试（while + DuplicateEntry） | insert 已够，重试为 service 层语义 | ✅ |
-| fill 可选条件 + orderBy + page + count | find/aggregate | ✅ |
-| 动态 Class 多投影 | 多方法共享 filter、EntitySchema 各异 | ✅ |
-| `StringUtils.join(ids, ",")`（IDs 逗号串列） | 业务数据形态，与 dao 机制无关 | ✅ |
-
-**结论**：v-pay 的单行/查询形态大部分可表达；4 个机制缺口（in、null 条件、单列投影、join 类型）+ 2 个模型级待决策（批量、update null 语义）。最重的发现是**聚合粒度 DAO**——VOpDaoImpl 是聚合仓储雏形（v_op 根 + v_usr_op 成员 + detail），这印证 dao_schema 单表原子性的边界正确：多表落库编排归 service（flow）+ @Trans，批量映射插入 = service 循环 + @Trans，未来由 Repository（aggregate.md 规划）收编。
-
-## 7.3 参照系：zoom mapper（Java zoom-dao 的方法约定式 DAO）
-
-zoom mapper = 接口方法名约定 + 参数注解（`@Like`/`@WhereIn`/`@Condition`/`@IgnoreNull`/`@Filter`/`@Version`/`@Select`/`@OrderBy`）驱动 SQL 生成。**TS 生态无此形态**（Java 编译期注解处理的产物）；TS 的成熟参数化编排 = Prisma 式参数对象（`findMany({ where, orderBy, take, skip })`）或 Drizzle/MikroORM 链式构建器。pylon dao_schema 走第三条路：显式声明 + 生成器。
-
-**两条"严格字段映射"路线的对比**（入口不同，目标相同）：
-
-| | zoom @Condition | pylon ValueExpr |
-|---|---|---|
-| 入口 | SQL 片段字符串（`"name=? and (time>? or time<?)"`） | 结构化表达式 AST（`{ kind: 'bin', ... }`） |
-| 严格映射手段 | **SQL 分析器**：解析片段、字段名严格映射到实体列、参数化绑定（全部转化为 `a=? and b=? and c in (?,?,?)` 形式防注入） | **结构即校验**：列引用是 Field 对象（定义期归属校验），值走绑定参数——无需解析器，无解析歧义 |
-| 复杂度 | 高（需维护 SQL 分析器） | 低（AST 遍历 + 定义期校验） |
-| pylon 选择 | 不走 | **采用**（3.6） |
-
-**方向验证（zoom 实践印证 pylon 设计）**：
-
-| zoom mapper | pylon | 状态 |
-|---|---|---|
-| `@Version` → 自动 `where version=当前值 + set version+1` | 3.7 `TableSchema.version` | 设计一致 |
-| `@Filter("id,name")` 更新列白名单 | update args 精确列 | 同构 |
-| **"dao 层一次只做一次 sql 元操作，事务在 Service 层"** | dao_schema 单表原子性 + service @Trans | 核心哲学一致 |
-| `@Select("id")` 单列投影 List | 缺口 3 | 印证 |
-
-**新缺口（zoom 有、pylon 无）**：
-
-1. **save / insertOrUpdate（upsert）**：`@Keys` 唯一键判断，DB 原生 upsert（返回 1=插入/2=更新）；v-pay `create` 的 while + DuplicateEntry 重试是缺 upsert 的手工模拟——待决策 13；
-2. **insertIgnore**：忽略唯一键冲突的插入（v-pay 高频）——与 13 合并讨论；
-3. **`@IgnoreNull` 默认语义**：zoom 的 update **默认跳过 null 字段**（`@IgnoreNull(false)` 才写 null）——待决策 11 的权威参照（主流默认 = null 跳过）；
-4. **动态 OrderBy**：`find(OrderBy.asc("id","name"))` 运行时排序参数，pylon 只有声明静态 orderBy——待决策 14。
-
-## 8. 待决策问题
-
-1. ~~**alias 声明**~~（已决策：完全推导，无声明字段——多表重名列 alias，唯一列裸名，map 计数机器可判；命名公式 = `{表短语 ?? 表名}_{列名}`，字段命名本身就是短语命名）
-2. ~~**insert 租户列**~~（已决策：**A 声明保证**——add 实体必须含 tenant 列（lint 校验），insert 全行插入，零生成器改动）
-3. ~~**update/delete 的 tenant 参数形态**~~（已决策：**update 走 row 内提取**——tenant 列从 row destructure 进 WHERE、不进 set，与 pk/version 三种隐式列同构，签名不变；**delete 走独立参数 `(id, shopId)`**——args 是键，tenant 无处可藏）
-4. ~~**行类型产出位置**~~（已决策：**统一 `entities/` 目录文件**（curd 现状被消费方引用）——gen-dao 的行类型 interface 从 DAO 文件移出）
-5. ~~**app 有 tenant 但表无 FK**~~（已决策：**跳过**——该 dao 无租户，存量项目不炸）
-6. ~~**get 参数顺序**~~（已决策：args 声明顺序 + tenant 最后）
-7. ~~**FK label 展开声明方式**~~（已决策：**隐式展开发生在 curd → dao_schema 生成环节**——curd 把被引用表 label 列写成外部引用列进 EntitySchema.columns；dao 层无 label 概念，纯外部引用列机制（3.2））
-8. **动态表名 / 同结构多表**：cca-pay 的 `dao.ar(Pay.class, table)` 支持表名运行时参数（当前全部传 baseTable，防御性预留）。dao_schema 的 dao 绑定固定 table 表达不了。选项：a 暂不支持（当前无真实分表需求，真分表时再设计）；b 方法级 `tableParam?: boolean`（生成 table 参数透传 knex）；c dao 绑定"表组"（同结构多表的集合声明）。
-9. ~~**update 的表达式 set 与列间比较**~~（已决策：`ValueExpr` 递归 AST + `set?: SetExpr[]` + `FilterCondition.right?: ValueExpr`，见 3.6；**乐观锁为一等公民 `TableSchema.version`（3.7），不走手写 set**）
-10. **批量操作**（v-pay `@Batch` 批量 update/insert）：机制级批量（insert/update 的 args 支持 EntitySchema 数组，生成批量方法）vs service 层循环 + @Trans（语义等价，N 次 SQL vs 批量提交）？——**后续课题，不进本次**
-11. **update 的 null 跳过语义**（v-pay `ignoreNull` 动态部分更新）：args 声明 `nullSkip` 标记 vs 保持静态列（声明多个 update 方法各管各列）？**zoom mapper 参照：`@IgnoreNull` 默认 true（跳过 null 列），主流默认 = null 跳过**。——**后续课题，不进本次**
-12. **join 类型**（v-pay INNER JOIN 实体）：find 的跨表 join 全 LEFT；INNER（join 表过滤主表）的声明位——`renderJoins` 的 sources 加类型标记？跨表 filter 条件天然需要 inner 语义（条件必须命中）？——**后续课题，不进本次**
-13. **upsert / insertIgnore**（zoom `save`/`insertOrUpdate` + `@Keys`；v-pay create 的冲突重试是手工模拟）：`save` 机制（args 实体 + 唯一键集合，生成 DB 原生 `INSERT ... ON DUPLICATE KEY UPDATE`）？还是坚持 service 层组合（insert 冲突 → 重试/update）？——**后续课题，不进本次**
-14. **动态 orderBy**（zoom `find(OrderBy.asc(...))` 运行时排序参数）：find 的 orderBy 参数化（排序列 + 方向运行时传入，列域受限）vs 保持声明静态？——**后续课题，不进本次**
-
+# DAO 生成标准化规划（dao_schema v2）
+
+> 状态：**规划中（未实现）**
+> 关联代码：`dsl/src/dao.ts`（DaoSchema 六方法）、`dsl/src/entity.ts`（EntitySchema 单表列）、`dsl/src/project.ts`（app.schema.tenant）、`gen/src/gen-dao.ts`（dao_schema 生成器）、`curd/src/dao.ts` + `curd/src/dao_utils.ts`（curd 直产 DAO 实现）、`dsl/src/flow.ts`（FlowMethodRef 含 DaoMethodSchema）
+> 背景：curd 的 DAO 与 dao_schema 的 DAO 是两套独立生成逻辑（仅 filter 模块文件共享 `renderFilterFile`），本次规划把 DAO 生成收敛到 dao_schema 单一标准。
+
+## 1. 目标与原则
+
+**目标**：DAO 实现只有一个生成入口（`gen dao`）。curd 不再直接产出 DAO 代码，改为产出 `dao_schema` + `entity_schema` 声明，由统一生成器展开实现。任何 DAO 查询语义（精确列、多表 join、租户）都先落到 dao_schema 声明能力，再进生成器。
+
+**原则**：
+
+1. 声明完整：一个 dao 方法声明包含生成所需的一切（列、join、租户、分页），产物无需手工填充；
+2. 机器可校验：精确列是否单表（写方法）、跨表源是否有 FK（读方法）、租户注入是否一致——全部 lint 可查；
+3. 写读分界：写方法（insert/update）列必须单表（写不能 join）；读方法（find/get/aggregate）可多表；
+4. 生成约定集中：join 推导、租户注入、FK label 别名规则只在 gen 一处，curd 声明不携带重复逻辑。
+
+## 2. 现状差距（curd 产物语义 → dao_schema 表达力）
+
+| curd DAO 方法 | curd 产物语义 | dao_schema 现状 | 差距 |
+|---|---|---|---|
+| `page`/`list`/`query` | 精确 select 列 + FK label 别名 + 跨表列别名 + leftJoin + tenant WHERE + filter | `find`：`select *`、`EntitySchema` 单表列 | 精确列、多表行类型、别名、租户 |
+| `detail` | 跨表列 + FK label + leftJoin + PK + tenant WHERE | `get`：单表 `select *` | 多表、精确列、租户 |
+| `get` | own-table 精确列 + PK + tenant | `get` | 精确列、租户 |
+| `insert` | 全行插入（generator 补 PK） | `insert` | ✅ 语义一致（generator 已实现） |
+| `update` | `where({pk, tenantFk}).update(setCols)` | `update`：`where({pk}) + where filter` | 租户 WHERE |
+| （无 delete） | — | `delete`：`where({pk})` | 租户 WHERE |
+| 分页 | 自写 `clone().clearSelect().count()` + offset/limit | `paginate()`（@pylonts/dao） | 收敛到 `paginate()` |
+
+**落地现状（2026-08-16 合并决策）**：`EntitySchema` 与 `RowSchema` 已合并为一个 schema——`EntitySchema` 承载数据库字段集合，**来源（单表/跨表）不是 schema 的责任**，由消费位置决定（写方法 args = 单表，读方法 results = 可跨表）。文件规则：一个文件对应一张表（主表），文件内可声明多个 entity，entity 名字可以 Row 化（如 `OrderListRow`），全部走 `defineEntity`。
+
+**flow 耦合**：`FlowMethodRef` 含 `DaoMethodSchema`——service flow 的 invoke 可直接引用 dao 方法，dao 方法签名（参数形状）是 flow 契约的一部分。签名变化（如新增 tenant 参数）必须同步 flow invoke 的渲染与校验。
+
+## 3. 核心概念改造
+
+### 3.1 行类型模型：EntitySchema（结果行）
+
+`find.results` / `get.results` 与写方法 args 统一使用 `EntitySchema`——精确列 + 跨表列，**无显式 alias 声明**：
+
+```ts
+/** A row object: a set of database columns. Columns may come from one table
+ *  (write args) or span tables through the main table's foreign keys (read
+ *  results) — where the columns come from is the responsibility of the
+ *  consuming position. */
+export interface EntitySchema extends SchemaBase {
+  type: 'entity';
+  api: ProjectApiSchema;
+  app: FrontAppSchema;
+  columns: Field[];   // 任意表列（单表 = 写方法 args；多表 = 读方法 results）
+}
+```
+
+**alias 完全推导（隐式，map 计数）**：
+
+- 单表查询（delete/insert/update 的 args、单表 get/find）：列名天然唯一，**无 alias**，SELECT/接口都用裸列名；
+- 多表查询（find/get 的结果列跨表）：收集所有参与表的列名，map 计数——
+  - 列名**唯一**（只在一张表出现）→ 沿用裸列名；
+  - 列名**重复**（≥2 张表有同名列）→ 重名列必须带 alias；主表列优先保留裸名，跨表列 alias 按词典短语命名；
+- 规则完全机器可判（列名集合 + 计数），lint 可校验产物一致性——**EntitySchema 无 alias 声明字段**。
+
+**alias 命名公式（表短语 + 列名）**：
+
+```
+alias = {table.phrase?.name ?? table.name} + '_' + {column.name}
+```
+
+- 表侧：用表的实体短语（`TableSchema.phrase`，词典 EntityPhrase 条目，如 `mer`/`shop`）；关联表等多实体场景无短语 → 用表名；
+- 列侧：**直接用列名**——字段命名本身就是短语命名（词典约定，如 amount → `amt`、rate → `rate`），列名即短语形式，无需再挂短语引用或解析词典；
+- curd 生成的外部引用列别名即此规则：`merchant`（phrase `mer`）的 `name` 列被 `order` 的查询引用 → `mer_name`。
+
+```ts
+// 多表 find：merchant.name 与 shop.name 重名 → 跨表列 alias（表短语 + 列名）
+select('merchant.id', 'merchant.name', 'shop.name as shop_name')
+// 不重名场景：shop.address 唯一 → 裸名
+select('merchant.id', 'shop.address')
+```
+
+**单表硬约束落在使用位置**：写方法的 args（insert/update）在 `defineDao` 校验期强制单表列；读方法 results 可跨表（外部引用列需 FK 可达）——insert/update 的行类型语义不变。
+
+**enum 列的类型渲染**：EntitySchema 渲染的 TS interface 中，enum 列必须用枚举 JS 名（`status: MerchantStatus`）+ 类型 import，**不得**用 `Field.jsType`（enum 的 jsType 是 `'string' | 'number'`，会丢失枚举类型）——复用 filter 产物的 `enumImportOf` 机制。**现状差距**：gen-dao 的 `renderRowInterface` 用 `c.jsType`，enum 列退化为 string/number；curd 的 entity 生成器用 jsName + import，是正确的。v2 必须对齐后者。
+
+### 3.1.1 聚合字段 AggregateField（aggregate 查询的输出列）
+
+聚合查询（`aggregate` 机制）的 results 实体中，列分两类：**普通列 = GROUP BY 维度**（一行一组），**聚合字段 = 计算输出列**。聚合字段由 `aggField(name, expr)` 构建，与普通列同处 `columns`，定义在实体文件（`{table}.entity.ts`）——dao 方法 `results` 只引用实体，从不在 dao 文件内联聚合字段：
+
+```ts
+import { aggField, Compute } from '@pylonts/dsl';
+
+// entity_schema/{api}/{app}/entity/order.entity.ts
+export const orderStatusStats = defineEntity({
+  name: 'OrderStatusStats',
+  api, app,
+  columns: [
+    order.columns.status,                        // GROUP BY 维度（普通列）
+    aggField('total', Compute.count()),          // count → jsType: 'number'
+    aggField('sumAmt', Compute.sum(order.columns.amount)), // sum(decimal) → jsType: 'string'
+  ],
+});
+```
+
+- `AggregateField` 是 `Field` 联合成员（`type: 'aggregate'`），实体可像任何列一样携带它；构造器 `aggField(name, expr)`，表达式 `Compute.count()` / `Compute.sum(field)` / `Compute.avg(field)`；
+- **`jsType` 两态**，由表达式推导：`count()` 与整数列的 `sum/avg` → `'number'`；`decimal`/`bigint`/`rate` 列的 `sum/avg` → `'string'`（精度串，JS number 丢精度）；
+- 驱动规则（mysql2 `supportBigNumbers` 开启）：COUNT/SUM/AVG 一律以 string 返回，生成物按 `jsType` 决定是否 `Number()` 转换（`'number'` → 转，`'string'` → 原样）；
+- DTO 可用 `from(entity, ...)` 投影聚合字段：`jsType === 'number'` 渲染 `Type.Number()`，否则 `Type.String()`。
+
+### 3.2 外部引用列（多表列）+ curd 层的 label 展开
+
+**dao 层无 label 概念**：EntitySchema.columns 可包含**任何表的列**——属于其他表的列 = 外部引用列（external reference）。外部引用列的 join 关系由 **FK 推导**：**FK 就是 join 条件**——main table 的某个 FK 指向该列所属表，渲染 `table.column as alias` + LEFT JOIN（join 条件 = FK 的 columns/references）。alias 公式（3.1）对多表列统一生效。
+
+**引用表可能有 label，也可能没有**——外部引用列机制不依赖 label：`merchant.name`、`merchant.id`、`merchant.created_at` 作为外部引用列，机制完全相同（FK 推导 join → alias）。label 只是 **curd 层在选择"FK 引用表上展示哪一列"时的默认来源**（有 label 用 label，无 label 用 PK），dao 生成器完全不感知 label。
+
+```ts
+// curd list.columns = [..., order.mer_id]（FK 列，mer_id 的 FK 就是 order↔merchant 的 join 条件）
+// → curd 生成的 dao_schema 声明（隐式展开，选择 merchant 的 label 列作外部引用列）：
+results.columns = [..., order.mer_id, merchant.name /* 外部引用列：FK(order.mer_id→merchant.id) 推导 join */]
+// → gen-dao 渲染（无 label 概念，纯外部引用机制）：
+select('order.mer_id', 'merchant.name as mer_name')
+  .leftJoin('merchant', 'merchant.id', 'order.mer_id')
+```
+
+"隐式展开"的隐式发生在 **curd → dao_schema 生成环节**（待决策 7 已决策），不在 gen-dao 环节——gen-dao 拿到什么列渲染什么列，声明与产物一一对应。
+
+### 3.3 join 推导统一（gen 单一函数）
+
+规则（两边现状已一致，收敛即可）：main table 通过自己的 `foreignKeys` 指向跨表 source；结果列、filter 条件、FK label 展开（3.2）涉及的跨表 source 集合 = LEFT JOIN 集合；只支持一层 join（main 直接 FK，多层不做）。现有 `renderFilterJoins` 泛化为 `renderJoins(mainTable, sources)`，find/get 的结果列与 filter 条件合并计算 sources。
+
+### 3.4 租户自动注入
+
+`app.schema.tenant` 语义已在 dsl 定义（"所有指向此表的 FK 的表自动获得租户作用域"），生成器实现：
+
+| 方法 | 注入规则 |
+|------|---------|
+| `find`/`get`/`aggregate` | tenant FK 成为**强制方法参数**（camelCase）+ 无条件 WHERE |
+| `update`/`delete` | tenant FK 进 WHERE（args 内或独立参数，待决策） |
+| `insert` | 待决策（3.5） |
+
+dao_schema **不新增声明**：tenant 从 `dao.api`/`dao.app` 的 `app.schema.tenant` + `dao.table` 的 FK 机器推导（有 tenant 表且表有 FK 才注入；无 FK = 无租户，报错还是跳过待决策）。
+
+### 3.5 insert 的租户列
+
+curd 现状 insert 无 tenant 处理（examples 未启用 tenant，路径未跑过）。两条路（待决策）：
+
+- **A 声明保证**：add 行类型（EntitySchema）必须包含 tenant 列，insert 全行插入即可（零生成器改动，声明期 lint 校验 add 实体含 tenant 列）；
+- **B 生成器注入**：insert 方法签名加 tenant 参数，生成器 `insert({ ...row, tenant_col: tenantId })`（调用方无感知，但行类型与 DB 行不一致）。
+
+### 3.6 值表达式 ValueExpr（update 表达式 set + 条件右值）
+
+**背景**：乐观锁（`version = version + 1`）、扣库存（`stock = stock - ? WHERE stock >= ?`）、列间比较（`stock > locked`）要求 set 值与条件右值是表达式，不能只是直接赋值/同名参数。受控算子列表（`{col, op:'+', value}`）封闭不可扩展，否决；SQL 字符串泄漏 SQL 不可 lint，否决。**采用声明式递归 AST——节点类型可扩展**。
+
+```ts
+// 值表达式：列引用 / 字面量 / 方法参数 / 二元运算（递归）
+export type ValueExpr =
+  | { kind: 'col';   field: Field }                             // 列引用（当前行该列）
+  | { kind: 'lit';   value: string | number }                   // 字面量
+  | { kind: 'param'; name: string }                             // 方法参数（进方法签名）
+  | { kind: 'bin';   op: 'add' | 'sub' | 'mul' | 'div'; left: ValueExpr; right: ValueExpr };
+
+// update 扩展：col = expr（与 args 的直接赋值列互斥，lint 校验不重叠）
+interface UpdateSchema { args: EntitySchema; set?: SetExpr[]; where?: FilterSchema }
+interface SetExpr { col: Field; expr: ValueExpr }
+
+// 条件右值：缺省 = 现状同名参数语义（零破坏）；显式 = 表达式（列间比较/常量/运算）
+interface FilterCondition { field: Field; op?: Operator; right?: ValueExpr; optional?: boolean }
+
+// 便利函数：incr(col, by) / decr(col, by)（by = ValueExpr）
+```
+
+**需求覆盖矩阵**：
+
+| 场景 | 声明 | 生成 SQL |
+|---|---|---|
+| 乐观锁 | **一等公民（3.7）**：`TableSchema.version` 声明后，update 自动合成——无需手写 set | `SET ..., version = version + 1 WHERE id = ? AND version = ?`（affected=0 即冲突，重试/报错为调用方语义） |
+| 扣库存（防超卖） | `set: [{ col: stock, expr: bin('sub', col(stock), param('qty')) }]` + `where`（stock gte） | `SET stock = stock - ? WHERE id = ? AND stock >= ?` |
+| 扣款 | 同上（balance - param('amt')） | `SET balance = balance - ? WHERE balance >= ?` |
+| 列间运算 | `bin('sub', col(stock), col(locked))` | `SET stock = stock - locked` |
+| 状态机 CAS | args 直接赋值 + `where`（现状已支持） | `SET state = 'refund' WHERE id = ? AND state = 'success'` |
+
+**机器校验（lint）**：列引用属于 `dao.table` 或 args 实体；param 名唯一且进签名；lit 类型与列类型相容；bin 左右类型相容。
+
+**安全**：AST → SQL 全受控（列名来自 Field、op 封闭、值走 knex 绑定参数），无注入面。
+
+**扩展性**：未来加节点 = 加 kind（如 `{ kind: 'fn', name: 'greatest', args: ValueExpr[] }`、一元取负），不动已有结构、不改存量声明——AST 的价值所在。
+
+### 3.7 乐观锁一等公民（TableSchema.version）
+
+乐观锁是表级属性（版本列属于表，不随方法变化），声明收敛到 `TableSchema.version`，update 自动合成版本自增 + 版本条件——不要求每个方法手写 `incr(version, lit(1))`。
+
+```ts
+defineTable({
+  name: 'order',
+  columns: { ..., version: { type: 'integer' } },
+  version: order.columns.version,   // 乐观锁版本列（列引用）
+});
+```
+
+**语义**：
+
+| 机制 | 行为 |
+|---|---|
+| `TableSchema.version?: Field` | 指向本表一个整数列；定义期校验：属于本表 + 类型为 integer/number |
+| update（有 version 的表） | args 实体**必须含 version 列**（lint）；生成器从 row 提取 version 进 WHERE，set 自动合成 `version = version + 1`，其余列直接赋值——签名不变 `update(row)`，返回 affected rows，0 = 冲突（重试/报错为调用方语义） |
+| insert | 照旧——version 初始值（0/1）由调用方在行数据里给，生成器不注入 |
+| delete / get / find | 不受影响（乐观锁 delete 如需要，另议） |
+| 与 `set?: SetExpr[]` 的关系 | 互斥——version 列由一等公民机制管理，set 表达式不得再引用 version 列（lint） |
+
+**与 tenant 形态一致**：row 里的 version 列与 row 里的 tenant FK 列同构——都是"行内列既进 WHERE 又不在 set"（destructure 后进 where），签名都只有一个 row。三种隐式列（pk / tenant FK / version）的 WHERE 提取是同一生成器函数。
+
+**价值**：乐观锁零声明成本（表声明一次，所有 update 自动生效）、不可遗漏（lint 强制 args 含 version 列）、调用方直接受影响行数判断冲突。
+
+## 4. dao_schema v2 方法形态
+
+```ts
+// find — 精确列 + 多表 + 分页 + filter
+find: {
+  type: 'find',
+  args?: FilterSchema,          // 查询条件（现状不变）
+  results: EntitySchema,           // SELECT 列 + 行类型（可跨表）
+  mode?: 'page' | 'limit',      // 分页（现状不变）
+  orderBy?: OrderBySchema | OrderBySchema[],
+},
+// 扩展点（7.2 验证倒逼）：
+//   results: EntitySchema | Field —— Field = 单列投影（valueList：List<值>）
+//   Operator + 'in' / 'null' / 'notNull'（IN 条件 / NULL 条件）
+//   join 类型 left/inner 声明位（filter 跨表条件 inner join 过滤主表）
+
+// get — 机制语义：按精确键取单行（任意列组合，不限于 PK；复合 PK / getByXX 均合法）
+get: {
+  type: 'get',
+  args: Field | Field[],        // 单字段或 AND 精确匹配的多字段（复合 PK）
+  where?: FilterSchema,         // 附加条件（AND 到键上）："PK + 状态条件"取单行 / 乐观锁读取
+  results: EntitySchema,           // 可多表
+},
+
+// insert — 精确列（现状语义已对，不变）
+insert: { type: 'insert', args: EntitySchema },
+
+// update — 精确 set 列 + PK + tenant（+where filter 现状不变）
+update: { type: 'update', args: EntitySchema, where?: FilterSchema },
+// 表达式能力（3.6 ValueExpr 模型）：set?: SetExpr[]（col = expr）、FilterCondition.right?: ValueExpr
+
+// delete — 按精确键删除（复合 PK 支持）
+delete: { type: 'delete', args: Field | Field[] },
+
+// aggregate — filter + tenant + filter 跨表 join（现状 + tenant）
+aggregate: { type: 'aggregate', args?: FilterSchema, results: EntitySchema },
+```
+
+**方法名与机制 type 正交**：dao_schema 是**低级机制**——`type` 只表达"怎么查"（按 PK 取单行 / 条件列表 / 写 / 删 / 聚合），六种机制封闭，不再随业务新增；方法名（methods map 的 key）是**业务语义**，自由命名，生成器原样保留。同一个机制可以有多个业务方法，每个方法有各自的 args/results：
+
+```ts
+defineDao({
+  name: 'MerchantDao',
+  table: merchantTable,
+  methods: {
+    get:    { type: 'get', args: pk,     results: merchantGetRow },    // curd get：单表精确列
+    detail: { type: 'get', args: pk,     results: merchantDetailRow },  // curd detail：多表 + label
+    getByOrderNo: { type: 'get', args: orderNoField, results: merchantGetRow },  // 任意列精确取单行
+    getByCombo: { type: 'get', args: [orderNoField, merIdField], results: merchantGetRow },  // 多字段 AND（复合 PK 同理）
+    page:   { type: 'find', mode: 'page', ... },   // curd page
+    list:   { type: 'find', ... },                 // curd list
+    query:  { type: 'find', ... },                 // curd keyword query
+  },
+});
+```
+
+因此 dao 语义**不需要**为业务延伸出新 type（如 `getDetail`）——延伸发生在方法名与键组合层面：`get` 的 args 是"精确键"（任意列或列组合），`getByXX`、复合 PK 都是合法声明。curd 生成 dao_schema 时业务方法名原样保留（`page`/`list`/`query`/`get`/`detail`），service/controller 对 `dao.page(...)`、`dao.detail(...)` 的引用签名不变。
+
+**curd 方法 → dao_schema 映射**：
+
+| curd 业务方法 | 机制 type | 差异 |
+|---|---|---|
+| `page` | `find` + `mode: 'page'` | `table.paginated === true` 时 curd 生成 page；映射规则：paginated → `mode: 'page'`（方法名 page），非 paginated → 无 mode（方法名 list） |
+| `list` | `find` | — |
+| `query`（keyword） | `find`（同一 filter） | 无分页参数；keyword 存在才生成 |
+| `get` | `get`（单表 EntitySchema） | — |
+| `detail` | `get`（多表 EntitySchema） | 单表 vs 多表只是 EntitySchema 内容差异 |
+| `insert` / `update` | `insert` / `update` | — |
+| （无 delete） | `delete` 机制保留并补租户 | — |
+
+**对齐检查：v2 能力 ≥ curd 现状（逐项）**：
+
+| curd 现状能力 | v2 覆盖 | 说明 |
+|---|---|---|
+| 精确 select 列 | ✅ 3.1 EntitySchema | — |
+| FK label 自动展开 | ✅ 3.2 | 展开声明方式待决策 7 |
+| 跨表列 + leftJoin 推导 | ✅ 3.3 | 结果列 + filter + label 合并 sources |
+| tenant 强制参数 + WHERE | ✅ 3.4 | — |
+| filter 柯里化 + keyword 端点 | ✅（现状共享 `renderFilterFile`） | — |
+| 分页 | ✅ 收敛到 `paginate()` | curd 自写 count 与 `paginate()` 等价（clone + clearSelect） |
+| 单列 orderBy | ✅ `find.orderBy` | 且支持多列 |
+| generator 表 insert 补 PK | ✅ 现状 gen-dao 已实现 | — |
+| 枚举列类型 | ✅ 3.1 enum 渲染 | **gen-dao 现状有 bug**（jsType 退化），v2 修复 |
+| 类导出形态 | ✅ 一致 | `export default class` + `export const xxxDao = new XxxDao()` 两边相同 |
+
+**行为差异点（统一后变化，消费方需同步）**：
+
+1. **get 的 miss 返回**：curd 现状 `Promise<Row | undefined>`，gen-dao 现状 `Promise<Row | null>`——v2 统一 `| null`，curd 的 service/controller 生成器的 undefined 判断改为 null 判断；
+2. **PagedRows import 来源**：curd 从 `@pylonts/core`，gen-dao 从 `@pylonts/dao`——统一 `@pylonts/dao`；
+3. **select 列 qualified**：curd detail 全 table-qualified（`merchant.id`），page 单表裸列——v2 规则：单表裸列、多表重名列 alias（3.1），多表唯一列 qualified 裸名。
+
+**新增校验**（defineDao/loadDaos）：
+
+| 校验 | 规则 |
+|------|------|
+| 写方法单表 | insert/update 的 args 列必须全部来自 `dao.table` |
+| 键列属于主表 | get/delete 的 args 字段必须属于 `dao.table`（跨表键不走 get/delete） |
+| 读方法 FK | find/get 结果列的跨表 source 必须有 main-table FK 指向，否则报错 |
+| 租户一致性 | app 有 tenant 且 table 有 FK → 方法必须能注入（机器推导，无声明可错） |
+
+## 5. 产物形态（gen-dao 输出样例）
+
+```ts
+// {api}/src/modules/{app}/dao/MerchantDao.ts
+import { knex, paginate, type PagedRows } from '@pylonts/dao';
+import { merchantListFilter, type MerchantListFilterArgs } from '../filter/MerchantListFilter';
+
+export interface MerchantListRow {           // EntitySchema.columns 渲染
+  id: string;
+  name: string;
+  status: MerchantStatus;
+  shop_name: string;                          // FK label 别名（推导）
+}
+
+export default class MerchantDao {
+  // 业务名 page，机制 find + mode page
+  async page(page: number, pageSize: number, filter: MerchantListFilterArgs, shopId: string): Promise<PagedRows<MerchantListRow>> {
+    return paginate<MerchantListRow>(
+      merchantListFilter(filter)(knex('merchant')
+        .leftJoin('shop', 'shop.id', 'merchant.shop_id'))   // renderJoins（结果列 + filter 条件合并）
+        .select('merchant.id', 'merchant.name', 'merchant.status', 'shop.name as shop_name')
+        .where('merchant.shop_id', '=', shopId),            // tenant 无条件 WHERE
+      page, pageSize,
+    );
+  }
+
+  // 业务名 get，机制 get（单表 EntitySchema）
+  async get(id: string, shopId: string): Promise<MerchantGetRow | null> {
+    return knex('merchant')
+      .select('merchant.id', 'merchant.name')
+      .where({ id })
+      .where('merchant.shop_id', '=', shopId)
+      .first();
+  }
+
+  // 业务名 detail，机制 get（多表 EntitySchema）——同一机制的第二业务方法
+  async detail(id: string, shopId: string): Promise<MerchantListRow | null> {
+    return knex('merchant')
+      .leftJoin('shop', 'shop.id', 'merchant.shop_id')
+      .select('merchant.id', 'merchant.name', 'shop.name as shop_name')
+      .where({ id })
+      .where('merchant.shop_id', '=', shopId)
+      .first();
+  }
+
+  // update + tenant
+  async update(row: MerchantUpdateRow, shopId: string): Promise<number> {
+    const { id, shop_id, ...data } = row;
+    return knex('merchant').where({ id }).where('shop_id', '=', shopId).update(data);
+  }
+}
+```
+
+## 6. 消费方连锁影响
+
+| 消费方 | 影响 |
+|--------|------|
+| curd service/controller/page 生成器 | 行类型 import 从 `../entities/{Pascal}Entity` 改为 DAO 文件导出（或统一 entities 目录，待决策）；方法签名变化（tenant 参数） |
+| curd entity 生成器 | 退役：`entities/{Pascal}Entity.ts` 的 ListRow/AddRow/UpdateRow 改为产出 `entity_schema/{api}/{app}/entity/{table}.entity.ts` 声明（文件名=表名的机器规则正好容纳） |
+| curd dao/dao_utils | `createSqlBuilder`/`buildJoins`/`renderPageResult`（自写 count 分页）全部退役，产物语义移入 gen-dao |
+| flow（`FlowMethodRef` 含 DaoMethodSchema） | dao 方法签名变（tenant 参数）→ flow invoke 的 args 槽位渲染与 service 绑定校验同步 |
+| lint dao / entity-check | 新增写方法单表、读方法 FK、别名唯一、租户一致性检查 |
+
+## 7. 分阶段落地
+
+| 阶段 | 内容 | 产出 |
+|------|------|------|
+| 1 | dsl：`EntitySchema`（`columns: Field[]`，alias 隐式推导）、find/get 的 results 升级、get/delete args 放宽为 `Field \| Field[]`（任意键组合/复合 PK）+ get `where?: FilterSchema`、`ValueExpr` 表达式模型（3.6，update set + 条件右值）、`TableSchema.version` 乐观锁一等公民（3.7）、写方法单表/读方法 FK 校验、tenant 语义文档化 | `dsl/src/db.ts`、`dsl/src/dao.ts`、`dsl/src/entity.ts`（或新 row.ts）、`dsl/src/filter.ts`、`dsl/src/expr.ts`（或并入 dao.ts）+ 测试 |
+| 2 | gen：`renderJoins` 泛化、alias 推导（map 计数重名列 + `{表短语 ?? 表名}_{列名}` 公式）、gen-dao 按 v2 升级（精确列 select、get 多表、tenant 注入、分页统一 paginate）+ 测试 | `gen/src/gen-dao.ts`、`gen/src/filter-render.ts` |
+| 3 | curd：dao/entity 生成器改为产出 dao_schema + entity_schema 声明；service/controller/page import 改向；自写 count/join 代码退役 | `curd/src/dao.ts`、`curd/src/entity.ts` 等 |
+| 4 | flow invoke 同步 + lint dao 新规则 + examples 全量回归 | cli lint、examples |
+
+**阶段 2 之后、阶段 3 之前存在过渡期**：gen-dao 已升级，curd 仍直产实现（旧语义）——filter 模块文件继续幂等共享，不冲突。阶段 3 完成即两条路径合一。
+
+## 7.1 复杂项目验证（思维实验：cca-pay trans）
+
+用真实支付项目 `cca-back-server/cca-pay-parent/cca-pay` 的核心业务（zoom `dao.ar` ActiveRecord 形态）对照 v2 能力：
+
+| cca-pay 现状（zoom AR） | dao_schema v2 表达 | 覆盖 |
+|---|---|---|
+| `dao.ar(Pay.class).insert(pay)` | `insert`（args 精确列） | ✅ |
+| `.filter("state\|chId\|chTime\|errMsg\|errCode").update(pay)`（列白名单 update） | `update` args 精确列 | ✅ |
+| `.where("state", success).filter("state").update(pay)`（乐观锁条件更新，判影响行数） | `update` + `where?: FilterSchema` | ✅ |
+| `.get(id)` / `.where("id", id).get()` | `get` 单键 | ✅ |
+| `.where("devId", devId).where("devSeq", devSeq).get()`（组合键） | `get` args `Field[]`（v2 放宽） | ✅ |
+| `.where("state", success).get(id)`（PK + 状态条件取单行） | `get` + `where?: FilterSchema`（本次补充） | ✅ |
+| `.where(...).count() > 0`（contains） | `aggregate` count 或 `find` + limit 1 | ✅ |
+| `fill()` 可选条件分页 + 日期范围（GTE/LTE） | `find` + filter（optional 条件 + `op: 'gte'/'lte'`） | ✅ |
+| `orderBy("id", DESC)` + `.page(...)` | `find.orderBy` + `mode: 'page'` | ✅ |
+| `PayStatistics`（count(\*) + sum(amt) 聚合投影） | `aggregate` + `Compute.count/sum` | ✅ |
+| 同一查询多投影（Pay 全行 / 子集 / 统计） | 多个方法共享同一 filter，EntitySchema 各异 | ✅ |
+| 一表多实体（Pay / PayForRefund / PayStatistics 同表 t_pay） | 多 EntitySchema/EntitySchema 绑定同表 | ✅ |
+| enum 存 ordinal（int） | enum `valueType: 'integer'` | ✅ |
+| `@ColumnIgnore`（exception 不落库） | 列不进 EntitySchema 即可 | ✅ |
+| ID 生成器（时间 + 序号 snowflake 变体） | `table.generator` + `@pylonts/id-gen` registry | ✅ |
+| `@Trans` / `@EventNotifier` | `@pylonts/dao` `@Trans` / `@pylonts/event` | ✅ |
+| `dao.ar(Pay.class, table)`（表名运行时参数） | dao 绑定固定 table | ❌ 待决策 8（当前全传 baseTable，防御性预留） |
+| `@LockKey`（分布式锁）/ `@CacheKey`（缓存） | 无 | ❌ 非 dao 范围（service 层能力，flow 建模时会遇到） |
+
+**结论**：trans 核心业务的 DAO 形态 16/18 可表达；两个缺口——动态表名（当前无真实分表需求，待决策 8）与分布式锁/缓存（dao 生成范围之外）。乐观锁更新与"PK+条件取单行"促使本次补充 `get.where?: FilterSchema`。
+
+## 7.2 复杂项目验证（思维实验：v-pay 虚拟卡支付）
+
+`v-pay-impl`（zoom AR 形态，比 trans 更重：批量、IN、NULL、聚合粒度 DAO）：
+
+| v-pay 现状（zoom AR） | dao_schema v2 表达 | 覆盖 |
+|---|---|---|
+| `whereIn("bsUsrId", ids)` / `whereIn("id", cardIds)`（IN 条件，高频） | ❌ Operator 无 `in` | **缺口 1：Operator + `'in'`** |
+| `whereNull("nextSendTime")`（NULL 条件） | ❌ 无条件位 | **缺口 2：Operator + `'null'/'notNull'`** |
+| `valueList("id", Integer.class)`（单列投影 List） | ❌ find.results 只有 EntitySchema | **缺口 3：results 支持单 Field（单列列表）** |
+| `@Batch` 批量 update（filter + List）/ 批量 insert（`ar.insert(list)`） | ❌ 单行方法 | **待决策 10（批量机制）** |
+| `filter(...).ignoreNull(false).update`（null 跳过/动态部分更新） | ❌ set 列静态声明 | **待决策 11（update null 语义）** |
+| INNER JOIN 实体（`builder(VOp.class).join(INNER, "v_usr_op", ...)`） | ❌ join 推导全 LEFT | **待决策 12（join 类型 left/inner 声明）** |
+| 聚合粒度 DAO（VOpDaoImpl 一个类管 v_op + v_usr_op + v_op_detail 三表） | ⚠️ dao_schema 一 dao 一表 | **边界确认：多表编排 = service + 未来 Repository，dao_schema 不收编** |
+| `getByBsIdAndIds`（eq + in 组合） | 缺口 1 补上后 ✅ | — |
+| 插入冲突重试（while + DuplicateEntry） | insert 已够，重试为 service 层语义 | ✅ |
+| fill 可选条件 + orderBy + page + count | find/aggregate | ✅ |
+| 动态 Class 多投影 | 多方法共享 filter、EntitySchema 各异 | ✅ |
+| `StringUtils.join(ids, ",")`（IDs 逗号串列） | 业务数据形态，与 dao 机制无关 | ✅ |
+
+**结论**：v-pay 的单行/查询形态大部分可表达；4 个机制缺口（in、null 条件、单列投影、join 类型）+ 2 个模型级待决策（批量、update null 语义）。最重的发现是**聚合粒度 DAO**——VOpDaoImpl 是聚合仓储雏形（v_op 根 + v_usr_op 成员 + detail），这印证 dao_schema 单表原子性的边界正确：多表落库编排归 service（flow）+ @Trans，批量映射插入 = service 循环 + @Trans，未来由 Repository（aggregate.md 规划）收编。
+
+## 7.3 参照系：zoom mapper（Java zoom-dao 的方法约定式 DAO）
+
+zoom mapper = 接口方法名约定 + 参数注解（`@Like`/`@WhereIn`/`@Condition`/`@IgnoreNull`/`@Filter`/`@Version`/`@Select`/`@OrderBy`）驱动 SQL 生成。**TS 生态无此形态**（Java 编译期注解处理的产物）；TS 的成熟参数化编排 = Prisma 式参数对象（`findMany({ where, orderBy, take, skip })`）或 Drizzle/MikroORM 链式构建器。pylon dao_schema 走第三条路：显式声明 + 生成器。
+
+**两条"严格字段映射"路线的对比**（入口不同，目标相同）：
+
+| | zoom @Condition | pylon ValueExpr |
+|---|---|---|
+| 入口 | SQL 片段字符串（`"name=? and (time>? or time<?)"`） | 结构化表达式 AST（`{ kind: 'bin', ... }`） |
+| 严格映射手段 | **SQL 分析器**：解析片段、字段名严格映射到实体列、参数化绑定（全部转化为 `a=? and b=? and c in (?,?,?)` 形式防注入） | **结构即校验**：列引用是 Field 对象（定义期归属校验），值走绑定参数——无需解析器，无解析歧义 |
+| 复杂度 | 高（需维护 SQL 分析器） | 低（AST 遍历 + 定义期校验） |
+| pylon 选择 | 不走 | **采用**（3.6） |
+
+**方向验证（zoom 实践印证 pylon 设计）**：
+
+| zoom mapper | pylon | 状态 |
+|---|---|---|
+| `@Version` → 自动 `where version=当前值 + set version+1` | 3.7 `TableSchema.version` | 设计一致 |
+| `@Filter("id,name")` 更新列白名单 | update args 精确列 | 同构 |
+| **"dao 层一次只做一次 sql 元操作，事务在 Service 层"** | dao_schema 单表原子性 + service @Trans | 核心哲学一致 |
+| `@Select("id")` 单列投影 List | 缺口 3 | 印证 |
+
+**新缺口（zoom 有、pylon 无）**：
+
+1. **save / insertOrUpdate（upsert）**：`@Keys` 唯一键判断，DB 原生 upsert（返回 1=插入/2=更新）；v-pay `create` 的 while + DuplicateEntry 重试是缺 upsert 的手工模拟——待决策 13；
+2. **insertIgnore**：忽略唯一键冲突的插入（v-pay 高频）——与 13 合并讨论；
+3. **`@IgnoreNull` 默认语义**：zoom 的 update **默认跳过 null 字段**（`@IgnoreNull(false)` 才写 null）——待决策 11 的权威参照（主流默认 = null 跳过）；
+4. **动态 OrderBy**：`find(OrderBy.asc("id","name"))` 运行时排序参数，pylon 只有声明静态 orderBy——待决策 14。
+
+## 8. 待决策问题
+
+1. ~~**alias 声明**~~（已决策：完全推导，无声明字段——多表重名列 alias，唯一列裸名，map 计数机器可判；命名公式 = `{表短语 ?? 表名}_{列名}`，字段命名本身就是短语命名）
+2. ~~**insert 租户列**~~（已决策：**A 声明保证**——add 实体必须含 tenant 列（lint 校验），insert 全行插入，零生成器改动）
+3. ~~**update/delete 的 tenant 参数形态**~~（已决策：**update 走 row 内提取**——tenant 列从 row destructure 进 WHERE、不进 set，与 pk/version 三种隐式列同构，签名不变；**delete 走独立参数 `(id, shopId)`**——args 是键，tenant 无处可藏）
+4. ~~**行类型产出位置**~~（已决策：**统一 `entities/` 目录文件**（curd 现状被消费方引用）——gen-dao 的行类型 interface 从 DAO 文件移出）
+5. ~~**app 有 tenant 但表无 FK**~~（已决策：**跳过**——该 dao 无租户，存量项目不炸）
+6. ~~**get 参数顺序**~~（已决策：args 声明顺序 + tenant 最后）
+7. ~~**FK label 展开声明方式**~~（已决策：**隐式展开发生在 curd → dao_schema 生成环节**——curd 把被引用表 label 列写成外部引用列进 EntitySchema.columns；dao 层无 label 概念，纯外部引用列机制（3.2））
+8. **动态表名 / 同结构多表**：cca-pay 的 `dao.ar(Pay.class, table)` 支持表名运行时参数（当前全部传 baseTable，防御性预留）。dao_schema 的 dao 绑定固定 table 表达不了。选项：a 暂不支持（当前无真实分表需求，真分表时再设计）；b 方法级 `tableParam?: boolean`（生成 table 参数透传 knex）；c dao 绑定"表组"（同结构多表的集合声明）。
+9. ~~**update 的表达式 set 与列间比较**~~（已决策：`ValueExpr` 递归 AST + `set?: SetExpr[]` + `FilterCondition.right?: ValueExpr`，见 3.6；**乐观锁为一等公民 `TableSchema.version`（3.7），不走手写 set**）
+10. **批量操作**（v-pay `@Batch` 批量 update/insert）：机制级批量（insert/update 的 args 支持 EntitySchema 数组，生成批量方法）vs service 层循环 + @Trans（语义等价，N 次 SQL vs 批量提交）？——**后续课题，不进本次**
+11. **update 的 null 跳过语义**（v-pay `ignoreNull` 动态部分更新）：args 声明 `nullSkip` 标记 vs 保持静态列（声明多个 update 方法各管各列）？**zoom mapper 参照：`@IgnoreNull` 默认 true（跳过 null 列），主流默认 = null 跳过**。——**后续课题，不进本次**
+12. **join 类型**（v-pay INNER JOIN 实体）：find 的跨表 join 全 LEFT；INNER（join 表过滤主表）的声明位——`renderJoins` 的 sources 加类型标记？跨表 filter 条件天然需要 inner 语义（条件必须命中）？——**后续课题，不进本次**
+13. **upsert / insertIgnore**（zoom `save`/`insertOrUpdate` + `@Keys`；v-pay create 的冲突重试是手工模拟）：`save` 机制（args 实体 + 唯一键集合，生成 DB 原生 `INSERT ... ON DUPLICATE KEY UPDATE`）？还是坚持 service 层组合（insert 冲突 → 重试/update）？——**后续课题，不进本次**
+14. **动态 orderBy**（zoom `find(OrderBy.asc(...))` 运行时排序参数）：find 的 orderBy 参数化（排序列 + 方向运行时传入，列域受限）vs 保持声明静态？——**后续课题，不进本次**
+
 **本次实施范围**（已拍板）：v2 核心（EntitySchema / get·delete 放宽 / ValueExpr / TableSchema.version / tenant 注入）+ **Operator 'in'/'null'/'notNull'**（v-pay 高频刚需）。单列投影（缺口 3）与待决策 10-14 全部后续。