@pylonts/dsl 1.0.1 → 1.0.2

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.1",
+  "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

@@ -1,63 +1,15 @@
 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.
+// means and what it is called.
 
-/** 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 });
+/** A vocabulary entry. */
+export interface DictionaryEntry extends SchemaBase {
+  /** Display label (Chinese) for the term. */
+  label?: string;
 }
 
-/**
- * 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;
+/** Creates a phrase entry. */
+export function definePhrase(extra: DictionaryEntry): DictionaryEntry {
+  return extra;
 }

package/src/dsl.ts

@@ -211,6 +211,8 @@ export function defineTable(
     primaryKey?: Field | Field[];
     indexes?: Index[];
     foreignKeys?: Record<string, ForeignKey>;
+    /** 引用的实体短语（词典条目） */
+    phrase?: DictionaryEntry;
     fields: Record<string, Field>;
   },
 ): TableSchema {

package/src/flow.ts

@@ -0,0 +1,104 @@
+import { SchemaBase } from './dsl';
+
+// Flow model: nodes and edges are separate entities. A FlowNode is a plain
+// named step; a FlowEdge references its start/end node objects directly (no
+// ids). Because a node object may appear in many edges, the graph can share
+// nodes, merge branches, and form cycles (e.g. poll-and-retry loops).
+
+export interface FlowNode extends SchemaBase {
+  /** Optional sub-flow. When present, entering this node runs the sub-flow;
+   *  after the sub-flow reaches any terminal node, the outer flow continues
+   *  via this node's outgoing edges. Sub-flows nest recursively. */
+  flow?: FlowSchema;
+}
+
+export interface FlowEdge extends SchemaBase {
+  /** Trigger condition; undefined = default path (success/normal). */
+  when?: string;
+  start: FlowNode;
+  end: FlowNode;
+}
+
+export interface FlowSchema extends SchemaBase {
+  /** Entry node. */
+  start: FlowNode;
+  /** All nodes, collected from edges (deduplicated by object identity). */
+  nodes: FlowNode[];
+  /** Independent edges; a node may be start of many edges, so cycles are expressible. */
+  edges: FlowEdge[];
+}
+
+export function node(name: string, flow?: FlowSchema, description?: string): FlowNode {
+  return { name, flow, description };
+}
+
+export function edge(start: FlowNode, end: FlowNode, when?: string, description?: string): FlowEdge {
+  // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
+  return { name: `${start.name}->${end.name}`, start, end, when, description };
+}
+
+export function defineFlow(
+  name: string,
+  schema: {
+    start: FlowNode;
+    edges: FlowEdge[];
+    description?: string;
+  },
+): FlowSchema {
+  const seen = new Set<FlowNode>();
+  const nodes: FlowNode[] = [];
+  for (const e of schema.edges) {
+    for (const n of [e.start, e.end]) {
+      if (!seen.has(n)) {
+        seen.add(n);
+        nodes.push(n);
+      }
+    }
+  }
+  if (!seen.has(schema.start)) {
+    seen.add(schema.start);
+    nodes.push(schema.start);
+  }
+  const flow: FlowSchema = { name, description: schema.description, start: schema.start, nodes, edges: schema.edges };
+  validate(flow);
+  return flow;
+}
+
+// Nodes that never appear as an edge start are terminals. Reverse BFS from all
+// terminals marks every node that can reach a terminal; unmarked nodes sit on
+// a path that never ends (e.g. a cycle without an exit) — reject them at
+// definition time.
+function validate(schema: FlowSchema): void {
+  const starts = new Set<FlowNode>();
+  for (const e of schema.edges) starts.add(e.start);
+
+  const reverse = new Map<FlowNode, FlowNode[]>();
+  for (const n of schema.nodes) reverse.set(n, []);
+  for (const e of schema.edges) {
+    reverse.get(e.end)!.push(e.start);
+  }
+
+  const reached = new Set<FlowNode>();
+  const queue: FlowNode[] = [];
+  for (const n of schema.nodes) {
+    if (!starts.has(n)) {
+      reached.add(n);
+      queue.push(n);
+    }
+  }
+  while (queue.length > 0) {
+    const cur = queue.shift()!;
+    for (const prev of reverse.get(cur)!) {
+      if (!reached.has(prev)) {
+        reached.add(prev);
+        queue.push(prev);
+      }
+    }
+  }
+
+  for (const n of schema.nodes) {
+    if (!reached.has(n)) {
+      throw new Error(`flow ${schema.name}: node "${n.name}" cannot reach a terminal`);
+    }
+  }
+}

package/src/index.ts

@@ -5,4 +5,10 @@ export * from './prototype';
 export * from './dictionary';
 export * from './mysql-driver';
 export * from './enum-driver';
-export * from './typebox-driver';
+export * from './typebox-driver';
+export * from './pattern';
+export * from './patterns/retry';
+export * from './flow';
+export * from './page';
+export * from './page-flow';
+export * from './mermaid-driver';

package/src/mermaid-driver.ts

@@ -0,0 +1,81 @@
+import { FlowEdge, FlowNode, FlowSchema } from './flow';
+import { Page } from './page';
+import { PageEdge, PageFlow } from './page-flow';
+
+// Mermaid driver: converts a FlowSchema into a Mermaid flowchart (TD).
+// Node ids are hierarchical (n0, n0_0, n0_0_0, ...) so nested sub-flows stay
+// globally unique. A node with a sub-flow renders as a subgraph block whose
+// internals are rendered recursively. ok edges render as -->, conditional
+// edges render as -->|"WHEN"|.
+
+function escapeLabel(s: string): string {
+  return s.replace(/"/g, '\\"').replace(/\n/g, '<br/>');
+}
+
+export function renderFlowMermaid(schema: FlowSchema): string {
+  const lines: string[] = ['flowchart TD'];
+  const ids = new Map<FlowNode, string>();
+  renderFlow(schema, 'n', lines, ids);
+  lines.push('');
+  lines.push('    classDef start fill:#e6f4ea,stroke:#333,stroke-width:1px;');
+  lines.push(`    class ${ids.get(schema.start)} start;`);
+  return lines.join('\n');
+}
+
+function renderFlow(schema: FlowSchema, prefix: string, lines: string[], ids: Map<FlowNode, string>): void {
+  schema.nodes.forEach((n, i) => ids.set(n, `${prefix}${i}`));
+  for (const n of schema.nodes) {
+    const id = ids.get(n)!;
+    if (n.flow) {
+      lines.push(`    subgraph ${id}["${escapeLabel(n.name)}"]`);
+      renderFlow(n.flow, `${id}_`, lines, ids);
+      lines.push('    end');
+    } else {
+      lines.push(`    ${id}["${escapeLabel(n.name)}"]`);
+    }
+  }
+  for (const e of schema.edges) {
+    lines.push(renderEdge(e, ids));
+  }
+}
+
+function renderEdge(e: FlowEdge, ids: Map<FlowNode, string>): string {
+  const label = e.when ? `|"${escapeLabel(e.when)}"|` : '';
+  return `    ${ids.get(e.start)} -->${label} ${ids.get(e.end)}`;
+}
+
+// Page-driven flow renderer: groups pages by their app into swimlane
+// subgraphs, then renders edges across the whole flow.
+
+export function renderPageFlowMermaid(schema: PageFlow): string {
+  const lines: string[] = ['flowchart TD'];
+  const ids = new Map<Page, 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);
+  }
+
+  let appIdx = 0;
+  for (const [appName, pages] of byApp) {
+    lines.push(`    subgraph app${appIdx}["${escapeLabel(appName)}"]`);
+    pages.forEach((p, i) => ids.set(p, `app${appIdx}_p${i}`));
+    for (const p of pages) {
+      lines.push(`    ${ids.get(p)}["${escapeLabel(p.name)}"]`);
+    }
+    appIdx++;
+    lines.push('    end');
+  }
+
+  for (const e of schema.edges) {
+    const label = e.when ? `|"${escapeLabel(e.when.name)}"|` : '';
+    lines.push(`    ${ids.get(e.start)} -->${label} ${ids.get(e.end)}`);
+  }
+
+  lines.push('');
+  lines.push('    classDef start fill:#e6f4ea,stroke:#333,stroke-width:1px;');
+  lines.push(`    class ${ids.get(schema.start)} start;`);
+  return lines.join('\n');
+}

