@pylonts/dsl 1.1.21 → 1.1.22

package/README.md

@@ -7,21 +7,24 @@ Schema 定义与产物生成分离的 DSL 系统：先写 DSL 元数据（表 /
 从概要设计到详细设计的自顶向下链路：
 
 ```
-project（地图：应用与 API 拓扑）
-  → dictionary（词典：命名与数据类型标准）
-    → prototype（概要设计：页面与字段）
-      → table / dto（详细设计）
-        → driver 生成产物（SQL / 枚举 / TypeBox）
+concepts（概念：名词 + 名词解释——先于一切存在的名字层）
+  → project（地图：应用与 API 拓扑）
+    → dictionary（词典：词根与字段命名标准，概念派生）
+      → prototype（概要设计：页面与字段）
+        → table / dto（详细设计）
+          → driver 生成产物（SQL / 枚举 / TypeBox）
 ```
 
 ## 文档
 
+- [concepts.md](./docs/concepts.md) — 概念层（名词 + 名词解释，蓝图的名字层；设计草案）
 - [project.md](./docs/project.md) — 项目拓扑（地图）
 - [dictionary.md](./docs/dictionary.md) — 短语词典（命名标准）
 - [prototype.md](./docs/prototype.md) — 页面原型（概要设计）
 - [table.md](./docs/table.md) — 定义表（详细设计）
 - [dto.md](./docs/dto.md) — 定义 DTO
 - [curd.md](./docs/curd.md) — 管理端 CRUD 页面标准（CurdSchema）
+- [task.md](./docs/task.md) — 系统任务（TaskSchema：scheduled 定时 / async 异步，action 闭包成员）
 - [utils.md](./docs/utils.md) — 工具模块与领域规则（UtilsSchema：防御 guard / 判断 / 计算）
 - [aggregate.md](./docs/aggregate.md) — 聚合/仓储 DSL 扩展规划（声明层已落地：DomainAggregate/RepositorySchema + 存储校验，生成器待选型）
 - [domain-event.md](./docs/domain-event.md) — 领域事件 DSL 扩展规划（声明层已落地：DomainEventSchema + event_schema 存储校验，发布/订阅待实现）

package/dist/action.d.ts

@@ -1,39 +1,82 @@
 import { SchemaBase } from './dsl.js';
-import type { DtoField, DtoMessage, DtoArrayField, DtoObjectField } from './dto.js';
-import type { RefSchema } from './ref.js';
 import type { ControllerMethodSchema } from './controller.js';
-/** An action a user can perform on a page (e.g. submit, approve, reject).
- *  Subclasses use `type` as the discriminator. */
+import type { ThirdServiceMethodSchema, ThirdCallbackSchema } from './third-service.js';
+import type { TaskSchema } from './task.js';
+import type { TableSchema } from './db.js';
+import type { PageSchema } from './page.js';
+/** A beat of a journey: type + properties + input data. */
 export interface ActionSchema extends SchemaBase {
-    type: string;
+    type: 'page' | 'controller' | 'third' | 'db' | 'task';
+    /** Input data of this beat (blueprint: names first, refined to refs later). */
+    data?: Record<string, unknown>;
 }
