@nocobase/plugin-flow-engine 2.1.0-alpha.6 → 2.1.0-alpha.8

package/dist/ai/docs/runjs/resource/api-resource.md

@@ -1,73 +1,73 @@
 # APIResource
 
-Generic **API resource** that sends requests by URL; use for any HTTP endpoint. Extends FlowResource with request config and `refresh()`. Unlike [MultiRecordResource](./multi-record-resource.md) and [SingleRecordResource](./single-record-resource.md), APIResource does not depend on resource name and requests directly by URL; suitable for custom endpoints, third-party APIs, etc.
+A **generic API resource** for making requests based on URLs, suitable for any HTTP interface. It inherits from the `FlowResource` base class and extends it with request configuration and `refresh()`. Unlike [MultiRecordResource](./multi-record-resource.md) and [SingleRecordResource](./single-record-resource.md), `APIResource` does not depend on a resource name; it requests directly by URL, making it suitable for custom interfaces, third-party APIs, and other scenarios.
 
-**Create with**: `ctx.makeResource('APIResource')` or `ctx.initResource('APIResource')`. Before use call `setURL()`; RunJS context auto-injects `ctx.api` (APIClient), no need to call `setAPIClient` manually.
+**Creation method**: `ctx.makeResource('APIResource')` or `ctx.initResource('APIResource')`. You must call `setURL()` before use. In the RunJS context, `ctx.api` (APIClient) is automatically injected, so there is no need to call `setAPIClient` manually.
 
 ---
 
-## Use cases
+## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **Custom endpoints** | Call non-standard resource APIs (e.g. `/api/custom/stats`, `/api/reports/summary`) |
-| **Third-party APIs** | Request external services via full URL (target must support CORS) |
-| **One-off queries** | Fetch data temporarily, no need to bind to `ctx.resource` |
-| **vs ctx.request** | Use APIResource when you need reactive data, events, or error state; use `ctx.request()` for simple one-off requests |
+|------|------|
+| **Custom Interface** | Call non-standard resource APIs (e.g., `/api/custom/stats`, `/api/reports/summary`). |
+| **Third-party API** | Request external services via full URL (requires CORS support from the target). |
+| **One-time Query** | Temporary data fetching that is disposable and does not need to be bound to `ctx.resource`. |
+| **Choosing between APIResource and ctx.request** | Use `APIResource` when reactive data, events, or error states are needed; use `ctx.request()` for simple one-time requests. |
 
 ---
 
-## Base (FlowResource)
+## Base Class Capabilities (FlowResource)
 
-All resources support:
+All Resources possess the following:
 
 | Method | Description |
-|--------|-------------|
-| `getData()` | Current data |
-| `setData(value)` | Set data (local only) |
-| `hasData()` | Whether data exists |
-| `getMeta(key?)` / `setMeta(meta)` | Read/write metadata |
-| `getError()` / `setError(err)` / `clearError()` | Error state |
-| `on(event, callback)` / `once` / `off` / `emit` | Subscribe and emit events |
+|------|------|
+| `getData()` | Get current data. |
+| `setData(value)` | Set data (local only). |
+| `hasData()` | Whether data exists. |
+| `getMeta(key?)` / `setMeta(meta)` | Read/write metadata. |
+| `getError()` / `setError(err)` / `clearError()` | Error state management. |
+| `on(event, callback)` / `once` / `off` / `emit` | Event subscription and triggering. |
 
 ---
 
-## Request config
+## Request Configuration
 
 | Method | Description |
-|--------|-------------|
-| `setAPIClient(api)` | Set APIClient instance (RunJS usually injects via context) |
-| `getURL()` / `setURL(url)` | Request URL |
-| `loading` | Load state (get/set) |
-| `clearRequestParameters()` | Clear request params |
-| `setRequestParameters(params)` | Merge request params |
-| `setRequestMethod(method)` | Method (e.g. `'get'`, `'post'`, default `'get'`) |
-| `addRequestHeader(key, value)` / `removeRequestHeader(key)` | Headers |
-| `addRequestParameter(key, value)` / `getRequestParameter(key)` / `removeRequestParameter(key)` | Single param add/get/remove |
-| `setRequestBody(data)` | Request body (for POST/PUT/PATCH) |
-| `setRequestOptions(key, value)` / `getRequestOptions()` | General request options |
+|------|------|
+| `setAPIClient(api)` | Set the APIClient instance (usually automatically injected in RunJS). |
+| `getURL()` / `setURL(url)` | Request URL. |
+| `loading` | Read/write loading state (get/set). |
+| `clearRequestParameters()` | Clear request parameters. |
+| `setRequestParameters(params)` | Merge and set request parameters. |
+| `setRequestMethod(method)` | Set request method (e.g., `'get'`, `'post'`, default is `'get'`). |
+| `addRequestHeader(key, value)` / `removeRequestHeader(key)` | Request headers. |
+| `addRequestParameter(key, value)` / `getRequestParameter(key)` / `removeRequestParameter(key)` | Add, delete, or query a single parameter. |
+| `setRequestBody(data)` | Request body (used for POST/PUT/PATCH). |
+| `setRequestOptions(key, value)` / `getRequestOptions()` | General request options. |
 
 ---
 
