unis-oa/docs/draft-create-api.md

12 KiB
Raw Permalink Blame History

创建流程草稿接口

一句话:调一次接口,就能给任意类型的流程建出一张草稿,人在页面草稿箱里点开接着填。

面向两类人:本系统前端(登录态)、外部系统(应用令牌)。两条路共用同一套口径 (backend/app/service/drafts.py),差别只在"以谁的身份" 怎么给:页面用登录会话,外部系统用 identity 点名。

接口 谁用 干什么
GET /api/v1/draft/types 调用方 查有哪些流程类型、每个类型要传哪些参数
POST /api/v1/draft 页面 / 脚本 建一张草稿(带 dryRun 只体检不落库)
GET /api/v1/draft 页面 我的草稿箱
PUT /api/v1/draft/{id} 页面 / 调用方 改草稿(顺带换流程类型也可以)
DELETE /api/v1/draft/{id} 页面 删草稿
POST /api/v1/open/drafts 外部系统 替某个身份建草稿
GET /api/v1/open/drafts 外部系统 查某个身份的草稿

1. 通用约定

  • 前缀 /api/v1,统一响应体 {"code": 0, "message": "", "data": ...},code != 0 即失败。
  • 页面侧鉴权:Authorization: Bearer <access_token>,令牌来自 POST /api/v1/auth/login。
  • 请求体下划线与驼峰两种写法都收(dryRun == dry_run),未定义的键一律忽略。
  • 时间是本地时区的 YYYY-MM-DD HH:mm:ss。
  • 草稿只属于建它的那个人:person 决定谁能在草稿箱看到它,别人的接口碰不到它。

2. 建草稿:POST /api/v1/draft

参数 类型 必填 说明
process string 是 建哪一类流程。五种写法都认:流程 id、名称、别名、分类/流程名、关键词
category string 否 分类限定(分类 id 或中文名),用来区分同名流程
title string 否 草稿标题。不传就按标题规则生成,再兜底成「某某的XX流程」
data object 否 表单值,键取 params[].key
dry_run bool 否 true 时只体检不落库,库里一个字都不写

请求与响应(data 为节选):

curl -X POST http://127.0.0.1:8000/api/v1/draft \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"process":"印章使用申请","title":"(示例)合同用印申请",
       "data":{"sealCount":2,"reason":"合同用印","no_such":1}}'
{
  "code": 0,
  "data": {
    "id": "c0031464eecf45879dcb6456519f0efe",
    "title": "(示例)合同用印申请",
    "process": "7e5f00a1185a4cff846678b63df4f41d",
    "process_name": "印章使用申请流程",
    "category_name": "行政办公",
    "form": "b8f6545e45704451a3cb6d97af8fa3db",
    "data": {"sealCount": 2, "reason": "合同用印", "no_such": 1},
    "person_name": "系统管理员",
    "identity": "localadmin",
    "create_time": "2026-10-16 09:08:35",
    "update_time": "2026-10-16 09:08:35",
    "page_path": "/start?process=7e5f...&draft=c00314...",
    "notices": [
      "还差 3 项才提交得了:印章申请分类、用印类型、印章形式(草稿不拦,填全了再发起)",
      "表单里没有这几个字段,草稿照样存着,但发起时不会当成表单值:no_such"
    ]
  }
}

page_path 是本站相对路径,拼上站点地址就能点开;只带 ?draft= 也认,流程由草稿自己反查。

dry_run=true 时回的是同一份体检结果,但没有 id:

{"code": 0, "data": {"dry_run": true, "process": "7e5f...", "process_name": "印章使用申请流程",
                     "title": "系统管理员的印章使用申请流程", "data": {}, "notices": ["还差 4 项…"],
                     "page_path": "/start?process=7e5f..."}}

错误码

HTTP reason 什么时候
400 PROCESS_REQUIRED process 空着
400 PROCESS_NOT_FOUND 这个写法找不到流程(带分类时会说清是哪个分类里也没有)
400 PROCESS_AMBIGUOUS 撞上多条同名流程,消息里把候选念出来让人改名。宁可报错也不替你猜:草稿建错流程比建失败难查得多
400 PROCESS_NOT_PUBLISHED 流程还没发布
403 START_FORBIDDEN 这个人不在该流程的发起范围里(与 POST /job 同一把尺子)
401 UNAUTHORIZED 没带令牌或令牌过期

3. 查类型与参数:GET /api/v1/draft/types

参数 说明
process 只查某一个类型(写法同上),传了就回单个对象
keyword / category 清单过滤
params 默认 true,带参数清单;只想要类型清单时传 false

清单只列这个人发得起来的流程——发不起的列出去也建不了。类型对象里值得注意的几个键:

键 说明
ref 流程 id,直接拿去当 process 传最稳
refByName 分类/流程名,人话写法,同样认
page_path 这个类型的发起页
params 参数清单,见下

params[] 一条就是一个表单字段:

键 说明
key 传 data 时用的键名
label 界面上显示的名字(notices 里报的就是它)
type 字段类型,取值形状见第 6 节
required 发起时是否必填(已折过开始环节的字段权限,不是设计器上那个老勾选框)
writable false = 这一格发起环节改不动(只读/隐藏),传了也不生效
system true = 值由系统带出或公式算出,不用传
options / optionSource 合法取值与来源(字典 loanType 或 表单内置选项),最多回 50 条
columns / minRows / maxRows 明细表(type=table)才有;行的键取 columns[].key
unit 金额、数字那类的单位后缀,只是展示用

4. 改与删

  • PUT /api/v1/draft/{id}:请求体同 POST。不带 process 就是原地改数据;带了就把流程类型一起换掉 (换类型后老数据里新表单没有的键会进 notices 提示,不悄悄删)。只能改自己的草稿。
  • DELETE /api/v1/draft/{id}:删自己的草稿(管理员可删别人的)。
  • 草稿被 POST /api/v1/job 用 draft_id 发起成功后,这张草稿自动删掉。

5. 外部系统这条路

先换访问令牌,再调数据面:

curl -X POST http://127.0.0.1:8000/api/v1/open/token \
  -H "Content-Type: application/json" -d '{"app_key":"oa_xxx","app_secret":"xxx"}'

curl -X POST http://127.0.0.1:8000/api/v1/open/drafts \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"identity":"zhangsan","process":"备用金申请",
       "title":"张三的备用金申请","data":{"loanReason":"出差备用"}}'
# → {"code":0,"data":{"draft":{"id":"...","identity":"...","pagePath":"/start?process=...&draft=...", ...},
#                     "notices":["还差 1 项才提交得了:借款类型(草稿不拦,填全了再发起)"]}}
  • 应用要在开放平台里勾上 draft:write(建草稿)/draft:read(查某人的草稿)。 读写分两档是刻意的:草稿是还没提交的半张单,"能替别人铺一张"和"能翻看别人写了什么"是两回事。
  • identity 必填,必须是本系统里存在且在职的身份;没有"以管理员身份"这种兜底。
  • 发起范围照样生效:那个人发不起这个流程,接口就 403。
  • data 与 notices 的口径和第 2 节完全一样;字段名在这条路上是驼峰(processName、pagePath)。
  • 超速率回 429(按应用配置的每分钟上限,读留痕计数判定,多副本一致)。
  • GET /api/v1/open/drafts?identity=...&limit=50 查他草稿箱,limit 上限 200。

6. 各类型字段的取值形状

type 传什么
text textarea mobile email idcard url address 字符串
number money rate 数字(别带单位、千分位、货币符号)
date / datetime / time "2026-10-16" / "2026-10-16 09:00" / "09:00"
daterange ["2026-10-16", "2026-10-20"]
select radio 选项的 value(params[].options[].value,不是中文名)
checkbox value 的字符串数组
switch true / false
cascader 从顶级一路到末级的字典项 value 数组,半条路径会被挡
dept user 部门路径 / 人员引用(登录账号;只有发起环节放开时才轮得到你传。人员引用只认登录账号,写别的等于没填,见 person-reference-design.md)
attachment image 附件对象数组,至少含 id:先 POST /api/v1/attachment 上传再拿 id
relation 关联单据的 job
signature PNG 的 data URL 字符串
table 行对象数组,行的键取 columns[].key
title 字符串;传了顶掉标题规则(表单里有标题字段时优先看这一格)
auto formula 不用传(system: true),传了会被服务端按真实数据重算掉

7. notices 这三类话

不是错误,草稿已经存好了;分三类是按"到发起那一刻会不会挡你"排的:

  1. 发起时会被表单校验挡住:… —— 取值本身不合法(选项值早就不在字典里、级联没选到末级)。现在说,是省一趟返工。
  2. 还差 N 项才提交得了:…(草稿不拦,填全了再发起) —— 必填还没填。草稿的意义就是先存一半。
  3. 表单里没有这几个字段… / 「XX」里有 N 行整行没填,已经丢掉 —— 前者照样存着但不算表单值(引擎也是这个口径,不替调用方丢数据);后者是明细表整型,跟提交时做的是同一件事。

界面只在发起页提示,不当红色警告弹;外部系统建议把第 1 类当失败处理,第 2 类按需忽略。

8. 几个容易踩的地方

  • 草稿不卡必填,也不启动流转。要直接发起用 POST /api/v1/job(页面)或 POST /open/works(外部); 别为了省事硬凑假数据发起——发出去的单子要退回、要终止,比多存一张草稿麻烦得多。
  • 外部建的草稿由本人在页面发起。开放平台的 POST /open/works 不带 draft_id,外部铺的单子 要本人点开 pagePath 确认后自己提交。
  • 同名流程一律报错不猜。别把 process 写成"流程"这种到处都命中的词,用 refByName 或直接传 id。
  • data 会原样存,只有一处例外:明细表按引擎口径整型(丢空行、补列默认值、按 maxRows 截断)。
  • 流程下架或发起范围收紧之后,老草稿还在草稿箱里,但点开会被提示发不起——这是有意留着让人自己确认, 不是悄悄删数据。
  • 草稿箱没有分页:GET /api/v1/draft 一次回全部,拟稿箱不是归档处。

9. 代码落点