@pylonts/dsl 1.0.5 → 1.1.1

package/docs/driver.md

@@ -1,42 +1,42 @@
-# Driver 模式与产物生成
-
-DSL 定义元数据，driver 翻译成目标语言产物。产物与定义解耦，同一份定义可生成不同目标：
-
-| 定义 | Driver | 产物 | 消费方 |
-|---|---|---|---|
-| `TableSchema` | mysql-driver | `CREATE TABLE` | MySQL |
-| `EnumDef` | enum-driver | `export enum Xxx { … }` + `XXX_LABEL` | 业务代码 |
-| `DtoMessage` | typebox-driver | `Type.Object({…})` + `Static` 推导 | fastify v5 参数校验 |
-
-## 生成 SQL
-
-```ts
-import { buildCreateTableSql } from '@pylonts/dsl';
-
-buildCreateTableSql(order);   // "CREATE TABLE `order` (\n  ..."
-```
-
-默认不生成外键约束；需要时：
-
-```ts
-buildCreateTableSql(order, { generateForeignKeys: true });
-```
-
-## 生成枚举源码
-
-```ts
-import { renderEnum } from '@pylonts/dsl';
-
-renderEnum(AcquiringType);    // TS enum 源码
-```
-
-## 生成 TypeBox 源码
-
-```ts
-import { renderDtoMessage } from '@pylonts/dsl';
-
-renderDtoMessage(orderPageQuery, {
-  source: 'dto_schema/order/order.dsl.dto.ts',
-  resolver: (name) => ({ from: '@mall/enums/user', name }),   // 枚举引用解析
-});
-```
+# Driver 模式与产物生成
+
+DSL 定义元数据，driver 翻译成目标语言产物。产物与定义解耦，同一份定义可生成不同目标：
+
+| 定义 | Driver | 产物 | 消费方 |
+|---|---|---|---|
+| `TableSchema` | mysql-driver | `CREATE TABLE` | MySQL |
+| `EnumDef` | enum-driver | `export enum Xxx { … }` + `XXX_LABEL` | 业务代码 |
+| `DtoMessage` | typebox-driver | `Type.Object({…})` + `Static` 推导 | fastify v5 参数校验 |
+
+## 生成 SQL
+
+```ts
+import { buildCreateTableSql } from '@pylonts/dsl';
+
+buildCreateTableSql(order);   // "CREATE TABLE `order` (\n  ..."
+```
+
+默认不生成外键约束；需要时：
+
+```ts
+buildCreateTableSql(order, { generateForeignKeys: true });
+```
+
+## 生成枚举源码
+
+```ts
+import { renderEnum } from '@pylonts/dsl';
+
+renderEnum(AcquiringType);    // TS enum 源码
+```
+
+## 生成 TypeBox 源码
+
+```ts
+import { renderDtoMessage } from '@pylonts/dsl';
+
+renderDtoMessage(orderPageQuery, {
+  source: 'dto_schema/order/order.dto.ts',
+  resolver: (name) => ({ from: '@mall/enums/user', name }),   // 枚举引用解析
+});
+```

package/docs/dto.md

