工作流接口对接文档

适用于通过 OpenAPI 拿到 user_token 后调用工作流业务接口的第三方系统。 所有接口前缀：/workflow/，需在 Header 中携带 Authorization: Bearer <user_token>。

---

1. 概念与流程总览

1.1 核心概念

概念	说明
Workflow	工作流定义（流程模板），如"请假流程"。
FlowList	由 Workflow 实例化出的"流程版本"，含 nodes（流程节点 JSON）。
Form	流程绑定的表单，定义申请人需填写的字段。
FormData	一条申请记录，关联 flowId + formId。
FlowCheck	一条审核记录，每个审批节点对每位审批人会产生一条记录。
FlowCopy	抄送记录，节点可配置抄送给指定用户。
Node	流程节点：type=1审批节点 / type=2抄送节点 / type=3条件节点 / type=4发起人节点 / type=5结束节点。
workType	业务类型：0=审批流（work）/ 1=任务流（task）。

1.2 完整调用流程

① GET  /workflow/list                      → 列出可用工作流
② GET  /workflow/addbefore?id=<workflowId> → 取流程详情 + 关联表单
③ POST /workflow/adddata                   → 提交申请（创建 FormData + 触发流程）
④ GET  /workflow/datalist                  → 我发起的申请列表
⑤ GET  /workflow/mychecklist               → 待我审批的列表
⑥ GET  /workflow/getcheckdata?id=<checkId> → 取单条待审批数据详情
⑦ POST /workflow/checkflowdata             → 提交审批结果（通过/驳回/转交）
⑧ GET  /workflow/getflowcheckcomments      → 查看审核历史意见

---

2. 接口总览

2.1 接口分类

类别	接口数	用途
流程查询	4	列表、详情、流程图
申请发起	3	提交、重新提交、查询
审批操作	4	待办、取数据、审批、意见
抄送	2	发出、收到
父子流程	3	流程关系查询
工具	4	部门用户、视图、导出

2.2 接口清单

Method	路径	说明
GET	/workflow/list	工作流列表（按业务类型）
GET	/workflow/addbefore	申请前置：流程详情 + 表单
POST	/workflow/adddata	提交新申请（核心）
POST	/workflow/resubmitflowformdata	驳回后重新提交
GET	/workflow/getdata	获取一条申请数据
GET	/workflow/datalist	我发起的申请列表
GET	/workflow/myauditdatalist	我审核过的数据列表
GET	/workflow/formdata	获取前端列表表格定义
GET	/workflow/getview	获取流程图（含数据）
GET	/workflow/mychecklist	待我审批的列表
GET	/workflow/getcheckdata	单条待审批数据
POST	/workflow/checkflowdata	提交审批结果
GET	/workflow/getflowcheckcomments	流程审核历史意见
GET	/workflow/getcopytomelist	收到的抄送
GET	/workflow/getcopyfrommelist	发出的抄送
POST	/workflow/getusersbydeptids	按部门 ID 列出用户
GET	/workflow/exportdata	导出申请数据
GET	/workflow/getFlowRelation	父子流程关系
GET	/workflow/getParentFlowChildren	父流程的所有子流程
GET	/workflow/getWorkFlowListByType	按业务类型获取流程列表

---

3. 接口详解

3.1 获取工作流列表

GET /workflow/list?workType=0

参数	必填	说明
workType	❌	0=审批流（默认）/ 1=任务流

响应（示意）：

{
  "code": 0,
  "data": [
    {
      "id": 7,
      "name": "请假申请",
      "workType": 0,
      "formId": 12,
      "flowType": 1
    }
  ]
}

---

3.2 取申请前置数据

GET /workflow/addbefore?id=<workflowId>

返回流程节点定义、绑定的表单、当前用户可写的字段等。第三方系统据此渲染申请表单。

该接口在源码中标注 NeedAuth=0，但建议仍带 token 以获得正确的"当前用户"上下文。

---

3.3 提交申请（核心）

POST /workflow/adddata

提交一条新的工作流申请。

Body (JSON)：

{
  "flowId": 7,
  "data": "{\"reason\":\"出差北京\",\"amount\":2000,\"days\":3,\"start_date\":\"2025-06-01\"}",
  "copyers": "12,15",
  "is_draft": false
}

字段	类型	必填	说明
flowId	int	✅	目标流程 ID（即 FlowList.id）
data	string	✅	表单数据 JSON 字符串（键为 form 字段 field）
copyers	string	❌	发起人手动选择的抄送用户 ID（逗号分隔）
is_draft	bool	❌	是否仅存为草稿（不真正触发流程）

响应：

{ "code": 0, "msg": "success", "data": { "id": 1024 } }

返回的 id 即新建的 FormData.id。

---

3.4 重新提交（驳回后修改）

POST /workflow/resubmitflowformdata

Body 与 adddata 类似，额外需 id（原 FormData.id），流程会自动从被驳回的节点重新流转。

{
  "id": 1024,
  "data": "{\"reason\":\"修正后的事由\",\"amount\":1500,...}",
  "copyers": "",
  "is_draft": false
}

---

3.5 获取单条申请数据

