# 创建流程草稿接口 一句话:**调一次接口,就能给任意类型的流程建出一张草稿,人在页面草稿箱里点开接着填。** 面向两类人:本系统前端(登录态)、外部系统(应用令牌)。两条路共用同一套口径 ([backend/app/service/drafts.py](../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 `,令牌来自 `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` 为节选): ```bash 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}}' ``` ```json { "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`: ```json {"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. 外部系统这条路 先换访问令牌,再调数据面: ```bash 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. 代码落点 * 口径:[backend/app/service/drafts.py](../backend/app/service/drafts.py)(认流程、参数清单、数据体检、标题、落库) * 页面侧接口:[backend/app/api/support.py](../backend/app/api/support.py) * 外部侧接口:[backend/app/api/openapi.py](../backend/app/api/openapi.py),授权范围在 [backend/app/service/openauth.py](../backend/app/service/openauth.py) * 标题口径:[backend/app/service/titles.py](../backend/app/service/titles.py);发起范围: [backend/app/service/starters.py](../backend/app/service/starters.py) * 字段权限与明细表整型:[backend/app/service/formruntime.py](../backend/app/service/formruntime.py)