@@ -1,67 +1,67 @@
-# 定义 DTO（四种方向）
-
-DTO 描述接口出入参。方向决定可选性规则，由各方向工厂设置；**规则统一只在 `field.optional === undefined` 时生效**（作者已显式设置的跳过）：
-
-| 构建器 | 方向 | 可选性规则 |
-|---|---|---|
-| `buildInput` | input | 按 DB 列规则：可空 / 有默认 / 自增列 → 可选；NOT NULL 无默认 → 必填 |
-| `buildOutput` | output | 不设置（保持字段构建器/作者设置） |
-| `buildQuery` | query | 全部可选 |
-| `buildPk` | pk | 主键字段必填，其他字段可选 |
-
-## 从表提取字段
-
-```ts
-import { buildInput, buildQuery, dtoField, from } from '@pylonts/dsl';
-
-// 输入：新增订单
-buildInput('OrderAddRequest', { ...from(order, [order.fields.mer_id, order.fields.amount]) });
-
-// 输出：订单行
-buildOutput('OrderRow', from(order, [order.fields.id, order.fields.order_no]));
-
-// 查询：分页 + 过滤（query 字段恒为可选，.op() 声明比较操作符）
-buildQuery('OrderPageQuery', {
-  keyword: dtoField(stringField({ maxLength: 32 })).setOperator('like'),
-  ...from(order, [order.fields.mer_id]),
-});
-
-// 主键：按 id 取详情
-buildPk('OrderDetailRequest', from(order, [order.fields.id]));
-```
-
-`from(table, fields)` 提取表字段包装为 DTO 字段，字段实例与表共享，`name/schema` 保持指向表。**DTO 字段名转 camelCase**（`mer_id` → `merId`），与 DB 列名（snake_case）分离。`from()` 本身不做任何可选性推断——推断在各方向工厂。
-
-## 独立字段
-
-不来自表的内联字段直接用 `dtoField(...)` 包装任意字段构建器，可加 `pattern`、`optional`、`operator`、`default`。
-
-```ts
-dtoField(stringField({ maxLength: 32 })).setOperator('like')
-dtoField(intField()).setDefault(0)        // TypeBox default 注解
-```
-
-## 默认值
-
-- `setDefault(v)` 设 DTO 层默认值，渲染为 TypeBox `default:` 注解（`Type.String({ default: 'PENDING' })`、`Type.Enum(OrderStatus, { default: OrderStatus.PENDING })`）。
-- 枚举默认值必须是该枚举的成员值（value），渲染时解析为成员引用；非成员值直接报错。
-- 未显式设置时，fallback 到字段构建器的 `default`（DB 默认值，string），`from()` 提取的字段自动带出。
-
-## 继承基础 schema
-
-```ts
-buildQuery('OrderPageQuery', { ... })
-  .include({ from: '@pylonts/core', name: 'PageRequest' });   // 渲染 Type.Intersect([PageRequest, ...])
-```
-
-## 关键语义
-
-- **字段两层名**：`DtoField.name` 是接口字段名（DTO map key 反写）；`field.name` 是数据库列名（表反写）。
-- **可选性优先级**：DTO 层 `optional` 优先于字段层；query 方向所有字段强制可选。
-- **HTTP 传 string**：bigint / decimal / date / time 在接口层渲染为 `Type.String()`，保证精度与序列化语义。
-
-## 文件组织
-
-- `dto_schema/{module}/*.dto.ts`：DTO 源文件，一个文件可导出多个 DtoMessage；`module` = `project.config.ts` 的 `apps.name`，另加 `common/` 放跨 app 共享 DTO。
-- `gen-cli dto` 按 module 逐个扫描：`dto_schema/{module}/*.dto.ts` → 生成 `dto/{module}/{Name}.dto.ts`。
+# 定义 DTO（四种方向）
+
+DTO 描述接口出入参。方向决定可选性规则，由各方向工厂设置；**规则统一只在 `field.optional === undefined` 时生效**（作者已显式设置的跳过）：
+
+| 构建器 | 方向 | 可选性规则 |
+|---|---|---|
+| `buildInput` | input | 按 DB 列规则：主键 → 必填；可空 / 有默认 → 可选；其余 → 必填 |
+| `buildOutput` | output | 不设置（保持字段构建器/作者设置） |
+| `buildQuery` | query | 全部可选 |
+| `buildPk` | pk | 主键字段必填，其他字段可选 |
+
+## 从表提取字段
+
+```ts
+import { buildInput, buildQuery, dtoField, from } from '@pylonts/dsl';
+
+// 输入：新增订单
+buildInput('OrderAddRequest', { ...from(order, [order.columns.mer_id, order.columns.amount]) });
+
+// 输出：订单行
+buildOutput('OrderRow', from(order, [order.columns.id, order.columns.order_no]));
+
+// 查询：分页 + 过滤（query 字段恒为可选，.op() 声明比较操作符）
+buildQuery('OrderPageQuery', {
+  keyword: dtoField(stringField({ maxLength: 32 })).setOperator('like'),
+  ...from(order, [order.columns.mer_id]),
+});
+
+// 主键：按 id 取详情
+buildPk('OrderDetailRequest', from(order, [order.columns.id]));
+```
+
+`from(table, fields)` 提取表字段包装为 DTO 字段，字段实例与表共享，`name/schema` 保持指向表。**DTO 字段名转 camelCase**（`mer_id` → `merId`），与 DB 列名（snake_case）分离。`from()` 本身不做任何可选性推断——推断在各方向工厂。
+
+## 独立字段
+
+不来自表的内联字段直接用 `dtoField(...)` 包装任意字段构建器，可加 `pattern`、`optional`、`operator`、`default`。
+
+```ts
+dtoField(stringField({ maxLength: 32 })).setOperator('like')
+dtoField(intField()).setDefault(0)        // TypeBox default 注解
+```
+
+## 默认值
+
+- `setDefault(v)` 设 DTO 层默认值，渲染为 TypeBox `default:` 注解（`Type.String({ default: 'PENDING' })`、`Type.Enum(OrderStatus, { default: OrderStatus.PENDING })`）。
+- 枚举默认值必须是该枚举的成员值（value），渲染时解析为成员引用；非成员值直接报错。
+- 未显式设置时，fallback 到字段构建器的 `default`（DB 默认值，string），`from()` 提取的字段自动带出。
+
+## 继承基础 schema
+
+```ts
+buildQuery('OrderPageQuery', { ... })
+  .include({ from: '@pylonts/core', name: 'PageRequest' });   // 渲染 Type.Intersect([PageRequest, ...])
+```
+
+## 关键语义
+
+- **字段两层名**：`DtoField.name` 是接口字段名（DTO map key 反写）；`field.name` 是数据库列名（表反写）。
+- **可选性优先级**：DTO 层 `optional` 优先于字段层；query 方向所有字段强制可选。
+- **HTTP 传 string**：bigint / decimal / date / time 在接口层渲染为 `Type.String()`，保证精度与序列化语义。
+
+## 文件组织
+
+- `dto_schema/{module}/*.dto.ts`：DTO 源文件，一个文件可导出多个 DtoMessage；`module` = `project.config.ts` 的 `apps.name`，另加 `common/` 放跨 app 共享 DTO。
+- `gen-cli dto` 按 module 逐个扫描：`dto_schema/{module}/*.dto.ts` → 生成 `dto/{module}/{Name}.dto.ts`。
 - 枚举字段引用 `enums/` 下生成的枚举源文件，DTO 文件通过 `../../enums/{JsName}.enum` 导入。

