@pylonts/dsl 1.1.15 → 1.1.17

package/dist/typebox-driver.js

@@ -8,11 +8,35 @@ function renderDefault(v) {
         return renderString(v);
     return JSON.stringify(v);
 }
-function renderBasic(field, pattern, defaultValue, resolver, indent = 0) {
+/** BaseField-level description: description takes priority over label. */
+function fieldDescription(field) {
+    return field.description ?? field.label;
+}
+/** DtoField-level description: own description > referenced field description/label. */
+function dtoFieldDescription(f) {
+    return f.description ?? fieldDescription(f.field);
+}
+/** Resolve a ref chain to its terminal field (the one without .ref).
+ *  Cycles are a DSL definition error — fail loudly at render time. */
+function resolveRefChain(f) {
+    const seen = new Set();
+    let cur = f;
+    while (cur.ref !== undefined) {
+        if (seen.has(cur.ref)) {
+            throw new Error(`dto field ${cur.name}: circular ref chain (field references itself)`);
+        }
+        seen.add(cur.ref);
+        cur = cur.ref;
+    }
+    return cur;
+}
+function renderBasic(field, pattern, defaultValue, resolver, indent = 0, description) {
     if (pattern !== undefined && field.type !== 'string') {
         throw new Error(`pattern is only supported on string fields, got ${field.type} (${field.name})`);
     }
     const def = defaultValue !== undefined ? `default: ${renderDefault(defaultValue)}` : undefined;
+    const desc = description !== undefined ? `description: ${renderString(description)}` : undefined;
+    const withOpts = (base, opts) => opts.length > 0 ? `${base}({ ${opts.join(', ')} })` : `${base}()`;
     switch (field.type) {
         case 'string': {
             const opts = [];
@@ -24,10 +48,18 @@ function renderBasic(field, pattern, defaultValue, resolver, indent = 0) {
                 opts.push(`pattern: ${renderString(pattern)}`);
             if (def !== undefined)
                 opts.push(def);
-            return opts.length > 0 ? `Type.String({ ${opts.join(', ')} })` : 'Type.String()';
+            if (desc !== undefined)
+                opts.push(desc);
+            return withOpts('Type.String', opts);
+        }
+        case 'text': {
+            const opts = [];
+            if (def !== undefined)
+                opts.push(def);
+            if (desc !== undefined)
+                opts.push(desc);
+            return withOpts('Type.String', opts);
         }
-        case 'text':
-            return def !== undefined ? `Type.String({ ${def} })` : 'Type.String()';
         case 'integer': {
             const opts = [];
             if (field.min !== undefined)
@@ -36,21 +68,41 @@ function renderBasic(field, pattern, defaultValue, resolver, indent = 0) {
                 opts.push(`maximum: ${field.max}`);
             if (def !== undefined)
                 opts.push(def);
-            return opts.length > 0 ? `Type.Integer({ ${opts.join(', ')} })` : 'Type.Integer()';
+            if (desc !== undefined)
+                opts.push(desc);
+            return withOpts('Type.Integer', opts);
         }
         case 'bigint':
         case 'decimal':
         case 'rate':
         case 'time':
         case 'date':
-        case 'datetime':
+        case 'datetime': {
             // Transmitted as string over HTTP: bigint/decimal/rate keep full
             // precision, date/time serialize to string.
-            return def !== undefined ? `Type.String({ ${def} })` : 'Type.String()';
-        case 'boolean':
-            return def !== undefined ? `Type.Boolean({ ${def} })` : 'Type.Boolean()';
-        case 'json':
-            return def !== undefined ? `Type.Unknown({ ${def} })` : 'Type.Unknown()';
+            const opts = [];
+            if (def !== undefined)
+                opts.push(def);
+            if (desc !== undefined)
+                opts.push(desc);
+            return withOpts('Type.String', opts);
+        }
+        case 'boolean': {
+            const opts = [];
+            if (def !== undefined)
+                opts.push(def);
+            if (desc !== undefined)
+                opts.push(desc);
+            return withOpts('Type.Boolean', opts);
+        }
+        case 'json': {
+            const opts = [];
+            if (def !== undefined)
+                opts.push(def);
+            if (desc !== undefined)
+                opts.push(desc);
+            return withOpts('Type.Unknown', opts);
+        }
         case 'enum': {
             const ref = resolver?.(field.enum.jsName);
             if (!ref)
@@ -60,18 +112,29 @@ function renderBasic(field, pattern, defaultValue, resolver, indent = 0) {
                 if (!member) {
                     throw new Error(`enum field ${field.name}: default ${renderDefault(defaultValue)} is not a member of ${field.enum.jsName}`);
                 }
-                return `Type.Enum(${ref.name}, { default: ${ref.name}.${member.symbol} })`;
+                const opts = [];
+                if (desc !== undefined)
+                    opts.push(desc);
+                return `Type.Enum(${ref.name}, { default: ${ref.name}.${member.symbol}${opts.length > 0 ? `, ${opts.join(', ')}` : ''} })`;
             }
+            if (desc !== undefined)
+                return `Type.Enum(${ref.name}, { ${desc} })`;
             return `Type.Enum(${ref.name})`;
         }
-        case 'aggregate':
+        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()';
+            const opts = [];
+            if (desc !== undefined)
+                opts.push(desc);
+            return field.jsType === 'number' ? withOpts('Type.Number', opts) : withOpts('Type.String', opts);
+        }
         case 'array':
-            return `Type.Array(${renderFieldValue(field.items, indent, resolver)})`;
+            return desc !== undefined
+                ? `Type.Array(${renderFieldValue(field.items, indent, resolver)}, { ${desc} })`
+                : `Type.Array(${renderFieldValue(field.items, indent, resolver)})`;
         case 'object':
-            return renderFieldObject(field.properties, indent + 1, resolver);
+            return renderFieldObject(field.properties, indent + 1, resolver, description);
         default:
             // Field union is exhaustive; this branch is unreachable at runtime.
             throw new Error(`unsupported field type: ${String(field.type)}`);
@@ -79,46 +142,92 @@ function renderBasic(field, pattern, defaultValue, resolver, indent = 0) {
 }
 /** Render a plain Field value (wire-format nested fields), wrapping optional. */
 function renderFieldValue(field, indent, resolver) {
-    const base = renderBasic(field, undefined, undefined, resolver, indent);
+    const base = renderBasic(field, undefined, undefined, resolver, indent, fieldDescription(field));
     return field.optional ? `Type.Optional(${base})` : base;
 }
 /** Render a plain Field object (wire-format nested object). */
-function renderFieldObject(properties, indent, resolver) {
+function renderFieldObject(properties, indent, resolver, description) {
     const pad = '  '.repeat(indent);
     const entries = Object.entries(properties).map(([name, f]) => `${pad}${name}: ${renderFieldValue(f, indent, resolver)}`);
-    return `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
+    const obj = `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
+    return description !== undefined
+        ? `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}}, { description: ${renderString(description)} })`
+        : obj;
 }
-function renderObject(fields, indent, resolver) {
+function renderObject(fields, indent, resolver, description) {
     const pad = '  '.repeat(indent);
     const entries = Object.entries(fields).map(([name, f]) => {
         const rendered = isDtoField(f) ? renderField(f, indent, resolver) : renderFieldValue(f, indent, resolver);
         return `${pad}${name}: ${rendered}`;
     });
-    return `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
+    const obj = `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
+    return description !== undefined
+        ? `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}}, { description: ${renderString(description)} })`
+        : obj;
 }
 function renderField(f, indent, resolver) {
+    // Ref branch renders its own optional (referencing overrides + chain fallback).
+    if (f.ref !== undefined)
+        return renderValue(f, indent, resolver);
     const base = renderValue(f, indent, resolver);
     return f.isOptional() ? `Type.Optional(${base})` : base;
 }
+/** Render a ref-carrying field's bare type (no optional wrapper): resolve the
+ *  chain, inherit the terminal field's type/constraints, keep the referencing
+ *  field's own overrides (pattern / default / description). */
+function renderRefBase(f, indent, resolver) {
+    const target = resolveRefChain(f);
+    const targetField = target.field;
+    const pattern = f.pattern ?? target.pattern;
+    const defaultValue = f.default ?? target.default;
+    const desc = f.description ?? dtoFieldDescription(target);
+    return renderBasic(targetField, pattern, defaultValue, resolver, indent, desc);
+}
+/** Render a ref-carrying field with its optional wrapper: referencing
+ *  override first, then the chain's DtoField-level optional, then the bare
+ *  column optionality. */
+function renderRefField(f, indent, resolver) {
+    const target = resolveRefChain(f);
+    const optional = f.optional ?? target.optional ?? target.field.optional ?? false;
+    const base = renderRefBase(f, indent, resolver);
+    return optional ? `Type.Optional(${base})` : base;
+}
 function renderValue(f, indent, resolver) {
+    if (f.ref !== undefined)
+        return renderRefField(f, indent, resolver);
     if (f.field.type === 'array') {
         const items = f.field.items;
+        const desc = dtoFieldDescription(f);
         // Referenced DTO element — render by name (same-file export), not expanded.
-        if (isDtoMessage(items))
-            return `Type.Array(${items.name})`;
-        if (isDtoField(items))
-            return `Type.Array(${renderField(items, indent + 1, resolver)})`;
-        return `Type.Array(${renderFieldValue(items, indent, resolver)})`;
+        if (isDtoMessage(items)) {
+            return desc !== undefined
+                ? `Type.Array(${items.name}, { description: ${renderString(desc)} })`
+                : `Type.Array(${items.name})`;
+        }
+        if (isDtoField(items)) {
+            const rendered = `Type.Array(${renderField(items, indent + 1, resolver)})`;
+            return desc !== undefined
+                ? `Type.Array(${renderField(items, indent + 1, resolver)}, { description: ${renderString(desc)} })`
+                : rendered;
+        }
+        const rendered = `Type.Array(${renderFieldValue(items, indent, resolver)})`;
+        return desc !== undefined
+            ? `Type.Array(${renderFieldValue(items, indent, resolver)}, { description: ${renderString(desc)} })`
+            : rendered;
     }
     if (f.field.type === 'object') {
-        return renderObject(f.field.properties, indent + 1, resolver);
+        return renderObject(f.field.properties, indent + 1, resolver, dtoFieldDescription(f));
     }
     // DtoField only wraps a database Field; array/object defs live in the subclasses.
     // Only DTO-level defaults (setDefault) are emitted as TypeBox default
     // annotations; DB field defaults are not carried into the API contract.
-    return renderBasic(f.field, f.pattern, f.default, resolver, indent);
+    return renderBasic(f.field, f.pattern, f.default, resolver, indent, dtoFieldDescription(f));
 }
 function collectEnumImports(f, resolver, out) {
+    if (f.ref !== undefined) {
+        collectEnumImports(resolveRefChain(f), resolver, out);
+        return;
+    }
     if (f.field.type === 'array') {
         const items = f.field.items;
         if (isDtoMessage(items))
@@ -161,19 +270,91 @@ export function collectDtoImports(schema, resolver, out) {
     for (const f of Object.values(schema.fields))
         collectEnumImports(f, resolver, out);
 }
+/** Render the server-injection base: token-injected fields as Optional
+ *  properties of a TypeBox object, plus a non-enumerable __inject adapter
+ *  (same mechanism as hand-written bases, see pylon __inject docs) that fills
+ *  each field from the token at runtime. */
+function renderInjectBase(fields, resolver) {
+    const entries = Object.entries(fields).map(([name, f]) => {
+        const base = f.ref !== undefined ? renderRefBase(f, 1, resolver) : renderValue(f, 1, resolver);
+        return `  ${name}: Type.Optional(${base})`;
+    });
+    const inner = `Type.Object({\n${entries.join(',\n')}\n})`;
+    const assigns = Object.keys(fields)
+        .map((k) => `body.${k} = token.${k};`)
+        .join(' ');
+    return [
+        `Object.defineProperty(`,
+        `  ${inner},`,
+        `  '__inject',`,
+        `  { value: (body: Record<string, unknown>, token: Record<string, unknown>): void => { ${assigns} }, enumerable: false },`,
+        `)`,
+    ].join('\n');
+}
 /** Render one DTO export (const + type) — no file header, for file-level generation. */
 export function renderDtoExport(schema, resolver) {
-    const object = renderObject(schema.fields, 1, resolver);
-    const bases = schema.bases ?? [];
-    const body = bases.length > 0
-        ? `Type.Intersect([${bases.map(renderBase).join(', ')}, ${object}])`
-        : object;
+    const injectFields = {};
+    const normalFields = {};
+    for (const [key, f] of Object.entries(schema.fields)) {
+        if (f.injectFrom !== undefined)
+            injectFields[key] = f;
+        else
+            normalFields[key] = f;
+    }
+    const parts = [];
+    if (Object.keys(injectFields).length > 0)
+        parts.push(renderInjectBase(injectFields, resolver));
+    parts.push(renderObject(normalFields, 1, resolver, schema.description));
+    for (const base of schema.bases ?? [])
+        parts.push(renderBase(base));
+    const body = parts.length > 1 ? `Type.Intersect([${parts.join(', ')}])` : parts[0];
     return `export const ${schema.name} = ${body};`;
 }
 /** Render the Static type export for a DTO. */
 export function renderDtoTypeExport(name) {
     return `export type ${name} = Static<typeof ${name}>;`;
 }
+/** Render one token export: a flat TypeBox object. Security fields keep
+ *  their declared optionality (secret required, cipher optional); identity
+ *  fields are Optional except the primary-key anchor — they only exist after
+ *  login (two-state object, flat runtime shape), while the PK is guaranteed
+ *  to be projected (token validation enforces it) and serves as the identity
+ *  anchor (e.g. the tenant key for tenant-scoped controllers). */
+export function renderTokenExport(token, resolver) {
+    const constName = `${token.name}Token`;
+    const entries = [
+        ...Object.entries(token.security).map(([name, f]) => `  ${name}: ${renderField(f, 1, resolver)}`),
+        ...Object.entries(token.identity).map(([name, f]) => isPrimaryKeyProjection(f) ? `  ${name}: ${renderValue(f, 1, resolver)}` : `  ${name}: Type.Optional(${renderValue(f, 1, resolver)})`),
+    ];
+    const desc = token.description !== undefined ? `, { description: ${renderString(token.description)} }` : '';
+    return `export const ${constName} = Type.Object({\n${entries.join(',\n')}\n}${desc});`;
+}
+/** True when the DTO field projects a primary-key column of its source table. */
+function isPrimaryKeyProjection(f) {
+    const tbl = f.field.schema;
+    if (tbl?.type !== 'table')
+        return false;
+    // A table-backed field is always a plain Field (only Field carries a table
+    // schema); array/object DTO fields reference messages, not tables.
+    const field = f.field;
+    const table = tbl;
+    const pk = table.primaryKey;
+    if (!pk)
+        return false;
+    const pks = Array.isArray(pk) ? pk : [pk];
+    return pks.includes(field);
+}
+/** Render the Static type export for a token. */
+export function renderTokenTypeExport(name) {
+    return `export type ${name}Token = Static<typeof ${name}Token>;`;
+}
+/** Collect all imports needed to render a token: enum references across
+ *  security + identity fields. */
+export function collectTokenImports(token, resolver, out) {
+    for (const f of [...Object.values(token.security), ...Object.values(token.identity)]) {
+        collectEnumImports(f, resolver, out);
+    }
+}
 export function renderDtoMessage(schema, options = {}) {
     const { resolver, source } = options;
     const imports = new Map();

package/docs/curd.md

@@ -1,146 +1,150 @@
-# 管理端 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） |
+# 管理端 CRUD 页面标准（CurdSchema）
+
+CurdSchema 是**管理端专用**（`FrontAppSchema.type === 'admin'`）的 CRUD 页面标准：绑定一张实体表 + 一个管理端 app，描述列表页与新增/编辑/详情动作页生成所需的全部页面语义。一条 CurdSchema = 列表页（+ 动作页）的生成规格。
+
+页面定义文件按**管理端 app + 实体表**组织：`{project}/curd_schema/{app}/{table}.curd.ts`（一文件一 curd；同一张表可在不同 admin app 下分别 CRUD——curd 的身份是 **(app, table)**，生成物落在 `dto_schema/{app}/` 也按 app 隔离，不会互相撞名）。
+
+**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` 允许跨表，**不校验归属**
+- 存储校验（`loadCurds`，仿 `loadDaos`/`loadEntities` 机器校验风格）：
+  - 唯一合法目录是 `curd_schema/{app.name}/`（一级，app 名）；`curd.app` 必须是 project.config.ts 共享实例（`type === 'admin'`），且与所在目录一致
+  - **文件名 = `{table}.curd.ts`（表名 verbatim**，与 `{table}.entity.ts` / `{table}.dao.ts` 同规）——(app, table) 两维决定 curd 身份，同一张表可在不同 admin app 下合法共存
+  - 一文件一 curd（多导出/零导出报错）
+- 运行时校验（`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） |