GET /workflow/getdata?id=<formDataId>

返回 FormData 详情，包含 data、status、节点位置等。

---

3.6 我发起的申请列表

GET /workflow/datalist

参数	必填	说明
page	❌	页码（默认 1，每页固定 10 条）
workType	❌	0/1
knowId	❌	知识库 ID 过滤
param	❌	URL编码的子查询 flowId=7&status=1

响应：

{
  "code": 0,
  "data": {
    "total": 12,
    "datalist": [
      {
        "id": 1024,
        "flowName": "请假申请",
        "nodeId": "node_xxxx",
        "status": 1,
        "add_time": 1717150000
      }
    ],
    "flowlist": [
      { "flowId": 7, "name": "请假申请" }
    ],
    "userId": 100
  }
}

status 含义：0未审批 / 1审批中 / 2审批通过 / 3驳回上一节点 / 4驳回到初始 / 9已全部通过。

---

3.7 待我审批的列表

GET /workflow/mychecklist

参数	必填	说明
page	✅	页码
limit	✅	每页条数
checkStatus	❌	0=全部 / 1=待审 / 2=已审
status	❌	流程状态过滤；传 -1 表示不过滤
knowId	❌	知识库过滤

响应：

{
  "code": 0,
  "data": {
    "total": 3,
    "datalist": [
      {
        "id": 88,
        "checkerId": 100,
        "dataId": 1024,
        "cronId": 7,
        "nodeId": "node_xxxx",
        "status": 1,
        "all_status": 0,
        "flowName": "请假申请",
        "flowType": 1,
        "add_time": 1717150000
      }
    ]
  }
}

⚠️ 这里返回的 id 是 FlowCheck.id（审批记录 ID），不是 FormData.id。下一步 getcheckdata 与 checkflowdata 都使用此 id。

---

3.8 获取待审批数据详情

GET /workflow/getcheckdata?id=<flowCheckId>

响应：

{
  "code": 0,
  "data": {
    "checkData": {
      "id": 88,
      "dataId": 1024,
      "cronId": 7,
      "nodeId": "node_xxxx",
      "checkerId": 100,
      "status": 1
    },
    "nodeData": {
      "nodeId": "node_xxxx",
      "nodeName": "部门经理审批",
      "type": 1,
      "settype": 1
    },
    "allowCopyList": [
      { "id": 15, "nickname": "李四" }
    ],
    "readonlyFields": ["amount"]
  }
}

字段	含义
checkData	FlowCheck 记录
nodeData	当前节点配置（去掉了子节点防泄露）
allowCopyList	子节点是抄送 + 允许自选时返回的可选用户
readonlyFields	当前节点对哪些表单字段只读

---

3.9 审批操作（核心）

POST /workflow/checkflowdata

Body (JSON)：

{
  "id": 88,
  "checkAction": 1,
  "passBackDesc": "同意",
  "userIdsStr": "15,16",
  "sign_base64": "data:image/png;base64,iVBORw0KGgoAAAANS...",
  "attachments": "[{\"name\":\"附件.pdf\",\"url\":\"/upload/x.pdf\"}]"
}

字段	类型	必填	说明
id	int	✅	FlowCheck.id（来自 mychecklist）
checkAction	int	✅	审批动作：1=通过 / 2=驳回到上一节点 / 3=驳回到发起人 / 4=转交他人
passBackDesc	string	❌	审批意见（驳回时建议必填）
userIdsStr	string	❌	转交时填接收用户 ID；通过+自选抄送时填新增抄送人 ID
sign_base64	string	❌	手写签名 Base64 字符串
attachments	string	❌	附件 JSON 字符串 [{name,url}]

响应：

{ "code": 0, "msg": "success", "data": null }

⚠️ 后端会校验：仅当 status in (待审/进行中) 且 all_status=0（流程未结束）时才允许操作。

---

3.10 流程审核历史意见

GET /workflow/getflowcheckcomments?workflowId=<formDataId>

参数名虽然叫 workflowId，但实际传的是 FormData.id（一条申请的 ID）。

响应：

{
  "code": 0,
  "data": {
    "flowChecks": [
      {
        "id": 86,
        "nodeName": "部门经理",
        "checkerId": 100,
        "checkerName": "张三",
        "status": 2,
        "passBackDesc": "同意",
        "checkTime": 1717160000
      }
    ]
  }
}

---

3.11 抄送列表

收到的抄送：GET /workflow/getcopytomelist我发出的抄送：GET /workflow/getcopyfrommelist

参数	必填	格式	说明
start_date	✅	YYYY-MM-DD	开始日期
end_date	✅	YYYY-MM-DD	结束日期（≥ start_date）
page	✅	int	页码
limit	✅	int	每页

---

3.12 按部门 ID 取用户列表

POST /workflow/getusersbydeptids

{ "deptIds": [1, 2, 5] }

返回所选部门下所有用户。

---

3.13 流程图

GET /workflow/getview?id=<formDataId>

返回 { data: <FormData>, flow: <FlowList> }，第三方系统可使用 flow.nodes JSON 自行渲染流程图。

---