package/docs/enum.md

@@ -1,24 +1,24 @@
-# 定义枚举（可跨表复用）
-
-枚举定义与字段分离：`defineEnum` 产生共享定义（纯值对象），`enumField` 引用它。同一枚举可被多张表 / 多个 DTO 复用，只生成一次。
-
-```ts
-import { defineEnum, enumField } from '@pylonts/dsl';
-
-// 共享定义（_common.ts 等公共文件）
-export const AcquiringType = defineEnum('AcquiringType', 'string', [
-  { symbol: 'WECHAT', value: 'wechat', label: '微信' },
-  { symbol: 'UNIONPAY', value: 'unionpay', label: '银联商务' },
-]);
-
-// 字段引用（每表独立实例）
-buildTable('merchant', { fields: { acquiring_type: enumField({ enum: AcquiringType }) }, ... });
-buildTable('order',    { fields: { acquiring_type: enumField({ enum: AcquiringType }) }, ... });
-```
-
-- 字段实例每表独立（列名、可选性随表），枚举定义全局共享。
-- 枚举由 enum-driver 生成独立文件；typebox-driver 只渲染 `Type.Enum(名称)` + import 引用，不内联。
-
-## 生成枚举源码
-
-见 [driver.md](./driver.md)。
+# 定义枚举（可跨表复用）
+
+枚举定义与字段分离：`defineEnum` 产生共享定义（纯值对象），`enumField` 引用它。同一枚举可被多张表 / 多个 DTO 复用，只生成一次。
+
+```ts
+import { defineEnum, enumField } from '@pylonts/dsl';
+
+// 共享定义（_common.ts 等公共文件）
+export const AcquiringType = defineEnum('AcquiringType', 'string', [
+  { symbol: 'WECHAT', value: 'wechat', label: '微信' },
+  { symbol: 'UNIONPAY', value: 'unionpay', label: '银联商务' },
+]);
+
+// 字段引用（每表独立实例）
+buildTable('merchant', { columns: { acquiring_type: enumField({ enum: AcquiringType }) }, ... });
+buildTable('order',    { columns: { acquiring_type: enumField({ enum: AcquiringType }) }, ... });
+```
+
+- 字段实例每表独立（列名、可选性随表），枚举定义全局共享。
+- 枚举由 enum-driver 生成独立文件；typebox-driver 只渲染 `Type.Enum(名称)` + import 引用，不内联。
+
+## 生成枚举源码
+
+见 [driver.md](./driver.md)。

