@pylonts/dsl 1.0.0 → 1.0.2

package/dist/pattern.d.ts

@@ -0,0 +1,15 @@
+export interface PatternParamDef {
+    type: 'int' | 'string';
+    min?: number;
+    default?: number | string;
+}
+export interface PatternDef {
+    name: string;
+    params: Record<string, PatternParamDef>;
+}
+export interface PatternRef {
+    ref: string;
+    args: Record<string, unknown>;
+}
+export declare function definePattern(def: PatternDef): PatternDef;
+export declare function ref(name: string, args: Record<string, unknown>): PatternRef;

package/dist/pattern.js

@@ -0,0 +1,13 @@
+"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) {
+    return def;
+}
+function ref(name, args) {
+    return { ref: name, args };
+}

package/dist/patterns/retry.d.ts

@@ -0,0 +1,16 @@
+import { PatternDef } from '../pattern';
+export declare const retryPattern: PatternDef;
+export interface RetryAction {
+    /** Function to call, e.g. 'queryOrderList' */
+    call: string;
+    /** Type name of the single argument passed through, e.g. 'OrderQueryParams' */
+    params?: string;
+}
+export interface RetryRefArgs {
+    max?: number;
+    backoffMs?: number;
+    action: RetryAction;
+    /** Generated function name; defaults to '<call>WithRetry' */
+    fnName?: string;
+}
+export declare function renderRetry(args: RetryRefArgs): string;

package/dist/patterns/retry.js

@@ -0,0 +1,40 @@
+"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 = {
+    name: 'retry',
+    params: {
+        max: { type: 'int', min: 1, default: 3 },
+        backoffMs: { type: 'int', min: 0, default: 0 },
+    },
+};
+function renderRetry(args) {
+    if (args.max !== undefined && args.max < 1)
+        throw new Error('retry: max must be >= 1');
+    if (!args.action.call)
+        throw new Error('retry: action.call is required');
+    const max = args.max ?? 3;
+    const backoffMs = args.backoffMs ?? 0;
+    const call = args.action.call;
+    const paramType = args.action.params ?? 'unknown';
+    const fnName = args.fnName ?? `${call}WithRetry`;
+    const retryLine = backoffMs > 0 ? `      await sleep(${backoffMs});` : '';
+    return [
+        `export async function ${fnName}(params: ${paramType}) {`,
+        `  for (let attempt = 1; ; attempt++) {`,
+        `    try {`,
+        `      return await ${call}(params);`,
+        `    } catch (err) {`,
+        `      if (attempt >= ${max}) throw err;`,
+        retryLine,
+        `    }`,
+        `  }`,
+        `}`,
+        '',
+    ].join('\n');
+}

package/dist/project.d.ts