-## URL format
+## URL Format
 
-- **Resource style**: NocoBase shorthand supported, e.g. `users:list`, `posts:get`, concatenated with baseURL
-- **Relative path**: e.g. `/api/custom/endpoint`, concatenated with app baseURL
-- **Full URL**: Use full address for cross-origin; target must configure CORS
+- **Resource Style**: Supports NocoBase resource shorthand, such as `users:list` or `posts:get`, which will be concatenated with the `baseURL`.
+- **Relative Path**: e.g., `/api/custom/endpoint`, concatenated with the application's `baseURL`.
+- **Full URL**: Use full addresses for cross-origin requests; the target must have CORS configured.
 
 ---
 
-## Data fetch
+## Data Fetching
 
 | Method | Description |
-|--------|-------------|
-| `refresh()` | Send request with current URL, method, params, headers, data; write response `data` to `setData(data)` and emit `'refresh'`. On failure sets `setError(err)` and throws `ResourceError`, does not emit `refresh`. Requires `api` and URL. |
+|------|------|
+| `refresh()` | Initiates a request based on the current URL, method, params, headers, and data. It writes the response `data` into `setData(data)` and triggers the `'refresh'` event. On failure, it sets `setError(err)` and throws a `ResourceError`, without triggering the `refresh` event. Requires `api` and URL to be set. |
 
 ---
 
 ## Examples
 
-### Basic GET request
+### Basic GET Request
 
 ```js
 const res = ctx.makeResource('APIResource');
@@ -77,7 +77,7 @@ await res.refresh();
 const data = res.getData();
 ```
 
-### Resource-style URL
+### Resource Style URL
 
 ```js
 const res = ctx.makeResource('APIResource');
@@ -87,18 +87,18 @@ await res.refresh();
 const rows = res.getData()?.data ?? [];
 ```
 
-### POST request (with body)
+### POST Request (with Request Body)
 
 ```js
 const res = ctx.makeResource('APIResource');
 res.setURL('/api/custom/submit');
 res.setRequestMethod('post');
-res.setRequestBody({ name: 'Test', type: 'report' });
+res.setRequestBody({ name: 'test', type: 'report' });
 await res.refresh();
 const result = res.getData();
 ```
 
-### Listen to refresh event
+### Listening to the refresh Event
 
 ```js
 const res = ctx.makeResource('APIResource');
@@ -110,7 +110,7 @@ res.on('refresh', () => {
 await res.refresh();
 ```
 
-### Error handling
+### Error Handling
 
 ```js
 const res = ctx.makeResource('APIResource');
@@ -124,7 +124,7 @@ try {
 }
 ```
 