package/docs/project.md

@@ -18,7 +18,7 @@ export const mall = defineProject('mall', {
 });
 ```
 
-- `FrontApp`：`name` / `description` / `type`（admin | wxmini）/ `dir`（相对仓库根目录的源码目录）。
-- `ProjectApi`：`name` / `description` / `dir` / `apps`（直接引用共享的 FrontApp 实例——一个 app 被多个 API 服务就定义一次、引用多次）/ `contextPath`（API 基础 URL 前缀，如 `/mall`，空串表示无前缀）。
+- `FrontAppSchema`：`name` / `description` / `type`（admin | wxmini）/ `dir`（相对仓库根目录的源码目录）。
+- `ProjectApiSchema`：`name` / `description` / `dir` / `apps`（直接引用共享的 FrontAppSchema 实例——一个 app 被多个 API 服务就定义一次、引用多次）/ `contextPath`（API 基础 URL 前缀，如 `/mall`，空串表示无前缀）。
 - **直接对象引用优先**：`api.apps` 与 `project.apps` 指向同一实例，不写字符串。
 - **contextPath 解析**：前端 app 的 API 前缀由服务它的 api 决定——`api.apps` 必须恰好包含该 app（零个或多个都报错），app 本身不声明 contextPath。

package/docs/table.md

@@ -16,7 +16,7 @@
 | `enumField` | enum | string / number | VARCHAR(20) / TINYINT | 引用共享枚举定义，见 [enum.md](./enum.md) |
 | `jsonField` | json | object | JSON | |
 
-通用扩展属性（构建器第二参数）：`label`（中文标签）、`description`、`optional`、`readOnly`、`default`。
+通用扩展属性（构建器参数）：`label`（中文标签）、`description`、`optional`、`readOnly`、`default`。
 
 ## 定义表
 
@@ -27,8 +27,8 @@ const id = bigintField({ readOnly: true, label: '主键' });
 
 export const order = defineTable('order', {
   description: '订单',
-  generator: 'auto_increment',
-  fields: {
+  autoIncrement: id,
+  columns: {
     id,
     order_no: stringField({ label: '订单号', maxLength: 32, optional: false }),
     amount: decimalField({ precision: 18, scale: 2, label: '金额' }),
@@ -37,15 +37,40 @@ export const order = defineTable('order', {
 });
 ```
 
-- 字段名从 map key 反写，`fields` 里的 key 就是列名。
+- 字段名从 map key 反写，`columns` 里的 key 就是列名。
 - 字段实例不可跨表复用（复用同一字段实例会抛错），枚举除外。
 
+## 主键生成策略
+
+`autoIncrement` 与 `generator` 互斥，二者选一：
+
+| 属性 | 含义 | 例子 |
+|---|---|---|
+| `autoIncrement` | 引用自增主键字段，数据库负责生成值（MySQL `AUTO_INCREMENT`）。设了该属性的字段在 DTO 中自动标记为 optional（写入时不需要传） | `autoIncrement: id` |
+| `generator` | 主键由业务侧生成（非数据库自增），告诉下游工具用哪个 ID 生成器 | `generator: 'snowflake'` |
+
+```ts
+// 数据库自增主键
+export const t1 = defineTable('t1', {
+  autoIncrement: id,
+  columns: { id: bigintField({ readOnly: true, label: '主键' }) },
+  primaryKey: id,
+});
+
+// 业务生成主键（snowflake）
+export const t2 = defineTable('t2', {
+  generator: 'snowflake',
+  columns: { id: bigintField({ readOnly: true, label: '主键' }) },
+  primaryKey: id,
+});
+```
+
 ## 索引
 
 ```ts
 indexes: [
-  { name: 'uk_uuid', fields: c_uuid, unique: true },
-  { fields: [c_enum, c_date] },   // 名字缺省时 = 字段名 join '_'
+  { name: 'uk_uuid', columns: c_uuid, unique: true },
+  { columns: [c_enum, c_date] },   // 名字缺省时 = 字段名 join '_'
 ],
 ```
 
