@nocobase/plugin-flow-engine 2.1.0-alpha.3 → 2.1.0-alpha.30

package/dist/ai/docs/runjs/context/data-source-manager.md

@@ -1,18 +1,18 @@
 # ctx.dataSourceManager
 
-The data source manager (`DataSourceManager` instance) for managing and accessing multiple data sources (e.g. main `main`, logging `logging`). Use when you have multiple data sources or need cross–data-source metadata access.
+The Data Source Manager (`DataSourceManager` instance) is used to manage and access multiple data sources (e.g., the main database `main`, logging database `logging`, etc.). It is used when multiple data sources exist or when cross-data source metadata access is required.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **Multiple data sources** | Enumerate all data sources, get one by key |
-| **Cross–data-source access** | When context doesn’t know the data source, access by “data source key + collection name” |
-| **Field by full path** | Get field definition with path format `dataSourceKey.collectionName.fieldPath` |
+|------|------|
+| **Multi-data source** | Enumerate all data sources, or get a specific data source by key. |
+| **Cross-data source access** | Access metadata using the "data source key + collection name" format when the data source of the current context is unknown. |
+| **Get fields by full path** | Use the `dataSourceKey.collectionName.fieldPath` format to retrieve field definitions across different data sources. |
 
-> Note: If you only work with the current data source, use `ctx.dataSource`; use `ctx.dataSourceManager` when you need to enumerate or switch data sources.
+> Note: If you are only operating on the current data source, prioritize using `ctx.dataSource`. Use `ctx.dataSourceManager` only when you need to enumerate or switch between data sources.
 
-## Type
+## Type Definition
 
 ```ts
 dataSourceManager: DataSourceManager;
@@ -20,64 +20,74 @@ dataSourceManager: DataSourceManager;
 class DataSourceManager {
   constructor();
 
+  // Data source management
   addDataSource(ds: DataSource | DataSourceOptions): void;
   upsertDataSource(ds: DataSource | DataSourceOptions): void;
   removeDataSource(key: string): void;
   clearDataSources(): void;
 
-  getDataSources(): DataSource[];
-  getDataSource(key: string): DataSource | undefined;
+  // Read data sources
+  getDataSources(): DataSource[];                     // Get all data sources
+  getDataSource(key: string): DataSource | undefined;  // Get data source by key
 
+  // Access metadata directly by data source + collection
   getCollection(dataSourceKey: string, collectionName: string): Collection | undefined;
   getCollectionField(fieldPathWithDataSource: string): CollectionField | undefined;
 }
 ```
 
-## Relation to ctx.dataSource
+## Relationship with ctx.dataSource
 
-| Need | Recommended |
-|------|-------------|
-| **Single data source for context** | `ctx.dataSource` |
-| **Entry to all data sources** | `ctx.dataSourceManager` |
+| Requirement | Recommended Usage |
+|------|----------|
+| **Single data source bound to the current context** | `ctx.dataSource` (e.g., the data source of the current page/block) |
+| **Entry point for all data sources** | `ctx.dataSourceManager` |
 | **List or switch data sources** | `ctx.dataSourceManager.getDataSources()` / `getDataSource(key)` |
-| **Collection in current data source** | `ctx.dataSource.getCollection(name)` |
-| **Collection in another data source** | `ctx.dataSourceManager.getCollection(dataSourceKey, collectionName)` |
-| **Field in current data source** | `ctx.dataSource.getCollectionField('users.profile.avatar')` |
-| **Field across data sources** | `ctx.dataSourceManager.getCollectionField('main.users.profile.avatar')` |
+| **Get collection within the current data source** | `ctx.dataSource.getCollection(name)` |
+| **Get collection across data sources** | `ctx.dataSourceManager.getCollection(dataSourceKey, collectionName)` |
+| **Get field within the current data source** | `ctx.dataSource.getCollectionField('users.profile.avatar')` |
+| **Get field across data sources** | `ctx.dataSourceManager.getCollectionField('main.users.profile.avatar')` |
 
 ## Examples
 
-### Get a data source
+### Get a Specific Data Source
 
 ```ts
+// Get the data source named 'main'
 const mainDS = ctx.dataSourceManager.getDataSource('main');
+
+// Get all collections under this data source
 const collections = mainDS?.getCollections();
 ```
 
