docs(integration): add introduce to new intehration method (#95)

Author: mymodian

content/guides/pro/api.mdx

@@ -31,11 +31,21 @@ This page lists common Univer Server APIs. The default base URL is `http://local
       type: 'string',
       required: true,
       description: 'Creator id',
+    }, {
+      name: 'idempotencyKey',
+      type: 'string',
+      required: false,
+      description: 'Introduced since v0.20.0. Optional idempotency key; The total byte size must be ≤ 64.',
+    }, {
+      name: 'metaData',
+      type: 'string',
+      required: false,
+      description: 'Introduced since v0.20.0. User-defined information, bound to the created unit, will be transparently passed through in subsequent synchronization events and USIP calls. The total byte size must be ≤ 1024.',
     }],
     example: `curl http://localhost:8000/universer-api/snapshot/{type}/unit/-/create \\
     -X POST \\
     -H 'Content-Type: application/json' \\
-    --data-raw '{"type":2,"name":"New Sheet By Univer","creator":"userID"}'`,
+    --data-raw '{"type":2,"name":"New Sheet By Univer","creator":"userID","idempotencyKey":"a-idgenerator-unique-id","metaData":"tenant12345"}'`,
   }}
   response={{
     type: 'application/json',
@@ -292,10 +302,20 @@ This page lists common Univer Server APIs. The default base URL is `http://local
       type: 'int',
       required: true,
       description: 'Minimum columns; import validates column count',
+    }, {
+      name: 'idempotencyKey',
+      type: 'string',
+      required: false,
+      description: 'Introduced since v0.20.0. Optional idempotency key; The total byte size must be ≤ 64.',
+    }, {
+      name: 'metaData',
+      type: 'string',
+      required: false,
+      description: 'Introduced since v0.20.0. User-defined information, bound to the imported unit, will be transparently passed through in subsequent synchronization events and USIP calls. The total byte size must be ≤ 1024.',
     }],
     example: `curl -X POST 'http://localhost:8000/universer-api/exchange/2/import' \\
     -H 'Content-Type: application/json' \\
-    --data-raw '{"fileID":"123","outputType":1,"minSheetRowCount":1000,"minSheetColumnCount":20}'`,
+    --data-raw '{"fileID":"123","outputType":1,"minSheetRowCount":1000,"minSheetColumnCount":20,"idempotencyKey":"a-idgenerator-unique-id","metaData":"tenant12345"}'`,
   }}
   response={{
     type: 'application/json',

content/guides/pro/api.zh-CN.mdx

@@ -31,11 +31,21 @@ title: API
       type: 'string',
       required: true,
       description: '创建者 id',
+    }, {
+      name: 'idempotencyKey',
+      type: 'string',
+      required: false,
+      description: 'v0.20.0开始引入，可选幂等键, 字符数需要<=64',
+    }, {
+      name: 'metaData',
+      type: 'string',
+      required: false,
+      description: 'v0.20.0开始引入，用户自定义信息，会绑定到创建的unit，之后的同步事件和USIP调用会透传，总字节数需要<=1024',
     }],
     example: `curl http://localhost:8000/universer-api/snapshot/{type}/unit/-/create \\
     -X POST \\
     -H 'Content-Type: application/json' \\
-    --data-raw '{"type":2,"name":"New Sheet By Univer","creator":"userID"}'`,
+    --data-raw '{"type":2,"name":"New Sheet By Univer","creator":"userID","idempotencyKey":"a-idgenerator-unique-id","metaData":"tenant12345"}'`,
   }}
   response={{
     type: 'application/json',
@@ -292,10 +302,20 @@ title: API
       type: 'int',
       required: true,
       description: '最小列数，导入时会检查表格列数是否满足要求',
+    }, {
+      name: 'idempotencyKey',
+      type: 'string',
+      required: false,
+      description: 'v0.20.0开始引入，可选幂等键, 字符数需要<=64',
+    }, {
+      name: 'metaData',
+      type: 'string',
+      required: false,
+      description: 'v0.20.0开始引入，用户自定义信息，会绑定到导入的unit，之后的同步事件和USIP调用会透传，总字节数需要<=1024',
     }],
     example: `curl -X POST 'http://localhost:8000/universer-api/exchange/2/import' \\
     -H 'Content-Type: application/json' \\
