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

package/dist/ai/docs/nocobase/data-sources/data-source-external-postgres/index.md

@@ -1,18 +1,122 @@
 ---
 pkg: "@nocobase/plugin-data-source-external-postgres"
+title: "External data source - PostgreSQL"
+description: "Connect PostgreSQL as an external NocoBase database, including version support, plugin installation, connection configuration, Schema, SSL, permissions, and field mapping."
+keywords: "external data source,PostgreSQL,external database,Schema,SSL,field mapping,NocoBase"
 ---
 
-# External Data Source - PostgreSQL
+# PostgreSQL
 
 ## Introduction
 
-Use an external PostgreSQL database as a data source. Currently supported versions: PostgreSQL >= 9.5
+PostgreSQL can be connected to NocoBase as an external database. NocoBase reads PostgreSQL tables, fields, and views and uses them as collections in the external data source.
 
-## Installation
+Unlike the [main database](../main/index.md), the original business system, database client, or migration scripts continue to maintain the real PostgreSQL schema. NocoBase reads structure, stores field metadata, and configures blocks, permissions, workflows, and APIs.
 
-This is a commercial plugin. For detailed activation instructions, please refer to: [Commercial Plugin Activation Guide](https://www.nocobase.com/en/blog/nocobase-commercial-license-activation-guide)
+| Setting | Description |
+| --- | --- |
+| Supported version | PostgreSQL >= 9.5. |
+| Commercial editions | Standard, Professional, and Enterprise. |
+| Plugin | `@nocobase/plugin-data-source-external-postgres`. |
 
+Use external PostgreSQL to connect existing ERP, MES, WMS, or CRM databases; build management pages without migrating historical data; apply permissions, workflows, corrections, or reports to existing tables; and leave schema maintenance to DBAs, migration scripts, or the original system.
 
-## Usage Instructions
+:::warning Note
 
-Refer to the [Data Source / External Database](/data-sources/data-source-manager/external-database) section.
+External PostgreSQL is not the NocoBase system database. NocoBase does not manage its backup, restore, migrations, or schema changes.
+
+:::
+
+## Plugin installation
+
+This is a commercial plugin. See the [commercial plugin activation guide](https://www.nocobase.com/en/blog/nocobase-commercial-license-activation-guide) for activation.
+
+## Add a data source
+
+In **Data source management**, click **Add new**, select PostgreSQL, and enter the connection information.
+
+![Add PostgreSQL](https://static-docs.nocobase.com/20260709204045.png)
+
+| Setting | Description |
+| --- | --- |
+| Data source name | Internal identifier used by blocks, permissions, workflows, and APIs. It cannot be changed after creation. |
+| Data source display name | Name shown in the interface, such as ERP PostgreSQL or Reporting database. |
+| Host / Port | PostgreSQL server address and port. The usual default port is `5432`. |
+| Database | The PostgreSQL database to connect. |
+| Username / Password | Connection credentials. NocoBase reads only objects that this account is allowed to access; it does not grant access to other users' private objects. |
+| Schema | The PostgreSQL schema to read, such as `public`. When several schemas exist, set only the schema required by the current business use. |
+| Table prefix | Limits reading to matching tables and views, and removes the prefix from the NocoBase collection name. |
+| Collections / Add all collections | Controls the imported scope. With **Add all collections** enabled, NocoBase imports all tables and views in scope; otherwise it imports only selected objects. |
+| Enabled the data source | Disables or enables access through blocks, permissions, workflows, and APIs while keeping the configuration. |
+| SSL options | PostgreSQL SSL settings, including SSL mode, unauthorized-certificate handling, and CA, client-certificate, and client-key paths. |
+
+:::tip Tip
+
+For a database with many objects, narrow the scope with `Schema`, `Table prefix`, and **Collections**. Import only tables and views that the application needs so that permission configuration, page building, and later synchronization remain manageable.
+
+:::
+
+## Select collections
+
+After connection settings are entered, click **Load Collections** to read available PostgreSQL tables and views. Results depend on the connection account, `Schema`, `Table prefix`, and **Collections** settings.
+
+**Add all collections** is enabled by default and imports every table and view in the current scope. Disable it and select individual tables or views when only part of the database is needed.
+
+![Select PostgreSQL collections](https://static-docs.nocobase.com/20260709204309.png)
+
+:::warning Note
+
+One external data source can import at most 500 tables or views. Narrow the scope with `Schema`, `Table prefix`, or **Collections** when PostgreSQL has many objects.
+
+:::
+
+## Synchronize and configure fields
+
+PostgreSQL maintains the external table structure. NocoBase does not create columns, change column types, or delete real fields in external PostgreSQL.
+
+When the PostgreSQL schema changes, use **Sync from database** to reread collection and field metadata. Synchronization updates NocoBase collections, fields, primary keys, unique keys, and type mappings; it does not delete real PostgreSQL tables or data.
+
+After synchronization, configure field titles, Field types, and Field interfaces in NocoBase. NocoBase relation fields are relation metadata only and do not automatically add real foreign-key columns to PostgreSQL.
+
+## Field type mapping
+
+NocoBase automatically maps PostgreSQL types to suitable Field types and Field interfaces. You can adjust the display interface in field configuration.
+
+| PostgreSQL type | NocoBase Field type | Available Field interfaces |
+| --- | --- | --- |
+| `BOOLEAN` | `boolean` | Checkbox, Switch. |
+| `SMALLINT`, `INTEGER`, `SERIAL`, `SMALLSERIAL` | `integer`, `boolean`, `sort` | Integer, Sort, Checkbox, Switch, Select, Radio group. |
+| `BIGINT`, `BIGSERIAL` | `bigInt`, `sort` | Integer, Sort, Checkbox, Switch, Select, Radio group, Unix timestamp, Created at, Updated at. |
+| `REAL` | `float` | Number, Percent. |
+| `DOUBLE PRECISION` | `double` | Number, Percent. |
+| `DECIMAL`, `NUMERIC` | `decimal` | Number, Percent, Currency. |
+| `VARCHAR`, `CHAR` | `string`, `password`, `uuid`, `nanoid` | Input, Email, Phone, Password, Color, Icon, Select, Radio group, UUID, Nano ID. |
+| `TEXT` | `text`, `json` | Textarea, Markdown, Vditor, Rich text, URL, JSON. |
+| `UUID` | `uuid` | UUID. |
+| `JSON`, `JSONB` | `json` | JSON. |
+| `TIMESTAMP` | `date` | Date, Time, Created at, Updated at. |
+| `DATE` | `dateOnly` | Date. |
+| `TIME` | `time` | Time. |
+| `POINT`, `LINESTRING`, `POLYGON`, `CIRCLE` | `point`, `lineString`, `polygon`, `circle` | Point, Line string, Polygon, Circle, JSON. |
+| `ARRAY` | `array` | Multiple select, Checkbox group. |
+
+:::warning Note
+
+Unsupported PostgreSQL types are shown separately in field configuration. They require development support before they can be used as normal NocoBase fields.
+
+:::
+
+## Primary key and Record unique key
+
+Collections used for block display and editing should have a primary key or unique field. NocoBase uses the primary key as the Record unique key when available.
+
+For views, tables without a primary key, or composite-primary-key tables, configure **Record unique key** manually. Without a usable identifier, blocks might not view, edit, or delete records correctly.
+
+![Primary key and Record unique key](https://static-docs.nocobase.com/20260709204742.png)
+![Configure Record unique key](https://static-docs.nocobase.com/20260709204827.png)
+
+## Related links
+
+- [External databases](./index.md) - General external-database configuration and management.
+- [Data source management](../data-source-manager/index.md) - Data-source entry points and management.
+- [Collection fields](../data-modeling/collection-fields/index.md) - Field types and mapping.

package/dist/ai/docs/nocobase/data-sources/data-source-kingbase/index.md

@@ -1,29 +1,42 @@
 ---
 pkg: "@nocobase/plugin-data-source-kingbase"
+title: "Main data source - KingbaseES"
+description: "Learn KingbaseES version support, installation, environment variables, Docker deployment, usage, and field mapping for the NocoBase main database."
+keywords: "main data source,KingbaseES,main database,PostgreSQL compatibility mode,field mapping,NocoBase"
 ---
 
-# Data Source - KingbaseES Database
+# KingbaseES
 
 ## Introduction
 
-KingbaseES can be used as a data source, either as the primary database or an external database.
+KingbaseES can be used as the NocoBase main database. It stores NocoBase system-table data and business data in the main data source. Configure it when deploying NocoBase; it cannot be deleted after the application is running.
+
+To connect an existing KingbaseES database as an external database, see [External KingbaseES](../external/kingbase.md).
+
+| Setting | Description |
+| --- | --- |
+| Supported version | >= V9. |
+| Commercial editions | Professional and Enterprise. |
+| Database type | PostgreSQL compatibility mode. |
+
+:::warning Note
+
+Only KingbaseES databases running in PostgreSQL compatibility mode are supported.
 
-:::warning
-Currently, only KingbaseES databases running in pg mode are supported.
 :::
 
 ## Installation
 
-### Using as the Primary Database
+### Use as the main database
 
-Refer to the Installation documentation for the setup procedures, the difference is mainly due to the environment variables.
+Follow [Install a NocoBase application](/ai/install-nocobase-app). The main difference is the database environment variables.
 
-#### Environment Variables
+#### Environment variables
 
-Edit the .env file to add or modify the following environment variable configurations:
+Add or update these database variables in `.env`:
 
 ```bash
-# Adjust DB parameters as needed
+# Adjust DB parameters for your environment.
 DB_DIALECT=kingbase
 DB_HOST=localhost
 DB_PORT=54321
@@ -32,7 +45,7 @@ DB_USER=nocobase
 DB_PASSWORD=nocobase
 ```
 
-#### Docker Installation
+#### Docker installation
 
 ```yml
 networks:
@@ -41,81 +54,94 @@ networks:
 
 services:
   app:
-    image: nocobase/nocobase:latest
+    image: registry.cn-shanghai.aliyuncs.com/nocobase/nocobase:latest
     restart: always
-    networks:
-      - nocobase
-    depends_on:
-      - kingbase
+    networks: [nocobase]
+    depends_on: [kingbase]
     environment:
-      # Application key for generating user tokens, etc.
-      # Changing APP_KEY invalidates old tokens
-      # Use a random string and keep it confidential
       - APP_KEY=your-secret-key
-      # Database type
       - DB_DIALECT=kingbase
-      # Database host, replace with existing database server IP if needed
       - DB_HOST=kingbase
       - DB_PORT=54321
-      # Database name
       - DB_DATABASE=kingbase
-      # Database user
       - DB_USER=nocobase
-      # Database password
       - DB_PASSWORD=nocobase
-      # Timezone
       - TZ=UTC
     volumes:
       - ./storage:/app/nocobase/storage
     ports:
       - "11000:80"
 
-  # Kingbase service for testing purposes only
   kingbase:
-    image: nocobase/kingbase:v009r001c001b0030_single_x86
+    image: registry.cn-shanghai.aliyuncs.com/nocobase/kingbase:v009r001c001b0030_single_x86
     platform: linux/amd64
     restart: always
     privileged: true
-    networks:
-      - nocobase
+    networks: [nocobase]
     volumes:
       - ./storage/db/kingbase:/home/kingbase/userdata
     environment:
-      ENABLE_CI: no # Must be set to no
+      ENABLE_CI: no
       DB_USER: nocobase
       DB_PASSWORD: nocobase
-      DB_MODE: pg  # pg only
+      DB_MODE: pg
       NEED_START: yes
     command: ["/usr/sbin/init"]
 ```
 
-#### Installation Using create-nocobase-app
+`APP_KEY` is used for user tokens and similar application secrets. Changing it invalidates existing tokens; use a random value and store it safely. The `kingbase` service is intended only for local evaluation. `DB_MODE` must be `pg`.
+
+#### Install with create-nocobase-app
 
 ```bash
 yarn create nocobase-app my-nocobase-app -d kingbase \
-   -e DB_HOST=localhost \
-   -e DB_PORT=54321 \
-   -e DB_DATABASE=kingbase \
-   -e DB_USER=nocobase \
-   -e DB_PASSWORD=nocobase \
-   -e TZ=UTC
+  -e DB_HOST=localhost \
+  -e DB_PORT=54321 \
+  -e DB_DATABASE=kingbase \
+  -e DB_USER=nocobase \
+  -e DB_PASSWORD=nocobase \
+  -e TZ=Asia/Shanghai
 ```
 
-### Using as an External Database
+### Use as an external database
 
-Execute the installation or upgrade command
+For configuration entry points, connection parameters, and synchronization rules when using KingbaseES as an external database, see [External KingbaseES](../external/kingbase.md).
 
-```bash
-yarn nocobase install
-# or
-yarn nocobase upgrade
-```
+## Usage
 
-Activate the Plugin
+KingbaseES main data sources use PostgreSQL compatibility mode. For everyday management, see [PostgreSQL main data source](../main/postgresql.md).
 
-![20241024121815](https://static-docs.nocobase.com/20241024121815.png)
+1. Select or enter KingbaseES connection settings when deploying NocoBase.
+2. After NocoBase starts, open **Data source management**, select **Main**, and manage collections and fields.
+3. Use **Sync from database** to connect tables that already exist in the main database.
+4. Use [Collections](../data-modeling/collection.md) and [Collection fields](../data-modeling/collection-fields/index.md) to choose Field types and Field interfaces.
 
-## User Guide
+## Field type mapping
+
+When you create a field in NocoBase, NocoBase creates the corresponding KingbaseES field. When you synchronize an existing table, NocoBase applies PostgreSQL-compatible mapping to select a Field type and Field interface.
+
+| KingbaseES type | NocoBase Field type | Available Field interfaces |
+| --- | --- | --- |
+| `BOOLEAN` | `boolean` | Checkbox, Switch. |
+| `SMALLINT`, `INTEGER` | `integer`, `sort` | Integer, Sort, Select, Radio group. |
+| `BIGINT` | `bigInt`, `snowflakeId`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Created at, Updated at. |
+| `REAL`, `DOUBLE PRECISION` | `float` | Number, Percent. |
+| `DECIMAL`, `NUMERIC` | `decimal` | Number, Percent, Currency. |
+| `VARCHAR`, `CHAR` | `string`, `uuid`, `nanoid`, `encryption`, `datetimeNoTz` | Input, Email, Phone, Password, Color, Icon, Select, Radio group, UUID, Nano ID. |
+| `TEXT` | `text` | Textarea, Markdown, Vditor, Rich text, URL. |
+| `UUID` | `uuid` | UUID. |
+| `JSON`, `JSONB` | `json`, `array` | JSON. |
+| `TIMESTAMP WITHOUT TIME ZONE` | `datetimeNoTz` | Date, Time, Created at, Updated at. |
+| `TIMESTAMP WITH TIME ZONE` | `datetimeTz`, `date` | Date, Time, Created at, Updated at. |
+| `DATE` | `dateOnly` | Date. |
+| `TIME WITHOUT TIME ZONE` | `time` | Time. |
+| `POINT`, `PATH`, `POLYGON`, `CIRCLE` | `json` | JSON. |
+| `ARRAY` | `array` | Multiple select, Checkbox group, JSON. |
+
+:::warning Note
+
+Unsupported KingbaseES types are shown separately in field configuration. They require development support before they can be used as normal NocoBase fields.
+
+:::
 
-- Primary Database: Refer to the [Main data source](/data-sources/data-source-main/index.md)
-- External Database: See [Data Source / External Database](/data-sources/data-source-manager/external-database)
+For common configuration, see [Main database](./index.md).

package/dist/ai/docs/nocobase/data-sources/data-source-main/general-collection.md

@@ -1,30 +1,131 @@
 ---
 pkg: "@nocobase/plugin-data-source-main"
+title: "General collection"
+description: "Use a General collection for common business data such as customers, orders, contracts, work orders, projects, and tasks."
+keywords: "General collection,system fields,collection,NocoBase"
 ---
 
-# General Collection
+# General collection
 
 ## Introduction
-It is used in most scenarios. A general collection can be used unless a special collection template is needed.
 
-## User Manual
+A **General collection** is the most common collection type. Use it for customers, orders, contracts, work orders, expense claims, projects, tasks, and other business records that do not need a special structure.
 
+General collections can come from a new table created in the main database, an existing main-database table synchronized into NocoBase, an external-database table, a resource mapped from a REST API, or a collection in an external NocoBase application.
 
-![20240324085739](https://static-docs.nocobase.com/20240324085739.png)
+All of these are used as general collections in NocoBase. The difference is that NocoBase can create and maintain the real table structure for a main-database collection, while an external source normally exposes an existing structure maintained by the external system.
 
-### Set Primary Key
+## Use cases
 
-When creating a collection, you need to specify a primary key field. It is recommended to enable the preset ID field when creating a new collection. The default primary key type for the ID field is Snowflake ID (53-bit).
+- CRM data such as customers, contacts, opportunities, and contracts.
+- Transaction data such as orders, deliveries, returns, and invoices.
+- Collaboration data such as work orders, tasks, projects, and requirements.
+- Process data such as expense claims, purchase orders, and payment requests.
+- Master data such as equipment, assets, products, and stores.
 
-![20251209210153](https://static-docs.nocobase.com/20251209210153.png)
+## Create and configure
 
-Hover over the Interface of the ID field to select other primary key types.
+In the main data source, click **Create collection** and select **General collection**.
 
-![20251209210517](https://static-docs.nocobase.com/20251209210517.png)
+![Create a general collection](https://static-docs.nocobase.com/20240324085739.png)
 
-Available primary key types include:
-- [Text](/data-sources/data-modeling/collection-fields/basic/input)
-- [Integer](/data-sources/data-modeling/collection-fields/basic/integer)
-- [Snowflake ID (53-bit)](/data-sources/data-modeling/collection-fields/advanced/snowflake-id)
-- [UUID](/data-sources/data-modeling/collection-fields/advanced/uuid)
-- [Nano ID](/data-sources/data-modeling/collection-fields/advanced/nano-id)
+| Setting | Description |
+| --- | --- |
+| Collection display name | The name displayed in the interface, such as Customers, Orders, or Contract attachments. Use a name business users can understand. |
+| Collection name | The internal identifier used by APIs, relation fields, permissions, and workflows. It is generated automatically but can be changed before creation. It supports letters, numbers, and underscores and must start with a letter. |
+| Categories | Organizes collections in data-source management without changing the collection structure. Use business modules such as Customer management, Projects, or Finance when many collections exist. |
+| Description | Document what the collection stores, who maintains it, and the related business processes. |
+| Use simple pagination mode | Skips total-record counting when table blocks paginate. Use it for very large collections to reduce query pressure. |
+| Preset fields | Adds common fields such as ID, created at, created by, updated at, and last updated by. Keep them for normal business collections. |
+
+### Built-in fields
+
+Use `Preset fields` to add common system fields when creating the collection.
+
+| Field | Field name | Description |
+| --- | --- | --- |
+| ID | `id` | The default primary key that uniquely identifies a record. Its default primary-key interface is `Snowflake ID (53-bit)`. |
+| Created at | `createdAt` | Records when a record was created. Use it for sorting, filtering, auditing, and workflow conditions. |
+| Created by | `createdBy` | Records the user who created the record. Use it for creator filtering, permissions, and ownership tracking. |
+| Updated at | `updatedAt` | Records when the record was last updated. |
+| Last updated by | `updatedBy` | Records the user who last updated the record. |
+| [Space](../../multi-app/multi-space/index.md) | `space` | Available when the multi-space plugin is enabled. It isolates data by space and is not shown in preset fields otherwise. |
+
+### Primary key field
+
+**Primary key** identifies a record uniquely at the database level. Keep the ID preset field when creating a collection; its default primary-key interface is `Snowflake ID (53-bit)`.
+
+![Primary key field](https://static-docs.nocobase.com/20251209210153.png)
+
+Hover over the ID field interface to select another primary-key type.
+
+![Select a primary-key interface](https://static-docs.nocobase.com/20251209210517.png)
+
+Available primary-key types are [Single line text](../data-modeling/collection-fields/basic/input.md), [Integer](../data-modeling/collection-fields/basic/integer.md), [Snowflake ID (53-bit)](../data-modeling/collection-fields/advanced/snowflake-id.md), [UUID](../data-modeling/collection-fields/advanced/uuid.md), and [Nano ID](../data-modeling/collection-fields/advanced/nano-id.md).
+
+:::warning Note
+
+A collection without a primary key must set a **Record unique key** when editing the collection. Otherwise, blocks cannot be created and records cannot be viewed or edited reliably.
+
+:::
+
+## Use in pages
+
+General collections can be used by most data and filter blocks.
+
+| Block | Use |
+| --- | --- |
+| [Table](../../interface-builder/blocks/data-blocks/table.md) | View, filter, sort, and batch-process records. |
+| [Form](../../interface-builder/blocks/data-blocks/form.md) | Create or edit one record. |
+| [Details](../../interface-builder/blocks/data-blocks/details.md) | View one record in detail. |
+| [List](../../interface-builder/blocks/data-blocks/list.md) | Display records as a list. |
+| [Grid card](../../interface-builder/blocks/data-blocks/grid-card.md) | Display images, files, products, assets, and other records as cards. |
+| [Kanban](../../interface-builder/blocks/data-blocks/kanban.md) | Group records by status, stage, owner, or another field. |
+| [Calendar](../../interface-builder/blocks/data-blocks/calendar.md) | Display records by date or time range. |
+| [Chart](../../interface-builder/blocks/data-blocks/chart.md) | Create statistics charts from records. |
+| [Map](../../interface-builder/blocks/data-blocks/map.md) | Display records by geographic location. |
+| [Gantt](../../plugins/@nocobase/plugin-gantt/index.md) | Display project plans and task schedules by start and end time. |
+| [Form filter](../../interface-builder/blocks/filter-blocks/form.md) | Filter data blocks with form conditions. |
+| [Tree filter](../../interface-builder/blocks/filter-blocks/tree.md) | Filter data blocks by hierarchy, such as category, organization, or region. |
+
+## Edit configuration
+
+Click **Edit** beside the collection to change collection metadata and selected runtime configuration. Use **Configure fields** to add fields, change Field types or interfaces, or delete fields.
+
+![Edit a collection](https://static-docs.nocobase.com/edit_collection.png)
+
+![Edit collection configuration](https://static-docs.nocobase.com/edit_collection_configure.png)
+
+| Setting | Can be edited | Description |
+| --- | --- | --- |
+| Collection display name | Yes | Changes only the name displayed in the interface. |
+| Collection name | No | The internal identifier cannot be changed after creation. |
+| Inherits | Conditional | Available only when the main database is PostgreSQL and the setting is displayed. Check fields, blocks, permissions, and workflows before changing inheritance for an existing collection. |
+| Categories | Yes | Organizes the management interface without changing the schema. |
+| Description | Yes | Document the collection purpose, maintainer, source, and related processes. |
+| Use simple pagination mode | Yes | Skips total-count queries in table blocks. |
+| Record unique key | Yes | Locates records in blocks. It normally uses a primary key or unique field. |
+
+:::warning Note
+
+Editing a collection does not adjust existing fields automatically. `Preset fields` apply only at creation. Add created-at, created-by, updated-at, or updated-by fields later through **Configure fields**.
+
+:::
+
+## Delete a collection
+
+Click **Delete** beside a general collection to delete it. Main-database collections can also be selected and deleted in batches.
+
+![Delete a collection](https://static-docs.nocobase.com/delete_collection.png)
+
+After confirmation, NocoBase removes the collection metadata and the real table and data in the main database.
+
+![Delete confirmation](https://static-docs.nocobase.com/delete_collection_second_confirmation.png)
+
+The confirmation dialog can automatically delete database objects that depend on the collection, such as database views built from it and objects that depend on those views.
+
+:::danger Warning
+
+Deleting a general collection is high risk. It can remove the table structure, table data, field metadata, and dependent page blocks, relation fields, permissions, workflows, and API calls. Confirm that dependent objects can be deleted before enabling automatic deletion.
+
+:::