东风低代码 - API规范

一、文档概述

1. 文档目的

本文档详细描述 EIMSNext 企业信息管理系统后台 API 的功能、请求参数、响应格式、调用示例等信息，为开发者提供规范的 API 调用指南，助力快速集成系统功能。

2. 系统简介

EIMSNext 是一款企业低代码应用系统，提供身份验证、数据管理、流程控制、文件上传等全方位信息管理解决方案，支持通过 API 实现数据交互，基于 MongoDB 提供持久化存储支持。

3. 基础信息

官方网站：www.eimsnext.com
示例网站：work.eimsnext.com
技术架构：基于 C# / .NET 6 开发，采用 MongoDB 存储数据，支持 JWT 身份认证、OData 数据查询
接口文档支持：OpenAPI/Swagger
许可证：Apache 2.0 许可证

二、通用规范

1. 通信协议

所有 API 接口均采用 HTTP/HTTPS 协议进行通信。

2. 数据格式

请求与响应数据默认使用 JSON 格式（Content-Type: application/json）。

3. 身份认证

接口采用 JWT 令牌进行身份验证，令牌需在请求头中携带：Authorization: Bearer {token}
支持的授权方式：密码验证、验证码验证、单点登录 (SSO)、集成授权

4. 错误响应格式

          { "code": "错误码", "message": "错误描述", "details":
          "详细错误信息（可选）" }
        

5. 分页参数规范（通用）

参数名 <	类型 <	说明 <	是否必填
$top	int	每页显示条数	否
$skip	int	跳过的记录数（分页偏移量）	否
$orderby	string	排序字段（格式：字段名 asc/desc）	否

三、核心 API 接口详情

1. 身份验证模块（Auth）

1.1 发送验证码

POST/auth/sendcode

请求参数：

参数名 <	类型 <	说明 <	是否必填
phone	string	手机号（接收验证码的载体）	是
type	string	验证码类型（login/register/reset 等）	是

