109 lines
4.5 KiB
Markdown
109 lines
4.5 KiB
Markdown
# 审批提单值来源
|
||
|
||
## 目的
|
||
|
||
本文用于回答一个固定问题：在调用 `approval instances create` 发起原生审批实例时，**每个要填写的值从哪里拿**。
|
||
|
||
阅读顺序固定如下：
|
||
|
||
1. [`lark-approval-initiate.md`](./lark-approval-initiate.md) 中的创建请求参数、节点参数和返回结果说明
|
||
2. `approval approvals get` 返回的 `form` / `node_list`
|
||
3. [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md)
|
||
4. 本文
|
||
|
||
## 总原则
|
||
|
||
- `lark-approval-initiate.md` 决定创建请求字段名、字段层级、节点参数结构。
|
||
- `approvals.get.form` 决定控件 `id`、`type`、选项值范围、子控件结构。
|
||
- `approvals.get.node_list` 决定节点 key、是否必须补审批人、是否允许多人。
|
||
- [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md) 决定各控件 `value` 的最终结构。
|
||
- 除非本文明确允许，否则不要猜值来源，不要把展示文案直接当成可提交值。
|
||
|
||
## 默认来源
|
||
|
||
- 审批定义、`approval_code`、`is_external`、`create_link` 等基础信息，默认从 `approval approvals search` 获取。
|
||
- 控件 `id`、`type`、选项值、子控件结构，默认从 `approval approvals get.form` 获取。
|
||
- 节点 key、`need_approver`、`approver_chosen_multi` 等节点信息，默认从 `approval approvals get.node_list` 获取。
|
||
- 本文只补充 **这些默认来源之外** 的取值规则，以及当前必须由用户直接提供的值。
|
||
|
||
## 控件值来源规则
|
||
|
||
### 联系人 `contact`
|
||
|
||
- 只推荐写 `open_ids`。
|
||
- 不再推荐双写 `value(user_id)` + `open_ids`，避免复杂度继续上升。
|
||
- 如果用户给的是姓名、邮箱或账号，先用 `lark-contact` 解析成 `open_id`。
|
||
|
||
### 部门 `department`
|
||
|
||
- 最优先：用户直接提供 `open_department_id`。
|
||
- 若用户说“我的部门”或“张三的部门”，先用 `lark-contact` 查询对应人员信息，再取其所属部门里的 `open_department_id`。
|
||
- 如果查到该人员只有一个部门，可直接使用。
|
||
- 如果查到多个部门，不自动猜，必须让用户明确选一个，或直接输入 `open_department_id`。
|
||
- 如果仍无法确定，则明确告知当前不支持自动决定部门值。
|
||
|
||
### 附件 `attachmentV2`
|
||
|
||
- 当前 `lark-approval` 不负责上传文件。
|
||
- 用户必须直接提供 file code。
|
||
- 如果用户无法提供 file code，应明确告知当前无法仅通过 `lark-approval` 完成该控件提单。
|
||
|
||
### 图片 `image` / `imageV2`
|
||
|
||
- 当前 `lark-approval` 不负责上传图片。
|
||
- 用户必须直接提供 file code。
|
||
- 如果用户无法提供 file code，应明确告知当前无法仅通过 `lark-approval` 完成该控件提单。
|
||
|
||
### 文档 `document`
|
||
|
||
- 用户可直接提供 `token` / `document_id`。
|
||
- 如果用户给的是飞书文档链接，应先尝试从链接中提取 token。
|
||
- 若链接提取失败，再要求用户手动输入 token。
|
||
|
||
### 关联审批 `connect`
|
||
|
||
- 用户直接提供目标审批实例的 `instance_code`。
|
||
- 当前不默认做“搜索关联实例再反查 code”的自动流程。
|
||
|
||
### 地址 `address`
|
||
|
||
- 用户直接提供地理库 `id`。
|
||
- 若用户无法提供该 `id`，当前不支持自动取值。
|
||
|
||
## 特殊控件组
|
||
|
||
以下控件组的结构仍按 [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md) 组装：
|
||
|
||
- `leaveGroupV2`
|
||
- `workGroup`
|
||
- `outGroup`
|
||
- `shiftGroup`
|
||
|
||
补充规则：
|
||
|
||
- 控件组自身和子控件的 `id` / `type` 从 `approval approvals get.form` 中识别。
|
||
- 组内单选/多选或业务枚举值，优先从 `approval approvals get.form` 返回的选项结构中取。
|
||
- 不要把控件组整体当成普通字符串或扁平对象提交。
|
||
|
||
## 不支持自动准备的值
|
||
|
||
以下值当前不建议由 `lark-approval` 自动准备：
|
||
|
||
- 文件上传后的 file code
|
||
- 图片上传后的 file code
|
||
- 地址控件的地理库 `id`
|
||
- 无法唯一确定的部门 `open_department_id`
|
||
|
||
遇到这类值时，应明确告诉用户需要提供什么，而不是继续猜测。
|
||
|
||
## 最小决策表
|
||
|
||
| 场景 | 处理 |
|
||
|---|---|
|
||
| 用户说“找张三当审批人” | 用 `lark-contact` 解析张三，取 `open_id` |
|
||
| 用户说“我的部门” | 先查当前用户部门；若多个部门，让用户选 |
|
||
| 用户给了文档链接 | 先尝试提取 token |
|
||
| 用户要填图片/附件 | 要求直接提供 file code |
|
||
| 用户要填关联审批 | 要求直接提供 `instance_code` |
|
||
| 用户要填地址 | 要求直接提供地理库 `id` |
|