@@ -55,44 +80,54 @@ indexes: [
 
 ```ts
 // schema/_dictionary.ts
-import { definePhrase } from '@pylonts/dsl';
+import { defineEntityPhrase } from '@pylonts/dsl';
 
-const bd = definePhrase({ name: 'bd', label: 'BD推广员', description: '线下拓展商户的推广人员' });
+export const bd = defineEntityPhrase({ name: 'bd', label: 'BD推广员', description: '线下拓展商户的推广人员' });
 ```
 
 ```ts
-import { bd } from './_dictionary';
+// schema/bd.table.ts
+import { bigintField, defineTable } from '@pylonts/dsl';
+import { bd as bdPhrase } from './_dictionary';
 
 const bdId = bigintField({ readOnly: true, label: 'BD ID' });
 
 export const bd = defineTable('bd', {
   description: 'BD',
-  phrase: bd,            // 链接词典条目：本表归属的实体
-  fields: { id: bdId },
+  phrase: bdPhrase,       // 链接词典条目：本表归属的实体
+  columns: { id: bdId },
   primaryKey: bdId,
 });
+```
+
+```ts
+// schema/audit.table.ts
+import { bigintField, defineTable } from '@pylonts/dsl';
+import { bd } from './bd.table';
 
 const auditBdId = bigintField({ label: 'BD' });
 
 export const audit = defineTable('audit', {
   description: '审核',
-  fields: {
+  columns: {
     bd_id: auditBdId,    // 列名必须 = 短语 + '_' + 被引用字段名
   },
   foreignKeys: {
-    bd_bd_id: { fields: auditBdId, references: bdId },
+    fk_audit_bd: { columns: auditBdId, references: bd.columns.id },
   },
 });
 ```
 
 **规则（defineTable 时强制检查）**：外键字段名必须等于 `被引用表.phrase.name + "_" + 被引用字段名`。即引用 `bd.id` 的字段必须叫 `bd_id`——`bd` 来自词典（权威短语），`id` 是 `bd` 表主键。
 
-**短语口径**：`definePhrase` 解释的**就是短语本身**——`name` 即短语词干（如 `mer`），不是实体全名。引用 `merchant` 实体的字段用短语 `mer`（`mer_id`），**不用长语**（`merchant_id`）。短语要短（mer / bd / amt 三字母左右），语义由 `label`/`description` 解释。
+**短语口径**：`defineEntityPhrase`（实体短语）解释的**就是短语本身**——`name` 即短语词干（如 `mer`），不是实体全名。引用 `merchant` 实体的字段用短语 `mer`（`mer_id`），**不用长语**（`merchant_id`）。短语要短（mer / bd / amt 三字母左右），语义由 `label`/`description` 解释。`TableSchema.phrase` 只接受实体短语（`defineEntityPhrase` 产物）；业务短语（`defineBusinessPhrase`）用于字段命名后缀校验，见 [field-check.md](../../lint/docs/field-check.md)。
 
 - 被引用表未定义 `phrase` → 抛错（检查链要求每个被引用表都有短语）。
 - 命名不匹配 → 抛错并提示期望名，例如：
   `foreign key bad: field must be named bd_id (phrase bd + id), got merchant_id`
-- 关联表等涉及多个实体的场景不需要 `phrase`，也不建外键。
+- 关联表不需要 `phrase`。
+
+> **外键是逻辑作用**：`foreignKeys` 用于定义期命名强校验与关系表达，**DDL 默认不渲染物理 FOREIGN KEY 约束**（`gen-cli sql init` 不传 `generateForeignKeys`）。数据完整性由 Service/DAO 层保证；如需物理约束，调用 `buildCreateTableSql(schema, { generateForeignKeys: true })`。
 
 ## 生成 SQL
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@pylonts/dsl",
-  "version": "1.0.5",
+  "version": "1.1.1",
   "description": "Schema definition DSL with drivers: MySQL DDL, TS enum, TypeBox schema codegen.",
-  "type": "commonjs",
+  "type": "module",
   "main": "src/index.ts",
   "types": "./dist/index.d.ts",
   "files": [
@@ -13,6 +13,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "prepublishOnly": "npm run build",
+    "test": "vitest run",
     "typecheck": "npx tsc --noEmit"
   },
   "keywords": [
@@ -24,6 +25,7 @@
   "author": "",
   "license": "MIT",
   "devDependencies": {
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
   }
-}
+}

