@nocobase/plugin-ai 2.2.0-alpha.1 → 2.2.0-alpha.10

package/dist/ai/docs/nocobase/data-sources/field-markdown-vditor/index.md

@@ -1,13 +1,113 @@
-# Markdown (Vditor)
+---
+title: "Markdown Vditor"
+description: "The Markdown Vditor field uses the Vditor editor to edit Markdown content."
+keywords: "Markdown Vditor,vditor,field,Field interface,NocoBase"
+---
+
+# Markdown Vditor
 
 ## Introduction
 
-## Field Configuration
+In NocoBase, **Markdown Vditor** uses the Vditor editor to edit Markdown content.
+
+It is suitable for content needing a fuller Markdown editing experience, such as comment bodies, knowledge-base content, and proposal descriptions. Use Markdown for simple editing or Rich text for a WYSIWYG experience.
+
+## Use cases
+
+Markdown Vditor fields are suitable for these business scenarios:
+
+- Comment bodies
+- Knowledge-base content
+- Proposal descriptions
+- Long Markdown documents
+
+## Create and configure
+
+On the collection's **Configure fields** page, click **Add field** and select **Markdown Vditor** to create this field.
+
+![Configure a Markdown Vditor field](https://static-docs.nocobase.com/20240512180647.png)
+
+| Setting | Description |
+| --- | --- |
+| Field interface | The field interface. Markdown Vditor uses `vditor`, which determines how the field is entered and displayed in pages. |
+| Field display name | The name displayed for the field, such as `Comment content`, `Knowledge-base body`, or `Proposal description`. Use a name that business users can recognize. |
+| Field name | The field identifier used internally by APIs, relation fields, permissions, and workflows. It usually cannot be changed after creation. It supports only letters, numbers, and underscores, and must begin with a letter. |
+| Field type | The data-layer type. Markdown Vditor uses `text` by default. |
+| Default value | The default value. When a new record has no value, NocoBase can fill this value automatically. |
+| Validation rules | Validation rules. Supports length and required validation. |
+| Description | A field description. Record the field meaning, entry requirements, data source, or maintainer. |
+
+:::warning Note
+
+Field names are referenced by page blocks, permissions, workflows, and APIs after creation. Confirm the name before creating the field to avoid later configuration changes.
+
+:::
+
+## Field behavior
+
+The default behavior of a Markdown Vditor field is as follows:
+
+| Behavior | Description |
+| --- | --- |
+| Default Field interface | `vditor`. |
+| Default Field type | `text`. |
+| Available Field types | `text`. |
+| Page component | Uses the Vditor Markdown editor in edit mode. |
+| Filtering | Supports text filters where supported by the data source. |
+| Sorting | Supports sorting in Table blocks where supported by the data source. |
+| Validation | Supports length and required validation. |
+
+## Edit configuration
+
+After creation, click **Edit** beside the field to edit its configuration. Edit fields to adjust how they are displayed and used in NocoBase, such as the display name, description, default value, validation rules, or field-specific settings.
+
+When a field comes from a synchronized main-database table, editing usually maps the database field to a NocoBase Field type and Field interface.
+
+| Setting | Can be edited | Description |
+| --- | --- | --- |
+| Field display name | Yes | Changes the name displayed in the interface without changing the field identifier. |
+| Field name | No | The field identifier normally cannot be changed in the edit form after creation. |
+| Field interface | Conditional | Main-database fields and synchronized fields can be adjusted during field mapping. Changes affect page input, display, and validation. |
+| Field type | Conditional | Main-database fields and synchronized fields can be adjusted during field mapping. Confirm that existing values can be used by the new type first. |
+| Default value | Yes | Adjusts the default value for new records. |
+| Validation rules | Yes | Adjusts field validation rules. |
+| Description | Yes | Adds the field meaning, entry requirements, data source, or maintainer. |
+
+:::warning Note
+
+Changing a Field type or Field interface is more than changing a display name. It affects field storage, input components, validation rules, filters, and workflow-variable usage. When the field contains substantial existing data, confirm that its data format is compatible first.
+
+:::
+
+## Delete field
+
+Click **Delete** beside a Markdown Vditor field to delete it. You can also select multiple fields and delete them in the main data source.
+
+Deleting a Markdown Vditor field created in the main database usually also deletes the actual database column and its values. For a synchronized or external-data-source field, the impact depends on the corresponding data source and field origin.
+
+:::danger Warning
+
+Deleting a field can affect page blocks, forms, filters, permissions, workflows, APIs, imports and exports, and existing data. Confirm that the field is no longer referenced by business configuration before deleting it.
+
+:::
+
+## Use in pages
+
+Markdown Vditor fields are suitable for advanced Markdown editing in forms and details.
 
+![Use a Markdown Vditor field in a page](https://static-docs.nocobase.com/20260709230930.png)
 
-![20240512180647](https://static-docs.nocobase.com/20240512180647.png)
 
+| Scenario | Use |
+| --- | --- |
+| Form block | Edit Markdown content with Vditor. |
+| Details block | Render Markdown content. |
+| Table block | Display a shortened content value. |
+| Workflows and APIs | Pass Markdown text to business logic. |
 
-## Example
+## Related links
 
-Coming soon.
+- [Fields](../data-modeling/collection-fields/index.md) - Learn about field categories and mapping.
+- [General collection](../data-source-main/general-collection.md) - Create and manage fields in a collection.
+- [Markdown](../data-modeling/collection-fields/media/markdown.md) - Store simple Markdown content.
+- [Rich text](../data-modeling/collection-fields/media/rich-text.md) - Store WYSIWYG content.

package/dist/ai/docs/nocobase/data-sources/field-sequence/index.md

@@ -1,17 +1,114 @@
 ---
-pkg: "@nocobase/plugin-field-sequence"
+title: "Sequence"
+description: "The Sequence field generates readable business numbers such as order, contract, and work-order numbers."
+keywords: "Sequence,sequence,field,Field interface,NocoBase"
 ---
 
 # Sequence
 
 ## Introduction
 
-## Field Configuration
+In NocoBase, **Sequence** generates business numbers.
 
+It is suitable for order numbers, contract numbers, work-order numbers, and application numbers that need readable rules. Unlike a primary key, it is intended for business display and manual identification. Use Snowflake ID, UUID, or Nano ID for internal unique identifiers.
 
-![20240512173752](https://static-docs.nocobase.com/20240512173752.png)
+## Use cases
 
+Sequence fields are suitable for these business scenarios:
 
-## Example
+- Order numbers
+- Contract numbers
+- Work-order numbers
+- Application numbers
 
-To be added
+## Create and configure
+
+On the collection's **Configure fields** page, click **Add field** and select **Sequence** to create this field.
+
+![Configure a Sequence field](https://static-docs.nocobase.com/20240512173752.png)
+
+| Setting | Description |
+| --- | --- |
+| Field interface | The field interface. Sequence uses `sequence`, which determines how the field is entered and displayed in pages. |
+| Field display name | The name displayed for the field, such as `Order number`, `Contract number`, or `Work-order number`. Use a name that business users can recognize. |
+| Field name | The field identifier used internally by APIs, relation fields, permissions, and workflows. It usually cannot be changed after creation. It supports only letters, numbers, and underscores, and must begin with a letter. |
+| Field type | The data-layer type. Sequence uses `string` by default. |
+| Default value | The default value. When a new record has no value, NocoBase can fill this value automatically. |
+| Validation rules | Validation rules. Is normally generated by the system according to rules and does not need manual validation. |
+| Description | A field description. Record the field meaning, entry requirements, data source, or maintainer. |
+
+:::warning Note
+
+Field names are referenced by page blocks, permissions, workflows, and APIs after creation. Confirm the name before creating the field to avoid later configuration changes.
+
+:::
+
+## Field behavior
+
+The default behavior of a Sequence field is as follows:
+
+| Behavior | Description |
+| --- | --- |
+| Default Field interface | `sequence`. |
+| Default Field type | `string`. |
+| Available Field types | `string`. |
+| Page component | Displays a value generated according to sequence rules. |
+| Filtering | Supports text filters where supported by the data source. |
+| Sorting | Supports sorting in Table blocks. |
+| Validation | Is normally generated by the system according to rules and does not need manual validation. |
+
+## Edit configuration
+
+After creation, click **Edit** beside the field to edit its configuration. Edit fields to adjust how they are displayed and used in NocoBase, such as the display name, description, default value, validation rules, or field-specific settings.
+
+When a field comes from a synchronized main-database table, editing usually maps the database field to a NocoBase Field type and Field interface.
+
+| Setting | Can be edited | Description |
+| --- | --- | --- |
+| Field display name | Yes | Changes the name displayed in the interface without changing the field identifier. |
+| Field name | No | The field identifier normally cannot be changed in the edit form after creation. |
+| Field interface | Conditional | Main-database fields and synchronized fields can be adjusted during field mapping. Changes affect page input, display, and validation. |
+| Field type | Conditional | Main-database fields and synchronized fields can be adjusted during field mapping. Confirm that existing values can be used by the new type first. |
+| Default value | Yes | Adjusts the default value for new records. |
+| Validation rules | Yes | Adjusts field validation rules. |
+| Description | Yes | Adds the field meaning, entry requirements, data source, or maintainer. |
+
+:::warning Note
+
+Changing a Field type or Field interface is more than changing a display name. It affects field storage, input components, validation rules, filters, and workflow-variable usage. When the field contains substantial existing data, confirm that its data format is compatible first.
+
+:::
+
+## Delete field
+
+Click **Delete** beside a Sequence field to delete it. You can also select multiple fields and delete them in the main data source.
+
+Deleting a Sequence field created in the main database usually also deletes the actual database column and its values. For a synchronized or external-data-source field, the impact depends on the corresponding data source and field origin.
+
+:::danger Warning
+
+Deleting a field can affect page blocks, forms, filters, permissions, workflows, APIs, imports and exports, and existing data. Confirm that the field is no longer referenced by business configuration before deleting it.
+
+:::
+
+## Use in pages
+
+Sequence fields are suitable for readable business identifiers in pages and documents.
+
+![Use a Sequence field in a page](https://static-docs.nocobase.com/20260710151731.png)
+
+
+| Scenario | Use |
+| --- | --- |
+| Details block | Display a business number. |
+| Table block | Display, sort, and filter business numbers. |
+| Forms | Show a generated number where supported. |
+| Workflows and APIs | Use a business number in integrations. |
+
+## Related links
+
+- [Fields](../data-modeling/collection-fields/index.md) - Learn about field categories and mapping.
+- [General collection](../data-source-main/general-collection.md) - Create and manage fields in a collection.
+- [Snowflake ID](../data-modeling/collection-fields/advanced/snowflake-id.md) - Generate internal IDs.
+- [UUID](../data-modeling/collection-fields/advanced/uuid.md) - Generate UUID identifiers.
+- [Nano ID](../data-modeling/collection-fields/advanced/nano-id.md) - Generate short random identifiers.

package/dist/ai/docs/nocobase/data-sources/field-signature/index.md

@@ -2,35 +2,37 @@
 pkg: "@nocobase/plugin-field-signature"
 ---
 
-# Collection field: Signature
+# Collection field: Handwritten signature
 
 ## Introduction
 
-The handwritten signature field lets users draw a signature on the canvas (mouse or touch). After saving, the signature image is stored in the selected **file collection** and uses the file upload and storage pipeline provided by **File manager**.
+The Handwritten signature field lets users write a signature on a canvas with a mouse or touch screen. After saving, the signature image is written to the selected **File collection** and uses the file-upload and storage flow provided by **File manager**.
 
 ## Installation
 
-1. Confirm your deployment is on **Professional edition or above** and the license is valid.
-2. Open **Plugin manager**, find **Collection field: Handwritten Signature** (`@nocobase/plugin-field-signature`), and enable it.
-3. Ensure **File manager** (`@nocobase/plugin-file-manager`) is enabled. The handwritten signature field depends on it to provide file collections, uploads, and storage capabilities; without it, signature images cannot be saved.
+1. Confirm that the current environment is Professional edition or higher and has a valid license.
+2. Open **Plugin manager**, find **Collection field: Handwritten signature** (`@nocobase/plugin-field-signature`), and enable it.
+3. Enable **File manager** (`@nocobase/plugin-file-manager`). The Handwritten signature field depends on its File collection, upload, and storage capabilities; it cannot save signature images when File manager is disabled.
 
 ## Usage
 
-### Add the field
+### Add a field
 
-In **Data sources** → select a collection → **Configure fields** → **Add field** → choose **Handwritten Signature** (under the media group).
+Open **Data source** -> select a collection -> **Configure fields** -> **Add field**, then choose **Handwritten signature** in the Media group.
 
-### Field options
+### Field configuration
 
-- **File collection**: required. Select a file collection used to store files (for example, `attachments`), and the signature image will be saved there.
-- The actual storage used is determined by the selected file collection's own configuration.
+- **File collection**: Required. Select a File collection used to store files, such as `attachments`; signature images are saved there
+- The storage configuration and upload rules used by signature images are determined by the selected File collection
 
-### UI configuration
+### Interface configuration
 
-- After adding the handwritten signature field to a form, you can adjust **Signature settings** in the field UI configuration, including pen color, background color, canvas width, canvas height, thumbnail width, and thumbnail height.
-- In read-only display scenarios, you can also adjust the thumbnail width and height to control the rendered size of the signature image.
+- After adding a Handwritten signature field to a form, adjust **Signature settings** in the field interface settings, including stroke color, background color, signature-canvas width and height, and thumbnail width and height
+- In read-only display scenarios, adjust thumbnail width and height to control the display size of signature images
 
-### In the UI
+### Interface operations
 
-- Click the field to open the signature canvas, draw, then confirm to upload and link the corresponding file record.
-- On small screens, a full-screen / landscape signing experience may be used for easier drawing.
+- Click the field area to open the signature canvas. After writing, confirm the signature to upload and relate the corresponding file record
+- On small-screen devices, use a landscape or full-screen signature interface for easier writing
+
+![Handwritten signature](https://static-docs.nocobase.com/20260709232226.png)

package/dist/ai/docs/nocobase/data-sources/field-sort/index.md

@@ -1,163 +1,166 @@
 ---
 pkg: "@nocobase/plugin-field-sort"
+title: "Sort field"
+description: "Sort fields order collection records and support grouped ordering for custom record display order."
+keywords: "Sort field,Sort field,grouped sorting,sort,NocoBase"
 ---
 
-# Sort Field
+# Sort field
 
 ## Introduction
 
-Sort fields are used to sort records in a collection, supporting sorting within groups.
+In NocoBase, the **Sort** field records the sort value of collection records. It is commonly used for drag-and-drop ordering in blocks such as Tables and Kanban.
 
-:::warning
-Since the sort field is part of the same collection, a record cannot be assigned to multiple groups when using group sorting.
-:::
-
-## Installation
+Sort fields support ungrouped sorting and grouped sorting. Grouped sorting is suitable when records must be ordered independently inside each group, such as students ordered by class or tasks ordered by Kanban status.
 
-Built-in plugin, no separate installation required.
+:::warning Note
 
-## User Manual
-
-### Create a Sort Field
+Because a Sort field is a field in the same collection, grouped sorting does not support the same record appearing in multiple groups at the same time.
 
+:::
 
-![20240409091123_rec_](https://static-docs.nocobase.com/20240409091123_rec_.gif)
+## Installation
 
+The Sort field is provided by a built-in plugin and does not require separate installation.
 
-When creating sort fields, the sort values will be initialized:
+## Create a Sort field
 
-- If group sorting is not selected, initialization will be based on the primary key field and creation date field.
-- If group sorting is selected, the data will be grouped first, and then initialization will be based on the primary key field and creation date field.
+On the collection's **Configure fields** page, click **Add field** and select **Sort**.
 
-:::warning{title="Explanation of Transaction Consistency"}
-- When creating a field, if the sort value initialization fails, the sort field will not be created.
-- Within a certain range, if a record moves from position A to position B, the sort values of all records between A and B will change. If any part of this update fails, the entire move operation is rolled back, and the sort values of the related records will not change.
-:::
+![Create a Sort field](https://static-docs.nocobase.com/20240409091123_rec_.gif)
 
-#### Example 1: Create the sort1 field
+When creating a Sort field, NocoBase initializes sort values:
 
-The sort1 field is not grouped.
+- Without grouped sorting, it initializes values according to the primary key and Created at fields
+- With grouped sorting, it groups records first, then initializes values according to the primary key and Created at fields
 
+:::warning Note
 
-![20240409091510](https://static-docs.nocobase.com/20240409091510.png)
+If sort-value initialization fails during field creation, the Sort field is not created. Within a range, when one record moves from position A to B, the sort values of all records between A and B change. If updating any one record fails, the move fails and none of the related sort values change.
 
+:::
 
-The sort fields of each record will be initialized based on the primary key field and creation date field.
+### Create an ungrouped Sort field
 
+The following example creates a `sort1` field without grouped sorting.
 
-![20240409092305](https://static-docs.nocobase.com/20240409092305.png)
+![Create an ungrouped Sort field](https://static-docs.nocobase.com/20240409091510.png)
 
+Each record's Sort field is initialized according to its primary key and Created at field.
 
-#### Example 2: Create a sort2 field based on Class ID grouping
+![Initialized ungrouped Sort values](https://static-docs.nocobase.com/20240409092305.png)
 
+### Create a grouped Sort field
 
-![20240409092620](https://static-docs.nocobase.com/20240409092620.png)
+The following example creates a `sort2` field grouped by `Class ID`.
 
+![Create a grouped Sort field](https://static-docs.nocobase.com/20240409092620.png)
 
-At this time, all records in the collection will be grouped first (grouped by Class ID), and then the sort field (sort2) will be initialized. The initial values of each record are:
+All records in the collection are first grouped by `Class ID`, then their Sort field values are initialized.
 
+![Initialized grouped Sort values](https://static-docs.nocobase.com/20240409092847.png)
 
-![20240409092847](https://static-docs.nocobase.com/20240409092847.png)
+## Drag-and-drop sorting
 
+Sort fields are primarily used for drag-and-drop ordering of records in blocks. Table and Kanban blocks currently support drag-and-drop sorting.
 
-### Drag-and-Drop Sorting
+:::warning Note
 
-Sort fields are mainly used for drag-and-drop sorting of records in various blocks. The blocks that currently support drag-and-drop sorting include tables and boards.
+- Using the same Sort field for drag-and-drop sorting in multiple blocks can disrupt existing ordering
+- A Table block cannot use a grouped Sort field for drag-and-drop sorting
+- In a one-to-many relation Table block, the foreign key can be used as the group
+- Only Kanban blocks currently support grouped drag-and-drop sorting
 
-:::warning
-- When the same sort field is used for drag-and-drop sorting, using it across multiple blocks may disrupt the existing order.
-- The field for table drag-and-drop sorting cannot be a sort field with a grouping rule.
-  - Exception: In a one-to-many relationship table block, the foreign key can serve as a group.
-- Currently, only the board block supports drag-and-drop sorting within groups.
 :::
 
-#### Drag-and-Drop Sorting of Table Rows
-
-Table block
+### Drag-and-drop Table rows
 
+Table blocks can use Sort fields to adjust record order by drag and drop.
 
-![20240409104621_rec_](https://static-docs.nocobase.com/20240409104621_rec_.gif)
+![Drag-and-drop Table rows](https://static-docs.nocobase.com/20240409104621_rec_.gif)
 
+Relation Table blocks can also use Sort fields for drag-and-drop ordering.
 
-Relationship table block
+<video controls width="100%" src="https://static-docs.nocobase.com/20240409111903_rec_.mp4" title="Drag-and-drop sorting in a relation Table block"></video>
 
-<video controls width="100%" src="https://static-docs.nocobase.com/20240409111903_rec_.mp4" title="Title"></video>
+:::warning Note
 
-:::warning
-In a one-to-many relationship block:
+In a one-to-many relation block, when an ungrouped Sort field is selected, all records can participate in sorting. When records are grouped by the foreign key before sorting, the rule affects only data in the current group. The final display can look the same, but the set of records participating in the sort differs.
 
-- If an ungrouped sort field is selected, all records may participate in the sorting.
-- If records are first grouped by the foreign key and then sorted, the sorting rule will only affect the data within the current group.
-
-The final effect is consistent, but the number of records participating in the sort is different. For more details, see [Sorting Rule Explanation](#sorting-rule-explanation).
 :::
 
-#### Drag-and-Drop Sorting of Board Cards
-
+### Drag-and-drop Kanban cards
 
-![20240409110423_rec_](https://static-docs.nocobase.com/20240409110423_rec_.gif)
+Kanban blocks can use Sort fields to adjust card order by drag and drop.
 
+![Drag-and-drop Kanban cards](https://static-docs.nocobase.com/20240409110423_rec_.gif)
 
-### Sorting Rule Explanation
+## Sorting rules
 
-#### Displacement between ungrouped (or same-group) elements
+### Moving ungrouped records
 
-Suppose there is a set of data:
+Suppose records are ordered as follows:
 
-```
+```text
 [1,2,3,4,5,6,7,8,9]
 ```
 
-When an element, say 5, moves forward to the position of 3, only the positions of items 3, 4, and 5 change. Item 5 takes the position of 3, and items 3 and 4 each shift back one position.
+When 5 moves forward to the position of 3, only the positions of 3, 4, and 5 change. Record 5 takes the position of 3, and 3 and 4 each move one position backward.
 
-```
+```text
 [1,2,5,3,4,6,7,8,9]
 ```
 
-If we then move item 6 backward to the position of 8, item 6 takes the position of 8, and items 7 and 8 each shift forward one position.
+Then move 6 backward to the position of 8. Record 6 takes the position of 8, and 7 and 8 each move one position forward.
 
-```
+```text
 [1,2,5,3,4,7,8,6,9]
 ```
 
-#### Movement of elements between different groups
+### Moving between groups
 
-When sorting by group, if a record is moved to another group, its group assignment will also change. For example:
+With grouped sorting, when a record moves to another group, its own group also changes. Suppose there are two groups:
 
-```
+```text
 A: [1,2,3,4]
 B: [5,6,7,8]
 ```
 
-When item 1 is moved after item 6 (the default behavior), its group will also change from A to B.
+When 1 moves after 6, its group changes from A to B.
 
-```
+```text
 A: [2,3,4]
 B: [5,6,1,7,8]
 ```
 
-#### Sort changes are unrelated to the data displayed on the interface
+### Sorting changes are independent of displayed records
 
-For example, consider a set of data:
+Suppose records are ordered as follows:
 
-```
+```text
 [1,2,3,4,5,6,7,8,9]
 ```
 
-The interface only displays a filtered view:
+The interface displays only:
 
-```
+```text
 [1,5,9]
 ```
 
-When item 1 is moved to the position of item 9, the positions of all intermediate items (2, 3, 4, 5, 6, 7, 8) will also change, even though they are not visible.
+When 1 moves to the position of 9, the positions of 2, 3, 4, 5, 6, 7, and 8 also change.
 
-```
+```text
 [2,3,4,5,6,7,8,9,1]
 ```
 
-The interface now displays the new order based on the filtered items:
+The interface finally displays:
 
-```
+```text
 [5,9,1]
-```
+```
+
+## Related links
+
+- [Fields](../data-modeling/collection-fields/index.md) - Learn about field types and field mapping.
+- [Table block](../../interface-builder/blocks/data-blocks/table.md) - Use drag-and-drop sorting in a Table.
+- [Kanban block](../../interface-builder/blocks/data-blocks/kanban.md) - Use drag-and-drop sorting in Kanban.