205 lines
12 KiB
Markdown
205 lines
12 KiB
Markdown
|
||
# 创建流程草稿接口
|
||
|
||
一句话:**调一次接口,就能给任意类型的流程建出一张草稿,人在页面草稿箱里点开接着填。**
|
||
|
||
面向两类人:本系统前端(登录态)、外部系统(应用令牌)。两条路共用同一套口径
|
||
([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 <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` 为节选):
|
||
|
||
```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)
|