@pylonts/dsl 1.0.0 → 1.0.1

package/README.md

@@ -1,94 +1,26 @@
 # @pylonts/dsl
 
-Schema 定义与产物生成分离的 DSL 系统：先写 DSL 元数据（表 / DTO），再由 driver 翻译成目标产物（SQL、TS 枚举、TypeBox 源码）。
+Schema 定义与产物生成分离的 DSL 系统：先写 DSL 元数据（表 / DTO / 原型 / 项目 / 词典），再由 driver 翻译成目标产物（SQL、TS 枚举、TypeBox 源码）。
 
-## 结构
+## 分层结构
 
-```
-dsl/
-├── src/
-│   ├── dsl.ts            # 表 / 字段定义 + builder（stringField / intField / buildTable …）
-│   ├── dto.ts            # 接口层：buildInput / buildOutput / buildQuery / buildPk / from / include / op
-│   ├── mysql-driver.ts   # 表 → CREATE TABLE SQL
-│   ├── enum-driver.ts    # 枚举字段 → TS enum + LABEL 映射源码
-│   └── typebox-driver.ts # DTO → TypeBox 源码（fastify v5 校验）
-└── package.json
-```
-
-## 核心概念：driver 模式
-
-DSL 定义元数据，driver 翻译成目标语言产物。产物与定义解耦，同一份定义可生成不同目标：
-
-| 定义 | Driver | 产物 | 消费方 |
-|---|---|---|---|
-| `TableSchema` | mysql-driver | `CREATE TABLE` | MySQL |
-| `EnumField` | enum-driver | `export enum Xxx { … }` + `XXX_LABEL` | 业务代码 |
-| `DtoMessage` | typebox-driver | `Type.Object({…})` + `Static` 推导 | fastify v5 参数校验 |
+从概要设计到详细设计的自顶向下链路：
 
-## 用法
-
-### 定义表
-
-```ts
-import { bigintField, buildTable, decimalField, stringField } from './src/dsl';
-
-const id = bigintField({ readOnly: true, label: '主键' });
-const merId = bigintField({ label: '商户' });
-
-export const order = buildTable('order', {
-  description: '订单',
-  generator: 'auto_increment',
-  fields: {
-    id,
-    order_no: stringField({ label: '订单号', maxLength: 32, optional: false }),
-    mer_id: merId,
-    amount: decimalField({ precision: 18, scale: 2, label: '金额' }),
-  },
-  primaryKey: id,
-  indexes: [{ fields: merId }],
-});
 ```
-
-### 定义 DTO（四种方向）
-
-```ts
-import { buildInput, buildPk, buildQuery, dtoField, from } from './src/dto';
-
-// 输入：新增订单
-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 })).op('like'),
-  ...from(order, [order.fields.mer_id]),
-}).include({ from: '@pylonts/core', name: 'PageRequest' });
-
-// 主键：按 id 取详情
-buildPk('OrderDetailRequest', from(order, [order.fields.id]));
-```
-
-### 生成产物
-
-```ts
-import { buildCreateTableSql } from './src/mysql-driver';
-import { renderEnum } from './src/enum-driver';
-import { renderDtoMessage } from './src/typebox-driver';
-
-buildCreateTableSql(order);                                  // SQL
-renderEnum(statusField);                                    // TS enum 源码
-renderDtoMessage(orderPageQuery, {
-  source: 'dto_schema/order/order.dsl.dto.ts',
-  resolver: (name) => ({ from: '@mall/enums/user', name }), // 枚举引用解析
-});
+project（地图：应用与 API 拓扑）
+  → dictionary（词典：命名与数据类型标准）
+    → prototype（概要设计：页面与字段）
+      → table / dto（详细设计）
+        → driver 生成产物（SQL / 枚举 / TypeBox）
 ```
 
-## 关键语义
+## 文档
 
