talesofzes
149 lines
4.3 KiB
Markdown
149 lines
4.3 KiB
Markdown
# 03_飞书通知与反馈
|
|
|
|
## 1. 模块目标
|
|
|
|
飞书模块负责平台登录身份、老板机器人私聊入口、个人消息通知、交互卡片确认和反馈回调。第一版飞书是闭环主入口之一，所有回调必须验签、幂等、可追溯。
|
|
|
|
## 2. 第一版做什么
|
|
|
|
1. 飞书扫码登录 / 身份登录。
|
|
2. 根据飞书身份匹配平台用户和角色。
|
|
3. 接收老板机器人私聊消息。
|
|
4. 非老板私聊机器人时提示进入平台并记录未授权访问。
|
|
5. 发送 AI 草稿确认卡片给老板。
|
|
6. 发送复杂事项待确认提醒给程经理，按钮只跳转平台。
|
|
7. 发送事项或提醒通知给接收人。
|
|
8. 接收卡片按钮回调。
|
|
9. 支持接收人反馈已收到、处理中、已完成、有问题。
|
|
10. 记录飞书事件、通知发送结果和回调处理结果。
|
|
|
|
## 3. 第一版不做
|
|
|
|
1. 不把机器人开放成程经理或普通员工通用派活入口。
|
|
2. 不让程经理在机器人里对话分发事项。
|
|
3. 不在飞书消息里展开敏感全文。
|
|
4. 不做飞书卡片内复杂字段编辑表单。
|
|
5. 不绕过平台角色权限。
|
|
|
|
## 4. 核心流程
|
|
|
|
飞书登录：
|
|
|
|
```text
|
|
用户点击飞书登录
|
|
-> 跳转飞书授权
|
|
-> 飞书回调 auth callback
|
|
-> 校验 state 和 code
|
|
-> 换取飞书身份
|
|
-> 匹配平台用户
|
|
-> 写入 feishu_auth_sessions
|
|
-> 建立平台登录态
|
|
```
|
|
|
|
机器人私聊：
|
|
|
|
```text
|
|
飞书推送消息事件
|
|
-> 验签
|
|
-> 记录 feishu_events
|
|
-> 匹配平台用户
|
|
-> 校验 boss 角色
|
|
-> 转发到 POST /api/secretary/handle-message
|
|
-> 根据 reply_type 发送确认卡片、追问或普通回复
|
|
```
|
|
|
|
卡片回调：
|
|
|
|
```text
|
|
飞书卡片按钮点击
|
|
-> 验签
|
|
-> 记录 feishu_events
|
|
-> 查找 notification / draft / task / reminder
|
|
-> 校验操作人权限
|
|
-> 执行业务动作
|
|
-> 写 operation_logs
|
|
-> 返回飞书处理结果
|
|
```
|
|
|
|
## 5. 数据对象
|
|
|
|
本模块主要使用：
|
|
|
|
1. `users`
|
|
2. `person_mappings`
|
|
3. `feishu_auth_sessions`
|
|
4. `feishu_events`
|
|
5. `notifications`
|
|
6. `feedbacks`
|
|
7. `bot_contexts`
|
|
8. `secretary_messages`
|
|
9. `failure_records`
|
|
10. `operation_logs`
|
|
|
|
字段以 `docs/contracts/数据对象约定.md` 为准。
|
|
|
|
## 6. 接口需求
|
|
|
|
主要接口：
|
|
|
|
1. `GET /api/auth/feishu/login`
|
|
2. `GET /api/auth/feishu/callback`
|
|
3. `POST /api/feishu/events`
|
|
4. `POST /api/feishu/bot/messages`
|
|
5. `POST /api/feishu/card-callback`
|
|
6. `POST /api/notifications/{id}/retry`
|
|
|
|
接口格式以 `docs/contracts/API接口约定.md` 为准。
|
|
|
|
## 7. 权限规则
|
|
|
|
1. 飞书身份只用于认证和操作人追溯，业务权限仍以平台角色为准。
|
|
2. 机器人私聊入口第一版只允许老板使用。
|
|
3. 老板只能确认、取消、补充自己发起的草稿。
|
|
4. 程经理待办提醒只能跳转平台确认。
|
|
5. 反馈人必须是事项或提醒接收人。
|
|
6. 管理员 / AI 团队可以处理系统失败和补发，但不能代替业务反馈。
|
|
|
|
## 8. 状态与幂等
|
|
|
|
状态以 `docs/contracts/状态流转约定.md` 为准。幂等约束：
|
|
|
|
1. 同一个飞书 `event_id` 只处理一次。
|
|
2. 同一个通知只允许一个有效发送结果。
|
|
3. 同一个卡片按钮重复点击不得重复创建事项、提醒或反馈。
|
|
4. 同一个机器人消息还必须按 `source + message_id` 在老板秘书入口二次幂等，不重复追加 `secretary_messages`。
|
|
5. 回调处理失败必须标记 `feishu_events.process_status = failed` 并写失败记录。
|
|
|
|
## 9. 失败和日志
|
|
|
|
必须记录：
|
|
|
|
1. 飞书登录成功或失败。
|
|
2. 飞书事件原始 payload。
|
|
3. 机器人消息处理结果。
|
|
4. 卡片回调处理结果。
|
|
5. 通知发送成功或失败。
|
|
6. 验签失败。
|
|
7. 找不到关联对象。
|
|
8. 操作人无权操作。
|
|
9. 有问题反馈缺少原因。
|
|
|
|
普通日志不得打印飞书 token、App Secret、完整手机号或完整邮箱。
|
|
|
|
## 10. 给 AI 的测试样例
|
|
|
|
1. 验签失败的回调应返回拒绝并写失败记录。
|
|
2. 同一 `event_id` 重放应幂等，不重复创建反馈。
|
|
3. 非接收人点击反馈按钮应返回权限错误。
|
|
4. 老板点击取消草稿后，草稿不能再转换。
|
|
5. 非老板私聊机器人不应调用 AI。
|
|
6. 飞书通知失败时，应写 `failure_records` 并保留通知失败状态。
|
|
|
|
## 11. Review 重点
|
|
|
|
1. 回调是否验签。
|
|
2. 回调是否幂等。
|
|
3. 飞书身份是否没有直接绕过平台权限。
|
|
4. 通知内容是否只发摘要和链接。
|
|
5. 失败是否可复盘。
|