文档:完善泽源后端协作基线
This commit is contained in:
@@ -1 +1,160 @@
|
||||
# 01_老板 AI 秘书与 AI 草稿
|
||||
|
||||
## 1. 模块目标
|
||||
|
||||
老板 AI 秘书负责接收老板在飞书机器人私聊或平台输入的一句话,判断意图,并整理成可人工确认的草稿。第一版 AI 只生成草稿或回答,不直接创建事项、不直接创建提醒、不直接发送通知。
|
||||
|
||||
## 2. 第一版做什么
|
||||
|
||||
1. 支持老板在平台输入文本。
|
||||
2. 支持老板通过飞书机器人私聊输入文本。
|
||||
3. 判断意图类型:`task`、`reminder`、`qa`、`realtime_qa`、`note`、`unknown`。
|
||||
4. 对 `task` 生成事项草稿。
|
||||
5. 对 `reminder` 生成提醒草稿。
|
||||
6. 对 `qa` 直接用大白话回答,不生成草稿。
|
||||
7. 对 `realtime_qa` 提示第一版暂不支持正式实时查询,不创建草稿、不通知、不做交易判断。
|
||||
8. 对 `unknown` 追问关键缺失信息,最多 3 个补充项。
|
||||
9. 支持老板确认、补充/重说、取消草稿。
|
||||
10. 支持补充/重说 30 分钟上下文,超时后按新输入处理。
|
||||
11. 支持复杂事项转程经理确认。
|
||||
12. AI 调用时加载公司背景摘要、老板大白话风格和第一版业务规则版本。
|
||||
|
||||
## 3. 第一版不做
|
||||
|
||||
1. 不做老板独立 App。
|
||||
2. 不做语音、图片、文件上传或多模态输入。
|
||||
3. 不做员工通用 AI 工作台。
|
||||
4. 不让 AI 自动替代程经理拆复杂任务。
|
||||
5. 不让 AI 未经确认直接通知别人。
|
||||
6. 不做实时天气、新闻、股价、行情查询的正式能力。
|
||||
7. 不把老板解释中的游戏化表达写进事项标题、接收人、时间、反馈要求等结构化字段。
|
||||
|
||||
## 4. 核心流程
|
||||
|
||||
平台入口:
|
||||
|
||||
```text
|
||||
老板输入一句话
|
||||
-> POST /api/ai-drafts/parse
|
||||
-> 后端加载 prompt_contexts
|
||||
-> 调用 ai_client
|
||||
-> 校验模型 JSON
|
||||
-> 写入 model_call_logs
|
||||
-> 生成 ai_drafts
|
||||
-> 前端展示草稿
|
||||
```
|
||||
|
||||
飞书机器人入口:
|
||||
|
||||
```text
|
||||
老板私聊机器人
|
||||
-> 飞书事件回调
|
||||
-> 后端验签
|
||||
-> 匹配平台用户
|
||||
-> 校验 boss 角色
|
||||
-> 检查 bot_contexts 是否等待补充
|
||||
-> 调用 AI 生成或重写草稿
|
||||
-> 发送飞书确认卡片
|
||||
-> 写入 feishu_events、ai_drafts、operation_logs
|
||||
```
|
||||
|
||||
非老板私聊机器人:
|
||||
|
||||
```text
|
||||
收到机器人私聊
|
||||
-> 匹配用户
|
||||
-> 发现不是 boss
|
||||
-> 不调用 AI
|
||||
-> 不生成草稿
|
||||
-> 回复进入平台处理
|
||||
-> 写入未授权访问失败记录
|
||||
```
|
||||
|
||||
## 5. 数据对象
|
||||
|
||||
本模块主要使用:
|
||||
|
||||
1. `users`
|
||||
2. `person_mappings`
|
||||
3. `bot_contexts`
|
||||
4. `prompt_contexts`
|
||||
5. `ai_drafts`
|
||||
6. `model_call_logs`
|
||||
7. `feishu_events`
|
||||
8. `failure_records`
|
||||
9. `operation_logs`
|
||||
|
||||
字段以 `docs/contracts/数据对象约定.md` 为准。
|
||||
|
||||
## 6. 接口需求
|
||||
|
||||
主要接口:
|
||||
|
||||
1. `POST /api/ai-drafts/parse`
|
||||
2. `GET /api/ai-drafts`
|
||||
3. `GET /api/ai-drafts/{id}`
|
||||
4. `PATCH /api/ai-drafts/{id}`
|
||||
5. `POST /api/ai-drafts/{id}/confirm`
|
||||
6. `POST /api/ai-drafts/{id}/cancel`
|
||||
7. `POST /api/ai-drafts/{id}/convert`
|
||||
8. `POST /api/ai-drafts/{id}/follow-up`
|
||||
9. `POST /api/feishu/events`
|
||||
10. `POST /api/feishu/card-callback`
|
||||
|
||||
接口格式以 `docs/contracts/API接口约定.md` 为准。
|
||||
|
||||
## 7. 权限规则
|
||||
|
||||
1. 飞书机器人私聊入口第一版只允许老板使用。
|
||||
2. 非老板私聊机器人时,不调用模型、不生成草稿,只记录未授权访问。
|
||||
3. 老板可以确认、补充/重说、取消自己发起的草稿。
|
||||
4. 程经理只能确认转给自己的复杂事项草稿。
|
||||
5. 管理员 / AI 团队只能协助排查,不代替老板或程经理做业务确认。
|
||||
|
||||
## 8. 状态流转
|
||||
|
||||
草稿状态以 `docs/contracts/状态流转约定.md` 为准。核心约束:
|
||||
|
||||
1. `pending_confirmation` 只能等待确认、取消、补充或转程经理。
|
||||
2. 未确认草稿不得创建事项、提醒或通知。
|
||||
3. `parse_failed` 不得继续转换。
|
||||
4. `converted` 草稿不得重复转换。
|
||||
5. 补充/重说会生成新草稿,并通过 `parent_draft_id` 指向上一版草稿。
|
||||
|
||||
## 9. 失败和日志
|
||||
|
||||
必须记录:
|
||||
|
||||
1. 原始输入和 AI 输出摘要。
|
||||
2. 模型调用使用的背景摘要版本、老板风格版本和业务规则版本。
|
||||
3. AI JSON 解析失败。
|
||||
4. 缺少人员映射。
|
||||
5. 非老板机器人访问。
|
||||
6. 补充/重说上下文过期。
|
||||
7. 人工确认、修改、取消、转程经理确认。
|
||||
|
||||
不得记录:
|
||||
|
||||
1. API Key。
|
||||
2. 飞书 token。
|
||||
3. 完整手机号。
|
||||
4. 完整邮箱。
|
||||
5. 飞书 App Secret。
|
||||
|
||||
## 10. 给 AI 的测试样例
|
||||
|
||||
1. 老板输入“明天上午提醒东东给我订会议室”,应生成 `reminder` 草稿,不直接创建提醒。
|
||||
2. 老板输入“让剑楠下周给我看一下期货策略风险”,应生成 `task` 草稿,并倾向 `manager_confirm`。
|
||||
3. 老板输入“今天杭州天气怎么样”,应识别为 `realtime_qa`,不生成事项或提醒。
|
||||
4. 普通员工私聊机器人,应返回未开放提示,并写入未授权访问记录。
|
||||
5. 老板点击补充/重说后 30 分钟内再发消息,应关联上一版草稿。
|
||||
6. AI 输出 JSON 缺少 `draft_type` 时,应写入解析失败,不创建草稿闭环对象。
|
||||
|
||||
## 11. Review 重点
|
||||
|
||||
1. 是否严格保证 AI 只生成草稿。
|
||||
2. 是否所有关键动作都需要人工确认。
|
||||
3. 是否避免将游戏化表达写入结构化字段。
|
||||
4. 是否记录模型版本和 prompt_contexts 版本。
|
||||
5. 是否对非老板机器人访问做了后端权限校验。
|
||||
6. 是否对模型 JSON 做了结构校验和失败记录。
|
||||
|
||||
@@ -1 +1,131 @@
|
||||
# 02_事项任务
|
||||
|
||||
## 1. 模块目标
|
||||
|
||||
事项任务模块承接老板 AI 秘书草稿、程经理确认和手动创建事项,负责通知接收人、记录反馈、展示状态和沉淀失败原因。第一版只做轻量事项闭环,不做完整项目管理。
|
||||
|
||||
## 2. 第一版做什么
|
||||
|
||||
1. 事项可以来自 AI 草稿确认。
|
||||
2. 事项可以由程经理确认复杂草稿后生成。
|
||||
3. 事项可以由老板或程经理手动创建。
|
||||
4. 普通员工第一版不默认给别人创建事项。
|
||||
5. 事项必须有发起人、接收人、事项内容、反馈要求和状态。
|
||||
6. 事项生成前必须经过人工确认。
|
||||
7. 事项生成后可以创建飞书通知。
|
||||
8. 接收人可以反馈:已收到、处理中、已完成、有问题。
|
||||
9. 有问题反馈必须填写一句原因。
|
||||
10. 发起人、程经理或有权限人员可以查看处理进度。
|
||||
11. 通知失败或无人反馈的事项需要可见,但不单独做看板。
|
||||
|
||||
## 3. 第一版不做
|
||||
|
||||
1. 不做复杂项目管理系统。
|
||||
2. 不做多级子任务。
|
||||
3. 不做复杂审批流。
|
||||
4. 不做绩效排名。
|
||||
5. 不做任务依赖和甘特图。
|
||||
6. 不做项目级看板。
|
||||
7. 不做独立反馈看板。
|
||||
8. 不从 AI 工作台结果生成事项。
|
||||
|
||||
## 4. 核心流程
|
||||
|
||||
简单事项:
|
||||
|
||||
```text
|
||||
AI 草稿或手动输入
|
||||
-> 人工确认
|
||||
-> 创建 tasks
|
||||
-> 创建 notifications
|
||||
-> 飞书通知接收人
|
||||
-> 接收人反馈
|
||||
-> 更新事项状态
|
||||
-> 写入 operation_logs
|
||||
```
|
||||
|
||||
复杂事项:
|
||||
|
||||
```text
|
||||
老板确认转程经理
|
||||
-> 创建 pending_manager_confirm 事项或待确认记录
|
||||
-> 给程经理发飞书提醒
|
||||
-> 程经理进入平台确认、修改和分发
|
||||
-> 通知接收人
|
||||
-> 接收反馈
|
||||
```
|
||||
|
||||
## 5. 数据对象
|
||||
|
||||
本模块主要使用:
|
||||
|
||||
1. `ai_drafts`
|
||||
2. `tasks`
|
||||
3. `notifications`
|
||||
4. `feedbacks`
|
||||
5. `failure_records`
|
||||
6. `operation_logs`
|
||||
|
||||
字段以 `docs/contracts/数据对象约定.md` 为准。
|
||||
|
||||
## 6. 接口需求
|
||||
|
||||
主要接口:
|
||||
|
||||
1. `GET /api/tasks`
|
||||
2. `POST /api/tasks`
|
||||
3. `GET /api/tasks/{id}`
|
||||
4. `PATCH /api/tasks/{id}`
|
||||
5. `POST /api/tasks/{id}/manager-confirm`
|
||||
6. `POST /api/tasks/{id}/cancel`
|
||||
7. `POST /api/tasks/{id}/notify`
|
||||
8. `POST /api/tasks/{id}/feedback`
|
||||
|
||||
接口格式以 `docs/contracts/API接口约定.md` 为准。
|
||||
|
||||
## 7. 权限规则
|
||||
|
||||
1. 老板可以创建事项。
|
||||
2. 程经理可以创建和分发事项。
|
||||
3. 普通员工不能给别人创建事项。
|
||||
4. 接收人只能反馈自己相关事项。
|
||||
5. 程经理只能确认待自己处理的复杂事项。
|
||||
6. 管理员 / AI 团队可以为排查查看必要记录,但不处理业务分歧。
|
||||
|
||||
## 8. 状态流转
|
||||
|
||||
事项状态以 `docs/contracts/状态流转约定.md` 为准。核心约束:
|
||||
|
||||
1. 未确认事项不得通知接收人。
|
||||
2. `pending_manager_confirm` 必须由程经理确认后才能进入通知流程。
|
||||
3. 通知失败进入 `notify_failed`,不得假装已通知。
|
||||
4. 已取消事项不能反馈、通知或补发。
|
||||
5. 有问题反馈会将事项标记为 `problem`,并记录原因。
|
||||
|
||||
## 9. 失败和日志
|
||||
|
||||
必须记录:
|
||||
|
||||
1. 事项创建来源:AI 草稿、手动创建或程经理确认。
|
||||
2. 创建、修改、取消、通知、补发、反馈操作。
|
||||
3. 权限拒绝。
|
||||
4. 通知失败。
|
||||
5. 有问题反馈原因。
|
||||
6. 人员映射缺失或接收人不明确。
|
||||
|
||||
## 10. 给 AI 的测试样例
|
||||
|
||||
1. 普通员工请求给同事创建事项,应返回权限错误。
|
||||
2. 老板确认简单事项后,事项进入待通知或已通知状态。
|
||||
3. 研究类事项应进入程经理确认路径。
|
||||
4. 接收人反馈“有问题”但不填原因,应返回校验错误。
|
||||
5. 通知失败时,事项状态不得变成已通知。
|
||||
6. 已取消事项不得再次通知。
|
||||
|
||||
## 11. Review 重点
|
||||
|
||||
1. 后端是否做了权限校验,而不是只靠前端隐藏按钮。
|
||||
2. 状态流转是否只走允许路径。
|
||||
3. 通知失败是否留下失败记录。
|
||||
4. 有问题反馈是否强制原因。
|
||||
5. 是否避免把复杂项目管理能力混入第一版。
|
||||
|
||||
@@ -1 +1,146 @@
|
||||
# 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 角色
|
||||
-> 调用 AI 草稿服务
|
||||
-> 发送确认卡片
|
||||
```
|
||||
|
||||
卡片回调:
|
||||
|
||||
```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. `failure_records`
|
||||
9. `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. 回调处理失败必须标记 `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. 失败是否可复盘。
|
||||
|
||||
@@ -1 +1,139 @@
|
||||
# 04_定时提醒
|
||||
|
||||
## 1. 模块目标
|
||||
|
||||
定时提醒模块负责创建一次性或固定周期提醒,到点生成通知、发送飞书消息、按需接收反馈,并记录触发结果和失败原因。
|
||||
|
||||
## 2. 第一版做什么
|
||||
|
||||
1. 支持一次性提醒。
|
||||
2. 支持每天、每周、每月固定周期提醒。
|
||||
3. 支持提醒来自手动创建。
|
||||
4. 支持提醒来自老板 AI 草稿确认。
|
||||
5. 支持提醒与事项关联。
|
||||
6. 到点后通知接收人。
|
||||
7. 通知成功或失败都要记录。
|
||||
8. 支持查看自己相关提醒状态。
|
||||
9. 创建人、发起人、管理员可以修改、暂停或取消提醒。
|
||||
10. 提醒可以设置是否需要接收人反馈。
|
||||
|
||||
## 3. 第一版不做
|
||||
|
||||
1. 不做 cron 表达式。
|
||||
2. 不做自定义复杂周期规则。
|
||||
3. 不做日历系统。
|
||||
4. 不做复杂自动化流程。
|
||||
5. 不自动操作外部系统。
|
||||
6. 不从 AI 工作台结果生成提醒。
|
||||
|
||||
## 4. 核心流程
|
||||
|
||||
创建提醒:
|
||||
|
||||
```text
|
||||
手动创建或草稿确认
|
||||
-> 后端校验创建权限
|
||||
-> 写入 reminders
|
||||
-> 计算 next_trigger_at
|
||||
-> 写 operation_logs
|
||||
```
|
||||
|
||||
触发提醒:
|
||||
|
||||
```text
|
||||
scheduler 扫描 due reminders
|
||||
-> 校验提醒状态
|
||||
-> 生成幂等键
|
||||
-> 创建 notifications
|
||||
-> 调用飞书发送
|
||||
-> 更新 last_triggered_at 和 next_trigger_at
|
||||
-> 成功或失败都写记录
|
||||
```
|
||||
|
||||
反馈:
|
||||
|
||||
```text
|
||||
接收人点击卡片反馈
|
||||
-> 飞书回调验签
|
||||
-> 校验接收人权限
|
||||
-> 写 feedbacks
|
||||
-> 保留 reminders 调度状态,反馈结果通过 feedbacks 展示
|
||||
```
|
||||
|
||||
## 5. 数据对象
|
||||
|
||||
本模块主要使用:
|
||||
|
||||
1. `ai_drafts`
|
||||
2. `tasks`
|
||||
3. `reminders`
|
||||
4. `notifications`
|
||||
5. `feedbacks`
|
||||
6. `failure_records`
|
||||
7. `operation_logs`
|
||||
|
||||
字段以 `docs/contracts/数据对象约定.md` 为准。
|
||||
|
||||
## 6. 接口需求
|
||||
|
||||
主要接口:
|
||||
|
||||
1. `GET /api/reminders`
|
||||
2. `POST /api/reminders`
|
||||
3. `GET /api/reminders/{id}`
|
||||
4. `PATCH /api/reminders/{id}`
|
||||
5. `POST /api/reminders/{id}/pause`
|
||||
6. `POST /api/reminders/{id}/resume`
|
||||
7. `POST /api/reminders/{id}/cancel`
|
||||
8. `POST /api/reminders/{id}/notify`
|
||||
9. `POST /api/reminders/{id}/feedback`
|
||||
|
||||
接口格式以 `docs/contracts/API接口约定.md` 为准。
|
||||
|
||||
## 7. 权限规则
|
||||
|
||||
1. 所有人可以创建自己的提醒。
|
||||
2. 老板和程经理可以给别人创建提醒。
|
||||
3. 普通员工不能给同事创建提醒。
|
||||
4. 创建人、发起人、管理员可以修改、暂停或取消提醒。
|
||||
5. 接收人只能反馈自己相关提醒。
|
||||
|
||||
## 8. 状态流转
|
||||
|
||||
提醒状态以 `docs/contracts/状态流转约定.md` 为准。核心约束:
|
||||
|
||||
1. `active` 提醒才允许 scheduler 触发。
|
||||
2. `paused` 不触发,但可以恢复。
|
||||
3. `cancelled` 不触发、不可恢复。
|
||||
4. `trigger_failed` 必须写失败记录。
|
||||
5. 同一个提醒同一触发时间同一接收人只能生成一条有效通知。
|
||||
6. 一次性提醒成功触发后进入 `triggered`;周期提醒成功触发后保持 `active` 并计算下一次 `next_trigger_at`。
|
||||
7. 提醒反馈不改变提醒调度状态,反馈结果通过 `feedbacks` 展示。
|
||||
|
||||
## 9. 失败和日志
|
||||
|
||||
必须记录:
|
||||
|
||||
1. 提醒创建、修改、暂停、恢复、取消。
|
||||
2. scheduler 触发成功或失败。
|
||||
3. 飞书通知发送成功或失败。
|
||||
4. 幂等冲突或重复触发跳过。
|
||||
5. 权限拒绝。
|
||||
6. 有问题反馈原因。
|
||||
|
||||
## 10. 给 AI 的测试样例
|
||||
|
||||
1. 普通员工给同事创建提醒,应返回权限错误。
|
||||
2. `paused` 提醒到点不应触发通知。
|
||||
3. 同一提醒同一触发时间重复扫描,不应重复创建通知。
|
||||
4. 每周提醒触发后,应计算下一次提醒时间。
|
||||
5. 通知失败应写失败记录。
|
||||
6. 自己提醒自己默认不需要反馈,老板或程经理给别人提醒默认需要反馈。
|
||||
|
||||
## 11. Review 重点
|
||||
|
||||
1. 是否防止重复触发。
|
||||
2. 是否限制普通员工给别人创建提醒。
|
||||
3. 是否不支持 cron 等第一版不做内容。
|
||||
4. scheduler 是否走 service 层而不是直接改业务表。
|
||||
5. 失败是否可复盘。
|
||||
|
||||
@@ -1 +1,135 @@
|
||||
# 05_权限日志失败记录
|
||||
|
||||
## 1. 模块目标
|
||||
|
||||
权限、日志和失败记录模块负责保证第一版闭环可控、可追溯、可复盘。权限必须在后端校验,关键操作必须写日志,AI、飞书、调度和业务失败必须形成失败记录。
|
||||
|
||||
## 2. 第一版做什么
|
||||
|
||||
1. 定义老板、程经理、普通员工、管理员 / AI 团队四类角色。
|
||||
2. 控制事项、提醒、草稿、反馈、失败记录的可见范围和操作范围。
|
||||
3. 记录关键操作日志。
|
||||
4. 记录 AI 解析失败、人员映射缺失、飞书通知失败、回调失败、定时触发失败、用户反馈有问题等失败。
|
||||
5. 支持管理员 / AI 团队查看和处理失败记录。
|
||||
6. 对敏感信息做日志边界约束。
|
||||
|
||||
## 3. 第一版不做
|
||||
|
||||
1. 不做复杂组织架构。
|
||||
2. 不做细粒度多级权限。
|
||||
3. 不做复杂审批流。
|
||||
4. 不做独立失败看板或复杂 BI。
|
||||
5. 不把飞书身份直接等同于业务权限。
|
||||
6. 不把密钥、token、完整手机号、完整邮箱写入普通日志。
|
||||
|
||||
## 4. 核心流程
|
||||
|
||||
权限校验:
|
||||
|
||||
```text
|
||||
请求进入 DRF view
|
||||
-> permission class 做入口校验
|
||||
-> serializer 做参数校验
|
||||
-> service 做业务权限和状态校验
|
||||
-> 通过后执行业务动作
|
||||
```
|
||||
|
||||
失败记录:
|
||||
|
||||
```text
|
||||
业务或外部调用失败
|
||||
-> 写 failure_records
|
||||
-> 保留关联对象和失败类型
|
||||
-> 管理员 / AI 团队处理
|
||||
-> 填写处理结果
|
||||
-> 写 operation_logs
|
||||
```
|
||||
|
||||
操作日志:
|
||||
|
||||
```text
|
||||
关键动作发生
|
||||
-> 记录 actor、action、target_type、target_id
|
||||
-> 记录操作渠道和结果摘要
|
||||
-> 避免记录敏感明文
|
||||
```
|
||||
|
||||
## 5. 数据对象
|
||||
|
||||
本模块主要使用:
|
||||
|
||||
1. `users`
|
||||
2. `failure_records`
|
||||
3. `operation_logs`
|
||||
4. `model_call_logs`
|
||||
5. `feishu_events`
|
||||
|
||||
字段以 `docs/contracts/数据对象约定.md` 为准。
|
||||
|
||||
## 6. 接口需求
|
||||
|
||||
主要接口:
|
||||
|
||||
1. `GET /api/users/me`
|
||||
2. `GET /api/failure-records`
|
||||
3. `GET /api/failure-records/{id}`
|
||||
4. `PATCH /api/failure-records/{id}`
|
||||
5. `POST /api/failure-records/{id}/resolve`
|
||||
6. `GET /api/notifications`
|
||||
7. `GET /api/notifications/{id}`
|
||||
8. `GET /api/feedbacks`
|
||||
|
||||
接口格式以 `docs/contracts/API接口约定.md` 为准。
|
||||
|
||||
## 7. 权限规则
|
||||
|
||||
1. 普通员工只能看自己作为接收人、创建人或反馈人的记录。
|
||||
2. 老板能看自己发起、创建或接收的记录。
|
||||
3. 程经理能看自己发起、负责、待确认,以及第一批试用管理范围内的记录。
|
||||
4. 管理员 / AI 团队能看失败记录、通知记录、人员映射和必要操作日志。
|
||||
5. 普通员工不能给别人创建事项或提醒。
|
||||
6. 反馈人必须是事项或提醒接收人。
|
||||
7. 飞书登录用户必须匹配到启用状态的平台用户后才能进入平台。
|
||||
|
||||
## 8. 状态流转
|
||||
|
||||
失败记录状态以 `docs/contracts/状态流转约定.md` 为准。核心约束:
|
||||
|
||||
1. 新失败进入 `pending`。
|
||||
2. 处理中进入 `processing`。
|
||||
3. 填写处理结果后进入 `resolved`。
|
||||
4. 确认不处理可进入 `cancelled`。
|
||||
5. 失败记录状态变化必须写操作日志。
|
||||
|
||||
## 9. 必须写日志的动作
|
||||
|
||||
1. 飞书登录成功或失败。
|
||||
2. 机器人收到老板消息。
|
||||
3. 非老板私聊机器人。
|
||||
4. AI 生成草稿、解析失败。
|
||||
5. 人工确认、修改、取消草稿。
|
||||
6. 老板点击补充/重说。
|
||||
7. 程经理确认复杂事项。
|
||||
8. 创建事项、创建提醒。
|
||||
9. 发送通知、补发通知、通知失败。
|
||||
10. 接收反馈,尤其是有问题反馈。
|
||||
11. 定时提醒触发成功或失败。
|
||||
12. 失败记录处理。
|
||||
13. 背景摘要或老板风格提示词版本启用。
|
||||
|
||||
## 10. 给 AI 的测试样例
|
||||
|
||||
1. 普通员工创建给别人的事项,应被拒绝并写权限失败日志。
|
||||
2. 普通员工创建给别人的提醒,应被拒绝。
|
||||
3. 非接收人提交反馈,应被拒绝。
|
||||
4. 管理员处理失败记录时,必须留下处理结果。
|
||||
5. 日志中不得包含完整手机号、完整邮箱、飞书 token 或密钥。
|
||||
6. 未匹配平台用户的飞书登录应失败并写失败记录。
|
||||
|
||||
## 11. Review 重点
|
||||
|
||||
1. 后端权限是否完整。
|
||||
2. 状态流转是否可追踪。
|
||||
3. 失败记录是否包含关联对象、失败类型和处理结果。
|
||||
4. 日志是否记录操作人和渠道。
|
||||
5. 敏感信息是否被脱敏。
|
||||
|
||||
Reference in New Issue
Block a user