@nocobase/flow-engine 2.1.0-alpha.10 → 2.1.0-alpha.12

package/lib/types.d.ts

@@ -30,6 +30,221 @@ export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 export type DeepPartial<T> = {
     [P in keyof T]?: T[P] extends (infer U)[] ? DeepPartial<U>[] : T[P] extends Record<string, any> ? DeepPartial<T[P]> : T[P] extends object ? DeepPartial<T[P]> : T[P];
 };
+export type FlowJsonSchema = Record<string, any> & {
+    $schema?: string;
+    $id?: string;
+};
+export interface FlowDynamicHintMetadata {
+    slotRules?: {
+        slotKey?: string;
+        type?: 'object' | 'array';
+        allowedUses?: string[];
+    };
+    contextRequirements?: string[];
+    unresolvedReason?: string;
+    recommendedFallback?: any;
+}
+export interface FlowDynamicHint {
+    kind: 'dynamic-ui-schema' | 'dynamic-children' | 'custom-component' | 'x-reactions' | 'unresolved-action' | 'manual-schema-required' | 'unresolved-model';
+    path?: string;
+    message: string;
+    'x-flow'?: FlowDynamicHintMetadata;
+}
+export interface FlowSchemaCoverage {
+    status: 'auto' | 'manual' | 'mixed' | 'unresolved';
+    source: 'official' | 'plugin' | 'third-party';
+    strict?: boolean;
+    issues?: string[];
+}
+export type FlowModelSchemaExposure = 'public' | 'internal';
+export interface FlowSchemaPattern {
+    title: string;
+    description?: string;
+    snippet?: any;
+}
+export interface FlowSchemaDocument {
+    use: string;
+    title?: string;
+    jsonSchema: FlowJsonSchema;
+    coverage: FlowSchemaCoverage;
+    dynamicHints: FlowDynamicHint[];
+    examples: any[];
+    minimalExample?: any;
+    commonPatterns: FlowSchemaPattern[];
+    antiPatterns: FlowSchemaPattern[];
+    skeleton: any;
+    hash: string;
+    source: FlowSchemaCoverage['source'];
+}
+export type FlowSchemaDetail = 'compact' | 'full';
+export interface FlowSchemaPublicDocument {
+    use: string;
+    title?: string;
+    jsonSchema: FlowJsonSchema;
+    dynamicHints: FlowDynamicHint[];
+    minimalExample?: any;
+    commonPatterns: FlowSchemaPattern[];
+    antiPatterns: FlowSchemaPattern[];
+    hash: string;
+    source: FlowSchemaCoverage['source'];
+}
+export interface FlowSchemaDocs {
+    description?: string;
+    examples?: any[];
+    minimalExample?: any;
+    commonPatterns?: FlowSchemaPattern[];
+    antiPatterns?: FlowSchemaPattern[];
+    dynamicHints?: FlowDynamicHint[];
+}
+export interface FlowSchemaBundleSlotCatalog {
+    type: 'object' | 'array';
+    required?: boolean;
+    minItems?: number;
+    open?: boolean;
+    candidates: FlowSchemaBundleNode[];
+}
+export interface FlowSchemaBundleNode {
+    use: string;
+    title?: string;
+    compatibility?: FlowFieldModelCompatibility;
+    subModelCatalog?: Record<string, FlowSchemaBundleSlotCatalog>;
+}
+export type FlowSchemaBundleItem = FlowSchemaBundleNode;
+export interface FlowSchemaBundleDocument {
+    items: FlowSchemaBundleNode[];
+}
+export interface FlowSchemaContextEdge {
+    parentUse: string;
+    slotKey: string;
+    childUse: string;
+}
+export interface FlowSubModelContextPathStep {
+    slotKey: string;
+    use?: string | string[];
+}
+export interface FlowModelSchemaPatch {
+    stepParamsSchema?: FlowJsonSchema;
+    flowRegistrySchema?: FlowJsonSchema;
+    subModelSlots?: Record<string, FlowSubModelSlotSchema>;
+    flowRegistrySchemaPatch?: FlowJsonSchema;
+    docs?: FlowSchemaDocs;
+    examples?: any[];
+    skeleton?: any;
+    dynamicHints?: FlowDynamicHint[];
+}
+export interface FlowDescendantSchemaPatch {
+    path: FlowSubModelContextPathStep[];
+    patch: FlowModelSchemaPatch;
+}
+export interface FlowSubModelSlotSchema {
+    type: 'object' | 'array';
+    use?: string;
+    uses?: string[];
+    required?: boolean;
+    minItems?: number;
+    dynamic?: boolean;
+    schema?: FlowJsonSchema;
+    fieldBindingContext?: string;
+    childSchemaPatch?: FlowModelSchemaPatch | Record<string, FlowModelSchemaPatch>;
+    descendantSchemaPatches?: FlowDescendantSchemaPatch[];
+    description?: string;
+}
+export interface FlowModelSchemaMeta {
+    stepParamsSchema?: FlowJsonSchema;
+    flowRegistrySchema?: FlowJsonSchema;
+    subModelSlots?: Record<string, FlowSubModelSlotSchema>;
+    flowRegistrySchemaPatch?: FlowJsonSchema;
+    docs?: FlowSchemaDocs;
+    examples?: any[];
+    skeleton?: any;
+    dynamicHints?: FlowDynamicHint[];
+    source?: FlowSchemaCoverage['source'];
+    strict?: boolean;
+    exposure?: FlowModelSchemaExposure;
+    abstract?: boolean;
+    allowDirectUse?: boolean;
+    suggestedUses?: string[];
+}
+export interface FlowActionSchemaContribution {
+    name: string;
+    title?: string;
+    paramsSchema?: FlowJsonSchema;
+    docs?: FlowSchemaDocs;
+    source?: FlowSchemaCoverage['source'];
+    strict?: boolean;
+}
+export interface FlowModelSchemaContribution {
+    use: string;
+    title?: string;
+    stepParamsSchema?: FlowJsonSchema;
+    flowRegistrySchema?: FlowJsonSchema;
+    subModelSlots?: Record<string, FlowSubModelSlotSchema>;
+    flowRegistrySchemaPatch?: FlowJsonSchema;
+    docs?: FlowSchemaDocs;
+    examples?: any[];
+    skeleton?: any;
+    dynamicHints?: FlowDynamicHint[];
+    source?: FlowSchemaCoverage['source'];
+    strict?: boolean;
+    exposure?: FlowModelSchemaExposure;
+    abstract?: boolean;
+    allowDirectUse?: boolean;
+    suggestedUses?: string[];
+}
+export interface FlowSchemaContributionDefaults {
+    source?: FlowSchemaCoverage['source'];
+    strict?: boolean;
+}
+export interface FlowSchemaSlotUseExpansion {
+    parentUse: string;
+    slotKey: string;
+    uses: string[];
+}
+export interface FlowSchemaInventoryContribution {
+    publicTreeRoots?: string[];
+    slotUseExpansions?: FlowSchemaSlotUseExpansion[];
+}
+export interface FlowFieldBindingConditions {
+    association?: boolean;
+    fieldTypes?: string[];
+    targetCollectionTemplateIn?: string[];
+    targetCollectionTemplateNotIn?: string[];
+}
+export interface FlowFieldBindingContextContribution {
+    name: string;
+    inherits?: string[];
+}
+export interface FlowFieldBindingContribution {
+    context: string;
+    use: string;
+    interfaces: string[];
+    isDefault?: boolean;
+    order?: number;
+    conditions?: FlowFieldBindingConditions;
+    defaultProps?: any;
+}
+export interface FlowFieldModelCompatibility {
+    context: string;
+    interfaces: string[];
+    isDefault?: boolean;
+    order?: number;
+    association?: boolean;
+    fieldTypes?: string[];
+    targetCollectionTemplateIn?: string[];
+    targetCollectionTemplateNotIn?: string[];
+    inheritParentFieldBinding?: boolean;
+}
+export interface FlowSchemaContribution {
+    models?: FlowModelSchemaContribution[] | Record<string, FlowModelSchemaContribution>;
+    actions?: FlowActionSchemaContribution[] | Record<string, FlowActionSchemaContribution>;
+    fieldBindingContexts?: FlowFieldBindingContextContribution[] | Record<string, FlowFieldBindingContextContribution>;
+    fieldBindings?: FlowFieldBindingContribution[] | Record<string, FlowFieldBindingContribution | FlowFieldBindingContribution[]>;
+    inventory?: FlowSchemaInventoryContribution;
+    defaults?: FlowSchemaContributionDefaults;
+}
+export interface FlowSchemaContributionProvider {
+    getFlowSchemaContributions(): FlowSchemaContribution | undefined | Promise<FlowSchemaContribution | undefined>;
+}
 /**
  * Defines a flow with generic model type support.
  */
