@pylonts/dsl 1.0.2 → 1.0.4

package/dist/utils.js

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

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

@@ -1,13 +1,13 @@
 # 定义 DTO（四种方向）
 
-DTO 描述接口出入参。方向决定语义与可选性规则：
+DTO 描述接口出入参。方向决定可选性规则，由各方向工厂设置；**规则统一只在 `field.optional === undefined` 时生效**（作者已显式设置的跳过）：
 
-| 构建器 | 方向 | 用途 |
+| 构建器 | 方向 | 可选性规则 |
 |---|---|---|
-| `buildInput` | input | 新增/修改请求体 |
-| `buildOutput` | output | 响应体 |
-| `buildQuery` | query | 分页 + 过滤查询（字段恒为可选） |
-| `buildPk` | pk | 按主键取详情 |
+| `buildInput` | input | 按 DB 列规则：可空 / 有默认 / 自增列 → 可选；NOT NULL 无默认 → 必填 |
+| `buildOutput` | output | 不设置（保持字段构建器/作者设置） |
+| `buildQuery` | query | 全部可选 |
+| `buildPk` | pk | 主键字段必填，其他字段可选 |
 
 ## 从表提取字段
 
@@ -15,31 +15,38 @@ 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]));
 
 // 查询：分页 + 过滤（query 字段恒为可选，.op() 声明比较操作符）
 buildQuery('OrderPageQuery', {
-  keyword: dtoField(stringField({ maxLength: 32 })).op('like'),
-  ...from(order, [order.fields.merchant_id]),
+  keyword: dtoField(stringField({ maxLength: 32 })).setOperator('like'),
+  ...from(order, [order.fields.mer_id]),
 });
 
 // 主键：按 id 取详情
 buildPk('OrderDetailRequest', from(order, [order.fields.id]));
 ```
 
-`from(table, fields)` 提取表字段包装为 DTO 字段，字段实例与表共享，`name/schema` 保持指向表。
+`from(table, fields)` 提取表字段包装为 DTO 字段，字段实例与表共享，`name/schema` 保持指向表。**DTO 字段名转 camelCase**（`mer_id` → `merId`），与 DB 列名（snake_case）分离。`from()` 本身不做任何可选性推断——推断在各方向工厂。
 
 ## 独立字段
 
-不来自表的内联字段直接用 `dtoField(...)` 包装任意字段构建器，可加 `pattern`、`optional`、`operator`。
+不来自表的内联字段直接用 `dtoField(...)` 包装任意字段构建器，可加 `pattern`、`optional`、`operator`、`default`。
 
 ```ts
-dtoField(stringField({ maxLength: 32 })).op('like')
+dtoField(stringField({ maxLength: 32 })).setOperator('like')
+dtoField(intField()).setDefault(0)        // TypeBox default 注解
 ```
 
+## 默认值
+
+- `setDefault(v)` 设 DTO 层默认值，渲染为 TypeBox `default:` 注解（`Type.String({ default: 'PENDING' })`、`Type.Enum(OrderStatus, { default: OrderStatus.PENDING })`）。
+- 枚举默认值必须是该枚举的成员值（value），渲染时解析为成员引用；非成员值直接报错。
+- 未显式设置时，fallback 到字段构建器的 `default`（DB 默认值，string），`from()` 提取的字段自动带出。
+
 ## 继承基础 schema
 
 ```ts
@@ -52,3 +59,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.4",
   "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/dsl.ts

@@ -8,17 +8,24 @@ export interface SchemaBase {
   description?: string;
 }
 
