@pylonts/dsl 1.0.2 → 1.0.3

package/dist/dictionary.d.ts

@@ -4,5 +4,10 @@ export interface DictionaryEntry extends SchemaBase {
     /** Display label (Chinese) for the term. */
     label?: string;
 }
-/** Creates a phrase entry. */
+/**
+ * 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 declare function definePhrase(extra: DictionaryEntry): DictionaryEntry;

package/dist/dictionary.js

@@ -1,7 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.definePhrase = definePhrase;
-/** Creates a phrase entry. */
+/**
+ * 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.
+ */
 function definePhrase(extra) {
     return extra;
 }

package/docs/dictionary.md

@@ -5,16 +5,27 @@
 - 是基础知识库，很少变更。
 - **能引用就引用**：魔法字符串只在首次出现时使用，之后一律引用词典条目。
 
+## 规范位置：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({ label: 'BD推广员', description: '线下拓展商户、辅助入驻的推广人员' });
-const Amt = definePhrase({ label: '金额', description: '交易金额，单位分' });
+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) 的外键检查链）。关联表等多实体场景不需要。
-- 业务短语供字段命名/文档使用，跨团队对齐。
+- 业务短语供字段命名/文档使用，跨团队对齐。
+- 未收录短语的实体保留全名作词干（不臆造缩写），评审时再裁决收录。

package/docs/dto.md

@@ -15,7 +15,7 @@ DTO 描述接口出入参。方向决定语义与可选性规则：
 import { buildInput, buildQuery, dtoField, from } from '@pylonts/dsl';
 
 // 输入：新增订单
-buildInput('OrderAddRequest', { ...from(order, [order.fields.merchant_id, order.fields.amount]) });
+buildInput('OrderAddRequest', { ...from(order, [order.fields.mer_id, order.fields.amount]) });
 
 // 输出：订单行
 buildOutput('OrderRow', from(order, [order.fields.id, order.fields.order_no]));
@@ -23,7 +23,7 @@ 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]),
+  ...from(order, [order.fields.mer_id]),
 });
 
 // 主键：按 id 取详情
@@ -52,3 +52,9 @@ buildQuery('OrderPageQuery', { ... })
 - **字段两层名**：`DtoField.name` 是接口字段名（DTO map key 反写）；`field.name` 是数据库列名（表反写）。
 - **可选性优先级**：DTO 层 `optional` 优先于字段层；query 方向所有字段强制可选。
 - **HTTP 传 string**：bigint / decimal / date / time 在接口层渲染为 `Type.String()`，保证精度与序列化语义。
+
+## 文件组织
+
+- `dto_schema/{module}/*.dto.ts`：DTO 源文件，一个文件可导出多个 DtoMessage；`module` = `project.config.ts` 的 `apps.name`，另加 `common/` 放跨 app 共享 DTO。
+- `gen-cli dto` 按 module 逐个扫描：`dto_schema/{module}/*.dto.ts` → 生成 `dto/{module}/{Name}.dto.ts`。
+- 枚举字段引用 `enums/` 下生成的枚举源文件，DTO 文件通过 `../../enums/{JsName}.enum` 导入。

package/docs/table.md