@@ -130,6 +345,9 @@ export interface ActionDefinition<TModel extends FlowModel = FlowModel, TCtx ext
     title?: string;
     handler: (ctx: TCtx, params: any) => Promise<any> | any;
     uiSchema?: Record<string, ISchema> | ((ctx: TCtx) => Record<string, ISchema> | Promise<Record<string, ISchema>>);
+    paramsSchema?: FlowJsonSchema;
+    paramsSchemaPatch?: FlowJsonSchema;
+    schemaDocs?: FlowSchemaDocs;
     defaultParams?: Record<string, any> | ((ctx: TCtx) => Record<string, any> | Promise<Record<string, any>>);
     beforeParamsSave?: (ctx: FlowSettingsContext<TModel>, params: any, previousParams: any) => void | Promise<void>;
     afterParamsSave?: (ctx: FlowSettingsContext<TModel>, params: any, previousParams: any) => void | Promise<void>;
@@ -228,6 +446,8 @@ export interface StepDefinition<TModel extends FlowModel = FlowModel> extends Pa
     use?: string;
     sort?: number;
     preset?: boolean;
+    paramsSchemaOverride?: FlowJsonSchema;
+    schemaDocs?: FlowSchemaDocs;
     uiMode?: StepUIMode | ((ctx: FlowRuntimeContext<TModel>) => StepUIMode | Promise<StepUIMode>);
 }
 /**
@@ -340,6 +560,18 @@ export interface EnsureBatchResult {
 }
 export interface IFlowModelRepository<T extends FlowModel = FlowModel> {
     findOne(query: Record<string, any>): Promise<Record<string, any> | null>;
+    /**
+     * Ensure a model exists (create if missing) in a single request.
+     */
+    ensure: (values: Record<string, any>, options?: {
+        includeAsyncNode?: boolean;
+    }) => Promise<Record<string, any> | null>;
+    /**
+     * Optional: run multiple ops in a single transaction (server capability).
+     */
+    mutate?: (values: Record<string, any>, options?: {
+        includeAsyncNode?: boolean;
+    }) => Promise<Record<string, any>>;
     save(model: T, options?: {
         onlyStepParams?: boolean;
     }): Promise<Record<string, any>>;
