aitable-workflow-cli 0.1.13-beta.1

package/templates/aitable-handoff/wiki/faq-support/18-/345/274/200/345/217/221/350/200/205/346/214/207/345/215/227/AI/350/241/250/346/240/274/346/225/260/346/215/256/346/272/220 /345/274/200/345/217/221/346/214/207/345/215/227.md"

@@ -0,0 +1,607 @@
+# AI表格数据源 开发指南
+
+# 数据源同步概述
+
+## 数据源同步是什么？
+
+数据源同步是钉钉AI 表格提供的一项数据集成能力，它能够将分散在不同系统和平台的数据自动汇聚到AI 表格中，实现数据的统一管理和分析。
+
+### 核心价值
+
+1.  数据集中化管理
+    
+    将企业内外部多个系统的数据整合到一个平台，避免数据孤岛；统一的数据视图，便于全局分析和决策
+    
+2.  自动化数据流转
+    
+    支持定时或实时同步，减少人工导入导出的工作量；确保数据的时效性和准确性
+    
+3.  跨系统数据协作
+    
+
+打通不同业务系统之间的数据壁垒；实现业务流程的无缝衔接
+
+### 目前支持丰富的开箱即用的数据源：
+
+*   钉钉生态数据：AI 表格、钉钉表格、OA审批、考勤打卡、通讯录、会议、日程等
+    
+*   数据库系统：MySQL、PostgreSQL、SQLServer等主流数据库
+    
+*   业务平台数据：淘宝生意参谋、拼多多商家后台、得物商家后台、阿里妈妈等电商平台
+    
+*   企业管理：聚水潭ERP、Teambition系统等企业应用
+    
+
+## 数据同步插件如何使用
+
+以MySQL 插件为例，介绍如何使用插件完成数据同步的过程
+
+### 1.2.1 功能入口
+
+AI 表格左下角，「添加/导入」-「从其他数据源同步」
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/924493f8-5edc-473f-815b-dabe23e040ae.png)
+
+在弹出的数据链接中心，选择MySQL
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/jP2lRYj3jM0kZO8g/img/1070d32c-4fd9-48a8-ac31-e527288f5d58.png)
+
+### 1.2.2 登录数据库、选择数据表及导出字段
+
+登录数据库
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/317cd69a-80ac-416b-b317-00acbc3ecb9b.png)
+
+选择数据库和数据表
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/dc60922e-b3d1-4537-935c-59adea7d1325.png)
+
+选择导出的字段
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/850813fc-5dd3-4647-8a84-9d2531680da5.png)
+
+### 1.2.3 数据同步设置
+
+点击下一步，进入数据同步设置页面。数据同步设置页面是一个通用的页面，用户可以在该页面配置同步字段、开启/关闭定时同步。
+
+支持全部字段
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/d098c9cd-9497-4dd9-8265-0e18eb7672b7.png)
+
+指定同步的字段
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/2f2f7eb9-a682-4a0b-94fe-154ea8b548be.png)
+
+### 1.2.4 保存并同步
+
+点击「保存并同步」，等待同步过程后，即可以得到一张同步表，同步表的数据来源于前置步骤中选择的数据表，至此完成了MySQL插件的数据同步配置。
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/bba44dfd-1917-4c89-b06b-36d85190fdbc.png)
+
+### 1.2.5 其他操作
+
+同步表的更多菜单
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/a738f149-2e41-44c9-b27a-6179c4dfd075.png)
+
+同步表解除同步关系后，支持编辑
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/8c887e7f-a2fc-41f0-876a-78af52d2bec0.png)
+
+同步表的更多菜单中有数据同步设置、更新数据、解除同步关系选项，具有权限的用户可以对同步表进行操作。
+
+| 操作 | 介绍 |
+| --- | --- |
+| 数据同步设置 | 可以对同步字段和自动同步的配置进行修改 |
+| 更新数据 | 可以手动触发一次数据同步 |
+| 解除同步关系 | 同步表不支持编辑同步字段，解除同步关系后，表格将转换为普通AI表格，支持编辑字段及数据。 |
+
+# 如何开发数据源同步插件
+
+开发数据源同步插件时，开发者需着重关注`插件前端`和`插件服务端`，`插件前端`用于使用者配置数据源信息，`插件服务端`用于获取数据源表结构与行记录。
+
+## 快速开始
+
+### 2.1.1 数据源三方插件的基本信息
+
+每个三方数据源插件都需要具备以下信息，在开发、自定义插件测试和插件发布过程中，都会围绕这几个内容展开。
+
+| 信息 | 是否必须 | 作用 | 举例 |
+| --- | --- | --- | --- |
+| 前端配置页面 | Y | 使用者点击插件，会进入到三方提供的前端配置页面。用户在配置页面完成三方数据源的配置。<br>如Mysql插件的配置页面，完成数据库的地址、帐密配置。 | MySQL 插件的配置页面<br>![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/85706856-d003-4018-bd25-49e891b08642.png) |
+| 前端页面的宽度和高度 | N | 在展示前端配置页面时，容器的宽度和高度。默认是 300 \* 450 |  |
+| 三方服务端地址 | Y | 用户完成前端页面配置后，会由AI表格服务端向三方服务端发起拉取表结构/数据的请求。 | 如： https://alidoc.host.com/<br>（仅举例，不支持访问） |
+| 数据表结构同步接口 | Y | 完成配置后，AI表格服务端首先会调用三方的表结构接口，查询表结构，如字段配置，表名称等，然后根据表结构完成数据表的创建。 | 如 /api/sheet\_meta<br>最终请求的接口为<br>{服务端地址}+ {表结构接口}，即<br>https://alidoc.host.com/api/sheet\_meta |
+| 行记录同步接口 | Y | 在更新数据时，AI表格服务端会调用三方行记录同步接口，完成行记录的数据拉取。 | 如 /api/records<br>最终请求的接口为<br>{服务端地址}+ {行记录接口}，即<br>https://alidoc.host.com/api/records |
+| 请求签名 | N | 确认接口来源为AI 表格服务端，防止其他方调用，保证通信安全。 |  |
+
+### 2.1.2 前端配置页面开发
+
+同步配置界面用于管理待同步数据的参数设置，用户可根据不同业务场景灵活定制不同配置，确保匹配业务需求。
+
+#### 2.1.2.1 快速开始
+
+推荐使用官方模板快速开始：
+
+[https://github.com/dingdocs-notable/datasource-plugin-demo: https://github.com/dingdocs-notable/datasource-plugin-demo](https://github.com/dingdocs-notable/datasource-plugin-demo)
+
+```bash
+git clone https://github.com/dingdocs-notable/datasource-plugin-demo
+cd datasource-plugin-demo
+npm install
+npm start
+```
+
+需要注意的是，如果不使用脚手架，在前端代码中，需要初始化iframe环境。
+
+```javascript
+npm install dingtalk-docs-cool-app --save
+```
+```javascript
+import { initView } from 'dingtalk-docs-cool-app';
+
+
+function App (){
+  ...
+  
+  // 初始化iframe内环境
+  useEffect(() => {
+    initView({
+      onReady: () => {},
+      onError: e => {
+        console.log(e);
+      }
+    });
+  }, []);
+
+  
+  ...
+}
+
+```
+
+#### 2.1.2.1 UI开发
+
+以下是界面的一个 UI demo。
+
+```javascript
+import { useEffect, useState } from 'react';
+import { initView } from 'dingtalk-docs-cool-app';
+
+function App() {
+  const [value, setValue] = useState('someValue');
+
+  useEffect(() => {
+    initView({
+      onReady: () => {
+      },
+      onError: (e) => {
+        console.log(e);
+      },
+    });
+  }, []);
+
+  const goNext = async () => {
+    const config = { a: 'test' };
+    await (Dingdocs.base.host as any).saveConfigAndGoNext(config);
+  };
+
+  return (
+    <div style={{display: 'flex', flexDirection: 'column', alignItems: 'center'}}>
+      <h1>数据源插件demo</h1>
+      <div style={{display: 'flex'}}>
+        <label>输入框:</label>
+        <input value={value} onChange={(e) => setValue(e.target.value)} />
+      </div>
+      <button style={{marginTop: 20, maxWidth: 100}} onClick={goNext}>点击下一步</button>
+    </div>
+  )
+}
+
+export default App;
+
+```
+
+#### 2.1.2.2 前端 API
+
+主要提供必要信息查询和写入功能，以支持配置界面的开发。
+
+*   **saveConfigAndGoNext**
+    
+
+保存数据源同步配置后（配置信息可自定义，格式为 key-value）调用该 API，会关闭同步配置页面进入字段配置。
+
+#### 2.1.2.3 运行调试
+
+前端页面开发完成后，开发者需要将其部署到公网可访问的服务器上。注意，前端页面的资源地址协议需为 **https协议**，否则会因为浏览器安全策略，导致页面无法打开。
+
+#### 2.1.2.4 获取当前登录用户/免登
+
+免登需要两步
+
+1.  前端调用`Dingdocs.base.host.getAuthCode(corpId)`获取免登码
+    
+2.  插件前端调用插件服务端，将免登码发给插件服务端
+    
+3.  插件服务端调用[钉钉开放接口](https://open.dingtalk.com/document/orgapp/obtain-the-userid-of-a-user-by-using-the-log-free)通过免登码获取用户信息
+    
+
+#### 2.1.2.5 获取当前AI 表格所属组织
+
+在酷应用中配置的前端插件URL中，可以带上`$CORPID$` 占位符。AI 表格加载前端插件时，会将`$CORPID$`替换为当前AI 表格组织。
+
+例如，配置URL为`https://xxx.com?corpId=$CORPID$`时，最后加载的URL为`https://xxx.com?corpId=dingxxxx`，其中`dingxxx`为当前AI 表格所属组织的corpId。
+
+### 2.1.3 服务端接口开发
+
+主要实现两个服务端接口，分别用于获取三方数据源的表结构和表记录。开发者需要提供一个公网可访问的服务地址：
+
+*   ${服务地址}/api/sheet\_meta：获取表结构接口
+    
+*   ${服务地址}/api/records：获取表记录接口
+    
+
+#### 2.1.3.1 代码示例
+
+这是一个使用nodeJS搭建的服务端代码示例，可以部署到公网 或者通过本地运行 + ngrok内网穿透的方式进行测试。
+
+1.  **运行部署node服务**
+    
+    [https://github.com/dingdocs-notable/datasource-plugin-node-demo: https://github.com/dingdocs-notable/datasource-plugin-node-demo](https://github.com/dingdocs-notable/datasource-plugin-node-demo)
+    
+    ```bash
+    git clone https://github.com/dingdocs-notable/datasource-plugin-node-demo
+    cd datasource-plugin-node-demo
+    npm install
+    npm start
+    ```
+    
+2.  **内网穿透（本地运行服务需要）**
+    
+
+内网穿透将本地开发环境暴露到公网，使外网用户可以访问你本机运行的服务。如果你的node/java 服务代码运行在本地，则需要进行内网穿透，让AI表格的服务端可以访问到你的服务。常见的内网穿透工具有ngrok、localtunnel、serveo等。
+
+**重要提示：请仔细阅读以下条款**
+
+1.  第三方工具性质：内网穿透工具为第三方提供的内网穿透服务，非本公司开发或维护，使用该工具产生的任何问题与本公司无关。
+    
+2.  安全风险提醒：
+    
+    1.  使用内网穿透工具会将您的本地服务暴露到公网，存在一定的安全风险
+        
+    2.  请确保本地开发环境不包含敏感数据
+        
+    3.  建议仅在开发调试阶段使用，生产环境请使用正式部署方案
+        
+3.  责任范围：
+    
+    1.  因使用 ngrok 工具导致的数据泄露、网络安全问题，本公司不承担任何责任
+        
+    2.  因 ngrok 服务本身故障、变更、终止等造成的开发中断，本公司不承担任何责任
+        
+    3.  用户应自行承担使用该工具的所有风险
+        
+4.  替代方案：如对安全性有特殊要求，建议使用企业内部的内网穿透解决方案或其他符合安全规范的调试方式。
+    
+
+使用即表示您已理解并接受上述所有条款和风险。
+
+1.  **ngrok的使用指南**
+    
+
+[《使用ngrok进行本地调试 》](https://alidocs.dingtalk.com/i/nodes/NZQYprEoWoxKPoqwC02GboMDV1waOeDk?corpId=)
+
+#### 2.1.3.2 获取表结构 API
+
+**基本信息**
+
+| 说明 | 该接口返回三方数据源的表结构，说明数据源有哪些字段，以及每个字段的类型 |
+| --- | --- |
+| 方法 | `POST` |
+| Path | https://{应用服务器地址}/api/sheet\_meta |
+| 超时时间 | 10s |
+| 请求头 | *   Ding-Docs-Timestamp<br>    <br>*   Ding-Docs-Signature<br>    <br>*   Content-Type:"application/json; charset=utf-8" |
+| 请求体 | ```json<br>{<br>  "requestId": "", // 单次同步任务的requestId<br>  "params": "", // JsonString, 查询三方表结构信息参数，由开发者自定义，即前端调用saveConfigAndGoNext保存的信息<br>  "context": {<br>    "unionId": "", // 数据同步用户id<br>    "corpId": "" // AI 表格所属组织id<br>  }<br>}<br>``` |
+| 返回体示例 | ```json<br>{<br>  "code": 0,<br>  "msg": "",<br>  "data": {<br>    "sheetName":""<br>    "fields":[<br>            {<br>                "id":"fid_1",// 字段唯一标识<br>                "name":"id", // 字段名称<br>                "type":"text",  // 字段类型,<br>                "isPrimary": true // 是否主键字段<br>                "property": {<br>                },<br>                "description":"description"<br>            },<br>            {<br>                "id":"fid_2",// 字段唯一标识<br>                "name":"name", // 字段名称<br>                "type":"number",  // 字段类型, 枚举值见附录<br>                "isPrimary": false // 是否主键字段<br>                "property": {<br>                    "formatter": "INT" <br>                  },<br>                "description":"description"<br>            },<br>            ……<br>        ]<br>  }<br>}<br>``` |
+
+**返回体参数说明**
+
+| 参数名 | 类型 | 是否必填 | 描述 |
+| --- | --- | --- | --- |
+| code | int | 是 | 0 是正常值，非 0 异常，错误码如下：<br>10001：参数错误<br>10002：配置信息错误<br>10003：权益不足<br>10004：身份校验失败<br>10005：三方系统异常，请稍后再试 |
+| msg | string | 否 | 具体错误信息 |
+| data | object | 是 |  |
+| \-- sheetName | string | 是 | 三方数据源名-同步表名 |
+| \-- fields | array object | 是 | 同步表字段列表 |
+| \-- -- id | string | 是 | 字段唯一标识 |
+| \-- -- name | string | 是 | 字段名称-同步表字段名 |
+| \-- -- isPrimary | boolean | 是 | 是否主键字段，仅一列为主键字段 |
+| \-- -- type | string | 是 | 字段类型，枚举值见[4.1 字段类型枚举](https://alidocs.dingtalk.com/i/nodes/G1DKw2zgV2KnvL4kFNq3rdMyJB5r9YAn?utm_scene=team_space&iframeQuery=anchorId%3Duu_maq71k6rox7iqpx5v1e) |
+| \-- -- property | object | 否 | 字段类型属性，参考[4.1 字段类型枚举](https://alidocs.dingtalk.com/i/nodes/G1DKw2zgV2KnvL4kFNq3rdMyJB5r9YAn?utm_scene=team_space&iframeQuery=anchorId%3Duu_maq71k6rox7iqpx5v1e) |
+
+#### 2.1.3.3 获取表记录 API
+
+**基本信息**
+
+| 说明 | 该接口返回三方数据源表中的记录，分页返回 |
+| --- | --- |
+| 方法 | `POST` |
+| Path | https://{应用服务器地址}/api/records |
+| 超时时间 | 20s |
+| 请求头 | *   Ding-Docs-Timestamp<br>    <br>*   Ding-Docs-Signature<br>    <br>*   Content-Type:"application/json; charset=utf-8" |
+| 请求体 | ```json<br>{<br>  "requestId": "", // 单次同步任务的requestId<br>  "maxResults":300, // 单次返回最大记录条数，默认300条<br>  "nextToken": "", 数据拉取的起始位置。首次调用不传，后续调用时使用插件服务端返回的nextToken参数<br>  "params": "", // JsonString, 查询三方表结构信息参数，由开发者自定义，即前端调用saveConfigAndGoNext保存的信息<br>  "context": {<br>    "unionId": "", // 数据同步用户id<br>    "corpId": "" // AI 表格所属组织id<br>  }<br>}<br>``` |
+| 返回体示例 | ```json<br>{<br>    "code": 0, <br>    "msg": "", <br>    "data": {<br>        "nextToken":"xxx", // 下次分页的起始令牌<br>        "hasMore": false,  // 是否还有更多数据<br>        "records":[<br>            {<br>                "id":"1",  // 行记录id<br>                "fields": {<br>                    "fid_1": "xxx",  // 字段id：字段值<br>                    "fid_2": 1222,<br>                }  <br>            },<br>            {<br>                "id":"2",<br>                "fields": {<br>                    "fid_1": "xxx",<br>                    "fid_2": 334.33,<br>                }  <br>            }<br>        ],<br>        ……<br>        "total": 100  // 字段总数，可选，用于计算当前数据同步进度<br>    }<br>}<br>``` |
+
+**返回体参数说明**
+
+| 参数名 | 类型 | 是否必填 | 描述 |
+| --- | --- | --- | --- |
+| code | int | 是 | 0 是正常值，非 0 异常，错误码如下： |
+| msg | string | 否 | 具体错误信息 |
+| data | object | 是 |  |
+| \-- nextToken | string | 否 | 下一页 token |
+| \-- hasMore | bool | 是 | 是否还有下一页表记录 |
+| \-- records | array object | 是 | 表记录列表 |
+| \-- -- id | string | 是 | 单条表记录 id |
+| \-- -- fields | map<string,any> | 是 | 表记录具体数据 |
+
+#### 2.1.3.4 请求签名
+
+签名的作用是确认接口来源为AI 表格服务端，防止其他方调用。
+
+**签名规则**
+
+在请求接口时，按照如下的规则生成签名，并将对应的签名和数据放在请求的 Header 中。
+
+1.  数据源插件上架时，双方约定设置好一个secretKey；
+    
+2.  获取请求 Header 中的`Ding-Docs-Timestamp`、`Ding-Docs-Signature`的值，分别记为 **timestamp**、**signature**；
+    
+3.  获取原始请求 Body 的数据记为 body；
+    
+4.  将 secretKey、body、timestamp 按照规则进行加密得到 `signatureExpected`；
+    
+5.  校验 **signature** 和`signatureExpected`的值是否一致；
+    
+
+**示例代码**
+
+Java 代码示例
+
+```java
+/**
+ * @param secretKey  密钥
+ * @param body 请求体
+ * @param timestamp 时间戳
+ * @param signature 请求签名
+ * @return 校验签名是否相等的 boolean
+ */
+    public static boolean hmacSha256Base64(String secretKey, String body, long timestamp, String signature) {
+        try {
+            SecretKeySpec secret_key = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), HMAC_SHA256_ALGORITHM);
+            sha256_HMAC.init(secret_key);
+            String content = body + timestamp;
+            byte[] hash = sha256_HMAC.doFinal(content.getBytes(StandardCharsets.UTF_8));
+            String signatureExpected = Base64.getEncoder().encodeToString(hash);
+            return signature.equals(signatureExpected);
+        } catch (Exception e) {
+            throw new RuntimeException("signature not match", e);
+        }
+    }
+```
+
+## 插件调试
+
+### 2.2.1  插件调试入口
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/e0533809-4577-4eaa-b137-171092f8da83.png)
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/9016a6ba-5e40-46fe-afea-6756f4244c21.png)
+
+### 2.2.2  填写配置信息连接到插件
+
+按照弹窗中的描述，填写必选项的内容，点击下一步，进入填写的前端页面地址。
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/b7ef57c9-b5cb-487c-90d6-3cbf200924e2.png)
+
+### 2.2.3  在数据源自定义页面进行界面设置
+
+此时将会弹出上一步在「前端页面地址」中配置的数据源自定义页面，可根据业务情况进行界面设置
+
+### 2.2.4 数据源同步配置，完成同步
+
+配置同步设置
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/e6ede8d0-586c-4ee2-8f25-28da45ca3967.png)
+
+完成同步
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/8c9b4c2c-3ff2-4f9f-a6be-923287dcfaa5.png)
+
+### 2.2.5 修改配置
+
+通过点击同步表的「更多菜单」中的 「数据同步设置」，可以对数据源配置进行修改。
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/d78173eb-bfb7-46f4-aeb5-2f1b363d8851.png)
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/bfba5c49-acc6-4d55-bac2-b57c75fdc0db.png)
+
+## 2.3 常见 Q & A
+
+**Q：前端页面无法加载**
+
+![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/ZWGl05m3WZNoen34/img/2910a964-e2fc-47f5-82af-cf75c2b13904.png)
+
+A：检查如下
+
+1. url链接是否为https协议，非https协议会因为浏览器安全策略，导致页面无法打开
+
+2.  代码中是否执行了initView方法，具体见2.1.2.1 章节。[《AI表格数据源 开发指南》](https://alidocs.dingtalk.com/i/nodes/1OQX0akWmBejogd0TAlmRyQGVGlDd3mE?utm_scene=team_space&iframeQuery=anchorId%3Duu_miwt4zgne3wbz4459fi)
+    
+
+**Q： 企业内插件获取授权码失败**
+
+A： 见[《AI 表格插件 - 企业内插件发布指南》](https://alidocs.dingtalk.com/i/nodes/vNG4YZ7JnpyN1Mo0uEKQXpb2W2LD0oRE?utm_scene=team_space&iframeQuery=anchorId%3Duu_mkorcf4hllunv8wwipj)
+
+# 发布插件
+
+目前数据源插件支持**企业内插件**和**三方企业插件**。企业内插件仅服务于本企业自身，仅在当前企业内可见并使用，三方企业插件面向多企业开放，支持其他企业或全网使用插件。
+
+## 3.1 插件类型对比及使用场景
+
+| **对比维度** | **企业内插件** | **三方企业插件** |
+| --- | --- | --- |
+| 目标用户 | 单一企业内部 | 多家企业客户 |
+| 收费模式 | 自建自用 | 可进行商业化收费 |
+| 审核要求 | 企业内部审核 | 平台严格审核 |
+
+### 3.1.2 企业内应用
+
+**功能定位**
+
+**自用性质**：为企业内部员工提供工作协同和业务管理工具
+
+**定制化**：针对本企业特定业务流程和管理需求开发
+
+**成本控制**：无需支付第三方费用，主要承担开发和维护成本
+
+**技术特点**
+
+**权限简单**：基于企业内部组织架构进行权限控制
+
+**集成便利**：可直接对接企业内部系统（如HR、财务系统）
+
+**部署灵活**：无需平台审核，企业自主管理和发布
+
+### 3.1.1 三方企业应用
+
+**功能定位**
+
+**商业模式**：作为ISV（独立软件供应商）开发，通过钉钉应用市场向多家企业销售
+
+**服务范围**：为不同企业提供标准化或定制化的SaaS服务
+
+**盈利导向**：以商业化运营为目标，按企业数量、功能模块或使用时长收费
+
+**技术特点**
+
+**通用性强**：需适配不同企业的个性化需求和权限体系
+
+**安全隔离**：多租户架构，确保各企业数据完全隔离
+
+**审批流程**：需通过钉钉平台审核，符合安全和合规要求
+
+## 3.2 企业内插件
+
+企业内插件仅发布插件的企业内可见，无需平台审核，功能由企业自主管理和发布，因此发布比较简单。
+
+| **步骤** | **备注** | **截图** |
+| --- | --- | --- |
+| 1. 进入钉钉者开发平台 | 地址：[https://open-dev.dingtalk.com](https://open-dev.dingtalk.com/?hash=%23%2F#/) |  |
+| 2. 创建一个企业内部应用 |  | ![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/7ade9123-8d33-42ae-aa66-17d71203892b.png)<br>![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/90758ba5-b7e6-4eee-bca4-77bc9d6cd7a1.png) |
+| 3. 添加酷应用 | 1.  进入创建的企业应用，点击酷应用卡片在的「添加」<br>    <br>2.  进入酷应用菜单，选择创建酷应用<br>    <br>3.  在弹窗中选择「扩展到AI表格」<br>    <br>4.  填写基本信息、选择数据同步插件、填写调试的用户页面地址，以及服务端接口地址<br>    <br>5.  保存，发布。 | ![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/6fbbd6e8-f2b4-4265-9a97-0752fc894ec0.png)<br>![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/a9d1f4fd-2bd3-4432-ad2f-1edf1e4b5df0.png)<br>![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/12471101-cc50-40b2-9619-3a17823710d7.png)<br>![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/eYVOL5j7mwE6wlpz/img/3ac9c371-c676-4c24-b597-2453f0ba326e.png) |
+| 4. 发布酷应用 | 1.  进入「应用发布」-「版本管理与发布」，点击创建新版本<br>    <br>2.  选择发布的版本号和可见范围，点击保存后，完成发布酷应用 | ![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/eYVOL5j7mwE6wlpz/img/68ed9776-ade5-47f4-a73f-8d3a8c248403.png)<br>![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/eYVOL5j7mwE6wlpz/img/e0aebe75-895f-4858-8da4-6f5616372984.png) |
+| 5. 进行联调 | 在「数据连接中心」-「企业专用」，可以看到发布的插件。点击即可唤起在 步骤3 中配置的用户页面地址。 | ![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/eYVOL5j7mwE6wlpz/img/5835ee0b-285d-4ac7-89a2-46ea68b39905.png) |
+| 6、发布 | 注意在测试完成后，可以在钉钉开发者平台中 「版本管理与发布」上的「应用可见范围」，调整插件可见范围。 | ![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/jP2lRYj3jM0kZO8g/img/fddb835f-5bc6-4e45-8cc0-103240f76e46.png) |
+
+## 3.3 三方企业插件
+
+AI 表格的第三方企业插件依托钉钉开放平台[酷应用](https://open.dingtalk.com/document/orgapp/cool-application-overview)能力实现用户的信息流转、免登鉴权等能力。一个插件就是一个酷应用，因此在三方完成`插件前端`和`插件服务端`开发后，需要在钉钉开放平台创建并发布一个AI表格的数据源酷应用。
+
+相比于3.2中的企业内插件，第三方企业插件的发布插件步骤较多，**发布插件前请先了解前置知识：**[**钉钉企业内部应用开发信息**](https://open.dingtalk.com/document/orgapp/learning-map)
+
+| **步骤** | **备注** | **截图** |
+| --- | --- | --- |
+| 1、入驻服务商 | 只有入驻钉钉的服务商企业才可以注册三方应用，因此想要发布一个三方插件，需要成为入驻钉钉的服务商。<br>[服务商介绍及入驻页面，点击打开。](https://partner.dingtalk.com/#/) 提交审批后，由  $\color{#0089FF}{@李强(自亦)}$ 完成审核。<br>注意服务商的入驻申请需要由企业管理员提交。组织管理员可以登录oa管理后台进行权限配置，设置管理员身份：[oa管理后台链接](https://oa.dingtalk.com/oa_welcome.htm#/sub_permission/index_pc_new?showIntroTip=true)。 | ![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/cd2d95a4-352f-4a00-8d42-ec032716212e.png) |
+| 2、注册三方应用（收费，授权相关） | 1.  开通免费规格的商品<br>    <br>    1.  加入企业： [钉钉ISV沟通](https://wx-in-i.dingtalk.com/invite-page/weixin.html?bizSource=____source____&corpId=dinga22b5311e4211323&inviteCode=rqPl3JkxnrtKbje&dtaction=os&cid=&origin=&originMeta=&scene=PCInviteMemberNew&deptId=-1&dtaction=os)后，提交审批： [审批链接](dingtalk://dingtalkclient/action/openapp?app_id=-4&container_type=work_platform&corpid=dinga22b5311e4211323&ddtab=true&redirect_type=jump&redirect_url=https%3A%2F%2Faflow.dingtalk.com%2Fdingtalk%2Fmobile%2Fhomepage.htm%3FappUuid%3Ddinga22b5311e4211323%26backcontrol%3Dfalse%26corpid%3Ddinga22b5311e4211323%26dd_progress%3Dfalse%26dd_share%3Dfalse%26ddtab%3Dtrue%26showmenu%3Dfalse%23%2Fcustom%3Fpcredirect%3Dself%26processCode%3DPROC-E4B69876-7A74-421C-8C40-33527DD10703)。<br>        <br>    2.  联系 $\color{#0089FF}{@李强(自亦)}$ 开通发布免费规格的商品，需要appid增加白名单。<br>        <br>2.  免费应用<br>    <br>    1.  联系 $\color{#0089FF}{@李强(自亦)}$ 沟通，免费应用0元应用，需要appid。<br>        <br>3.  申请不展示开放平台入口<br>    <br>    1.  提交应用隐藏申请：[应用隐藏申请链接](https://yida.alibaba-inc.com/s/ddopen?spm=a1z32v.14449796.0.0.2c534a97uufFZ6#/FORM-5T566E8114O8EFADCD3SM7XBHS9036EVAFWEL82)<br>        <br>    2.  联系  $\color{#0089FF}{@李强(自亦)}$ 沟通，确定应用不在开放平台展示，需要appid。<br>        <br>4.  去掉开通通知<br>    <br>    1.  联系 $\color{#0089FF}{@李强(自亦)}$ 沟通，去掉开通通知，否则用户启用插件时，会通知企业所在管理员开通应用。<br>        <br>5.  应用发布<br>    <br>6.  开通成员授权<br>    <br>    1.  需要审批。https://open.dingtalk.com/document/isvapp/document-on-authorization-of-application-market-members |  |
+| 3、发布酷应用（展示相关） | *   发布扩展到 AI 表格<br>    <br>*   加入 钉钉合作伙伴组织<br>    <br>    *   角色+部门申请链接：[dingtalk://dingtalkclient/page/link?url=https%3A%2F%2Fpre-h5.dingtalk.com%2F40plan%2Fweb-tianyuan-rbac%2Findex.html%3Fddtab%3Dtrue%23%2Fapply](dingtalk://dingtalkclient/page/link?url=https%3A%2F%2Fpre-h5.dingtalk.com%2F40plan%2Fweb-tianyuan-rbac%2Findex.html%3Fddtab%3Dtrue%23%2Fapply)<br>        <br>    *   其他角色找 $\color{#0089FF}{@李强(自亦)}$  加入到这个组织<br>        <br>*   发布之后，需要提审批 [dingtalk://dingtalkclient/action/openapp?app\_id=-4&container\_type=work\_platform&corpid=ding77a7af8924a84af0&ddtab=true&redirect\_type=jump&redirect\_url=https%3A%2F%2Faflow.dingtalk.com%2Fdingtalk%2Fmobile%2Fhomepage.htm%3Fback\_control%3Dfalse%26backcontrol%3Dfalse%26corpid%3Dding77a7af8924a84af0%26dd\_progress%3Dfalse%26dd\_share%3Dfalse%26ddtab%3Dtrue%26showmenu%3Dfalse%23%2Fcustom%3Fpcredirect%3Dself%26processCode%3DPROC-21027998-89B9-4D56-862D-4122960CA038](dingtalk://dingtalkclient/action/openapp?app_id=-4&container_type=work_platform&corpid=ding77a7af8924a84af0&ddtab=true&redirect_type=jump&redirect_url=https%3A%2F%2Faflow.dingtalk.com%2Fdingtalk%2Fmobile%2Fhomepage.htm%3Fback_control%3Dfalse%26backcontrol%3Dfalse%26corpid%3Dding77a7af8924a84af0%26dd_progress%3Dfalse%26dd_share%3Dfalse%26ddtab%3Dtrue%26showmenu%3Dfalse%23%2Fcustom%3Fpcredirect%3Dself%26processCode%3DPROC-21027998-89B9-4D56-862D-4122960CA038) | ![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/c0f67e64-afd9-4b99-8eb2-5e1b5e5af9ff.png)<br>![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/2M9qP5jzYp9RDO01/img/efe3501f-978f-40f4-a48b-e604fed4dfd1.png) |
+| 4、验证和发布 | 完成后，联系 $\color{#0089FF}{@刘福林(烁硕)}$ （数据源插件）或  $\color{#0089FF}{@欧阳莫微(弗隐)}$ （边栏插件） 的功能测试和审批发布。 |  |
+
+# 附录
+
+## 4.1 字段类型枚举
+
+| 字段 | 类型（type） | 属性（property） |
+| --- | --- | --- |
+| 文本 | text | 无 |
+| 数字 | number | ```java<br>{<br>    formatter: "INT"        // 整数<br>        \| "FLOAT_1"         // 保留1位小数<br>        \| "FLOAT_2"         // 保留2位小数<br>        \| "FLOAT_3"         // 保留3位小数<br>        \| "FLOAT_4"         // 保留4位小数<br>        \| "THOUSAND"        // 千分位<br>        \| "THOUSAND_FLOAT"  // 千分位（小数点）<br>        \| "PRESENT"         // 百分比<br>        \| "PRESENT_FLOAT"   // 百分比（小数点）<br>        \| "CNY"             // 人民币<br>        \| "CNY_FLOAT"       // 人民币（小数点）<br>        \| "HKD"             // 港元<br>        \| "HKD_FLOAT"       // 港元（小数点）<br>        \| "USD"             // 美元<br>        \| "USD_FLOAT"       // 美元（小数点）<br>        \| "EUR"             // 欧元<br>        \| "EUR_FLOAT"       // 欧元（小数点）<br>        \| "JPY"             // 日元<br>        \| "JPY_FLOAT";      // 日元（小数点）<br>}<br>``` |
+| 单选 | singleSelect | ```java<br>{<br>    choices: [{<br>        name: "optionName1" // 配置选项名<br>    }, {<br>        name: "optionName2"<br>    }];<br>}<br>``` |
+| 多选 | multipleSelect | 同「单选」 |
+| 日期 | date | ```java<br>{<br>    formatter: "YYYY-MM-DD"    // 显示格式: 2023-12-31<br>        \| "YYYY-MM-DD HH:mm"   // 显示格式: 2023-12-31 09:00<br>        \| "YYYY/MM/DD"         // 显示格式: 2023/12/31<br>        \| "YYYY/MM/DD HH:mm";  // 显示格式: 2023/12/31 09:00<br>}<br>``` |
+| 链接 | url | 无 |
+
+## 4.2 数据连接器
+
+### 4.2.1 核心要素
+
+### 4.2.2 关键流程
+
+![image](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/a/B20xLbq5frxavmbP/2c777cc27a014f0f8e14c550e7cdb22a2715.png)
+
+1.  用户只有通过授权才能拿到三方平台数据；
+    
+2.  说明同步的数据的来源和范围；
+    
+3.  说明三方数据源同步的表结构以及表记录；
+    
+4.  根据配置的三方数据源，返回数据记录，写入同步表中。
+    
+
+#### 4.2.2.1 三方平台授权
+
+#### 4.2.2.2 同步配置
+
+授权成功后，用户可以进行数据同步配置。
+
+```mermaid
+sequenceDiagram
+autonumber
+actor user as 用户
+participant f as 多维表前端
+participant cf as 插件前端
+participant cb as 插件服务端
+participant b as 多维表服务端
+
+user ->>f: 点击三方数据源同步
+f ->>f: 三方数据源插件授权
+f ->>cf: 唤起三方数据源配置页面
+cf ->>cf: 数据源配置
+cf ->>f: 配置完成点下一步
+f ->>+b: 请求表字段配置信息
+b ->>cb: 带上数据源配置参数，请求插件服务端，获取表字段信息
+cb -->>b: 返回表结构数据
+b -->>-f: 返回表结构数据
+f -->>user: 返回表结构数据
+user ->>f: 选择要同步的数据源字段及配置，点击保存
+f ->>b: 保存数据源配置
+```
+
+#### 4.2.2.3 数据同步
+
+```mermaid
+sequenceDiagram
+autonumber
+participant s as 多维表服务端
+participant cb as 插件服务端
+
+s ->>s: 查询数据源配置信息
+s ->> cb: 获取数据源表结构数据
+cb -->> s: 返回表结构数据
+loop 分页拉取数据源分页记录
+s ->> cb: 请求数据源记录信息
+cb -->> s: 返回数据源记录
+end
+s ->>s: 更新同步表行数据
+```
+
+## 4.3 研发skill（持续更新中）
+
+下面是一个用于快速开发数据源插件的skill，内部描述了如何快速部署、测试一个自定义数据源插件。
+
+[请至钉钉文档查看附件《ai-table-datasource-plugin-generator.zip》。](https://alidocs.dingtalk.com/i/nodes/1OQX0akWmBejogd0TAlmRyQGVGlDd3mE?iframeQuery=anchorId%3DX02mn48o78qy73f712co7i)
+
+# FAQ
+
+# 联系我们
+
+ $\color{#0089FF}{@刘福林(烁硕)}$  $\color{#0089FF}{@张瑞(陌渊)}$