@pylonts/dsl 1.1.6 → 1.1.12

package/dist/third-service.js

@@ -85,6 +85,7 @@ export function defineThirdService(options) {
             schema,
             args: undefined,
             results: undefined,
+            throws: method.throws,
         };
         methodSchema.args = defineThirdMethod(method.args);
         methodSchema.results = defineThirdMethod(method.results);

package/dist/typebox-driver.js

@@ -62,6 +62,10 @@ function renderBasic(field, pattern, defaultValue, resolver, indent = 0) {
             }
             return `Type.Enum(${ref.name})`;
         }
+        case 'aggregate':
+            // Aggregate query outputs: count/sum(int) are numbers, everything else
+            // arrives as a precision string.
+            return field.jsType === 'number' ? 'Type.Number()' : 'Type.String()';
         case 'array':
             return `Type.Array(${renderFieldValue(field.items, indent, resolver)})`;
         case 'object':

package/dist/utils.d.ts

@@ -1,5 +1,5 @@
 import type { Field, SchemaBase } from './dsl.js';
-import type { FrontAppSchema } from './project.js';
+import type { FrontAppSchema, ProjectApiSchema } from './project.js';
 /** A utility method with a full signature. */
 export interface UtilsMethodSchema extends SchemaBase {
     type: 'utilsMethod';
@@ -15,13 +15,20 @@ export type UtilsMethodDef = Omit<UtilsMethodSchema, 'type' | 'schema' | 'name'>
 /** A base utility module (e.g. DateTimeUtils). */
 export interface UtilsSchema extends SchemaBase {
     type: 'utils';
-    /** Optional binding — empty means a shared public module. */
+    /** Backend binding — the api module this utils belongs to (shared instance
+     *  from project.config.ts apis). With `app` it serves that frontend
+     *  ({api}/{app}/utils/); alone it is the api's public module
+     *  ({api}/common/utils/). Unset = not backend-side. */
+    api?: ProjectApiSchema;
+    /** Optional binding — the frontend app this utils serves (shared instance
+     *  from project.config.ts apps). Empty means a shared public module. */
     app?: FrontAppSchema;
     /** Methods keyed by name — the map key is written back as the method name. */
     methods: Record<string, UtilsMethodSchema>;
 }
 export declare function defineUtils(options: {
     name: string;
+    api?: ProjectApiSchema;
     app?: FrontAppSchema;
     methods: Record<string, UtilsMethodDef>;
     description?: string;

package/dist/utils.js

@@ -1,8 +1,12 @@
 export function defineUtils(options) {
+    if (options.api !== undefined && options.app !== undefined && !options.api.apps.includes(options.app)) {
+        throw new Error(`utils ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
+    }
     const schema = {
         type: 'utils',
         name: options.name,
         description: options.description,
+        api: options.api,
         app: options.app,
         methods: {},
     };

package/docs/aggregate.md

@@ -0,0 +1,110 @@
+# 聚合与仓储 DSL 扩展规划（Aggregate / Repository）
+
+> 状态：**规划中（未实现）**
+> 关联代码：`dsl/src/db.ts`（TableSchema）、`dsl/src/dao.ts`（DaoSchema）、`dsl/src/service.ts`（ServiceSchema）
+> 背景对话：ts-libs 会话「dd DDD 扩展讨论」（商城下单用例）
+
+## 1. 背景：pylon 现状与 DDD 缺口
+
+**现状**：
+
+- `TableSchema` 是全局扁平数据字典（"表无物理归属"），orders / order_items 是两张互相独立声明、无聚合关系的表；
+- `DaoSchema` 是单表单 SQL（knex 透明代理），粒度 = 表，无跨表能力；
+- 多表读写由 service flow 手工编排：`dao.insert(orders) → dao.insert(order_items)` + 手工 `@Trans()`，"总额 = Σ明细"这类一致性靠开发者自觉，无强制约束。
+
+**DDD 缺口对照**（战术模式）：
+
+| DDD 概念 | dsl 现状 | 缺口 |
+|---------|---------|------|
+| 聚合 / 聚合根 | 无 | **全新概念** |
+| 值对象 | mock 识别"金额/手机号"语义 | 无声明层 |
+| 领域事件 | 只有 UI 组件事件（event.ts） | **全新概念** |
+| 领域服务 | 全混在应用服务（service_schema） | 需拆分 |
+| 仓储 | 无（DAO 粒度是表） | **全新概念** |
+| 应用服务编排 | service_schema + flow ✅ | 已具备 |
+| 防腐层 | ThirdServiceSchema 只隔离 | 缺模型映射 |
+
+## 2. 扩展一：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
+  },
+  invariants: [                             // 跨成员表不变式，挂聚合上，可被生成代码消费
+    { name: 'total = sum(items.price * items.qty)',
+      check: 'totalAmount == sum(items.price * items.qty)' },
+  ],
+  references: { productId: 'ProductAggregate' },  // 聚合间只按 ID 引用
+});
+```
+
+| 声明项 | 含义 | 缺了会怎样 |
+|--------|------|-----------|
+| `root` | 谁是聚合根 | 分不清一致性入口 |
+| `members` | 包含哪几个 table schema | "包含"只是列表，无结构 |
+| `members[i].via` | 成员表靠哪个外键挂根 | 工具无法推导 join / 级联关系 |
+| `invariants` | 跨成员一致性规则 | "总额=Σ明细"又回到 flow 里手工写 |
+| `references` | 聚合间只按 ID 引用 | 无法 lint 跨聚合直接持表引用 |
+
+**消费方**（声明一旦存在即可自动推导）：
+
+1. **生成 Repository**：按"加载 / 保存 / 删除"三套固定骨架自动产出（见下），`orders + order_items` 自动同事务，不再手工 `@Trans()`；
+2. **lint 约束**：禁止聚合外代码直接 `insert/update/delete` 成员表（只准经 root 走）；
+3. **不变式挂载**：save 前后强制校验。
+
+**多表映射三种模式**（聚合↔表）：A 单表=单聚合（1:1，几乎透明）；B 一聚合=多表（1:N，最常见，Order 案例）；C 多聚合共享表（N:1，DDD 不推荐）。
+
+## 3. 扩展二：RepositorySchema（可推导，也可显式声明）
+
+**作用**：聚合粒度的存储入口，把"哪些表一起查、怎么拼成聚合"的知识从 service flow 下沉到仓储。调用方只面对领域概念（Order），不面对表。
+
+```ts
+defineRepository({
+  name: 'OrderRepository',
+  aggregate: orderAggregate,   // 绑定聚合
+  // 内部如何落到 DAO 由 generator 按 aggregate 结构自动展开：
+  //   save(order)     = tx { ordersDao.upsert + orderItemsDao 级联 }
+  //   findByOrderNo() = ordersDao.get + orderItemsDao 按 order_no 查
+});
+```
+
+**聚合内 join 下沉、聚合间禁止 join**：
+
+- 聚合内：加载整个 Order（根 + 明细 + 地址）由 Repository 内部完成，调用方一行，join 知识声明在 `members[].via`；
+- 聚合间：只按 ID 引用，跨聚合 join 是 DDD 禁止的；展示商品名这类信息走读模型 / 查询服务（CQRS 的 Q 侧），或应用服务分步查 + 内存组装。
+
+**分层对照**：
+
+| 层 | 操作单元 | 一次操作覆盖 | dsl |
+|----|---------|------------|-----|
+| Service | 用例 | 跨多个聚合/服务 | service_schema ✅ |
+| Repository | **聚合** | orders + order_items 一个事务 | **本扩展** |
+| DAO | **表** | 单表一条 SQL | dao_schema ✅ |
+
+## 4. 扩展三：引入支持 DDD 的 TS 库（选型，待决策）
+
+dsl 是**声明期**（`defineAggregate` 声明结构），引入的库是**运行期**（代码跑起来时持久化/发事件）。两者互补，不冲突——声明可翻译为运行期库的配置。
+
+| 库 | 类型 | 聚合能力 | 与本扩展关系 |
+|----|------|---------|-------------|
+| **MikroORM** | ORM | Entity / Repository / Unit of Work / Identity Map / cascade persist | **首选参考**：`@OneToMany(cascade, orphanRemoval)` + `em.persist(order)` 就是"orders + order_items 同事务整体落库"的标准实现；AggregateSchema 声明可翻译成它的映射配置 |
+| **Remesh** | DDD 框架 | CQRS + 领域事件 + Command/Query 分离 | 领域事件 / CQRS 参考 |
+| **Emmett** | 事件溯源 | 聚合状态由事件重建 | 事件溯源聚合参考 |
+| TypeORM | ORM | Repository + cascade，无 UoW / Identity Map | 弱支持，不推荐 |
+| Prisma / Drizzle | 查询构建器 | 不支持聚合 | 需手工包 Repository |
+
+**建议**：运行时持久化参考/选用 **MikroORM**（聚合持久化设计最完整）；领域事件参考 **Remesh**。dsl 的 `AggregateSchema` 声明层本身无现成开源，属本项目的增量设计空间。
+
+## 5. 落地步骤（待办，未开工）
+
+1. `AggregateSchema` 类型 + `defineAggregate` + 定义期校验（root 必须在其表内、via 外键存在、成员表不能是其他聚合的 root 等）；
+2. `RepositorySchema` 类型 + `defineRepository`（或从 aggregate 自动推导生成）；
+3. `gen` 生成 Repository 代码：加载/保存/删除三套骨架 + 同事务包装（`@Trans()` 从声明推导）；
+4. `lint` 聚合边界检查：聚合外禁止直接改成员表、聚合间禁止跨表引用；
+5. 运行期库选型落地（MikroORM 或保持 DAO 同事务包装）。

package/docs/curd.md

@@ -1,111 +1,146 @@
-# 管理端 CRUD 页面标准（CurdSchema）
-
-CurdSchema 是**管理端专用**（`FrontAppSchema.type === 'admin'`）的 CRUD 页面标准：绑定一张实体表 + 一个管理端 app，描述列表页与新增/编辑/详情动作页生成所需的全部页面语义。一条 CurdSchema = 列表页（+ 动作页）的生成规格。
-
-页面定义文件按实体组织：`{project}/pages/{entity}.curd.ts`（与 `schema/*.table.ts` 平级）。
-
-**CurdSchema 只依赖 table schema（`Field` 实例），不挂钩 DTO（`DtoMessage`）**——DTO 由生成器按标准从 `columns` 推导。
-
-## 定义
-
-```ts
-import { defineCurd } from '@pylonts/dsl';
-
-export const orderCurd = defineCurd('order-curd', {
-  description: '订单管理',
-  app: webAdmin,                    // 所属管理端（project.config.ts 的 FrontAppSchema 共享实例）
-  table: order,                     // 绑定实体表（共享实例）
-  title: '订单管理',
-  section: '订单管理',               // 必填：sidebar 分组名
-  actions: [defineAction('EXPORT', '导出订单')],   // 额外操作按钮
-  actionPages: {
-    add:    { mode: 'modal', columns: [order.columns.order_no, order.columns.mer_id] },
-    update: { mode: 'modal', columns: [order.columns.id, order.columns.order_no] },
-    detail: { mode: 'route',  columns: [order.columns.id, order.columns.order_no, order.columns.amount] },
-  },
-  list: {
-    columns: [order.columns.id, order.columns.order_no, merchant.columns.name],  // 可跨表
-    keyword: { columns: [order.columns.order_no] },  // 模糊搜索（本表字段）
-    orderBy: { column: order.columns.id, direction: 'desc' },
-    searchFields: [{ field: order.columns.mer_id }, { field: order.columns.order_no, op: 'like' }],
-    columnTitles: { order_no: '订单号', name: '商户名称' },   // Field.name → 文案
-  },
-});
-```
-
-## 字段
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `app` | `FrontAppSchema` | 所属管理端（共享实例，`type` 必须为 `'admin'`） |
-| `table` | `TableSchema` | 绑定实体表（共享实例） |
-| `title` | `string` | 列表页中文标题 |
-| `section` | `string` | **必填**：sidebar 分组名（`pylonts gen curd` 据此生成路由注册的 `section` 字段） |
-| `actions?` | `ActionSchema[]` | 页面额外可执行动作（标准 CRUD 之外，如导出、审核） |
-| `actionPages?` | `{ add? / update? / detail? }` | 动作页：`{ mode: 'modal' \| 'route'; columns: Field[] }` |
-| `list` | `CurdListConfig` | 列表页配置（必填） |
-
-### ActionPage
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `mode` | `'modal' \| 'route'` | 弹窗或独立路由 |
-| `columns` | `Field[]` | 该页面渲染的字段，**必填非空**——前端要显示的字段必须全部显式列出 |
-
-### CurdListConfig
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `columns` | `Field[]` | 列表列，**必填非空**——前端要显示的字段必须全部显式列出；可含跨表字段（见下） |
-| `keyword?` | `{ columns: Field[] }` | 模糊搜索，columns 必须是**本表字段实例** |
-| `orderBy` | `{ column: Field; direction: 'asc' \| 'desc' }` | 默认排序，**必填**，column 与 direction 都必填；column 必须是**本表字段实例** |
-| `searchFields?` | `{ field: Field; op?: Operator }[]` | 搜索条件字段，op 默认 `'eq'`，可选 `eq/gt/gte/lt/lte/like/ne` |
-| `columnTitles?` | `Record<string, string>` | 列标题覆盖：`Field.name` → 中文文案 |
-
-## 跨表字段
-
-`columns` / `searchFields` 里的 `Field` 实例可指向**本表或其他表**的列——列表列与搜索条件因此可以显示关联表字段（如订单列表显示商户名称）：
-
-```ts
-list: {
-  columns: [order.columns.id, order.columns.order_no, merchant.columns.name],  // 跨表：字段指向 merchant.name
-}
-```
-
-## 默认与校验
-
-- `list.columns` / `actionPages.*.columns` **必填非空**（不允许省略、不允许空数组）——前端显示什么必须显式定义
-- `list.orderBy` **必填**，`column` 与 `direction` 都必填（规格：默认主键 desc 由定义方显式写出）
-- 运行时校验（`defineCurd`，仿 `defineTable` 强校验风格）：
-  - `app.type` 必须为 `'admin'`，否则抛错
-  - 所有 `columns` 非空，否则抛错
-  - `list.keyword.columns` / `list.orderBy.column` 必须属于 `table`，否则抛错
-  - `list.columns` / `list.searchFields` 允许跨表，**不校验归属**
-- 生成时校验（curd 生成器，`DtoSchemaGen.add` / `update`）：
-  - 表配置 `autoIncrement` 或 `generator`（主键由服务端生成）时，`actionPages.add.columns` **不允许包含主键字段**，否则抛错——AddRequest 不携带服务端生成的主键
-  - `actionPages.update.columns` **必须包含主键字段**，否则抛错——UpdateRequest 靠主键定位记录
-
-## DTO 推导（生成器约定）
-
-DTO 由 curd 生成器从 `CurdSchema` 按标准命名推导，页面语义不持有 DTO 实例：
-
-| DTO | 命名 | 字段来源 |
-|---|---|---|
-| Row | `{Pascal}Row` | `list.columns` |
-| AddRequest | `{Pascal}AddRequest` | `actionPages.add.columns` |
-| UpdateRequest | `{Pascal}UpdateRequest` | `actionPages.update.columns` |
-| DetailRequest | `{Pascal}DetailRequest` | 主键 |
-| DetailResponse | `{Pascal}DetailResponse` | `actionPages.detail.columns` |
-
-## 与旧 PageConfig 的差异
-
-| PageConfig（旧方案，已废弃） | CurdSchema |
-|---|---|
-| `module: string` | 由 `app` 推导（后端模块 == app 1:1） |
-| `schema: 'bd'` 字符串 | `table: TableSchema` 实例（类型安全） |
-| `operations: { label, action }` | `actions: ActionSchema[]` |
-| `detail.mode` 单例 | `actionPages.detail.mode` |
-| `forms.add / forms.update` | `actionPages.add / actionPages.update` |
-| `keyword` / `orderBy` / `columnTitles` | `list.keyword` / `list.orderBy` / `list.columnTitles`（列改字段实例引用） |
-| `naming` | 去掉（DTO 命名是生成器约定，非页面语义） |
-| DTO 引用（`request` / `fields` / `DtoFields`） | 去掉（DTO 由生成器推导，页面只依赖 table） |
+# 管理端 CRUD 页面标准（CurdSchema）
+
+CurdSchema 是**管理端专用**（`FrontAppSchema.type === 'admin'`）的 CRUD 页面标准：绑定一张实体表 + 一个管理端 app，描述列表页与新增/编辑/详情动作页生成所需的全部页面语义。一条 CurdSchema = 列表页（+ 动作页）的生成规格。
+
+页面定义文件按实体组织：`{project}/pages/{entity}.curd.ts`（与 `schema/*.table.ts` 平级）。
+
+**CurdSchema 只依赖 table schema（`Field` 实例），不挂钩 DTO（`DtoMessage`）**——DTO 由生成器按标准从 `columns` 推导。
+
+## 定义
+
+```ts
+import { defineCurd } from '@pylonts/dsl';
+import { admin } from '../project.config';
+import { order } from '../schema/order.table';
+import { merchant } from '../schema/merchant.table';
+import { orderListFilter } from '../filter_schema/api/admin/filter/order-list.filter';
+
+export const orderCurd = defineCurd('order', {   // name = table.name 的 kebab（即 admin 路由路径）
+  description: '订单管理',
+  app: admin,                      // 所属管理端（project.config.ts 的 FrontAppSchema 共享实例）
+  table: order,                     // 绑定实体表（共享实例）
+  title: '订单管理',
+  section: '订单管理',               // 必填：sidebar 分组名
+  actions: [defineAction('EXPORT', '导出订单')],   // 额外操作按钮
+  actionPages: {
+    add:    { mode: 'modal', columns: [order.columns.order_no, order.columns.mer_id] },
+    update: { mode: 'modal', columns: [order.columns.id, order.columns.order_no] },
+    detail: { mode: 'route',  columns: [order.columns.id, order.columns.order_no, order.columns.amount] },
+  },
+  list: {
+    columns: [order.columns.id, order.columns.order_no, merchant.columns.name],  // 可跨表
+    filter: orderListFilter,       // 搜索表单 + keyword（FilterSchema 引用，可选）
+    orderBy: { column: order.columns.id, direction: 'desc' },
+    columnTitles: { order_no: '订单号', name: '商户名称' },   // Field.name → 文案
+  },
+});
+```
+
+搜索条件**不内联在 list 里**，而是独立的 **FilterSchema**（`defineFilter`）声明，存放在 `filter_schema/{api.name}/{app.name}/filter/`（机器校验：一文件一 filter，文件名 = 名字去 Filter 后缀转 kebab）：
+
+```ts
+// filter_schema/api/admin/filter/order-list.filter.ts
+import { defineFilter } from '@pylonts/dsl';
+import { admin, api } from '../../../project.config';
+import { order } from '../../../schema/order.table';
+
+export const orderListFilter = defineFilter({
+  name: 'OrderListFilter',
+  api,
+  app: admin,
+  conditions: [
+    { field: order.columns.status, optional: true },              // op 默认 eq；optional = 有值才加 WHERE
+    { field: order.columns.order_no, op: 'like', optional: true },
+  ],
+  keyword: { columns: [order.columns.order_no] },                 // 单输入值多列 OR 模糊
+});
+```
+
+生成物为 `{api}/src/modules/{app}/filter/{FilterName}.ts`（两段柯里化 WHERE 拼装方法，DAO/Service 列表查询共用）。
+
+## 字段
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `app` | `FrontAppSchema` | 所属管理端（共享实例，`type` 必须为 `'admin'`） |
+| `table` | `TableSchema` | 绑定实体表（共享实例） |
+| `title` | `string` | 列表页中文标题 |
+| `section` | `string` | **必填**：sidebar 分组名 |
+| `actions?` | `ActionSchema[]` | 页面额外可执行动作（标准 CRUD 之外，如导出、审核） |
+| `actionPages?` | `{ add? / update? / detail? }` | 动作页：`{ mode: 'modal' \| 'route'; columns: Field[] }` |
+| `list` | `CurdListConfig` | 列表页配置（必填） |
+
+### ActionPage
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `mode` | `'modal' \| 'route'` | 弹窗或独立路由 |
+| `columns` | `Field[]` | 该页面渲染的字段，**必填非空**——前端要显示的字段必须全部显式列出 |
+
+### CurdListConfig
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `columns` | `Field[]` | 列表列，**必填非空**；可含跨表字段 |
+| `filter?` | `FilterSchema` | 页面过滤器引用：搜索表单（AND 条件）+ keyword（多列 OR 模糊）；缺省 = 无搜索表单 |
+| `orderBy` | `{ column: Field; direction: 'asc' \| 'desc' }` | 默认排序，**必填**，column 与 direction 都必填；column 必须是**本表字段实例** |
+| `columnTitles?` | `Record<string, string>` | 列标题覆盖：`Field.name` → 中文文案 |
+
+### FilterSchema（`defineFilter`）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `name` | `string` | PascalCase、`Filter` 结尾；导出名 = name 首字母小写 |
+| `api` | `ProjectApiSchema` | 所属后端 api（project.config.ts 共享实例）；`api.apps` 必须包含 `app` |
+| `app` | `FrontAppSchema` | 所属前端 app（共享实例）；必须与引用它的 curd 同 app |
+| `conditions?` | `FilterCondition[]` | AND 组合条件：`{ field, op?='eq', right?, optional? }`；`optional: true` = 有值才加 WHERE（页面搜索场景） |
+| `keyword?` | `{ columns: Field[] }` | 单输入值对多列 OR like 模糊；配置后驱动「关键词查询」端点（`query({ keyword })`，供 Select/AutoComplete 搜索） |
+
+## 跨表字段
+
+`list.columns` 与 filter `conditions` 里的 `Field` 实例可指向**本表或其他表**的列——列表列与搜索条件因此可以显示/过滤关联表字段（如订单列表显示商户名称、按商户名称过滤）。
+
+## 默认与校验
+
+- `list.columns` / `actionPages.*.columns` **必填非空**（不允许省略、不允许空数组）
+- `list.orderBy` **必填**，`column` 与 `direction` 都必填（规格：默认主键 desc 由定义方显式写出）
+- 运行时校验（`defineCurd`，仿 `defineTable` 强校验风格）：
+  - `app.type` 必须为 `'admin'`，否则抛错
+  - **`name` 必须是 `table.name` 的 kebab 形式**（name 即 admin 路由路径，不允许与所服务的表漂移）
+  - `section` 必填
+  - 所有 `columns` 非空，否则抛错
+  - `list.filter.app` 必须 === `curd.app`，否则抛错
+  - `list.orderBy.column` 必须属于 `table`，否则抛错
+  - `list.columns` 允许跨表，**不校验归属**
+- 运行时校验（`defineFilter`）：`api.apps` 包含 `app`；conditions 与 keyword 不能同时为空；keyword.columns 非空
+- 生成时校验（curd 生成器，`DtoSchemaGen.add` / `update`）：
+  - 表配置 `autoIncrement` 或 `generator`（主键由服务端生成）时，`actionPages.add.columns` **不允许包含主键字段**，否则抛错——AddRequest 不携带服务端生成的主键
+  - `actionPages.update.columns` **必须包含主键字段**，否则抛错——UpdateRequest 靠主键定位记录
+
+## DTO 推导（生成器约定）
+
+DTO 由 curd 生成器从 `CurdSchema` 按标准命名推导，页面语义不持有 DTO 实例：
+
+| DTO | 命名 | 字段来源 |
+|---|---|---|
+| Row | `{Pascal}Row` | `list.columns` |
+| ListRequest | `{Pascal}ListRequest` | filter 的 conditions（camelCase + op）与 keyword + 分页参数（`PageRequest`，仅 paginated 表） |
+| QueryRequest | `{Pascal}QueryRequest` | filter 的 conditions + keyword，无分页——keyword 查询端点专用（仅配置 keyword 时生成） |
+| ListResponse | `{Pascal}ListResponse` | `PageResult(Row)`（仅 paginated 表；非分页表列表接口直接返回 `Row[]`，不生成 ListResponse） |
+| AddRequest | `{Pascal}AddRequest` | `actionPages.add.columns` |
+| UpdateRequest | `{Pascal}UpdateRequest` | `actionPages.update.columns` |
+| DetailRequest | `{Pascal}DetailRequest` | 主键 |
+| DetailResponse | `{Pascal}DetailResponse` | `actionPages.detail.columns` |
+
+## 与旧 PageConfig 的差异
+
+| PageConfig（旧方案，已废弃） | CurdSchema |
+|---|---|
+| `module: string` | 由 `app` 推导（后端模块 == app 1:1） |
+| `schema: 'bd'` 字符串 | `table: TableSchema` 实例（类型安全） |
+| `operations: { label, action }` | `actions: ActionSchema[]` |
+| `detail.mode` 单例 | `actionPages.detail.mode` |
+| `forms.add / forms.update` | `actionPages.add / actionPages.update` |
+| `keyword` / `orderBy` / `columnTitles` | `list.filter`（FilterSchema）/ `list.orderBy` / `list.columnTitles` |
+| `naming` | 去掉（DTO 命名是生成器约定，非页面语义） |
+| DTO 引用（`request` / `fields` / `DtoFields`） | 去掉（DTO 由生成器推导，页面只依赖 table） |