-- **字段两层名**：`DtoField.name` 是接口字段名（DTO 容器 map key 反写）；`field.name` 是数据库列名（buildTable 反写）。`from()` 提取的字段共享表 Field 实例，`name/schema` 保持指向表，不会被 DTO 覆盖。
-- **可选性优先级**：DTO 层 `optional` 优先于字段层 `optional`；query 方向所有字段强制可选（Rule B）。
-- **枚举外部引用**：枚举由 enum-driver 生成独立文件，typebox-driver 只渲染 `Type.Enum(名称)` + import 引用，不内联。
-- **HTTP 传 string**：bigint / decimal / date / time 在接口层渲染为 `Type.String()`，保证精度与序列化语义。
-- **继承分页**：`.include({ from, name, args })` 渲染 `Type.Intersect([PageRequest, Type.Object({…})])`。
+- [project.md](./docs/project.md) — 项目拓扑（地图）
+- [dictionary.md](./docs/dictionary.md) — 短语词典（命名标准）
+- [prototype.md](./docs/prototype.md) — 页面原型（概要设计）
+- [table.md](./docs/table.md) — 定义表（详细设计）
+- [dto.md](./docs/dto.md) — 定义 DTO
+- [enum.md](./docs/enum.md) — 定义枚举
+- [driver.md](./docs/driver.md) — driver 模式与产物生成
+- [mysql-connection.md](./docs/mysql-connection.md) — MySQL 连接说明

package/dist/dictionary.d.ts

@@ -0,0 +1,25 @@
+import { SchemaBase } from './dsl';
+/** A vocabulary entry: name is written back from the dictionary key. */
+export interface DictionaryEntry extends SchemaBase {
+}
+export interface DictionarySchema extends SchemaBase {
+    entries: Record<string, DictionaryEntry>;
+}
+/** Creates a phrase entry. name is filled in by defineDictionary. */
+export declare function definePhrase(extra?: Omit<DictionaryEntry, 'name'>): DictionaryEntry;
+/** Defines the entity phrase dictionary: standard words aligned with entities. */
+export declare function defineEntityDictionary(schema: {
+    description?: string;
+    entries: Record<string, DictionaryEntry>;
+}): DictionarySchema;
+/**
+ * Defines a business phrase package (one file per industry): entries are the
+ * top-level map keys, no wrapping container.
+ */
+export declare function defineBusinessDictionary(entries: Record<string, DictionaryEntry>): DictionarySchema;
+/**
+ * Merges business phrase packages (one file per industry) into a single flat
+ * map. Package metadata (name/description) is dropped; duplicate keys across
+ * packages throw.
+ */
+export declare function mergeBusinessDictionaries(packages: DictionarySchema[]): Record<string, DictionaryEntry>;

package/dist/dictionary.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.definePhrase = definePhrase;
+exports.defineEntityDictionary = defineEntityDictionary;
+exports.defineBusinessDictionary = defineBusinessDictionary;
+exports.mergeBusinessDictionaries = mergeBusinessDictionaries;
+/** Creates a phrase entry. name is filled in by defineDictionary. */
+function definePhrase(extra = {}) {
+    return { name: '', ...extra };
+}
+function defineDictionary(schema) {
+    const dictionary = { ...schema };
+    for (const key of Object.keys(dictionary.entries)) {
+        dictionary.entries[key].name = key;
+    }
+    return dictionary;
+}
+/** Defines the entity phrase dictionary: standard words aligned with entities. */
+function defineEntityDictionary(schema) {
+    return defineDictionary({ name: 'entity', ...schema });
+}
+/**
+ * Defines a business phrase package (one file per industry): entries are the
+ * top-level map keys, no wrapping container.
+ */
+function defineBusinessDictionary(entries) {
+    return defineDictionary({ name: 'business', entries });
+}
+/**
+ * Merges business phrase packages (one file per industry) into a single flat
+ * map. Package metadata (name/description) is dropped; duplicate keys across
+ * packages throw.
+ */
+function mergeBusinessDictionaries(packages) {
+    const merged = {};
+    for (const pkg of packages) {
+        for (const key of Object.keys(pkg.entries)) {
+            if (merged[key]) {
+                throw new Error(`business phrase ${key} is defined in multiple packages`);
+            }
+            merged[key] = pkg.entries[key];
+        }
+    }
+    return merged;
+}

package/dist/dsl.d.ts