-    --data-raw '{"fileID":"123","outputType":1,"minSheetRowCount":1000,"minSheetColumnCount":20}'`,
+    --data-raw '{"fileID":"123","outputType":1,"minSheetRowCount":1000,"minSheetColumnCount":20,"idempotencyKey":"a-idgenerator-unique-id","metaData":"tenant12345"}'`,
   }}
   response={{
     type: 'application/json',

content/guides/pro/event-sync.ja-JP.mdx

@@ -53,6 +53,7 @@ message EventSyncData {
     univer.ChangesetAck csAckEvent = 4;
     // more event types in the future.
   }
+  optional string unitMetaData = 99; // Introduced since v0.20.0, customer setted metadata of the unit(created by CreateUnit request or Import request)
 }
 
 message ChangesetAck {

content/guides/pro/event-sync.mdx

@@ -53,6 +53,7 @@ message EventSyncData {
     univer.ChangesetAck csAckEvent = 4;
     // more event types in the future.
   }
+  optional string unitMetaData = 99; // Introduced since v0.20.0, customer setted metadata of the unit(created by CreateUnit request or Import request)
 }
 
 message ChangesetAck {

content/guides/pro/event-sync.zh-CN.mdx

@@ -53,6 +53,7 @@ message EventSyncData {
     univer.ChangesetAck csAckEvent = 4;
     // more event types in the future.
   }
+  optional string unitMetaData = 99; // Introduced since v0.20.0, customer setted metadata of the unit(created by CreateUnit request or Import request)
 }
 
 message ChangesetAck {

content/guides/pro/event-sync.zh-TW.mdx

@@ -53,6 +53,7 @@ message EventSyncData {
     univer.ChangesetAck csAckEvent = 4;
     // more event types in the future.
   }
+  optional string unitMetaData = 99; // Introduced since v0.20.0, customer setted metadata of the unit(created by CreateUnit request or Import request)
 }
 
 message ChangesetAck {

content/guides/pro/usip.mdx

@@ -149,6 +149,11 @@ To determine permissions for reading/editing a document.
       type: 'string',
       example: 'acff-adebc125e45b',
       description: 'Document ID',
+    }, {
+      name: 'metaData',
+      type: 'string',
+      example: '{"tenantId":"company1"}',
+      description: 'metadata associated with the unit. Introduced since v0.20.0',
     }],
     example: 'curl -X GET "http://sample.univer.ai/role?unitID=acff-adebc125e45b&userID=acd5455e44fc5bb55"',
   }}
@@ -194,9 +199,15 @@ Required when selecting users for protected ranges or sheets.
       type: 'array[string]',
       example: '["unit_id1", "unit_id2"]',
       description: 'Document IDs',