-### Cross–data-source collection metadata
+### Access Collection Metadata Across Data Sources
 
 ```ts
+// Get collection by dataSourceKey + collectionName
 const users = ctx.dataSourceManager.getCollection('main', 'users');
 const orders = ctx.dataSourceManager.getCollection('main', 'orders');
 
+// Get the primary key of the collection
 const primaryKey = users?.filterTargetKey ?? 'id';
 ```
 
-### Field by full path
+### Get Field Definition by Full Path
 
 ```ts
 // Format: dataSourceKey.collectionName.fieldPath
+// Get field definition by "data source key.collection name.field path"
 const field = ctx.dataSourceManager.getCollectionField('main.users.profile.avatar');
 
+// Supports association field paths
 const userNameField = ctx.dataSourceManager.getCollectionField('main.orders.createdBy.name');
 ```
 
-### Iterate all data sources
+### Iterate Through All Data Sources
 
 ```ts
 const dataSources = ctx.dataSourceManager.getDataSources();
 for (const ds of dataSources) {
-  ctx.logger.info(`Data source: ${ds.key}, display: ${ds.displayName}`);
+  ctx.logger.info(`Data Source: ${ds.key}, Display Name: ${ds.displayName}`);
   const collections = ds.getCollections();
   for (const col of collections) {
     ctx.logger.info(`  - Collection: ${col.name}`);
@@ -85,7 +95,7 @@ for (const ds of dataSources) {
 }
 ```
 
-### Dynamic data source from variable
+### Dynamically Select Data Source Based on Variables
 
 ```ts
 const dsKey = ctx.getVar('dataSourceKey') ?? 'main';
@@ -99,12 +109,12 @@ if (col) {
 
 ## Notes
 
-- `getCollectionField` path format is `dataSourceKey.collectionName.fieldPath`; first segment is data source key, then collection name and field path.
-- `getDataSource(key)` returns `undefined` if the data source doesn’t exist—check before use.
-- `addDataSource` throws if key already exists; `upsertDataSource` overwrites or adds.
+- The path format for `getCollectionField` is `dataSourceKey.collectionName.fieldPath`, where the first segment is the data source key, followed by the collection name and the field path.
+- `getDataSource(key)` returns `undefined` if the data source does not exist; it is recommended to perform a null check before use.
+- `addDataSource` will throw an exception if the key already exists; `upsertDataSource` will either overwrite the existing one or add a new one.
 
 ## Related
 
-- [ctx.dataSource](./data-source.md): current data source instance
-- [ctx.collection](./collection.md): collection for current context
-- [ctx.collectionField](./collection-field.md): current field’s collection field definition
+- [ctx.dataSource](./data-source.md): Current data source instance
+- [ctx.collection](./collection.md): Collection associated with the current context
+- [ctx.collectionField](./collection-field.md): Collection field definition for the current field

package/dist/ai/docs/runjs/context/data-source.md

@@ -1,18 +1,18 @@
 # ctx.dataSource
 
-The data source instance (`DataSource`) bound to the current RunJS context; used to access collections, field metadata, and collection config **within that data source**. Usually the current page/block’s data source (e.g. main `main`).
+The `DataSource` instance bound to the current RunJS execution context, used to access collections, field metadata, and manage collection configurations **within the current data source**. It usually corresponds to the data source selected for the current page or block (e.g., the main database `main`).
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **Single data source** | Get collections, field metadata when the current data source is known |
-| **Collection management** | Get/add/update/remove collections in the current data source |
-| **Field by path** | Get field definition by `collectionName.fieldPath` (supports association path) |
+|------|------|
+| **Single Data Source Operations** | Get collection and field metadata when the current data source is known. |
+| **Collection Management** | Get, add, update, or delete collections under the current data source. |
+| **Get Fields by Path** | Use the `collectionName.fieldPath` format to get field definitions (supports association paths). |
 
-> Note: `ctx.dataSource` is the single data source for the current context; to enumerate or access other data sources use [ctx.dataSourceManager](./data-source-manager.md).
+> Note: `ctx.dataSource` represents a single data source for the current context. To enumerate or access other data sources, please use [ctx.dataSourceManager](./data-source-manager.md).
 
-## Type
+## Type Definition
 
 ```ts
 dataSource: DataSource;
