AI-Secretary/docs/specs/03_飞书通知与反馈.md

03_飞书通知与反馈

1. 模块目标

飞书模块负责平台登录身份、老板机器人私聊入口、个人消息通知、交互卡片确认和反馈回调。第一版飞书是闭环主入口之一，所有回调必须验签、幂等、可追溯。

2. 第一版做什么

1. 飞书扫码登录 / 身份登录。
2. 根据飞书身份匹配平台用户和角色。
3. 接收老板机器人私聊消息。
4. 非老板私聊机器人时提示进入平台并记录未授权访问。
5. 发送 AI 草稿确认卡片给老板。
6. 发送复杂事项待确认提醒给程经理，按钮只跳转平台。
7. 发送事项或提醒通知给接收人。
8. 接收卡片按钮回调。
9. 支持接收人反馈已收到、处理中、已完成、有问题。
10. 记录飞书事件、通知发送结果和回调处理结果。
11. 旧卡片、失效卡片和重复点击必须幂等处理。
12. 平台内“有问题反馈”页需要在飞书手机端最小可用。

3. 第一版不做

1. 不把机器人开放成程经理或普通员工通用派活入口。
2. 不让程经理在机器人里对话分发事项。
3. 不在飞书消息里展开敏感全文。
4. 不做飞书卡片内复杂字段编辑表单。
5. 不绕过平台角色权限。

4. 核心流程

飞书登录：

用户点击飞书登录
-> 跳转飞书授权
-> 飞书回调 auth callback
-> 校验 state 和 code
-> 换取飞书身份
-> 匹配平台用户
-> 写入 feishu_auth_sessions
-> 建立平台登录态

机器人私聊：

飞书推送消息事件
-> 验签
-> 记录 feishu_events
-> 匹配平台用户
-> 校验 boss 角色
-> 转发到 POST /api/secretary/handle-message
-> 根据 reply_type 发送确认卡片、追问或普通回复

卡片回调：

飞书卡片按钮点击
-> 验签
-> 记录 feishu_events
-> 查找 notification / draft / task / reminder
-> 校验 event_id 或 idempotency_key
-> 校验操作人权限
-> 校验通知、草稿和卡片仍有效
-> 执行业务动作
-> 写 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 为准；权限、安全、日志脱敏、验签和幂等以 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 只处理一次；没有稳定 event_id 时必须使用 idempotency_key。
2. 同一个通知只允许一个有效发送结果。
3. 同一个卡片按钮重复点击不得重复创建事项、提醒或反馈。
4. 草稿确认类卡片必须匹配 ai_drafts.active_card_notification_id。
5. 旧卡片、失效卡片、已替代草稿和已过期通知的回调只写入 feishu_events，标记 ignored，不得写业务对象。
6. 同一个机器人消息还必须按 source + message_id 在老板秘书入口二次幂等，不重复追加 secretary_messages。
7. 回调处理失败必须标记 feishu_events.process_status = failed 并写失败记录。

9. 失败和日志

必须记录：

1. 飞书登录成功或失败。
2. 飞书事件原始 payload。
3. 机器人消息处理结果。
4. 卡片回调处理结果。
5. 通知发送成功或失败。
6. 验签失败。
7. 找不到关联对象。
8. 操作人无权操作。
9. 有问题反馈缺少原因。

普通日志不得打印飞书 token、App Secret、OAuth code/state、一次性操作 token、回调验签密钥、完整手机号或完整邮箱。

10. 平台内反馈页

飞书卡片无法直接完成“有问题”原因填写时，允许跳转平台内反馈页。第一版不做完整手机网页适配，但该页在飞书手机端必须最小可用：

1. 能通过飞书登录态或一次性反馈 token 识别反馈人。
2. 一次性反馈 token 只保存 hash，不保存明文。
3. 只展示事项或提醒摘要、反馈状态选择和问题原因输入。
4. 操作人不是接收人、链接过期、通知失效或卡片失效时，只提示不可反馈并记录事件或失败，不写业务对象。
5. 提交成功后写入 feedbacks 并按状态流转更新事项或提醒。

11. 给 AI 的测试样例

1. 验签失败的回调应返回拒绝并写失败记录。
2. 同一 event_id 重放应幂等，不重复创建反馈。
3. 非接收人点击反馈按钮应返回权限错误。
4. 老板点击取消草稿后，草稿不能再转换。
5. 非老板私聊机器人不应调用 AI。
6. 飞书通知失败时，应写 failure_records 并保留通知失败状态。
7. 没有稳定 event_id 的卡片回调应使用 idempotency_key 幂等。
8. 旧确认卡片或已失效通知的回调只记录 feishu_events，不得创建事项、提醒或反馈。
9. 飞书手机端平台反馈页必须能提交“有问题”原因，并拒绝过期 token。

12. Review 重点

1. 回调是否验签。
2. 回调是否使用 event_id 或 idempotency_key 幂等。
3. 飞书身份是否没有直接绕过平台权限。
4. 通知内容是否只发摘要和链接。
5. 失败是否可复盘。
6. 旧卡片、失效卡片是否不会继续写业务对象。