@pylonts/dsl 1.0.6 → 1.1.2

package/docs/table.md

@@ -16,7 +16,9 @@
 | `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`。
+
+**`optional` 默认语义（MySQL 惯例）**：不写 `optional` 或写 `optional: true` → 列可空，DDL 不渲染 `NOT NULL`；写 `optional: false` → 列必填（`NOT NULL`）。业务上必填的列必须显式声明。
 
 ## 定义表
 
@@ -27,25 +29,50 @@ 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: '金额' }),
+    amount: decimalField({ precision: 18, scale: 2, label: '金额', optional: false }),
   },
   primaryKey: id,
 });
 ```
 
-- 字段名从 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 +82,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 约束**（`pylonts gen sql init` 不传 `generateForeignKeys`）。数据完整性由 Service/DAO 层保证；如需物理约束，调用 `buildCreateTableSql(schema, { generateForeignKeys: true })`。
 
 ## 生成 SQL
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@pylonts/dsl",
-  "version": "1.0.6",
+  "version": "1.1.2",
   "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/action.ts

@@ -0,0 +1,11 @@
+import { SchemaBase } from './dsl.js';
+
+/** An action a user can perform on a page (e.g. submit, approve, reject).
+ *  Subclasses use `type` as the discriminator. */
+export interface ActionSchema extends SchemaBase {
+  type: string;
+}
+
+export function defineAction(name: string, description?: string): ActionSchema {
+  return { name, description, type: 'gesture' };
+}

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:
+ *   // pylonts gen asset list --tag form       → all form-related assets
+ *   // pylonts gen 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,20 +1,30 @@
-import type { DtoMessage, ImportRef } from './dto';
-
-// Named base-schema references for common protocol DTOs.
-//
-// These are ImportRef metadata (not re-exports of the actual TypeBox schemas):
-// the DSL stores { from, name } so the generator can emit the import line and
-// the identifier — the runtime schema object itself is never loaded by the DSL.
-//
-// `import { PageRequest } from '@pylonts/dsl'` therefore gives .include() an
-// 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' };
-
-/** Paginated list response base — renders `import { PageResult } from '@pylonts/core'` + `PageResult(<row>)` */
-export const PageResult = (row: DtoMessage): ImportRef => ({
-  from: '@pylonts/core',
-  name: 'PageResult',
-  args: [row],
-});
+import type { DtoMessage, ImportBase, ImportRef } from './dto.js';
+
+// Named base-schema references for common protocol DTOs.
+//
+// These are ImportRef metadata (not re-exports of the actual TypeBox schemas):
+// the DSL stores { from, name } so the generator can emit the import line and
+// the identifier — the runtime schema object itself is never loaded by the DSL.
+//
+// `import { PageRequest } from '@pylonts/dsl'` therefore gives .include() an
+// already-resolved reference — no static analysis or name lookup needed.
+
+/** Paginated query request base — renders `import { PageRequest } from '@pylonts/core'` + Intersect */
+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 => ({
+  from: '@pylonts/core',
+  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/component.ts

@@ -0,0 +1,22 @@
+import type { SchemaBase } from './dsl.js';
+import type { RefSchema } from './ref.js';
+import type { ActionSchema } from './action.js';
+import type { EventDataSchema } from './event.js';
+
+/** A component event trigger declaration. */
+export interface TriggerSchema extends SchemaBase {
+  /** Data the event carries (e.g. e.detail). */
+  eventData?: EventDataSchema;
+  /** Actions that fire when the event occurs. */
+  actions?: ActionSchema[];
+}
+
+/** A UI component declaration — a virtual schema that describes props and
+ *  event triggers, not a real renderable component.
+ *
+ *  properties: data bindings via RefSchema (or literal values).
+ *  triggers: event name → TriggerSchema bindings. */
+export interface ComponentSchema extends SchemaBase {
+  properties: Record<string, RefSchema | string | number | boolean>;
+  triggers: Record<string, TriggerSchema>;
+}

package/src/convert.ts

@@ -0,0 +1,13 @@
+import type { SchemaBase } from './dsl.js';
+
+/** Declares post-call result → page data field mapping.
+ *  Driver generates per-item transform (e.g. .map()) before setData. */
+export interface ConvertSchema extends SchemaBase {
+  type: 'convert';
+  /** { targetField: sourceField } — renames or copies fields from call result. */
+  fields: Record<string, string>;
+}
+
+export function defineConvert(name: string, fields: Record<string, string>): ConvertSchema {
+  return { name, type: 'convert', fields };
+}

package/src/curd.ts

@@ -0,0 +1,94 @@
+import { SchemaBase, Field, Operator } from './dsl.js';
+import { TableSchema } from './db.js';
+import { FrontAppSchema } from './project.js';
+import { ActionSchema } from './action.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;
+  /** For add/update: when true, render as modal on list page; when false/undefined, render as standalone route page. */
+  modal?: boolean;
+  /** 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;
+}

package/src/db.ts

@@ -0,0 +1,153 @@
+// DB table definitions.
+// Shape: { type: 'table', <extension fields> }
+
+import type { EntityPhrase } from './dictionary.js';
+import type { CollectionSchemaBase, EnumDef, Field } from './dsl.js';
+
+export type Index = {
+  name?: string;
+  columns: Field | Field[];
+  unique?: boolean;
+};
+
+export type ForeignKey = {
+  columns: Field | Field[];
+  references: Field | Field[];
+};
+
+export interface TableSchemaOptions<
+  N extends string = string,
+  C extends Record<string, Field> = Record<string, Field>,
+  E extends Record<string, EnumDef> = Record<string, EnumDef>
+> {
+  description?: string;
+  paginated?: boolean;
+  actor?: boolean;
+  generator?: string;
+  autoIncrement?: Field;
+  /** 本表用于关联显示的名称字段（如 name / username）。被外键引用时，自动用该字段做 label 展示。 */
+  label?: Field;
+  primaryKey?: Field | Field[];
+  indexes?: Index[];
+  foreignKeys?: Record<string, ForeignKey>;
+  /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
+  phrase?: EntityPhrase;
+  /** 本表引用的所有枚举定义（map，key 为枚举标识），显式声明供 gen-enums 收集 */
+  enums: E;
+  columns: C;
+}
+
+export class TableSchema<
+  N extends string = string,
+  C extends Record<string, Field> = Record<string, Field>,
+  E extends Record<string, EnumDef> = Record<string, EnumDef>
+> implements CollectionSchemaBase {
+  type = 'table';
+  name: N;
+  description?: string;
+  /** 分页 */
+  paginated?: boolean;
+  /** 系统操作者（如小程序为 C 端用户，管理端为运营） */
+  actor?: boolean;
+  /** id 生成器 */
+  generator?: string;
+  /** 自增主键字段 */
+  autoIncrement?: Field;
+  primaryKey?: Field | Field[];
+  indexes?: Index[];
+  /** 外键，引用其他表的字段 */
+  foreignKeys?: Record<string, ForeignKey>;
+  /** 本表用于关联显示的名称字段（如 name / username）。被外键引用时，自动用该字段做 label 展示。 */
+  label?: Field;
+  /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
+  phrase?: EntityPhrase;
+  /** 本表引用的所有枚举定义（map，key 为枚举标识），显式声明供 gen-enums 收集 */
+  enums: E;
+  columns: C;
+
+  constructor(name: N, options: TableSchemaOptions<N, C, E>) {
+    if (!options.enums) {
+      throw new Error(`table '${name}': enums is required — declare enums: {} when the table has no enums`);
+    }
+    this.name = name;
+    this.description = options.description;
+    this.paginated = options.paginated;
+    this.actor = options.actor;
+    this.generator = options.generator;
+    this.autoIncrement = options.autoIncrement;
+    this.primaryKey = options.primaryKey;
+    this.indexes = options.indexes;
+    this.foreignKeys = options.foreignKeys;
+    this.label = options.label;
+    this.phrase = options.phrase;
+    this.enums = options.enums;
+    this.columns = options.columns;
+  }
+
+  /** True when the field is part of this table's primary key */
+  isPk(fieldRef: Field): boolean {
+    if (this.primaryKey === undefined) return false;
+    return Array.isArray(this.primaryKey)
+      ? this.primaryKey.includes(fieldRef)
+      : this.primaryKey === fieldRef;
+  }
+}
+
+export function defineTable<
+  N extends string,
+  C extends Record<string, Field>,
+  E extends Record<string, EnumDef> = Record<string, EnumDef>
+>(
+  name: N,
+  schema: TableSchemaOptions<N, C, E>,
+): TableSchema<N, C, E> {
+  const table = new TableSchema<N, C, E>(name, schema);
+  if (table.generator && table.autoIncrement) {
+    throw new Error(`table '${name}': generator and autoIncrement are mutually exclusive`);
+  }
+  if (table.label && !Object.values(table.columns).includes(table.label)) {
+    throw new Error(`table '${name}': label field '${table.label.name}' must be one of the table's columns`);
+  }
+  for (const key of Object.keys(table.columns)) {
+    const field = table.columns[key] as Field;
+    if (field.schema && field.schema !== table) {
+      throw new Error(
+        `field ${key}: belongs to table ${field.schema.name}, cannot reuse in table ${table.name}`,
+      );
+    }
+  }
+  for (const key of Object.keys(table.columns)) {
+    table.columns[key].name = key;
+    table.columns[key].schema = table;
+  }
+  for (const [fkName, fk] of Object.entries(table.foreignKeys ?? {})) {
+    const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
+    const fields = Array.isArray(fk.columns) ? fk.columns : [fk.columns];
+    for (let i = 0; i < refs.length; i++) {
+      const ref = refs[i];
+      if (!ref.schema) throw new Error(`foreign key ${fkName}: references field has no schema`);
+      if (ref.schema === table) throw new Error(`foreign key ${fkName}: cannot reference own table ${table.name}`);
+      const phrase = (ref.schema as TableSchema).phrase;
+      if (!phrase) throw new Error(`foreign key ${fkName}: referenced table ${ref.schema.name} has no phrase, cannot check field naming`);
+      const expected = `${phrase.name}_${ref.name}`;
+      const fkField = fields[i];
+      if (fkField.name !== expected) {
+        throw new Error(
+          `foreign key ${fkName}: field must be named ${expected} (phrase ${phrase.name} + ${ref.name}), got ${fkField.name}`,
+        );
+      }
+    }
+  }
+  for (const [idxKey, index] of Object.entries(table.indexes ?? {})) {
+    const cols = Array.isArray(index.columns) ? index.columns : [index.columns];
+    for (const col of cols) {
+      if (typeof col !== 'object' || col === null || typeof (col as Field).type !== 'string') {
+        const idxName = index.name ?? idxKey;
+        throw new Error(
+          `index ${idxName}: columns must be Field instances (stringField()/intField()/...), got ${JSON.stringify(col)}`,
+        );
+      }
+    }
+  }
+  return table;
+}