-export declare function defineAction(name: string, description?: string): ActionSchema;
-/** Parameter data source for a call argument. */
-export type DataRef = {
-    type: 'route';
-    key: string;
-} | {
-    type: 'data';
-    key: string;
-} | {
-    type: 'value';
-    value: unknown;
-};
-/** Create a route-parameter reference. */
-export declare function route(key: string): DataRef;
-/** Create a page-data reference. */
-export declare function data(key: string): DataRef;
-export interface CallAction extends ActionSchema {
-    type: 'call';
-    func: ControllerMethodSchema;
-    args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>;
+/** Visit a page — `data` present means fill/submit a form, absent means pure view. */
+export interface PageAction extends ActionSchema {
+    type: 'page';
+    /** Target page (PageFlow node). */
+    page: PageSchema;
+    /** Page url/path (e.g. '/bd/apply'). */
+    url: string;
+}
+/** Call a backend controller method. */
+export interface ControllerAction extends ActionSchema {
+    type: 'controller';
+    /** The controller method invoked (shared instance). */
+    method: ControllerMethodSchema;
+}
+/** Invoke a third-party service method or receive its callback. */
+export interface ThirdAction extends ActionSchema {
+    type: 'third';
+    /** The third-party method invoked (outbound). */
+    method?: ThirdServiceMethodSchema;
+    /** The third-party callback received (inbound) — mutually exclusive with method. */
+    callback?: ThirdCallbackSchema;
+    /** Wait for the async callback (inbound) before the journey continues. */
+    async?: boolean;
 }
-export declare function call(func: ControllerMethodSchema, args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>): CallAction;
-/** Assign a call's result to a page data field.
- *  React: setState({ [field]: await ... }). Mini-program: this.setData({ [field]: ... }). */
-export interface SetDataAction extends ActionSchema {
-    type: 'setData';
-    call: CallAction;
-    field: DtoField;
+/** Write to a database table. */
+export interface DbAction extends ActionSchema {
+    type: 'db';
+    /** The table written (shared instance). */
+    table: TableSchema;
+    /** Write operation: insert | update | delete. */
+    op: 'insert' | 'update' | 'delete';
 }
-export declare function setData(call: CallAction, field: DtoField): SetDataAction;
+/** Trigger a system task (scheduled or async). */
+export interface TaskAction extends ActionSchema {
+    type: 'task';
+    /** The task triggered (shared instance). */
+    task: TaskSchema;
+}
+/** Builder for a journey action. */
+export declare const action: {
+    page(options: {
+        page: PageSchema;
+        url: string;
+        data?: Record<string, unknown>;
+        description?: string;
+    }): PageAction;
+    controller(options: {
+        method: ControllerMethodSchema;
+        data?: Record<string, unknown>;
+        description?: string;
+    }): ControllerAction;
+    third(options: {
+        method?: ThirdServiceMethodSchema;
+        callback?: ThirdCallbackSchema;
+        data?: Record<string, unknown>;
+        async?: boolean;
+        description?: string;
+    }): ThirdAction;
+    db(options: {
+        table: TableSchema;
+        op: 'insert' | 'update' | 'delete';
+        data?: Record<string, unknown>;
+        description?: string;
+    }): DbAction;
+    task(options: {
+        task: TaskSchema;
+        data?: Record<string, unknown>;
+        description?: string;
+    }): TaskAction;
+};

package/dist/action.js

@@ -1,17 +1,19 @@
-export function defineAction(name, description) {
-    return { name, description, type: 'gesture' };
-}
-/** Create a route-parameter reference. */
-export function route(key) {
-    return { type: 'route', key };
-}
-/** Create a page-data reference. */
-export function data(key) {
-    return { type: 'data', key };
-}
-export function call(func, args) {
-    return { name: func.name, type: 'call', func, args };
-}
-export function setData(call, field) {
-    return { name: 'setData', type: 'setData', call, field };
-}
+/** Builder for a journey action. */
+export const action = {
+    page(options) {
+        return { name: options.page.name, type: 'page', page: options.page, url: options.url, data: options.data, description: options.description };
+    },
+    controller(options) {
+        return { name: options.method.name, type: 'controller', method: options.method, data: options.data, description: options.description };
+    },
+    third(options) {
+        const name = options.method?.name ?? options.callback?.name ?? 'third';
+        return { name, type: 'third', method: options.method, callback: options.callback, data: options.data, async: options.async, description: options.description };
+    },
+    db(options) {
+        return { name: options.table.name, type: 'db', table: options.table, op: options.op, data: options.data, description: options.description };
+    },
+    task(options) {
+        return { name: options.task.name, type: 'task', task: options.task, data: options.data, description: options.description };
+    },
+};

package/dist/component.d.ts

@@ -1,13 +1,13 @@
 import type { SchemaBase } from './dsl.js';
 import type { RefSchema } from './ref.js';
-import type { ActionSchema } from './action.js';
+import type { PageActionSchema } from './page-action.js';
 import type { EventDataSchema } from './event.js';
 /** A component event trigger declaration. */
 export interface TriggerSchema extends SchemaBase {
     /** Data the event carries (e.g. e.detail). */
     eventData?: EventDataSchema;
-    /** Actions that fire when the event occurs. */
-    actions?: ActionSchema[];
+    /** Page actions that fire when the event occurs. */
+    actions?: PageActionSchema[];
 }
 /** A UI component declaration — a virtual schema that describes props and
  *  event triggers, not a real renderable component.

package/dist/curd.d.ts

@@ -1,7 +1,7 @@
 import { SchemaBase, Field } from './dsl.js';
 import { TableSchema } from './db.js';
 import { FrontAppSchema } from './project.js';
-import { ActionSchema } from './action.js';
+import { PageActionSchema } from './page-action.js';
 import type { FilterSchema } from './filter.js';
 /** Mode of an action page: modal dialog or standalone route. */
 export type ActionPageMode = 'modal' | 'route';
@@ -43,7 +43,7 @@ export interface CurdSchema extends SchemaBase {
     /** Sidebar menu section (group) this CRUD page belongs to. */
     section: string;
     /** Extra user actions on this page (beyond the standard CRUD). */
-    actions?: ActionSchema[];
+    actions?: PageActionSchema[];
     /** Add/update/detail action pages. */
     actionPages?: {
         add?: ActionPage;

package/dist/index.d.ts

@@ -16,6 +16,8 @@ export * from './pattern.js';
 export * from './patterns/retry.js';
 export * from './flow.js';
 export * from './action.js';
+export * from './journey.js';
+export * from './page-action.js';
 export * from './event.js';
 export * from './component.js';
 export * from './convert.js';
@@ -31,6 +33,7 @@ export * from './aggregate.js';
 export * from './repository.js';
 export * from './domain-event.js';
 export * from './third-service.js';
+export * from './task.js';
 export * from './token.js';
 export * from './field-rule.js';
 export * from './exception.js';

package/dist/index.js

@@ -16,6 +16,8 @@ export * from './pattern.js';
 export * from './patterns/retry.js';
 export * from './flow.js';
 export * from './action.js';
+export * from './journey.js';
+export * from './page-action.js';
 export * from './event.js';
 export * from './component.js';
 export * from './convert.js';
@@ -31,6 +33,7 @@ export * from './aggregate.js';
 export * from './repository.js';
 export * from './domain-event.js';
 export * from './third-service.js';
+export * from './task.js';
 export * from './token.js';
 export * from './field-rule.js';
 export * from './exception.js';

package/dist/journey.d.ts

@@ -0,0 +1,23 @@
+import { SchemaBase } from './dsl.js';
+import type { ActionSchema } from './action.js';
+/** One business journey: a goal-directed line of actions. */
+export interface JourneySchema extends SchemaBase {
+    /** Chinese title of the journey. */
+    title: string;
+    /** The business goal the journey achieves (what it is for). */
+    goal: string;
+    /** The running list of actions, in business order. */
+    actions: ActionSchema[];
+}
+/**
+ * Defines a business journey. `name` is kebab-case (e.g. 'merchant-onboarding');
+ * the export symbol is the kebab-camel of the name (merchantOnboarding).
+ * File name is the name plus '.journey.ts' (journey_schema/merchant-onboarding.journey.ts).
+ */
+export declare function defineJourney(options: {
+    name: string;
+    title: string;
+    goal: string;
+    actions: ActionSchema[];
+    description?: string;
+}): JourneySchema;

package/dist/journey.js

@@ -0,0 +1,26 @@
+/**
+ * Defines a business journey. `name` is kebab-case (e.g. 'merchant-onboarding');
+ * the export symbol is the kebab-camel of the name (merchantOnboarding).
+ * File name is the name plus '.journey.ts' (journey_schema/merchant-onboarding.journey.ts).
+ */
+export function defineJourney(options) {
+    if (!/^[a-z][a-z0-9-]*$/.test(options.name)) {
+        throw new Error(`journey ${options.name}: name must be kebab-case (lowercase letters/digits/dashes)`);
+    }
+    if (!options.title) {
+        throw new Error(`journey ${options.name}: title is required`);
+    }
+    if (!options.goal) {
+        throw new Error(`journey ${options.name}: goal is required`);
+    }
+    if (!options.actions || options.actions.length === 0) {
+        throw new Error(`journey ${options.name}: actions must be non-empty (a journey is a line of actions)`);
+    }
+    return {
+        name: options.name,
+        title: options.title,
+        goal: options.goal,
+        description: options.description,
+        actions: options.actions,
+    };
+}

package/dist/navigation.d.ts

@@ -1,8 +1,8 @@
 import type { RouteDataSchema } from './route.js';
-import type { ActionSchema } from './action.js';
+import type { PageActionSchema } from './page-action.js';
 import { PageSchema } from './page.js';
 /** Navigation primitives: front-end routing actions that are not provider calls. */
-export interface NavigationAction extends ActionSchema {
+export interface NavigationAction extends PageActionSchema {
     type: 'navigation';
     method: 'back' | 'push' | 'popup' | 'home';
     /** Target page for push navigation. */

package/dist/page-action.d.ts

@@ -0,0 +1,39 @@
+import { SchemaBase } from './dsl.js';
+import type { DtoField, DtoMessage, DtoArrayField, DtoObjectField } from './dto.js';
+import type { RefSchema } from './ref.js';
+import type { ControllerMethodSchema } from './controller.js';
+/** An action a user can perform on a page (e.g. submit, approve, reject).
+ *  Subclasses use `type` as the discriminator. */
+export interface PageActionSchema extends SchemaBase {
+    type: string;
+}
+export declare function definePageAction(name: string, description?: string): PageActionSchema;
+/** Parameter data source for a call argument. */
+export type DataRef = {
+    type: 'route';
+    key: string;
+} | {
+    type: 'data';
+    key: string;
+} | {
+    type: 'value';
+    value: unknown;
+};
+/** Create a route-parameter reference. */
+export declare function route(key: string): DataRef;
+/** Create a page-data reference. */
+export declare function data(key: string): DataRef;
+export interface CallAction extends PageActionSchema {
+    type: 'call';
+    func: ControllerMethodSchema;
+    args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>;
+}
+export declare function call(func: ControllerMethodSchema, args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>): CallAction;
+/** Assign a call's result to a page data field.
+ *  React: setState({ [field]: await ... }). Mini-program: this.setData({ [field]: ... }). */
+export interface SetDataAction extends PageActionSchema {
+    type: 'setData';
+    call: CallAction;
+    field: DtoField;
+}
+export declare function setData(call: CallAction, field: DtoField): SetDataAction;

package/dist/page-action.js

@@ -0,0 +1,17 @@
+export function definePageAction(name, description) {
+    return { name, description, type: 'gesture' };
+}
+/** Create a route-parameter reference. */
+export function route(key) {
+    return { type: 'route', key };
+}
+/** Create a page-data reference. */
+export function data(key) {
+    return { type: 'data', key };
+}
+export function call(func, args) {
+    return { name: func.name, type: 'call', func, args };
+}
+export function setData(call, field) {
+    return { name: 'setData', type: 'setData', call, field };
+}

package/dist/page-def.d.ts

@@ -2,21 +2,21 @@ import type { ImportableSchemaBase, CollectionSchemaBase, SchemaBase } from './d
 import { DtoField } from './dto.js';
 import type { DtoMessage, DtoArrayField, DtoObjectField } from './dto.js';
 import type { ComponentSchema } from './component.js';
-import type { ActionSchema } from './action.js';
+import type { PageActionSchema } from './page-action.js';
 export type { RouteDataSchema } from './route.js';
 export { defineRouteData } from './route.js';
 /** Page lifecycle events that trigger data loading. */
 export interface EventSchema extends SchemaBase {
     type: 'onLoad' | 'onShow' | 'onHide' | 'onPullDownRefresh' | 'onReachBottom';
-    /** Actions that fire when this event occurs. */
-    actions?: ActionSchema[];
+    /** Page actions that fire when this event occurs. */
+    actions?: PageActionSchema[];
 }
 export declare const events: {
-    onLoad(actions?: ActionSchema[], description?: string): EventSchema;
-    onShow(actions?: ActionSchema[], description?: string): EventSchema;
-    onHide(actions?: ActionSchema[], description?: string): EventSchema;
-    onPullDownRefresh(actions?: ActionSchema[], description?: string): EventSchema;
-    onReachBottom(actions?: ActionSchema[], description?: string): EventSchema;
+    onLoad(actions?: PageActionSchema[], description?: string): EventSchema;
+    onShow(actions?: PageActionSchema[], description?: string): EventSchema;
+    onHide(actions?: PageActionSchema[], description?: string): EventSchema;
+    onPullDownRefresh(actions?: PageActionSchema[], description?: string): EventSchema;
+    onReachBottom(actions?: PageActionSchema[], description?: string): EventSchema;
 };
 /** Page data: a named collection of fields that defines the page's data shape. */
 export interface PageDataSchema extends CollectionSchemaBase {
@@ -30,7 +30,7 @@ export interface PageDef extends ImportableSchemaBase {
     /** Lifecycle events that trigger data loading. */
     events: EventSchema[];
     /** Page actions (provider calls, navigation, etc.). */
-    actions: ActionSchema[];
+    actions: PageActionSchema[];
     /** UI component declarations that make up the page skeleton. */
     components: ComponentSchema[];
     /** Whether the driver should generate page-level loading / error / empty state wrappers. */

package/dist/page-flow.d.ts

@@ -1,9 +1,9 @@
 import { SchemaBase } from './dsl.js';
-import type { ActionSchema } from './action.js';
+import type { PageActionSchema } from './page-action.js';
 import { Page } from './page.js';
 export interface PageEdge extends SchemaBase {
-    /** Trigger action; undefined = default path (success/normal). */
-    when?: ActionSchema;
+    /** Trigger page action; undefined = default path (success/normal). */
+    when?: PageActionSchema;
     start: Page;
     end: Page;
 }
@@ -14,7 +14,7 @@ export interface PageFlow extends SchemaBase {
     pages: Page[];
     edges: PageEdge[];
 }
-export declare function pageEdge(start: Page, end: Page, when?: ActionSchema, description?: string): PageEdge;
+export declare function pageEdge(start: Page, end: Page, when?: PageActionSchema, description?: string): PageEdge;
 export declare function definePageFlow(name: string, schema: {
     start: Page;
     pages: Page[];

package/dist/popup.d.ts

@@ -1,13 +1,13 @@
-import type { ActionSchema } from './action.js';
+import type { PageActionSchema } from './page-action.js';
 import type { RefSchema } from './ref.js';
 /** Display a toast notification. React: toast/message UI. Mini-program: wx.showToast. */
-export interface ToastAction extends ActionSchema {
+export interface ToastAction extends PageActionSchema {
     type: 'toast';
     message: string | RefSchema;
     icon?: 'success' | 'error' | 'loading' | 'none';
 }
 /** Display an alert dialog. React: modal. Mini-program: wx.showModal. */
-export interface AlertAction extends ActionSchema {
+export interface AlertAction extends PageActionSchema {
     type: 'alert';
     title: string | RefSchema;
     content: string | RefSchema;

package/dist/task.d.ts

@@ -0,0 +1,20 @@
+import { CollectionSchemaBase } from './dsl.js';
+export interface TaskSchema extends CollectionSchemaBase {
+    type: 'task';
+    /** Display label (Chinese) for the task. */
+    label: string;
+    /** Cron expression — the timer schedule. */
+    cron: string;
+}
+/**
+ * Defines a scheduled task. `name` must end with 'Task' (PascalCase,
+ * e.g. 'AutoRefundTask'); the export symbol equals the name. File name is the
+ * name minus the Task suffix, kebab-cased, plus '.task.ts'
+ * (AutoRefundTask → task_schema/auto-refund.task.ts).
+ */
+export declare function defineTask(options: {
+    name: string;
+    label: string;
+    cron: string;
+    description?: string;
+}): TaskSchema;

package/dist/task.js

@@ -0,0 +1,21 @@
+/**
+ * Defines a scheduled task. `name` must end with 'Task' (PascalCase,
+ * e.g. 'AutoRefundTask'); the export symbol equals the name. File name is the
+ * name minus the Task suffix, kebab-cased, plus '.task.ts'
+ * (AutoRefundTask → task_schema/auto-refund.task.ts).
+ */
+export function defineTask(options) {
+    if (!/(Task)$/.test(options.name)) {
+        throw new Error(`task ${options.name}: name must end with 'Task' (PascalCase, e.g. 'AutoRefundTask')`);
+    }
+    if (!options.cron || options.cron.trim() === '') {
+        throw new Error(`task ${options.name}: cron is required (a task is a timer)`);
+    }
+    return {
+        type: 'task',
+        name: options.name,
+        label: options.label,
+        description: options.description,
+        cron: options.cron,
+    };
+}