docs: readme

document/README.md

@@ -17,42 +17,89 @@
 
 ### 代码拉取
 
-```javascript
+```powershell
 # 使用 recursive 克隆 sparkmagic
 git clone --recursive http://gogsb.soaringnova.com/ylproj/jupyterlab.git
 ```
 
 ### 开发环境搭建
 
-首先安装 conda 环境，配置 python3.8 版本（一定要 3.8 版本）
-然后再安装一下构建相关的依赖
+#### 配置 python 环境
 
-```javascript
+##### 安装 `Anaconda`
+
+[官网地址](https://www.anaconda.com/)
+
+##### 安装 `py38` 环境
+
+1、检查 `conda` 是否安装成功
+
+```powershell
+conda -v
+```
+
+如果发生报错，请返回上一步重新安装
+
+2、查看当前所拥有的环境
+
+```powershell
+conda info --env
+```
+
+正常情况，如下图所示
+
+![](/images/Snipaste_2024-03-15_14-43-23.png)
+
+3、创建新的 python 环境
+
+```powershell
+conda create -n py38 python=3.8
+```
+
+4、查看环境是否创建成功
+
+```powershell
+conda info --env
+```
+
+![](/images/Snipaste_2024-03-15_14-46-48.png)
+
+#### 安装依赖
+
+```powershell
+# 切换到 py38 版本
+conda activate py38
+
+# 安装需要的 python 库
 pip install -e .
+
+# 安装依赖  jlpm 是 JupyterLab 提供的特定版本的 yarn, 这里也可以使用 yarn install
 jlpm install
-jlpm build
 ```
 
-_注: 这里的 jlpm 是 JupyterLab 提供的特定版本的 yarn, 这里也可以使用 yarn install_
-
-如果出现缺失 canvas 的报错，按照以下的操作步骤进行
+如果出现缺失 `canvas` 的情况
 
-```javascript
+```powershell
 # macOS
 brew install pkg-config cairo pango libpng jpeg giflib librsvg
+
 # mamba or conda
 conda install -c conda-forge pkg-config glib pango pixman
 ```
 
-完成上述操作流程后，运行开发模式
+参考文档 https://jupyterlab.readthedocs.io/en/stable/developer/contributing.html
 
-```javascript
-# 运行项目，但是想要看见改动效果，需要手动刷新浏览器
+#### 运行项目
+
+```powershell
 jupyter lab --dev-mode --extensions-in-dev-mode
-# 实时观测代码的改动
+
+# 改动前端代码后自动编译
 jupyter lab --dev-mode --extensions-in-dev-mode --watch
 ```
 
+注：目前的 `JupyterLab` 提供的构建工具并不能自动刷新浏览器, 改动代码后需要手动刷新一下浏览器
+
 ## 功能开发
 
 功能开发主要在 `packages` 内进行
@@ -80,7 +127,7 @@ export const getDataMgmtList = (): any =>
   request({
     url: `/jpt/datamanagement/`,
     method: 'get'
-  })
+  });
 ```
 
 - 中间数据表查询（已弃用）
@@ -90,7 +137,7 @@ export const fetchFile = (uri: string): any =>
   request({
     url: `/jpt/files/?uri=${uri}`,
     method: 'get'
-  })
+  });
 ```
 
 - 删除文件
@@ -100,7 +147,7 @@ export const deleteDataMgmt = (id: string): any =>
   request({
     url: `/jpt/datamanagement/?data_management_id=${id}`, // 文件id
     method: 'delete'
-  })
+  });
 ```
 
 - 获取数据预览部分的数据
@@ -110,13 +157,13 @@ export const tableContent = (params: ITableContent): any =>
   request({
     url: `/jpt/datamanagement/table_content?table_name=${params.table_name}&page=${params.page}&size=${params.size}`,
     method: 'get'
-  })
+  });
 
 params = {
   table_name: '', // 文件名称
   page: 1, // 页数，现规定为1
   size: 100 // 最大请求数，现规定为100
-}
+};
 ```
 
 - 获取文件数据