-### Custom headers
+### Custom Request Headers
 
 ```js
 const res = ctx.makeResource('APIResource');
@@ -138,18 +138,18 @@ await res.refresh();
 
 ## Notes
 
-- **ctx.api dependency**: RunJS injects `ctx.api`; usually no need to call `setAPIClient`. Set it manually when used without context.
-- **refresh = request**: `refresh()` sends one request with current config; method, params, data, etc. must be set before calling.
-- **Error does not update data**: On failure `getData()` keeps previous value; use `getError()` for error info.
-- **vs ctx.request**: Use `ctx.request()` for simple one-off requests; use APIResource when you need reactive data, events, or error state management.
+- **ctx.api Dependency**: In RunJS, `ctx.api` is injected by the environment; manual `setAPIClient` is usually unnecessary. If used in a context-less scenario, you must set it yourself.
+- **Refresh Means Request**: `refresh()` initiates a request based on the current configuration; method, params, data, etc., must be configured before calling.
+- **Errors Do Not Update Data**: On failure, `getData()` keeps its previous value; error information can be retrieved via `getError()`.
+- **Vs ctx.request**: Use `ctx.request()` for simple one-time requests; use `APIResource` when reactive data, events, and error state management are required.
 
 ---
 
 ## Related
 
-- [ctx.resource](../context/resource.md) - Resource instance in current context
-- [ctx.initResource()](../context/init-resource.md) - Initialize and bind to ctx.resource
-- [ctx.makeResource()](../context/make-resource.md) - Create resource instance without binding
-- [ctx.request()](../context/request.md) - Generic HTTP request, for simple one-off calls
-- [MultiRecordResource](./multi-record-resource.md) - For data tables/lists, CRUD, pagination
-- [SingleRecordResource](./single-record-resource.md) - For single records
+- [ctx.resource](../context/resource.md) - The resource instance in the current context
+- [ctx.initResource()](../context/init-resource.md) - Initialize and bind to `ctx.resource`
+- [ctx.makeResource()](../context/make-resource.md) - Create a new resource instance without binding
+- [ctx.request()](../context/request.md) - General HTTP request, suitable for simple one-time calls
+- [MultiRecordResource](./multi-record-resource.md) - For Collections/lists, supports CRUD and pagination
+- [SingleRecordResource](./single-record-resource.md) - For single records

package/dist/ai/docs/runjs/resource/multi-record-resource.md

@@ -1,102 +1,102 @@
 # MultiRecordResource
 
-Resource for **data tables/lists**: request returns an array; supports pagination, filter, sort, and CRUD. Use for tables, lists, and other "multiple records" scenarios. Unlike [APIResource](./api-resource.md), MultiRecordResource uses `setResourceName()` to specify resource name and auto-builds URLs like `users:list`, `users:create`, with built-in pagination, filter, and selected rows.
+A collection-oriented Resource: requests return an array and support pagination, filtering, sorting, and CRUD operations. It is suitable for "multiple records" scenarios such as tables and lists. Unlike [APIResource](./api-resource.md), MultiRecordResource specifies the resource name via `setResourceName()`, automatically constructs URLs like `users:list` and `users:create`, and includes built-in capabilities for pagination, filtering, and row selection.
 
 **Inheritance**: FlowResource → APIResource → BaseRecordResource → MultiRecordResource.
 
-**Create with**: `ctx.makeResource('MultiRecordResource')` or `ctx.initResource('MultiRecordResource')`. Before use call `setResourceName('collectionName')` (e.g. `'users'`); RunJS injects `ctx.api`.
+**Creation**: `ctx.makeResource('MultiRecordResource')` or `ctx.initResource('MultiRecordResource')`. Before use, you must call `setResourceName('collectionName')` (e.g., `'users'`). In RunJS, `ctx.api` is injected by the runtime environment.
 
 ---
 
-## Use cases
+## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **Table block** | Table and list blocks use MultiRecordResource by default; pagination, filter, sort |
-| **JSBlock list** | Load users, orders, etc. in JSBlock and render custom UI |
-| **Batch operations** | Use `getSelectedRows()` for selected rows, `destroySelectedRows()` for batch delete |
-| **Association resources** | Load associated data with `users.tags`; requires `setSourceId(parentRecordId)` |
+|------|------|
+| **Table Blocks** | Table and list blocks use MultiRecordResource by default, supporting pagination, filtering, and sorting. |
+| **JSBlock Lists** | Load data from collections like users or orders in a JSBlock and perform custom rendering. |
+| **Bulk Operations** | Use `getSelectedRows()` to get selected rows and `destroySelectedRows()` for bulk deletion. |
+| **Association Resources** | Load associated collections using formats like `users.tags`, which requires `setSourceId(parentRecordId)`. |
 
 ---
 
-## Data format
+## Data Format
 
-- `getData()` returns a **record array**, i.e. the list API `data` field
-- `getMeta()` returns pagination meta: `page`, `pageSize`, `count`, `totalPage`, etc.
+- `getData()` returns an **array of records**, which is the `data` field from the list API response.
+- `getMeta()` returns pagination and other metadata: `page`, `pageSize`, `count`, `totalPage`, etc.
 
 ---
 
-## Resource name and data source
+## Resource Name and Data Source
 
 | Method | Description |
-|--------|-------------|
-| `setResourceName(name)` / `getResourceName()` | Resource name, e.g. `'users'`, `'users.tags'` (association) |
-| `setSourceId(id)` / `getSourceId()` | Parent record id for association resources (e.g. `users.tags` needs users primary key) |
-| `setDataSourceKey(key)` / `getDataSourceKey()` | Data source key (for multiple data sources) |
+|------|------|
+| `setResourceName(name)` / `getResourceName()` | The resource name, e.g., `'users'`, `'users.tags'` (association resource). |
+| `setSourceId(id)` / `getSourceId()` | The parent record ID for association resources (e.g., for `users.tags`, pass the primary key of the user). |
+| `setDataSourceKey(key)` / `getDataSourceKey()` | Data source identifier (used in multi-data source scenarios). |
 
 ---
 
-## Request params (filter / fields / sort)
+## Request Parameters (Filter / Fields / Sort)
 
 | Method | Description |
-|--------|-------------|
-| `setFilterByTk(tk)` / `getFilterByTk()` | Primary key filter (single get, etc.) |
-| `setFilter(filter)` / `getFilter()` / `resetFilter()` | Filter; supports `$eq`, `$ne`, `$in`, etc. |
-| `addFilterGroup(key, filter)` / `removeFilterGroup(key)` | Filter groups (combine conditions) |
-| `setFields(fields)` / `getFields()` | Requested fields (whitelist) |
-| `setSort(sort)` / `getSort()` | Sort, e.g. `['-createdAt']` for created-at desc |
-| `setAppends(appends)` / `getAppends()` / `addAppends` / `removeAppends` | Association expansion (e.g. `['user', 'tags']`) |
+|------|------|
+| `setFilterByTk(tk)` / `getFilterByTk()` | Filter by primary key (for single record `get`, etc.). |
+| `setFilter(filter)` / `getFilter()` / `resetFilter()` | Filter conditions, supporting operators like `$eq`, `$ne`, `$in`, etc. |
+| `addFilterGroup(key, filter)` / `removeFilterGroup(key)` | Filter groups (for combining multiple conditions). |
+| `setFields(fields)` / `getFields()` | Requested fields (whitelist). |
+| `setSort(sort)` / `getSort()` | Sorting, e.g., `['-createdAt']` for descending order by creation time. |
+| `setAppends(appends)` / `getAppends()` / `addAppends` / `removeAppends` | Association loading (e.g., `['user', 'tags']`). |
 
 ---
 
 ## Pagination
 
 | Method | Description |
-|--------|-------------|
-| `setPage(page)` / `getPage()` | Current page (1-based) |
-| `setPageSize(size)` / `getPageSize()` | Page size, default 20 |
-| `getTotalPage()` | Total pages |
-| `getCount()` | Total count (from server meta) |
-| `next()` / `previous()` / `goto(page)` | Change page and trigger refresh |
+|------|------|
+| `setPage(page)` / `getPage()` | Current page (starting from 1). |
+| `setPageSize(size)` / `getPageSize()` | Number of items per page, default is 20. |
+| `getTotalPage()` | Total number of pages. |
+| `getCount()` | Total number of records (from server-side meta). |
+| `next()` / `previous()` / `goto(page)` | Change page and trigger `refresh`. |
 
 ---
 
-## Selected rows (table)
+## Selected Rows (Table Scenarios)
 
 | Method | Description |
-|--------|-------------|
-| `setSelectedRows(rows)` / `getSelectedRows()` | Currently selected row data for batch delete, etc. |
+|------|------|
+| `setSelectedRows(rows)` / `getSelectedRows()` | Currently selected row data, used for bulk deletion and other operations. |
 
 ---
 
-## CRUD and list operations
+## CRUD and List Operations
 
 | Method | Description |
-|--------|-------------|
-| `refresh()` | Request list with current params; update `getData()` and pagination meta; emit `'refresh'` |
-| `get(filterByTk)` | Request single record; returns that record (does not write to getData) |
-| `create(data, options?)` | Create; optional `{ refresh: false }` to skip auto refresh; emit `'saved'` |
-| `update(filterByTk, data, options?)` | Update by primary key |
-| `destroy(target)` | Delete; target can be primary key, row object, or array (batch delete) |
-| `destroySelectedRows()` | Delete selected rows (throws if none selected) |
-| `setItem(index, item)` | Replace one row locally (no request) |
-| `runAction(actionName, options)` | Call any resource action (e.g. custom action) |
+|------|------|
+| `refresh()` | Requests the list with current parameters, updates `getData()` and pagination meta, and triggers the `'refresh'` event. |
+| `get(filterByTk)` | Requests a single record and returns it (does not write to `getData`). |
+| `create(data, options?)` | Creates a record. Optional `{ refresh: false }` prevents automatic refresh. Triggers `'saved'`. |
+| `update(filterByTk, data, options?)` | Updates a record by its primary key. |
+| `destroy(target)` | Deletes records. `target` can be a primary key, a row object, or an array of primary keys/row objects (bulk delete). |
+| `destroySelectedRows()` | Deletes currently selected rows (throws an error if none are selected). |
+| `setItem(index, item)` | Replaces a specific row of data locally (does not initiate a request). |
+| `runAction(actionName, options)` | Calls any resource action (e.g., custom actions). |
 
 ---
 
-## Config and events
+## Configuration and Events
 
 | Method | Description |
-|--------|-------------|
-| `setRefreshAction(name)` | Action used for refresh; default `'list'` |
-| `setCreateActionOptions(options)` / `setUpdateActionOptions(options)` | Request config for create/update |
-| `on('refresh', fn)` / `on('saved', fn)` | Fired when refresh completes or after save |
+|------|------|
+| `setRefreshAction(name)` | The action called during refresh, default is `'list'`. |
+| `setCreateActionOptions(options)` / `setUpdateActionOptions(options)` | Request configuration for create/update. |
+| `on('refresh', fn)` / `on('saved', fn)` | Triggered after refresh completion or after saving. |
 
 ---
 
 ## Examples
 
-### Basic list
+### Basic List
 
 ```js
 ctx.initResource('MultiRecordResource');