package/src/page-flow.ts

@@ -0,0 +1,52 @@
+import { SchemaBase } from './dsl';
+import { ActionSchema, Page } from './page';
+
+// Page-driven flow: every node is a page, and a page belongs to an app.
+// Leaf nodes are pages too — a journey starts at a page and ends at a page.
+// Page definitions (PageSchema/Page/actions) live in page.ts; this file
+// models the flow graph between pages.
+
+export interface PageEdge extends SchemaBase {
+  /** Trigger action; undefined = default path (success/normal). */
+  when?: ActionSchema;
+  start: Page;
+  end: Page;
+}
+
+export interface PageFlow extends SchemaBase {
+  /** Entry page. */
+  start: Page;
+  /** All pages, collected from edges (deduplicated by object identity). */
+  pages: Page[];
+  edges: PageEdge[];
+}
+
+export function pageEdge(start: Page, end: Page, when?: ActionSchema, description?: string): PageEdge {
+  // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
+  return { name: `${start.name}->${end.name}`, start, end, when, description };
+}
+
+export function definePageFlow(
+  name: string,
+  schema: {
+    start: Page;
+    edges: PageEdge[];
+    description?: string;
+  },
+): PageFlow {
+  const seen = new Set<Page>();
+  const pages: Page[] = [];
+  for (const e of schema.edges) {
+    for (const p of [e.start, e.end]) {
+      if (!seen.has(p)) {
+        seen.add(p);
+        pages.push(p);
+      }
+    }
+  }
+  if (!seen.has(schema.start)) {
+    seen.add(schema.start);
+    pages.push(schema.start);
+  }
+  return { name, description: schema.description, start: schema.start, pages, edges: schema.edges };
+}

