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

205 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

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