@nocobase/plugin-flow-engine 2.1.0-alpha.9 → 2.1.0-beta.10

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

@@ -1,73 +1,73 @@
 # APIResource
 
-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.
+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.
 
-**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.
+**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.
 
 ---
 
-## Use Cases
+## Use cases
 
 | Scenario | Description |
-|------|------|
-| **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. |
+|----------|-------------|
+| **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 |
 
 ---
 
-## Base Class Capabilities (FlowResource)
+## Base (FlowResource)
 
-All Resources possess the following:
+All resources support:
 
 | Method | Description |
-|------|------|
-| `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. |
+|--------|-------------|
+| `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 |
 
 ---
 
-## Request Configuration
+## Request config
 
 | Method | Description |
-|------|------|
-| `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. |
+|--------|-------------|
+| `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 |
 
 ---
 
-## URL Format
+## URL format
 
-- **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.
+- **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
 
 ---
 
-## Data Fetching
+## Data fetch
 
 | Method | Description |
-|------|------|
-| `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. |
+|--------|-------------|
+| `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. |
 
 ---
 
 ## 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 Request Body)
+### POST request (with 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();
 ```
 
-### Listening to the refresh Event
+### Listen to 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 Request Headers
+### Custom headers
 
 ```js
 const res = ctx.makeResource('APIResource');
@@ -138,18 +138,18 @@ await res.refresh();
 
 ## Notes
 
-- **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.
+- **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.
 
 ---
 
 ## Related
 
-- [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
+- [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

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

@@ -1,102 +1,102 @@
 # MultiRecordResource
 
-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.
+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.
 
 **Inheritance**: FlowResource → APIResource → BaseRecordResource → MultiRecordResource.
 
-**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.
+**Create with**: `ctx.makeResource('MultiRecordResource')` or `ctx.initResource('MultiRecordResource')`. Before use call `setResourceName('collectionName')` (e.g. `'users'`); RunJS injects `ctx.api`.
 
 ---
 
-## Use Cases
+## Use cases
 
 | Scenario | Description |
-|------|------|
-| **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)`. |
+|----------|-------------|
+| **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)` |
 
 ---
 
-## Data Format
+## Data format
 
-- `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.
+- `getData()` returns a **record array**, i.e. the list API `data` field
+- `getMeta()` returns pagination meta: `page`, `pageSize`, `count`, `totalPage`, etc.
 
 ---
 
-## Resource Name and Data Source
+## Resource name and data source
 
 | Method | Description |
-|------|------|
-| `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). |
+|--------|-------------|
+| `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) |
 
 ---
 
-## Request Parameters (Filter / Fields / Sort)
+## Request params (filter / fields / sort)
 
 | Method | Description |
-|------|------|
-| `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']`). |
+|--------|-------------|
+| `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']`) |
 
 ---
 
 ## Pagination
 
 | Method | Description |
-|------|------|
-| `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`. |
+|--------|-------------|
+| `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 |
 
 ---
 
-## Selected Rows (Table Scenarios)
+## Selected rows (table)
 
 | Method | Description |
-|------|------|
-| `setSelectedRows(rows)` / `getSelectedRows()` | Currently selected row data, used for bulk deletion and other operations. |
+|--------|-------------|
+| `setSelectedRows(rows)` / `getSelectedRows()` | Currently selected row data for batch delete, etc. |
 
 ---
 
-## CRUD and List Operations
+## CRUD and list operations
 
 | Method | Description |
-|------|------|
-| `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). |
+|--------|-------------|
+| `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) |
 
 ---
 
-## Configuration and Events
+## Config and events
 
 | Method | Description |
-|------|------|
-| `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. |
+|--------|-------------|
+| `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 |
 
 ---
 
 ## Examples
 
-### Basic List
+### Basic list
 
 ```js
 ctx.initResource('MultiRecordResource');
@@ -107,7 +107,7 @@ const rows = ctx.resource.getData();
 const total = ctx.resource.getCount();
 ```
 
-### Filtering and Sorting
+### Filter and sort
 
 ```js
 ctx.resource.setResourceName('users');
@@ -117,7 +117,7 @@ ctx.resource.setFields(['id', 'nickname', 'email']);
 await ctx.resource.refresh();
 ```
 
-### Association Loading
+### Association expansion
 
 ```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 Doe', email: 'john.doe@example.com' });
+await ctx.resource.create({ name: 'John', email: 'john@example.com' });
 
 await ctx.resource.next();
 await ctx.resource.previous();
 await ctx.resource.goto(3);
 ```
 
-### Bulk Delete Selected Rows
+### Batch delete selected rows
 
 ```js
 const rows = ctx.resource?.getSelectedRows?.() || [];
@@ -148,7 +148,7 @@ await ctx.resource.destroySelectedRows();
 ctx.message.success(ctx.t('Deleted'));
 ```
 
-### Listening to the refresh Event
+### Listen to refresh event
 
 ```js
 ctx.resource?.on?.('refresh', () => {
@@ -158,7 +158,7 @@ ctx.resource?.on?.('refresh', () => {
 await ctx.resource?.refresh?.();
 ```
 
-### Association Resource (Sub-table)
+### Association resource (child table)
 
 ```js
 const res = ctx.makeResource('MultiRecordResource');
@@ -172,17 +172,17 @@ const roles = res.getData();
 
 ## Notes
 
-- **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.
+- **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.
 
 ---
 
 ## Related
 
-- [ctx.resource](../context/resource.md) - The resource instance in the current context
+- [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 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
+- [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