@@ -126,7 +173,7 @@ export const tableInfo = (id: number): any =>
   request({
     url: `/jpt/datamanagement/info?id=${id}`,
     method: 'get'
-  })
+  });
 ```
 
 #### `browser.tsx`
@@ -148,7 +195,7 @@ export const getDataMgmtList = (): any =>
   request({
     url: `/jpt/datamanagement/`,
     method: 'get'
-  })
+  });
 ```
 
 本文件中主要是查看和删除两个功能，转存数据的函数绑定在查看上。
@@ -164,7 +211,7 @@ export const tableInfo = (id: number): any =>
   request({
     url: `/jpt/datamanagement/info?id=${id}`,
     method: 'get'
-  })
+  });
 ```
 
 若数据转存成功，则能够正常打开文件，如图：
@@ -184,7 +231,7 @@ export const deleteDataMgmt = (id: string): any =>
   request({
     url: `/jpt/datamanagement/?data_management_id=${id}`,
     method: 'delete'
-  })
+  });
 ```
 
 若删除成功，则会提示删除成功
@@ -216,13 +263,13 @@ export const tableInfo = (id: number): any =>
   request({
     url: `/jpt/datamanagement/info?id=${id}`,
     method: 'get'
-  })
+  });
 
 export const tableContent = (params: ITableContent): any =>
   request({
     url: `/jpt/datamanagement/table_content?table_name=${params.table_name}&page=${params.page}&size=${params.size}`,
     method: 'get'
-  })
+  });
 ```
 
 `tableInfo` 用于获取数据预览以上部分的数据，如图：
@@ -300,13 +347,13 @@ export const getDebugTable = (params: any) =>
     url: `/jpt/datamanagement/`,
     method: 'get',
     params
-  })
+  });
 
 // params参数
 params = {
   user_id: 'test',
   project_id: 'test'
-}
+};
 ```
 
 - 获取系统数据调试表
@@ -316,7 +363,7 @@ export const getLocalDebugTable = () =>
   request({
     url: `/jpt/datasource/ailab_table`,
     method: 'get'
-  })
+  });
 ```
 
 - 获取中间数据列表（已弃用）
@@ -327,7 +374,7 @@ export const getIntermediate = (params: any) =>
     url: `/jpt/intermediate/get_intermediate`,
     method: 'get',
     params
-  })
+  });
 ```
 
 - 获取文件信息（已弃用）
@@ -338,7 +385,7 @@ export const getFileData = (params: any) =>
     url: `/jpt/files`,
     method: 'get',
     params
-  })
+  });
 ```
 
 - 代码校验
@@ -349,12 +396,12 @@ export const codeCheck = (params: any) =>
     url: `/jpt/code_check`,
     method: 'post',
     params
-  })
+  });
 
 params = {
   code: '', // 代码
   code_type: 'sql' ? 'sql' : 'python' // 代码类型
-}
+};
 ```
 
 - 执行代码
@@ -365,7 +412,7 @@ export const executeDag = (params: any) =>
     url: `/jpt/dag/execute`,
     method: 'post',
     data: params
-  })
+  });
 
 params = {
   dag_uuid: '', // dag文件的ID
@@ -373,7 +420,7 @@ params = {
     sub_nodes: script_nodes,
     edges: script_edges
   })
-}
+};
 ```
 
 - 节点状态
@@ -383,7 +430,7 @@ export const debugStatus = (uuid: string) =>
   request({
     url: `/jpt/dag/debug_status?dag_uuid=${uuid}`, // uuid: dag文件的ID
     method: 'get'
-  })
+  });
 ```
 
 - 节点执行日志
@@ -393,12 +440,12 @@ export const getNodeLog = (params: any) =>
   request({
     url: `/jpt/dag/node_log?dag_uuid=${params.dag_uuid}&node_id=${params.node_id}`,
     method: 'get'
-  })
+  });
 
 params = {
   dag_uuid: '', // dag文件的ID
   node_id: '' // 节点的ID
-}
+};
 ```
 
 - 节点结果表表格部分
@@ -408,13 +455,13 @@ export const getNodeResult = (params: any) =>
   request({
     url: `/jpt/dag/node_result_data?dag_uuid=${params.dag_uuid}&node_id=${params.node_id}&out_pin=${params.out_pin}`,
     method: 'get'
-  })
+  });
 
 params = {
   dag_uuid: '', // dag文件ID
   node_id: '', // 节点ID
   out_pin: 0 // 输出pin脚，现规定为0
-}
+};
 ```
 
 - 节点结果表明细部分
