@pylonts/dsl 1.0.3 → 1.0.4

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 | 主键字段必填，其他字段可选 |
 
 ## 从表提取字段
 
@@ -22,7 +22,7 @@ buildOutput('OrderRow', from(order, [order.fields.id, order.fields.order_no]));
 
 // 查询：分页 + 过滤（query 字段恒为可选，.op() 声明比较操作符）
 buildQuery('OrderPageQuery', {
-  keyword: dtoField(stringField({ maxLength: 32 })).op('like'),
+  keyword: dtoField(stringField({ maxLength: 32 })).setOperator('like'),
   ...from(order, [order.fields.mer_id]),
 });
 
@@ -30,16 +30,23 @@ buildQuery('OrderPageQuery', {
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonts/dsl",
-  "version": "1.0.3",
+  "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/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;