@@ -51,16 +51,23 @@ indexes: [
 
 ## 外键与短语检查链
 
+短语统一定义在 `schema/_dictionary.ts`（见 [dictionary.md](./dictionary.md)），表文件从那里 import：
+
 ```ts
+// schema/_dictionary.ts
 import { definePhrase } from '@pylonts/dsl';
 
-const BD = definePhrase({ label: 'BD推广员', description: '线下拓展商户的推广人员' });
+const bd = definePhrase({ name: 'bd', label: 'BD推广员', description: '线下拓展商户的推广人员' });
+```
+
+```ts
+import { bd } from './_dictionary';
 
 const bdId = bigintField({ readOnly: true, label: 'BD ID' });
 
 export const bd = defineTable('bd', {
   description: 'BD',
-  phrase: BD,            // 链接词典条目：本表归属的实体
+  phrase: bd,            // 链接词典条目：本表归属的实体
   fields: { id: bdId },
   primaryKey: bdId,
 });
@@ -70,7 +77,7 @@ const auditBdId = bigintField({ label: 'BD' });
 export const audit = defineTable('audit', {
   description: '审核',
   fields: {
-    bd_id: auditBdId,    // 列名必须 = phrase.name + '_' + 被引用字段名
+    bd_id: auditBdId,    // 列名必须 = 短语 + '_' + 被引用字段名
   },
   foreignKeys: {
     bd_bd_id: { fields: auditBdId, references: bdId },
@@ -80,6 +87,8 @@ export const audit = defineTable('audit', {
 
 **规则（defineTable 时强制检查）**：外键字段名必须等于 `被引用表.phrase.name + "_" + 被引用字段名`。即引用 `bd.id` 的字段必须叫 `bd_id`——`bd` 来自词典（权威短语），`id` 是 `bd` 表主键。
 
+**短语口径**：`definePhrase` 解释的**就是短语本身**——`name` 即短语词干（如 `mer`），不是实体全名。引用 `merchant` 实体的字段用短语 `mer`（`mer_id`），**不用长语**（`merchant_id`）。短语要短（mer / bd / amt 三字母左右），语义由 `label`/`description` 解释。
+
 - 被引用表未定义 `phrase` → 抛错（检查链要求每个被引用表都有短语）。
 - 命名不匹配 → 抛错并提示期望名，例如：
   `foreign key bad: field must be named bd_id (phrase bd + id), got merchant_id`

package/package.json

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

package/src/dictionary.ts

@@ -9,7 +9,12 @@ export interface DictionaryEntry extends SchemaBase {
   label?: string;
 }
 
-/** Creates a phrase entry. */
+/**
+ * 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;
 }

package/src/typebox-driver.ts

@@ -1,141 +1,141 @@
-import { DtoArrayField, DtoField, DtoMessage, DtoObjectField, ImportRef } from './dto';
-import { Field } from './dsl';
-
-// TypeBox driver: renders a DtoMessage into TypeBox TypeScript source.
-// Shape matches the codegen product consumed by fastify v5 TypeBoxTypeProvider:
-//
-//   export const RegisterUserInput = Type.Object({...});
-//   export type RegisterUserInput = Static<typeof RegisterUserInput>;
-//
-// ENUM fields reference a generated enum (see enum-driver) by its import
-// location — the resolver maps a jsName to its product import.
-// DTO bases (.include()) render as Type.Intersect([...bases, Type.Object({...})]).
-
-export type EnumResolver = (enumName: string) => ImportRef | undefined;
-
-function renderString(s: string): string {
-  return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
-}
-
-function renderBasic(field: Field, pattern: string | undefined, resolver: EnumResolver | undefined): string {
-  if (pattern !== undefined && field.type !== 'string') {
-    throw new Error(`pattern is only supported on string fields, got ${field.type} (${field.name})`);
-  }
-  switch (field.type) {
-    case 'string': {
-      const opts: string[] = [];
-      if (field.minLength !== undefined) opts.push(`minLength: ${field.minLength}`);
-      if (field.maxLength !== undefined) opts.push(`maxLength: ${field.maxLength}`);
-      if (pattern !== undefined) opts.push(`pattern: ${renderString(pattern)}`);
-      return opts.length > 0 ? `Type.String({ ${opts.join(', ')} })` : 'Type.String()';
-    }
-    case 'text':
-      return 'Type.String()';
-    case 'integer': {
-      const opts: string[] = [];
-      if (field.min !== undefined) opts.push(`minimum: ${field.min}`);
-      if (field.max !== undefined) opts.push(`maximum: ${field.max}`);
-      return opts.length > 0 ? `Type.Integer({ ${opts.join(', ')} })` : 'Type.Integer()';
-    }
-    case 'bigint':
-    case 'decimal':
-    case 'time':
-    case 'date':
-    case 'datetime':
-      // Transmitted as string over HTTP: bigint/decimal keep full precision,
-      // date/time serialize to string.
-      return 'Type.String()';
-    case 'boolean':
-      return 'Type.Boolean()';
-    case 'json':
-      return 'Type.Unknown()';
-    case 'enum': {
-      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:
-      // Field union is exhaustive; this branch is unreachable at runtime.
-      throw new Error(`unsupported field type: ${String((field as Field).type)}`);
-  }
-}
-
-function renderObject(fields: Record<string, DtoField>, indent: number, resolver: EnumResolver | undefined): string {
-  const pad = '  '.repeat(indent);
-  const entries = Object.entries(fields).map(([name, f]) => `${pad}${name}: ${renderField(f, indent, resolver)}`);
-  return `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
-}
-
-function renderField(f: DtoField, indent: number, resolver: EnumResolver | undefined): string {
-  const base = renderValue(f, indent, resolver);
-  return f.isOptional() ? `Type.Optional(${base})` : base;
-}
-
-function renderValue(f: DtoField, indent: number, resolver: EnumResolver | undefined): string {
-  if (f instanceof DtoArrayField) {
-    return `Type.Array(${renderField(f.items(), indent + 1, resolver)})`;
-  }
-  if (f instanceof DtoObjectField) {
-    return renderObject(f.properties(), indent + 1, resolver);
-  }
-  // DtoField only wraps a database Field; array/object defs live in the subclasses.
-  return renderBasic(f.field as Field, f.pattern, resolver);
-}
-
-function collectEnumImports(
-  f: DtoField,
-  resolver: EnumResolver | undefined,
-  out: Map<string, ImportRef>,
-): void {
-  if (f instanceof DtoArrayField) {
-    collectEnumImports(f.items(), resolver, out);
-    return;
-  }
-  if (f instanceof DtoObjectField) {
-    for (const child of Object.values(f.properties())) collectEnumImports(child, resolver, out);
-    return;
-  }
-  if (f.field.type === 'enum') {
-    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);
-  }
-}
-
-export function renderDtoMessage(
-  schema: DtoMessage,
-  options: { resolver?: EnumResolver; source?: string } = {},
-): string {
-  const { resolver, source } = options;
-  const imports = new Map<string, ImportRef>();
-  for (const base of schema.bases ?? []) imports.set(`${base.from}#${base.name}`, base);
-  for (const f of Object.values(schema.fields)) collectEnumImports(f, resolver, imports);
-
-  const header = [
-    '// 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}';`),
-  ];
-
-  const object = renderObject(schema.fields, 1, resolver);
-  const bases = schema.bases ?? [];
-  const body =
-    bases.length > 0
-      ? `Type.Intersect([${bases.map(renderBase).join(', ')}, ${object}])`
-      : object;
-
-  return [
-    ...header,
-    '',
-    `export const ${schema.name} = ${body};`,
-    `export type ${schema.name} = Static<typeof ${schema.name}>;`,
-    '',
-  ].join('\n');
-}
-
-function renderBase(base: ImportRef): string {
-  return base.args !== undefined && base.args.length > 0
-    ? `${base.name}(${base.args.join(', ')})`
-    : base.name;
+import { DtoArrayField, DtoField, DtoMessage, DtoObjectField, ImportRef } from './dto';
+import { Field } from './dsl';
+
+// TypeBox driver: renders a DtoMessage into TypeBox TypeScript source.
+// Shape matches the codegen product consumed by fastify v5 TypeBoxTypeProvider:
+//
+//   export const RegisterUserInput = Type.Object({...});
+//   export type RegisterUserInput = Static<typeof RegisterUserInput>;
+//
+// ENUM fields reference a generated enum (see enum-driver) by its import
+// location — the resolver maps a jsName to its product import.
+// DTO bases (.include()) render as Type.Intersect([...bases, Type.Object({...})]).
+
+export type EnumResolver = (enumName: string) => ImportRef | undefined;
+
+function renderString(s: string): string {
+  return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+
+function renderBasic(field: Field, pattern: string | undefined, resolver: EnumResolver | undefined): string {
+  if (pattern !== undefined && field.type !== 'string') {
+    throw new Error(`pattern is only supported on string fields, got ${field.type} (${field.name})`);
+  }
+  switch (field.type) {
+    case 'string': {
+      const opts: string[] = [];
+      if (field.minLength !== undefined) opts.push(`minLength: ${field.minLength}`);
+      if (field.maxLength !== undefined) opts.push(`maxLength: ${field.maxLength}`);
+      if (pattern !== undefined) opts.push(`pattern: ${renderString(pattern)}`);
+      return opts.length > 0 ? `Type.String({ ${opts.join(', ')} })` : 'Type.String()';
+    }
+    case 'text':
+      return 'Type.String()';
+    case 'integer': {
+      const opts: string[] = [];
+      if (field.min !== undefined) opts.push(`minimum: ${field.min}`);
+      if (field.max !== undefined) opts.push(`maximum: ${field.max}`);
+      return opts.length > 0 ? `Type.Integer({ ${opts.join(', ')} })` : 'Type.Integer()';
+    }
+    case 'bigint':
+    case 'decimal':
+    case 'time':
+    case 'date':
+    case 'datetime':
+      // Transmitted as string over HTTP: bigint/decimal keep full precision,
+      // date/time serialize to string.
+      return 'Type.String()';
+    case 'boolean':
+      return 'Type.Boolean()';
+    case 'json':
+      return 'Type.Unknown()';
+    case 'enum': {
+      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:
+      // Field union is exhaustive; this branch is unreachable at runtime.
+      throw new Error(`unsupported field type: ${String((field as Field).type)}`);
+  }
+}
+
+function renderObject(fields: Record<string, DtoField>, indent: number, resolver: EnumResolver | undefined): string {
+  const pad = '  '.repeat(indent);
+  const entries = Object.entries(fields).map(([name, f]) => `${pad}${name}: ${renderField(f, indent, resolver)}`);
+  return `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
+}
+
+function renderField(f: DtoField, indent: number, resolver: EnumResolver | undefined): string {
+  const base = renderValue(f, indent, resolver);
+  return f.isOptional() ? `Type.Optional(${base})` : base;
+}
+
+function renderValue(f: DtoField, indent: number, resolver: EnumResolver | undefined): string {
+  if (f instanceof DtoArrayField) {
+    return `Type.Array(${renderField(f.items(), indent + 1, resolver)})`;
+  }
+  if (f instanceof DtoObjectField) {
+    return renderObject(f.properties(), indent + 1, resolver);
+  }
+  // DtoField only wraps a database Field; array/object defs live in the subclasses.
+  return renderBasic(f.field as Field, f.pattern, resolver);
+}
+
+function collectEnumImports(
+  f: DtoField,
+  resolver: EnumResolver | undefined,
+  out: Map<string, ImportRef>,
+): void {
+  if (f instanceof DtoArrayField) {
+    collectEnumImports(f.items(), resolver, out);
+    return;
+  }
+  if (f instanceof DtoObjectField) {
+    for (const child of Object.values(f.properties())) collectEnumImports(child, resolver, out);
+    return;
+  }
+  if (f.field.type === 'enum') {
+    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);
+  }
+}
+
+export function renderDtoMessage(
+  schema: DtoMessage,
+  options: { resolver?: EnumResolver; source?: string } = {},
+): string {
+  const { resolver, source } = options;
+  const imports = new Map<string, ImportRef>();
+  for (const base of schema.bases ?? []) imports.set(`${base.from}#${base.name}`, base);
+  for (const f of Object.values(schema.fields)) collectEnumImports(f, resolver, imports);
+
+  const header = [
+    '// 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}';`),
+  ];
+
+  const object = renderObject(schema.fields, 1, resolver);
+  const bases = schema.bases ?? [];
+  const body =
+    bases.length > 0
+      ? `Type.Intersect([${bases.map(renderBase).join(', ')}, ${object}])`
+      : object;
+
+  return [
+    ...header,
+    '',
+    `export const ${schema.name} = ${body};`,
+    `export type ${schema.name} = Static<typeof ${schema.name}>;`,
+    '',
+  ].join('\n');
+}
+
+function renderBase(base: ImportRef): string {
+  return base.args !== undefined && base.args.length > 0
+    ? `${base.name}(${base.args.join(', ')})`
+    : base.name;
 }