@@ -424,13 +471,13 @@ export const getNodeResultInfo = (params: any) =>
   request({
     url: `/jpt/dag/node_result_info?dag_uuid=${params.dag_uuid}&node_id=${params.node_id}&out_pin=${params.out_pin}`,
     method: 'get'
-  })
+  });
 
 params = {
   dag_uuid: '', // dag文件ID
   node_id: '', // 节点ID
   out_pin: 0 // 现规定为0
-}
+};
 ```
 
 - 上传至项目目录
@@ -441,13 +488,13 @@ export const uploadFile = (params: any) =>
     url: '/jpt/files/upload_file',
     method: 'post',
     data: params
-  })
+  });
 
 params = {
   file: [blob], // 二进制文件，blob格式
   project_id: '', // 工程ID，现规定为test
   file_type: '' // 文件类型，现规定为dag
-}
+};
 ```
 
 - 中间结果另存为
@@ -458,7 +505,7 @@ export const saveNodeTable = (params: any) =>
     url: '/jpt/datamanagement/',
     method: 'post',
     data: params
-  })
+  });
 
 params = {
   name: '', // 文件名
@@ -468,7 +515,7 @@ params = {
   dag_uuid: '', // dag文件ID
   node_id: '', // 节点ID
   out_pin: '' // 选择的输出pin脚
-}
+};
 ```
 
 - 获取调试数据表对应的节点及数据类型
@@ -478,7 +525,7 @@ export const getSchema = (table_name: string) =>
   request({
     url: `/jpt/datamanagement/table_schema?table_name=${table_name}`, // table_name 调试数据表的名称
     method: 'get'
-  })
+  });
 ```
 
 - sql 数据源表预览
@@ -488,7 +535,7 @@ export const getSqlDsTable = (table_name: string) =>
   request({
     url: `/jpt/dag/dag_node_content?table_name=${table_name}&page=${1}&size=${100}`,
     method: 'get'
-  })
+  });
 ```
 
 - 依赖编辑
@@ -499,12 +546,12 @@ export const postRequirements = (params: any) =>
     url: `/jpt/dag/install_requirements`,
     method: 'post',
     data: params
-  })
+  });
 
 params = {
   requirements: '', // 依赖名
   dag_uuid: '' // dag文件ID
-}
+};
 ```
 
 - 获取依赖相关数据
@@ -514,7 +561,7 @@ export const getRequirementsStatus = (id: string) =>
   request({
     url: `/jpt/dag/requirements_status?dag_uuid=${id}`,
     method: 'get'
-  })
+  });
 ```
 
 #### `AlgoNode.tsx`
@@ -530,7 +577,7 @@ export const debugStatus = (uuid: string) =>
   request({
     url: `/jpt/dag/debug_status?dag_uuid=${uuid}`, // uuid: 节点的ID
     method: 'get'
-  })
+  });
 ```
 
 - 未开始执行
@@ -569,12 +616,12 @@ export const getNodeLog = (params: any) =>
   request({
     url: `/jpt/dag/node_log?dag_uuid=${params.dag_uuid}&node_id=${params.node_id}`,
     method: 'get'
-  })
+  });
 
 params = {
   dag_uuid: '', // dag文件的ID
   node_id: '' // 节点的ID
-}
+};
 ```
 
 ![执行日志](/images/Snipaste_2023-02-21_09-59-05.jpg)
@@ -588,13 +635,13 @@ export const getNodeResultInfo = (params: any) =>
   request({
     url: `/jpt/dag/node_result_info?dag_uuid=${params.dag_uuid}&node_id=${params.node_id}&out_pin=${params.out_pin}`,
     method: 'get'
-  })
+  });
 
 params = {
   dag_uuid: '', // dag文件ID
   node_id: '', // 节点ID
   out_pin: 0 // 现规定为0
-}
+};
 ```
 
 `getNodeResultInfo` 用于获取结果表内表格以上的信息，如图。