package/src/asset.ts

@@ -0,0 +1,63 @@
+/**
+ * defineAsset — registry for reusable project assets (utils, components, flows, pages, hooks).
+ *
+ * Each asset declares its name, category, import path, tags, and optional usage example.
+ * CLI scans all asset declarations, supports query (by tag/category) and generate (import links).
+ *
+ *   // assets/utils.assets.ts
+ *   import { defineAsset } from '@pylonts/dsl';
+ *   export const formatAmt = defineAsset({
+ *     name: 'formatAmt',
+ *     category: 'util',
+ *     tags: ['amount', 'format'],
+ *     import: { name: 'formatAmt', from: '@/utils/amount' },
+ *     example: 'formatAmt(12345) => "12,345.00"',
+ *   });
+ *
+ *   // CLI:
+ *   // gen-cli asset list --tag form       → all form-related assets
+ *   // gen-cli asset import formatAmt      → import { formatAmt } from '@/utils/amount';
+ */
+
+export type AssetCategory = 'util' | 'component' | 'flow' | 'page' | 'hook';
+
+export interface AssetImport {
+  /** Named export, e.g. 'formatAmt' */
+  name: string;
+  /** Module path, e.g. '@/utils/amount' */
+  from: string;
+}
+
+export interface AssetConfig {
+  name: string;
+  category: AssetCategory;
+  tags: string[];
+  import: AssetImport;
+  description?: string;
+  /** One-liner usage example */
+  example?: string;
+  /** Link to detailed docs */
+  see?: string;
+}
+
+export interface AssetDef {
+  name: string;
+  category: AssetCategory;
+  tags: string[];
+  import: AssetImport;
+  description?: string;
+  example?: string;
+  see?: string;
+}
+
+export function defineAsset(config: AssetConfig): AssetDef {
+  return {
+    name: config.name,
+    category: config.category,
+    tags: config.tags,
+    import: config.import,
+    description: config.description,
+    example: config.example,
+    see: config.see,
+  };
+}

package/src/bases.ts

@@ -1,4 +1,4 @@
-import type { DtoMessage, ImportRef } from './dto';
+import type { DtoMessage, ImportBase, ImportRef } from './dto.js';
 
 // Named base-schema references for common protocol DTOs.
 //
@@ -10,7 +10,7 @@ import type { DtoMessage, ImportRef } from './dto';
 // already-resolved reference — no static analysis or name lookup needed.
 
 /** Paginated query request base — renders `import { PageRequest } from '@pylonts/core'` + Intersect */
