@pylonts/dsl 1.0.6 → 1.1.1

package/dist/page-flow.js

@@ -1,12 +1,8 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.pageEdge = pageEdge;
-exports.definePageFlow = definePageFlow;
-function pageEdge(start, end, when, description) {
+export function pageEdge(start, end, when, description) {
     // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
     return { name: `${start.name}->${end.name}`, start, end, when, description };
 }
-function definePageFlow(name, schema) {
+export function definePageFlow(name, schema) {
     const seen = new Set();
     const pages = [];
     for (const e of schema.edges) {

package/dist/page.d.ts

@@ -1,10 +1,10 @@
-import { SchemaBase } from './dsl';
-import { FrontApp } from './project';
+import { SchemaBase } from './dsl.js';
+import { FrontAppSchema } from './project.js';
 /** Standalone page definition. A page is a shared value object: it lists
  *  the actions a user can perform, and belongs to exactly one frontend app. */
 export interface PageSchema extends SchemaBase {
     /** The frontend app this page belongs to (shared instance from project.config). */
-    app: FrontApp;
+    app: FrontAppSchema;
     /** Actions a user can perform on this page (e.g. submit, approve, reject). */
     actions: ActionSchema[];
 }
@@ -15,12 +15,12 @@ export declare function defineAction(name: string, description?: string): Action
 export declare function definePage(schema: {
     name: string;
     description?: string;
-    app: FrontApp;
+    app: FrontAppSchema;
     actions: ActionSchema[];
 }): PageSchema;
 /** A page node in a page-driven flow: every node is a page, and a page belongs to an app. */
 export interface Page extends SchemaBase {
     /** The frontend app this page belongs to (shared instance from project.config). */
-    app: FrontApp;
+    app: FrontAppSchema;
 }
-export declare function page(app: FrontApp, name: string, description?: string): Page;
+export declare function page(app: FrontAppSchema, name: string, description?: string): Page;

package/dist/page.js

@@ -1,14 +1,9 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineAction = defineAction;
-exports.definePage = definePage;
-exports.page = page;
-function defineAction(name, description) {
+export function defineAction(name, description) {
     return { name, description };
 }
-function definePage(schema) {
+export function definePage(schema) {
     return { ...schema };
 }
-function page(app, name, description) {
+export function page(app, name, description) {
     return { name, app, description };
 }

package/dist/pattern.js

@@ -1,13 +1,9 @@
-"use strict";
 // Pattern core: minimal definitions to bootstrap the Flow × Pattern DSL.
 // A Pattern is a reusable solution ("how to guarantee success") declared as
 // pure data. Concrete usage fills its params and action injection points.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.definePattern = definePattern;
-exports.ref = ref;
-function definePattern(def) {
+export function definePattern(def) {
     return def;
 }
-function ref(name, args) {
+export function ref(name, args) {
     return { ref: name, args };
 }

package/dist/patterns/retry.d.ts

@@ -1,4 +1,4 @@
-import { PatternDef } from '../pattern';
+import { PatternDef } from '../pattern.js';
 export declare const retryPattern: PatternDef;
 export interface RetryAction {
     /** Function to call, e.g. 'queryOrderList' */

package/dist/patterns/retry.js

@@ -1,19 +1,15 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.retryPattern = void 0;
-exports.renderRetry = renderRetry;
 // Retry pattern: blind mechanical retry for read-only operations.
 // Valid because a read-only action is idempotent by nature: clicking a query
 // button any number of times never changes the result, so retrying the same
 // call is always safe. No idempotency key, no query-and-resume, no compensate.
-exports.retryPattern = {
+export const retryPattern = {
     name: 'retry',
     params: {
         max: { type: 'int', min: 1, default: 3 },
         backoffMs: { type: 'int', min: 0, default: 0 },
     },
 };
-function renderRetry(args) {
+export function renderRetry(args) {
     if (args.max !== undefined && args.max < 1)
         throw new Error('retry: max must be >= 1');
     if (!args.action.call)

package/dist/project.d.ts

@@ -1,41 +1,46 @@
-import { SchemaBase } from './dsl';
+import { SchemaBase } from './dsl.js';
 /** Frontend form factor. Closed enum, extend when new form factors appear. */
 export type FrontType = 'admin' | 'wxmini';
 /** A frontend application (e.g. admin console, wechat mini program). */
-export interface FrontApp extends SchemaBase {
+export interface FrontAppSchema extends SchemaBase {
     type: FrontType;
     /** Source directory relative to project root, e.g. 'web-admin/'. */
     dir: string;
 }
-/** A backend API service. apps references shared FrontApp instances. */
-export interface ProjectApi extends SchemaBase {
+/** A backend API service. apps references shared FrontAppSchema instances. */
+export interface ProjectApiSchema extends SchemaBase {
     /** Source directory relative to project root, e.g. 'api/'. */
     dir: string;
     /** Frontends this API serves. Direct instance references (see defineProject). */
-    apps: FrontApp[];
+    apps: FrontAppSchema[];
     /** API base URL prefix shared by all apps it serves, e.g. '/mall'. '' = no prefix. */
     contextPath?: string;
+    /** API service base URL for node clients, e.g. 'http://127.0.0.1:3000'. */
+    baseUrl?: string;
 }
 /** A third-party system (e.g. wechat pay, unionpay). Owns its own
  *  implementation dir and contract (controller_types), just like an API,
  *  but is not part of this repo's served surface. */
-export interface ThirdApi extends SchemaBase {
+export interface ThirdApiSchema extends SchemaBase {
     /** Source directory relative to project root, e.g. 'wechat/'. */
     dir: string;
 }
 export interface ProjectSchema extends SchemaBase {
-    apps: FrontApp[];
-    apis: ProjectApi[];
-    thirdApis: ThirdApi[];
+    apps: FrontAppSchema[];
+    apis: ProjectApiSchema[];
+    thirdApis: ThirdApiSchema[];
 }
 /**
- * Defines the project topology. FrontApp instances are shared value objects:
+ * 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).
  */
 export declare function defineProject(name: string, schema: {
     description?: string;
-    apps: FrontApp[];
-    apis: ProjectApi[];
-    thirdApis?: ThirdApi[];
+    apps: FrontAppSchema[];
+    apis: ProjectApiSchema[];
+    thirdApis?: ThirdApiSchema[];
 }): ProjectSchema;

package/dist/project.js

@@ -1,11 +1,46 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineProject = defineProject;
 /**
- * Defines the project topology. FrontApp instances are shared value objects:
+ * 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).
  */
-function defineProject(name, schema) {
-    return { name, ...schema, thirdApis: schema.thirdApis ?? [] };
+export function defineProject(name, schema) {
+    const project = { name, ...schema, thirdApis: schema.thirdApis ?? [] };
+    const appNames = new Set();
+    for (const app of project.apps) {
+        if (!app.name)
+            throw new Error(`project ${name}: app name is required`);
+        if (appNames.has(app.name))
+            throw new Error(`project ${name}: duplicate app name '${app.name}'`);
+        appNames.add(app.name);
+        if (app.type !== 'admin' && app.type !== 'wxmini') {
+            throw new Error(`project ${name}: app '${app.name}' must be type 'admin' or 'wxmini' (got '${app.type}')`);
+        }
+        if (!app.dir)
+            throw new Error(`project ${name}: app '${app.name}' dir is required`);
+    }
+    const apiNames = new Set();
+    for (const api of project.apis) {
+        if (!api.name)
+            throw new Error(`project ${name}: api name is required`);
+        if (apiNames.has(api.name))
+            throw new Error(`project ${name}: duplicate api name '${api.name}'`);
+        apiNames.add(api.name);
+        if (!api.dir)
+            throw new Error(`project ${name}: api '${api.name}' dir is required`);
+        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)`);
+            }
+        }
+    }
+    for (const third of project.thirdApis) {
+        if (!third.name)
+            throw new Error(`project ${name}: thirdApi name is required`);
+        if (!third.dir)
+            throw new Error(`project ${name}: thirdApi '${third.name}' dir is required`);
+    }
+    return project;
 }

package/dist/prototype.d.ts

@@ -1,4 +1,4 @@
-import { SchemaBase } from './dsl';
+import { SchemaBase } from './dsl.js';
 /** Display metadata for a prototype field. */
 export interface PrototypeFieldMeta {
     label: string;

package/dist/prototype.js

@@ -1,10 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.definePrototype = definePrototype;
 /**
  * Defines a page prototype. The field keys become the names referenced by
  * later DTO/table definitions; here they only carry label/description.
  */
-function definePrototype(name, schema) {
+export function definePrototype(name, schema) {
     return { name, ...schema };
 }

package/dist/typebox-driver.d.ts

@@ -1,7 +1,7 @@
-import { DtoMessage, ImportRef } from './dto';
-export type EnumResolver = (enumName: string) => ImportRef | undefined;
+import { DtoMessage, ImportBase } from './dto.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, ImportRef>): void;
+export declare function collectDtoImports(schema: DtoMessage, resolver: EnumResolver | undefined, out: Map<string, ImportBase>): void;
 /** Render one DTO export (const + type) — no file header, for file-level generation. */
 export declare function renderDtoExport(schema: DtoMessage, resolver: EnumResolver | undefined): string;
 /** Render the Static type export for a DTO. */

package/dist/typebox-driver.js

@@ -1,10 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.collectDtoImports = collectDtoImports;
-exports.renderDtoExport = renderDtoExport;
-exports.renderDtoTypeExport = renderDtoTypeExport;
-exports.renderDtoMessage = renderDtoMessage;
-const dto_1 = require("./dto");
 function renderString(s) {
     return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 }
@@ -83,31 +76,36 @@ function renderField(f, indent, resolver) {
     return f.isOptional() ? `Type.Optional(${base})` : base;
 }
 function renderValue(f, indent, resolver) {
-    if (f instanceof dto_1.DtoArrayField) {
-        const items = f.items();
+    if (f.field.type === 'array') {
+        const items = f.field.items;
         // Referenced DTO element — render by name (same-file export), not expanded.
-        if (items instanceof dto_1.DtoMessage)
+        if (isDtoMessage(items))
             return `Type.Array(${items.name})`;
         return `Type.Array(${renderField(items, indent + 1, resolver)})`;
     }
-    if (f instanceof dto_1.DtoObjectField) {
-        return renderObject(f.properties(), indent + 1, resolver);
+    if (f.field.type === 'object') {
+        return renderObject(f.field.properties, indent + 1, resolver);
     }
     // DtoField only wraps a database Field; array/object defs live in the subclasses.
-    // DTO-level default wins over the DB field default; the DB default (string)
-    // is used as a fallback so from() picks carry it into the API contract.
-    const defaultValue = f.default !== undefined ? f.default : f.field.default;
-    return renderBasic(f.field, f.pattern, defaultValue, resolver);
+    // 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);
+}
+/** 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';
 }
 function collectEnumImports(f, resolver, out) {
-    if (f instanceof dto_1.DtoArrayField) {
-        const items = f.items();
-        if (!(items instanceof dto_1.DtoMessage))
+    if (f.field.type === 'array') {
+        const items = f.field.items;
+        if (!isDtoMessage(items))
             collectEnumImports(items, resolver, out);
         return;
     }
-    if (f instanceof dto_1.DtoObjectField) {
-        for (const child of Object.values(f.properties()))
+    if (f.field.type === 'object') {
+        for (const child of Object.values(f.field.properties))
             collectEnumImports(child, resolver, out);
         return;
     }
@@ -119,14 +117,14 @@ function collectEnumImports(f, resolver, out) {
     }
 }
 /** Collect all imports needed to render a DTO: include() bases + enum references. */
-function collectDtoImports(schema, resolver, out) {
+export function collectDtoImports(schema, resolver, out) {
     for (const base of schema.bases ?? [])
         out.set(`${base.from}#${base.name}`, base);
     for (const f of Object.values(schema.fields))
         collectEnumImports(f, resolver, out);
 }
 /** Render one DTO export (const + type) — no file header, for file-level generation. */
-function renderDtoExport(schema, resolver) {
+export function renderDtoExport(schema, resolver) {
     const object = renderObject(schema.fields, 1, resolver);
     const bases = schema.bases ?? [];
     const body = bases.length > 0
@@ -135,10 +133,10 @@ function renderDtoExport(schema, resolver) {
     return `export const ${schema.name} = ${body};`;
 }
 /** Render the Static type export for a DTO. */
-function renderDtoTypeExport(name) {
+export function renderDtoTypeExport(name) {
     return `export type ${name} = Static<typeof ${name}>;`;
 }
-function renderDtoMessage(schema, options = {}) {
+export function renderDtoMessage(schema, options = {}) {
     const { resolver, source } = options;
     const imports = new Map();
     collectDtoImports(schema, resolver, imports);
@@ -146,7 +144,7 @@ function renderDtoMessage(schema, options = {}) {
         '// AUTO-GENERATED by typebox-driver — DO NOT EDIT',
         ...(source !== undefined ? [`// Source: ${source}`] : []),
         "import { Type, Static } from '@sinclair/typebox';",
-        ...[...imports.values()].map((r) => `import { ${r.name} } from '${r.from}';`),
+        ...[...imports.values()].map((r) => `import${r.type ? ' type' : ''} { ${r.name} } from '${r.from}';`),
     ];
     return [
         ...header,

package/dist/utils.d.ts

@@ -1,2 +1,4 @@
 /** snake_case → camelCase: mer_id → merId; names without underscores are unchanged */
 export declare function toCamelCase(name: string): string;
+/** snake_case → PascalCase: mer_id → MerId */
+export declare function toPascalCase(snake: string): string;

package/dist/utils.js

@@ -1,8 +1,9 @@
-"use strict";
 // ── naming conversions ──
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.toCamelCase = toCamelCase;
 /** snake_case → camelCase: mer_id → merId; names without underscores are unchanged */
-function toCamelCase(name) {
+export function toCamelCase(name) {
     return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
 }
+/** snake_case → PascalCase: mer_id → MerId */
+export function toPascalCase(snake) {
+    return snake.replace(/(^|_)([a-z])/g, (_m, _p, c) => c.toUpperCase());
+}

package/docs/curd.md

@@ -0,0 +1,111 @@
+# 管理端 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 分组名（`gen-cli 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） |

package/docs/dictionary.md

@@ -1,31 +1,42 @@
-# 短语词典 (Dictionary)
-
-词典是与团队达成共识的基础知识库：**某词代表什么**（语义/定义层面），不是物理形式。短语定了，字段命名、外键命名就都有依据——全项目只说同一种话。
-
-- 是基础知识库，很少变更。
-- **能引用就引用**：魔法字符串只在首次出现时使用，之后一律引用词典条目。
-
-## 规范位置：schema/_dictionary.ts
-
-**所有短语统一定义在 `schema/_dictionary.ts`**，一个文件一处定义；`*.table.ts` 从该文件 import 短语，禁止在表文件里内联定义短语。
-
-## 口径：definePhrase 解释短语，name 即短语
-
-`definePhrase` 返回的条目**就是短语本身**，不是"全名 + 缩写"两套——`name` 即短语词干（列名前缀），`label`/`description` 解释语义。**变量名与 name 一致**（小写）。短语要短（mer / bd / amt 三字母左右），**不要用长语**：引用商户实体的字段叫 `mer_id`，不叫 `merchant_id`。
-
-## 定义
-
-```ts
-// schema/_dictionary.ts
-import { definePhrase } from '@pylonts/dsl';
-
-const bd = definePhrase({ name: 'bd', label: 'BD推广员', description: '线下拓展商户、辅助入驻的推广人员' });
-const amt = definePhrase({ name: 'amt', label: '金额', description: '交易金额，单位分' });
-const mer = definePhrase({ name: 'mer', label: '商户', description: '入驻平台的商户' });
-```
-
-## 使用
-
-- **表链接实体**：`TableSchema.phrase` 引用实体条目，声明本表归属哪个实体（见 [table.md](./table.md) 的外键检查链）。关联表等多实体场景不需要。
-- 业务短语供字段命名/文档使用，跨团队对齐。
-- 未收录短语的实体保留全名作词干（不臆造缩写），评审时再裁决收录。
+# 短语词典 (Dictionary)
+
+词典是与团队达成共识的基础知识库：**某词代表什么**（语义/定义层面），不是物理形式。短语定了，字段命名、外键命名就都有依据——全项目只说同一种话。
+
+- 是基础知识库，很少变更。
+- **能引用就引用**：魔法字符串只在首次出现时使用，之后一律引用词典条目。
+
+## 规范位置：schema/_dictionary.ts
+
+**所有短语统一定义在 `schema/_dictionary.ts`**，一个文件一处定义；`*.table.ts` 从该文件 import 短语，禁止在表文件里内联定义短语。
+
+## 两种短语，两种命名规则
+
+短语分两类，参与不同的字段命名校验：
+
+| 类型 | 定义函数 | 含义 | 命名规则 | 例子 |
+|---|---|---|---|---|
+| `entity` | `defineEntityPhrase` | 实体缩写 | 字段名**首段**（实体领先） | `mer_id`、`bd_rate` |
+| `business` | `defineBusinessPhrase` | 实体的属性 | 字段名**末段**（属性收尾） | `bd_rate`、`acquiring_rate` |
+
+## 口径：name 即短语
+
+两个定义函数返回的条目**就是短语本身**，不是"全名 + 缩写"两套——`name` 即短语词干（列名前缀），`label`/`description` 解释语义。**变量名与 name 一致**（小写）。短语要短（mer / bd / amt 三字母左右），**不要用长语**：引用商户实体的字段叫 `mer_id`，不叫 `merchant_id`。
+
+## 定义
+
+```ts
+// schema/_dictionary.ts
+import { defineEntityPhrase, defineBusinessPhrase } from '@pylonts/dsl';
+
+const bd  = defineEntityPhrase({ name: 'bd',  label: 'BD推广员', description: '线下拓展商户、辅助入驻的推广人员' });
+const mer = defineEntityPhrase({ name: 'mer', label: '商户', description: '入驻平台的商户' });
+const amt = defineBusinessPhrase({ name: 'amt', label: '金额', description: '交易金额，单位分' });
+const rate = defineBusinessPhrase({ name: 'rate', label: '费率', description: '结算费率' });
+```
+
+## 使用
+
+- **表链接实体**：`TableSchema.phrase` 引用**实体短语**条目，声明本表归属哪个实体（见 [table.md](./table.md) 的外键检查链）。关联表等多实体场景不需要。
+- 业务短语供字段命名/文档使用，跨团队对齐。
+- 未收录短语的实体保留全名作词干（不臆造缩写），评审时再裁决收录。
+- 字段命名校验按类型区分：实体短语必须首段、业务短语必须末段（见 [field-check.md](../../lint/docs/field-check.md)）。