@@ -20,15 +20,18 @@ dataSource: DataSource;
 class DataSource {
   constructor(options?: Record<string, any>);
 
-  get flowEngine(): FlowEngine;
-  get displayName(): string;
-  get key(): string;
-  get name(): string;
+  // Read-only properties
+  get flowEngine(): FlowEngine;   // Current FlowEngine instance
+  get displayName(): string;      // Display name (supports i18n)
+  get key(): string;              // Data source key, e.g., 'main'
+  get name(): string;             // Same as key
 
-  getCollections(): Collection[];
-  getCollection(name: string): Collection | undefined;
-  getAssociation(associationName: string): CollectionField | undefined;
+  // Collection reading
+  getCollections(): Collection[];                      // Get all collections
+  getCollection(name: string): Collection | undefined; // Get collection by name
+  getAssociation(associationName: string): CollectionField | undefined; // Get association field (e.g., users.roles)
 
+  // Collection management
   addCollection(collection: Collection | CollectionOptions): void;
   updateCollection(newOptions: CollectionOptions): void;
   upsertCollection(options: CollectionOptions): Collection | undefined;
@@ -36,6 +39,7 @@ class DataSource {
   removeCollection(name: string): void;
   clearCollections(): void;
 
+  // Field metadata
   getCollectionField(fieldPath: string): CollectionField | undefined;
 }
 ```
@@ -43,57 +47,61 @@ class DataSource {
 ## Common Properties
 
 | Property | Type | Description |
-|----------|------|-------------|
-| `key` | `string` | Data source key (e.g. `main`) |
+|------|------|------|
+| `key` | `string` | Data source key, e.g., `'main'` |
 | `name` | `string` | Same as key |
-| `displayName` | `string` | Display name (i18n) |
+| `displayName` | `string` | Display name (supports i18n) |
 | `flowEngine` | `FlowEngine` | Current FlowEngine instance |
 
 ## Common Methods
 
 | Method | Description |
-|--------|-------------|
-| `getCollections()` | All collections in this data source (sorted, hidden filtered) |
-| `getCollection(name)` | Collection by name; `name` can be `collectionName.fieldName` for association target |
-| `getAssociation(associationName)` | Association field by `collectionName.fieldName` |
-| `getCollectionField(fieldPath)` | Field by `collectionName.fieldPath`; supports paths like `users.profile.avatar` |
+|------|------|
+| `getCollections()` | Gets all collections under the current data source (sorted, with hidden ones filtered). |
+| `getCollection(name)` | Gets a collection by name; `name` can be `collectionName.fieldName` to get the target collection of an association. |
+| `getAssociation(associationName)` | Gets an association field definition by `collectionName.fieldName`. |
+| `getCollectionField(fieldPath)` | Gets a field definition by `collectionName.fieldPath`, supporting association paths like `users.profile.avatar`. |
 
-## Relation to ctx.dataSourceManager
+## Relationship with ctx.dataSourceManager
 
-| Need | Recommended |
-|------|-------------|
-| **Single data source for context** | `ctx.dataSource` |
-| **Entry to all data sources** | `ctx.dataSourceManager` |
-| **Collection in current data source** | `ctx.dataSource.getCollection(name)` |
-| **Collection in another data source** | `ctx.dataSourceManager.getCollection(dataSourceKey, collectionName)` |
-| **Field in current data source** | `ctx.dataSource.getCollectionField('users.profile.avatar')` |
-| **Field across data sources** | `ctx.dataSourceManager.getCollectionField('main.users.profile.avatar')` |
+| Requirement | Recommended Usage |
+|------|----------|
+| **Single data source bound to current context** | `ctx.dataSource` |
+| **Entry point for all data sources** | `ctx.dataSourceManager` |
+| **Get collection within current data source** | `ctx.dataSource.getCollection(name)` |
+| **Get collection across data sources** | `ctx.dataSourceManager.getCollection(dataSourceKey, collectionName)` |
+| **Get field within current data source** | `ctx.dataSource.getCollectionField('users.profile.avatar')` |
+| **Get field across data sources** | `ctx.dataSourceManager.getCollectionField('main.users.profile.avatar')` |
 
-## Examples
+## Example
 
-### Get collections and fields
+### Get Collections and Fields
 
 ```ts
+// Get all collections
 const collections = ctx.dataSource.getCollections();
 
+// Get collection by name
 const users = ctx.dataSource.getCollection('users');
 const primaryKey = users?.filterTargetKey ?? 'id';
 
+// Get field definition by "collectionName.fieldPath" (supports associations)
 const field = ctx.dataSource.getCollectionField('users.profile.avatar');
 const userNameField = ctx.dataSource.getCollectionField('orders.createdBy.name');
 ```
 
-### Get association field
+### Get Association Fields
 
 ```ts
+// Get association field definition by collectionName.fieldName
 const rolesField = ctx.dataSource.getAssociation('users.roles');
 if (rolesField?.isAssociationField()) {
   const targetCol = rolesField.targetCollection;
-  // ...
+  // Process based on target collection structure
 }
 ```
 
-### Iterate collections
+### Iterate Through Collections for Dynamic Processing
 
 ```ts
 const collections = ctx.dataSource.getCollections();
@@ -104,25 +112,25 @@ for (const col of collections) {
 }
 ```
 
-### Validation or dynamic UI from field metadata
+### Perform Validation or Dynamic UI Based on Field Metadata
 
 ```ts
 const field = ctx.dataSource.getCollectionField('users.status');
 if (field) {
   const options = field.enum ?? [];
   const operators = field.getFilterOperators();
-  // ...
+  // Perform UI logic or validation based on interface, enum, validation, etc.
 }
 ```
 
 ## Notes
 
-- `getCollectionField(fieldPath)` uses path format `collectionName.fieldPath`; first segment is collection name, rest is field path (supports association, e.g. `user.name`).
-- `getCollection(name)` supports `collectionName.fieldName` and returns the association target collection.
-- In RunJS, `ctx.dataSource` is usually determined by the current block/page; if there is no bound data source it may be `undefined`—check before use.
+- The path format for `getCollectionField(fieldPath)` is `collectionName.fieldPath`, where the first segment is the collection name and the subsequent segments are the field path (supports associations, e.g., `user.name`).
+- `getCollection(name)` supports the `collectionName.fieldName` format, returning the target collection of the association field.
+- In the RunJS context, `ctx.dataSource` is usually determined by the data source of the current block or page. If no data source is bound to the context, it may be `undefined`; it is recommended to perform a null check before use.
 
 ## Related
 
-- [ctx.dataSourceManager](./data-source-manager.md): manager for all data sources
-- [ctx.collection](./collection.md): collection for current context
-- [ctx.collectionField](./collection-field.md): current field’s collection field definition
+- [ctx.dataSourceManager](./data-source-manager.md): Data source manager, manages all data sources.
+- [ctx.collection](./collection.md): The collection associated with the current context.
+- [ctx.collectionField](./collection-field.md): The collection field definition for the current field.

package/dist/ai/docs/runjs/context/element.md

@@ -1,57 +1,60 @@
 # ctx.element
 
-The ElementProxy instance for the sandbox DOM container; it is the default render target of `ctx.render()`. Available in JSBlock, JSField, JSItem, JSColumn, and other contexts that have a render container.
+An `ElementProxy` instance pointing to the sandbox DOM container, serving as the default rendering target for `ctx.render()`. It is available in scenarios where a rendering container exists, such as `JSBlock`, `JSField`, `JSItem`, and `JSColumn`.
 
-## Use Cases
+## Applicable Scenarios
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock** | Block’s DOM container for custom content |
-| **JSField / JSItem / FormJSFieldItem** | Field/item render container (often a `<span>`) |
-| **JSColumn** | Table cell DOM container for custom column content |
+|------|------|
+| **JSBlock** | The DOM container for the block, used to render custom block content. |
+| **JSField / JSItem / FormJSFieldItem** | The rendering container for a field or form item (usually a `<span>`). |
+| **JSColumn** | The DOM container for a table cell, used to render custom column content. |
 
-> Note: `ctx.element` is only available in RunJS contexts that have a render container; in contexts without UI (e.g. pure backend) it may be `undefined`—check before use.
+> Note: `ctx.element` is only available in RunJS contexts that have a rendering container. In contexts without a UI (such as pure backend logic), it may be `undefined`. It is recommended to perform a null check before use.
 
-## Type
+## Type Definition
 
 ```typescript
 element: ElementProxy | undefined;
 
+// ElementProxy is a proxy for the raw HTMLElement, exposing a secure API
 class ElementProxy {
-  __el: HTMLElement;  // Internal native DOM (only for specific cases)
-  innerHTML: string;  // Read/write sanitized with DOMPurify
-  outerHTML: string;
+  __el: HTMLElement;  // The internal raw DOM element (accessible only in specific scenarios)
+  innerHTML: string;  // Sanitized via DOMPurify during read/write
+  outerHTML: string; // Same as above
   appendChild(child: HTMLElement | string): void;
-  // Other HTMLElement methods passed through (not recommended)
+  // Other HTMLElement methods are passed through (direct use is not recommended)
 }
 ```
 
-## Security
+## Security Requirements
 
-**Recommended: do all rendering via `ctx.render()`.** Do not use `ctx.element`’s DOM APIs directly (e.g. `innerHTML`, `appendChild`, `querySelector`).
+**Recommended: All rendering should be performed via `ctx.render()`.** Avoid using the DOM APIs of `ctx.element` directly (e.g., `innerHTML`, `appendChild`, `querySelector`, etc.).
 
-### Why use ctx.render()
+### Why ctx.render() is Recommended
 
-| Benefit | Description |
-|---------|-------------|
-| **Security** | Centralized control, avoids XSS and unsafe DOM use |
-| **React** | Full JSX, components, and lifecycle |
-| **Context** | Inherits app ConfigProvider, theme, etc. |
-| **Conflicts** | Manages React root create/unmount, avoids multiple instances |
+| Advantage | Description |
+|------|------|
+| **Security** | Centralized security control to prevent XSS and improper DOM operations. |
+| **React Support** | Full support for JSX, React components, and lifecycles. |
+| **Context Inheritance** | Automatically inherits the application's `ConfigProvider`, themes, etc. |
+| **Conflict Handling** | Automatically manages React root creation/unmounting to avoid multi-instance conflicts. |
 
-### ❌ Not recommended: direct ctx.element use
+### ❌ Not Recommended: Direct Manipulation of ctx.element
 
 ```ts
+// ❌ Not recommended: Using ctx.element APIs directly
 ctx.element.innerHTML = '<div>Content</div>';
 ctx.element.appendChild(node);
 ctx.element.querySelector('.class');
 ```
 
-> `ctx.element.innerHTML` is deprecated; use `ctx.render()` instead.
+> `ctx.element.innerHTML` is deprecated. Please use `ctx.render()` instead.
 
-### ✅ Recommended: ctx.render()
+### ✅ Recommended: Using ctx.render()
 
 ```ts
+// ✅ Rendering a React component
 const { Button, Card } = ctx.libs.antd;
 ctx.render(
   <Card title={ctx.t('Welcome')}>
@@ -59,40 +62,43 @@ ctx.render(
   </Card>
 );
 
+// ✅ Rendering an HTML string
 ctx.render('<div style="padding:16px;">' + ctx.t('Content') + '</div>');
 
+// ✅ Rendering a DOM node
 const div = document.createElement('div');
 div.textContent = ctx.t('Hello');
 ctx.render(div);
 ```
 
-## Exception: popover anchor
+## Special Case: As a Popover Anchor
 
-When you need the current element as a popover anchor, use `ctx.element?.__el` as the native DOM `target`:
+When you need to open a Popover using the current element as an anchor, you can access `ctx.element?.__el` to get the raw DOM as the `target`:
 
 ```ts
+// ctx.viewer.popover requires a raw DOM as the target
 await ctx.viewer.popover({
   target: ctx.element?.__el,
-  content: <div>Popover content</div>,
+  content: <div>Popup Content</div>,
 });
 ```
 
-> Use `__el` only for this “current container as anchor” case; do not touch DOM otherwise.
+> Use `__el` only in scenarios like "using the current container as an anchor"; do not manipulate the DOM directly in other cases.
 
-## Relation to ctx.render
+## Relationship with ctx.render
 
-- `ctx.render(vnode)` without a `container` argument renders into `ctx.element`.
-- If there is no `ctx.element` and no `container`, an error is thrown.
-- You can pass a container: `ctx.render(vnode, customContainer)`.
+- If `ctx.render(vnode)` is called without a `container` argument, it renders into the `ctx.element` container by default.
+- If both `ctx.element` is missing and no `container` is provided, an error will be thrown.
+- You can explicitly specify a container: `ctx.render(vnode, customContainer)`.
 
 ## Notes
 
-- Treat `ctx.element` as the internal container for `ctx.render()`; avoid reading or mutating it directly.
-- In contexts without a render container, `ctx.element` is `undefined`; ensure a container exists or pass `container` to `ctx.render()`.
-- ElementProxy’s `innerHTML`/`outerHTML` are sanitized with DOMPurify, but prefer `ctx.render()` for all rendering.
+- `ctx.element` is intended for internal use by `ctx.render()`. Directly accessing or modifying its properties/methods is not recommended.
+- In contexts without a rendering container, `ctx.element` will be `undefined`. Ensure the container is available or pass a `container` manually before calling `ctx.render()`.
+- Although `innerHTML`/`outerHTML` in `ElementProxy` are sanitized via DOMPurify, it is still recommended to use `ctx.render()` for unified rendering management.
 
 ## Related
 
-- [ctx.render](./render.md): render into container
-- [ctx.view](./view.md): current view controller
-- [ctx.modal](./modal.md): modal APIs
+- [ctx.render](./render.md): Rendering content into a container
+- [ctx.view](./view.md): Current view controller
+- [ctx.modal](./modal.md): Shortcut API for modals

package/dist/ai/docs/runjs/context/exit-all.md

@@ -1,94 +1,96 @@
 # ctx.exitAll()
 
-Stops the current event flow and all **subsequent** event flows that were triggered in the same event dispatch. Use when a global error or permission check requires stopping every flow for that event.
+Terminates the current event flow and all subsequent event flows triggered in the same event dispatch. It is commonly used when all event flows under the current event need to be aborted immediately due to a global error or permission validation failure.
 
 ## Use Cases
 
-Use `ctx.exitAll()` in JS-capable contexts when you need to **stop both the current flow and any later flows for the same event**:
+`ctx.exitAll()` is generally used in JS-executable contexts where it is necessary to **simultaneously abort the current event flow and subsequent event flows triggered by that event**:
 
 | Scenario | Description |
-|----------|-------------|
-| **Event flow** | Main flow fails (e.g. no permission); stop it and any subsequent flows for that event |
-| **Linkage rules** | When linkage validation fails and you want to stop current and subsequent linkage |
-| **Action events** | Pre-action check fails (e.g. delete permission); block the action and later steps |
+|------|------|
+| **Event Flow** | Main event flow validation fails (e.g., insufficient permissions), requiring the termination of the main flow and any subsequent flows under the same event that have not yet executed. |
+| **Linkage Rules** | When linkage validation fails, the current linkage and subsequent linkages triggered by the same event must be terminated. |
+| **Action Events** | Pre-action validation fails (e.g., permission check before deletion), requiring the prevention of the main action and subsequent steps. |
 
-> Difference from `ctx.exit()`: `ctx.exit()` only stops the current flow; `ctx.exitAll()` also stops **subsequent** flows for that event.
+> Difference from `ctx.exit()`: `ctx.exit()` only terminates the current event flow; `ctx.exitAll()` terminates the current event flow and any **unexecuted** subsequent event flows in the same event dispatch.
 
-## Type
+## Type Definition
 
 ```ts
 exitAll(): never;
 ```
 
-Calling `ctx.exitAll()` throws an internal `FlowExitAllException`, which the engine uses to stop the current flow instance and subsequent flows for the same event. The rest of the current JS does not run.
+Calling `ctx.exitAll()` throws an internal `FlowExitAllException`, which is caught by the FlowEngine to stop the current event flow instance and subsequent event flows under the same event. Once called, the remaining statements in the current JS code will not be executed.
 
 ## Comparison with ctx.exit()
 
 | Method | Scope |
-|--------|--------|
-| `ctx.exit()` | Stops only the current flow; later flows still run |
-| `ctx.exitAll()` | Stops the current flow and **subsequent** flows for the same event |
+|------|----------|
+| `ctx.exit()` | Only terminates the current event flow; subsequent event flows are unaffected. |
+| `ctx.exitAll()` | Terminates the current event flow and aborts subsequent event flows executed **sequentially** under the same event. |
 
-## Execution mode
+## Execution Mode
 
-- **Sequential**: flows for the same event run one after another; after any flow calls `ctx.exitAll()`, later flows do not run.
-- **Parallel**: flows run in parallel; one flow calling `ctx.exitAll()` does not stop other already-running flows.
+- **Sequential Execution**: Event flows under the same event are executed in order. After any event flow calls `ctx.exitAll()`, subsequent event flows will not execute.
+- **Parallel Execution**: Event flows under the same event are executed in parallel. Calling `ctx.exitAll()` in one event flow will not interrupt other concurrent event flows (as they are independent).
 
 ## Examples
 
-### Stop all flows on permission failure
+### Terminate all event flows when permission validation fails
 
 ```ts
+// Abort the main event flow and subsequent event flows when permissions are insufficient
 if (!hasPermission(ctx)) {
-  ctx.notification.error({ message: 'No permission' });
+  ctx.notification.error({ message: 'No operation permission' });
   ctx.exitAll();
 }
 ```
 
-### Stop on global pre-check failure
+### Terminate when global pre-validation fails
 
 ```ts
+// Example: If associated data is found to be non-deletable before deletion, prevent the main event flow and subsequent actions
 const canDelete = await checkDeletable(ctx.model?.getValue?.());
 if (!canDelete) {
-  ctx.message.error('Cannot delete: related data exists');
+  ctx.message.error('Cannot delete: associated data exists');
   ctx.exitAll();
 }
 ```
 
-### When to use ctx.exit() vs ctx.exitAll()
+### Choosing between ctx.exit() and ctx.exitAll()
 
 ```ts
-// Only this flow → ctx.exit()
+// Only the current event flow needs to exit -> Use ctx.exit()
 if (!params.valid) {
-  ctx.message.error('Invalid params');
-  ctx.exit();
+  ctx.message.error('Invalid parameters');
+  ctx.exit();  // Subsequent event flows are unaffected
 }
 
-// This and all subsequent flows → ctx.exitAll()
+// Need to terminate all subsequent event flows under the current event -> Use ctx.exitAll()
 if (!ctx.model?.context?.getPermission?.()) {
-  ctx.notification.warning({ message: 'No permission' });
-  ctx.exitAll();
+  ctx.notification.warning({ message: 'Insufficient permissions' });
+  ctx.exitAll();  // Both the main event flow and subsequent event flows under the same event are terminated
 }
 ```
 
-### Message then exit
+### Prompt before terminating
 
 ```ts
 if (!isValidInput(ctx.form?.getValues?.())) {
-  ctx.message.warning('Please fix form errors first');
+  ctx.message.warning('Please correct the errors in the form first');
   ctx.exitAll();
 }
 ```
 
 ## Notes
 
-- After `ctx.exitAll()`, the rest of the current JS does not run; explain to the user with `ctx.message`, `ctx.notification`, or a dialog before calling.
-- You usually do not need to catch `FlowExitAllException`; the engine handles it.
-- To stop only the current flow, use `ctx.exit()`.
-- In parallel mode, `ctx.exitAll()` only stops the current flow; it does not cancel other concurrent flows.
+- After calling `ctx.exitAll()`, subsequent code in the current JS will not execute. It is recommended to explain the reason to the user via `ctx.message`, `ctx.notification`, or a modal before calling it.
+- Business code usually does not need to catch `FlowExitAllException`; let the FlowEngine handle it.
+- If you only need to stop the current event flow without affecting subsequent ones, use `ctx.exit()`.
+- In parallel mode, `ctx.exitAll()` only terminates the current event flow and does not interrupt other concurrent event flows.
 
 ## Related
 
-- [ctx.exit()](./exit.md): stop only the current flow
-- [ctx.message](./message.md): message API
-- [ctx.modal](./modal.md): confirm dialog
+- [ctx.exit()](./exit.md): Terminates only the current event flow
+- [ctx.message](./message.md): Message prompts
+- [ctx.modal](./modal.md): Confirmation modal