package/src/page.ts

@@ -0,0 +1,40 @@
+import { SchemaBase } from './dsl';
+import { FrontApp } from './project';
+
+// Page definitions: standalone page schemas and the page node type used by
+// page-driven flows. Kept separate from page-flow.ts (the flow graph itself).
+
+/** Standalone page definition. A page is a shared value object: it lists
+ *  the actions a user can perform, and belongs to exactly one frontend app. */
+export interface PageSchema extends SchemaBase {
+  /** The frontend app this page belongs to (shared instance from project.config). */
+  app: FrontApp;
+  /** Actions a user can perform on this page (e.g. submit, approve, reject). */
+  actions: ActionSchema[];
+}
+
+/** An action a user can perform on a page (e.g. submit, approve, reject). */
+export interface ActionSchema extends SchemaBase {}
+
+export function defineAction(name: string, description?: string): ActionSchema {
+  return { name, description };
+}
+
+export function definePage(schema: {
+  name: string;
+  description?: string;
+  app: FrontApp;
+  actions: ActionSchema[];
+}): PageSchema {
+  return { ...schema };
+}
+
+/** A page node in a page-driven flow: every node is a page, and a page belongs to an app. */
+export interface Page extends SchemaBase {
+  /** The frontend app this page belongs to (shared instance from project.config). */
+  app: FrontApp;
+}
+
+export function page(app: FrontApp, name: string, description?: string): Page {
+  return { name, app, description };
+}

package/src/pattern.ts

@@ -0,0 +1,27 @@
+// 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.
+
+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 function definePattern(def: PatternDef): PatternDef {
+  return def;
+}
+
+export function ref(name: string, args: Record<string, unknown>): PatternRef {
+  return { ref: name, args };
+}

package/src/patterns/retry.ts

@@ -0,0 +1,55 @@
+import { PatternDef } from '../pattern';
+
+// 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.
+
+export const retryPattern: PatternDef = {
+  name: 'retry',
+  params: {
+    max: { type: 'int', min: 1, default: 3 },
+    backoffMs: { type: 'int', min: 0, default: 0 },
+  },
+};
+
+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 function renderRetry(args: RetryRefArgs): string {
+  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/src/project.ts

@@ -19,11 +19,22 @@ export interface ProjectApi extends SchemaBase {
   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[];
 }
 
 /**
@@ -37,7 +48,8 @@ export function defineProject(
     description?: string;
     apps: FrontApp[];
     apis: ProjectApi[];
+    thirdApis?: ThirdApi[];
   },
 ): ProjectSchema {
-  return { name, ...schema };
+  return { name, ...schema, thirdApis: schema.thirdApis ?? [] };
 }