+/** Field collection schemas (DB table vs DTO message); `type` is the discriminator */
+export interface CollectionSchemaBase extends SchemaBase {
+  type: string;
+}
+
 export interface BaseField {
   name: string;
   /** 显示名称（中文标签） */
   label?: string;
   /** 字段描述 */
   description?: string;
+  /** 业务语义码（如 'merchant_name'），驱动 mock 生成等下游消费 */
+  semantic?: string;
   optional?: boolean;
   readOnly?: boolean;
   default?: string;
   /** 所属 schema（db 或 dto） */
-  schema?: SchemaBase;
+  schema?: CollectionSchemaBase;
 }
 
 interface StringField extends BaseField {
@@ -132,7 +139,24 @@ export type ForeignKey = {
   references: Field | Field[];
 };
 
-export interface TableSchema extends SchemaBase {
+export interface TableSchemaOptions {
+  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>;
+}
+
+export class TableSchema implements CollectionSchemaBase {
+  type = 'table';
+  name: string;
+  description?: string;
   /** 分页 */
   paginated?: boolean;
   /** 系统操作者（如小程序为 C 端用户，管理端为运营） */
@@ -148,6 +172,28 @@ export interface TableSchema extends SchemaBase {
   /** 引用的实体短语（词典条目）：本表归属的实体；关联表等多实体场景不需要 */
   phrase?: DictionaryEntry;
   fields: Record<string, Field>;
+
+  constructor(name: string, options: TableSchemaOptions) {
+    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.phrase = options.phrase;
+    this.fields = options.fields;
+  }
+
+  /** 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;
+  }
 }
 
 // Field builders: type and jsType are fixed, pass extra properties only.
@@ -200,23 +246,8 @@ export function enumField(extra: Omit<EnumField, 'name' | 'type' | 'jsType'>): E
   return { name: '', type: 'enum', jsType, ...extra };
 }
 
-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 };
+export function defineTable(name: string, schema: TableSchemaOptions): TableSchema {
+  const table = new TableSchema(name, schema);
   for (const key of Object.keys(table.fields)) {
     const field = table.fields[key];
     if (field.schema && field.schema !== table) {

package/src/dto.ts

@@ -1,4 +1,5 @@
-import { BaseField, Field, SchemaBase, TableSchema } from './dsl';
+import { BaseField, CollectionSchemaBase, Field, SchemaBase, TableSchema } from './dsl';
+import { toCamelCase } from './utils';
 
 // Interface (DTO) field definitions.
 // Naming convention: all DTO types and builders use the Dto prefix.
@@ -16,18 +17,15 @@ export interface ImportRef {
   from: string;
   /** Named export, e.g. 'PageRequest' */
   name: string;
-  /** Generic type arguments for the base schema (same-file DTO export names), e.g. PageResult(AdvertRow) */
-  args?: string[];
+  /**
+   * Generic type arguments for the base schema (e.g. PageResult(OrderRow)).
+   * Two forms, both local DTOs:
+   *   string     — the DTO export name
+   *   DtoMessage — the DTO instance itself; the driver resolves it to its name
+   */
+  args?: (string | DtoMessage)[];
 }
 
-export type DtoExtras = {
-  pattern?: string;
-  /** 联合判断是否可选，定义后优先级高于 field.optional */
-  optional?: boolean;
-  /** 查询比较操作符（query 方向字段） */
-  operator?: Operator;
-};
-
 export type DtoArrayFieldDef = BaseField & {
   type: 'array';
   jsType: 'array';
@@ -40,23 +38,24 @@ export type DtoObjectFieldDef = BaseField & {
   properties: Record<string, DtoField>;
 };
 
-export class DtoField {
+export class DtoField implements SchemaBase {
   /** DTO 语义字段名（接口字段名），与 field.name（数据库列名）含义不同。
    *  构造时未知，由 buildMessage 从 map key 反写。 */
   name: string;
+  /** 字段描述 */
+  description?: string;
   /** 所属 DTO 容器（buildMessage 反写） */
   schema?: DtoMessage;
   field: Field | DtoArrayFieldDef | DtoObjectFieldDef;
   pattern?: string;
   optional?: boolean;
   operator?: Operator;
+  /** TypeBox default annotation (API contract level); falls back to field.default (DB default) */
+  default?: unknown;
 
-  constructor(field: Field | DtoArrayFieldDef | DtoObjectFieldDef, extra: DtoExtras = {}) {
+  constructor(field: Field | DtoArrayFieldDef | DtoObjectFieldDef) {
     this.name = '';
     this.field = field;
-    this.pattern = extra.pattern;
-    this.optional = extra.optional;
-    this.operator = extra.operator;
   }
 
   setPattern(value: string): this {
@@ -64,15 +63,29 @@ export class DtoField {
     return this;
   }
 
+  setDescription(value: string): this {
+    this.description = value;
+    return this;
+  }
+
+  getDescription(): string | undefined {
+    return this.description;
+  }
+
   setOptional(value: boolean): this {
     this.optional = value;
     return this;
   }
 
+  /** Set a default value — emitted as a TypeBox schema default annotation */
+  setDefault(value: unknown): this {
+    this.default = value;
+    return this;
+  }
+
   /** 查询比较操作符（query 方向字段）。Rule B: 查询字段恒为可选 */
-  op(value: Operator): this {
+  setOperator(value: Operator): this {
     this.operator = value;
-    this.optional = true;
     return this;
   }
 
@@ -99,46 +112,55 @@ export class DtoObjectField extends DtoField {
   }
 }
 
-export type DtoDirection = 'input' | 'output' | 'query' | 'pk';
+export enum DtoDirection {
+  Input = 'input',
+  Output = 'output',
+  Query = 'query',
+  Pk = 'pk',
+}
 
-export interface DtoMessage extends SchemaBase {
+export class DtoMessage implements CollectionSchemaBase {
+  type = 'dto';
+  name: string;
+  description?: string;
   /** 方向：输入或输出 */
   direction: DtoDirection;
   fields: Record<string, DtoField>;
   /** TypeBox base schemas to intersect with at generation time (e.g. PageRequest) */
-  bases?: ImportRef[];
+  bases: ImportRef[] = [];
+
+  constructor(name: string, direction: DtoDirection, fields: Record<string, DtoField>, description?: string) {
+    this.name = name;
+    this.direction = direction;
+    this.fields = fields;
+    this.description = description;
+  }
+
   /** 引用已存在的 TypeBox base schema，例如 include({ from: '@pylonts/core', name: 'PageRequest' }) */
-  include(...refs: ImportRef[]): DtoMessage;
+  include(...refs: ImportRef[]): this {
+    this.bases.push(...refs);
+    return this;
+  }
 }
 
-export function dtoField(field: Field, extra: DtoExtras = {}): DtoField {
-  return new DtoField(field, extra);
+export function dtoField(field: Field): DtoField {
+  return new DtoField(field);
 }
 
-export function dtoArrayField(def: { items: DtoField } & Omit<BaseField, 'name'>, extra: DtoExtras = {}): DtoArrayField {
-  return new DtoArrayField({ name: '', type: 'array', jsType: 'array', ...def }, extra);
+export function dtoArrayField(def: { items: DtoField | DtoMessage } & Omit<BaseField, 'name'>): DtoArrayField {
+  // Reuse an existing DTO as the array element: expand its fields into an object.
+  const items = def.items instanceof DtoMessage
+    ? new DtoObjectField({ name: '', type: 'object', jsType: 'object', properties: def.items.fields })
+    : def.items;
+  return new DtoArrayField({ name: '', type: 'array', jsType: 'array', ...def, items });
 }
 
-export function dtoObjectField(def: { properties: Record<string, DtoField> } & Omit<BaseField, 'name'>, extra: DtoExtras = {}): DtoObjectField {
-  return new DtoObjectField({ name: '', type: 'object', jsType: 'object', ...def }, extra);
+export function dtoObjectField(def: { properties: Record<string, DtoField> } & Omit<BaseField, 'name'>): DtoObjectField {
+  return new DtoObjectField({ name: '', type: 'object', jsType: 'object', ...def });
 }
 
 function buildMessage(name: string, direction: DtoDirection, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  const message: DtoMessage = {
-    name,
-    direction,
-    description,
-    fields,
-    bases: [],
-    include(...refs: ImportRef[]): DtoMessage {
-      this.bases!.push(...refs);
-      return this;
-    },
-  };
-  if (direction === 'query') {
-    // Rule B: query/search fields are always optional.
-    for (const field of Object.values(message.fields)) field.optional = true;
-  }
+  const message = new DtoMessage(name, direction, fields, description);
   // Write back the DTO field name from the map key (safe: DtoField instances
   // are created per DTO, never shared).
   for (const key of Object.keys(message.fields)) {
@@ -157,19 +179,40 @@ function buildMessage(name: string, direction: DtoDirection, fields: Record<stri
 }
 
 export function buildInput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  return buildMessage(name, 'input', fields, description);
+  const message = buildMessage(name, DtoDirection.Input, fields, description);
+  // Rule A — set optionality from the DB column rule (skips fields the author
+  // already set): nullable / default / auto-increment → optional, else required.
+  for (const field of Object.values(message.fields)) {
+    if (field.optional !== undefined) continue;
+    const f = field.field as Field;
+    if (f.schema?.type !== 'table') continue;
+    const table = f.schema as TableSchema;
+    field.optional = f.optional !== false || f.default !== undefined || table.autoIncrement === f;
+  }
+  return message;
 }
 
 export function buildOutput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  return buildMessage(name, 'output', fields, description);
+  return buildMessage(name, DtoDirection.Output, fields, description);
 }
 
 export function buildQuery(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  return buildMessage(name, 'query', fields, description);
+  const message = buildMessage(name, DtoDirection.Query, fields, description);
+  // Rule B: query/search fields are always optional.
+  for (const field of Object.values(message.fields)) field.optional = true;
+  return message;
 }
 
 export function buildPk(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage {
-  return buildMessage(name, 'pk', fields, description);
+  const message = buildMessage(name, DtoDirection.Pk, fields, description);
+  // Rule P: PK locator fields are required, other fields are optional.
+  for (const field of Object.values(message.fields)) {
+    if (field.optional !== undefined) continue;
+    const f = field.field as Field;
+    const table = f.schema as TableSchema | undefined;
+    field.optional = table !== undefined && table.isPk(f) ? false : true;
+  }
+  return message;
 }
 
 /** Pick columns from a built table and wrap them as DTO fields (aligned with dto.from). */
@@ -179,7 +222,9 @@ export function from(table: TableSchema, fields: Field[]): Record<string, DtoFie
     if (field.schema !== table) {
       throw new Error(`dto.from(${table.name}): field ${field.name} does not belong to this table`);
     }
-    out[field.name] = dtoField(field);
+    // DTO field name is camelCase (mer_id → merId); the underlying field.name
+    // stays snake_case (DB column).
+    out[toCamelCase(field.name)] = dtoField(field);
   }
   return out;
 }

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './dsl';
 export * from './dto';
+export * from './utils';
 export * from './project';
 export * from './prototype';
 export * from './dictionary';

package/src/mermaid-driver.ts

@@ -53,9 +53,12 @@ export function renderPageFlowMermaid(schema: PageFlow): string {
 
   const byApp = new Map<string, Page[]>();
   for (const p of schema.pages) {
-    const list = byApp.get(p.app.name) ?? [];
-    list.push(p);
-    byApp.set(p.app.name, list);
+    const list = byApp.get(p.app.name);
+    if (!list) {
+      byApp.set(p.app.name, [p]);
+    } else {
+      list.push(p);
+    }
   }
 
   let appIdx = 0;