@@ -107,7 +107,7 @@ const rows = ctx.resource.getData();
 const total = ctx.resource.getCount();
 ```
 
-### Filter and sort
+### Filtering and Sorting
 
 ```js
 ctx.resource.setResourceName('users');
@@ -117,7 +117,7 @@ ctx.resource.setFields(['id', 'nickname', 'email']);
 await ctx.resource.refresh();
 ```
 
-### Association expansion
+### Association Loading
 
 ```js
 ctx.resource.setResourceName('orders');
@@ -126,17 +126,17 @@ await ctx.resource.refresh();
 const orders = ctx.resource.getData();
 ```
 
-### Create and pagination
+### Create and Pagination
 
 ```js
-await ctx.resource.create({ name: 'John', email: 'john@example.com' });
+await ctx.resource.create({ name: 'John Doe', email: 'john.doe@example.com' });
 
 await ctx.resource.next();
 await ctx.resource.previous();
 await ctx.resource.goto(3);
 ```
 
-### Batch delete selected rows
+### Bulk Delete Selected Rows
 
 ```js
 const rows = ctx.resource?.getSelectedRows?.() || [];
@@ -148,7 +148,7 @@ await ctx.resource.destroySelectedRows();
 ctx.message.success(ctx.t('Deleted'));
 ```
 
-### Listen to refresh event
+### Listening to the refresh Event
 
 ```js
 ctx.resource?.on?.('refresh', () => {
@@ -158,7 +158,7 @@ ctx.resource?.on?.('refresh', () => {
 await ctx.resource?.refresh?.();
 ```
 
-### Association resource (child table)
+### Association Resource (Sub-table)
 
 ```js
 const res = ctx.makeResource('MultiRecordResource');
@@ -172,17 +172,17 @@ const roles = res.getData();
 
 ## Notes
 
-- **setResourceName required**: Must call `setResourceName('collectionName')` before use; otherwise request URL cannot be built.
-- **Association resources**: When resource name is `parent.child` (e.g. `users.tags`), call `setSourceId(parentPrimaryKey)` first.
-- **refresh debounce**: Multiple `refresh()` calls in the same event loop only run the last one to avoid duplicate requests.
-- **getData is array**: List API returns `data` as record array; `getData()` returns that array directly.
+- **setResourceName is Required**: You must call `setResourceName('collectionName')` before use, otherwise the request URL cannot be constructed.
+- **Association Resources**: When the resource name is in the format `parent.child` (e.g., `users.tags`), you must call `setSourceId(parentPrimaryKey)` first.
+- **Refresh Debouncing**: Multiple calls to `refresh()` within the same event loop will only execute the last one to avoid redundant requests.
+- **getData returns an Array**: The `data` returned by the list API is an array of records, and `getData()` returns this array directly.
 
 ---
 
 ## Related
 
-- [ctx.resource](../context/resource.md) - Resource instance in current context
+- [ctx.resource](../context/resource.md) - The resource instance in the current context
 - [ctx.initResource()](../context/init-resource.md) - Initialize and bind to ctx.resource
-- [ctx.makeResource()](../context/make-resource.md) - Create resource instance without binding
-- [APIResource](./api-resource.md) - Generic API resource, request by URL
-- [SingleRecordResource](./single-record-resource.md) - For single records
+- [ctx.makeResource()](../context/make-resource.md) - Create a new resource instance without binding
+- [APIResource](./api-resource.md) - General API resource requested by URL
+- [SingleRecordResource](./single-record-resource.md) - Oriented towards a single record