响应示例：

            { "code": "200", "message": "验证码发送成功", "data": {
            "expireTime": 300, // 验证码有效期（秒） "phone": "138****1234" } }
          

1.2 获取访问令牌（OAuth2 标准接口）

POST/connect/token

请求头：

Content-Type: application/x-www-form-urlencoded

请求参数（表单格式）：

参数名 <	类型 <	说明 <	是否必填
grant_type	string	授权类型（password/code/sso 等）	是
username	string	用户名（grant_type=password 时必填）	否
password	string	密码（grant_type=password 时必填）	否
code	string	验证码（grant_type=code 时必填）	否
client_id	string	客户端 ID	是
client_secret	string	客户端密钥	是
scope	string	权限范围（多个用空格分隔）	是

响应示例：

            { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // JWT
            访问令牌 "token_type": "Bearer", "expires_in": 3600, //
            令牌有效期（秒） "refresh_token": "def50200a95e8d...", // 刷新令牌
            "scope": "api.read api.write" }
          

1.3 刷新令牌

POST/connect/token

请求头：

Content-Type: application/x-www-form-urlencoded

请求参数（表单格式）：

参数名 <	类型 <	说明 <	是否必填
grant_type	string	授权类型，固定为 refresh_token	是
refresh_token	string	刷新令牌	是
client_id	string	客户端 ID	是
client_secret	string	客户端密钥	是

响应格式：

同“获取访问令牌”

2. 文件上传模块（FileUpload）

2.1 上传文件

POST/api/v1/upload

请求头：

Content-Type: multipart/form-data

请求参数：

参数名 <	类型 <	说明 <	是否必填
file	file	上传的文件流	是
folder	string	存储文件夹（可选，默认存放在根目录）	否
isPublic	boolean	是否公开访问（true/false，默认 false）	否

响应示例：

            { "code": "200", "message": "文件上传成功", "data": { "fileId":
            "f123456789", // 文件唯一标识 "fileName": "test.png", // 原始文件名
            "filePath": "/uploads/2025/12/test.png", // 存储路径 "fileSize":
            204800, // 文件大小（字节） "accessUrl":
            "https://api.eimsnext.com/files/f123456789", // 访问地址
            "uploadTime": "2025-12-04T20:46:52" // 上传时间 } }
          

3. 流程引擎模块（Flow）

3.1 启动工作流

POST/api/v1/workflow/start

请求头：

Authorization: Bearer {token}

请求参数：

参数名 <	类型 <	说明 <	是否必填
flowDefinitionId	string	流程定义 ID	是
businessKey	string	业务关联键（如订单 ID、表单 ID）	是
variables	object	流程变量（键值对格式，根据流程定义传入）	否
initiator	string	流程发起人 ID	是

响应示例：

            { "code": "200", "message": "流程启动成功", "data": {
            "processInstanceId": "proc123456789", // 流程实例 ID
            "flowDefinitionId": "def987654321", // 流程定义 ID "businessKey":
            "order789", // 业务关联键 "status": "running", //
            流程状态（running/completed/canceled） "startTime":
            "2025-12-04T21:00:00" // 启动时间 } }
          

3.2 提交审批

POST/api/v1/workflow/approve

请求头：

Authorization: Bearer {token}

请求参数：

参数名 <	类型 <	说明 <	是否必填
processInstanceId	string	流程实例 ID	是
taskId	string	待办任务 ID	是
approvalResult	string	审批结果（agree/reject）	是
approvalComment	string	审批意见	否
approver	string	审批人 ID	是
variables	object	审批过程变量（可选）	否

响应示例：

            { "code": "200", "message": "审批提交成功", "data": {
            "processInstanceId": "proc123456789", "taskId": "task987654321",
            "approvalResult": "agree", "approvalTime": "2025-12-04T21:30:00",
            "nextTaskId": "task654321987" // 下一个待办任务 ID（如无则为 null）
            } }
          

3.3 触发数据流操作

POST/api/v1/dataflow/run

请求头：

Authorization: Bearer {token}

请求参数：

参数名 <	类型 <	说明 <	是否必填
dataFlowDefinitionId	string	数据流定义 ID	是
inputData	object	输入数据（根据数据流定义传入）	是
operator	string	操作人员 ID	是

响应示例：

            { "code": "200", "message": "数据流执行成功", "data": {
            "dataFlowInstanceId": "dfi123456789", // 数据流实例 ID "outputData":
            { "result": "success", "count": 10 }, // 输出数据 "executeTime":
            150, // 执行耗时（毫秒） "status": "completed" //
            执行状态（completed/failed） } }
          

4. 数据服务模块（Service/Core）

4.1 OData 数据查询（通用接口）

GET/api/v1/{entityName}

注：entityName 为实体名称，如 form、user、department 等

请求头：

Authorization: Bearer {token}

请求参数（OData 标准参数）：

参数名 <	类型 <	说明 <	是否必填
$select	string	筛选返回字段（多个用逗号分隔）	否
$filter	string	过滤条件（如：name eq 'test' and status eq 1）	否
$top	int	每页条数（分页）	否
$skip	int	跳过条数（分页）	否
$orderby	string	排序（如：createTime desc）	否
$expand	string	关联查询（如：user.department）	否

响应示例（用户实体查询）：

            { "value": [ { "id": "user123", "username": "testuser", "name":
            "测试用户", "departmentId": "dept456", "status": 1, "createTime":
            "2025-11-01T10:00:00" }, { "id": "user456", "username": "admin",
            "name": "管理员", "departmentId": "dept789", "status": 1,
            "createTime": "2025-10-01T10:00:00" } ], "@odata.count": 2, //
            总记录数 "@odata.nextLink": "/api/v1/user?$skip=2&$top=2" //
            下一页链接（如存在） }
          

4.2 新增实体（通用接口）

POST/api/v1/{entityName}

请求头：

Authorization: Bearer {token}

请求参数：

实体对应的字段（键值对格式，根据实体定义传入）

响应示例（新增表单）：

            { "code": "200", "message": "实体新增成功", "data": { "id":
            "form789", // 新增实体 ID "name": "员工登记表", "createTime":
            "2025-12-04T22:00:00", "creator": "user123" } }
          

4.3 更新实体（通用接口）

PUT/api/v1/{entityName}/{id}

请求头：

Authorization: Bearer {token}

请求参数：

需要更新的字段（键值对格式）

响应示例：

            { "code": "200", "message": "实体更新成功", "data": { "id":
            "form789", "name": "新版员工登记表", "updateTime":
            "2025-12-04T22:30:00", "updater": "user456" } }
          

4.4 删除实体（通用接口）

DELETE/api/v1/{entityName}/{id}

请求头：

Authorization: Bearer {token}

响应示例：

            { "code": "200", "message": "实体删除成功", "data": { "id":
            "form789" } }
          

四、开发与测试说明

1. 环境准备

安装并运行 MongoDB 数据库
配置 appsettings.json 中的数据库连接信息
启动相关 API 服务（AuthApi、FileUploadApi、FlowApi、ServiceApi）

2. 测试工具

支持 Postman、curl 等工具直接调用接口
支持通过 OpenAPI/Swagger 文档（系统部署后可访问 /swagger 路径）在线调试

3. 开发相关

单元测试：使用 dotnet test 运行
事务管理：通过 MongoTransactionScope 实现
动态表达式执行：使用 V8ScriptEngine
灵活查询：通过 DynamicFindOptions 实现