@@ -606,12 +653,12 @@ export const getNodeLog = (params: any) =>
   request({
     url: `/jpt/dag/node_log?dag_uuid=${params.dag_uuid}&node_id=${params.node_id}`,
     method: 'get'
-  })
+  });
 
 params = {
   dag_uuid: '', // dag文件的ID
   node_id: '' // 节点的ID
-}
+};
 ```
 
 `getNodeResult` 用于获取结果表内表格内的信息，如图。
@@ -638,7 +685,7 @@ export const saveNodeTable = (params: any) =>
     url: '/jpt/datamanagement/',
     method: 'post',
     data: params
-  })
+  });
 
 params = {
   name: '', // 文件名
@@ -648,7 +695,7 @@ params = {
   dag_uuid: '', // dag文件ID
   node_id: '', // 节点ID
   out_pin: 0 // 选择的输出pin脚
-}
+};
 ```
 
 若在点击确认后，得到如图所示的反馈，极为数据转存成功。
@@ -718,20 +765,20 @@ export const getDebugTable = (params: any) =>
     url: `/jpt/datamanagement/`,
     method: 'get',
     params
-  })
+  });
 
 // params参数
 params = {
   user_id: 'test',
   project_id: 'test'
-}
+};
 
 // 获取系统数据，不带params参数
 export const getLocalDebugTable = () =>
   request({
     url: `/jpt/datasource/ailab_table`,
     method: 'get'
-  })
+  });
 ```
 
 - 添加调试数据表
@@ -762,7 +809,7 @@ export const getSchema = (table_name: string) =>
   request({
     url: `/jpt/datamanagement/table_schema?table_name=${table_name}`,
     method: 'get'
-  })
+  });
 
 //此处的参数 *table_name* ，为上一步中获取的参数，例：table_name = datamiing.d_evt_product_order_dtl
 ```
@@ -895,7 +942,7 @@ export const getSqlDsTable = (table_name: string) =>
   request({
     url: `/jpt/dag/dag_node_content?table_name=${table_name}&page=${1}&size=${100}`, // table_name 调试数据表的名称
     method: 'get'
-  })
+  });
 ```
 
 `pyspark` 会在页面加载时自动获取 dag 文件 ID、节点 ID 与输出 pin 脚，并调用 `getNodeResult` 函数。
@@ -905,13 +952,13 @@ export const getNodeResult = (params: any) =>
   request({
     url: `/jpt/dag/node_result_data?dag_uuid=${params.dag_uuid}&node_id=${params.node_id}&out_pin=${params.out_pin}`,
     method: 'get'
-  })
+  });
 
 params = {
   dag_uuid: '', // dag文件ID
   node_id: '', // 节点ID
   out_pin: 0 // 输出pin脚，现规定为0
-}
+};
 ```
 
 此处也是采用了分页的手法，对数据进行分段获取，提高展示的流畅度。
@@ -980,7 +1027,7 @@ export const getRequirementsStatus = (id: string) =>
   request({
     url: `/jpt/dag/requirements_status?dag_uuid=${id}`,
     method: 'get'
-  })
+  });
 ```
 
 ![](/images/Snipaste_2023-02-21_10-15-07.jpg)
@@ -993,12 +1040,12 @@ export const postRequirements = (params: any) =>
     url: `/jpt/dag/install_requirements`,
     method: 'post',
     data: params
-  })
+  });
 
 params = {
   requirements: '', // 依赖名
   dag_uuid: '' // dag文件ID
-}
+};
 ```
 
 在 _上传至项目目录_ 中可以将执行无误的程序上传至项目目录。
@@ -1011,11 +1058,11 @@ export const uploadFile = (params: any) =>
     url: '/jpt/files/upload_file',
     method: 'post',
     data: params
-  })
+  });
 
 params = {
   file: [blob], // 二进制文件，blob格式
   project_id: '', // 工程ID，现规定为test
   file_type: '' // 文件类型，现规定为dag
-}
+};
 ```