156 lines
7.6 KiB
Markdown
156 lines
7.6 KiB
Markdown
# OA 个人审批事件
|
||
|
||
先读事件产品入口 [SKILL.md](../SKILL.md) 的命令规则、调用流和子进程契约。本参考覆盖当前公开的七个 OA 个人事件：审批实例发起、抄送、终止和完成，以及审批任务创建、完成和转交。
|
||
|
||
<!-- dws-intent: event.listen.oa -->实时监听审批事件必须使用 `dws event consume` 长连接，不要轮询 OA 待办或审批实例列表来模拟事件。
|
||
|
||
## Prerequisite
|
||
|
||
OA 个人事件使用当前用户 OAuth 登录态。未登录或 token 失效时，先执行：
|
||
|
||
```bash
|
||
dws auth login
|
||
```
|
||
|
||
非默认组织使用全局 `--profile <corpId 或 profile 名>`。事件范围始终是该 OAuth 用户相关的全部 OA 事件，不需要也不接受审批人、发起人或审批模板选择参数。
|
||
|
||
## Event catalog
|
||
|
||
| 事件码 | 订阅规则 | 接收语义 | 必填参数 |
|
||
|---|---|---|---|
|
||
| `user_oa_approval_task_created` | `all` | 审批任务创建，发送给审批人 | 无 |
|
||
| `user_oa_approval_task_finished` | `all` | 审批任务已完成 | 无 |
|
||
| `user_oa_approval_task_redirected` | `all` | 审批任务已转交 | 无 |
|
||
| `user_oa_approval_instance_started` | `all` | 审批实例已发起 | 无 |
|
||
| `user_oa_approval_instance_cc` | `all` | 审批实例到达抄送节点，发送给被抄送人 | 无 |
|
||
| `user_oa_approval_instance_terminated` | `all` | 审批实例已终止 | 无 |
|
||
| `user_oa_approval_instance_finished` | `all` | 审批实例完成，发送给审批单发起人 | 无 |
|
||
|
||
只承认上表 7 个 OA 事件码。CLI 为每个事件发送 `ruleType=all`、`filterRule={}` 的独立订阅请求；不要添加 `--user`、`--open-dingtalk-id`、`--group`、`--query` 或 `--filter-json`。
|
||
|
||
## Intent mapping
|
||
|
||
| 用户说 | 下一步 |
|
||
|---|---|
|
||
| “监听新的待我审批任务” / “有审批任务创建时通知我” | `dws event consume user_oa_approval_task_created --flatten -f ndjson` |
|
||
| “审批任务完成时通知我” | `dws event consume user_oa_approval_task_finished --flatten -f ndjson` |
|
||
| “审批任务被转交时通知我” | `dws event consume user_oa_approval_task_redirected --flatten -f ndjson` |
|
||
| “有审批单发起时通知我” | `dws event consume user_oa_approval_instance_started --flatten -f ndjson` |
|
||
| “有审批抄送给我时通知我” | `dws event consume user_oa_approval_instance_cc --flatten -f ndjson` |
|
||
| “有审批单终止时通知我” | `dws event consume user_oa_approval_instance_terminated --flatten -f ndjson` |
|
||
| “监听我发起的审批何时完成” / “审批实例完成时通知我” | `dws event consume user_oa_approval_instance_finished --flatten -f ndjson` |
|
||
| “同时监听全部已公开 OA 事件” | 一个 consume 放入七个 OA event key，不加目标或过滤参数 |
|
||
| “查看 OA 事件目录” | `dws event list --category oa` |
|
||
| “查看 OA 事件输出字段” | 对对应事件运行 `dws event schema <event_key> --flatten` |
|
||
|
||
三个审批任务事件分别表达任务已创建、已完成和已转交；四个审批实例事件分别表达实例已发起、到达抄送节点、已终止和已完成。`status` 和 `result` 保留服务端原值，不把当前样本值推断为完整枚举。
|
||
|
||
## Commands
|
||
|
||
查看稳定的扁平输出 schema：
|
||
|
||
```bash
|
||
dws event schema user_oa_approval_task_created --flatten
|
||
dws event schema user_oa_approval_task_finished --flatten
|
||
dws event schema user_oa_approval_task_redirected --flatten
|
||
dws event schema user_oa_approval_instance_started --flatten
|
||
dws event schema user_oa_approval_instance_cc --flatten
|
||
dws event schema user_oa_approval_instance_terminated --flatten
|
||
dws event schema user_oa_approval_instance_finished --flatten
|
||
```
|
||
|
||
单独监听一种事件：
|
||
|
||
```bash
|
||
dws event consume user_oa_approval_task_created --flatten -f ndjson
|
||
dws event consume user_oa_approval_task_finished --flatten -f ndjson
|
||
dws event consume user_oa_approval_task_redirected --flatten -f ndjson
|
||
dws event consume user_oa_approval_instance_started --flatten -f ndjson
|
||
dws event consume user_oa_approval_instance_cc --flatten -f ndjson
|
||
dws event consume user_oa_approval_instance_terminated --flatten -f ndjson
|
||
dws event consume user_oa_approval_instance_finished --flatten -f ndjson
|
||
```
|
||
|
||
同时监听七种事件：
|
||
|
||
```bash
|
||
dws event consume \
|
||
user_oa_approval_task_created \
|
||
user_oa_approval_task_finished \
|
||
user_oa_approval_task_redirected \
|
||
user_oa_approval_instance_started \
|
||
user_oa_approval_instance_cc \
|
||
user_oa_approval_instance_terminated \
|
||
user_oa_approval_instance_finished \
|
||
--flatten \
|
||
-f ndjson
|
||
```
|
||
|
||
多事件 consume 会为七个 event key 分别创建订阅和逻辑 consumer，并共享当前组织的 personal bus、远程连接、stdout 和生命周期。不要给 OA 命令加 `--query` 或 `--filter-json`；这两个 flag 只用于兼容的 IM 消息接收事件。
|
||
|
||
## Output contract
|
||
|
||
`--flatten` 模式的所有 OA 事件都包含以下顶层字段：
|
||
|
||
```json
|
||
{
|
||
"type": "user_oa_approval_task_created",
|
||
"event_id": "...",
|
||
"timestamp": 0,
|
||
"subscribe_id": "...",
|
||
"process_instance_id": "...",
|
||
"process_code": "...",
|
||
"title": "...",
|
||
"status": "RUNNING",
|
||
"create_time": 0,
|
||
"event_time": 0
|
||
}
|
||
```
|
||
|
||
- `type` 是当前 event key；`event_id` 可用于去重；`timestamp` 是 transport 事件发生时间；`subscribe_id` 标识对应的独立订阅。
|
||
- `process_instance_id` 是审批实例 ID，可传给 OA 审批命令的 `--instance-id`；`process_code` 是审批流程模板编码。
|
||
- `create_time`、`finish_time` 和 `event_time` 都是毫秒时间戳。`event_time` 是审批业务事件时间，`timestamp` 是 transport 事件时间。
|
||
- 七类事件的额外字段如下；具体事件始终以 `dws event schema <event_key> --flatten` 为准。
|
||
|
||
| 事件 | 额外顶层字段 |
|
||
|---|---|
|
||
| `user_oa_approval_task_created` | `task_id` |
|
||
| `user_oa_approval_task_finished` | `task_id`、`result`、`finish_time` |
|
||
| `user_oa_approval_task_redirected` | `task_id`、`result`、`finish_time` |
|
||
| `user_oa_approval_instance_started` | 无 |
|
||
| `user_oa_approval_instance_cc` | 无 |
|
||
| `user_oa_approval_instance_terminated` | `finish_time` |
|
||
| `user_oa_approval_instance_finished` | `result`、`finish_time` |
|
||
|
||
任务完成事件示例：
|
||
|
||
```json
|
||
{
|
||
"type": "user_oa_approval_task_finished",
|
||
"event_id": "...",
|
||
"timestamp": 0,
|
||
"subscribe_id": "...",
|
||
"process_instance_id": "...",
|
||
"process_code": "...",
|
||
"task_id": "...",
|
||
"title": "测试审批",
|
||
"status": "FINISHED",
|
||
"result": "agree",
|
||
"create_time": 0,
|
||
"finish_time": 0,
|
||
"event_time": 0
|
||
}
|
||
```
|
||
|
||
- `task_id` 是当前审批任务 ID，可传给接受任务 ID 的 OA 审批命令。
|
||
- `status` 和 `result` 是服务端字符串；不要只根据当前样本把 `RUNNING/FINISHED/TERMINATED` 或 `agree/redirect` 写成封闭枚举。
|
||
- payload 缺失、为空、缺少对应事件的稳定 ID 或无法解析时，consume 会在 stderr 记录 warning，并把原始 transport envelope 写到 stdout，保证事件不被静默丢弃。
|
||
- 不传 `--flatten` 时保持兼容 transport envelope，业务 payload 位于 `.data | fromjson`。需要联调完整原始协议时使用不带 `--flatten` 的 `-f raw` 或 `--debug-raw-events`。
|
||
|
||
## Lifecycle
|
||
|
||
- 单事件等待 `[event] ready event_key=<key> bus_pid=<pid> subscribe_id=<id>`。
|
||
- 七事件先保存七条 `[event] subscription event_key=<key> subscribe_id=<id>`，再等待 `[event] ready event_count=7 bus_pid=<pid>`。
|
||
- 临时验证使用 `--max-events 1` 或 `--duration 10m`；任务完成后优雅结束 consume，本次新建的订阅会自动取消。
|
||
- 外部停止已有订阅时先运行 `dws event stop <subscribe_id> --dry-run`，确认后再加 `--yes`。不要 `kill -9`，否则会跳过自动退订。
|