-export const PageRequest: ImportRef = { from: '@pylonts/core', name: 'PageRequest' };
+export const PageRequest: ImportBase = { from: '@pylonts/core', name: 'PageRequest' };
 
 /** Paginated list response base — renders `import { PageResult } from '@pylonts/core'` + `PageResult(<row>)` */
 export const PageResult = (row: DtoMessage): ImportRef => ({
@@ -18,3 +18,13 @@ export const PageResult = (row: DtoMessage): ImportRef => ({
   name: 'PageResult',
   args: [row],
 });
+
+/** Paged rows type base without generic args — renders `import { PagedRows } from '@pylonts/core'` */
+export const PagedRows: ImportBase = { from: '@pylonts/core', name: 'PagedRows' };
+
+/** Paged rows type base — renders `import { PagedRows } from '@pylonts/core'` + `PagedRows(<row>)` */
+export const PageRows = (row: DtoMessage): ImportRef => ({
+  from: '@pylonts/core',
+  name: 'PagedRows',
+  args: [row],
+});

package/src/curd.ts

@@ -0,0 +1,92 @@
+import { SchemaBase, Field, Operator } from './dsl.js';
+import { TableSchema } from './db.js';
+import { FrontAppSchema } from './project.js';
+import { ActionSchema } from './page.js';
+
+// Admin-only CRUD page standard: binds one entity table to a frontend admin
+// app, describing everything needed to generate the list page plus optional
+// add/update/detail pages. Field-level columns are plain Field instances
+// (table fields, cross-table refs allowed) — DTOs are derived by the generator,
+// the schema itself never references DtoMessage.
+
+/** Mode of an action page: modal dialog or standalone route. */
+export type ActionPageMode = 'modal' | 'route';
+
+/** One CRUD action page (add / update / detail). */
+export interface ActionPage {
+  mode: ActionPageMode;
+  /** Fields rendered on this page. Required, non-empty — every field the
+   *  frontend shows must be listed explicitly. */
+  columns: Field[];
+}
+
+/** List page configuration. */
+export interface CurdListConfig {
+  /** List columns; required, non-empty. Every field the list shows must be
+   *  listed explicitly. May include cross-table fields via foreign refs. */
+  columns: Field[];
+  /** Fuzzy keyword search on this table's columns. */
+  keyword?: { columns: Field[] };
+  /** Default sort. Required — column and direction are both mandatory. */
+  orderBy: { column: Field; direction: 'asc' | 'desc' };
+  /** Search condition fields; op defaults to 'eq'. */
+  searchFields?: { field: Field; op?: Operator }[];
+  /** Column header text overrides: Field.name → header text. */
+  columnTitles?: Record<string, string>;
+}
+
+/** Admin-only CRUD page standard: binds one entity table to a frontend
+ *  admin app. Drives generation of the list page plus optional
+ *  add/update/detail pages. */
+export interface CurdSchema extends SchemaBase {
+  /** The admin frontend app this CRUD belongs to (shared instance, type must be 'admin'). */
+  app: FrontAppSchema;
+  /** The bound entity table (shared instance). */
+  table: TableSchema;
+  /** List page Chinese title. */
+  title: string;
+  /** Sidebar menu section (group) this CRUD page belongs to. */
+  section: string;
+  /** Extra user actions on this page (beyond the standard CRUD). */
+  actions?: ActionSchema[];
+  /** Add/update/detail action pages. */
+  actionPages?: {
+    add?: ActionPage;
+    update?: ActionPage;
+    detail?: ActionPage;
+  };
+  list: CurdListConfig;
+}
+
+function assertColumns(curd: CurdSchema, pageName: string, columns: Field[]): void {
+  if (columns.length === 0) {
+    throw new Error(`curd ${curd.name}: ${pageName}.columns must be non-empty`);
+  }
+}
+
+function assertFieldsOwnTable(curd: CurdSchema, label: string, fields: Field[]): void {
+  for (const f of fields) {
+    if (f.schema !== curd.table) {
+      throw new Error(`curd ${curd.name}: ${label} field ${f.name} does not belong to table ${curd.table.name}`);
+    }
+  }
+}
+
+/** Defines an admin CRUD page standard. Runtime-validates admin app binding,
+ *  non-empty columns and table field ownership (same style as defineTable). */
+export function defineCurd(name: string, schema: Omit<CurdSchema, 'name'>): CurdSchema {
+  const curd: CurdSchema = { name, ...schema };
+  if (curd.app.type !== 'admin') {
+    throw new Error(`curd ${name}: app ${curd.app.name} must be type 'admin' (got '${curd.app.type}')`);
+  }
+  if (!curd.section) {
+    throw new Error(`curd ${name}: section is required (sidebar menu group, e.g. '商户管理')`);
+  }
+  assertColumns(curd, 'list', curd.list.columns);
+  for (const [pageName, page] of Object.entries(curd.actionPages ?? {})) {
+    if (page) assertColumns(curd, `actionPages.${pageName}`, page.columns);
+  }
+  assertFieldsOwnTable(curd, 'keyword', curd.list.keyword?.columns ?? []);
+  assertFieldsOwnTable(curd, 'orderBy', [curd.list.orderBy.column]);
+  return curd;
+}

package/src/db-config.ts

@@ -0,0 +1,8 @@
+/** MySQL connection settings, loaded from mysql.config.ts at the project root. */
+export interface DbConfig {
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+  database: string;
+}