package/src/dictionary.ts

@@ -1,20 +1,46 @@
-import { SchemaBase } from './dsl';
-
-// Dictionary definitions: vocabulary shared across the team — what a term
-// means and what it is called.
-
-/** A vocabulary entry. */
-export interface DictionaryEntry extends SchemaBase {
-  /** Display label (Chinese) for the term. */
-  label?: string;
-}
-
-/**
- * Explains a phrase — the returned entry IS the phrase. `name` is the phrase
- * itself (column-name stem, e.g. mer / bd / amt), not a full entity name;
- * label/description explain what it means. Convention: short phrase, not long
- * name.
- */
-export function definePhrase(extra: DictionaryEntry): DictionaryEntry {
-  return extra;
+import { SchemaBase } from './dsl.js';
+
+// Dictionary definitions: vocabulary shared across the team — what a term
+// means and what it is called.
+
+/** Kind of a dictionary entry: which naming rule the phrase participates in. */
+export enum DictionaryEntryType {
+  Entity = 'entity',
+  Business = 'business',
+}
+
+/** A vocabulary entry. */
+export interface DictionaryEntry extends SchemaBase {
+  /**
+   * Entry kind. Entity phrases (abbreviation of an entity, e.g. mer) must be
+   * the FIRST segment of a field name; business phrases (attribute of an
+   * entity, e.g. rate) must be the LAST segment.
+   */
+  type: DictionaryEntryType;
+  /** Display label (Chinese) for the term. */
+  label?: string;
+}
+
+/** An entity phrase entry — type narrowed to Entity. */
+export interface EntityPhrase extends DictionaryEntry {
+  type: DictionaryEntryType.Entity;
+}
+
+/**
+ * Explains an entity phrase — the returned entry IS the phrase. `name` is the
+ * phrase itself (column-name stem, e.g. mer / bd), not a full entity name;
+ * label/description explain what it means. Convention: short phrase, not long
+ * name. Entity phrases appear as the first segment of a field name (mer_id).
+ */
+export function defineEntityPhrase(extra: Omit<DictionaryEntry, 'type'>): EntityPhrase {
+  return { type: DictionaryEntryType.Entity, ...extra };
+}
+
+/**
+ * Explains a business phrase (an attribute of an entity) — the returned entry
+ * IS the phrase. `name` is the phrase itself (column-name stem, e.g. amt /
+ * rate). Business phrases appear as the last segment of a field name (bd_rate).
+ */
+export function defineBusinessPhrase(extra: Omit<DictionaryEntry, 'type'>): DictionaryEntry {
+  return { type: DictionaryEntryType.Business, ...extra };
 }