3.14 父子流程相关

接口	用途
GET /workflow/getFlowRelation	取流程类型与父子关系映射
GET /workflow/getParentFlowChildren?parentId=<id>	列出父流程下所有子流程数据
GET /workflow/getWorkFlowListByType?flowType=<n>	按 flowType 取流程列表

---

4. 状态字段对照表

4.1 FormData.status（申请单状态）

值	含义
0	未审批（草稿）
1	审批中
2	审批通过（已完成所有节点）
3	被驳回到上一节点
4	被驳回到发起人
9	流程已全部通过（终态）

4.2 FlowCheck.status（节点审批记录状态）

值	含义
1	待审
2	进行中（已开始未完成）
3	已通过
4	已驳回
5	已转交

4.3 checkAction（审批动作）

值	含义
1	通过
2	驳回到上一节点
3	驳回到发起人
4	转交他人

4.4 Node.type（节点类型）

值	含义
1	审批节点
2	抄送节点
3	条件节点
4	发起人节点
5	结束节点

---

5. 完整对接示例（Node.js）

const axios = require('axios')

class GodoWorkflow {
  constructor(baseUrl, userToken) {
    this.http = axios.create({
      baseURL: baseUrl,
      headers: { Authorization: `Bearer ${userToken}` }
    })
  }

  // 提交申请
  async submitApply(flowId, formData, copyers = '') {
    const { data } = await this.http.post('/workflow/adddata', {
      flowId,
      data: JSON.stringify(formData),
      copyers,
      is_draft: false
    })
    return data
  }

  // 待办列表
  async myTodos(page = 1, limit = 20) {
    const { data } = await this.http.get('/workflow/mychecklist', {
      params: { page, limit, checkStatus: 1, status: -1 }
    })
    return data.data
  }

  // 审批通过
  async approve(checkId, comment = '同意') {
    const { data } = await this.http.post('/workflow/checkflowdata', {
      id: checkId,
      checkAction: 1,
      passBackDesc: comment
    })
    return data
  }

  // 审批驳回
  async reject(checkId, comment = '不同意') {
    const { data } = await this.http.post('/workflow/checkflowdata', {
      id: checkId,
      checkAction: 3,
      passBackDesc: comment
    })
    return data
  }

  // 查询我发起的
  async myApplies(page = 1) {
    const { data } = await this.http.get('/workflow/datalist', {
      params: { page, workType: 0 }
    })
    return data.data
  }
}

// 使用示例
;(async () => {
  const wf = new GodoWorkflow('https://your-godocloud.com', 'eyJhbGc...')

  // 1. 提交一个请假申请
  const apply = await wf.submitApply(7, {
    reason: '出差北京',
    amount: 2000,
    days: 3,
    start_date: '2025-06-01'
  }, '12,15')
  console.log('已提交:', apply)

  // 2. 处理我的待办
  const todos = await wf.myTodos()
  for (const todo of todos.datalist) {
    console.log(`处理：${todo.flowName} #${todo.dataId}`)
    await wf.approve(todo.id, '同意')
  }
})()

---

6. 注意事项

1. id 含义区分：
   • FormData.id —— 一次申请（适用于 getdata/getview/getflowcheckcomments）。
   • FlowList.id —— 流程版本（适用于 adddata.flowId）。
   • FlowCheck.id —— 一个节点的审批记录（适用于 getcheckdata/checkflowdata）。
   • Workflow.id —— 工作流定义（适用于 addbefore.id）。
2. data 字段必须是 JSON 字符串，不要直接传 JSON 对象。
3. 驳回后再提交 必须用 resubmitflowformdata，不能用 adddata（会生成新申请）。
4. 审批权限校验：只有当前节点的指定审批人才能操作；非指定人调用 checkflowdata 会被拒绝。
5. 多人会签节点：当 nodeData.settype=2（会签）时，所有审批人都需通过才能进入下一节点。
6. 抄送是自动的：节点配置中抄送对象会自动生成 FlowCopy 记录，无需第三方主动调用。
7. 流程节点解析：完整节点树存放在 FlowList.nodes JSON 中，第三方可解析以了解整个流程的走向。
8. workType=0 与 1 区别：workType=0 为标准审批流；workType=1 为任务流（通常不需审批，由发起人指定执行人）。

---

7. 常见问题

Q1：申请提交后流程没有走起来？ A：检查 is_draft 是否为 false；检查表单 data 字段是否包含流程节点的"分支条件字段"。

Q2：审批人提示"无权操作"？ A：可能是该节点已被其他人审批（会签/或签场景），调用 getcheckdata 确认 status 是否仍是待审。

Q3：如何实现"加签"或"转交"？ A：使用 checkAction=4 + userIdsStr 指定接收人即可转交；当前 API 暂未直接暴露"加签"，需通过抄送变通。

Q4：流程结束后是否能再修改 FormData.data？ A：不可以。后端会拒绝修改终态（status=9 或 2）的数据。

Q5：如何监听流程进度？ A：建议第三方系统轮询 getdata 或 getflowcheckcomments；如需实时推送可联系平台开通 Webhook（独立配置）。