@nocobase/plugin-ai 2.3.0-alpha.1 → 3.0.0-alpha.1

package/dist/ai/docs/nocobase/data-sources/data-modeling/collection-fields/datetime/time.md

@@ -1,13 +1,111 @@
+---
+title: "Time"
+description: "The Time field stores a time of day without a date."
+keywords: "Time,time,field,Field interface,NocoBase"
+---
+
 # Time
 
 ## Introduction
 
-## Field configuration
+In NocoBase, the **Time** field stores a time of day.
+
+It is suitable for opening times, shift times, reminder times, and other values where the date is not required. Use DateTime when both date and time are needed.
+
+## Use cases
+
+Time fields are suitable for these business scenarios:
+
+- Opening and closing times
+- Shift start and end times
+- Daily reminder times
+- Time-of-day business rules
+
+## Create and configure
+
+On the collection's **Configure fields** page, click **Add field** and select **Time** to create this field.
+
+![Configure a Time field](https://static-docs.nocobase.com/20240512181216.png)
+
+| Setting | Description |
+| --- | --- |
+| Field interface | The field interface. Time uses `time`, which determines how the field is entered and displayed in pages. |
+| Field display name | The name displayed for the field, such as `Opening time`, `Shift time`, or `Reminder time`. 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. Time uses `time` 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 time-range 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 Time field is as follows:
+
+| Behavior | Description |
+| --- | --- |
+| Default Field interface | `time`. |
+| Default Field type | `time`. |
+| Available Field types | `time`. |
+| Page component | Uses a time picker in edit mode. |
+| Filtering | Supports time filters such as before, after, range, is empty, and is not empty. |
+| Sorting | Supports chronological sorting in Table blocks. |
+| Validation | Supports time-range 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 Time field to delete it. You can also select multiple fields and delete them in the main data source.
+
+Deleting a Time 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
+
+Time fields are suitable for time-of-day entry, display, and business conditions.
 
+![Use a Time field in a page](https://static-docs.nocobase.com/20260709232726.png)
 
-![20240512181216](https://static-docs.nocobase.com/20240512181216.png)
 
+| Scenario | Use |
+| --- | --- |
+| Form block | Select a time. |
+| Table block | Display, sort, and filter times. |
+| Details block | Display a time value. |
+| Workflows and permissions | Use the time in business conditions. |
 
-## Example
+## Related links
 
-To be added.
+- [Fields](../index.md) - Learn about field categories and mapping.
+- [General collection](../../../data-source-main/general-collection.md) - Create and manage fields in a collection.

package/dist/ai/docs/nocobase/data-sources/data-modeling/collection-fields/datetime/unix-timestamp.md

@@ -1,13 +1,111 @@
-# Unix Timestamp
+---
+title: "Unix timestamp"
+description: "The Unix timestamp field stores timestamps from external systems as integer values."
+keywords: "Unix timestamp,unixTimestamp,field,Field interface,NocoBase"
+---
+
+# Unix timestamp
 
 ## Introduction
 
-## Field Configuration
+In NocoBase, the **Unix timestamp** field stores a Unix timestamp as an integer value.
+
+It is suitable for time values from external APIs, logs, and synchronized systems. Use DateTime when users need to enter and manage ordinary date-time values directly.
+
+## Use cases
+
+Unix timestamp fields are suitable for these business scenarios:
+
+- External API timestamps
+- Log and event timestamps
+- Synchronized system time values
+- Integer-based time values
+
+## Create and configure
+
+On the collection's **Configure fields** page, click **Add field** and select **Unix timestamp** to create this field.
+
+![Configure a Unix timestamp field](https://static-docs.nocobase.com/20240512180432.png)
+
+| Setting | Description |
+| --- | --- |
+| Field interface | The field interface. Unix timestamp uses `unixTimestamp`, which determines how the field is entered and displayed in pages. |
+| Field display name | The name displayed for the field, such as `External timestamp`, `Event timestamp`, or `Log time`. 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. Unix timestamp uses `integer` 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 timestamp-format 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 Unix timestamp field is as follows:
+
+| Behavior | Description |
+| --- | --- |
+| Default Field interface | `unixTimestamp`. |
+| Default Field type | `integer`. |
+| Available Field types | `integer`, `bigInt`. |
+| Page component | Uses a date-time presentation component for the timestamp where configured. |
+| Filtering | Supports date-time and numerical filters where supported by the field mapping. |
+| Sorting | Supports chronological sorting in Table blocks. |
+| Validation | Supports timestamp-format 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 Unix timestamp field to delete it. You can also select multiple fields and delete them in the main data source.
+
+Deleting a Unix timestamp 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
+
+Unix timestamp fields are suitable for external-system timestamps and integration data.
 
+![Use a Unix timestamp field in a page](https://static-docs.nocobase.com/20260709232558.png)
 
-![20240512180432](https://static-docs.nocobase.com/20240512180432.png)
 
+| Scenario | Use |
+| --- | --- |
+| Form block | Enter or display a timestamp where needed. |
+| Table block | Display, sort, and filter timestamps. |
+| Details block | Display a converted timestamp. |
+| Workflows and APIs | Pass integer-based time values to integrations. |
 
-## Example
+## Related links
 
-to be added.
+- [Fields](../index.md) - Learn about field categories and mapping.
+- [General collection](../../../data-source-main/general-collection.md) - Create and manage fields in a collection.

package/dist/ai/docs/nocobase/data-sources/data-modeling/collection-fields/geometric/circle.md

@@ -1,13 +1,111 @@
+---
+title: "Circle"
+description: "The Circle field stores a circular geographic area such as a service radius or coverage range."
+keywords: "Circle,circle,field,Field interface,NocoBase"
+---
+
 # Circle
 
 ## Introduction
 
-## Field configuration
+In NocoBase, the **Circle** field stores a circular geographic area.
+
+It is suitable for service radii, coverage ranges, impact ranges, and other circular geographic data.
+
+## Use cases
+
+Circle fields are suitable for these business scenarios:
+
+- Service radii
+- Coverage ranges
+- Impact ranges
+- Other circular geographic data
+
+## Create and configure
+
+On the collection's **Configure fields** page, click **Add field** and select **Circle** to create this field.
+
+![Configure a Circle field](https://static-docs.nocobase.com/20240512181522.png)
+
+| Setting | Description |
+| --- | --- |
+| Field interface | The field interface. Circle uses `circle`, which determines how the field is entered and displayed in pages. |
+| Field display name | The name displayed for the field, such as `Service radius`, `Coverage range`, or `Impact range`. 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. Circle uses `circle` 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 base validation such as required. |
+| 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 Circle field is as follows:
+
+| Behavior | Description |
+| --- | --- |
+| Default Field interface | `circle`. |
+| Default Field type | `circle`. |
+| Available Field types | `circle`. |
+| Page component | Uses a map-drawing component in edit mode. |
+| Filtering | Spatial filtering depends on map-plugin and data-source capabilities. |
+| Sorting | It is usually not used for sorting. |
+| Validation | Supports base validation such as required. |
+
+## 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 Circle field to delete it. You can also select multiple fields and delete them in the main data source.
+
+Deleting a Circle 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
+
+Circle fields are suitable for map display and radial geographic data.
 
+![Use a Circle field in a page](https://static-docs.nocobase.com/20260710145031.png)
 
-![20240512181522](https://static-docs.nocobase.com/20240512181522.png)
 
+| Scenario | Use |
+| --- | --- |
+| Form block | Draw or edit a circle on a map. |
+| Details block | Display a circular area. |
+| Map and geographic blocks | Show coverage or service radius. |
+| Workflows and APIs | Pass circular area data to business logic. |
 
-## Example
+## Related links
 
-To be added.
+- [Fields](../index.md) - Learn about field categories and mapping.
+- [General collection](../../../data-source-main/general-collection.md) - Create and manage fields in a collection.

package/dist/ai/docs/nocobase/data-sources/data-modeling/collection-fields/geometric/line.md

@@ -1,13 +1,111 @@
-# Line
+---
+title: "Line string"
+description: "The Line string field stores a geographic line such as a delivery route, inspection track, or pipeline."
+keywords: "Line string,lineString,field,Field interface,NocoBase"
+---
+
+# Line string
 
 ## Introduction
 
-## Field configuration
+In NocoBase, the **Line string** field stores a geographic line.
+
+It is suitable for delivery routes, inspection tracks, pipelines, and other linear geographic data.
+
+## Use cases
+
+Line string fields are suitable for these business scenarios:
+
+- Delivery routes
+- Inspection tracks
+- Pipelines
+- Other linear geographic data
+
+## Create and configure
+
+On the collection's **Configure fields** page, click **Add field** and select **Line string** to create this field.
+
+![Configure a Line string field](https://static-docs.nocobase.com/20240512181454.png)
+
+| Setting | Description |
+| --- | --- |
+| Field interface | The field interface. Line string uses `lineString`, which determines how the field is entered and displayed in pages. |
+| Field display name | The name displayed for the field, such as `Delivery route`, `Inspection track`, or `Pipeline`. 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. Line string uses `lineString` 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 base validation such as required. |
+| 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 Line string field is as follows:
+
+| Behavior | Description |
+| --- | --- |
+| Default Field interface | `lineString`. |
+| Default Field type | `lineString`. |
+| Available Field types | `lineString`. |
+| Page component | Uses a map-drawing component in edit mode. |
+| Filtering | Spatial filtering depends on map-plugin and data-source capabilities. |
+| Sorting | It is usually not used for sorting. |
+| Validation | Supports base validation such as required. |
+
+## 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 Line string field to delete it. You can also select multiple fields and delete them in the main data source.
+
+Deleting a Line string 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
+
+Line string fields are suitable for map display and linear geographic data.
 
+![Use a Line string field in a page](https://static-docs.nocobase.com/20260710144453.png)
 
-![20240512181454](https://static-docs.nocobase.com/20240512181454.png)
 
+| Scenario | Use |
+| --- | --- |
+| Form block | Draw or edit a line on a map. |
+| Details block | Display a geographic line. |
+| Map and geographic blocks | Show a route or track in a map context. |
+| Workflows and APIs | Pass line data to business logic. |
 
-## Example
+## Related links
 
-to be added.
+- [Fields](../index.md) - Learn about field categories and mapping.
+- [General collection](../../../data-source-main/general-collection.md) - Create and manage fields in a collection.

package/dist/ai/docs/nocobase/data-sources/data-modeling/collection-fields/geometric/point.md

@@ -1,13 +1,111 @@
+---
+title: "Point"
+description: "The Point field stores a geographic point such as a store, device, or customer location."
+keywords: "Point,point,field,Field interface,NocoBase"
+---
+
 # Point
 
 ## Introduction
 
-## Field configuration
+In NocoBase, the **Point** field stores a geographic point.
+
+It is suitable for store locations, device coordinates, customer locations, and other single-point geographic data.
+
+## Use cases
+
+Point fields are suitable for these business scenarios:
+
+- Store locations
+- Device coordinates
+- Customer locations
+- Other single-point geographic data
+
+## Create and configure
+
+On the collection's **Configure fields** page, click **Add field** and select **Point** to create this field.
+
+![Configure a Point field](https://static-docs.nocobase.com/20240512181420.png)
+
+| Setting | Description |
+| --- | --- |
+| Field interface | The field interface. Point uses `point`, which determines how the field is entered and displayed in pages. |
+| Field display name | The name displayed for the field, such as `Store location`, `Device coordinates`, or `Customer location`. 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. Point uses `point` 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 base validation such as required. |
+| 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 Point field is as follows:
+
+| Behavior | Description |
+| --- | --- |
+| Default Field interface | `point`. |
+| Default Field type | `point`. |
+| Available Field types | `point`. |
+| Page component | Uses a map or coordinate-selection component in edit mode. |
+| Filtering | Spatial filtering depends on map-plugin and data-source capabilities. |
+| Sorting | It is usually not used for sorting. |
+| Validation | Supports base validation such as required. |
+
+## 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 Point field to delete it. You can also select multiple fields and delete them in the main data source.
+
+Deleting a Point 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
+
+Point fields are suitable for map display and geographic business data.
 
+![Use a Point field in a page](https://static-docs.nocobase.com/20260710144034.png)
 
-![20240512181420](https://static-docs.nocobase.com/20240512181420.png)
 
+| Scenario | Use |
+| --- | --- |
+| Form block | Select a location on a map or enter coordinates. |
+| Details block | Display a point location. |
+| Map and geographic blocks | Show a location in a map context. |
+| Workflows and APIs | Pass geographic point data to business logic. |
 
-## Example
+## Related links
 
-To be added.
+- [Fields](../index.md) - Learn about field categories and mapping.
+- [General collection](../../../data-source-main/general-collection.md) - Create and manage fields in a collection.