@@ -1,3 +1,4 @@
+import type { DictionaryEntry } from './dictionary';
 export interface SchemaBase {
     name: string;
     description?: string;
@@ -61,13 +62,19 @@ export interface EnumValue {
     symbol: string;
     label: string;
 }
+/** Shared enum definition. Pure value object, safe to reference from multiple fields/tables. */
+export interface EnumDef {
+    /** JS 定义名称，如 MerchantStatus */
+    jsName: string;
+    valueType: 'string' | 'integer';
+    values: EnumValue[];
+}
+export declare function defineEnum(jsName: string, valueType: 'string' | 'integer', values: EnumValue[]): EnumDef;
 export interface EnumField extends BaseField {
     type: 'enum';
     jsType: 'string' | 'number';
-    valueType: 'string' | 'integer';
-    /** JS 定义名称，如 MerchantStatus */
-    jsName?: string;
-    values: EnumValue[];
+    /** Reference to a shared enum definition (see defineEnum). */
+    enum: EnumDef;
 }
 interface JsonField extends BaseField {
     type: 'json';
@@ -90,10 +97,14 @@ export interface TableSchema extends SchemaBase {
     actor?: boolean;
     /** id 生成器 */
     generator?: string;
+    /** 自增主键字段 */
+    autoIncrement?: Field;
     primaryKey?: Field | Field[];
     indexes?: Index[];
     /** 外键，引用其他表的字段 */
     foreignKeys?: Record<string, ForeignKey>;
+    /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
+    phrase?: DictionaryEntry;
     fields: Record<string, Field>;
 }
 type FieldExtras<T extends Field> = Omit<T, 'name' | 'type' | 'jsType'>;
@@ -108,11 +119,12 @@ export declare function timeField(extra?: FieldExtras<TimeField>): TimeField;
 export declare function datetimeField(extra?: FieldExtras<DateTimeField>): DateTimeField;
 export declare function jsonField(extra?: FieldExtras<JsonField>): JsonField;
 export declare function enumField(extra: Omit<EnumField, 'name' | 'type' | 'jsType'>): EnumField;
-export declare function buildTable(name: string, schema: {
+export declare function defineTable(name: string, schema: {
     description?: string;
     paginated?: boolean;
     actor?: boolean;
     generator?: string;
+    autoIncrement?: Field;
     primaryKey?: Field | Field[];
     indexes?: Index[];
     foreignKeys?: Record<string, ForeignKey>;

package/dist/dsl.js

@@ -2,6 +2,7 @@
 // DSL field type definitions.
 // Shape: { type: <type name>, <extension fields> }
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineEnum = defineEnum;
 exports.stringField = stringField;
 exports.textField = textField;
 exports.intField = intField;
@@ -13,7 +14,10 @@ exports.timeField = timeField;
 exports.datetimeField = datetimeField;
 exports.jsonField = jsonField;
 exports.enumField = enumField;
-exports.buildTable = buildTable;
+exports.defineTable = defineTable;
+function defineEnum(jsName, valueType, values) {
+    return { jsName, valueType, values };
+}
 function stringField(extra = {}) {
     return { name: '', type: 'string', jsType: 'string', ...extra };
 }
@@ -45,22 +49,38 @@ function jsonField(extra = {}) {
     return { name: '', type: 'json', jsType: 'object', ...extra };
 }
 function enumField(extra) {
-    const jsType = extra.valueType === 'integer' ? 'number' : 'string';
+    const jsType = extra.enum.valueType === 'integer' ? 'number' : 'string';
     return { name: '', type: 'enum', jsType, ...extra };
 }
-function buildTable(name, schema) {
+function defineTable(name, schema) {
     const table = { name, ...schema };
+    for (const key of Object.keys(table.fields)) {
+        const field = table.fields[key];
+        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.fields)) {
         table.fields[key].name = key;
         table.fields[key].schema = table;
     }
     for (const [fkName, fk] of Object.entries(table.foreignKeys ?? {})) {
         const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
-        for (const ref of refs) {
+        const fields = Array.isArray(fk.fields) ? fk.fields : [fk.fields];
+        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.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}`);
+            }
         }
     }
     return table;

package/dist/enum-driver.d.ts

@@ -1,2 +1,2 @@
-import { EnumField } from './dsl';
-export declare function renderEnum(field: EnumField): string;
+import { EnumDef } from './dsl';
+export declare function renderEnum(def: EnumDef): string;

package/dist/enum-driver.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderEnum = renderEnum;
-// Enum driver: renders an EnumField into a standalone TypeScript enum file.
+// Enum driver: renders an EnumDef into a standalone TypeScript enum file.
 // Shape matches the generated-enum product consumed by the TypeBox driver (Type.Enum):
 //
 //   export enum UserStatus {
@@ -23,12 +23,10 @@ function renderValue(value) {
 function labelName(jsName) {
     return `${jsName.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase()}_LABEL`;
 }
-function renderEnum(field) {
-    if (!field.jsName)
-        throw new Error(`enum field ${field.name} requires jsName to render`);
-    const name = field.jsName;
-    const members = field.values.map((v) => `  ${v.symbol} = ${renderValue(v.value)},`);
-    const labels = field.values.map((v) => `  [${name}.${v.symbol}]: ${renderString(v.label)},`);
+function renderEnum(def) {
+    const name = def.jsName;
+    const members = def.values.map((v) => `  ${v.symbol} = ${renderValue(v.value)},`);
+    const labels = def.values.map((v) => `  [${name}.${v.symbol}]: ${renderString(v.label)},`);
     return [
         `export enum ${name} {`,
         ...members,

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export * from './dsl';
 export * from './dto';
+export * from './project';
+export * from './prototype';
+export * from './dictionary';
 export * from './mysql-driver';
 export * from './enum-driver';
 export * from './typebox-driver';

package/dist/index.js

@@ -16,6 +16,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./dsl"), exports);
 __exportStar(require("./dto"), exports);
+__exportStar(require("./project"), exports);
+__exportStar(require("./prototype"), exports);
+__exportStar(require("./dictionary"), exports);
 __exportStar(require("./mysql-driver"), exports);
 __exportStar(require("./enum-driver"), exports);
 __exportStar(require("./typebox-driver"), exports);

package/dist/mysql-driver.d.ts

@@ -1,2 +1,6 @@
 import { TableSchema } from './dsl';
-export declare function buildCreateTableSql(schema: TableSchema): string;
+export interface BuildCreateTableSqlOptions {
+    /** 是否生成外键约束，默认 false（不生成） */
+    generateForeignKeys?: boolean;
+}
+export declare function buildCreateTableSql(schema: TableSchema, options?: BuildCreateTableSqlOptions): string;

package/dist/mysql-driver.js

@@ -26,17 +26,19 @@ function columnType(field) {
             return 'DATETIME';
         case 'enum':
             // Enum is stored as a plain column: string -> VARCHAR(20), integer -> TINYINT.
-            return field.valueType === 'integer' ? 'TINYINT' : 'VARCHAR(20)';
+            return field.enum.valueType === 'integer' ? 'TINYINT' : 'VARCHAR(20)';
         case 'json':
             return 'JSON';
     }
 }
-function columnDef(field) {
+function columnDef(field, autoIncrement) {
     const parts = [field.name, columnType(field)];
     if (field.optional === false)
         parts.push('NOT NULL');
     if (field.default !== undefined)
         parts.push(`DEFAULT '${field.default}'`);
+    if (field === autoIncrement)
+        parts.push('AUTO_INCREMENT');
     return parts.join(' ');
 }
 function primaryKeyClause(schema) {
@@ -51,12 +53,27 @@ function indexClause(index) {
     const name = index.name ?? fields.map((f) => f.name).join('_');
     return `${kind} ${name} (${fields.map((f) => f.name).join(', ')})`;
 }
-function buildCreateTableSql(schema) {
-    const lines = Object.values(schema.fields).map(columnDef);
+function foreignKeyClause(name, fk) {
+    const fields = Array.isArray(fk.fields) ? fk.fields : [fk.fields];
+    const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
+    const refTable = refs[0].schema?.name;
+    if (!refTable)
+        throw new Error(`foreign key ${name}: references field has no schema`);
+    const fkCols = fields.map((f) => f.name).join(', ');
+    const refCols = refs.map((r) => r.name).join(', ');
+    return `CONSTRAINT \`${name}\` FOREIGN KEY (${fkCols}) REFERENCES \`${refTable}\` (${refCols})`;
+}
+function buildCreateTableSql(schema, options = {}) {
+    const lines = Object.values(schema.fields).map((field) => columnDef(field, schema.autoIncrement));
     const pk = primaryKeyClause(schema);
     if (pk)
         lines.push(pk);
     for (const index of schema.indexes ?? [])
         lines.push(indexClause(index));
+    if (options.generateForeignKeys) {
+        for (const [name, fk] of Object.entries(schema.foreignKeys ?? {})) {
+            lines.push(foreignKeyClause(name, fk));
+        }
+    }
     return `CREATE TABLE \`${schema.name}\` (\n  ${lines.join(',\n  ')}\n);`;
 }

package/dist/project.d.ts

@@ -0,0 +1,30 @@
+import { SchemaBase } from './dsl';
+/** 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 {
+    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 {
+    /** Source directory relative to project root, e.g. 'api/'. */
+    dir: string;
+    /** Frontends this API serves. Direct instance references (see defineProject). */
+    apps: FrontApp[];
+}
+export interface ProjectSchema extends SchemaBase {
+    apps: FrontApp[];
+    apis: ProjectApi[];
+}
+/**
+ * Defines the project topology. FrontApp 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.
+ */
+export declare function defineProject(name: string, schema: {
+    description?: string;
+    apps: FrontApp[];
+    apis: ProjectApi[];
+}): ProjectSchema;

package/dist/project.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineProject = defineProject;
+/**
+ * Defines the project topology. FrontApp 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.
+ */
+function defineProject(name, schema) {
+    return { name, ...schema };
+}

package/dist/prototype.d.ts

@@ -0,0 +1,18 @@
+import { SchemaBase } from './dsl';
+/** Display metadata for a prototype field. */
+export interface PrototypeFieldMeta {
+    label: string;
+    description?: string;
+}
+export interface PrototypeSchema extends SchemaBase {
+    /** Field requirements: key is the field name, value is display metadata. */
+    fields: Record<string, PrototypeFieldMeta>;
+}
+/**
+ * Defines a page prototype. The field keys become the names referenced by
+ * later DTO/table definitions; here they only carry label/description.
+ */
+export declare function definePrototype(name: string, schema: {
+    description?: string;
+    fields: Record<string, PrototypeFieldMeta>;
+}): PrototypeSchema;

package/dist/prototype.js

@@ -0,0 +1,10 @@
+"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) {
+    return { name, ...schema };
+}

package/dist/typebox-driver.js

@@ -43,11 +43,9 @@ function renderBasic(field, pattern, resolver) {
         case 'json':
             return 'Type.Unknown()';
         case 'enum': {
-            if (!field.jsName)
-                throw new Error(`enum field ${field.name} requires jsName to render`);
-            const ref = resolver?.(field.jsName);
+            const ref = resolver?.(field.enum.jsName);
             if (!ref)
-                throw new Error(`enum field ${field.name}: no import ref for ${field.jsName} — pass an EnumResolver`);
+                throw new Error(`enum field ${field.name}: no import ref for ${field.enum.jsName} — pass an EnumResolver`);
             return `Type.Enum(${ref.name})`;
         }
         default:
@@ -85,11 +83,9 @@ function collectEnumImports(f, resolver, out) {
         return;
     }
     if (f.field.type === 'enum') {
-        if (!f.field.jsName)
-            throw new Error(`enum field ${f.field.name} requires jsName to render`);
-        const ref = resolver?.(f.field.jsName);
+        const ref = resolver?.(f.field.enum.jsName);
         if (!ref)
-            throw new Error(`enum field ${f.field.name}: no import ref for ${f.field.jsName} — pass an EnumResolver`);
+            throw new Error(`enum field ${f.field.name}: no import ref for ${f.field.enum.jsName} — pass an EnumResolver`);
         out.set(`${ref.from}#${ref.name}`, ref);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonts/dsl",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Schema definition DSL with drivers: MySQL DDL, TS enum, TypeBox schema codegen.",
   "type": "commonjs",
   "main": "src/index.ts",

package/src/dictionary.ts

@@ -0,0 +1,63 @@
+import { SchemaBase } from './dsl';
+
+// Dictionary definitions: vocabulary shared across the team — what a term
+// means and what it is called. Entries are written back from the map key,
+// the same mechanism as defineTable fields.
+
+/** A vocabulary entry: name is written back from the dictionary key. */
+export interface DictionaryEntry extends SchemaBase {}
+
+export interface DictionarySchema extends SchemaBase {
+  entries: Record<string, DictionaryEntry>;
+}
+
+/** Creates a phrase entry. name is filled in by defineDictionary. */
+export function definePhrase(extra: Omit<DictionaryEntry, 'name'> = {}): DictionaryEntry {
+  return { name: '', ...extra };
+}
+
+function defineDictionary(schema: {
+  name: string;
+  description?: string;
+  entries: Record<string, DictionaryEntry>;
+}): DictionarySchema {
+  const dictionary: DictionarySchema = { ...schema };
+  for (const key of Object.keys(dictionary.entries)) {
+    dictionary.entries[key].name = key;
+  }
+  return dictionary;
+}
+
+/** Defines the entity phrase dictionary: standard words aligned with entities. */
+export function defineEntityDictionary(schema: {
+  description?: string;
+  entries: Record<string, DictionaryEntry>;
+}): DictionarySchema {
+  return defineDictionary({ name: 'entity', ...schema });
+}
+
+/**
+ * Defines a business phrase package (one file per industry): entries are the
+ * top-level map keys, no wrapping container.
+ */
+export function defineBusinessDictionary(entries: Record<string, DictionaryEntry>): DictionarySchema {
+  return defineDictionary({ name: 'business', entries });
+}
+
+/**
+ * Merges business phrase packages (one file per industry) into a single flat
+ * map. Package metadata (name/description) is dropped; duplicate keys across
+ * packages throw.
+ */
+export function mergeBusinessDictionaries(packages: DictionarySchema[]): Record<string, DictionaryEntry> {
+  const merged: Record<string, DictionaryEntry> = {};
+  for (const pkg of packages) {
+    for (const key of Object.keys(pkg.entries)) {
+      if (merged[key]) {
+        throw new Error(`business phrase ${key} is defined in multiple packages`);
+      }
+      merged[key] = pkg.entries[key];
+    }
+  }
+  return merged;
+}

package/src/dsl.ts

@@ -1,6 +1,8 @@
 // DSL field type definitions.
 // Shape: { type: <type name>, <extension fields> }
 
+import type { DictionaryEntry } from './dictionary';
+
 export interface SchemaBase {
   name: string;
   description?: string;
@@ -78,13 +80,27 @@ export interface EnumValue {
   label: string;
 }
 
+/** Shared enum definition. Pure value object, safe to reference from multiple fields/tables. */
+export interface EnumDef {
+  /** JS 定义名称，如 MerchantStatus */
+  jsName: string;
+  valueType: 'string' | 'integer';
+  values: EnumValue[];
+}
+
+export function defineEnum(
+  jsName: string,
+  valueType: 'string' | 'integer',
+  values: EnumValue[],
+): EnumDef {
+  return { jsName, valueType, values };
+}
+
 export interface EnumField extends BaseField {
   type: 'enum';
   jsType: 'string' | 'number';
-  valueType: 'string' | 'integer';
-  /** JS 定义名称，如 MerchantStatus */
-  jsName?: string;
-  values: EnumValue[];
+  /** Reference to a shared enum definition (see defineEnum). */
+  enum: EnumDef;
 }
 
 interface JsonField extends BaseField {
@@ -123,15 +139,19 @@ export interface TableSchema extends SchemaBase {
   actor?: boolean;
   /** id 生成器 */
   generator?: string;
+  /** 自增主键字段 */
+  autoIncrement?: Field;
   primaryKey?: Field | Field[];
   indexes?: Index[];
   /** 外键，引用其他表的字段 */
   foreignKeys?: Record<string, ForeignKey>;
+  /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
+  phrase?: DictionaryEntry;
   fields: Record<string, Field>;
 }
 
 // Field builders: type and jsType are fixed, pass extra properties only.
-// The field name is written back from the map key later (see buildTable).
+// The field name is written back from the map key later (see defineTable).
 
 type FieldExtras<T extends Field> = Omit<T, 'name' | 'type' | 'jsType'>;
 
@@ -176,17 +196,18 @@ export function jsonField(extra: FieldExtras<JsonField> = {}): JsonField {
 }
 
 export function enumField(extra: Omit<EnumField, 'name' | 'type' | 'jsType'>): EnumField {
-  const jsType = extra.valueType === 'integer' ? 'number' : 'string';
+  const jsType = extra.enum.valueType === 'integer' ? 'number' : 'string';
   return { name: '', type: 'enum', jsType, ...extra };
 }
 
-export function buildTable(
+export function defineTable(
   name: string,
   schema: {
     description?: string;
     paginated?: boolean;
     actor?: boolean;
     generator?: string;
+    autoIncrement?: Field;
     primaryKey?: Field | Field[];
     indexes?: Index[];
     foreignKeys?: Record<string, ForeignKey>;
@@ -194,15 +215,34 @@ export function buildTable(
   },
 ): TableSchema {
   const table: TableSchema = { name, ...schema };
+  for (const key of Object.keys(table.fields)) {
+    const field = table.fields[key];
+    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.fields)) {
     table.fields[key].name = key;
     table.fields[key].schema = table;
   }
   for (const [fkName, fk] of Object.entries(table.foreignKeys ?? {})) {
     const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
-    for (const ref of refs) {
+    const fields = Array.isArray(fk.fields) ? fk.fields : [fk.fields];
+    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}`,
+        );
+      }
     }
   }
   return table;

package/src/enum-driver.ts

@@ -1,6 +1,6 @@
-import { EnumField } from './dsl';
+import { EnumDef } from './dsl';
 
-// Enum driver: renders an EnumField into a standalone TypeScript enum file.
+// Enum driver: renders an EnumDef into a standalone TypeScript enum file.
 // Shape matches the generated-enum product consumed by the TypeBox driver (Type.Enum):
 //
 //   export enum UserStatus {
@@ -26,11 +26,10 @@ function labelName(jsName: string): string {
   return `${jsName.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase()}_LABEL`;
 }
 
-export function renderEnum(field: EnumField): string {
-  if (!field.jsName) throw new Error(`enum field ${field.name} requires jsName to render`);
-  const name = field.jsName;
-  const members = field.values.map((v) => `  ${v.symbol} = ${renderValue(v.value)},`);
-  const labels = field.values.map((v) => `  [${name}.${v.symbol}]: ${renderString(v.label)},`);
+export function renderEnum(def: EnumDef): string {
+  const name = def.jsName;
+  const members = def.values.map((v) => `  ${v.symbol} = ${renderValue(v.value)},`);
+  const labels = def.values.map((v) => `  [${name}.${v.symbol}]: ${renderString(v.label)},`);
   return [
     `export enum ${name} {`,
     ...members,
@@ -41,4 +40,4 @@ export function renderEnum(field: EnumField): string {
     '};',
     '',
   ].join('\n');
-}
+}

package/src/index.ts

@@ -1,5 +1,8 @@
 export * from './dsl';
 export * from './dto';
+export * from './project';
+export * from './prototype';
+export * from './dictionary';
 export * from './mysql-driver';
 export * from './enum-driver';
-export * from './typebox-driver';
+export * from './typebox-driver';

package/src/mysql-driver.ts

@@ -1,4 +1,4 @@
-import { Field, Index, TableSchema } from './dsl';
+import { Field, ForeignKey, Index, TableSchema } from './dsl';
 
 // MySQL driver: converts a TableSchema into a CREATE TABLE statement.
 
@@ -25,16 +25,17 @@ function columnType(field: Field): string {
       return 'DATETIME';
     case 'enum':
       // Enum is stored as a plain column: string -> VARCHAR(20), integer -> TINYINT.
-      return field.valueType === 'integer' ? 'TINYINT' : 'VARCHAR(20)';
+      return field.enum.valueType === 'integer' ? 'TINYINT' : 'VARCHAR(20)';
     case 'json':
       return 'JSON';
   }
 }
 
-function columnDef(field: Field): string {
+function columnDef(field: Field, autoIncrement?: Field): string {
   const parts = [field.name, columnType(field)];
   if (field.optional === false) parts.push('NOT NULL');
   if (field.default !== undefined) parts.push(`DEFAULT '${field.default}'`);
+  if (field === autoIncrement) parts.push('AUTO_INCREMENT');
   return parts.join(' ');
 }
 
@@ -51,10 +52,30 @@ function indexClause(index: Index): string {
   return `${kind} ${name} (${fields.map((f) => f.name).join(', ')})`;
 }
 
-export function buildCreateTableSql(schema: TableSchema): string {
-  const lines = Object.values(schema.fields).map(columnDef);
+function foreignKeyClause(name: string, fk: ForeignKey): string {
+  const fields = Array.isArray(fk.fields) ? fk.fields : [fk.fields];
+  const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
+  const refTable = refs[0].schema?.name;
+  if (!refTable) throw new Error(`foreign key ${name}: references field has no schema`);
+  const fkCols = fields.map((f) => f.name).join(', ');
+  const refCols = refs.map((r) => r.name).join(', ');
+  return `CONSTRAINT \`${name}\` FOREIGN KEY (${fkCols}) REFERENCES \`${refTable}\` (${refCols})`;
+}
+
+export interface BuildCreateTableSqlOptions {
+  /** 是否生成外键约束，默认 false（不生成） */
+  generateForeignKeys?: boolean;
+}
+
+export function buildCreateTableSql(schema: TableSchema, options: BuildCreateTableSqlOptions = {}): string {
+  const lines = Object.values(schema.fields).map((field) => columnDef(field, schema.autoIncrement));
   const pk = primaryKeyClause(schema);
   if (pk) lines.push(pk);
   for (const index of schema.indexes ?? []) lines.push(indexClause(index));
+  if (options.generateForeignKeys) {
+    for (const [name, fk] of Object.entries(schema.foreignKeys ?? {})) {
+      lines.push(foreignKeyClause(name, fk));
+    }
+  }
   return `CREATE TABLE \`${schema.name}\` (\n  ${lines.join(',\n  ')}\n);`;
 }

package/src/project.ts

@@ -0,0 +1,43 @@
+import { SchemaBase } from './dsl';
+
+// Project topology definitions: describe the applications (frontends) and
+// backend APIs of a repository, and which frontends each API serves.
+
+/** 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 {
+  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 {
+  /** Source directory relative to project root, e.g. 'api/'. */
+  dir: string;
+  /** Frontends this API serves. Direct instance references (see defineProject). */
+  apps: FrontApp[];
+}
+
+export interface ProjectSchema extends SchemaBase {
+  apps: FrontApp[];
+  apis: ProjectApi[];
+}
+
+/**
+ * Defines the project topology. FrontApp 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.
+ */
+export function defineProject(
+  name: string,
+  schema: {
+    description?: string;
+    apps: FrontApp[];
+    apis: ProjectApi[];
+  },
+): ProjectSchema {
+  return { name, ...schema };
+}

package/src/prototype.ts

@@ -0,0 +1,30 @@
+import { SchemaBase } from './dsl';
+
+// Prototype definitions: high-level design of a page. A prototype lists only
+// the fields a page needs — no types, no bindings to apps/APIs/tables. Field
+// details (DTO/table definitions) are written separately and connected later.
+
+/** Display metadata for a prototype field. */
+export interface PrototypeFieldMeta {
+  label: string;
+  description?: string;
+}
+
+export interface PrototypeSchema extends SchemaBase {
+  /** Field requirements: key is the field name, value is display metadata. */
+  fields: Record<string, PrototypeFieldMeta>;
+}
+
+/**
+ * Defines a page prototype. The field keys become the names referenced by
+ * later DTO/table definitions; here they only carry label/description.
+ */
+export function definePrototype(
+  name: string,
+  schema: {
+    description?: string;
+    fields: Record<string, PrototypeFieldMeta>;
+  },
+): PrototypeSchema {
+  return { name, ...schema };
+}

package/src/typebox-driver.ts

@@ -50,9 +50,8 @@ function renderBasic(field: Field, pattern: string | undefined, resolver: EnumRe
     case 'json':
       return 'Type.Unknown()';
     case 'enum': {
-      if (!field.jsName) throw new Error(`enum field ${field.name} requires jsName to render`);
-      const ref = resolver?.(field.jsName);
-      if (!ref) throw new Error(`enum field ${field.name}: no import ref for ${field.jsName} — pass an EnumResolver`);
+      const ref = resolver?.(field.enum.jsName);
+      if (!ref) throw new Error(`enum field ${field.name}: no import ref for ${field.enum.jsName} — pass an EnumResolver`);
       return `Type.Enum(${ref.name})`;
     }
     default:
@@ -97,9 +96,8 @@ function collectEnumImports(
     return;
   }
   if (f.field.type === 'enum') {
-    if (!f.field.jsName) throw new Error(`enum field ${f.field.name} requires jsName to render`);
-    const ref = resolver?.(f.field.jsName);
-    if (!ref) throw new Error(`enum field ${f.field.name}: no import ref for ${f.field.jsName} — pass an EnumResolver`);
+    const ref = resolver?.(f.field.enum.jsName);
+    if (!ref) throw new Error(`enum field ${f.field.name}: no import ref for ${f.field.enum.jsName} — pass an EnumResolver`);
     out.set(`${ref.from}#${ref.name}`, ref);
   }
 }