@@ -452,6 +684,7 @@ export type FlowModelMeta = Pick<SubModelItem, 'key' | 'label' | 'icon' | 'child
         label: string;
         value: string;
     }[];
+    schema?: FlowModelSchemaMeta;
 };
 /**
  * 字段 FlowModel 的专用元数据接口

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/flow-engine",
-  "version": "2.1.0-alpha.10",
+  "version": "2.1.0-alpha.12",
   "private": false,
   "description": "A standalone flow engine for NocoBase, managing workflows, models, and actions.",
   "main": "lib/index.js",
@@ -8,8 +8,8 @@
   "dependencies": {
     "@formily/antd-v5": "1.x",
     "@formily/reactive": "2.x",
-    "@nocobase/sdk": "2.1.0-alpha.10",
-    "@nocobase/shared": "2.1.0-alpha.10",
+    "@nocobase/sdk": "2.1.0-alpha.12",
+    "@nocobase/shared": "2.1.0-alpha.12",
     "ahooks": "^3.7.2",
     "dayjs": "^1.11.9",
     "dompurify": "^3.0.2",
@@ -36,5 +36,5 @@
   ],
   "author": "NocoBase Team",
   "license": "Apache-2.0",
-  "gitHead": "ce790d46c0a5768ca9618c7d0d77ab8300de75c8"
+  "gitHead": "f12c4a75470590b1670ce54510b96ef94c2cd7a2"
 }

package/server.d.ts

@@ -0,0 +1 @@
+export * from './src/server';

package/server.js

@@ -0,0 +1 @@
+module.exports = process.env.IS_DEV_CMD || process.env.VITEST ? require('./src/server.ts') : require('./lib/server');