+    }, {
+      name: 'unitsMetaDatas',
+      type: 'object',
+      example: '{"unit_id1":"metadata of unit_id1","unit_id2":"metadata of unit_id2"}',
+      description: 'metadata of each unit in the unitIDs param, introduced since v0.20.0',
     }],
     example: JSON.stringify({
-      unitIDs: ['unit_id1', 'unit_id2', 'unit_id3'],
+      unitIDs: ['unit_id1', 'unit_id2'],
+      unitsMetaDatas: { unit_id1: 'metadata of unit_id1', unit_id2: 'metadata of unit_id2' },
     }, null, 2),
   }}
   response={{
@@ -300,10 +311,16 @@ For your system to display last edit time.
       type: 'int',
       example: '1762591632345',
       description: 'Unix timestamp in milliseconds',
+    }, {
+      name: 'metaData',
+      type: 'string',
+      example: '{"tenantId":"company1"}',
+      description: 'metadata associated with the unit. Introduced since v0.20.0',
     }],
     example: JSON.stringify({
       unitID: 'unit_id1',
       editTimeUnixMs: 1762591632345,
+      metaData: { tenantId: 'company1' },
     }, null, 2),
   }}
   response={{
@@ -360,7 +377,7 @@ If your USIP service is exposed on the public network, to ensure API request sec
 
 Univer uses RBAC with fixed roles: `owner`, `editor`, `reader`. You can override minimum role requirements for permission points.
 
-Default permission points:
+Default permission points and minimum role requirements are as follows:
 
 | Permission | Enum | Description | Minimum Role | Role Enum |
 |:-------|:---------|:-------|:-------|:-------|
@@ -415,7 +432,7 @@ universer:
 
 ### Object Permission Inheritance
 
-By default, document owners do not automatically own all protected ranges/sheets. To enable inheritance:
+By default, the owner of a document does not automatically have owner permissions for all "protected areas / sub-tables" within that document. If you want the document owner to unconditionally have full permissions over all sub-objects within the document, you can enable permission inheritance by configuring the following settings:
 
 ```properties title=".env.custom"
 AUTH_PERMISSION_ENABLE_OBJ_INHERIT=true

content/guides/pro/usip.zh-CN.mdx

@@ -149,6 +149,11 @@ Univer Pro 默认不内置账户体系。若需要身份认证、权限控制或
       type: 'string',
       example: 'acff-adebc125e45b',
       description: '文档 ID',
+    }, {
+      name: 'metaData',
+      type: 'string',
+      example: '{"tenantId":"company1"}',
+      description: '文档关联的由客户系统设置的自定义metadata，从v0.20.0开始引入',
     }],
     example: 'curl -X GET "http://sample.univer.ai/role?unitID=acff-adebc125e45b&userID=acd5455e44fc5bb55"',
   }}
@@ -194,9 +199,15 @@ Univer Pro 默认不内置账户体系。若需要身份认证、权限控制或
       type: 'array[string]',
       example: '["unit_id1", "unit_id2"]',
       description: '文档 ID 数组',
+    }, {
+      name: 'unitsMetaDatas',
+      type: 'object',
+      example: '{"unit_id1":"metadata of unit_id1","unit_id2":"metadata of unit_id2"}',
+      description: '参数unitIDs数组中每个unit的metadata，从v0.20.0开始引入',
     }],
     example: JSON.stringify({
-      unitIDs: ['unit_id1', 'unit_id2', 'unit_id3'],
+      unitIDs: ['unit_id1', 'unit_id2'],
+      unitsMetaDatas: { unit_id1: 'metadata of unit_id1', unit_id2: 'metadata of unit_id2' },
     }, null, 2),
   }}
   response={{
@@ -300,10 +311,16 @@ Univer Pro 默认不内置账户体系。若需要身份认证、权限控制或
       type: 'int',
       example: '1762591632345',
       description: 'unix 时间戳（毫秒）',
+    }, {
+      name: 'metaData',
+      type: 'string',
+      example: '{"tenantId":"company1"}',
+      description: '文档关联的由客户系统设置的自定义metadata，从v0.20.0开始引入',
     }],
     example: JSON.stringify({
       unitID: 'unit_id1',
       editTimeUnixMs: 1762591632345,
+      metaData: { tenantId: 'company1' },
     }, null, 2),
   }}
   response={{
@@ -360,9 +377,9 @@ Univer Pro 默认不内置账户体系。若需要身份认证、权限控制或
 
 ## Univer 权限模型
 
-Univer 使用 RBAC 模型，固定角色为 `owner`、`editor`、`reader`。可以通过配置为某些权限点位设置最低角色。
+Univer 使用 RBAC 模型，固定角色为 `owner`、`editor`、`reader`。可以通过配置为某些权限点位设置最低角色要求。
 
-默认权限点位与最低角色如下：
+默认权限点位与最低角色要求如下：
 
 | 权限点位 | 权限点位枚举值 | 点位含义 | 最低角色要求 | 角色枚举值 |
 |:-------|:---------|:-------|:-------|:-------|
@@ -417,7 +434,7 @@ universer:
 
 ### 对象权限继承
 
-默认情况下，文档的 owner 并不自动拥有该文档内所有“保护区/子表”的 owner 权限。若需要开启继承：
+默认情况下，文档的 owner 并不自动拥有该文档内所有“保护区/子表”的 owner 权限。如果你希望文档的owner无条件地拥有文档内所有子对象的所有权限，可以如下配置来开启权限的继承：
 
 ```properties title=".env.custom"
 AUTH_PERMISSION_ENABLE_OBJ_INHERIT=true