12 KiB
12 KiB
创建流程草稿接口
一句话:调一次接口,就能给任意类型的流程建出一张草稿,人在页面草稿箱里点开接着填。
面向两类人:本系统前端(登录态)、外部系统(应用令牌)。两条路共用同一套口径
(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 这三类话
不是错误,草稿已经存好了;分三类是按"到发起那一刻会不会挡你"排的:
发起时会被表单校验挡住:…—— 取值本身不合法(选项值早就不在字典里、级联没选到末级)。现在说,是省一趟返工。还差 N 项才提交得了:…(草稿不拦,填全了再发起)—— 必填还没填。草稿的意义就是先存一半。表单里没有这几个字段…/「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. 代码落点
- 口径:backend/app/service/drafts.py(认流程、参数清单、数据体检、标题、落库)
- 页面侧接口:backend/app/api/support.py
- 外部侧接口:backend/app/api/openapi.py,授权范围在 backend/app/service/openauth.py
- 标题口径:backend/app/service/titles.py;发起范围: backend/app/service/starters.py
- 字段权限与明细表整型:backend/app/service/formruntime.py