@pylonts/dsl 1.1.11 → 1.1.13

package/dist/project.d.ts

@@ -43,8 +43,11 @@ export interface ProjectSchema extends SchemaBase {
  * api.apps references the same instances from project.apps, so an app served
  * by multiple APIs is defined once and referenced many times.
  *
- * Runtime-validates app type whitelist, unique names and api.apps reference
- * integrity (same style as defineTable/defineCurd).
+ * Runtime-validates app type whitelist, unique names, api.apps reference
+ * integrity (same style as defineTable/defineCurd), plus two naming
+ * conventions: every app/api/thirdApi dir equals its name ('api/' == 'api'),
+ * and the first api must be named exactly 'api' (prefixed names like
+ * 'xx-api' are only allowed from the second api on).
  */
 export declare function defineProject(name: string, schema: {
     description?: string;

package/dist/project.js

@@ -7,13 +7,26 @@ function checkInstanceName(project, kind, name) {
         throw new Error(`project ${project}: ${kind} name '${name}' must match ${INSTANCE_NAME_RE} (lowercase letters/digits/dashes; underscores are table-only)`);
     }
 }
+// Directory convention: the instance dir equals its name ('api/' == 'api').
+// One concept, one spelling — no separate dir/name pairs to keep in sync.
+function normalizedDir(dir) {
+    return dir.replace(/[\\/]+$/, '');
+}
+function checkDirMatchesName(project, kind, name, dir) {
+    if (normalizedDir(dir) !== name) {
+        throw new Error(`project ${project}: ${kind} '${name}' dir must equal its name (got '${dir}')`);
+    }
+}
 /**
  * Defines the project topology. FrontAppSchema instances are shared value objects:
  * api.apps references the same instances from project.apps, so an app served
  * by multiple APIs is defined once and referenced many times.
  *
- * Runtime-validates app type whitelist, unique names and api.apps reference
- * integrity (same style as defineTable/defineCurd).
+ * Runtime-validates app type whitelist, unique names, api.apps reference
+ * integrity (same style as defineTable/defineCurd), plus two naming
+ * conventions: every app/api/thirdApi dir equals its name ('api/' == 'api'),
+ * and the first api must be named exactly 'api' (prefixed names like
+ * 'xx-api' are only allowed from the second api on).
  */
 export function defineProject(name, schema) {
     const project = { name, ...schema, thirdApis: schema.thirdApis ?? [] };
@@ -30,6 +43,7 @@ export function defineProject(name, schema) {
         }
         if (!app.dir)
             throw new Error(`project ${name}: app '${app.name}' dir is required`);
+        checkDirMatchesName(name, 'app', app.name, app.dir);
     }
     const apiNames = new Set();
     for (const api of project.apis) {
@@ -41,18 +55,23 @@ export function defineProject(name, schema) {
         apiNames.add(api.name);
         if (!api.dir)
             throw new Error(`project ${name}: api '${api.name}' dir is required`);
+        checkDirMatchesName(name, 'api', api.name, api.dir);
         for (const ref of api.apps) {
             if (!project.apps.includes(ref)) {
                 throw new Error(`project ${name}: api '${api.name}' references app '${ref.name}' that is not a shared instance in project.apps (define once and reference it)`);
             }
         }
     }
+    if (project.apis.length > 0 && project.apis[0].name !== 'api') {
+        throw new Error(`project ${name}: first api must be named 'api' (got '${project.apis[0].name}'); prefixed names like 'xx-api' are only allowed from the second api on`);
+    }
     for (const third of project.thirdApis) {
         if (!third.name)
             throw new Error(`project ${name}: thirdApi name is required`);
         checkInstanceName(name, 'thirdApi', third.name);
         if (!third.dir)
             throw new Error(`project ${name}: thirdApi '${third.name}' dir is required`);
+        checkDirMatchesName(name, 'thirdApi', third.name, third.dir);
     }
     return project;
 }

package/dist/service.d.ts

@@ -1,17 +1,20 @@
-import type { SchemaBase } from './dsl.js';
+import type { CollectionSchemaBase, SchemaBase } from './dsl.js';
 import type { FrontAppSchema, ProjectApiSchema } from './project.js';
 import type { DtoMessage } from './dto.js';
 import type { ExceptionSchema } from './exception.js';
 import type { FlowSchema } from './flow.js';
-/** A backend service serving exactly one frontend app (1:1 module). */
-export interface ServiceSchema extends SchemaBase {
+/** A backend service serving one frontend app (1:1 module), or a
+ *  platform-shared domain service (app unset — shared across modules). */
+export interface ServiceSchema extends CollectionSchemaBase {
     type: 'service';
     /** The backend api module this service belongs to (shared instance from
      *  project.config.ts apis). Services are always backend-side, so storage is
-     *  service_schema/{api.name}/{app.name}/service/. */
+     *  service_schema/{api.name}/{app.name}/service/ — app unset = the api-level
+     *  common domain layer, stored at service_schema/{api.name}/common/service/. */
     api: ProjectApiSchema;
-    /** The frontend app this service serves (shared instance from project.config). */
-    app: FrontAppSchema;
+    /** The frontend app this service serves (shared instance from project.config).
+     *  Unset = api-level common domain service shared by all modules of the api. */
+    app?: FrontAppSchema;
     /** Methods keyed by name — the map key is written back as the method name. */
     methods: Record<string, ServiceMethodSchema>;
 }
@@ -20,11 +23,13 @@ export type ServiceMethodDef = Omit<ServiceMethodSchema, 'type' | 'schema' | 'na
 export declare function defineService(options: {
     name: string;
     api: ProjectApiSchema;
-    app: FrontAppSchema;
+    app?: FrontAppSchema;
     methods: Record<string, ServiceMethodDef>;
     description?: string;
 }): ServiceSchema;
-/** A method exposed by a service. */
+/** A method exposed by a business service — the contract with the calling
+ *  frontend. Third-party integration methods are a separate contract
+ *  (ThirdServiceMethodSchema): they can never bind a flow. */
 export interface ServiceMethodSchema extends SchemaBase {
     type: 'method';
     schema: ServiceSchema;

package/dist/service.js

@@ -1,6 +1,6 @@
 import { exceptionEndNames } from './flow.js';
 export function defineService(options) {
-    if (!options.api.apps.includes(options.app)) {
+    if (options.app && !options.api.apps.includes(options.app)) {
         throw new Error(`service ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
     }
     const schema = {

package/dist/third-service.d.ts

@@ -1,6 +1,6 @@
-import { CollectionSchemaBase, Field, SchemaBase } from './dsl.js';
+import type { SchemaBase } from './dsl.js';
+import type { DtoMessage } from './dto.js';
 import type { ExceptionSchema } from './exception.js';
-import type { FieldRuleEnd, FieldRuleSchema } from './field-rule.js';
 import type { ThirdApiSchema } from './project.js';
 /** A third-party integration service (e.g. tenpay wechat pay).
  *  Distinct from ServiceSchema (backend service bound to an app) and
@@ -13,65 +13,22 @@ export interface ThirdServiceSchema extends SchemaBase {
     /** Methods keyed by name — the map key is written back as the method name. */
     methods: Record<string, ThirdServiceMethodSchema>;
 }
-/** A method exposed by a third-party service. */
+/** A method of a third-party integration service. Same contract shape as
+ *  ServiceMethodSchema minus flow — the implementation lives in the external
+ *  system, there is nothing to model. Kept separate so a third method can
+ *  never bind a flow. */
 export interface ThirdServiceMethodSchema extends SchemaBase {
     type: 'method';
     schema: ThirdServiceSchema;
-    /** Input message — the Field-collection counterpart of a DtoMessage. */
-    args: ThirdMethodSchema;
-    /** Output message. */
-    results: ThirdMethodSchema;
-    /** Exceptions this method may throw (e.g. IOException, CodeException). */
-    throws?: ExceptionSchema[];
-}
-/** Field binding to a rule: which end the local wire field stands on.
- *  The ref always stands on the other end — from/to carry no extra information. */
-export interface ConvertFieldSchema {
-    /** The rule binding field and ref (rule = name + two ends). */
-    rule: FieldRuleSchema;
-    /** The end instance the local wire field stands on. */
-    end: FieldRuleEnd;
-}
-/** Same-fact variant link: a wire field carrying the same fact as a local
- *  entity column under a different type/format (e.g. total_fee in fen vs amount in yuan). */
-export interface ThirdFieldRef {
-    /** Wire field defined in this message (local definition). */
-    field: Field;
-    /** Field in another schema (table column or another message). */
-    ref: Field;
-    /** Optional rule binding — omitted when the fact is merely linked, not converted. */
-    convert?: ConvertFieldSchema;
-}
-/** A directional message of a third-party method: a Field collection mirroring
- *  TableSchema.columns, but fields hold wire-format names/types. A field may be
- *  a shared instance of a local entity column (same fact, same type) — its
- *  name/schema keep pointing at the table and the DTO projection inherits
- *  type/semantics from the entity, exactly like from(table). */
-export interface ThirdMethodSchema extends CollectionSchemaBase {
-    type: 'thirdMethod';
-    /** The method this message belongs to (direction implied by args/results slot). */
-    schema: ThirdServiceMethodSchema;
-    /** Wire-format fields. */
-    fields: Record<string, Field>;
-    /** Same-fact variant links: wire field -> local entity column. */
-    refs?: ThirdFieldRef[];
-}
-/** Message input for defineThirdMethod: type/schema are set by the builder. */
-export type ThirdMethodDef = Omit<ThirdMethodSchema, 'type' | 'schema'>;
-/** Build a third-party method message. Writes back name/schema on own fields
- *  (top-level and nested); shared entity columns keep their table identity and
- *  must be keyed by their column name. */
-export declare function defineThirdMethod(def: ThirdMethodDef): ThirdMethodSchema;
-/** Method input for defineThirdService: name is written back from the methods map key. */
-export interface ThirdServiceMethodDef {
     /** Input message. */
-    args: ThirdMethodDef;
+    args: DtoMessage;
     /** Output message. */
-    results: ThirdMethodDef;
+    results: DtoMessage;
     /** Exceptions this method may throw (e.g. IOException, CodeException). */
     throws?: ExceptionSchema[];
-    description?: string;
 }
+/** Method input for defineThirdService: name/schema are set by the builder. */
+export type ThirdServiceMethodDef = Omit<ThirdServiceMethodSchema, 'type' | 'schema' | 'name'>;
 export declare function defineThirdService(options: {
     schema: ThirdApiSchema;
     name: string;

package/dist/third-service.js

@@ -1,73 +1,3 @@
-/** Build a third-party method message. Writes back name/schema on own fields
- *  (top-level and nested); shared entity columns keep their table identity and
- *  must be keyed by their column name. */
-export function defineThirdMethod(def) {
-    const message = {
-        type: 'thirdMethod',
-        name: def.name,
-        description: def.description,
-        // Filled by defineThirdService.
-        schema: undefined,
-        fields: def.fields,
-        refs: def.refs,
-    };
-    for (const key of Object.keys(message.fields)) {
-        const field = message.fields[key];
-        if (field.schema === undefined) {
-            field.name = key;
-            field.schema = message;
-        }
-        else if (field.schema.type === 'table') {
-            // Shared entity column: from() names the projection after field.name, so
-            // a mismatched key would silently rename the wire field. Same-fact fields
-            // with different names go through refs instead.
-            if (field.name !== key) {
-                throw new Error(`thirdMethod '${message.name}': shared column key '${key}' must match the column name '${field.name}' — ` +
-                    `same-fact fields with different names go through refs instead`);
-            }
-        }
-        else if (field.schema !== message) {
-            throw new Error(`thirdMethod '${message.name}': field '${key}' already belongs to ${field.schema.type} '${field.schema.name}', cannot reuse`);
-        }
-        writeBackNested(message, field);
-    }
-    if (message.refs !== undefined) {
-        const ownFields = Object.values(message.fields);
-        for (const link of message.refs) {
-            if (!ownFields.includes(link.field)) {
-                throw new Error(`thirdMethod '${message.name}': ref field must be one of its fields`);
-            }
-            if (link.ref.schema === undefined || link.ref.schema === message) {
-                throw new Error(`thirdMethod '${message.name}': ref target '${link.ref.name}' must be defined in another schema`);
-            }
-            if (link.convert !== undefined) {
-                const ends = Object.values(link.convert.rule.ends);
-                if (!ends.includes(link.convert.end)) {
-                    throw new Error(`thirdMethod '${message.name}': convert end '${link.convert.end.name}' must be one of rule '${link.convert.rule.name}' ends`);
-                }
-            }
-        }
-    }
-    return message;
-}
-/** Write back name/schema on nested wire fields (array items, object properties);
- *  shared entity columns keep their table identity. */
-function writeBackNested(message, field) {
-    if (field.type === 'array') {
-        writeBackNested(message, field.items);
-        return;
-    }
-    if (field.type !== 'object')
-        return;
-    for (const key of Object.keys(field.properties)) {
-        const child = field.properties[key];
-        if (child.schema === undefined) {
-            child.name = key;
-            child.schema = message;
-        }
-        writeBackNested(message, child);
-    }
-}
 export function defineThirdService(options) {
     const schema = {
         type: 'thirdService',
@@ -78,20 +8,15 @@ export function defineThirdService(options) {
     };
     for (const key of Object.keys(options.methods)) {
         const method = options.methods[key];
-        const methodSchema = {
+        schema.methods[key] = {
             type: 'method',
             name: key,
             description: method.description,
             schema,
-            args: undefined,
-            results: undefined,
+            args: method.args,
+            results: method.results,
             throws: method.throws,
         };
-        methodSchema.args = defineThirdMethod(method.args);
-        methodSchema.results = defineThirdMethod(method.results);
-        methodSchema.args.schema = methodSchema;
-        methodSchema.results.schema = methodSchema;
-        schema.methods[key] = methodSchema;
     }
     return schema;
 }

package/dist/typebox-driver.d.ts

@@ -1,5 +1,4 @@
 import { DtoMessage, ImportBase } from './dto.js';
-import type { ThirdMethodSchema } from './third-service.js';
 export type EnumResolver = (enumName: string) => ImportBase | undefined;
 /** Collect all imports needed to render a DTO: include() bases + enum references. */
 export declare function collectDtoImports(schema: DtoMessage, resolver: EnumResolver | undefined, out: Map<string, ImportBase>): void;
@@ -11,8 +10,3 @@ export declare function renderDtoMessage(schema: DtoMessage, options?: {
     resolver?: EnumResolver;
     source?: string;
 }): string;
-/** Render one third-party method message export (const only — pair with
- *  renderDtoTypeExport for the Static type). */
-export declare function renderThirdMethodExport(schema: ThirdMethodSchema, resolver: EnumResolver | undefined): string;
-/** Collect all imports needed to render a third-party method message: enum references. */
-export declare function collectThirdMethodImports(schema: ThirdMethodSchema, resolver: EnumResolver | undefined, out: Map<string, ImportBase>): void;

package/dist/typebox-driver.js

@@ -1,3 +1,5 @@
+import { isDtoField, isDtoMessage } from './dto.js';
+import { collectEnumRefs } from './dsl.js';
 function renderString(s) {
     return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 }
@@ -116,18 +118,6 @@ function renderValue(f, indent, resolver) {
     // annotations; DB field defaults are not carried into the API contract.
     return renderBasic(f.field, f.pattern, f.default, resolver, indent);
 }
-/** Structural check — DtoMessage instances may come from a different module copy, so instanceof is unreliable. */
-function isDtoMessage(v) {
-    if (typeof v !== 'object' || v === null)
-        return false;
-    return v.type === 'dto';
-}
-/** Structural check — a DtoField wraps a Field in a .field property and has no .type of its own. */
-function isDtoField(v) {
-    if (typeof v !== 'object' || v === null)
-        return false;
-    return 'field' in v && !('type' in v);
-}
 function collectEnumImports(f, resolver, out) {
     if (f.field.type === 'array') {
         const items = f.field.items;
@@ -154,23 +144,15 @@ function collectEnumImports(f, resolver, out) {
 }
 /** Enum import collection over a plain Field (wire-format nested fields). */
 function collectFieldEnumImports(field, resolver, out) {
-    if (field.type === 'array') {
-        collectFieldEnumImports(field.items, resolver, out);
-        return;
-    }
-    if (field.type === 'object') {
-        for (const child of Object.values(field.properties))
-            collectFieldEnumImports(child, resolver, out);
-        return;
+    for (const jsName of collectEnumRefs(field)) {
+        const ref = resolver?.(jsName);
+        if (!ref)
+            throw new Error(`enum ${jsName}: no import ref — pass an EnumResolver`);
+        out.set(`${ref.from}#${ref.name}`, ref);
     }
-    if (field.type === 'enum')
-        collectEnumRef(field, resolver, out);
 }
 function collectEnumRef(field, resolver, out) {
-    const ref = resolver?.(field.enum.jsName);
-    if (!ref)
-        throw new Error(`enum field ${field.name}: no import ref for ${field.enum.jsName} — pass an EnumResolver`);
-    out.set(`${ref.from}#${ref.name}`, ref);
+    collectFieldEnumImports(field, resolver, out);
 }
 /** Collect all imports needed to render a DTO: include() bases + enum references. */
 export function collectDtoImports(schema, resolver, out) {
@@ -216,13 +198,3 @@ function renderBase(base) {
     const args = base.args.map((a) => (typeof a === 'string' ? a : a.name));
     return `${base.name}(${args.join(', ')})`;
 }
-/** Render one third-party method message export (const only — pair with
- *  renderDtoTypeExport for the Static type). */
-export function renderThirdMethodExport(schema, resolver) {
-    return `export const ${schema.name} = ${renderFieldObject(schema.fields, 1, resolver)};`;
-}
-/** Collect all imports needed to render a third-party method message: enum references. */
-export function collectThirdMethodImports(schema, resolver, out) {
-    for (const f of Object.values(schema.fields))
-        collectFieldEnumImports(f, resolver, out);
-}

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-import type { Field, SchemaBase } from './dsl.js';
+import type { CollectionSchemaBase, Field, SchemaBase } from './dsl.js';
 import type { FrontAppSchema, ProjectApiSchema } from './project.js';
 /** A utility method with a full signature. */
 export interface UtilsMethodSchema extends SchemaBase {
@@ -13,7 +13,7 @@ export interface UtilsMethodSchema extends SchemaBase {
 /** Method input for defineUtils: type/schema/name are set by the builder. */
 export type UtilsMethodDef = Omit<UtilsMethodSchema, 'type' | 'schema' | 'name'>;
 /** A base utility module (e.g. DateTimeUtils). */
-export interface UtilsSchema extends SchemaBase {
+export interface UtilsSchema extends CollectionSchemaBase {
     type: 'utils';
     /** Backend binding — the api module this utils belongs to (shared instance
      *  from project.config.ts apis). With `app` it serves that frontend

package/docs/curd.md

@@ -10,10 +10,14 @@ CurdSchema 是**管理端专用**（`FrontAppSchema.type === 'admin'`）的 CRUD
 
 ```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-curd', {
+export const orderCurd = defineCurd('order', {   // name = table.name 的 kebab（即 admin 路由路径）
   description: '订单管理',
-  app: webAdmin,                    // 所属管理端（project.config.ts 的 FrontAppSchema 共享实例）
+  app: admin,                      // 所属管理端（project.config.ts 的 FrontAppSchema 共享实例）
   table: order,                     // 绑定实体表（共享实例）
   title: '订单管理',
   section: '订单管理',               // 必填：sidebar 分组名
@@ -25,14 +29,35 @@ export const orderCurd = defineCurd('order-curd', {
   },
   list: {
     columns: [order.columns.id, order.columns.order_no, merchant.columns.name],  // 可跨表
-    keyword: { columns: [order.columns.order_no] },  // 模糊搜索（本表字段）
+    filter: orderListFilter,       // 搜索表单 + keyword（FilterSchema 引用，可选）
     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 → 文案
   },
 });
 ```
 
+搜索条件**不内联在 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 列表查询共用）。
+
 ## 字段
 
 | 字段 | 类型 | 说明 |
@@ -40,7 +65,7 @@ export const orderCurd = defineCurd('order-curd', {
 | `app` | `FrontAppSchema` | 所属管理端（共享实例，`type` 必须为 `'admin'`） |
 | `table` | `TableSchema` | 绑定实体表（共享实例） |
 | `title` | `string` | 列表页中文标题 |
-| `section` | `string` | **必填**：sidebar 分组名（`pylonts gen curd` 据此生成路由注册的 `section` 字段） |
+| `section` | `string` | **必填**：sidebar 分组名 |
 | `actions?` | `ActionSchema[]` | 页面额外可执行动作（标准 CRUD 之外，如导出、审核） |
 | `actionPages?` | `{ add? / update? / detail? }` | 动作页：`{ mode: 'modal' \| 'route'; columns: Field[] }` |
 | `list` | `CurdListConfig` | 列表页配置（必填） |
@@ -56,31 +81,38 @@ export const orderCurd = defineCurd('order-curd', {
 
 | 字段 | 类型 | 说明 |
 |---|---|---|
-| `columns` | `Field[]` | 列表列，**必填非空**——前端要显示的字段必须全部显式列出；可含跨表字段（见下） |
-| `keyword?` | `{ columns: Field[] }` | 模糊搜索，columns 必须是**本表字段实例** |
+| `columns` | `Field[]` | 列表列，**必填非空**；可含跨表字段 |
+| `filter?` | `FilterSchema` | 页面过滤器引用：搜索表单（AND 条件）+ keyword（多列 OR 模糊）；缺省 = 无搜索表单 |
 | `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` → 中文文案 |
 
-## 跨表字段
+### FilterSchema（`defineFilter`）
 
-`columns` / `searchFields` 里的 `Field` 实例可指向**本表或其他表**的列——列表列与搜索条件因此可以显示关联表字段（如订单列表显示商户名称）：
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `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 搜索） |
 
-```ts
-list: {
-  columns: [order.columns.id, order.columns.order_no, merchant.columns.name],  // 跨表：字段指向 merchant.name
-}
-```
+## 跨表字段
+
+`list.columns` 与 filter `conditions` 里的 `Field` 实例可指向**本表或其他表**的列——列表列与搜索条件因此可以显示/过滤关联表字段（如订单列表显示商户名称、按商户名称过滤）。
 
 ## 默认与校验
 
-- `list.columns` / `actionPages.*.columns` **必填非空**（不允许省略、不允许空数组）——前端显示什么必须显式定义
+- `list.columns` / `actionPages.*.columns` **必填非空**（不允许省略、不允许空数组）
 - `list.orderBy` **必填**，`column` 与 `direction` 都必填（规格：默认主键 desc 由定义方显式写出）
 - 运行时校验（`defineCurd`，仿 `defineTable` 强校验风格）：
   - `app.type` 必须为 `'admin'`，否则抛错
+  - **`name` 必须是 `table.name` 的 kebab 形式**（name 即 admin 路由路径，不允许与所服务的表漂移）
+  - `section` 必填
   - 所有 `columns` 非空，否则抛错
-  - `list.keyword.columns` / `list.orderBy.column` 必须属于 `table`，否则抛错
-  - `list.columns` / `list.searchFields` 允许跨表，**不校验归属**
+  - `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 靠主键定位记录
@@ -92,6 +124,9 @@ DTO 由 curd 生成器从 `CurdSchema` 按标准命名推导，页面语义不
 | 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` | 主键 |
@@ -106,6 +141,6 @@ DTO 由 curd 生成器从 `CurdSchema` 按标准命名推导，页面语义不
 | `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`（列改字段实例引用） |
+| `keyword` / `orderBy` / `columnTitles` | `list.filter`（FilterSchema）/ `list.orderBy` / `list.columnTitles` |
 | `naming` | 去掉（DTO 命名是生成器约定，非页面语义） |
-| DTO 引用（`request` / `fields` / `DtoFields`） | 去掉（DTO 由生成器推导，页面只依赖 table） |
+| DTO 引用（`request` / `fields` / `DtoFields`） | 去掉（DTO 由生成器推导，页面只依赖 table） |