@@ -0,0 +1,41 @@
+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[];
+    /** API base URL prefix shared by all apps it serves, e.g. '/mall'. '' = no prefix. */
+    contextPath?: 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 {
+    /** Source directory relative to project root, e.g. 'wechat/'. */
+    dir: string;
+}
+export interface ProjectSchema extends SchemaBase {
+    apps: FrontApp[];
+    apis: ProjectApi[];
+    thirdApis: ThirdApi[];
+}
+/**
+ * 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[];
+    thirdApis?: ThirdApi[];
+}): 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, thirdApis: schema.thirdApis ?? [] };
+}

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/docs/dictionary.md

@@ -0,0 +1,20 @@
+# 短语词典 (Dictionary)
+
+词典是与团队达成共识的基础知识库：**某词代表什么**（语义/定义层面），不是物理形式。短语定了，字段命名、外键命名就都有依据——全项目只说同一种话。
+
+- 是基础知识库，很少变更。
+- **能引用就引用**：魔法字符串只在首次出现时使用，之后一律引用词典条目。
+
+## 定义
+
+```ts
+import { definePhrase } from '@pylonts/dsl';
+
+const BD = definePhrase({ label: 'BD推广员', description: '线下拓展商户、辅助入驻的推广人员' });
+const Amt = definePhrase({ label: '金额', description: '交易金额，单位分' });
+```
+
+## 使用
+
+- **表链接实体**：`TableSchema.phrase` 引用实体条目，声明本表归属哪个实体（见 [table.md](./table.md) 的外键检查链）。关联表等多实体场景不需要。
+- 业务短语供字段命名/文档使用，跨团队对齐。

package/docs/driver.md

@@ -0,0 +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 }),   // 枚举引用解析
+});
+```

package/docs/dto.md

@@ -0,0 +1,54 @@
+# 定义 DTO（四种方向）
+
+DTO 描述接口出入参。方向决定语义与可选性规则：
+
+| 构建器 | 方向 | 用途 |
+|---|---|---|
+| `buildInput` | input | 新增/修改请求体 |
+| `buildOutput` | output | 响应体 |
+| `buildQuery` | query | 分页 + 过滤查询（字段恒为可选） |
+| `buildPk` | pk | 按主键取详情 |
+
+## 从表提取字段
+
+```ts
+import { buildInput, buildQuery, dtoField, from } from '@pylonts/dsl';
+
+// 输入：新增订单
+buildInput('OrderAddRequest', { ...from(order, [order.fields.merchant_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.merchant_id]),
+});
+
+// 主键：按 id 取详情
+buildPk('OrderDetailRequest', from(order, [order.fields.id]));
+```
+
+`from(table, fields)` 提取表字段包装为 DTO 字段，字段实例与表共享，`name/schema` 保持指向表。
+
+## 独立字段
+
+不来自表的内联字段直接用 `dtoField(...)` 包装任意字段构建器，可加 `pattern`、`optional`、`operator`。
+
+```ts
+dtoField(stringField({ maxLength: 32 })).op('like')
+```
+
+## 继承基础 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()`，保证精度与序列化语义。

package/docs/enum.md

@@ -0,0 +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)。

package/docs/mysql-connection.md

@@ -0,0 +1 @@
+连接 MySQL 时，必须配置：`supportBigNumbers: true, bigNumberStrings: true`

package/docs/project.md

@@ -0,0 +1,24 @@
+# 项目拓扑 (Project)
+
+Project 是仓库的地图：描述有哪些前端应用、哪些后端 API，以及每个 API 服务哪些前端。
+
+```ts
+import { defineProject } from '@pylonts/dsl';
+
+const webAdmin   = { name: 'web-admin',   type: 'admin',  dir: 'web-admin/',  description: '管理后台' };
+const miniUser   = { name: 'mini-user',   type: 'wxmini', dir: 'mini-user/',  description: 'C端小程序' };
+const miniVerify = { name: 'mini-verify', type: 'wxmini', dir: 'mini-verify/',description: '核销小程序' };
+
+export const mall = defineProject('mall', {
+  description: '合作商户权益兑换商城',
+  apps: [webAdmin, miniUser, miniVerify],
+  apis: [
+    { name: 'mall-api', description: '商城主后端', dir: 'api/', contextPath: '/mall', apps: [webAdmin, miniUser, miniVerify] },
+  ],
+});
+```
+
+- `FrontApp`：`name` / `description` / `type`（admin | wxmini）/ `dir`（相对仓库根目录的源码目录）。
+- `ProjectApi`：`name` / `description` / `dir` / `apps`（直接引用共享的 FrontApp 实例——一个 app 被多个 API 服务就定义一次、引用多次）/ `contextPath`（API 基础 URL 前缀，如 `/mall`，空串表示无前缀）。
+- **直接对象引用优先**：`api.apps` 与 `project.apps` 指向同一实例，不写字符串。
+- **contextPath 解析**：前端 app 的 API 前缀由服务它的 api 决定——`api.apps` 必须恰好包含该 app（零个或多个都报错），app 本身不声明 contextPath。

package/docs/prototype.md

@@ -0,0 +1,21 @@
+# 页面原型 (Prototype)
+
+原型是**单个实例**的页面/功能概要设计——一张页面的草图。只列出页面需要的字段，不涉及类型、不绑定 app/API/表，字段细节（DTO/表定义）在详细设计阶段另行编写、后续连接。
+
+```ts
+import { definePrototype } from '@pylonts/dsl';
+
+export const adminOrderList = definePrototype('AdminOrderList', {
+  description: '管理端订单列表页',
+  fields: {
+    order_no:   { label: '订单号', description: '商家下单生成的订单编号' },
+    merchant:   { label: '商户', description: '下单商户' },
+    amount:     { label: '金额', description: '订单实付金额' },
+    created_at: { label: '下单时间' },
+  },
+});
+```
+
+- 字段 key 即字段名，后续 DTO/表定义直接引用同名；这里只携带 `label` / `description`。
+- 原型是单实例的（一个东西的原型，不是整个项目的），同名页面在不同 app 中各自定义，互不干扰。
+- 不做回写：原型字段无写回机制，各走各的。

package/docs/table.md

@@ -0,0 +1,90 @@
+# 定义表 (TableSchema)
+
+## 字段类型
+
+| 构建器 | 类型 | jsType | MySQL 列 | 备注 |
+|---|---|---|---|---|
+| `stringField` | string | string | VARCHAR | 必填 `maxLength` |
+| `textField` | text | string | TEXT | |
+| `intField` | integer | number | INT | |
+| `bigintField` | bigint | string | BIGINT | 传输层走 string 保精度 |
+| `decimalField` | decimal | string | DECIMAL | 必填 `precision` / `scale`，传输层走 string 避免浮点误差 |
+| `booleanField` | boolean | boolean | TINYINT(1) | |
+| `dateField` | date | Date | DATE | |
+| `timeField` | time | string | TIME | |
+| `datetimeField` | datetime | Date | DATETIME | |
+| `enumField` | enum | string / number | VARCHAR(20) / TINYINT | 引用共享枚举定义，见 [enum.md](./enum.md) |
+| `jsonField` | json | object | JSON | |
+
+通用扩展属性（构建器第二参数）：`label`（中文标签）、`description`、`optional`、`readOnly`、`default`。
+
+## 定义表
+
+```ts
+import { bigintField, defineTable, decimalField, stringField } from '@pylonts/dsl';
+
+const id = bigintField({ readOnly: true, label: '主键' });
+
+export const order = defineTable('order', {
+  description: '订单',
+  generator: 'auto_increment',
+  fields: {
+    id,
+    order_no: stringField({ label: '订单号', maxLength: 32, optional: false }),
+    amount: decimalField({ precision: 18, scale: 2, label: '金额' }),
+  },
+  primaryKey: id,
+});
+```
+
+- 字段名从 map key 反写，`fields` 里的 key 就是列名。
+- 字段实例不可跨表复用（复用同一字段实例会抛错），枚举除外。
+
+## 索引
+
+```ts
+indexes: [
+  { name: 'uk_uuid', fields: c_uuid, unique: true },
+  { fields: [c_enum, c_date] },   // 名字缺省时 = 字段名 join '_'
+],
+```
+
+## 外键与短语检查链
+
+```ts
+import { definePhrase } from '@pylonts/dsl';
+
+const BD = definePhrase({ label: 'BD推广员', description: '线下拓展商户的推广人员' });
+
+const bdId = bigintField({ readOnly: true, label: 'BD ID' });
+
+export const bd = defineTable('bd', {
+  description: 'BD',
+  phrase: BD,            // 链接词典条目：本表归属的实体
+  fields: { id: bdId },
+  primaryKey: bdId,
+});
+
+const auditBdId = bigintField({ label: 'BD' });
+
+export const audit = defineTable('audit', {
+  description: '审核',
+  fields: {
+    bd_id: auditBdId,    // 列名必须 = phrase.name + '_' + 被引用字段名
+  },
+  foreignKeys: {
+    bd_bd_id: { fields: auditBdId, references: bdId },
+  },
+});
+```
+
+**规则（defineTable 时强制检查）**：外键字段名必须等于 `被引用表.phrase.name + "_" + 被引用字段名`。即引用 `bd.id` 的字段必须叫 `bd_id`——`bd` 来自词典（权威短语），`id` 是 `bd` 表主键。
+
+- 被引用表未定义 `phrase` → 抛错（检查链要求每个被引用表都有短语）。
+- 命名不匹配 → 抛错并提示期望名，例如：
+  `foreign key bad: field must be named bd_id (phrase bd + id), got merchant_id`
+- 关联表等涉及多个实体的场景不需要 `phrase`，也不建外键。
+
+## 生成 SQL
+
+见 [driver.md](./driver.md)。

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@pylonts/dsl",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Schema definition DSL with drivers: MySQL DDL, TS enum, TypeBox schema codegen.",
   "type": "commonjs",
   "main": "src/index.ts",
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "docs"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/src/dictionary.ts

@@ -0,0 +1,15 @@
+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;
+}
+
+/** Creates a phrase entry. */
+export function definePhrase(extra: DictionaryEntry): DictionaryEntry {
+  return extra;
+}

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,33 +196,55 @@ 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>;
+    /** 引用的实体短语（词典条目） */
+    phrase?: DictionaryEntry;
     fields: Record<string, Field>;
   },
 ): 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;